Cómo usar cURL en PHP | Envato Tuts+

Spanish (Español) translation by Ana Paulina Figueroa (you can also view the original English article)

Hoy vamos a explorar la extensión cURL en PHP, la cual te permite realizar solicitudes HTTP desde tu código.

Durante tu desarrollo diario con PHP, a menudo necesitas comunicarte con sitios web externos. Ya sea para llamar a APIs REST de terceros con el fin de obtener datos, o para descargar recursos de un sitio web externo, querrás contar con una biblioteca que te permita hacer esto sin esfuerzo.

En PHP existen diferentes métodos que puedes usar para conectarte y comunicarte con diferentes tipos de servidores. Una de las maneras más sencillas es usar la función file_get_contents para leer archivos remotos. Por otro lado, también puedes usar sockets para implementar la comunicación cliente-servidor. Sin embargo, en este artículo vamos a discutir la extensión cURL a detalle usando ejemplos reales.

cURL significa URLs cliente, y es una biblioteca que te permite enviar y recibir información con la sintaxis de un URL. De hecho aprovecha la biblioteca libcurl, creada por Daniel Stenberg, que te permite conectarte y comunicarte con muchos tipos diferentes de servidores usando muchos tipos distintos de protocolos. Además de HTTP y HTTPS, la biblioteca libcurl también es compatible con protocolos como FTP, Gopher, Telnet, DICT, File y LDAP.

A partir de la siguiente sección, analizaremos un par de ejemplos reales para demostrar cómo puedes usar las funciones de cURL en PHP.

Ejemplos reales

En esta sección vamos a crear ejemplos reales para hacer una demostración de varias funciones de cURL en PHP.

Cómo descargar archivos usando cURL en PHP

Leer o descargar archivos remotos es uno de los casos de uso más comunes de cURL. Esto se logra mediante una solicitud GET de cURL, que discutiremos en esta sección.

Sigue adelante y crea el archivo curl_read_file.php con el siguiente contenido.

<?php
$url = 'https://www.example.com';

$curl = curl_init();

curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HEADER, false);

$data = curl_exec($curl);

curl_close($curl);

En el ejemplo anterior, hemos usado funciones de cURL para leer la página de inicio del dominio example.com. Examinemos los fragmentos de código importantes para comprender su funcionamiento.

En primer lugar, hemos usado la función curl_init para inicializar una nueva sesión de cURL. La variable $curlHandle contiene un manipulador de cURL, el cual podemos usar para establecer varias opciones para la transferencia con cURL con la ayuda de la función curl_setopt.

Al trabajar con cURL, la función curl_setopt es la que ocuparás con más frecuencia, ya que te permite inicializar varias opciones de solicitud CURLOPT_*. La función curl_setopt recibe tres argumentos: un manipulador de cURL, la opción CURLOPT_XXX y el valor de la opción CURLOPT_XXX.

A continuación hemos usado la opción CURLOPT_URL para establecer el valor del URL de solicitud en example.com con la función curl_setopt. Además, hemos establecido el valor de la opción CURLOPT_RETURNTRANSFER en TRUE, ya que queremos inicializar la respuesta en la variable $responseData. Si no establecemos su valor en TRUE, la respuesta será mostrada directamente en la pantalla. Por último, hemos establecido el valor de la opción CURLOPT_HEADER en FALSE para omitir la información de la cabecera en la salida.

Finalmente, hemos usado la función curl_exec para ejecutar la solicitud de cURL. Si todo va bien, la variable $responseData debería contener la fuente de la página de inicio de example.com.

Cómo enviar datos usando cURL en PHP

En esta sección veremos cómo enviar datos con cURL.

Creemos el archivo curl_post_example.php con el siguiente contenido.

<?php
$url = '{POST_REST_ENDPOINT}';

$curl = curl_init();

$fields = array(
    'field_name_1' => 'Value 1',
    'field_name_2' => 'Value 2',
    'field_name_3' => 'Value 3'
);

$fields_string = http_build_query($fields);

curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_POST, TRUE);
curl_setopt($curl, CURLOPT_POSTFIELDS, $fields_string);

$data = curl_exec($curl);

curl_close($curl);

En el ejemplo anterior, estamos suponiendo que necesitamos enviar una solicitud con el método HTTP POST. De hecho, funciona de manera similar al envío de un formulario con el método POST.

La variable $fields contiene un arreglo de valores que debemos enviar como datos POST. Después hemos usado la función http_build_query para preparar una cadena de consulta codificada con estilo URL.

A continuación, hemos establecido el valor de la opción CURLOPT_POST en TRUE para configurar el método de solicitud como HTTP POST. Además, necesitamos usar la opción CURLOPT_POSTFIELDS para configurar los datos POST que queramos enviar junto con la solicitud.

