Gestion avancée des fichiers PHP 5

Autorisations, mise en cache et options de métadonnées

Le wrapper de flux App Engine pour Cloud Storage fournit les options suivantes pour configurer votre flux :

Option Valeurs possibles Description
acl Cette option peut prendre l'une des valeurs suivantes :
  • private
  • public-read
  • public-read-write
  • authenticated-read
  • bucket-owner-read
  • bucket-owner-full-control
  • project-private
Pour obtenir le détail de l'utilisation de ces paramètres dans Cloud Storage, consultez la section LCA prédéfinies. Si vous ne définissez pas l'option acl, Cloud Storage définit ce paramètre sur NULL et utilise la LCA de l'objet par défaut associée au bucket contenant le fichier.
Content-Type Tout type MIME de sortie valide Si vous ne spécifiez pas de type de contenu lorsque vous importez un objet, le système Google Cloud Storage utilise binary/octet-stream par défaut lors de la diffusion de l'objet.
Content-Disposition Toute valeur de disposition de contenu valide Il s'agit d'un en-tête que vous pouvez définir sur un objet spécifiant des informations présentant la manière dont les données de cet objet doivent être transmises.
Content-Encoding Tout algorithme de compression valide Il s'agit de l'algorithme de compression d'un objet, tel que gzip. Notez que Google Cloud Storage ne compresse ni ne décompresse automatiquement les objets en fonction de cet en-tête.
Content-Language Tout code de langue ISO 639-1 valide Il s'agit du code de langue ISO 639-1 du contenu. Pour en obtenir la liste complète, consultez la page Codes for the Representation of Names of Languages (Codes de représentation des noms de langues).
enable_cache TRUE ou FALSE (TRUE par défaut) Les fichiers lus à partir de Cloud Storage sont mis en cache dans la mémoire afin d'améliorer les performances. Pour en savoir plus, consultez l'article memcache. La mise en cache peut être désactivée à l'aide de la directive enable_cache dans le contexte du flux.
enable_optimistic_cache TRUE ou FALSE (FALSE par défaut) Vous pouvez activer la mise en cache optimiste afin de lire l'objet fichier à partir du cache sans vérifier si l'objet sous-jacent a été modifié dans Cloud Storage depuis sa dernière mise en cache. Cette solution convient parfaitement aux scénarios de type WORM (Write Once Read Many).
metadata Un tableau associatif, par exemple ['foo' => 'far', 'bar' => 'boo'] Consultez la section Lire et écrire des métadonnées personnalisées.
read_cache_expiry_seconds Nombre de secondes pendant lesquelles un objet restera valide dans le cache Vous pouvez définir la durée pendant laquelle un objet mis en cache reste valide à l'aide de la fonction read_cache_expiry_seconds directive. Elle spécifie le délai au bout duquel l'objet sera remis en cache lors de la prochaine tentative de lecture. Par défaut, ce paramètre est défini sur 1 heure (3 600 secondes).
writable_cache_expiry_seconds Nombre de secondes pendant lesquelles l'état accessible en écriture d'un bucket est mis en cache Le service de wrapper de flux Cloud Storage met en cache l'état accessible en écriture des buckets afin d'améliorer les performances. Cela signifie que les bits accessibles en écriture renvoyés par diverses fonctions liées à stat() sont susceptibles d'être temporairement désynchronisés en cas de modification de la LCA du bucket. Par défaut, ce paramètre est défini sur 10 minutes (600 secondes).

L'extrait suivant indique comment utiliser les options de flux :

$options = ['gs' => ['Content-Type' => 'text/plain']];
$context = stream_context_create($options);
file_put_contents("gs://${my_bucket}/hello_options.txt", $newFileContent, 0, $context);

Dans l'extrait de code ci-dessus, $options correspond à un ensemble d'arguments que le flux utilisera lors de l'écriture de nouveaux objets, qui peuvent être définis comme options par défaut à l'aide de stream_context_set_default.

Compatibilité des fonctions du système de fichiers PHP 5 sur Cloud Storage

Le wrapper de flux App Engine pour Cloud Storage est compatible avec de nombreuses fonctions natives du système de fichiers PHP. Certaines fonctions ne sont pas compatibles et d'autres ont été modifiées. La table suivante répertorie chacune de ces fonctions natives, en indiquant si la fonction est compatible ou non. Si la compatibilité d'une fonction présente des modifications ou des limitations, celles-ci sont décrites.

