php
  4 min. de lectura (aproximado)

Guzzle en PHP: tutorial para realizar peticiones HTTP

(4 min. de lectura) Guzzle es una librería de PHP que funciona como cliente HTTP. Básicamente permite hacer peticiones a cualquier servidor web (GET, POST, PUT, DELETE, etc.) de forma súper sencilla, limpia y potente. Es una de las librerías más usadas en PHP (especialmente en Laravel, Symfony, WordPress plugins, APIs, etc.).

¿Para qué sirve?

  • Consumir APIs externas (JSON, XML, etc.).
  • Subir archivos.
  • Manejar autenticación (Basic, Digest, OAuth2, Bearer tokens).
  • Enviar peticiones asíncronas (con promises).
  • Manejar cookies, headers, timeouts, redirecciones.
  • Depurar fácilmente (middleware de logging).

Instalación

Guzzle se instala de forma sencilla con el comando de Composer:

composer require guzzlehttp/guzzle

Ejemplo

  • Ejemplo petición GET

    require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$response = $client->get('https://jsonplaceholder.typicode.com/posts/1');

echo $response->getStatusCode(); // 200
echo $response->getBody();  // el JSON completo
    O también se puede hacer:

    require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$response = $client->get('https://api.example.com/users', [
'query' => [
'page' => 1,
'limit' => 10
]
]);

echo $response->getStatusCode(); // 200
echo $response->getBody();  // el JSON completo
  • Ejemplo petición POST:

    require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$response = $client->post('https://api.ejemplo.com/users', [
'json' => [
'name' => 'Juan',
'email' => 'juan@example.com'
]
]);

echo $response->getStatusCode(); // 200
echo $response->getBody();  // el JSON completo
    Con respecto al ejemplo del POST. Ha que hacer lo siguiente donde se recibe la petición para obtener los POST enviados:

    
header('Content-Type: application/json'); // opcional

// Leer el cuerpo raw de la petición
$rawInput = file_get_contents('php://input');

// Convertir JSON a array
$data = json_decode($rawInput, true);

if ($data === null) {
http_response_code(400);
echo json_encode(['error' => 'JSON inválido']);
exit;
}

// Ahora tienes los datos exactamente como los enviaste
$name  = $data['name']  ?? null;
$email = $data['email'] ?? null;

echo json_encode([
'recibido' => true,
'nombre'=> $name,
'email'=> $email
]);
    En este caso se usa json porque la llamada se hace con json.
  • Enviar formulario:

    require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$response = $client->post('https://api.ejemplo.com/users', [
'form_params' => [  // ← Esto simula <form method="post">
'nombre' => 'María García',
'email'  => 'maria@example.com',
'password'=> 'secreto123',
'telefono'=> '612345678',
'acepto' => '1'
]
]);

$status = $response->getStatusCode();
$body= $response->getBody()->getContents();
  • Enviar formulario con ficheros:

    require 'vendor/autoload.php';

use GuzzleHttp\Client;

use GuzzleHttp\Psr7\Utils;// ← importante para archivos grandes

$client = new Client();
$response = $client->post('https://api.ejemplo.com/users', [
'multipart' => [
[
  'name' => 'file',
  'contents' => Utils::tryFopen('fileToUpload', 'r'), //Se ùede usar fopen normal de php
  'filename' => 'fileUploaded.txt',
],
// Xampos normales (no archivos)
[
  'name' => 'usuario',
  'contents' => 'Juan123'
],
[
  'name' => 'descripcion',
  'contents' => 'Este es un archivo de prueba'
]
],
'headers' => [
'Authorization' => 'Bearer tu-token-aqui',// si hace falta
'Accept'=> 'application/json'
]
]);

$body = (string) $response->getBody();
echo 'Archivo enviado correctamente!
    ';
echo 'Respuesta del servidor: ' . $body;
    En el servidor hay que hacer como cuando se suben fichero normales de un formulario:

    // 1. Crear carpeta si no existe
$uploadDir = __DIR__ . '/uploads/';
if (!is_dir($uploadDir)) {
mkdir($uploadDir, 0755, true);
}

// 2. Verificar que llegó el archivo
if (isset($_FILES['file']) && $_FILES['file']['error'] === UPLOAD_ERR_OK) {

$nombreOriginal = $_FILES['file']['name'];
$tmpName= $_FILES['file']['tmp_name'];

// Puedes cambiar el nombre o ponerle timestamp para evitar sobreescribir
$nuevoNombre = date('Ymd_His_') . basename($nombreOriginal);
$rutaFinal= $uploadDir . $nuevoNombre;

// 3. Guardar el archivo
if (move_uploaded_file($tmpName, $rutaFinal)) {

echo json_encode([
  'status'  => 'success',
  'message' => 'Archivo guardado correctamente',
  'archivo' => $nuevoNombre,
  'ruta'=> '/uploads/' . $nuevoNombre,
  'tamaño'  => $_FILES['file']['size'] . ' bytes'
]);

// También puedes leer otros campos enviados
$usuario = $_POST['usuario'] ?? 'desconocido';
echo "\nUsuario recibido: " . $usuario;

} else {
http_response_code(500);
echo json_encode(['status' => 'error', 'message' => 'No se pudo guardar el archivo']);
}

} else {
http_response_code(400);
echo json_encode([
'status' => 'error',
'message' => 'No se recibió ningún archivo o hubo error',
'error_code' => $_FILES['file']['error'] ?? 'ninguno'
]);
}
  • Peticiones asíncronas:

    require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$promise = $client->getAsync('https://api.example.com/users', [
'headers' => [
'Accept' => 'application/json',
'Authorization' => 'Bearer tu-token'
],
'query' => ['page' => 1, 'limit' => 10]// parámetros GET
]);

$response = $promise->wait();// ← aquí espera la respuesta

$body = (string) $response->getBody();
$data = json_decode($body, true);

echo "Éxito! Código: " . $response->getStatusCode() . "\n";
print_r($data);
  • "$response->getStatusCode()": Devuelve el código de estado HTTP como número entero. Ejemplos comunes:
    • 200 → OK (todo bien).
    • 201 → Created (recurso creado).
    • 400 → Bad Request (error en los datos que enviaste).
    • 401 → Unauthorized (falta login).
    • 404 → Not Found.
    • 500 → Error del servidor.
  • "$response->getBody()": Devuelve el cuerpo (el contenido) de la respuesta. Es un stream.

¿Por qué es tan popular?