Finalmente, hemos usado la función curl_exec para ejecutar la solicitud de cURL. Entonces, de esta manera puedes realizar una solicitud POST de cURL.

Cómo enviar datos JSON usando cURL en PHP

La mayoría de las veces, necesitas enviar datos JSON en una solicitud POST de cURL. En esta sección veremos cómo puedes enviar datos JSON con el método POST en una solicitud de cURL.

Dado que es una solicitud POST, modifiquemos el ejemplo que acabamos de discutir en la sección anterior. Sigue adelante y crea el archivo curl_post_json.php con el siguiente contenido.

<?php
$url = '{POST_REST_ENDPOINT}';

$curl = curl_init();

$fields = array(
    'field_name_1' => 'Value 1',
    'field_name_2' => 'Value 2',
    'field_name_3' => 'Value 3'
);

$json_string = json_encode($fields);

curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_POST, TRUE);
curl_setopt($curl, CURLOPT_POSTFIELDS, $json_string);
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true );

$data = curl_exec($curl);

curl_close($curl);

Aunque puede parecer similar al ejemplo de la sección anterior, lo importante es que hemos usado la función json_encode para crear una cadena JSON a partir del arreglo $fields.

A continuación, hemos usado la opción CURLOPT_HTTPHEADER para establecer el valor de la cabecera Content-Type en application/json, con el fin de informar al servidor API que estamos enviando datos JSON. La cabecera Content-Type es útil para enviar datos en formatos diferentes. Por ejemplo, si quisieras enviar datos XML, tendrías que configurar el valor de la cabecera Content-Type en application/xml.

A excepción de eso, es prácticamente lo mismo que se usa para la solicitud POST normal. Entonces, de esta manera puedes enviar diferentes tipos de datos configurando la cabecera Content-Type apropiada. Si no configuras la cabecera Content-Type, esta usará application/x-www-form-urlencoded como valor predeterminado.

Cómo cargar archivos usando cURL en PHP

En esta sección discutiremos cómo puedes cargar archivos con cURL.

Creemos el archivo curl_post_file.php con el siguiente contenido.

<?php
$url = '{POST_REST_ENDPOINT}';

$curl = curl_init();

if (function_exists('curl_file_create')) {
  $fileAttachment = curl_file_create('/absolute/path/to/file/');
} else {
  $fileAttachment = '@' . realpath('/absolute/path/to/file/');
}

$fields = array(
    'field_name_1' => 'Value 1',
    'field_name_2' => 'Value 2',
    'field_name_3' => 'Value 3',
    'uploaded_file' => $fileAttachment
);

curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_POST, TRUE);
curl_setopt($curl, CURLOPT_POSTFIELDS, $fields);
curl_setopt($curl, CURLOPT_RETURNTRANSFER,1);

$data = curl_exec($curl);

curl_close($curl);

Cuando quieres cargar un archivo, en primer lugar necesitas crear un objeto CURLFile. A partir de PHP 5.5+ es bastante sencillo crearlo, ya que solamente necesitas usar la función curl_file_create para crear un objeto CURLFile. El primer argumento de la función curl_file_create es la ruta absoluta del archivo que quieras cargar.

Si todavía estás usando una versión anterior de PHP, lo cuál no es recomendable, hemos usado la sintaxis alternativa '@' . realpath('/absolute/path/to/file/') para crear un enlace de archivo.

Finalmente, hemos establecido el valor de la cabecera Content-Type en multipart/form-data, ya que será una solicitud POST de formulario de varias partes. Con excepción de eso, se trata de una solicitud POST rutinaria de cURL.

Hast ahora, hemos examinado un par de métodos diferentes de cURL que se usan frecuentemente en PHP. En la siguiente sección veremos cómo puedes usar la biblioteca Guzzle, que te facilita las cosas al trabajar con solicitudes HTTP en PHP.

¿Qué es el cliente HTTP Guzzle?

Según la documentación oficial:

Guzzle es un cliente HTTP de PHP que facilita el envío de solicitudes HTTP y es común integrarlo con servidores web.

Revisemos rápidamente los beneficios del uso de Guzzle en comparación con las funciones de cURL de PHP:

una interfaz simple para diferentes tipos de datos
permite solicitudes tanto síncronas como asíncronas
permite el uso de cURL, sockets y streams de PHP
cumple con el estándar PSR-7
y más

Tomando todo en consideración, es una de las mejores bibliotecas que puedes usar cuando quieres realizar llamadas HTTP con diferentes métodos. En esta sección discutiremos cómo instalar Guzzle, continuando con un par de ejemplos rápidos ¡para demostrar el poder de esta biblioteca!

