Skip to content

17. Servicios web

Nota: por «servicio web» entendemos aquí cualquier aplicación web que entrega datos sin formato que consume un cliente (en los ejemplos que siguen, un script de consola). No nos ocupamos de ninguna tecnología en particular (como REST (REpresentational State Transfer) o SOAP (Simple Object Access Protocol), por ejemplo), que entregan datos en un formato bien definido: JSON, casi siempre, en REST, y XML en SOAP. Cada una de estas tecnologías describe con precisión cómo debe consultar el cliente al servidor y el formato que debe tener la respuesta del servidor. En este curso seremos mucho más flexibles en cuanto a la naturaleza de la solicitud del cliente y de la respuesta del servidor. Sin embargo, los scripts escritos y las herramientas utilizadas son similares a los de la tecnología REST.

17.1. Introducción

Dado que los programas PHP pueden ser ejecutados por un servidor web, un programa de este tipo se convierte en un programa servidor capaz de atender a varios clientes. Desde el punto de vista del cliente, llamar a un servicio web equivale a solicitar la URL de ese servicio. El cliente puede estar escrito en cualquier lenguaje, incluido PHP. También necesitamos saber cómo «comunicarnos» con un servicio web, es decir, comprender el protocolo de comunicación HTTP entre un servidor web y sus clientes. Ese fue el objetivo del capítulo anterior, que nos introdujo en una parte de este protocolo.

Image

En su forma más simple, los intercambios cliente/servidor se desarrollan de la siguiente manera:

  • el cliente abre una conexión con el puerto 80 del servidor web;
  • el cliente envía una solicitud de un documento;
  • el servidor web envía el documento solicitado y cierra la conexión;
  • el cliente cierra entonces la conexión.

El documento puede ser de varios tipos: texto en formato HTML, una imagen, un video, etc. Puede ser un documento existente (documento estático) o un documento generado sobre la marcha por un script (documento dinámico). En este último caso se habla de programación web. El script de generación dinámica de documentos puede estar escrito en diversos lenguajes: PHP, Python, Java, JavaScript, C#, Ruby…

A continuación, utilizaremos scripts PHP para generar dinámicamente documentos de texto.

Image

  • En [1], el cliente establece una conexión con el servidor, solicita un script PHP y puede enviar o no parámetros a ese script;
  • En [2], el servidor web hace que el intérprete de PHP ejecute el script PHP. El script genera un documento que se envía al cliente [3];
  • El servidor cierra la conexión. El cliente hace lo mismo.

El servidor web puede atender a varios clientes al mismo tiempo.

