Gestion avancée des fichiers PHP 5

Cette API est compatible avec les environnements d'exécution de première génération et peut être utilisée lors de la mise à niveau vers des environnements d'exécution de deuxième génération correspondants. Si vous effectuez une mise à jour vers l'environnement d'exécution PHP 7/8 d'App Engine, consultez le guide de migration pour en savoir plus sur les options de migration des anciens services groupés.

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

Remarque : Les opérations de création de listes de Cloud Storage étant cohérentes à terme, la fonction readdir est susceptible de ne pas appliquer les modifications immédiatement après l'ajout, le changement de nom ou la suppression d'un objet.

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.

Remarque : Lorsque la mise en cache est activée, les fichiers lus à partir de Cloud Storage sont mis en cache au fur et à mesure de leur lecture. Ce cache contient également les informations de fichier concernant l'écriture. Gardez donc à l'esprit que is_writable peut interroger des informations de fichiers obsolètes. De plus, si vous modifiez la LCA d'un bucket Cloud Storage pour octroyer ou refuser des autorisations d'écriture à l'application, cette modification peut prendre un certain temps avant d'être appliquée.

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);