Trabajo con S3 y almacenamiento en la nube en PHP: guía completa

Trabajo con S3 y almacenamiento en la nube en PHP

Los almacenes de objetos en la nube compatibles con el protocolo Amazon S3 (Simple Storage Service) se han convertido en el estándar de facto para almacenar archivos, imágenes, copias de seguridad y contenido estático. PHP proporciona potentes herramientas para la integración con almacenes como AWS S3, MinIO (self-hosted), DigitalOcean Spaces, Wasabi, Yandex Object Storage y otros. En este artículo, veremos en detalle cómo trabajar con almacenes compatibles con S3 en PHP, utilizando el AWS SDK oficial y bibliotecas alternativas.

Conceptos básicos de S3

Antes de pasar al código, es importante comprender los conceptos clave de S3:

• Bucket — contenedor para objetos (archivos). El nombre del bucket debe ser único a nivel global (para nubes públicas).
• Objeto (Object) — archivo y sus metadatos. Cada objeto tiene una clave (Key) — la ruta al archivo dentro del bucket.
• Región (Region) — ubicación geográfica del almacén.
• Credentials — clave de acceso (Access Key ID) y clave secreta (Secret Access Key) para la autenticación.
• Endpoint — URL del almacén (para servicios compatibles con S3 distintos de AWS, el endpoint es obligatorio).

Instalación del AWS SDK para PHP

La biblioteca oficial para trabajar con S3 es aws/aws-sdk-php. Instalación a través de Composer:

composer require aws/aws-sdk-php

Para trabajar con MinIO o DigitalOcean Spaces no se requieren dependencias adicionales — el SDK admite endpoints personalizados.

Configuración básica del cliente S3

Creemos un cliente para conectarse a AWS S3:

<?phprequire 'vendor/autoload.php';

use Aws\\S3\\S3Client;use Aws\\Exception\\AwsException;

$s3Client = new S3Client([    'version'     => 'latest',    'region'      => 'us-east-1',    'credentials' => [        'key'    => 'YOUR_ACCESS_KEY',        'secret' => 'YOUR_SECRET_KEY',    ],]);?>

Para MinIO (almacén local compatible con S3), la configuración se verá así:

<?php$s3Client = new S3Client([    'version'     => 'latest',    'region'      => 'us-east-1', // MinIO ignora la región    'endpoint'    => 'http://localhost:9000',    'use_path_style_endpoint' => true,    'credentials' => [        'key'    => 'minioadmin',        'secret' => 'minioadmin',    ],]);?>

Tenga en cuenta el parámetro use_path_style_endpoint — es necesario para MinIO y algunos almacenes que no son de AWS.

Gestión de buckets

Creación de un bucket

<?phptry {    $result = $s3Client->createBucket([        'Bucket' => 'my-php-bucket',    ]);    echo "Bucket creado: " . $result['Location'];} catch (AwsException $e) {    echo "Error: " . $e->getMessage();}?>

Verificar si un bucket existe

<?php$exists = $s3Client->doesBucketExist('my-php-bucket');if ($exists) {    echo "El bucket existe";} else {    echo "Bucket no encontrado";}?>

Listar todos los buckets

<?php$buckets = $s3Client->listBuckets();foreach ($buckets['Buckets'] as $bucket) {    echo $bucket['Name'] . " (creado: " . $bucket['CreationDate'] . ")<br>";}?>

Carga de archivos a S3

Carga desde una cadena (datos de texto)

<?phptry {    $result = $s3Client->putObject([        'Bucket' => 'my-php-bucket',        'Key'    => 'hello.txt',        'Body'   => 'Hello, S3 from PHP!',    ]);    echo "Archivo cargado. URL: " . $result['ObjectURL'];} catch (AwsException $e) {    echo "Error de carga: "