Con [Laragon], el servidor web es [Apache], un servidor de código abierto de la Apache Foundation (https://httpd.apache.org). En las aplicaciones siguientes, [Laragon] debe estar iniciado y sus servicios en marcha (el botón [Start All] de la ventana de [Laragon]). Esto inicia el servidor web [Apache] y el SGBD [MySQL]. El servidor [Apache] de [Laragon] ejecuta los scripts PHP mediante el módulo [mod_php] de la versión de PHP seleccionada en [Laragon], en este caso PHP 8.5.

Hasta ahora hemos escrito scripts PHP que se ejecutan en un contexto de consola:

Image

El usuario utiliza la consola (el terminal de VS Code) para solicitar la ejecución de un script PHP y recibir sus resultados.

En las aplicaciones cliente/servidor que se describen a continuación:

  • el script cliente se ejecuta en un contexto de consola;
  • el script servidor se ejecuta en un contexto web.

Image

El script PHP del servidor no puede estar ubicado en cualquier parte del sistema de archivos. Esto se debe a que el servidor web busca los documentos estáticos y dinámicos que se le pide servir en las ubicaciones indicadas por la configuración. La configuración predeterminada de [Laragon] hace que los documentos se busquen en la carpeta [<laragon>/www], donde [<laragon>] es la carpeta de instalación de [Laragon] (por ejemplo, [C:\laragon]). Así, si un cliente web solicita el documento D mediante la URL o ruta [http://localhost/D], el servidor web servirá el documento D desde la ruta [<laragon>/www/D].

La carpeta de código de este curso, [php8-oct-2026], se colocó en la carpeta [<laragon>/www] (véase el capítulo sobre la instalación). Los scripts de servidor de este capítulo están en la carpeta [php8-oct-2026/scripts-web]. Si un script de servidor se llama [S.php], se consultará al servidor web con la URL [http://localhost/php8-oct-2026/scripts-web/S.php]. Entonces se servirá el documento [<laragon>/www/php8-oct-2026/scripts-web/S.php].

Los scripts cliente se encuentran en la carpeta [php8-oct-2026/scripts-console/web-clients]. Esta es la estructura de las dos carpetas (cada carpeta numerada corresponde a un apartado de este capítulo):

php8-oct-2026
├── scripts-console
│   └── web-clients
│       ├── 02      date / time client
│       ├── 03      JSON client
│       ├── 04      server environment client
│       ├── 05      GET / POST clients
│       ├── 06      client with a session (examples 1 and 2)
│       └── 08      client with authentication
├── scripts-web
│   ├── 01          static and dynamic pages
│   ├── 02          date / time server
│   ├── 03          JSON server
│   ├── 04          server environment
│   ├── 05          GET / POST server
│   ├── 06          sessions - example 1
│   ├── 07          sessions - example 2
│   └── 08          authentication
└── vendor          libraries installed by Composer

En VS Code, abra la carpeta [php8-oct-2026] (menú [File / Open Folder]). Todos los archivos de scripts web y de scripts de consola quedan entonces accesibles en el explorador de VS Code, y la extensión [PHP Intelephense] analiza el código de ambos. No hay ningún «proyecto web» que crear: para el servidor [Apache], un script web es simplemente un archivo [.php] ubicado en la carpeta [<laragon>/www].

Los clientes HTTP utilizados en este capítulo son:

  • un navegador web (Chrome, Firefox, Edge, etc.);
  • la herramienta de línea de comandos [curl], disponible en Windows 11 (y en el terminal de [Laragon]). En un terminal [PowerShell], debe escribir [curl.exe] en lugar de [curl], porque en Windows PowerShell, [curl] es un alias del comando [Invoke-WebRequest], que no tiene las mismas opciones. En un terminal [Command Prompt] (cmd) o en el terminal de [Laragon], [curl] es suficiente;
  • scripts de consola PHP que utilizan la biblioteca [HttpClient] de Symfony.

Utilizaremos [curl] con algunas opciones:

opción
función
[-i]
muestra los encabezados de la respuesta HTTP antes del documento
[-v]
modo detallado: muestra también los encabezados HTTP enviados por [curl]
[-d name=value]
envía el parámetro mediante una solicitud POST
[--data-urlencode "name=value"]
igual que lo anterior, codificando el valor como URL
[-u login:password]
autenticación [Basic]
[-c file] / [-b file]
Guarda / devuelve las cookies recibidas del servidor

17.2. Escritura de una página estática

Nota: para el resto de este proceso, [Laragon] debe estar en ejecución.

Mostraremos cómo crear una página estática en HTML (HyperText Markup Language). En VS Code, creamos la carpeta [scripts-web/01] y luego, dentro de esa carpeta, el archivo [example-01.html]. En un archivo HTML vacío, VS Code ofrece una plantilla de página: basta con escribir [!] y luego presionar la tecla [Tab] (la función [Emmet] de VS Code). Completamos esta plantilla de la siguiente manera:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>PHP 8 by example</title>
    </head>
    <body>
        <div><b>This is an example of a static page</b></div>
    </body>
</html>
  • Línea 6: el título de la página;
  • línea 9: su contenido.

Ahora hagamos que el servidor [Apache] de [Laragon] muestre la página HTML. En un navegador, solicitamos la URL [http://localhost/php8-oct-2026/scripts-web/01/example-01.html]:

Image

  • En la parte superior, la pestaña muestra el título de la página y la barra de direcciones muestra la URL solicitada;
  • debajo, el contenido de la página.

La página mostrada es una página estática: puede recargarla en el navegador (F5) tantas veces como quiera y siempre se muestra el mismo contenido.

La mayoría de los navegadores permiten acceder a los datos intercambiados entre el cliente y el servidor, como se describió en el capítulo anterior: presione F12 para abrir las herramientas de desarrollo y luego seleccione la pestaña [Network] y recargue la página (F5). Al hacer clic en el documento cargado, puede ver el comando enviado al servidor, los encabezados de la solicitud del navegador, los encabezados de la respuesta del servidor y, por último, el documento recibido.

La herramienta [curl] permite ver la misma información en un terminal. Con la opción [-i], muestra los encabezados HTTP de la respuesta del servidor, seguidos del documento recibido:

> curl -i http://localhost/php8-oct-2026/scripts-web/01/example-01.html
HTTP/1.1 200 OK
Date: Thu, 01 Oct 2026 15:31:46 GMT
Server: Apache/2.4.58 (Ubuntu)
Last-Modified: Thu, 01 Oct 2026 14:29:23 GMT
ETag: "12b-65cc83df75105"
Accept-Ranges: bytes
Content-Length: 299
Vary: Accept-Encoding
Content-Type: text/html

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>PHP 8 by example</title>
    </head>
    <body>
        <div><b>This is an example of a static page</b></div>
    </body>
</html>
  • Línea 2: la línea de estado de la respuesta: versión del protocolo HTTP, código de estado [200] y su descripción [OK];
  • a continuación vienen los encabezados HTTP de la respuesta. Entre ellos figuran, en particular, la fecha de la respuesta [Date], la firma del servidor [Server], la fecha de la última modificación del documento [Last-Modified], su tamaño en bytes [Content-Length] y su tipo [Content-Type];
  • seguidos de una línea en blanco, que separa los encabezados del documento;
  • y, por último, el documento HTML que creamos. Un navegador interpreta este código para mostrar la página que vimos antes.

17.3. Creación de una página dinámica en PHP

Ahora escribiremos una página dinámica en PHP. En la carpeta [scripts-web/01], creamos el siguiente archivo, [example-01.php]:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>Example of a dynamic page</title>
    </head>
    <body>
        <?php
        // time(): número de segundos transcurridos desde el 01/01/1970 00:00:00 UTC
        // formato de visualización de la fecha y la hora
        // d: día en 2 dígitos
        // m: mes en 2 dígitos
        // y: año en 2 dígitos
        // H: hora 00-23
        // i: minutos
        // s: segundos
        print "<b>Today's date and time: </b>" . date("d/m/y H:i:s", time());
        ?>
    </body>
</html>

Comentarios

  • línea 5: el título de la página;
  • línea 8: el código PHP se coloca entre las etiquetas [<?php] y [?>]. Todo lo que está fuera de estas etiquetas es HTML;
  • línea 17: escribe la fecha y la hora actuales. La función [time] devuelve el número de segundos transcurridos desde el 1 de enero de 1970 a las 0:00 UTC. La función [date] da formato a ese número según el formato especificado por su primer parámetro, en este caso día/mes/año horas:minutos:segundos.

En el fondo, el script PHP anterior escribe la hora actual en la consola. Sin embargo, cuando lo ejecuta un servidor web, el flujo de salida de la instrucción [print], que normalmente se dirige a la consola de ejecución del script, se redirige a la conexión entre el servidor y su cliente. Por lo tanto, en un contexto web, el script anterior envía la hora actual como texto al cliente, en este caso un navegador.

Probemos la URL [http://localhost/php8-oct-2026/scripts-web/01/example-01.php]:

Image

Esta es una página dinámica porque, si se recarga varias veces en el navegador (F5), su contenido cambia (cambia la hora).

El navegador ha recibido un flujo HTML. Para verlo, puede mostrar el código fuente de la página en el navegador (haga clic derecho en la página y seleccione la opción [View page source], o presione Ctrl-U), o utilizar [curl]:

> curl -i http://localhost/php8-oct-2026/scripts-web/01/example-01.php
HTTP/1.1 200 OK
Date: Thu, 01 Oct 2026 15:31:46 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Vary: Accept-Encoding
Content-Length: 222
Content-Type: text/html; charset=UTF-8

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>Example of a dynamic page</title>
    </head>
    <body>
        <b>Today's date and time: </b>01/10/26 17:31:46    </body>
</html>
  • después de la línea en blanco, el código HTML recibido. El código PHP ha desaparecido: fue reemplazado por el texto que generó, junto con la fecha y la hora;
  • entre los encabezados, el encabezado [X-Powered-By] no estaba presente cuando se solicitó la página estática. Indica que la respuesta del servidor fue generada por un script PHP. En cambio, los encabezados [Last-Modified] y [ETag] han desaparecido: el documento no existe en el disco, se genera en el momento de la solicitud. El encabezado [Content-Length] sigue presente: como el documento es corto, [Apache] pudo recibirlo por completo antes de enviar los encabezados y así calcular su tamaño.

Por lo tanto, es importante recordar que un script PHP destinado a ser ejecutado por un servidor web para un navegador debe producir un flujo HTML. Veremos que el script también puede generar los encabezados HTTP y prácticamente todos los elementos de la respuesta del servidor.

17.4. Fundamentos del lenguaje HTML

Este capítulo no profundizará en la programación web en PHP. Más adelante en este curso se desarrolla una aplicación web MVC. Aquí nos centramos más bien en los servicios web: páginas PHP que entregan datos a otros clientes PHP a través de un servidor web. No obstante, nos pareció útil ofrecer al lector algunos fundamentos de HTML.

Un navegador web puede mostrar diversos documentos, el más común de los cuales es el documento HTML (HyperText Markup Language). Se trata de texto con formato que contiene etiquetas de la forma [<tag>text</tag>]. Por ejemplo, el texto [<b>important</b>] mostrará texto importante en negrita. Existen etiquetas independientes, como la etiqueta [<hr>], que muestra una línea horizontal. No repasaremos todas las etiquetas que pueden encontrarse en un texto HTML. Una buena referencia es el sitio de documentación de Mozilla: https://developer.mozilla.org/en-US/docs/Web/HTML. Conocer el lenguaje HTML es esencial, ya que las aplicaciones web dinámicas deben generar ellas mismas el código HTML que enviarán a los clientes web.

En resumen, no es necesario conocer todo el lenguaje HTML para comenzar con la programación web. Una forma de descubrir los entresijos del lenguaje HTML es navegar por la web y ver el código fuente de las páginas que presentan características interesantes que aún no conoce.

Consideremos el siguiente ejemplo [tags.html], que incluye algunos elementos comunes en un documento web, como:

  • una tabla;
  • una imagen;
  • un enlace.

Image

Un documento HTML tiene generalmente el siguiente formato:

<!DOCTYPE html>
<html>
    <head>
        <title>A title</title>
        ...
    </head>
    <body attributes>
        ...
    </body>
</html>

Todo el documento está encerrado entre las etiquetas [<html>…</html>]. Consta de dos partes:

  • [<head>…</head>]: es la parte no visible del documento. Proporciona información al navegador que mostrará el documento. A menudo contiene la etiqueta [<title>…</title>], que especifica el texto que aparecerá en la pestaña del navegador. También puede haber otras etiquetas, entre ellas las que definen las palabras clave del documento, que luego utilizan los motores de búsqueda. Esta sección también puede contener scripts, escritos en JavaScript, que ejecutará el navegador;
  • [<body attributes>…</body>]: es la sección que mostrará el navegador. Las etiquetas HTML contenidas en esta sección indican al navegador la disposición visual «deseada» para el documento.

El código HTML de nuestro documento de ejemplo es el siguiente:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>A few HTML tags</title>
    </head>

    <body style="background-image: url(images/standard.jpg)">
        <h1 style="text-align: left">A few HTML tags</h1>
        <hr>

        <table border="1">
            <thead>
                <tr>
                    <th>Column 1</th>
                    <th>Column 2</th>
                    <th>Column 3</th>
                </tr>
            </thead>
            <tbody>
                <tr>
                    <td>cell(1,1)</td>
                    <td style="text-align: center;">cell(1,2)</td>
                    <td>cell(1,3)</td>
                </tr>
                <tr>
                    <td>cell(2,1)</td>
                    <td>cell(2,2)</td>
                    <td>cell(2,3)</td>
                </tr>
            </tbody>
        </table>
        <br><br>
        <table border="0">
            <tr>
                <td>An image</td>
                <td><img src="images/cherry-tree.jpg" alt="a cherry tree"></td>
            </tr>
            <tr>
                <td>The PHP language website</td>
                <td><a href="https://www.php.net/">here</a></td>
            </tr>
        </table>
    </body>
</html>
elemento
Etiquetas HTML y ejemplos
  
título del documento
[<title>A few HTML tags</title>] (línea 5): el texto [A few HTML tags] aparecerá en la pestaña del navegador que muestra el documento
  
barra horizontal
[<hr>]: muestra una línea horizontal (línea 10)
  
tabla
[<table attributes>….</table>]: para definir la tabla (línea 12);
[<thead>…</thead>]: para definir los encabezados de las columnas ({{L:<thead>
</thead>}});
[<tbody>…</tbody>]: para definir el contenido de la tabla ({{L:<tbody>
</tbody>}});
[<tr attributes>…</tr>]: para definir una fila (línea 21);
[<td attributes>…</td>]: para definir una celda (línea 22);
ejemplos:
[<table border="1">…</table>]: el atributo [border] define el grosor del borde de la tabla;
[<td style="text-align: center;">cell(1,2)</td>] (línea 23): define una celda cuyo contenido será [cell(1,2)]. Este contenido estará centrado horizontalmente ([text-align: center])
imagen
[<img src="images/cherry-tree.jpg" alt="a cherry tree">] (línea 37): define una imagen cuyo archivo de origen es [images/cherry-tree.jpg] en el servidor web. El atributo [alt] proporciona un texto alternativo, que se muestra si la imagen no puede mostrarse. Esta etiqueta aparece en un documento web generado mediante la URL [http://localhost/php8-oct-2026/scripts-web/01/tags.html]. Por lo tanto, el navegador solicitará la URL [http://localhost/php8-oct-2026/scripts-web/01/images/cherry-tree.jpg] para obtener la imagen a la que se hace referencia aquí
  
enlace
[<a href="https://www.php.net/">here</a>] (línea 41): hace que el texto [here] sirva como enlace a la URL [https://www.php.net/]
  
fondo de la página
[<body style="background-image: url(images/standard.jpg)">] (línea 8): indica que la imagen que se utilizará como fondo de la página se encuentra en la URL [images/standard.jpg] del servidor web. En el contexto de nuestro ejemplo, el navegador solicitará la URL [http://localhost/php8-oct-2026/scripts-web/01/images/standard.jpg] para obtener esta imagen de fondo
  

Este sencillo ejemplo muestra que, para construir el documento completo, el navegador debe hacer tres solicitudes al servidor:

  • [http://localhost/php8-oct-2026/scripts-web/01/tags.html] para obtener el código fuente HTML del documento;
  • [http://localhost/php8-oct-2026/scripts-web/01/images/cherry-tree.jpg] para obtener la imagen [cherry-tree.jpg];
  • [http://localhost/php8-oct-2026/scripts-web/01/images/standard.jpg] para obtener la imagen de fondo [standard.jpg].

Esto es lo que muestra la pestaña [Network] de las herramientas de desarrollo del navegador (F12): muestra las tres solicitudes realizadas por el navegador.

Nota: en Windows, los nombres de archivo no distinguen entre mayúsculas y minúsculas: [Cherry-tree.jpg] and [cherry-tree.jpg] se refieren al mismo archivo. En un servidor Linux, donde se alojan la mayoría de los sitios web, no es así. Por lo tanto, conviene adquirir el hábito de escribir los nombres de archivo exactamente como aparecen en el disco, también en las URL.

17.5. Cómo hacer dinámica una página estática

Mostremos cómo hacer dinámica la página HTML [example-01.html]. Copiemos su contenido en un archivo llamado [page-00.php]. Este script PHP no contiene nada de PHP, solo HTML. Solicitémoslo al servidor:

> curl http://localhost/php8-oct-2026/scripts-web/01/page-00.php
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>PHP 8 by example</title>
    </head>
    <body>
        <div><b>This is an example of a static page</b></div>
    </body>
</html>

El intérprete de PHP procesó el script [page-00.php] y produjo la misma salida HTML que la página estática [example-01.html]. Esto nos enseña una cosa: cuando el intérprete de PHP encuentra HTML dentro de un script PHP, lo deja intacto y lo envía al cliente tal cual.

Ahora agreguemos algunas instrucciones PHP al siguiente script [page-01.php] para que el intérprete de PHP tenga algo que hacer:

<!DOCTYPE html>
<html lang="en">
    <head>
        <title><?= $page->title ?></title>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
    </head>
    <body>
        <div><b><?= $page->contents ?></b></div>
    </body>
</html>
  • Líneas 4 y 9: agregamos código PHP para generar dinámicamente el título y el contenido de la página. Aquí suponemos que la variable [$page] es un objeto que contiene los datos que se mostrarán. La etiqueta [<?= expression ?>] es un atajo de [<?php print expression ?>]. Está pensada para este tipo de páginas: HTML con algunos valores calculados por PHP.

Si llamamos directamente a este script, obtenemos el siguiente resultado:

> curl http://localhost/php8-oct-2026/scripts-web/01/page-01.php
<!DOCTYPE html>
<html lang="en">
    <head>
        <title><br />
<b>Warning</b>:  Undefined variable $page in <b>.../php8-oct-2026/scripts-web/01/page-01.php</b> on line <b>4</b><br />
<br />
<b>Warning</b>:  Attempt to read property "title" on null in <b>.../php8-oct-2026/scripts-web/01/page-01.php</b> on line <b>4</b><br />
</title>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
    </head>
    <body>
        <div><b><br />
<b>Warning</b>:  Undefined variable $page in <b>.../php8-oct-2026/scripts-web/01/page-01.php</b> on line <b>9</b><br />
<br />
<b>Warning</b>:  Attempt to read property "contents" on null in <b>.../php8-oct-2026/scripts-web/01/page-01.php</b> on line <b>9</b><br />
</b></div>
    </body>
</html>
  • Líneas 5–8: no se pudo calcular el título de la página porque la variable [$page] no estaba definida. PHP insertó dos mensajes de advertencia en el flujo HTML: la variable [$page] no existe y no se puede leer la propiedad [title] de [null] ;
  • Líneas 14–17: el mismo problema con el contenido.

Nota: a partir de PHP 8.0, usar una variable no definida y leer una propiedad de [null] genera una advertencia [Warning] en lugar de un simple aviso [Notice] como en PHP 7. Los mensajes se muestran en la página porque la configuración de PHP de [Laragon] es una configuración de desarrollo ([display_errors=On]). En un servidor de producción se utiliza [display_errors=Off], y los errores se escriben en un archivo de registro.

Ahora escribamos el siguiente script web [example-02.php]:

<?php

declare(strict_types=1);

// definimos los elementos de la página que se mostrará
$page = new stdClass();
$page->title = "A new title";
$page->contents = "A new dynamically generated content";
// hacemos que se muestre [page-01.php]
require_once __DIR__ . "/page-01.php";
  • Línea 3: como todos los scripts PHP de este curso, este script exige una verificación estricta de tipos;
  • Líneas 6–8: definimos el objeto [$page]. La clase predefinida [stdClass] es la única clase (junto con las clases marcadas con el atributo [#[\AllowDynamicProperties]]) a la que aún se pueden agregar propiedades no declaradas sin una advertencia: a partir de PHP 8.2, la creación de propiedades dinámicas en objetos de otras clases está obsoleta;
  • Línea 10: se incluye el script [page-01.php]. El código de este script se interpretará entonces:
    • la variable [$page] ahora está definida y el intérprete de PHP la utilizará;
    • el código HTML de [page-01.php] se enviará tal cual al cliente;
    • los resultados de las expresiones de [<?= … ?>] se incluirán en el flujo de texto enviado al cliente.

Ahora, si solicitamos el script web [example-02.php], obtenemos lo siguiente en el navegador:

Image

Y este es el texto recibido por el navegador:

> curl http://localhost/php8-oct-2026/scripts-web/01/example-02.php
<!DOCTYPE html>
<html lang="en">
    <head>
        <title>A new title</title>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
    </head>
    <body>
        <div><b>A new dynamically generated content</b></div>
    </body>
</html>
  • Líneas 5 y 10: los códigos PHP y [page-01.php] han sido reemplazados por los valores de las expresiones [$page->title] y [$page->contents].

De este ejemplo podemos extraer dos puntos clave:

  • Las páginas HTML destinadas al navegador pueden aislarse en scripts PHP que contengan solo este código HTML y algunas partes dinámicas generadas por código PHP. Debe haber la menor cantidad posible de PHP en estas páginas;
  • toda la lógica que genera los datos dinámicos incluidos en las páginas HTML debe aislarse en scripts PHP puros, que no contengan código de presentación de páginas (HTML, CSS, JavaScript…).

Esto permite una separación de tareas:

  • la tarea de generar las páginas web que se mostrarán (HTML, CSS, JavaScript…);
  • la tarea de implementar la lógica de la aplicación web que se está construyendo. Esta lógica puede implementarse mediante una arquitectura en capas, exactamente como hicimos con los scripts de consola.

Nota: un valor insertado en una página HTML normalmente debería protegerse con la función [htmlspecialchars], que reemplaza los caracteres especiales de HTML ([<], [>], [&], ["]) por sus códigos HTML. De lo contrario, un valor proporcionado por un usuario que contenga, por ejemplo, una etiqueta como [<script>] sería ejecutado por el navegador (vulnerabilidad XSS). Volveremos sobre esto cuando escribamos páginas HTML.

A continuación, construiremos scripts web específicos:

  • enviarán únicamente datos al cliente y ningún formato (HTML, CSS, JavaScript). Por lo tanto, serán servidores de datos y no páginas web;
  • los clientes de estos scripts web serán scripts de consola que obtendrán los datos enviados por el servidor y los procesarán.

17.6. Aplicación cliente/servidor de fecha y hora

Ahora consideramos la siguiente configuración:

Image

Escribiremos:

  • un script web, [1], que envía la fecha y la hora actuales a su cliente;
  • un script de consola [2] que actuará como cliente del script web: obtendrá la fecha y la hora enviadas por el script web y las mostrará en la consola.
php8-oct-2026
├── scripts-console
│   └── web-clients
│       └── 02
│           ├── config-date-time-client-2.json
│           ├── config-date-time-client.json
│           ├── config-spy.json
│           ├── date-time-client.php
│           └── spy-server.php
└── scripts-web
    └── 02
        ├── date-time-server-2.php
        └── date-time-server.php

17.6.1. El script del lado del servidor

Ya escribimos un script web que genera la fecha y la hora actuales: el script [example-01.php] del apartado anterior. Mencionamos que escribiríamos servidores de datos: datos sin formato (HTML). Por lo tanto, el script de servidor [date-time-server.php] será el siguiente:

<?php

declare(strict_types=1);

// zona horaria usada por las funciones de fecha
date_default_timezone_set('Europe/Paris');
// establecemos el encabezado HTTP [Content-Type]
header('Content-Type: text/plain; charset=UTF-8');
//
// enviamos la fecha y la hora
// time(): número de segundos transcurridos desde el 01/01/1970 00:00:00 UTC
// formato de visualización de la fecha y la hora
// d: día en 2 dígitos
// m: mes en 2 dígitos
// y: año en 2 dígitos
// H: hora 00-23
// i: minutos
// s: segundos
print date("d/m/y H:i:s", time());
  • Línea 6: las funciones de fecha utilizan la zona horaria definida por la directiva [date.timezone] del archivo [php.ini]. Para no depender de la configuración del servidor, el script establece él mismo la zona horaria, en este caso la de París;
  • Línea 8: la función [header] agrega un encabezado HTTP a la respuesta. Aquí se establece el encabezado HTTP y [Content-Type], que informa al cliente sobre la naturaleza del documento que recibirá. Para la página [example-01.php], el encabezado [Content-Type] era [text/html; charset=UTF-8]. Aquí informamos al cliente de que el documento es texto sin formato (no HTML). Esto no es importante para nuestro cliente de consola, que no intentará utilizar este encabezado. Es más importante para los navegadores web, que sí lo utilizan. Los encabezados HTTP preceden al documento en la respuesta del servidor: por lo tanto, la función [header] debe llamarse antes de que el script haya escrito algo;
  • Línea 19: el documento enviado al cliente: la fecha y la hora, sin etiquetas HTML.

Solicitemos este script con un navegador:

Image

El navegador muestra el texto sin formato recibido. Con [curl], vemos el encabezado HTTP [Content-Type] establecido por el script y, tras la línea en blanco, el documento de texto recibido:

1
2
3
4
5
6
7
8
9
> curl -i http://localhost/php8-oct-2026/scripts-web/02/date-time-server.php
HTTP/1.1 200 OK
Date: Thu, 01 Oct 2026 15:31:46 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Content-Length: 17
Content-Type: text/plain; charset=UTF-8

01/10/26 17:31:46

17.6.2. El script del lado del cliente

En el capítulo anterior escribimos varios clientes HTTP. Podríamos utilizarlos para obtener el documento de texto enviado por el script de servidor [date-time-server.php]. Sin embargo, no lo haremos. Como hicimos con los protocolos SMTP e IMAP, utilizaremos una biblioteca de terceros, concretamente el componente [HttpClient] del framework Symfony, cuya documentación se encuentra en la URL https://symfony.com/doc/current/http_client.html.

Al igual que las bibliotecas anteriores, el componente [HttpClient] se instala con la herramienta [Composer]. En una ventana de terminal abierta en la carpeta [php8-oct-2026], el comando sería:

composer require symfony/http-client

Aquí no es necesario: el archivo [composer.json] de la carpeta [php8-oct-2026] ya declara esta dependencia (en la versión 8), así como la del componente [HttpFoundation], que utilizaremos próximamente. El comando [composer install] ejecutado durante la instalación del código del curso los instaló en la carpeta [php8-oct-2026/vendor].

El script de consola [date-time-client.php] procesará el siguiente archivo JSON [config-date-time-client.json]:

1
2
3
{
    "url": "http://localhost/php8-oct-2026/scripts-web/02/date-time-server.php"
}
  • Línea 2: la URL del script de servidor.

El script del lado del cliente [date-time-client.php] es el siguiente:

<?php

declare(strict_types=1);

// cliente del servicio de fecha / hora

// dependencias
require_once __DIR__ . '/../../../vendor/autoload.php';

use Symfony\Component\HttpClient\HttpClient;
use Symfony\Contracts\HttpClient\Exception\ExceptionInterface;

// el archivo de configuración: 1.er argumento de la línea de comandos si existe
$configFileName = $argv[1] ?? "config-date-time-client.json";

// recuperamos la configuración
if (!file_exists($configFileName)) {
    print "The configuration file [$configFileName] does not exist\n";
    exit(1);
}
try {
    $config = json_decode(file_get_contents($configFileName), true, flags: JSON_THROW_ON_ERROR);
} catch (JsonException $ex) {
    print "Error while using the JSON configuration file [$configFileName]: {$ex->getMessage()}\n";
    exit(1);
}

// creamos un cliente HTTP
$httpClient = HttpClient::create();

try {
    // hacemos la solicitud
    $response = $httpClient->request('GET', $config['url']);
    // estado de la respuesta
    $statusCode = $response->getStatusCode();
    print "---Response with status: $statusCode\n";
    // recuperamos los encabezados
    print "---Headers of the response\n";
    foreach ($response->getHeaders() as $name => $values) {
        print "$name: $values[0]\n";
    }
    // recuperamos el cuerpo de la respuesta
    $content = $response->getContent();
    // lo mostramos
    print "---Server response: [$content]\n";
} catch (ExceptionInterface $ex) {
    // mostramos el error
    print "Error communicating with the server: {$ex->getMessage()}\n";
    exit(2);
}

Comentarios

  • Línea 8: como hicimos con las bibliotecas anteriores, cargamos el archivo [vendor/autoload.php] generado por [Composer]. Su ruta se calcula a partir de la constante [__DIR__], que es la carpeta del script: el script funciona sin importar la ubicación de la carpeta [php8-oct-2026];
  • Línea 10: declaramos la clase [HttpClient] que utilizaremos;
  • línea 11: la interfaz [ExceptionInterface] es implementada por todas las excepciones que puede lanzar el cliente HTTP de Symfony;
  • línea 14: el nombre del archivo de configuración puede pasarse como argumento al script: [php date-time-client.php other-config.json]. De lo contrario, se utiliza el archivo [config-date-time-client.json] . El arreglo [$argv] contiene los argumentos de la línea de comandos, donde [$argv[0]] es el nombre del script. El operador [??] devuelve su operando izquierdo si existe y no es [null]; de lo contrario, devuelve su operando derecho;
  • líneas 17–25: la configuración del script se obtiene en el arreglo [$config]. El parámetro con nombre [flags: JSON_THROW_ON_ERROR] indica a [json_decode] que lance una excepción [JsonException] si el JSON es incorrecto, en lugar de dejar que [null] pase silenciosamente;
  • Línea 29: se crea un cliente HTTP. El método estático [create] selecciona la implementación más adecuada: en este caso, la clase [CurlHttpClient], que utiliza la extensión [curl] de PHP;
  • línea 33: se solicita la URL del script de servidor mediante un comando GET: [GET URL HTTP/1.1]. Esta operación es asíncrona: la ejecución continúa en la línea siguiente sin esperar la respuesta;
  • línea 35: se obtiene el código de estado de la respuesta. Este se encuentra en la primera línea de la respuesta del servidor. Así, si esta línea es [HTTP/1.1 200 OK], el estado de la respuesta es 200. Esta operación es bloqueante: la ejecución no se reanuda hasta que el cliente haya recibido los encabezados de la respuesta del servidor;
  • línea 39: se obtienen los encabezados HTTP de la respuesta. Se obtiene un arreglo asociativo cuyas claves son los nombres de los encabezados (en minúsculas) y cuyos valores son arreglos: en efecto, un mismo encabezado puede aparecer varias veces en una respuesta. Aquí mostramos el primer valor de cada encabezado;
  • línea 43: se obtiene el documento devuelto por el servidor; sabemos que este documento es texto;
  • línea 46: si se produce un error, se muestra el mensaje de error. El script PHP 7 capturaba las excepciones [TypeError | RuntimeException]; es más preciso capturar las excepciones del cliente HTTP, todas las cuales implementan [ExceptionInterface]. Tenga en cuenta que [getHeaders] y [getContent] lanzan una excepción cuando el código de estado de la respuesta indica un error (códigos del 300 al 599). Hablaremos de esto en la sección sobre autenticación.

El cliente se ejecuta en un terminal con el directorio abierto ([Laragon] debe estar en ejecución para que el script de servidor sea accesible):

1
2
3
4
5
6
7
8
9
> php date-time-client.php
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:26 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
content-length: 17
content-type: text/plain; charset=UTF-8
---Server response: [01/10/26 18:55:26]

La fecha y la hora actuales se obtienen correctamente en la última línea. Los encabezados mostrados son los mismos que vimos con [curl], con los nombres en minúsculas.

Tal vez sienta curiosidad por saber qué envió el script cliente al servidor. En el capítulo anterior utilizamos con ese fin un servidor TCP genérico, que muestra las líneas de texto que recibe. Aquí escribiremos un pequeño servidor «espía» TCP, [spy-server.php], que hace lo mismo y luego devuelve una respuesta HTTP mínima al cliente:

<?php

declare(strict_types=1);

// un servidor TCP "espía": muestra lo que le envía un cliente HTTP
// y luego le devuelve una respuesta HTTP mínima
// uso: php spy-server.php [port]

$port = (int) ($argv[1] ?? 100);
// el servicio en escucha
$server = stream_socket_server("tcp://127.0.0.1:$port", $errorCode, $errorMessage);
if ($server === false) {
    print "Unable to create the service on port $port: $errorMessage\n";
    exit(1);
}
print "Spy server waiting for a client on port $port\n";
// esperamos a un cliente (5 minutos como máximo)
$client = stream_socket_accept($server, 300, $clientName);
if ($client === false) {
    print "No client showed up\n";
    exit(1);
}
print "Client connected: $clientName\n";
print "--- lines received\n";
// lectura de los encabezados HTTP hasta la línea vacía
$contentLength = 0;
while (($line = fgets($client)) !== false) {
    $line = rtrim($line, "\r\n");
    print "$line\n";
    if ($line === "") {
        // fin de los encabezados
        break;
    }
    // el tamaño del documento que sigue a los encabezados
    if (preg_match('/^content-length:\s*(\d+)$/i', $line, $fields)) {
        $contentLength = (int) $fields[1];
    }
}
// lectura del posible documento
if ($contentLength > 0) {
    print stream_get_contents($client, $contentLength) . "\n";
}
// respuesta HTTP mínima: línea de estado, encabezados, línea vacía, documento
$document = "response of the spy server";
fwrite($client, "HTTP/1.1 200 OK\r\n"
    . "Content-Type: text/plain; charset=UTF-8\r\n"
    . "Content-Length: " . strlen($document) . "\r\n"
    . "Connection: close\r\n"
    . "\r\n"
    . $document);
// fin de la comunicación
fclose($client);
fclose($server);
print "--- end of the communication\n";
  • línea 9: el puerto de escucha se pasa como argumento; el valor predeterminado es 100;
  • línea 11: crea un servicio TCP en el puerto [port] de la máquina local;
  • línea 18: espera a un cliente;
  • línea 27: lee y muestra las líneas recibidas hasta la línea vacía que termina los encabezados HTTP. En el camino, anota el valor del encabezado [Content-Length], que especifica el tamaño del documento que puede seguir a los encabezados;
  • líneas 40–41: leen y muestran este documento;
  • líneas 45–50: envían una respuesta HTTP mínima: línea de estado, encabezados, línea vacía, documento;
  • línea 52: cierra la conexión con el cliente para que detecte que ha recibido toda la respuesta.

Iniciamos el servidor espía en el primer terminal:

php spy-server.php 100

El archivo de configuración [config-spy.json] especifica el puerto 100 de la máquina local:

1
2
3
{
    "url": "http://localhost:100/php8-oct-2026/scripts-web/02/date-time-server.php"
}

Esta vez, el cliente contacta con el servidor [localhost] en el puerto 100. Por lo tanto, nuestro servidor espía será el que atienda la solicitud. En un segundo terminal, ejecutamos el cliente con esta configuración:

1
2
3
4
5
6
7
> php date-time-client.php config-spy.json
---Response with status: 200
---Headers of the response
content-type: text/plain; charset=UTF-8
content-length: 26
connection: close
---Server response: [response of the spy server]
  • Línea 7: el cliente recibió correctamente el documento enviado por el servidor espía.

En el primer terminal, el servidor espía mostró lo que recibió:

> php spy-server.php 100
Spy server waiting for a client on port 100
Client connected: 127.0.0.1:49512
--- lines received
GET /php8-oct-2026/scripts-web/02/date-time-server.php HTTP/1.1
Host: localhost:100
Accept: */*
User-Agent: Symfony HttpClient (Curl)
Accept-Encoding: gzip

--- end of the communication
  • Línea 5: el comando HTTP GET generado por el script cliente;
  • Línea 6: el encabezado [Host] especifica la máquina y el puerto de destino;
  • línea 8: la firma del cliente de Symfony [HttpClient];
  • línea 9: el cliente indica que acepta una respuesta comprimida en formato [gzip];
  • línea 10: la línea vacía que termina los encabezados. Una solicitud GET no tiene documento.

17.6.3. El script del servidor – versión 2

De forma predeterminada, las funciones para escribir un script web no están orientadas a objetos. Del lado del servidor, esto significa que se terminan mezclando clases con funciones tradicionales de PHP. Para lograr un estilo de codificación más coherente, utilizaremos la biblioteca [HttpFoundation] del framework Symfony. Encapsula todas las funciones estándar de PHP de un script web dentro de un sistema de clases e interfaces: la clase [Request] representa la solicitud del cliente y la clase [Response] representa la respuesta del servidor. La documentación de la biblioteca está disponible en https://symfony.com/doc/current/components/http_foundation.html.

Al igual que [HttpClient], la biblioteca [HttpFoundation] (versión 8) ya está instalada en la carpeta [vendor]. Probablemente se instaló con el siguiente comando:

composer require symfony/http-foundation

La segunda versión del servidor [date-time-server-2.php] es la siguiente:

<?php

declare(strict_types=1);

// uso de la biblioteca [HttpFoundation] de Symfony

// dependencias
require_once __DIR__ . '/../../vendor/autoload.php';

use Symfony\Component\HttpFoundation\Response;

// zona horaria usada por las funciones de fecha
date_default_timezone_set('Europe/Paris');

// la respuesta: contenido, código de estado, encabezados HTTP
$response = new Response(
    content: date("d/m/y H:i:s", time()),
    status: Response::HTTP_OK,
    headers: ['Content-Type' => 'text/plain'],
);
// el texto enviado está codificado en UTF-8
$response->setCharset('UTF-8');

// enviamos la respuesta
$response->send();

Comentarios

  • Línea 8: carga de las bibliotecas instaladas por [Composer]. El script está en la carpeta [scripts-web/02]: la carpeta [vendor] está dos niveles más arriba;
  • Línea 10: la clase [Response] de la biblioteca [HttpFoundation] gestiona toda la respuesta a los clientes del servicio web;
  • Líneas 16–20: creación de la respuesta. El constructor de la clase [Response] tiene tres parámetros: el documento enviado al cliente (aquí, la fecha y la hora), el código de estado de la respuesta (aquí, la constante [Response::HTTP_OK], que vale 200) y un arreglo de encabezados HTTP. Utilizamos los argumentos con nombre de PHP 8.0 ([content:], [status:], [headers:]): hacen que la llamada sea más legible y eliminan la necesidad de respetar el orden de los parámetros;
  • línea 22: la respuesta es texto UTF-8. [HttpFoundation] agregará [charset=UTF-8] al encabezado [Content-Type];
  • línea 25: la respuesta se envía al cliente: la línea de estado, los encabezados y luego el documento. El método [send] utiliza las funciones [http_response_code], [header] y [print], que habríamos utilizado nosotros mismos.

Con [curl]:

> curl -i http://localhost/php8-oct-2026/scripts-web/02/date-time-server-2.php
HTTP/1.0 200 OK
Date: Thu, 01 Oct 2026 15:31:46 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Cache-Control: no-cache, private
Vary: Accept-Encoding
Connection: close
Content-Type: text/plain;charset=UTF-8

01/10/26 17:31:46
  • línea 2: código de respuesta 200;
  • el encabezado [Cache-Control] fue agregado por [HttpFoundation]. Indica que la respuesta no debe ser almacenada en caché por un intermediario (un proxy);
  • el encabezado [Content-Type] es el establecido por el script, complementado con el juego de caracteres;
  • La última línea es el documento.

17.6.4. El script del cliente – versión 2

El script del cliente permanece sin cambios. Simplemente se le da un archivo de configuración diferente, [config-date-time-client-2.json]:

1
2
3
{
    "url": "http://localhost/php8-oct-2026/scripts-web/02/date-time-server-2.php"
}

Los resultados son los mismos que en la versión 1:

> php date-time-client.php config-date-time-client-2.json
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:26 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: no-cache, private
vary: Accept-Encoding
content-encoding: gzip
connection: close
content-type: text/plain;charset=UTF-8
---Server response: [01/10/26 18:55:26]

17.7. Un servidor de datos JSON

La respuesta de un script web puede estar formada por varios elementos de datos que pueden organizarse en arreglos y objetos. El script puede entonces enviar estos diversos elementos dentro de una cadena JSON, que el cliente decodificará.

php8-oct-2026
├── scripts-console
│   └── web-clients
│       └── 03
│           ├── config-json-client.json
│           ├── json-client.php
│           └── Person.php
└── scripts-web
    └── 03
        ├── json-server.php
        └── Person.php

17.7.1. El script del lado del servidor

El script [json-server.php] utiliza la siguiente clase [Person]:

<?php

declare(strict_types=1);

namespace Models;

class Person implements \JsonSerializable
{
    // constructor con promoción de propiedades
    // las propiedades se pueden leer desde cualquier lugar pero modificar solo dentro de la clase
    public function __construct(
        public private(set) string $lastName = "",
        public private(set) string $firstName = "",
        public private(set) int $age = 0,
    ) {
    }

    // conversión de un arreglo asociativo en un objeto [Person]
    public static function fromArray(array $assoc): static
    {
        // las claves del arreglo se convierten en argumentos con nombre del constructor
        return new static(...$assoc);
    }

    // setter de la edad
    public function setAge(int $age): static
    {
        $this->age = $age;
        return $this;
    }

    // toString
    public function __toString(): string
    {
        return "Person [$this->firstName, $this->lastName, $this->age]";
    }

    // implementa la interfaz JsonSerializable
    public function jsonSerialize(): array
    {
        // devolvemos un arreglo asociativo cuyas claves son las propiedades del objeto
        // este arreglo se puede codificar luego en JSON
        return get_object_vars($this);
    }

    // conversión de una cadena JSON en un objeto [Person]
    public static function jsonUnserialize(string $json): static
    {
        return static::fromArray(json_decode($json, true, flags: JSON_THROW_ON_ERROR));
    }
}

Comentarios

  • línea 5: la clase pertenece al espacio de nombres [Models];
  • línea 7: la clase implementa la interfaz [JsonSerializable] de PHP. Esto la obliga a implementar el método [jsonSerialize] (líneas 39–43). El método debe devolver un valor que se serializará en JSON, en este caso un arreglo asociativo. Cuando se utiliza la expresión [json_encode($person)], la función [json_encode] comprueba si la clase [Person] implementa la interfaz [JsonSerializable]. Si es así, la expresión se convierte en [json_encode($person->jsonSerialize())];
  • líneas 11–15: el constructor utiliza la promoción de propiedades de PHP 8.0: cada parámetro precedido de un especificador de visibilidad declara una propiedad y la inicializa. Los tres parámetros tienen un valor predeterminado;
  • línea 12: visibilidad asimétrica, introducida en PHP 8.4: la propiedad se puede leer desde cualquier lugar ([public]) pero solo puede modificarse dentro de la clase ([private(set)]). Por lo tanto, podemos escribir [$person->lastName] para leer, sin un getter, pero no [$person->lastName = "x"] fuera de la clase. El PHP 7 de 2019 nos obligaba a declarar propiedades privadas y escribir un getter para cada una;
  • líneas 19–22: un constructor (también llamado fábrica) de un objeto [Person] a partir de un arreglo asociativo. La expresión [new static(...$assoc)] pasa los elementos del arreglo al constructor. Desde PHP 8.1, el operador [...] acepta arreglos con claves de tipo cadena: cada clave se convierte en un argumento con nombre. Así, [Person::fromArray(["lastName" => "x", "age" => 3])] equivale a [new Person(lastName: "x", age: 3)]. Una clave que no sea un parámetro del constructor provoca un error. La versión PHP 7 de la clase copiaba los elementos del arreglo en propiedades con nombres arbitrarios, lo que podía crear propiedades dinámicas, una característica obsoleta desde PHP 8.2;
  • líneas 26–29: el único setter de la clase. Devuelve el propio objeto (tipo de retorno [static]), lo que permite encadenar llamadas;
  • línea 43: la función [get_object_vars] devuelve el arreglo asociativo del objeto [property => value];
  • línea 47: la función estática [jsonUnserialize] permite crear un objeto [Person] a partir de su cadena JSON.

El script [json-server.php] es el siguiente:

<?php

declare(strict_types=1);

// dependencias
require_once __DIR__ . '/../../vendor/autoload.php';
require_once __DIR__ . '/Person.php';

use Models\Person;
use Symfony\Component\HttpFoundation\Response;

// creamos un objeto Person
$person = new Person(lastName: "de la Hûche", firstName: "jean-paul", age: 27);
// un arreglo asociativo
$assoc = [
    "attr1" => "value1",
    "attr2" => [
        "firstName" => "Jean-Paul",
        "lastName" => "de la Hûche",
    ],
];
// la respuesta es la cadena JSON de un arreglo
$response = new Response(
    content: json_encode([$person, $assoc], JSON_THROW_ON_ERROR),
    headers: ['Content-Type' => 'application/json'],
);
$response->setCharset('UTF-8');

// envío de la respuesta
$response->send();

Comentarios

  • líneas 7 y 9: se importa la clase [Person];
  • Línea 13: se crea un objeto [Person] con argumentos con nombre;
  • Líneas 15–21: se crea un arreglo asociativo de dos niveles;
  • Línea 24: el documento enviado al cliente es la cadena JSON de un arreglo:
    • el elemento [$person] se serializará a JSON mediante su método [jsonSerialize];
    • el elemento [$assoc] se serializará a JSON de forma nativa;
    • la opción [JSON_THROW_ON_ERROR] hace que [json_encode] lance una excepción en caso de error (por ejemplo, una cadena que no está en formato UTF-8) en lugar de devolver [false];
  • Línea 25: especifica que el documento es de tipo [application/json]. Al recibir este encabezado, los navegadores muestran la cadena JSON con formato.

Si se solicita este script con un navegador (Chrome en este caso), se obtiene la siguiente respuesta:

Image

Observe la codificación de los caracteres acentuados: de forma predeterminada, [json_encode] reemplaza cualquier carácter que no sea ASCII por su secuencia Unicode [\uXXXX] ([û] se convierte en [û]). La casilla [Pretty-print] de Chrome muestra el JSON con sangría. Con [curl]:

> curl -i http://localhost/php8-oct-2026/scripts-web/03/json-server.php
HTTP/1.0 200 OK
Date: Thu, 01 Oct 2026 15:31:46 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Cache-Control: no-cache, private
Connection: close
Content-Type: application/json

[{"lastName":"de la H\u00fbche","firstName":"jean-paul","age":27},{"attr1":"value1","attr2":{"firstName":"Jean-Paul","lastName":"de la H\u00fbche"}}]
  • el encabezado [Content-Type] especifica que el tipo del documento es [application/json];
  • la última línea es la cadena JSON recibida.

17.7.2. El cliente

El cliente [json-client.php] se configura mediante el siguiente archivo JSON [config-json-client.json]:

1
2
3
{
    "url": "http://localhost/php8-oct-2026/scripts-web/03/json-server.php"
}

Utiliza una copia de la clase [Person] del servidor, ubicada en su carpeta. El script [json-client.php] es el siguiente:

<?php

declare(strict_types=1);

// cliente de un servicio JSON

// dependencias
require_once __DIR__ . '/../../../vendor/autoload.php';
require_once __DIR__ . '/Person.php';

use Models\Person;
use Symfony\Component\HttpClient\HttpClient;
use Symfony\Contracts\HttpClient\Exception\ExceptionInterface;

// la configuración del cliente
const CONFIG_FILE_NAME = "config-json-client.json";

// recuperamos la configuración
if (!file_exists(CONFIG_FILE_NAME)) {
    print "The configuration file [" . CONFIG_FILE_NAME . "] does not exist\n";
    exit(1);
}
try {
    $config = json_decode(file_get_contents(CONFIG_FILE_NAME), true, flags: JSON_THROW_ON_ERROR);
} catch (JsonException $ex) {
    print "Error while using the JSON configuration file [" . CONFIG_FILE_NAME . "]: {$ex->getMessage()}\n";
    exit(1);
}

// creamos un cliente HTTP
$httpClient = HttpClient::create();

try {
    // hacemos la solicitud
    $response = $httpClient->request('GET', $config['url']);
    // estado de la respuesta
    $statusCode = $response->getStatusCode();
    print "---Response with status: $statusCode\n";
    // recuperamos los encabezados
    print "---Headers of the response\n";
    foreach ($response->getHeaders() as $name => $values) {
        print "$name: $values[0]\n";
    }
    // recuperamos el cuerpo JSON de la respuesta como un arreglo PHP
    [$person, $assoc] = $response->toArray();
    // instanciamos una persona a partir del arreglo de sus propiedades
    $person = Person::fromArray($person);
    // mostramos la respuesta del servidor
    print "---Server response\n";
    print "$person\n";
    print "array=" . json_encode($assoc, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE) . "\n";
} catch (ExceptionInterface $ex) {
    // mostramos el error
    print "Error communicating with the server: {$ex->getMessage()}\n";
    exit(2);
}

Comentarios

  • líneas 9 y 11: importación de la clase [Person];
  • Línea 16: este cliente siempre utiliza el mismo archivo de configuración, cuyo nombre es una constante;
  • línea 31: creación del cliente HTTP;
  • Línea 45: el método [toArray] de la respuesta decodifica el documento JSON recibido y devuelve el arreglo PHP correspondiente. Lanza una excepción si el documento no es de tipo JSON. Sabemos que lo que se codificó es un arreglo con dos elementos. La asignación por descomposición (también conocida como destructuring) [[$person, $assoc] = …] asigna estos dos elementos a dos variables. Reemplaza la antigua sintaxis [list($person, $assoc) = …];
  • línea 47: se crea un objeto [Person] a partir del arreglo de sus propiedades, para mostrarlo más adelante (línea 50). El objeto se convierte en cadena mediante su método [__toString];
  • línea 51: se muestra el segundo arreglo asociativo. La instrucción [print] no puede mostrar arreglos. Por lo tanto, este arreglo se convierte en una cadena JSON. Para conservar los caracteres acentuados tal cual, debe agregarse la opción [JSON_UNESCAPED_UNICODE]. Vimos que, sin esta opción, los caracteres acentuados se codifican en la cadena JSON.

La ejecución del script del lado del cliente produce los siguientes resultados:

> php json-client.php
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:26 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: no-cache, private
connection: close
content-type: application/json
---Server response
Person [jean-paul, de la Hûche, 27]
array={"attr1":"value1","attr2":{"firstName":"Jean-Paul","lastName":"de la Hûche"}}

En las dos últimas líneas, los caracteres acentuados se obtuvieron correctamente.

17.8. Obtención de las variables de entorno desde el servicio web

Un script del lado del servidor se ejecuta en un entorno web al que puede acceder. Este entorno se almacena en el arreglo [$_SERVER], una variable global de PHP. Si utilizamos la biblioteca [HttpFoundation], este entorno se encuentra en la propiedad [server] del objeto [Request], que representa la solicitud HTTP procesada por el script web.

1
2
3
4
5
6
7
8
9
php8-oct-2026
├── scripts-console
│   └── web-clients
│       └── 04
│           ├── config-env-client.json
│           └── env-client.php
└── scripts-web
    └── 04
        └── env-server.php

17.8.1. El script del lado del servidor

Escribimos una aplicación de servidor que envía su entorno de ejecución a sus clientes. El script web [env-server.php] es el siguiente:

<?php

declare(strict_types=1);

// dependencias
require_once __DIR__ . '/../../vendor/autoload.php';

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

// recuperamos la solicitud
$request = Request::createFromGlobals();
// la respuesta es la cadena JSON del entorno del script
$response = new Response(
    content: json_encode($request->server->all(), JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES),
    headers: ['Content-Type' => 'application/json'],
);
$response->setCharset('UTF-8');
// envío de la respuesta
$response->send();
  • Línea 12: creamos un objeto de tipo [Request] que encapsula toda la información disponible sobre la solicitud HTTP recibida por el script web, así como su entorno de ejecución. El método estático [createFromGlobals] construye este objeto a partir de las variables globales de PHP: [$_GET], [$_POST], [$_COOKIE], [$_FILES] y [$_SERVER];
  • Línea 15: la información enviada al cliente es la cadena JSON del objeto [$request->server], que representa el entorno de ejecución del script web. Es un objeto de tipo [ServerBag], una especie de diccionario. [$request->server->all()], en cambio, es un verdadero arreglo asociativo: el contenido de [ServerBag]. Sin [HttpFoundation], habríamos escrito [json_encode($_SERVER)]. La opción [JSON_UNESCAPED_SLASHES] evita que los caracteres [/] de las rutas se codifiquen como [\/];
  • Línea 20: se envía la respuesta.

Si se solicita este script con un navegador, muestra el diccionario JSON de variables de entorno.

17.8.2. El script del cliente

El script del cliente [env-client.php] se configura mediante el siguiente archivo JSON [config-env-client.json]:

{
    "url": "http://localhost/php8-oct-2026/scripts-web/04/env-server.php",
    "display": [
        "HTTP_HOST", "HTTP_USER_AGENT", "HTTP_ACCEPT_ENCODING",
        "SERVER_SOFTWARE", "SERVER_NAME", "SERVER_ADDR", "SERVER_PORT",
        "REMOTE_ADDR", "REMOTE_PORT", "REQUEST_SCHEME", "SERVER_ADMIN",
        "SCRIPT_FILENAME", "SERVER_PROTOCOL", "REQUEST_METHOD", "QUERY_STRING",
        "REQUEST_URI", "SCRIPT_NAME", "PHP_SELF", "REQUEST_TIME_FLOAT"
    ]
}
  • Línea 2: la URL del script de servidor;
  • líneas 3–9: los nombres de las variables de entorno que mostrará el cliente. Sin esta clave, las muestra todas.

El script del cliente [env-client.php] es el siguiente:

<?php

declare(strict_types=1);

// entorno de un script de servidor

// dependencias
require_once __DIR__ . '/../../../vendor/autoload.php';

use Symfony\Component\HttpClient\HttpClient;
use Symfony\Contracts\HttpClient\Exception\ExceptionInterface;

// la configuración del cliente
const CONFIG_FILE_NAME = "config-env-client.json";

// recuperamos la configuración
if (!file_exists(CONFIG_FILE_NAME)) {
    print "The configuration file [" . CONFIG_FILE_NAME . "] does not exist\n";
    exit(1);
}
try {
    $config = json_decode(file_get_contents(CONFIG_FILE_NAME), true, flags: JSON_THROW_ON_ERROR);
} catch (JsonException $ex) {
    print "Error while using the JSON configuration file [" . CONFIG_FILE_NAME . "]: {$ex->getMessage()}\n";
    exit(1);
}

// creamos un cliente HTTP
$httpClient = HttpClient::create();
try {
    // hacemos la solicitud al servidor
    $response = $httpClient->request('GET', $config['url']);
    // estado de la respuesta
    $statusCode = $response->getStatusCode();
    print "---Response with status: $statusCode\n";
    // recuperamos los encabezados
    print "---Headers of the response\n";
    foreach ($response->getHeaders() as $name => $values) {
        print "$name: $values[0]\n";
    }
    // mostramos la respuesta del servidor
    print "---Server response\n";
    $env = $response->toArray();
    // solo conservamos las variables listadas en la configuración (todas si no hay lista)
    if (isset($config['display'])) {
        $env = array_filter($env, fn(string $key): bool => in_array($key, $config['display'], true), ARRAY_FILTER_USE_KEY);
    }
    foreach ($env as $key => $value) {
        print "[$key]=>$value\n";
    }
} catch (ExceptionInterface $ex) {
    // mostramos el error
    print "Error communicating with the server: {$ex->getMessage()}\n";
    exit(2);
}

Comentarios

  • línea 43: se decodifica la respuesta JSON del servidor. Se obtiene un arreglo asociativo;
  • líneas 45–46: el entorno es extenso. Si el archivo de configuración contiene una lista de nombres de variables ([display]), solo se conservan esos nombres. La función [array_filter] conserva los elementos de un arreglo asociativo para los cuales la función pasada como parámetro devuelve [true]. Con la opción [ARRAY_FILTER_USE_KEY], esta función recibe la clave del elemento en lugar de su valor;
  • líneas 48–49: se muestran todos los valores de este arreglo asociativo.

Se obtiene la siguiente salida de consola (la ruta de la carpeta [php8-oct-2026] se abrevia como [.../php8-oct-2026]):

> php env-client.php
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 15:31:46 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: no-cache, private
connection: close
content-type: application/json
---Server response
[HTTP_HOST]=>localhost
[HTTP_USER_AGENT]=>Symfony HttpClient (Curl)
[HTTP_ACCEPT_ENCODING]=>gzip
[SERVER_SOFTWARE]=>Apache/2.4.58 (Ubuntu)
[SERVER_NAME]=>localhost
[SERVER_ADDR]=>127.0.0.1
[SERVER_PORT]=>80
[REMOTE_ADDR]=>127.0.0.1
[REQUEST_SCHEME]=>http
[SERVER_ADMIN]=>webmaster@localhost
[SCRIPT_FILENAME]=>.../php8-oct-2026/scripts-web/04/env-server.php
[REMOTE_PORT]=>54922
[SERVER_PROTOCOL]=>HTTP/1.1
[REQUEST_METHOD]=>GET
[QUERY_STRING]=>
[REQUEST_URI]=>/php8-oct-2026/scripts-web/04/env-server.php
[SCRIPT_NAME]=>/php8-oct-2026/scripts-web/04/env-server.php
[PHP_SELF]=>/php8-oct-2026/scripts-web/04/env-server.php
[REQUEST_TIME_FLOAT]=>1790868706.5464

Este es el significado de estas variables y de algunas otras que el servidor también envía:

variable
Significado
HTTP_HOST
El valor "xxx" del encabezado HTTP [Host: xxx] enviado por el cliente
HTTP_USER_AGENT
el valor xxx del encabezado HTTP [User-Agent: xxx] enviado por el cliente
HTTP_ACCEPT_ENCODING
El valor xxx del encabezado HTTP [Accept-Encoding: xxx] enviado por el cliente
PATH
la ruta de los ejecutables en la máquina donde se ejecuta el script del servidor
SERVER_SIGNATURE
la firma del servidor web, agregada por [Apache] a las páginas que genera él mismo (páginas de error, listas de archivos)
SERVER_SOFTWARE
el tipo de servidor web
SERVER_NAME
el nombre de host del servidor web
SERVER_PORT
Puerto de escucha del servidor web
SERVER_ADDR
la dirección IP de la máquina del servidor web
REMOTE_ADDR
la dirección IP del cliente. En este caso, el cliente estaba en la misma máquina que el servidor
REMOTE_PORT
el puerto desde el cual el cliente hizo su solicitud
DOCUMENT_ROOT
la raíz del árbol de directorios de los documentos servidos por el servidor web, [<laragon>/www] con [Laragon]
REQUEST_SCHEME
el protocolo de la URL solicitada: [http] o [https]
SERVER_ADMIN
la dirección de correo electrónico del administrador del servidor web
SCRIPT_FILENAME
La ruta completa del script del servidor
SERVER_PROTOCOL
la versión del protocolo HTTP utilizada por el servidor web
REQUEST_METHOD
El método HTTP utilizado por el cliente: GET, POST, PUT, DELETE…
QUERY_STRING
Parámetros enviados en la URL: GET /url?parameters
REQUEST_URI
la URL solicitada por el cliente. Si el cliente solicita la URL [http://machine:port/uri], se tiene REQUEST_URI=/uri
SCRIPT_NAME
la ruta del script a partir de la raíz del servidor: [$_SERVER['SCRIPT_FILENAME']] = [$_SERVER['DOCUMENT_ROOT'] . $_SERVER['SCRIPT_NAME']]
REQUEST_TIME_FLOAT
la hora de la solicitud, en segundos desde el 1 de enero de 1970, con precisión de microsegundos

17.9. Obtención en el servidor de los parámetros enviados por un cliente

17.9.1. Introducción

En el protocolo HTTP, un cliente dispone de dos métodos para pasar parámetros al servidor web:

  • solicita la URL del servicio con la forma
GET url?param1=val1&param2=val2&param3=val3… HTTP/1.1

donde los valores [vali] deben codificarse primero para que ciertos caracteres reservados se reemplacen por sus valores hexadecimales;

  • solicita la URL del servicio con la forma
POST url HTTP/1.1

luego, entre los encabezados HTTP enviados al servidor, incluye el siguiente encabezado:

Content-Length: N

El resto de los encabezados enviados por el cliente termina con una línea en blanco. El cliente puede entonces enviar sus datos con la forma

param1=val1&param2=val2&param3=val3…

donde los valores [vali] deben, al igual que con el método GET, codificarse previamente. El número de bytes enviados al servidor debe ser N, donde N es el valor declarado en el encabezado [Content-Length].

El script PHP del servicio web que recupera los parámetros [parami] enviados por el cliente obtiene sus valores de los arreglos:

  • [$_GET['parami']] para los parámetros de la URL;
  • [$_POST['parami']] para los parámetros enviados en el documento de una orden POST;

Esto se aplica a las funciones básicas de PHP. Si se utiliza la biblioteca [HttpFoundation], estos parámetros se encuentran en:

  • [$request->query->get('parami')] para los parámetros de la URL;
  • [$request->request->get('parami')] para los parámetros del documento asociado a una orden POST;

donde [$request] es el objeto [Request] que representa toda la información de la solicitud recibida por el script web.

php8-oct-2026
├── scripts-console
│   └── web-clients
│       └── 05
│           ├── config-parameters-client.json
│           ├── config-spy.json
│           ├── parameters-get-client-2.php
│           ├── parameters-get-client.php
│           ├── parameters-mixed-get-client.php
│           ├── parameters-mixed-post-client.php
│           └── parameters-post-client.php
└── scripts-web
    └── 05
        ├── parameters-server-native.php
        └── parameters-server.php

17.9.2. El cliente GET: versión 1

Los scripts cliente se configuran mediante el siguiente archivo JSON [config-parameters-client.json]:

1
2
3
4
{
    "url-get": "http://localhost/php8-oct-2026/scripts-web/05/parameters-server.php",
    "url-post": "http://localhost/php8-oct-2026/scripts-web/05/parameters-server.php"
}
  • Línea 2: la URL del script web objetivo de los clientes GET;
  • Línea 3: la URL del script web objetivo de los clientes POST.

Los clientes envían al servidor tres parámetros [firstName, lastName, age]. El cliente [parameters-get-client.php] es el siguiente:

<?php

declare(strict_types=1);

// cliente GET de un servidor web - los parámetros los codifica el script

// dependencias
require_once __DIR__ . '/../../../vendor/autoload.php';

use Symfony\Component\HttpClient\HttpClient;
use Symfony\Contracts\HttpClient\Exception\ExceptionInterface;

// el archivo de configuración: 1.er argumento de la línea de comandos si existe
$configFileName = $argv[1] ?? "config-parameters-client.json";

// recuperamos la configuración
if (!file_exists($configFileName)) {
    print "The configuration file [$configFileName] does not exist\n";
    exit(1);
}
try {
    $config = json_decode(file_get_contents($configFileName), true, flags: JSON_THROW_ON_ERROR);
} catch (JsonException $ex) {
    print "Error while using the JSON configuration file [$configFileName]: {$ex->getMessage()}\n";
    exit(1);
}

// creamos un cliente HTTP
$httpClient = HttpClient::create();

try {
    // los parámetros que se enviarán
    [$firstName, $lastName, $age] = ["jean-paul", "de la hûche", 45];
    // codificamos los parámetros
    $parameters = "firstName=" . urlencode($firstName)
        . "&lastName=" . urlencode($lastName)
        . "&age=$age";
    // hacemos la solicitud
    $response = $httpClient->request("GET", $config["url-get"] . "?$parameters");
    // estado de la respuesta
    $statusCode = $response->getStatusCode();
    print "---Response with status: $statusCode\n";
    // recuperamos los encabezados
    print "---Headers of the response\n";
    foreach ($response->getHeaders() as $name => $values) {
        print "$name: $values[0]\n";
    }
    // mostramos la respuesta del servidor
    print "---Server response [{$response->getContent()}]\n";
} catch (ExceptionInterface $ex) {
    // mostramos el error
    print "Error communicating with the server: {$ex->getMessage()}\n";
    exit(2);
}

Comentarios

  • línea 14: al igual que en el cliente de fecha y hora, el nombre del archivo de configuración puede pasarse como argumento;
  • línea 33: los tres parámetros se asignan desempaquetando un arreglo;
  • Líneas 35–37: codificación de los parámetros enviados al servidor. Los parámetros [$firstName] y [$lastName], que pueden contener cualquier carácter, se codifican con la función [urlencode]: todos los caracteres distintos de las letras y los dígitos ASCII y de los caracteres [-_.] se reemplazan por [%xx], donde [xx] es el valor hexadecimal del byte; un carácter UTF-8 ([û]), codificado en dos bytes, se convierte entonces en [%C3%BB]. Los espacios se reemplazan por el carácter [+];
  • línea 39: la URL solicitada es [URL?parameters], donde [parameters] tiene la forma [firstName=val1&lastName=val2&age=val3];
  • línea 49: el cliente se limita a mostrar la respuesta del servidor.

Nota: la función [http_build_query] de PHP construye la misma cadena a partir de un arreglo asociativo: [http_build_query(["firstName" => $firstName, "lastName" => $lastName, "age" => $age])].

Tal vez le interese ver lo que recibe el servidor cuando se envía una solicitud GET configurada. Para ello, lanzamos nuestro servidor espía [spy-server.php] (sniffer) en el puerto 100, en una ventana de terminal abierta en el directorio [web-clients/02]:

php spy-server.php 100

El archivo [config-spy.json] designa este servidor para los clientes GET y POST:

1
2
3
4
{
    "url-get": "http://localhost:100/php8-oct-2026/scripts-web/05/parameters-server.php",
    "url-post": "http://localhost:100/php8-oct-2026/scripts-web/05/parameters-server.php"
}

Ejecutamos el cliente con el comando [php parameters-get-client.php config-spy.json]. El servidor espía muestra la siguiente información:

> php spy-server.php 100
Spy server waiting for a client on port 100
Client connected: 127.0.0.1:34944
--- lines received
GET /php8-oct-2026/scripts-web/05/parameters-server.php?firstName=jean-paul&lastName=de+la+h%C3%BBche&age=45 HTTP/1.1
Host: localhost:100
Accept: */*
User-Agent: Symfony HttpClient (Curl)
Accept-Encoding: gzip

--- end of the communication
  • Línea 5: la orden GET configurada enviada por el cliente. La codificación de ciertos caracteres se aprecia claramente.

17.9.3. El servidor GET / POST

El script del servidor [parameters-server.php] es el siguiente:

<?php

declare(strict_types=1);

// dependencias
require_once __DIR__ . '/../../vendor/autoload.php';

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

// recuperamos la solicitud
$request = Request::createFromGlobals();
// recuperamos los parámetros de la solicitud
$getParameters = $request->query->all();
$bodyParameters = $request->request->all();

// la respuesta: un arreglo codificado en JSON
$response = new Response(
    content: json_encode([
        "method" => $request->getMethod(),
        "uri" => $request->getRequestUri(),
        "getParameters" => $getParameters,
        "bodyParameters" => $bodyParameters,
    ], JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    headers: ['Content-Type' => 'application/json'],
);
$response->setCharset('UTF-8');
// envío de la respuesta
$response->send();

Comentarios

  • línea 12: creación del objeto [Request] del script web. Este objeto encapsula toda la información que el script web recibió del cliente;
  • Línea 14: el objeto [$request->query] es de tipo [InputBag] y contiene los parámetros de la URL. La expresión [$request->query->get('X')] recupera el parámetro llamado X de los parámetros [firstName=val1&lastName=val2&age=val3]. La expresión [$request->query->all()] recupera el arreglo con todos estos parámetros;
  • Línea 15: el objeto [$request->request], que también es de tipo [InputBag], reúne los parámetros enviados en el documento del cliente. También se dice que estos parámetros son "posteados". La expresión [$request->request->get('X')] devuelve el parámetro posteado llamado X, y la expresión [$request->request->all()] devuelve un arreglo con todos los parámetros posteados;
  • líneas 20–23: el servidor devuelve al cliente todos los parámetros que recibió, el método [GET / POST / …] utilizado por el cliente, obtenido mediante [$request->getMethod()], y la URI solicitada, obtenida mediante [$request->getRequestUri()]. El documento enviado al cliente es la cadena JSON de un arreglo asociativo, algunos de cuyos valores son a su vez arreglos asociativos. La opción [JSON_UNESCAPED_UNICODE] especifica que los caracteres Unicode (como los caracteres acentuados) se envíen tal cual y no codificados;
  • línea 25: se informa al cliente de que se enviará JSON;
  • Línea 29: la respuesta se envía al cliente.

La ejecución del script cliente [parameters-get-client.php] con su configuración predeterminada produce los siguientes resultados:

> php parameters-get-client.php
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: no-cache, private
connection: close
content-type: application/json
---Server response [{"method":"GET","uri":"/php8-oct-2026/scripts-web/05/parameters-server.php?firstName=jean-paul&lastName=de+la+h%C3%BBche&age=45","getParameters":{"firstName":"jean-paul","lastName":"de la hûche","age":"45"},"bodyParameters":[]}]
  • última línea:
    • [method]: el método es GET;
    • [uri]: los parámetros de la solicitud GET codificados en la URL son visibles en la URI solicitada;
    • [getParameters]: el arreglo de parámetros de la URL, decodificado por PHP;
    • [bodyParameters]: el arreglo de parámetros posteados; está vacío.

El servidor también puede probarse con [curl]. Las comillas alrededor de la URL son necesarias porque el carácter [&] tiene un significado especial para el intérprete de comandos:

> curl -i "http://localhost/php8-oct-2026/scripts-web/05/parameters-server.php?firstName=jean-paul&lastName=de+la+h%C3%BBche&age=45"
HTTP/1.0 200 OK
Date: Thu, 01 Oct 2026 15:31:46 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Cache-Control: no-cache, private
Connection: close
Content-Type: application/json

{"method":"GET","uri":"/php8-oct-2026/scripts-web/05/parameters-server.php?firstName=jean-paul&lastName=de+la+h%C3%BBche&age=45","getParameters":{"firstName":"jean-paul","lastName":"de la hûche","age":"45"},"bodyParameters":[]}

17.9.3.1. Una versión sin HttpFoundation

El script [parameters-server-native.php] realiza la misma tarea utilizando solo las funciones de PHP:

<?php

declare(strict_types=1);

// lo mismo que [parameters-server.php] solo con funciones propias de PHP

// un parámetro específico y filtrado: el parámetro GET [age] debe ser un entero
// filter_input devuelve null si el parámetro está ausente, false si es inválido
$age = filter_input(INPUT_GET, 'age', FILTER_VALIDATE_INT);

// la respuesta es JSON
header('Content-Type: application/json');
print json_encode([
    "method" => $_SERVER['REQUEST_METHOD'],
    "uri" => $_SERVER['REQUEST_URI'],
    "getParameters" => $_GET,
    "bodyParameters" => $_POST,
    "age" => $age,
], JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
  • Línea 8: los arreglos [$_GET] y [$_POST] contienen cadenas de caracteres, sea cual sea el tipo de valor esperado. La función [filter_input] lee un parámetro y lo valida: aquí, el parámetro [age] de la URL ([INPUT_GET]) debe ser un entero ([FILTER_VALIDATE_INT]). Devuelve el entero si el parámetro es válido, [false] si no lo es, y [null] si falta;
  • Línea 12: el encabezado [Content-Type] de la respuesta;
  • línea 14: el método HTTP de la solicitud;
  • línea 15: la URI solicitada;
  • líneas 16 y 17: los parámetros de la URL y los del documento.

Dos solicitudes realizadas con [curl]:

> curl "http://localhost/php8-oct-2026/scripts-web/05/parameters-server-native.php?firstName=jean-paul&age=45"
{"method":"GET","uri":"/php8-oct-2026/scripts-web/05/parameters-server-native.php?firstName=jean-paul&age=45","getParameters":{"firstName":"jean-paul","age":"45"},"bodyParameters":[],"age":45}
> curl -d firstName=jean-paul "http://localhost/php8-oct-2026/scripts-web/05/parameters-server-native.php?age=4x"
{"method":"POST","uri":"/php8-oct-2026/scripts-web/05/parameters-server-native.php?age=4x","getParameters":{"age":"4x"},"bodyParameters":{"firstName":"jean-paul"},"age":false}
  • En la primera solicitud, el parámetro [age] es [45]: se devuelve como el entero 45 y no como la cadena ["45"];
  • En la segunda solicitud, la opción [-d] hace que la solicitud se envíe como POST: el parámetro [firstName] está en [$_POST], mientras que el parámetro [age] de la URL está en [$_GET]. Su valor, [4x], no es un entero: [filter_input] devuelve [false].

En el resto de este curso utilizaremos [HttpFoundation], cuyo código es más coherente. Pero conviene entender lo que hay detrás.

17.9.4. El cliente GET: versión 2

En la versión anterior del script cliente, codificamos nosotros mismos en la URL los parámetros enviados al servidor, con fines didácticos. El objeto [HttpClient] puede encargarse de esta tarea por sí solo. Este es el script [parameters-get-client-2.php], idéntico al anterior salvo por las siguientes líneas:

try {
    // los parámetros que se enviarán
    [$firstName, $lastName, $age] = ["jean-paul", "de la hûche", 45];
    // hacemos la solicitud al servidor
    $response = $httpClient->request("GET", $config["url-get"], [
        // parámetros de la URL (query)
        "query" => [
            "firstName" => $firstName,
            "lastName" => $lastName,
            "age" => $age,
        ],
    ]);
  • líneas 37–41: el tercer parámetro del método [request] es un arreglo de opciones. La opción [query] es el arreglo de parámetros que se agregarán a la URL. El objeto [HttpClient] se encarga él mismo de su codificación.

Resultados:

> php parameters-get-client-2.php
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: no-cache, private
connection: close
content-type: application/json
---Server response [{"method":"GET","uri":"/php8-oct-2026/scripts-web/05/parameters-server.php?firstName=jean-paul&lastName=de%20la%20h%C3%BBche&age=45","getParameters":{"firstName":"jean-paul","lastName":"de la hûche","age":"45"},"bodyParameters":[]}]
  • Última línea: observe que [HttpClient] codificó los espacios con [%20] en lugar de [+]. PHP acepta ambas codificaciones.

17.9.5. El cliente POST

Un cliente HTTP envía al servidor web la siguiente secuencia de texto: encabezados HTTP, línea en blanco, documento. En el cliente anterior, esta secuencia era la siguiente:

1
2
3
GET /url?parameters HTTP/1.1
… other HTTP headers
empty line

No había documento. Existe otra forma de transmitir parámetros, conocida como el método POST. En este caso, la secuencia de texto enviada al servidor web es la siguiente:

1
2
3
4
POST /url HTTP/1.1
… other HTTP headers
empty line
parameters

Esta vez, los parámetros —que, en el cliente GET, se incluían en la primera línea de la solicitud— forman parte del documento enviado después de los encabezados en el cliente POST.

El script del cliente POST [parameters-post-client.php] difiere del cliente GET (versión 2) solo en las siguientes líneas:

try {
    // los parámetros que se enviarán
    [$firstName, $lastName, $age] = ["jean-paul", "de la hûche", 45];
    // hacemos la solicitud al servidor
    $response = $httpClient->request("POST", $config["url-post"], [
        // parámetros del documento (cuerpo)
        "body" => [
            "firstName" => $firstName,
            "lastName" => $lastName,
            "age" => $age,
        ],
    ]);
  • línea 35: ahora se tiene una solicitud HTTP de tipo POST;
  • líneas 37–41: la opción [body] es el cuerpo de la solicitud POST: es el documento que el cliente envía al servidor. Cuando esta opción es un arreglo, [HttpClient] lo codifica en la URL y agrega el encabezado [Content-Type: application/x-www-form-urlencoded]. Aquí se envían tres parámetros: [firstName, lastName, age].

Los resultados de la ejecución del script cliente son los siguientes:

> php parameters-post-client.php
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: no-cache, private
connection: close
content-type: application/json
---Server response [{"method":"POST","uri":"/php8-oct-2026/scripts-web/05/parameters-server.php","getParameters":[],"bodyParameters":{"firstName":"jean-paul","lastName":"de la hûche","age":"45"}}]
  • Última línea: el método es [POST] y los parámetros son de tipo [bodyParameters]. No hay parámetros [getParameters], como lo muestra [uri].

Con [curl], la opción [-d] envía un parámetro mediante una solicitud POST, y la opción [--data-urlencode] hace lo mismo codificando su valor en la URL:

> curl -i -d firstName=jean-paul --data-urlencode "lastName=de la hûche" -d age=45 http://localhost/php8-oct-2026/scripts-web/05/parameters-server.php
HTTP/1.0 200 OK
Date: Thu, 01 Oct 2026 15:31:46 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Cache-Control: no-cache, private
Connection: close
Content-Type: application/json

{"method":"POST","uri":"/php8-oct-2026/scripts-web/05/parameters-server.php","getParameters":[],"bodyParameters":{"firstName":"jean-paul","lastName":"de la hûche","age":"45"}}

Veamos lo que recibe el servidor durante una solicitud POST. Reiniciamos el servidor espía en el puerto 100 y ejecutamos el cliente con el comando [php parameters-post-client.php config-spy.json]. El servidor espía muestra la siguiente información:

> php spy-server.php 100
Spy server waiting for a client on port 100
Client connected: 127.0.0.1:34950
--- lines received
POST /php8-oct-2026/scripts-web/05/parameters-server.php HTTP/1.1
Host: localhost:100
Accept: */*
Content-Type: application/x-www-form-urlencoded
User-Agent: Symfony HttpClient (Curl)
Accept-Encoding: gzip
Content-Length: 52

firstName=jean-paul&lastName=de+la+h%C3%BBche&age=45
--- end of the communication
  • Línea 5: la orden POST;
  • línea 8: el encabezado HTTP [Content-Type] especifica el tipo de documento enviado por el cliente. El tipo [application/x-www-form-urlencoded] designa un texto codificado en la URL;
  • línea 11: el encabezado HTTP [Content-Length] especifica el número de bytes del documento que el cliente enviará al servidor;
  • línea 12: la línea vacía que marca el final de los encabezados HTTP y el comienzo del documento de 52 bytes;
  • línea 13: el documento: la cadena de parámetros codificada en la URL. El lector puede verificar que, en efecto, tiene 52 caracteres.

17.9.6. Un cliente POST mixto

En un POST, es posible combinar parámetros codificados en la URL con parámetros codificados en el documento que el cliente envía después de los encabezados HTTP. Este es un ejemplo de [parameters-mixed-post-client.php]:

try {
    // los parámetros que se enviarán
    [$firstName, $lastName, $age] = ["jean-paul", "de la hûche", 45];
    // hacemos la solicitud al servidor
    $response = $httpClient->request("POST", $config["url-post"], [
        // parámetros del documento (cuerpo)
        "body" => [
            "firstName" => $firstName,
            "lastName" => $lastName,
            "age" => $age,
        ],
        // parámetros de la URL (query)
        "query" => [
            "firstName2" => $firstName,
            "lastName2" => $lastName,
            "age2" => $age,
        ],
    ]);

Comentarios

  • línea 35: una solicitud POST;
  • líneas 37–41: los parámetros codificados en la URL en el cuerpo (documento) de la solicitud;
  • líneas 43–47: los parámetros codificados en la URL en la propia URL.

Al ejecutarlo, se genera la siguiente salida en la consola:

> php parameters-mixed-post-client.php
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: no-cache, private
connection: close
content-type: application/json
---Server response [{"method":"POST","uri":"/php8-oct-2026/scripts-web/05/parameters-server.php?firstName2=jean-paul&lastName2=de%20la%20h%C3%BBche&age2=45","getParameters":{"firstName2":"jean-paul","lastName2":"de la hûche","age2":"45"},"bodyParameters":{"firstName":"jean-paul","lastName":"de la hûche","age":"45"}}]
  • Última línea: se observa que el servidor pudo recuperar ambos tipos de parámetros.

17.9.7. Un cliente GET mixto

Intentaremos hacer lo mismo con una solicitud GET. El script [parameters-mixed-get-client.php] difiere del anterior solo en su método:

    // hacemos la solicitud al servidor
    $response = $httpClient->request("GET", $config["url-get"], [

Al ejecutarlo, obtenemos la siguiente salida en la consola:

> php parameters-mixed-get-client.php
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: no-cache, private
connection: close
content-type: application/json
---Server response [{"method":"GET","uri":"/php8-oct-2026/scripts-web/05/parameters-server.php?firstName2=jean-paul&lastName2=de%20la%20h%C3%BBche&age2=45","getParameters":{"firstName2":"jean-paul","lastName2":"de la hûche","age2":"45"},"bodyParameters":[]}]
  • Última línea: se observa que el servidor no procesó los parámetros codificados en la URL del documento enviado por el cliente.

Sin embargo, el sniffer del servidor muestra que el cliente sí envió un documento de 52 bytes:

> php spy-server.php 100
Spy server waiting for a client on port 100
Client connected: 127.0.0.1:34952
--- lines received
GET /php8-oct-2026/scripts-web/05/parameters-server.php?firstName2=jean-paul&lastName2=de%20la%20h%C3%BBche&age2=45 HTTP/1.1
Host: localhost:100
Accept: */*
Content-Type: application/x-www-form-urlencoded
User-Agent: Symfony HttpClient (Curl)
Accept-Encoding: gzip
Content-Length: 52

firstName=jean-paul&lastName=de+la+h%C3%BBche&age=45
--- end of the communication

PHP solo llena el arreglo [$_POST] (y, por lo tanto, [HttpFoundation] y el objeto [$request->request]) a partir del documento de una solicitud POST. El documento de una solicitud GET se ignora.

Por último, ¿qué método debe utilizarse para enviar información al servidor?

  • El método [GET URL?param1=val1&param2=val2&…] utiliza una URL configurada que puede servir como enlace. Esta es su principal ventaja: el usuario puede agregar tales enlaces a sus marcadores. Está pensado para solicitudes que leen datos sin modificar nada en el servidor;
  • en otras aplicaciones, puede que no se quiera mostrar en una URL los parámetros enviados al servidor. Por razones de seguridad, por ejemplo: las URL se almacenan en el historial del navegador y en los archivos de registro del servidor. En tales casos, se utiliza un método [POST] y se incluyen los parámetros codificados en la URL en el documento enviado al servidor. Este es también el método que debe utilizarse para las solicitudes que modifican datos en el servidor.

17.10. Gestión de sesiones web

En los ejemplos cliente/servidor anteriores, el proceso funcionaba así:

  • el cliente abre una conexión con el puerto 80 del servidor web;
  • envía la siguiente secuencia de texto: encabezados HTTP, una línea vacía, [document];
  • en respuesta, el servidor envía una secuencia del mismo tipo;
  • el servidor cierra la conexión con el cliente;
  • el cliente cierra la conexión con el servidor.

Si el mismo cliente hace una nueva solicitud al servidor web poco después, se establece una nueva conexión entre el cliente y el servidor. El servidor no puede saber si el cliente que se conecta ya lo había visitado o si es su primera solicitud. Entre una conexión y otra, el servidor "olvida" a su cliente. Por esta razón se dice que el protocolo HTTP es un protocolo sin estado. Sin embargo, resulta útil que el servidor recuerde a sus clientes. Por ejemplo, si una aplicación es segura, el cliente enviará al servidor un nombre de usuario y una contraseña para autenticarse. Si el servidor "olvidara" a su cliente entre conexiones, este tendría que autenticarse en cada nueva conexión, lo cual no es viable.

Para dar seguimiento a un cliente, el servidor procede de la siguiente manera: cuando un cliente hace su primera solicitud, el servidor incluye en su respuesta un identificador, que el cliente debe enviar de vuelta en cada solicitud posterior. Gracias a este identificador, único para cada cliente, el servidor puede reconocerlo. Entonces puede mantener un registro de ese cliente en forma de una entrada en memoria asociada de manera exclusiva al identificador del cliente.

Técnicamente, funciona así:

  • en la respuesta a un cliente nuevo, el servidor incluye el encabezado HTTP [Set-Cookie: Keyword=Identifier]. Lo hace solo en la primera solicitud;
  • en las solicitudes posteriores, el cliente enviará su identificador mediante el encabezado HTTP [Cookie: Keyword=Identifier] para que el servidor pueda reconocerlo.

Cabe preguntarse cómo sabe el servidor que se trata de un cliente nuevo y no de uno que regresa. Lo indica la presencia del encabezado HTTP [Cookie] en los encabezados HTTP del cliente. En un cliente nuevo, este encabezado no existe.

Todas las conexiones realizadas por un mismo cliente se denominan una sesión.

php8-oct-2026
├── scripts-console
│   └── web-clients
│       └── 06
│           ├── config-session-client-07.json
│           ├── config-session-client-native.json
│           ├── config-session-client.json
│           └── session-client.php
└── scripts-web
    ├── 06
    │   ├── phpinfo.php
    │   ├── session-config.php
    │   ├── session-server-native.php
    │   └── session-server.php
    └── 07
        ├── Person.php
        └── session-server.php

17.10.1. El archivo de configuración [php.ini]

Para que la gestión de sesiones funcione correctamente con PHP, debe verificarse que esté bien configurada. Su archivo de configuración es [php.ini]. Según el contexto de ejecución (consola, web), el archivo de configuración [php.ini] utilizado puede variar. Para determinar cuál se utiliza, ejecute el siguiente script [phpinfo.php]:

1
2
3
4
5
6
<?php

declare(strict_types=1);

// información sobre el intérprete PHP que ejecuta el script
phpinfo();

La función [phpinfo] proporciona información sobre el intérprete de PHP que ejecuta el script. En particular, en la línea [Loaded Configuration File], indica la ruta del archivo de configuración [php.ini] en uso. Ya utilizamos esta función en un entorno de consola al instalar PHP. En un entorno web, basta con solicitar la URL [http://localhost/php8-oct-2026/scripts-web/06/phpinfo.php] con un navegador. Con [Laragon], el [php.ini] utilizado por el servidor [Apache] es el de la carpeta de la versión de PHP seleccionada ([<laragon>/bin/php/<version>/php.ini]). Puede abrirse desde el menú de [Laragon]: [PHP / php.ini].

Este archivo contiene una sección llamada [Session]. En lugar de copiarla, el siguiente script, [session-config.php], muestra los valores reales de las directivas que nos interesan:

<?php

declare(strict_types=1);

// la configuración de sesión del intérprete PHP del servidor web
$config = ini_get_all('session', details: false);
// mostramos solo las directivas presentadas en el curso
$keys = [
    'session.save_handler', 'session.save_path', 'session.use_strict_mode',
    'session.use_cookies', 'session.use_only_cookies', 'session.name',
    'session.auto_start', 'session.cookie_lifetime', 'session.cookie_path',
    'session.cookie_domain', 'session.cookie_httponly', 'session.cookie_samesite',
    'session.serialize_handler', 'session.gc_probability', 'session.gc_divisor',
    'session.gc_maxlifetime', 'session.cache_limiter', 'session.cache_expire',
    'session.use_trans_sid',
];
header('Content-Type: text/plain; charset=UTF-8');
foreach ($keys as $key) {
    print "$key = " . var_export($config[$key], true) . "\n";
}
  • Línea 6: la función [ini_get_all] devuelve los valores de las directivas de configuración de una extensión de PHP; en este caso, la extensión [session]. Con [details: false], se obtiene un arreglo [directive => value];
  • línea 19: la función [var_export] muestra un valor en forma de expresión PHP. Así, una cadena vacía aparece como [''].

Resultado:

> curl http://localhost/php8-oct-2026/scripts-web/06/session-config.php
session.save_handler = 'files'
session.save_path = ''
session.use_strict_mode = '0'
session.use_cookies = '1'
session.use_only_cookies = '1'
session.name = 'PHPSESSID'
session.auto_start = '0'
session.cookie_lifetime = '0'
session.cookie_path = '/'
session.cookie_domain = ''
session.cookie_httponly = '0'
session.cookie_samesite = ''
session.serialize_handler = 'php'
session.gc_probability = '1'
session.gc_divisor = '100'
session.gc_maxlifetime = '1440'
session.cache_limiter = 'nocache'
session.cache_expire = '180'
session.use_trans_sid = '0'
  • Línea 2: los datos de la sesión de un cliente se guardan en un archivo;
  • Línea 3: la carpeta donde se guardan los datos de sesión. Si está vacía, se refiere a la carpeta temporal del sistema. En la configuración de [Laragon], se refiere a una carpeta llamada [Laragon] (con la forma [<laragon>/tmp]). Si esta carpeta no existe, la gestión de sesiones no funcionará;
  • línea 4: en modo estricto, el servidor rechaza cualquier identificador de sesión que no haya creado él mismo. Es una salvaguarda contra los llamados ataques de fijación de sesión. Se recomienda activarlo;
  • Líneas 5–6: indican que el identificador de sesión se gestiona únicamente mediante los encabezados HTTP, [Set-Cookie], y [Cookie];
  • línea 7: el encabezado [Set-Cookie] tendrá la forma [Set-Cookie: PHPSESSID=session_id];
  • Línea 8: la sesión de un cliente no se inicia automáticamente. El script del servidor debe solicitarla explícitamente mediante el comando [session_start()];
  • línea 9: la cookie de sesión es válida hasta que se cierre el navegador del cliente;
  • línea 10: la ruta para la cual debe devolverse la cookie de sesión. Si [session.cookie_path = /xxx], cada vez que el navegador solicite una URL del tipo [/xxx/yyy/zzz], debe devolver la cookie. Aquí, la ruta [/] indica que la cookie debe devolverse para cualquier URL del sitio;
  • Líneas 12–13: el atributo [HttpOnly] de la cookie la hace inaccesible para el código JavaScript de la página; el atributo [SameSite] impide que se envíe en respuesta a solicitudes provenientes de otros sitios. Estos dos atributos protegen el identificador de sesión;
  • línea 14: los objetos de la sesión deben serializarse para almacenarse en un archivo. PHP se encarga de esta serialización y deserialización;
  • Líneas 15–17: cada vez que se inicia una sesión, PHP lanza, con probabilidad [gc_probability / gc_divisor], una limpieza de los archivos de sesión con más de [gc_maxlifetime] segundos de antigüedad: las sesiones inactivas durante más tiempo se pierden.

Nota: la sección [Session] del [php.ini] de 2019 contenía la directiva [session.sid_bits_per_character = 5]. Las directivas [session.sid_length] y [session.sid_bits_per_character], que especificaban la longitud y el juego de caracteres del identificador de sesión, están obsoletas desde PHP 8.4: PHP ahora utiliza identificadores hexadecimales de 32 caracteres, que son suficientemente seguros. Estas directivas ya no deben utilizarse.

Todos estos ajustes también pueden configurarse desde el propio script al iniciar la sesión, como veremos más adelante.

17.10.2. Ejemplo 1

17.10.2.1. El servidor

La gestión del identificador de sesión es transparente para un servicio web. PHP administra este identificador. Un servicio web accede a la sesión del cliente mediante la instrucción [session_start()]. A partir de ese momento, el servicio web puede leer y escribir en la sesión del cliente a través del arreglo [$_SESSION]. Si se utiliza la biblioteca [HttpFoundation], la sesión está representada por un objeto de tipo [Session].

El siguiente código, [session-server.php], muestra la gestión basada en sesiones de tres contadores. En cada nueva solicitud, el script web incrementa estos contadores y los almacena en la sesión para recuperarlos en la siguiente solicitud.

<?php

declare(strict_types=1);

// dependencias
require_once __DIR__ . '/../../vendor/autoload.php';

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\Session\Session;

// la sesión del cliente
$session = new Session();
$session->start();
// gestionamos tres contadores en la sesión
if ($session->has("N1")) {
    // incremento del contador N1
    $session->set("N1", $session->get("N1") + 1);
} else {
    // el contador N1 no está en la sesión - lo creamos
    $session->set("N1", 0);
}
if ($session->has("N2")) {
    // incremento del contador N2
    $session->set("N2", $session->get("N2") + 1);
} else {
    // el contador N2 no está en la sesión - lo creamos
    $session->set("N2", 10);
}
if ($session->has("N3")) {
    // incremento del contador N3
    $session->set("N3", $session->get("N3") + 1);
} else {
    // el contador N3 no está en la sesión - lo creamos
    $session->set("N3", 100);
}
// la respuesta es el JSON de un arreglo que contiene los tres contadores
$response = new Response(
    content: json_encode([
        "N1" => $session->get("N1"),
        "N2" => $session->get("N2"),
        "N3" => $session->get("N3"),
    ], JSON_THROW_ON_ERROR),
    headers: ['Content-Type' => 'application/json'],
);
$response->setCharset('UTF-8');

// envío de la respuesta
$response->send();
  • Líneas 12–13: se crea y se activa una sesión. El objeto [Session] encapsula los datos de sesión correspondientes a la cookie de sesión enviada por el cliente. Si el cliente no envió dicha cookie, no hay datos almacenados en [Session]. El script web incluirá el encabezado HTTP [Set-Cookie: PHPSESSID=xxx] en su primera respuesta. En las solicitudes posteriores, el cliente enviará los encabezados HTTP y [Cookie: PHPSESSID=xxx] para indicar la sesión cuyo contenido desea utilizar. Una sesión es la memoria de un cliente;
  • Líneas 15–20: verificamos si la sesión tiene una clave llamada [N1]. Este será el nombre de nuestro primer contador. Si no existe, le asignamos el valor 0 y lo almacenamos en la sesión. Si existe, hacemos lo siguiente:
    • lo recuperamos de la sesión;
    • incrementamos su valor en 1;
    • lo volvemos a colocar en la sesión;
  • líneas 22–34: hacemos lo mismo con los otros dos contadores, N2 y N3;
  • líneas 37–44: la respuesta será la cadena JSON, que es un arreglo con los tres contadores;
  • línea 48: la respuesta se envía al cliente. Al final del script, PHP guarda los datos de la sesión en el archivo de sesión.

En la relación cliente-servidor, la gestión de la sesión del cliente en el servidor depende de ambas partes, el cliente y el servidor:

  • el servidor es responsable de enviar un identificador al cliente en su primera solicitud;
  • el cliente es responsable de devolver este identificador en cada nueva solicitud. Si no lo hace, el servidor supondrá que se trata de un cliente nuevo y generará un nuevo identificador para una nueva sesión.

Resultados

Utilizamos un navegador web como cliente. De forma predeterminada, el navegador devuelve efectivamente al servidor los identificadores de sesión que este le envía. A medida que se hacen solicitudes, el navegador recibirá los tres contadores enviados por el servidor y verá cómo sus valores se incrementan. La primera solicitud produce:

Image

Después de recargar la página tres veces (F5), obtenemos:

Image

La cuarta solicitud muestra que los contadores, en efecto, se han incrementado. Los valores de los contadores se conservan realmente de una solicitud a otra.

Las herramientas para desarrolladores del navegador (F12, pestaña [Network]) muestran los encabezados HTTP intercambiados. Examinémoslos con [curl]. Con la opción [-c cookies.txt], [curl] guarda las cookies recibidas del servidor en el archivo [cookies.txt]; con la opción [-b cookies.txt], devuelve al servidor las cookies de este archivo. De este modo se comporta como un navegador. Primera solicitud:

> curl -i -c cookies.txt -b cookies.txt http://localhost/php8-oct-2026/scripts-web/06/session-server.php
HTTP/1.0 200 OK
Date: Thu, 01 Oct 2026 15:31:46 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: PHPSESSID=403de000aa6b2ee9ad770f2a00ffb773; path=/
Cache-Control: no-cache, private
Connection: close
Content-Type: application/json

{"N1":0,"N2":10,"N3":100}
  • El encabezado [Set-Cookie] contiene el identificador de sesión enviado por el servidor en su respuesta a la primera solicitud del cliente;
  • el primer encabezado, [Cache-Control], lo establece [HttpFoundation] al inicio de la sesión: la respuesta, específica de este cliente, no debe ser almacenada en caché por un intermediario ([private]) y debe solicitarse de nuevo al servidor ([max-age=0]);
  • la última línea contiene los tres contadores inicializados.

El archivo [cookies.txt] ahora contiene la cookie de sesión:

1
2
3
4
5
6
> type cookies.txt
# Netscape HTTP Cookie File
# https://curl.se/docs/http-cookies.html
# This file was generated by libcurl! Edit at your own risk.

localhost    FALSE    /    FALSE    0    PHPSESSID    403de000aa6b2ee9ad770f2a00ffb773

2.ª solicitud:

> curl -i -c cookies.txt -b cookies.txt http://localhost/php8-oct-2026/scripts-web/06/session-server.php
HTTP/1.0 200 OK
Date: Thu, 01 Oct 2026 15:31:46 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Cache-Control: max-age=0, private, must-revalidate
Cache-Control: no-cache, private
Connection: close
Content-Type: application/json

{"N1":1,"N2":11,"N3":101}
  • [curl] devolvió el identificador de sesión con el encabezado HTTP [Cookie: PHPSESSID=…];
  • En su respuesta, el servicio web ya no incluye el encabezado [Set-Cookie]. A partir de ahora, es responsabilidad del cliente enviar el identificador en cada una de sus solicitudes;
  • Última línea: los contadores se han incrementado.

17.10.2.2. El cliente

Ahora escribimos un script cliente basado en el script de servidor anterior. En la gestión de la sesión, debe comportarse como un navegador web:

  • en la respuesta del servidor a su primera solicitud, debe encontrar el identificador de sesión que el servidor le envía. Sabe que lo encontrará en el encabezado HTTP [Set-Cookie];
  • en cada solicitud posterior, debe devolver al servidor el identificador de sesión que recibió. Lo hará mediante el encabezado HTTP [Cookie].

El cliente [session-client.php] se configura mediante el siguiente archivo JSON [config-session-client.json]:

1
2
3
{
    "url": "http://localhost/php8-oct-2026/scripts-web/06/session-server.php"
}

El código del cliente [session-client.php] es el siguiente:

<?php

declare(strict_types=1);

// cliente de un servicio web con sesión

// dependencias
require_once __DIR__ . '/../../../vendor/autoload.php';

use Symfony\Component\HttpClient\HttpClient;
use Symfony\Contracts\HttpClient\Exception\ExceptionInterface;

// el archivo de configuración: 1.er argumento de la línea de comandos si existe
$configFileName = $argv[1] ?? "config-session-client.json";

// recuperamos la configuración
if (!file_exists($configFileName)) {
    print "The configuration file [$configFileName] does not exist\n";
    exit(1);
}
try {
    $config = json_decode(file_get_contents($configFileName), true, flags: JSON_THROW_ON_ERROR);
} catch (JsonException $ex) {
    print "Error while using the JSON configuration file [$configFileName]: {$ex->getMessage()}\n";
    exit(1);
}

// creamos un cliente HTTP
$httpClient = HttpClient::create();
// la cookie de sesión (aún desconocida)
$sessionCookie = null;
try {
    // vamos a hacer 10 solicitudes
    for ($i = 0; $i < 10; $i++) {
        // hacemos la solicitud al servidor
        if ($sessionCookie === null) {
            // sin cookie de sesión
            $response = $httpClient->request('GET', $config['url']);
        } else {
            // con la cookie de sesión
            $response = $httpClient->request('GET', $config['url'], [
                'headers' => ['Cookie' => $sessionCookie],
            ]);
        }
        // estado de la respuesta
        $statusCode = $response->getStatusCode();
        print "---Response with status: $statusCode\n";
        // recuperamos los encabezados
        print "---Headers of the response\n";
        $headers = $response->getHeaders();
        foreach ($headers as $name => $values) {
            print "$name: $values[0]\n";
        }
        // buscamos la cookie de sesión entre los encabezados [Set-Cookie]
        foreach ($headers['set-cookie'] ?? [] as $cookie) {
            if (preg_match('/^PHPSESSID=(.+?);/', $cookie, $fields)) {
                $sessionCookie = "PHPSESSID=$fields[1]";
            }
        }
    }
    // mostramos la última respuesta JSON del servidor
    print "---Server response: {$response->getContent()}\n";
} catch (ExceptionInterface $ex) {
    // mostramos el error
    print "Error communicating with the server: {$ex->getMessage()}\n";
    exit(2);
}

Comentarios

  • línea 29: creación del cliente HTTP;
  • línea 31: la variable [$sessionCookie] contendrá la cookie de sesión, con la forma [PHPSESSID=xxx]. Su valor es [null] hasta que el servidor la envíe;
  • línea 34: enviaremos 10 veces la misma solicitud al servidor: [session-server.php];
  • líneas 36–38: si la cookie de sesión aún no se conoce, enviamos la orden [GET] sin el encabezado [Cookie];
  • líneas 39–43: en caso contrario, enviamos la orden [GET] con el encabezado [Cookie]. La opción [headers] del método [request] es el arreglo de encabezados HTTP que se agregarán a la solicitud;
  • Línea 55: el servidor web puede enviar varios encabezados [Set-Cookie]. La cookie de sesión es solo uno de ellos. Tiene el formato exclusivo [PHPSESSID=xxx; …]. Si la respuesta no tiene un encabezado [Set-Cookie], la expresión [$headers['set-cookie'] ?? []] devuelve un arreglo vacío y el bucle no hace nada;
  • línea 56: se utiliza una expresión regular para encontrar la cookie de sesión;
  • línea 62: una vez realizadas las 10 solicitudes, se muestra la última respuesta del servidor, JSON.

Nota: el cliente Symfony [HttpClient] no gestiona por sí solo las cookies de una solicitud a otra, por lo que se incluye este código. La gestión de la cookie de sesión se tratará en las versiones de la aplicación de cálculo del impuesto que utilizan una sesión.

Resultados

La ejecución del script cliente produce la siguiente salida (mostramos solo el principio y el final):

> php session-client.php
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: max-age=0, private, must-revalidate
set-cookie: PHPSESSID=2dd2d2c53266ff4fb3eff4b943564f74; path=/
connection: close
content-type: application/json
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: max-age=0, private, must-revalidate
connection: close
content-type: application/json
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: max-age=0, private, must-revalidate
connection: close
content-type: application/json
---Server response: {"N1":9,"N2":19,"N3":109}
  • En su primera respuesta, el servidor envía el identificador de sesión (encabezado [set-cookie]). En las respuestas posteriores, ya no lo envía;
  • Última línea: los tres contadores [N1, N2, N3] se incrementaron efectivamente 9 veces. Se inicializaron durante la solicitud n.º 1.

17.10.2.3. Una versión sin HttpFoundation

El script [session-server-native.php] realiza la misma tarea utilizando solo las funciones de PHP:

<?php

declare(strict_types=1);

// lo mismo que [session-server.php] solo con funciones propias de PHP

// inicio de la sesión - las opciones reemplazan las directivas [session.*] de php.ini
session_start([
    // rechazamos un id de sesión que el servidor no haya creado él mismo
    'use_strict_mode' => true,
    // el JavaScript del navegador no puede acceder a la cookie de sesión
    'cookie_httponly' => true,
    // la cookie no se envía con las solicitudes provenientes de otros sitios
    'cookie_samesite' => 'Lax',
]);
// los tres contadores y sus valores iniciales
foreach (["N1" => 0, "N2" => 10, "N3" => 100] as $counter => $initialValue) {
    // el contador se incrementa si está en la sesión; de lo contrario, se crea
    $_SESSION[$counter] = isset($_SESSION[$counter]) ? $_SESSION[$counter] + 1 : $initialValue;
}
// la respuesta es el JSON de un arreglo que contiene los tres contadores
header('Content-Type: application/json');
print json_encode([
    "N1" => $_SESSION["N1"],
    "N2" => $_SESSION["N2"],
    "N3" => $_SESSION["N3"],
], JSON_THROW_ON_ERROR);
  • Líneas 8–15: inicio de la sesión. A partir de PHP 7.0, la función [session_start] acepta un arreglo de opciones: son las directivas [session.*] del archivo [php.ini], sin su prefijo [session.]. Se aplican solo a la solicitud actual. Aquí activamos el modo estricto y los atributos [HttpOnly] y [SameSite] de la cookie de sesión, como se describió en la sección sobre el archivo [php.ini];
  • líneas 17–19: recorremos el arreglo [counter => initial value]. Para cada contador, lo incrementamos si está en la sesión [$_SESSION]; de lo contrario, lo agregamos a la sesión con su valor inicial;
  • línea 22: el encabezado [Content-Type] de la respuesta;
  • línea 23: el documento JSON enviado al cliente.

Ejecutamos el mismo cliente con la configuración [config-session-client-native.json], que hace referencia a este script: [php session-client.php config-session-client-native.json]. Inicio de la salida:

> php session-client.php config-session-client-native.json
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
set-cookie: PHPSESSID=f2bf0d3a4e234d04ccc9e8900a2f83be; path=/; HttpOnly; SameSite=Lax
expires: Thu, 19 Nov 1981 08:52:00 GMT
cache-control: no-store, no-cache, must-revalidate
pragma: no-cache
content-length: 25
content-type: application/json
  • La cookie de sesión ahora tiene los atributos [HttpOnly] y [SameSite=Lax];
  • Los encabezados [Expires], [Cache-Control] y [Pragma], establecidos por PHP al inicio de la sesión, impiden que la respuesta se almacene en caché (directiva [session.cache_limiter = nocache]).

La última línea mostrada es la misma que antes:

---Server response: {"N1":9,"N2":19,"N3":109}

17.10.3. Ejemplo 2

17.10.3.1. El servidor

El siguiente ejemplo muestra que también se pueden guardar en la sesión los valores de un arreglo o de un objeto. Colocaremos un objeto [Person] en la sesión. La clase [Person] de la carpeta [scripts-web/07] es la misma que la del ejemplo JSON de la carpeta [scripts-web/03].

El script del servidor [session-server.php] de la carpeta [scripts-web/07] es el siguiente:

<?php

declare(strict_types=1);

// dependencias
require_once __DIR__ . '/../../vendor/autoload.php';
// la clase [Person] debe ser conocida ANTES de que inicie la sesión
require_once __DIR__ . '/Person.php';

use Models\Person;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\Session\Session;

// la sesión del cliente
$session = new Session();
$session->start();

// gestionamos datos diversos en la sesión
// un arreglo
if ($session->has("array")) {
    // el arreglo está en la sesión - incrementamos todos sus valores
    $array = array_map(fn(int $value): int => $value + 1, $session->get("array"));
} else {
    // el arreglo no está en la sesión - lo creamos
    $array = [0, 10, 100];
}
// ponemos el arreglo en la sesión
$session->set("array", $array);

// un diccionario
if ($session->has("assoc")) {
    // [assoc] está en la sesión - incrementamos todos sus elementos
    $assoc = $session->get("assoc");
    foreach ($assoc as $key => $value) {
        $assoc[$key] = $value + 1;
    }
} else {
    // [assoc] no está en la sesión - lo creamos
    $assoc = ["one" => 0, "two" => 10, "three" => 100];
}
// ponemos [assoc] en la sesión
$session->set("assoc", $assoc);

// un objeto Person
if ($session->has("person")) {
    // [person] está en la sesión - incrementamos su edad
    $person = $session->get("person");
    $person->setAge($person->age + 1);
} else {
    // [person] no está en la sesión - lo creamos
    $person = new Person(firstName: "Léonard", lastName: "Hûche", age: 0);
    // ponemos [person] en la sesión
    $session->set("person", $person);
}

// la respuesta es JSON
$response = new Response(
    content: json_encode([
        "array" => $array,
        "assoc" => $assoc,
        "person" => $person,
    ], JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE),
    headers: ['Content-Type' => 'application/json'],
);
$response->setCharset('UTF-8');

// envío de la respuesta
$response->send();

Comentarios

  • línea 8: la clase [Person] debe cargarse antes de que se inicie la sesión: al iniciarse, PHP deserializa los objetos colocados en la sesión durante solicitudes anteriores y, por lo tanto, debe conocer su clase;
  • Líneas 15–16: se recupera y se activa la sesión actual;
  • Líneas 20–28: gestionamos un arreglo [array] que se ha colocado en la sesión. En cada nueva solicitud, sus elementos se incrementan en 1. La función [array_map] aplica una función a cada elemento de un arreglo y devuelve el arreglo de resultados. La función aquí es una función flecha, introducida con PHP 7.4: [fn(int $value): int => $value + 1];
  • líneas 31–42: gestionamos un arreglo asociativo [assoc] que está en el ámbito de la sesión. En cada nueva solicitud, sus elementos se incrementan en 1;
  • líneas 45–53: gestionamos un objeto [Person] en el ámbito de la sesión. En cada nueva solicitud, la edad de esta persona se incrementa en 1. Observe que no es necesario volver a colocar el objeto en la sesión después de modificarlo: la sesión contiene una referencia a este objeto, y es el objeto modificado el que se guardará al final del script;
  • Líneas 57–64: enviamos una respuesta JSON al cliente: la cadena JSON de un arreglo asociativo.

Solicitemos este script con un navegador. Las dos primeras solicitudes devuelven los siguientes resultados (F5 en el navegador para la segunda):

Image

Image

Vemos que, en la segunda solicitud, todos los contadores se han incrementado.

17.10.3.2. El cliente

El cliente es el mismo que en el Ejemplo 1. Solo le proporcionamos el archivo de configuración [config-session-client-07.json]:

1
2
3
{
    "url": "http://localhost/php8-oct-2026/scripts-web/07/session-server.php"
}

La ejecución del comando [php session-client.php config-session-client-07.json] produce los siguientes resultados (inicio y final):

> php session-client.php config-session-client-07.json
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: max-age=0, private, must-revalidate
set-cookie: PHPSESSID=f5aad2acfda0f0a514b4134ffdc9e066; path=/
connection: close
content-type: application/json
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: max-age=0, private, must-revalidate
connection: close
content-type: application/json
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: max-age=0, private, must-revalidate
connection: close
content-type: application/json
---Server response: {"array":[9,19,109],"assoc":{"one":9,"two":19,"three":109},"person":{"lastName":"Hûche","firstName":"Léonard","age":9}}
  • Última línea: vemos que todos los contadores se han incrementado 9 veces.

17.11. Autenticación

Ahora nos centraremos en los servicios web destinados únicamente a usuarios específicos. El cliente debe autenticarse ante el servicio web antes de recibir una respuesta.

php8-oct-2026
├── scripts-console
│   └── web-clients
│       └── 08
│           ├── auth-client.php
│           ├── config-auth-client-https.json
│           ├── config-auth-client-https-verify.json
│           ├── config-auth-client-ko.json
│           ├── config-auth-client.json
│           └── config-spy.json
└── scripts-web
    └── 08
        └── auth-server.php

17.11.1. El cliente

El cliente [auth-client.php] se configura mediante el siguiente archivo JSON [config-auth-client.json]:

1
2
3
4
5
{
    "url": "http://localhost/php8-oct-2026/scripts-web/08/auth-server.php",
    "user": "admin",
    "password": "admin"
}
  • Línea 2: la URL del servicio web;
  • Líneas 3–4: las credenciales del usuario.

El código del cliente [auth-client.php] es el siguiente:

<?php

declare(strict_types=1);

// cliente de un servicio web con autenticación

// dependencias
require_once __DIR__ . '/../../../vendor/autoload.php';

use Symfony\Component\HttpClient\HttpClient;
use Symfony\Contracts\HttpClient\Exception\ExceptionInterface;

// el archivo de configuración: 1.er argumento de la línea de comandos si existe
$configFileName = $argv[1] ?? "config-auth-client.json";

// recuperamos la configuración
if (!file_exists($configFileName)) {
    print "The configuration file [$configFileName] does not exist\n";
    exit(1);
}
try {
    $config = json_decode(file_get_contents($configFileName), true, flags: JSON_THROW_ON_ERROR);
} catch (JsonException $ex) {
    print "Error while using the JSON configuration file [$configFileName]: {$ex->getMessage()}\n";
    exit(1);
}

// creamos un cliente HTTP
$httpClient = HttpClient::create([
    // las credenciales del usuario
    'auth_basic' => [$config['user'], $config['password']],
    // ¿se debe verificar el certificado del servidor (HTTPS)? sí por defecto
    'verify_peer' => $config['verify_peer'] ?? true,
    'verify_host' => $config['verify_host'] ?? true,
]);

try {
    // hacemos la solicitud al servidor
    $response = $httpClient->request('GET', $config['url']);
    // estado de la respuesta
    $statusCode = $response->getStatusCode();
    print "---Response with status: $statusCode\n";
    // recuperamos los encabezados
    print "---Headers of the response\n";
    foreach ($response->getHeaders() as $name => $values) {
        print "$name: $values[0]\n";
    }
    // mostramos la respuesta del servidor
    print "---Server response: [{$response->getContent()}]\n";
} catch (ExceptionInterface $ex) {
    // mostramos el error
    print "Error communicating with the server: {$ex->getMessage()}\n";
    exit(2);
}

Comentarios

  • Líneas 29–35: se pasó un parámetro al método estático [HttpClient::create]: un arreglo asociativo de opciones que se aplicarán a todas las solicitudes de este cliente;
  • Línea 31: la opción [auth_basic] tiene como valor un arreglo de dos elementos, [user, password]. El cliente utilizará estos elementos para autenticarse ante el servicio web. La opción [auth_basic] especifica un tipo de autenticación llamado [Basic], que lleva el nombre del valor del encabezado HTTP [Authorization] que el cliente enviará. Existen otros tipos de autenticación;
  • líneas 33–34: dos opciones útiles para el protocolo HTTPS, que veremos un poco más adelante. Su valor predeterminado es [true] si el archivo de configuración no especifica lo contrario;
  • Aparte de este código, el cliente es idéntico a los anteriores.

Para ver los encabezados HTTP enviados por el cliente, lo conectamos a nuestro servidor de monitoreo, que se ejecuta en el puerto 100, con la siguiente configuración [config-spy.json]:

1
2
3
4
5
{
    "url": "http://localhost:100/php8-oct-2026/scripts-web/08/auth-server.php",
    "user": "admin",
    "password": "admin"
}

El comando [php auth-client.php config-spy.json] produce la siguiente salida en el terminal del servidor espía:

> php spy-server.php 100
Spy server waiting for a client on port 100
Client connected: 127.0.0.1:50388
--- lines received
GET /php8-oct-2026/scripts-web/08/auth-server.php HTTP/1.1
Host: localhost:100
Accept: */*
Authorization: Basic YWRtaW46YWRtaW4=
User-Agent: Symfony HttpClient (Curl)
Accept-Encoding: gzip

--- end of the communication
  • Línea 8: vemos el encabezado [Authorization: Basic XXX] enviado por el cliente. La cadena XXX es la versión codificada en Base64 de la cadena [user:password].

Para verificarlo, puede decodificar la cadena recibida con la función [base64_decode] de PHP. La opción [-r] del comando [php] ejecuta el código PHP que la sigue:

> php -r "echo base64_decode('YWRtaW46YWRtaW4='), PHP_EOL;"
admin:admin

La codificación Base64 no es un cifrado: cualquiera puede decodificar la cadena.

17.11.2. El servidor

El servidor [auth-server.php] es el siguiente:

<?php

declare(strict_types=1);

// dependencias
require_once __DIR__ . '/../../vendor/autoload.php';

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

// usuarios autorizados: login => contraseña
$users = ["admin" => "admin"];
//
// recuperamos la solicitud actual
$request = Request::createFromGlobals();
// las credenciales enviadas por el cliente (null si no envió ninguna)
$requestUser = $request->getUser();
$requestPassword = $request->getPassword();
// ¿existe el usuario?
$found = $requestUser !== null && $requestPassword !== null
    && array_key_exists($requestUser, $users)
    && hash_equals($users[$requestUser], $requestPassword);
// preparación de la respuesta
$response = new Response();
// establecemos el código de estado de la respuesta
if (!$found) {
    // no encontrado - código 401
    $response->setStatusCode(Response::HTTP_UNAUTHORIZED);
    $response->headers->set("WWW-Authenticate", 'Basic realm="PHP 8 by example"');
} else {
    // encontrado - código 200
    $response->setStatusCode(Response::HTTP_OK);
}
// la respuesta no tiene contenido, solo encabezados HTTP
$response->send();

Comentarios

  • línea 12: usuarios autorizados (en este caso, solo uno) con el nombre de usuario [admin] y la contraseña [admin];
  • línea 17: el método [getUser] del objeto [Request] devuelve el identificador de usuario, extraído por PHP del encabezado [Authorization: Basic …] enviado por el cliente, o [null] si el cliente no envió ese encabezado. Sin [HttpFoundation], se encontraría en [$_SERVER['PHP_AUTH_USER']];
  • línea 18: lo mismo se aplica a la contraseña ([$_SERVER['PHP_AUTH_PW']]);
  • líneas 20–22: buscamos al usuario que intenta iniciar sesión en la lista de usuarios autorizados. Las contraseñas se comparan con la función [hash_equals] en lugar del operador [===]: su tiempo de ejecución no depende de la posición en la que difieren las dos cadenas, lo que impide que un atacante adivine una contraseña carácter por carácter midiendo los tiempos de respuesta;
  • líneas 26–29: si el usuario no ha sido autenticado, se envía lo siguiente al cliente:
    • el código [401 Unauthorized];
    • un encabezado [WWW-Authenticate: Basic realm="something"]. Los navegadores reconocen este encabezado y muestran una ventana de autenticación que solicita al usuario iniciar sesión. Los encabezados HTTP deben escribirse utilizando únicamente caracteres ASCII. El script PHP 7 utilizaba la función [utf8_decode] para convertir una cadena UTF-8 a ISO-8859-1; esta función está obsoleta desde PHP 8.2. Si fuera necesaria, utilizaríamos [mb_convert_encoding($text, 'ISO-8859-1', 'UTF-8')]. Nuestro texto [PHP 8 by example] utiliza únicamente caracteres ASCII;
  • líneas 30–32: si el usuario ha sido reconocido, se envía al cliente el código [200 OK];
  • línea 35: la respuesta no contiene ningún documento, solo una línea de estado y encabezados.

Solicitemos la URL [http://localhost/php8-oct-2026/scripts-web/08/auth-server.php] con un navegador: el navegador muestra una ventana de inicio de sesión. Si se ingresan credenciales incorrectas, el navegador muestra esta ventana indefinidamente hasta que se ingresan las credenciales correctas: cada vez se produce un viaje de ida y vuelta al servidor, que siempre devuelve la misma respuesta, lo que activa la ventana de autenticación del navegador. Esta es la respuesta del servidor sin credenciales:

1
2
3
4
5
6
7
8
9
> curl -i http://localhost/php8-oct-2026/scripts-web/08/auth-server.php
HTTP/1.0 401 Unauthorized
Date: Thu, 01 Oct 2026 15:31:46 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Cache-Control: no-cache, private
WWW-Authenticate: Basic realm="PHP 8 by example"
Connection: close
Content-Type: text/html; charset=UTF-8
  • línea 2: el código [401 Unauthorized] de la respuesta;
  • el encabezado HTTP [WWW-Authenticate] solicita al cliente que se autentique;
  • el cuerpo de la respuesta está vacío.

Con la opción [-u admin:admin], [curl] envía las credenciales [admin, admin]:

1
2
3
4
5
6
7
8
9
> curl -i -u admin:admin http://localhost/php8-oct-2026/scripts-web/08/auth-server.php
HTTP/1.0 200 OK
Date: Thu, 01 Oct 2026 15:31:46 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Cache-Control: no-cache, private
Vary: Accept-Encoding
Connection: close
Content-Type: text/html; charset=UTF-8
  • línea 2: el código de respuesta [200 OK];
  • el cuerpo de la respuesta está vacío.

Ejecutemos el cliente [auth-client.php] con el usuario autorizado [admin, admin]. La respuesta del servidor es la siguiente:

> php auth-client.php
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: no-cache, private
vary: Accept-Encoding
content-encoding: gzip
connection: close
content-type: text/html; charset=UTF-8
---Server response: []
  • Línea 2: el servidor respondió con [200 OK];
  • Última línea: la respuesta no tiene contenido.

Ahora ejecutemos el cliente con una contraseña incorrecta, utilizando el archivo de configuración [config-auth-client-ko.json]:

1
2
3
4
5
{
    "url": "http://localhost/php8-oct-2026/scripts-web/08/auth-server.php",
    "user": "admin",
    "password": "x"
}

La respuesta es la siguiente:

1
2
3
4
> php auth-client.php config-auth-client-ko.json
---Response with status: 401
---Headers of the response
Error communicating with the server: HTTP/1.0 401 Unauthorized returned for "http://localhost/php8-oct-2026/scripts-web/08/auth-server.php".
  • Línea 2: el cliente recibió correctamente un código 401;
  • línea 4: se lanzó una excepción en el cliente. La lanzó el cliente Symfony [HttpClient]: lanza una excepción de tipo [ClientExceptionInterface] (códigos 4xx) o [ServerExceptionInterface] (códigos 5xx) cuando el código de estado de la respuesta HTTP indica un error y el cliente intenta leer los encabezados o el contenido de la respuesta. El mensaje de la excepción muestra que el servidor respondió con [401 Unauthorized] para indicar que no se reconoció al usuario. Para leer de todos modos los encabezados o el cuerpo de una respuesta que contiene un error, se utiliza [$response->getHeaders(false)] o [$response->getContent(false)]. Lo utilizaremos en la aplicación de cálculo del impuesto, donde el servidor devuelve un mensaje de error JSON junto con sus códigos de error.

17.11.2.1. Cuando el servidor siempre responde con 401

En ciertas instalaciones de [Apache], el servidor responde con [401 Unauthorized] a todas las solicitudes, incluso con las credenciales correctas. La causa no es el script PHP: es la manera en que [Apache] ejecuta PHP. Cuando PHP es un módulo de [Apache] (mod_php), recibe todos los encabezados HTTP de la solicitud. Sin embargo, cuando [Apache] ejecuta PHP en un proceso separado, según el protocolo FastCGI (módulos [mod_fcgid] o [mod_proxy_fcgi]), de forma predeterminada no le transmite el encabezado [Authorization] que contiene los identificadores: para PHP, el cliente nunca se ha autenticado. Por esta razón, la carpeta [scripts-web] contiene el siguiente archivo [.htaccess], que se aplica a todas sus subcarpetas:

1
2
3
4
5
6
7
# Pasa el encabezado HTTP [Authorization] a PHP (autenticación HTTP Basic).
# Con PHP ejecutándose como módulo de Apache (mod_php), PHP siempre lo recibe. Pero cuando
# PHP se ejecuta mediante FastCGI (mod_fcgid, PHP-FPM...), Apache no lo transmite por
# defecto: las credenciales enviadas por el cliente se pierden entonces y el servidor
# responde 401 a todas las solicitudes. Las dos líneas siguientes lo solucionan.
CGIPassAuth On
SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
  • Línea 6: indica a [Apache] (versión 2.4.13 y posteriores) que transmita el encabezado [Authorization] a los programas FastCGI;
  • línea 7: un segundo método, más antiguo, que copia el encabezado [Authorization] en la variable de entorno [HTTP_AUTHORIZATION]. La clase [Request] de Symfony puede leer allí los identificadores.

Con mod_php, estas dos líneas no tienen efecto. Verificamos que el servidor recibe correctamente las credenciales con [curl], que, a diferencia del navegador, no conserva nada de una solicitud a otra: [curl -i -u admin:admin "http://localhost/php8-oct-2026/scripts-web/08/auth-server.php"] debería devolver un código de estado 200. Si el navegador sigue mostrando su ventana de autenticación, debe cerrarlo por completo (conserva las credenciales rechazadas durante toda la sesión) o utilizar una ventana de incógnito.

17.11.3. Protección de la conexión cliente/servidor

Hemos visto que, para autenticarse ante el servidor, el cliente envía el encabezado:

Authorization: Basic YWRtaW46YWRtaW4=

Si un software espía intercepta esta línea, puede recuperar fácilmente las credenciales [login, password] codificadas en Base64 en la cadena [YWRtaW46YWRtaW4=]. Por esta razón, la autenticación debe realizarse a través de una conexión segura entre el cliente y el servidor. Las conexiones seguras a una URL utilizan el protocolo [HTTPS] en lugar del protocolo HTTP. El protocolo [HTTPS] es el protocolo HTTP dentro de una conexión cliente/servidor cifrada mediante el protocolo TLS (Transport Layer Security, el sucesor de SSL). Las conexiones seguras a una URL tienen la forma [https://document_path]. El puerto predeterminado del protocolo HTTPS es el 443.

No todos los servidores web aceptan URL con este formato; deben configurarse para ello. El servidor [Apache] de [Laragon] admite el protocolo HTTPS, pero no está habilitado de forma predeterminada. Puede habilitarlo desde el menú de [Laragon]: haga clic con el botón derecho en la ventana de [Laragon] y luego seleccione [Apache / SSL / Enabled]. A continuación, el servidor [Apache] se reinicia y la ventana de [Laragon] muestra que ahora escucha en dos puertos: el puerto 80 (HTTP) y el puerto 443 (HTTPS). Durante esta activación, [Laragon] generó un certificado denominado autofirmado para el servidor.

Los navegadores web, en cambio, rechazan de forma predeterminada los certificados autofirmados. Con un certificado simplemente desconocido, [Chrome] y [Edge] muestran una página de advertencia ("Su conexión no es privada") con un botón [Advanced] seguido de un enlace [Proceed to localhost (unsafe)]. Sin embargo, este enlace no siempre se ofrece: falta notablemente cuando el certificado se considera no conforme, o cuando el navegador ha almacenado en caché que el sitio [localhost] debe servirse siempre como HTTPS con un certificado válido (mecanismo HSTS). La solución correcta consiste entonces en confiar en el certificado de [Laragon]:

  • en el menú de [Laragon], seleccione [Apache / SSL / Add laragon.crt to Trust Store]. [Windows] le solicita confirmar la incorporación del certificado a las entidades de certificación raíz de confianza del usuario; acepte;
  • cierre por completo el navegador (todas sus ventanas) y vuelva a iniciarlo: [Chrome] y [Edge] utilizan el almacén de certificados de [Windows], y el certificado de [Laragon] ahora se acepta sin advertencia para [https://localhost];
  • si el navegador sigue rechazando la página, elimine la regla HSTS que pueda haber almacenado en caché para [localhost]: abra la página [chrome://net-internals/#hsts] (o [edge://net-internals/#hsts] para [Edge]), escriba [localhost] en el campo [Delete domain security policies] y haga clic en [Delete].

Como último recurso, y solo en su propia computadora, [Chrome] y [Edge] permiten omitir la advertencia si se escribe, en la propia página de error (sin hacer clic en ningún campo de entrada), la palabra [thisisunsafe]. Este es un recurso del navegador pensado para desarrolladores: nunca lo utilice en un sitio que no controle. Si ninguno de estos métodos funciona, utilice la URL [http://localhost/...] en el navegador: en el capítulo sobre la Versión 8 del cálculo del impuesto veremos por qué esto no es imprudente en su propia máquina.

Agregar el certificado al almacén de [Windows] no afecta a nuestros clientes PHP: la biblioteca [curl] que utiliza PHP tiene su propia lista de entidades de certificación. Esto se ilustra en el siguiente ejemplo.

Ahora que tenemos un servidor seguro, proporcionemos al cliente [auth-client.php] el siguiente archivo de configuración, [config-auth-client-https-verify.json]:

1
2
3
4
5
{
    "url": "https://localhost/php8-oct-2026/scripts-web/08/auth-server.php",
    "user": "admin",
    "password": "admin"
}
  • Línea 2: el protocolo ahora es [https]. No se especifica el puerto; el valor predeterminado es el puerto 443.

Ejecutemos el cliente con esta configuración. La salida de la consola es la siguiente:

> php auth-client.php config-auth-client-https-verify.json
Error communicating with the server: SSL certificate problem: self-signed certificate for "https://localhost/php8-oct-2026/scripts-web/08/auth-server.php".

El cliente Symfony [HttpClient] lanzó una excepción porque no aceptó el certificado enviado por el servidor. La conexión TLS se basa en certificados emitidos por entidades de certificación reconocidas. El certificado generado por [Laragon] es un certificado autofirmado: ninguna entidad de certificación lo valida. Por lo tanto, el cliente lo rechazó, y con razón: no hay pruebas de que se esté comunicando con el servidor real y no con un impostor.

Es posible indicar a [HttpClient] que no verifique el certificado enviado por el servidor. Esto se hace mediante las opciones [verify_peer] y [verify_host] del método [HttpClient::create], que nuestro cliente lee de su archivo de configuración. El archivo [config-auth-client-https.json] las establece en [false]:

1
2
3
4
5
6
7
{
    "url": "https://localhost/php8-oct-2026/scripts-web/08/auth-server.php",
    "user": "admin",
    "password": "admin",
    "verify_peer": false,
    "verify_host": false
}
  • Línea 5: no verificar que el certificado haya sido emitido por una entidad de certificación reconocida;
  • línea 6: no verificar que el certificado haya sido emitido para la máquina con la que se establece contacto ([localhost] en este caso).

Ya nos habíamos encontrado con este problema en el capítulo anterior, con la biblioteca [libcurl] y su opción [CURLOPT_SSL_VERIFYPEER]. El cliente Symfony [HttpClient] es en realidad un cliente [curl] cuando la extensión [curl] está habilitada en la configuración de PHP, como ocurre aquí: la clase instanciada por [HttpClient::create] es entonces [CurlHttpClient], que traduce sus opciones a opciones de [curl]: [verify_peer] se convierte en [CURLOPT_SSL_VERIFYPEER], y [verify_host] se convierte en [CURLOPT_SSL_VERIFYHOST].

Si ahora ejecutamos el cliente con el comando [php auth-client.php config-auth-client-https.json], obtenemos el siguiente resultado:

> php auth-client.php config-auth-client-https.json
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: no-cache, private
vary: Accept-Encoding
content-encoding: gzip
connection: close
content-type: text/html; charset=UTF-8
---Server response: []

El usuario fue reconocido correctamente. Con [curl], la opción [-k] (o [--insecure]) cumple la misma función que nuestras dos opciones:

1
2
3
4
5
6
7
8
9
> curl -i -k -u admin:admin https://localhost/php8-oct-2026/scripts-web/08/auth-server.php
HTTP/1.0 200 OK
Date: Thu, 01 Oct 2026 15:31:46 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Cache-Control: no-cache, private
Vary: Accept-Encoding
Connection: close
Content-Type: text/html; charset=UTF-8

Nota: deshabilitar la verificación de certificados solo es aceptable durante el desarrollo, en su propia máquina. Una solución más limpia es indicar al cliente el certificado del servidor mediante la opción [cafile] de [HttpClient] (o la opción [--cacert] de [curl]): la verificación sigue habilitada y el cliente acepta ese certificado específico. En producción, el servidor tiene un certificado emitido por una entidad de certificación reconocida (por ejemplo, de forma gratuita por Let's Encrypt) y no se requiere ninguna opción.

Ahora sabemos cómo autenticarnos ante un servidor seguro.