README

Une petite couche PHP au-dessus du SDK AWS pour stocker et récupérer des objets compatibles S3.

Elle fournit une API simple pour créer un bucket, vérifier l'existence d'un objet, envoyer des chaînes, ressources ou fichiers, récupérer leurs métadonnées, les supprimer et les lister.

Prérequis

PHP 8.5 ou supérieur
Un endpoint S3 et des identifiants AWS valides

Installation

composer require sopheos/pebble_s3

Le paquet installe automatiquement aws/aws-sdk-php.

Configuration

Créez un client du SDK AWS avec les paramètres adaptés à votre fournisseur S3 :

use Aws\S3\S3Client;
use Pebble\S3\Store;

$client = new S3Client([
    'version' => 'latest',
    'region' => 'eu-west-3',
    'credentials' => [
        'key' => $_ENV['AWS_ACCESS_KEY_ID'],
        'secret' => $_ENV['AWS_SECRET_ACCESS_KEY'],
    ],
]);

$store = (new Store())
    ->setClient($client)
    ->setBucket('mon-bucket');

Pour un endpoint S3 compatible (MinIO, Scaleway, etc.), ajoutez notamment endpoint et, selon le fournisseur, use_path_style_endpoint à la configuration du client AWS.

Opérations

Une fois le client configuré sur le Store, les méthodes disponibles sont les suivantes.

Buckets et existence

// Crée le bucket s'il n'existe pas. Retourne true s'il a été créé.
$created = $store->createBucket();

// Vérifie la présence d'un objet.
$exists = $store->has('documents/rapport.pdf');

Envoyer un objet

// Envoyer le contenu d'une chaîne ou d'une ressource PHP.
$store->set('notes/bonjour.txt', 'Bonjour !', 'text/plain');

// Envoyer un fichier local ; son type MIME est détecté automatiquement.
$store->setFile('images/logo.png', '/chemin/vers/logo.png');

set() accepte une chaîne, une ressource, un stream PSR-7 (StreamInterface) ou une instance Imagick ; dans ce dernier cas, le type MIME de l'image est utilisé s'il est connu. setFile() exige un chemin vers un fichier existant.

Lire un objet

$item = $store->get('notes/bonjour.txt');

if ($item !== null) {
    $stream = $item->body();       // Stream PSR-7, rembobiné par défaut
    $type = $item->type;           // par exemple : text/plain
    $length = $item->length;       // taille en octets
    $timestamp = $item->date;      // date de modification Unix
    $etag = $item->etag;
}

get() retourne null si la clé est absente. Pour obtenir une ressource PHP native, utilisez $item->createResource() ; cette opération détache le flux PSR-7.

Supprimer et lister

// La suppression d'une clé absente est considérée comme réussie.
$store->delete('notes/bonjour.txt');

// Renvoie les clés en erreur ; les suppressions sont regroupées par lots de 1 000.
$failedKeys = $store->deleteMany(['a.txt', 'b.txt']);

// Itère sur toutes les clés, éventuellement sous un préfixe.
foreach ($store->list('images/') as $key) {
    echo $key, PHP_EOL;
}

Parcourir par lots

IterableHelper::chunk() découpe n'importe quel itérable (tableau ou générateur) en lots de taille fixe, sans le charger entièrement en mémoire. Le dernier lot peut être plus petit.

C'est pratique pour traiter le résultat de list(), qui est un générateur paginé :

use Pebble\S3\IterableHelper;

// Supprimer tous les objets sous un préfixe, 1 000 clés à la fois.
foreach (IterableHelper::chunk($store->list('tmp/'), 1000) as $keys) {
    $failedKeys = $store->deleteMany($keys);
}

Les clés de l'itérable d'origine ne sont pas conservées : chaque lot est une liste indexée à partir de 0.

Gestion des erreurs

Les erreurs renvoyées par S3 sont propagées sous forme de Aws\Exception\AwsException, à l'exception des objets absents traités par has(), get() et delete(). Les entrées invalides des méthodes d'écriture génèrent une InvalidArgumentException.

Licence

Distribué sous licence MIT.

sopheos / pebble_s3

Package info

Security

Statistics