Fonction du système de fichiers Compatibilité Détails
basename : renvoie le nom de la composante finale d'un chemin d'accès Compatible
chgrp : modifie le groupe d'un fichier Non compatible Renvoie toujours false
chmod : modifie le mode d'un fichier Non compatible Renvoie toujours false
chown : modifie le propriétaire d'un fichier Non compatible Renvoie toujours false
clearstatcache : efface le cache spécifique à l'état d'un fichier Compatible
copy : copie le fichier Compatible
dirname : renvoie le chemin d'accès au répertoire parent Compatible Compatible, mais inclut le préfixe gs://.
disk_free_space : renvoie la quantité d'espace disponible sur le système de fichiers ou la partition de disque Non compatible Cette fonction est désactivée.
disk_total_space : renvoie la taille totale d'un système de fichiers ou d'une partition de disque Non compatible Cette fonction est désactivée.
diskfreespace : alias de "disk_free_space"
fclose : ferme un pointeur de fichier ouvert Compatible
feof : teste la fin d'un fichier sur un pointeur de fichier Compatible
fflush : envoie tout le contenu généré dans un fichier Compatible Aucun effet (Renvoie toujours true)
fgetc : récupère un caractère à partir d'un pointeur de fichier Compatible
fgetcsv : récupère une ligne à partir d'un pointeur de fichier et analyse les champs CSV Compatible
fgets : récupère une ligne à partir d'un pointeur de fichier Compatible
fgetss : récupère une ligne à partir d'un pointeur de fichier et supprime les balises HTML Compatible
file_exists : vérifie si un fichier ou un répertoire existe Compatible
file_get_contents : lit l'intégralité d'un fichier dans une chaîne Compatible
file_put_contents : écrit une chaîne dans un fichier Compatible
file : lit l'intégralité d'un fichier dans un tableau Compatible
fileatime : récupère l'heure du dernier accès au fichier Non compatible Renvoie toujours 0
filectime : récupère l'heure de modification de l'inode d'un fichier Non compatible Renvoie toujours 0
filegroup : récupère le groupe d'un fichier Non compatible Renvoie toujours 0
fileinode : récupère le nœud d'index d'un fichier Non compatible Renvoie toujours 0
filemtime : récupère l'heure de modification d'un fichier Compatible
fileowner : récupère le propriétaire d'un fichier Non compatible Renvoie toujours 0
fileperms : récupère les autorisations de fichier Compatible Le bit d'exécution est toujours désactivé.
filesize : récupère la taille d'un fichier. Compatible
filetype : récupère le type d'un fichier Compatible
flock : procède au verrouillage recommandé d'un fichier via une interface portable Non compatible Renvoie toujours false
fopen : ouvre un fichier ou une URL Compatible Seuls les modes suivants sont acceptés : r, rb, rt, w, wb, wt.
fpassthru : affiche toutes les données restantes sur un pointeur de fichier Compatible
fputcsv : met la ligne au format CSV et écrit dans le pointeur de fichier Compatible
fputs : alias de "fwrite"
fread : lit un fichier en mode binaire Compatible
fscanf : analyse l'entrée d'un fichier en fonction d'un format spécifique Compatible
fseek : effectue une recherche sur un pointeur de fichier Compatible Compatible uniquement avec les fichiers ouverts en mode lecture
fstat : récupère des informations sur un fichier à l'aide d'un pointeur de fichier ouvert Compatible
ftell : renvoie la position actuelle du pointeur de fichier en lecture/écriture Compatible
ftruncate : tronque un fichier à une longueur donnée Non compatible Renvoie toujours false
fwrite : écrit un fichier en mode binaire Compatible
glob : recherche des chemins d'accès correspondant au masque "pattern". Compatible
is_dir : indique si le nom du fichier correspond à un répertoire Compatible
is_executable : indique si le nom du fichier correspond à un exécutable Non compatible Renvoie toujours false
is_file : indique si le nom du fichier correspond à un fichier standard Compatible
is_link : indique si le nom du fichier correspond à un lien symbolique Non compatible Renvoie toujours false
is_readable : indique si un fichier existe et s'il est lisible Compatible
is_uploaded_file : indique si un fichier a été téléchargé via HTTP POST Compatible
is_writable : indique si le nom du fichier est accessible en écriture Compatible La valeur est mise en cache, et les modifications d'autorisations sont susceptibles de ne pas être appliquées immédiatement.
is_writeable : alias de "is_writable"
lchgrp : modifie le groupe propriétaire d'un lien symbolique Non compatible Cette fonction est désactivée.
lchown : modifie l'utilisateur propriétaire d'un lien symbolique Non compatible Cette fonction est désactivée.
link : crée un lien physique Non compatible Cette fonction est désactivée.
linkinfo : récupère des informations sur un lien Non compatible Renvoie toujours -1
lstat : fournit des informations sur un fichier ou un lien symbolique Compatible
mkdir : crée un répertoire Compatible
move_uploaded_file : déplace un fichier téléchargé vers un nouvel emplacement Compatible
parse_ini_file : analyse un fichier de configuration Compatible
pathinfo : renvoie des informations sur le chemin d'accès à un fichier Compatible
pclose : ferme un processus de pointeur de fichier Non compatible Cette fonction est désactivée.
popen : ouvre un processus de pointeur de fichier Non compatible Cette fonction est désactivée.
readfile : affiche un fichier Compatible
readlink : renvoie la cible d'un lien symbolique Non compatible Renvoie toujours false
realpath : renvoie le nom absolu canonisé du chemin d'accès Non compatible Renvoie toujours false
rename : renomme un fichier ou un répertoire Compatible
rewind : replace le pointeur de fichier au début Compatible Compatible uniquement en mode lecture
rmdir : supprime le répertoire Compatible
set_file_buffer : alias de "stream_set_write_buffer"
stat : fournit des informations sur un fichier Compatible
symlink : crée un lien symbolique Non compatible Cette fonction est désactivée.
tempnam : crée un fichier avec un nom de fichier unique Compatible Consultez ces notes.
tmpfile : crée un fichier temporaire Compatible Renvoie un fichier stocké en mémoire, semblable à php://memory.
touch : définit l'heure d'accès et de modification d'un fichier Non compatible Renvoie toujours false
umask : modifie l'attribut "umask" actuel Compatible Cette fonction ne s'applique pas aux fichiers Cloud Storage.
unlink : supprime un fichier Compatible