Cómo instalar la biblioteca Guzzle

La documentación oficial recomienda que uses Composer para instalar Guzzle. Ejecutemos el siguiente comando para instalar Guzzle en tu proyecto.

$composer require guzzlehttp/guzzle:^7.0
./composer.json has been created
Loading composer repositories with package information
Updating dependencies (including require-dev)
Package operations: 6 installs, 0 updates, 0 removals
  - Installing psr/http-message (1.0.1): Loading from cache
  - Installing psr/http-client (1.0.1): Loading from cache
  - Installing ralouphie/getallheaders (3.0.3): Loading from cache
  - Installing guzzlehttp/psr7 (1.7.0): Loading from cache
  - Installing guzzlehttp/promises (1.4.1): Loading from cache
  - Installing guzzlehttp/guzzle (7.2.0): Loading from cache
guzzlehttp/psr7 suggests installing laminas/laminas-httphandlerrunner (Emit PSR-7 responses)
guzzlehttp/guzzle suggests installing psr/log (Required for using the Log middleware)
Writing lock file
Generating autoload files

Una vez instalado, debes requerir el cargador automático de Composer, como se muestra en el siguiente fragmento de código.

1	require 'vendor/autoload.php';

Y, con eso, ¡estás listo para usar Guzzle!

Cómo realizar una solicitud GET con Guzzle

En esta sección veremos cómo puedes enviar solicitudes GET con Guzzle.

Modificaremos el ejemplo que discutimos anteriormente, ya que te ayudará a comprender de qué manera podrías convertir tu código cURL de PHP existente a una implementación basada en Guzzle.

Echemos un vistazo al ejemplo modificado.

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$response = $client->get('https://example.com');

$responseContents = $response->getBody();

¿No es sencillo? Hemos creado una instancia de la clase \GuzzleHttp\Client, y esta se asigna a la variable $client. Y ahora tienes acceso a muchos métodos de utilidad proporcionados por la clase \GuzzleHttp\Client.

En nuestro caso necesitamos obtener contenido con el método GET, por lo que hemos usado el método get de la clase \GuzzleHttp\Client, y este devolverá el objeto GuzzleHttp\Psr7\Response. El objeto GuzzleHttp\Psr7\Response proporciona varios métodos como getStatusCode, getBody, getReasonPhrase y más. Hemos usado el método getBody para obtener el contenido del cuerpo de la respuesta.

Así es como puedes llevar a cabo solicitudes HTTP GET con Guzzle.

Cómo realizar una solicitud POST con Guzzle

En esta sección veremos cómo puedes realizar solicitudes HTTP POST con Guzzle.

Modificaremos el ejemplo curl_post_example.php que discutimos en la sección anterior. El código modificado con Guzzle se ve de esta manera.

<?php
require 'vendor/autoload.php';

$client = new \GuzzleHttp\Client();
$options = [
    'form_params' => [
        "field_name_1" => "Value 1",
        "field_name_2" => "Value 2",
        "field_name_3" => "Value 3",
    ]
];

$response = $client->post("{POST_REST_ENDPOINT}", $options);
$responseContents = $response->getBody();
?>

Ya que esta es una solicitud POST, necesitamos enviar el arreglo $options como segundo argumento del método post. En nuestro ejemplo, este contiene los datos del formulario que necesitamos enviar como datos POST.

Si te preguntas cómo enviar datos JSON, solamente necesitas cambiar la clave form_params a json, ¡y los datos se enviarán como JSON!

Además, si deseas enviar cabeceras HTTP junto con una solicitud, puedes hacerlo con la clave headers, como se muestra en el siguiente fragmento de código.

...
...
$headers = array(
    'Content-Type'   => 'application/json'
);
$options = [
    'form_params' => [
            "field_name_1" => "Value 1",
            "field_name_2" => "Value 2",
            "field_name_3" => "Value 3",
    ],
    ‘headers’ => $headers
];
...
...

De hecho, la biblioteca Guzzle proporciona muchas opciones de configuración para cada método. Además, existen varias formas de hacer lo mismo, por lo que te animo a que la explores a detalle, ¡y estoy seguro de que te divertirás!

Esa fue una introducción rápida a la biblioteca Guzzle, junto con las funciones de cURL de PHP.

Conclusión

Hoy exploramos los conceptos básicos de la extensión cURL en PHP. Discutimos cómo puedes llevar a cabo diferentes tipos de solicitudes HTTP con cURL en PHP. Además, vimos una rápida introducción a la biblioteca Guzzle, que facilita la vida a los desarrolladores al trabajar con solicitudes HTTP en PHP.