¿Cómo hacer una solicitud PUT con curl_init()?

La aplicación de software cURL, formalmente conocida como "Cliente para URLs", proporciona a los desarrolladores un conjunto de herramientas robusto para gestionar las transferencias de datos. Opera en dos modos distintos: una interfaz de línea de comandos fácil de usar que se adapta a las interacciones fundamentales y una potente biblioteca diseñada para una integración perfecta en proyectos de programación.

Definición formal de curl_init()

Basándose en el sitio web oficial de PHP, la función curl_init inicializa una sesión cURL y devuelve un controlador cURL para su uso con las funciones curl_setopt(), curl_exec() y curl_close().

Parámetros involucrados

url

Si proporcionas una URL, la opción CURLOPT_URL se establecerá en su valor. También puedes establecer manualmente esta opción utilizando la función curl_setopt().

Sin embargo, ten en cuenta que el protocolo file está desactivado por el propio cURL si se ha establecido open_basedir.

Valores de retorno

La función curl_init() devuelve un controlador cURL en caso de éxito y false en caso de error.

¿Qué es una solicitud PUT?

La solicitud PUT dentro del Protocolo de Transferencia de Hipertexto (HTTP) actúa como una herramienta refinada para gestionar los recursos en un servidor web. Se desvía de su contraparte, la solicitud GET (utilizada para la recuperación de datos), apuntando específicamente a las modificaciones en el lado del servidor.

Función de las solicitudes PUT

A diferencia de su contraparte, la solicitud GET utilizada para recuperar datos, una solicitud PUT se centra en la modificación de la información en el lado del servidor. Esta modificación puede abarcar dos acciones principales:

1. Actualización de recursos existentes: Si un recurso (como una cuenta de usuario o un producto en una base de datos) ya existe en una URL específica, se puede utilizar una solicitud PUT para actualizar sus datos asociados.
2. Creación de nuevos recursos: En escenarios donde un recurso no existe en la URL designada, se puede emplear una solicitud PUT para crear un nuevo recurso con los datos proporcionados.

Colocación de datos

Las solicitudes PUT suelen transmitir datos dentro del cuerpo de la solicitud, de forma similar a las solicitudes POST. Estos datos a menudo representan el estado nuevo o actualizado del recurso al que se dirige.

Idempotencia

Una característica definitoria de las solicitudes PUT es su naturaleza idempotente. Esto implica que la ejecución de una solicitud PUT varias veces con datos idénticos producirá el mismo resultado. En términos más simples, el envío de una solicitud PUT una o varias veces con los mismos datos conduce al mismo resultado en el servidor.

Casos de uso comunes de las solicitudes PUT

• Actualización de perfiles de usuario o información de la cuenta
• Modificación del contenido existente en una base de datos (por ejemplo, editar una entrada de blog)
• Carga de un nuevo archivo en una ubicación específica del servidor

Ejemplos de código para realizar solicitudes PUT con la función curl_init()

Aquí hay algunos ejemplos de código PHP a los que puedes referirte si deseas realizar solicitudes PUT con la función curl_init().

Ejemplo 1 - Actualización de la información del usuario (datos JSON)

Este ejemplo actualiza la información del perfil de un usuario en un servidor utilizando datos JSON.

<?php

$url = "https://www.example.com/api/users/123"; // Reemplazar con el ID de usuario real
$new_email = "new_email@example.com";

$data = array(
  "email" => $new_email
);

$data_json = json_encode($data);

$ch = curl_init($url);

curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT"); // Establecer el método de solicitud en PUT
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json); // Establecer los datos PUT como JSON
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);  // Devolver la respuesta

curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  'Content-Type: application/json',   // Establecer el tipo de contenido en JSON
  'Authorization: Bearer YOUR_API_KEY'  // Añadir el encabezado de autorización
));

$response = curl_exec($ch);

curl_close($ch);

if($response) {
  echo "¡Perfil de usuario actualizado con éxito!";
} else {
  echo "Error: " . curl_error($ch);
}

?>

Explicación del código:

1. Definimos la URL de destino (incluido el ID de usuario) y la nueva dirección de correo electrónico.
2. Creamos una matriz $data que contiene el correo electrónico actualizado y lo convertimos a JSON utilizando json_encode.
3. Inicializamos el controlador curl y establecemos el método de solicitud en PUT utilizando CURLOPT_CUSTOMREQUEST.
4. Establecemos los datos PUT con CURLOPT_POSTFIELDS y establecemos el encabezado del tipo de contenido en JSON.
5. Añadimos un encabezado de autorización con tu clave API para un acceso seguro.
6. Ejecutamos la solicitud, cerramos el controlador y comprobamos si hay una respuesta exitosa.

Ejemplo 2 - Carga de un archivo (datos sin procesar)

Este ejemplo carga un archivo en un servidor utilizando datos sin procesar.

<?php

$url = "https://www.example.com/api/uploads";
$filename = "myfile.txt";

$file_content = file_get_contents($filename); // Leer el contenido del archivo

$ch = curl_init($url);

curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT"); // Establecer el método de solicitud en PUT
curl_setopt($ch, CURLOPT_PUT, 1);  // Establecer el modo de carga PUT

curl_setopt($ch, CURLOPT_INFILE, fopen($filename, "rb")); // Establecer el archivo para la carga
curl_setopt($ch, CURLOPT_INFILESIZE, filesize($filename)); // Establecer el tamaño del archivo

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);  // Devolver la respuesta

curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  'Content-Type: application/octet-stream' // Establecer el tipo de contenido para los datos sin procesar
));

$response = curl_exec($ch);

curl_close($ch);

if($response) {
  echo "¡Archivo cargado con éxito!";
} else {
  echo "Error: " . curl_error($ch);
}

?>

Explicación del código:

1. Definimos la URL de carga y el nombre del archivo.
2. Leemos el contenido del archivo utilizando file_get_contents.
3. Inicializamos el controlador curl y establecemos el método de solicitud en PUT.
4. Habilitamos el modo de carga PUT con CURLOPT_PUT.
5. Especificamos el archivo para la carga utilizando CURLOPT_INFILE y su tamaño con CURLOPT_INFILESIZE.
6. Establecemos el encabezado del tipo de contenido para indicar datos sin procesar.
7. Ejecutamos la solicitud, cerramos el controlador y comprobamos si hay una respuesta exitosa.

Ejemplo 3 - PUT condicional con ETag

Este ejemplo demuestra una solicitud PUT condicional utilizando un ETag para el bloqueo optimista.

<?php

$url = "https://www.example.com/api/posts/123";
$new_title = "Título actualizado";
$etag = "some-etag-value";  // Reemplazar con el ETag real

$data = array(
  "title" => $new_title
);

$data_json = json_encode($data);

$ch = curl_init($url);

curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT"); // Establecer el método de solicitud en PUT
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json); // Establecer los datos PUT como JSON
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);  // Devolver la respuesta

curl_setopt($ch, CURLOPT_HTTPHEADER, array(
  'Content-Type: application/json',   // Establecer el tipo de contenido en JSON
  'If-Match: ' . $etag  // Añadir ETag para la actualización condicional
));

$response = curl_exec($ch);

curl_close($ch);

if($response) {
  echo "¡Publicación actualizada con éxito!";
} else {
  $error = curl_error($ch);
  if (strpos($error, '412 Precondition Failed') !== false) {
    echo "Error al actualizar: Desajuste de ETag (los datos pueden haber sido modificados por otro usuario).";
  } else {
    echo "Error: " . $error;
  }
}

?>

Explicación del código:

1. Definimos la URL de destino (ID de la publicación), el nuevo título y el ETag recuperado del servidor.
2. Creamos una matriz $data y la convertimos a JSON.
3. Establecemos el método de solicitud en PUT e incluimos los datos PUT.
4. Añadimos un encabezado If-Match con el ETag para asegurar que la actualización se produzca solo si la versión actual del lado del servidor coincide con el ETag. Esto evita la sobrescritura de los cambios realizados por otro usuario (bloqueo optimista).
5. Comprobamos la respuesta para ver si hay éxito y manejamos un error específico (412 Precondition Failed) que indica un desajuste de ETag.

Nota para recordar

Asegúrate de que los ejemplos de código anteriores no se copien y peguen en tus IDE, ya que están simplificados y requerirán modificaciones adicionales para adaptarse a las necesidades de tu aplicación.

Para la documentación oficial, puedes consultarla en: https://www.php.net/manual/en/book.curl.php

Acelera el desarrollo de tu API cURL con Apidog

Apidog es una sofisticada plataforma de desarrollo de APIs capaz de convertir líneas de comandos cURL en pantallas gráficas hermosas e intuitivas, lo que facilita a los desarrolladores la comprensión y el trabajo con las APIs.

No solo puedes importar comandos cURL, sino también construirlos, depurarlos, simularlos y documentarlos como cualquier otra API. Con tal comodidad, Apidog puede ayudarte con un flujo de trabajo ininterrumpido.

Importa APIs cURL en segundos

Apidog es compatible con los usuarios que deseen importar comandos cURL a Apidog. En un proyecto vacío, haz clic en el botón púrpura + alrededor de la parte superior izquierda de la ventana de Apidog y selecciona Import cURL.

Copia y pega el comando cURL en el cuadro que se muestra en tu pantalla.

Si tiene éxito, ahora deberías poder ver el comando cURL en forma de una solicitud API.

¿No estás seguro de PHP? Genera código con Apidog

Si no tienes experiencia previa en la codificación en el lenguaje de programación PHP, ¡no temas! Apidog tiene una función de generación de código en la que puedes confiar, que te proporciona marcos de código para múltiples otros lenguajes de programación.

Primero, localiza el botón </> Generate Code en cualquier API o solicitud, y selecciona Generate Client Code en la lista desplegable.

A continuación, selecciona PHP y busca la sección cURL. Ahora deberías ver el código generado para cURL. Todo lo que tienes que hacer es copiarlo y pegarlo en tu IDE (Entorno de Desarrollo Integrado) y continuar desarrollando tu aplicación.

Conclusión

Al dominar las solicitudes PUT con curl_init(), has desbloqueado una poderosa herramienta para interactuar con los servidores web. Esta función te permite no solo actualizar los recursos existentes, sino también crear otros nuevos. Ya sea que estés gestionando perfiles de usuario, modificando entradas de bases de datos o cargando archivos, las solicitudes PUT ofrecen un método preciso y eficiente para la manipulación de datos.

Recuerda, curl_init() proporciona un enfoque versátil, que te permite especificar formatos de datos, establecer encabezados personalizados para una comunicación segura e incluso manejar escenarios como actualizaciones condicionales e informes de progreso para transferencias de archivos grandes. Con este nuevo conocimiento, puedes aprovechar con confianza las solicitudes PUT para elevar la funcionalidad y el rendimiento de tus aplicaciones web.