Notez que les fonctions "stat" du fichier du tableau ci-dessus (file_exists, filemtime, filesize, fstat, is_file, is_dir, is_writable et stat ) sont mises en cache à la demande. Vous pouvez vider ce cache en appelant la fonction clearstatcache.

De plus, les fonctions de lecture de répertoire PHP suivantes sont compatibles :

Nom de la fonction
opendir
readdir
rewinddir
closedir

Utiliser les fonctions PHP include et require

Pour aider à garantir la sécurité de l'application, la possibilité d'utiliser les fonctions include ou require à partir d'un fichier Cloud Storage est désactivée par défaut, mais vous pouvez l'activer comme suit :

Pour utiliser les fonctions include ou require afin d'inclure à l'application du code PHP provenant de Google Cloud Storage, vous devez spécifier les buckets contenant ces fichiers à l'aide de la directive google_app_engine.allow_include_gs_buckets dans le fichier php.ini.

Lire et écrire des métadonnées personnalisées

Pour associer des métadonnées personnalisées à un fichier en cours d'écriture sur Google Cloud Storage, ajoutez-les à $options avant de créer le contexte de flux utilisé pour l'appel file_put_contents.

Dans cet exemple, les métadonnées nommées foo reçoivent la valeur far, tandis qu'une autre nommée bar reçoit la valeur boo. L'exemple définit également le type de contenu sur text/plain. Le contexte du flux est créé à l'aide de ces informations dans $options, comme indiqué. Le fichier est écrit dans Cloud Storage à l'aide de file_put_contents(), avec les métadonnées et le type de contenu :

$metadata = ['foo' => 'bar', 'baz' => 'qux'];
$options = [
    'Content-Type' => 'text/plain',
    'metadata' => $metadata
];
$context = stream_context_create(['gs' => $options]);
file_put_contents("gs://${my_bucket}/hello_metadata.txt", $newFileContent, 0, $context);

Pour lire les métadonnées et le type de contenu personnalisés d'un fichier, appelez la fonction fopen sur le fichier, puis utilisez CloudStorageTools::getContentType() pour obtenir le type de contenu, et CloudStorageTools::getMetaData() pour obtenir les métadonnées.

Les métadonnées et le type de contenu personnalisés sont disponibles une fois que le pointeur de fichier est renvoyé à partir de l'appel fopen.

$fp = fopen("gs://${my_bucket}/hello_metadata.txt", 'r');
$content_type = CloudStorageTools::getContentType($fp);
$metadata = CloudStorageTools::getMetaData($fp);

Mise en cache de fichiers lus

Par défaut, le wrapper de flux App Engine pour Cloud Storage met en cache les fichiers lus dans memcache afin d'améliorer les performances des prochaines lectures. La mise en cache peut être désactivée à l'aide de la directive enable_cache dans le contexte du flux.

Pour améliorer encore les performances, vous pouvez également activer la mise en cache optimiste, qui lira l'objet du fichier depuis le cache sans vérifier si l'objet sous-jacent a été modifié dans Google Cloud Storage depuis la dernière mise en cache. Pour cela, utilisez la directive enable_optimistic_cache (définie par défaut sur false). Cette solution convient parfaitement aux scénarios de type WORM (Write Once Read Many).

Vous pouvez également définir la durée pendant laquelle un objet mis en cache reste valide à l'aide de la directive read_cache_expiry_seconds. Passé ce délai, l'objet sera remis en cache lors de la prochaine tentative de lecture. Par défaut, ce paramètre est défini sur 1 heure (3600 secondes).

Dans cet exemple, la mise en cache optimiste est activée, et la configuration des objets fichier indique qu'ils doivent de nouveau être mis en cache à partir de Google Cloud Storage passé un délai de 5 minutes.

$options = [
    'gs' => [
        'enable_cache' => true,
        'enable_optimistic_cache' => true,
        'read_cache_expiry_seconds' => 300,
    ]
];
$context = stream_context_create($options);
file_put_contents("gs://${my_bucket}/hello_caching.txt", $newFileContent, 0, $context);