nwb/s3 (0.8.8)
Installation
{
"repositories": [{
"type": "composer",
"url": "composer require nwb/s3:0.8.8About this package
S3
Le module S3 est une bibliothèque PHP qui facilite l'interaction avec le service de stockage compatible S3 qu'il soit chez Amazon ou ailleurs. Il fournit une interface simple pour effectuer diverses opérations sur les objets stockés dans un compartiment S3, notamment le chargement, l'affichage, le téléchargement, la suppression, la vérification de l'existence et le listage des fichiers.
Installation
Composer
Ajouter les modules communs dans composer.json
{
"repositories": [{
"type": "composer",
"url": "https://git.nwb.fr/api/packages/modules-communs-php/composer"
}
]
}
Lancer la commande
composer require nwb/s3:0.*.*
Configuration
Pour utiliser le module S3, vous devez configurer certaines variables d'environnement. Voici la liste des variables nécessaires :
AWS_ACCESS_KEY_ID: votre clé d'accès AWS.AWS_SECRET_ACCESS_KEY: votre clé d'accès secrète AWS.AWS_REGION: la région AWS dans laquelle votre bucket S3 est hébergé.AWS_ENDPOINT: l'URL de l'API S3. Cette variable est facultative et n'est nécessaire que si vous utilisez un fournisseur S3 autre qu'AWS.AWS_BUCKET: le nom du bucket S3 que vous souhaitez utiliser.AWS_S3_ENCRYPTION_KEY: la clé de chiffrement à utiliser pour chiffrer et déchiffrer les données. Cette variable est facultative et n'est nécessaire que si vous souhaitez chiffrer les données (côté client) avant de les envoyer sur le système de stockage.
Vous pouvez définir ces variables dans votre fichier .env ou dans les paramètres de votre serveur.
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_REGION=your_region
export AWS_ENDPOINT=your_endpoint
export AWS_BUCKET=your_bucket_name
export AWS_S3_ENCRYPTION_KEY=your_optional_encryption_key
Configuration Additionnelle de la Classe ConfigS3
La plupart du temps il n'est pas nécessaire de configurer la classe ConfigS3 car les paramètres sont récupérés depuis les variables d'environnement. Cependant, pour des tests unitaires ou des transferts, il est possible, de configurer la classe ConfigS3 en utilisant la méthode setConfig comme ci-dessous :
$config = new ConfigS3();
$config->setConfig([
'accessKey' => 'votre_access_key',
'secretKey' => 'votre_secret_key',
'region' => 'votre_region',
'bucket' => 'votre_bucket',
'endpoint' => 'votre_endpoint',
'encryptionKey' => 'votre_clé_de_chiffrement_optionnelle'
]);
Utilisation
$s3 = new S3();
Upload d'un Fichier
$result = $s3->upload('chemin/du/fichier/local', 'chemin/du/seau/nom_du_fichier.jpg');
Upload d'un Fichier Public
$result = $s3->upload('chemin/du/fichier/local', 'chemin/du/seau/nom_du_fichier.jpg', true);
La méthode renverra une exception, si le bucket n'autorise pas l'envoi de fichiers public avec ACL.
Affichage d'un Fichier S3 dans le Navigateur
$s3->show('chemin/du/seau/nom_du_fichier.jpg');
Téléchargement d'un Fichier
$s3->download('chemin/du/seau/nom_du_fichier.jpg', 'chemin/du/fichier/local');
Suppression d'un Fichier sur S3
$result = $s3->delete('chemin/du/seau/nom_du_fichier.jpg');
listFiles
$files = $s3->listFiles('chemin/du/seau/', true); // Le second paramètre à 'true' pour un listage récursif
foreach ($files as $file) {
echo $file . PHP_EOL;
}
Vérification de l'Existence d'un Fichier sur S3
$existe = $s3->fileExists('dossier/seau/nom_du_fichier.jpg');
if ($existe) {
echo "Le fichier existe sur S3.";
} else {
echo "Le fichier n'existe pas sur S3.";
}
Déplacement d'un Fichier vers S3
$result = $s3->moveToS3('chemin/du/fichier/local', 'chemin/du/seau/nom_du_fichier.jpg');
Correspond à upload, mais supprime le fichier local une fois que le fichier a été envoyé à S3.
Upload d'un Fichier avec Durée de Vie
La durée de vie est exprimée en jour, et le fichier sera supprimé automatiquement par le fournisseur une fois que la durée de vie sera écoulée.
$result = $s3->uploadWithExpiration('chemin/du/fichier/local', 'chemin/du/seau/nom_du_fichier.jpg', 1, true);
Création d'un Dossier
La méthode createFolder permet de créer un nouveau dossier (également appelé "préfixe") dans votre bucket S3. Bien que S3 n'ait pas de concept de dossiers natifs, vous pouvez simuler une structure de dossiers en utilisant des préfixes dans les noms de fichiers.
Exemple d'Utilisation
$s3 = new S3();
$folderName = 'nouveau/dossier/';
$s3->createFolder($folderName);
⚠️ Notez que la création d'un dossier dans S3 ne crée pas réellement de structure de dossiers, mais plutôt un préfixe commun pour les objets stockés dans ce "dossier".
Exemple d'Utilisation de la Méthode uploadFromForm
Pour utiliser la méthode uploadFromForm, vous pouvez créer un formulaire HTML qui permet aux utilisateurs de télécharger un fichier. Voici un exemple :
$s3 = new S3();
try {
$result = $s3->uploadFromForm('file', 'chemin/du/seau/nom_du_fichier.jpg');
echo "Fichier uploadé avec succès : " . $result;
} catch (\Exception $e) {
echo "Erreur : " . $e->getMessage();
}
Exemple d'Utilisation de la Méthode getPublicUrl
La méthode getPublicUrl permet de générer l'URL d'accès à un fichier uploadé en publique sur S3.
$s3 = new S3();
$key = 'chemin/du/seau/nom_du_fichier.jpg';
$publicUrl = $s3->getPublicUrl($key);
echo "L'URL publique du fichier est : " . $publicUrl;
Suppression d'un Dossier
La méthode deleteFolder permet de supprimer un dossier et tout son contenu de votre bucket S3. Cette opération supprimera récursivement tous les objets ayant le préfixe du dossier spécifié.
$s3 = new S3();
$folderName = 'dossier/a/supprimer/';
$s3->deleteFolder($folderName);
echo "Le dossier '$folderName' et tout son contenu ont été supprimés avec succès.";
Dans cet exemple, nous supprimons le dossier spécifié par $folderName et tous les objets qu'il contient. Tous les fichiers ayant le préfixe dossier/a/supprimer/ seront supprimés de votre bucket S3.
⚠️ Soyez prudent lors de l'utilisation de la méthode deleteFolder, car elle supprimera de manière permanente tous les objets contenus dans le dossier spécifié. Assurez-vous de fournir le bon chemin de dossier et de confirmer que vous souhaitez supprimer définitivement son contenu.
Génération d'URL présignées
La méthode getPresignedUrl permet de générer une URL présignée pour un accès temporaire à un fichier stocké sur S3. Cette URL peut être partagée avec d'autres personnes ou utilisée pour accéder directement au fichier sans authentification supplémentaire pendant une durée limitée.
Avantages
- Accès Temporaire : Permet de fournir un accès temporaire à un fichier sans avoir à gérer l'authentification ou à exposer les clés d'accès S3.
- Contrôle d'Accès : Vous pouvez spécifier une durée de validité pour l'URL présignée, limitant ainsi la fenêtre d'accès au fichier.
- Simplicité : Génère une URL unique qui peut être facilement partagée ou intégrée dans d'autres applications.
Exemple d'Utilisation
$s3 = new S3();
$filePath = 'chemin/dans/bucket/nom_du_fichier.jpg';
$expiration = '+10 minutes';
$presignedUrl = $s3->getPresignedUrl($filePath, $expiration);
echo "URL présignée : " . $presignedUrl;
Dans cet exemple, nous générons une URL présignée pour le fichier spécifié par $filePath. L'URL sera valide pendant 10 minutes, comme indiqué par le paramètre $expiration. Vous pouvez ajuster la durée d'expiration selon vos besoins.
L'URL présignée générée peut être utilisée pour accéder directement au fichier via un navigateur web ou pour le télécharger programmatiquement sans avoir besoin d'une authentification supplémentaire pendant la période de validité spécifiée.
⚠️ Notez que les URL présignées doivent être générées avec précaution et partagées de manière sécurisée, car elles permettent un accès direct au fichier sans authentification supplémentaire pendant la période de validité.
⚠️ Attention, si les fichiers sont cryptés côté client par la classe le fichier sera illisible. Dans ce cas, il est préférable d'utiliser la méthode show() dans une page dédiée qui s'occupe de vérifier l'authentification.
UploadResource
La méthode uploadResource permet d'envoyer une ressource vers un stockage d'objets S3. Contrairement à l'envoi de fichiers par chemin, cette méthode vous permet d'envoyer des données directement depuis une ressource PHP. Cela est particulièrement utile lorsque vous travaillez avec des flux de données ou lorsque les données proviennent d'une source autre qu'un fichier local, comme une entrée utilisateur, une base de données ou un traitement intermédiaire.
Avantages
Flexibilité : Permet d'envoyer des données depuis n'importe quelle source qui peut être représentée comme une ressource PHP. Efficacité : Réduit le besoin d'écrire temporairement des données sur le disque, ce qui peut améliorer les performances pour les opérations de grande taille ou fréquentes. Contrôle : Offre un contrôle plus fin sur le processus de lecture des données, ce qui peut être utile pour des cas d'utilisation avancés comme le streaming de données ou le traitement par lots. Exemple d'utilisation
$resource = fopen('/chemin/vers/le/fichier', 'r');
$s3->uploadResource($resource, 'chemin/de/destination/sur/s3.jpg');
DownloadResource
La méthode downloadResource permet de télécharger un fichier depuis S3 et de retourner une ressource de flux. Cela est utile pour manipuler ou accéder directement au contenu d'un fichier sans avoir besoin de l'enregistrer sur le système de fichiers local.
Avantages
Accès Direct : Permet de travailler directement avec le flux de données téléchargé, ce qui est utile pour le traitement en mémoire ou le streaming. Économie de Stockage : Élimine la nécessité de stocker
Dependencies
Dependencies
| ID | Version |
|---|---|
| aws/aws-sdk-php | 3.*.* |
| php | >=7 |
Development Dependencies
| ID | Version |
|---|---|
| phpunit/phpunit | * |
| squizlabs/php_codesniffer | * |