Administración avanzada de archivos de PHP 5

Esta API es compatible con entornos de ejecución de primera generación y se puede usar en actualizaciones a los entornos de ejecución de segunda generación correspondientes. Si quieres actualizar al entorno de ejecución de PHP 7/8 de App Engine, consulta la guía de migración para obtener información sobre tus opciones de migración para servicios empaquetados heredados.

Opciones de permisos, almacenamiento en caché y metadatos

El wrapper de transmisión de App Engine para Cloud Storage ofrece las siguientes opciones a fin de configurar tu transmisión:

Opción	Valores posibles	Descripción
acl	Uno de los siguientes valores: private public-read public-read-write authenticated-read bucket-owner-read bucket-owner-full-control project-private	Para obtener descripciones de las acciones que realizan los parámetros de esta configuración en Cloud Storage, consulta las LCA predefinidas. Si no configuras acl, Cloud Storage establece este parámetro como nulo y usa la LCA de objeto predeterminada asociada con el bucket que contiene el archivo.
Content-Type	Cualquier tipo MIME válido	Si no especificas un tipo de contenido cuando subes un objeto, el sistema de Google Cloud Storage configura de forma predeterminada binary/octet-stream cuando entrega el objeto.
Content-Disposition	Cualquier valor de disposición de contenido válido	Un encabezado que puedes configurar en un objeto que especifica información de presentación sobre cómo se deben transmitir los datos del objeto.
Content-Encoding	Cualquier algoritmo de compresión válido	El algoritmo de compresión para el objeto, como gzip. Ten en cuenta que Google Cloud Storage no comprime ni descomprime de manera automática los objetos basados en este encabezado.
Content-Language	Cualquier código de lenguaje ISO 639-1 válido	El código de lenguaje ISO 639-1 del contenido (consulta Códigos para la representación de nombres de lenguajes a fin de obtener una lista completa).
enable_cache	verdadero o falso (verdadero por configuración predeterminada)	Los archivos que se leen desde Cloud Storage se almacenan en la memoria caché (consulta memcache) para una mejora en el rendimiento. El almacenamiento en caché se puede desactivar mediante la directiva enable_cache en el contexto de transmisión.
enable_optimistic_cache	verdadero o falso (falso por configuración predeterminada)	Puedes habilitar almacenamiento en caché optimista para leer el objeto del archivo desde la caché sin verificar si el objeto subyacente cambió en Cloud Storage desde la última vez que se almacenó en caché. El almacenamiento en caché optimista es ideal para situaciones de escritura única y lecturas múltiples.
metadata	Un arreglo asociado, p. ej.	['foo' => 'far', 'bar' => 'boo'] Consulta Lectura y escritura de metadatos personalizados.
read_cache_expiry_seconds	La cantidad de segundos de validez de un objeto en caché	Puedes cambiar la cantidad de tiempo que un objeto almacenado en caché permanece válido mediante el uso de read_cache_expiry_seconds directive. Esto especifica el tiempo después del cual el objeto volverá a almacenarse en caché en el próximo intento de lectura. Se configura de manera predeterminada en 1 hora (3600).
writable_cache_expiry_seconds	La cantidad de segundos que se almacena en caché el estado que admite escritura de un depósito	El wrapper de transmisión de Cloud Storage almacena en caché los estados que admiten escritura de los depósitos para mejorar el rendimiento. Esto significa que los bits que admiten escritura devueltos por varias funciones relacionadas con estadísticas() pueden no estar sincronizados de forma temporal cuando cambia la LCA del depósito. Se configura de manera predeterminada en 10 minutos (600).

En el siguiente fragmento, se muestra cómo usar las opciones de transmisión:

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

En el fragmento anterior, $options es un conjunto de argumentos que la transmisión usará cuando escriba objetos nuevos, que se pueden configurar como opciones predeterminadas mediante stream_context_set_default.

Compatibilidad de funciones de sistema de archivos de PHP 5 en Cloud Storage

El wrapper de transmisión de App Engine para Cloud Storage admite muchas funciones nativas del sistema de archivos PHP. Algunas funciones no se admiten, y algunas tienen una compatibilidad modificada. La tabla siguiente enumera cada una de esas funciones nativas y muestra si la función es compatible o no. Si una función es compatible, pero con modificaciones o limitaciones, eso se describe.

Función del sistema de archivos	¿Es compatible?	Detalles
basename — Muestra el componente de nombre final de la ruta.	Compatible.
chgrp — Cambia el grupo de archivos.	No compatible.	Siempre muestra false.
chmod: Cambia el modo de archivos.	No compatible.	Siempre muestra false.
chown: Cambia el propietario del archivo.	No compatible.	Siempre muestra false.
clearstatcache: Borra la caché de estado de archivos.	Compatible.
copy — Copia archivos.	Compatible.
dirname — Muestra la ruta del directorio superior.	Compatible.	Compatible, pero incluye el prefijo gs://.
disk_free_space: Muestra el espacio disponible en el sistema de archivos o en la partición de disco.	No compatible.	Está inhabilitada.
disk_total_space — Muestra el tamaño total de un sistema de archivos o de una partición de disco.	No compatible.	Está inhabilitada.
diskfreespace — Alias de disk_free_space.
fclose — Cierra un puntero de archivo abierto.	Compatible.
feof — Prueba el final de archivo en un puntero de archivo.	Compatible.
fflush — Limpia el resultado de un archivo.	Compatible.	Sin efecto. (Siempre muestra true).
fgetc: Obtiene el carácter del puntero del archivo.	Compatible.
fgetcsv — Obtiene la línea del puntero del archivo y analiza los campos CSV.	Compatible.
fgets — Obtiene la línea del puntero del archivo.	Compatible.
fgetss — Obtiene la línea del puntero del archivo y quita las etiquetas HTML.	Compatible.
file_exists — Comprueba si existe un archivo o un directorio.	Compatible.
file_get_contents — Lee un archivo completo y lo convierte en una string.	Compatible.
file_put_contents — Convierte una string en un archivo.	Compatible.
file — Lee un archivo completo y lo convierte en un arreglo.	Compatible.
fileatime — Obtiene la hora del último acceso al archivo.	No compatible.	Siempre muestra 0.
filectime — Obtiene la hora de cambio de inodo del archivo.	No compatible.	Siempre muestra 0.
filegroup — Obtiene un grupo de archivos.	No compatible.	Siempre muestra 0.
fileinode — Obtiene el inodo de archivos.	No compatible.	Siempre muestra 0.
filemtime — Obtiene la hora de modificación del archivo.	Compatible.
fileowner — Obtiene el propietario del archivo.	No compatible.	Siempre muestra 0.
fileperms — Obtiene los permisos del archivo.	Compatible.	El bit de ejecución está siempre desactivado.
filesize — Obtiene el tamaño del archivo.	Compatible.
filetype — Obtiene el tipo de archivo.	Compatible.
flock — Bloqueo de archivo de asesoría portátil.	No compatible.	Siempre muestra false.
fopen — Abre un archivo o URL.	Compatible.	Solo es compatible con estos modos: r, rb, rt, w, wb y wt.
fpassthru — Pone en el búfer todos los datos restantes desde un puntero de archivo.	Compatible.
fputcsv — Formatea la línea como CSV y la escribe en un puntero de archivo.	Compatible.
fputs — Alias de fwrite.
fread — Lectura de archivo binario seguro.	Compatible.
fscanf — Analiza la entrada desde un archivo de acuerdo con un formato.	Compatible.
fseek — Busca en un puntero de archivo.	Compatible.	Solo es compatible con archivos que se abren mediante el modo lectura.
fstat — Obtiene información sobre un archivo mediante un puntero de archivo abierto.	Compatible.
ftell — Muestra la posición actual del puntero de archivo de lectura y escritura.	Compatible.
ftruncate — Trunca un archivo en una longitud determinada.	No compatible.	Siempre muestra false.
fwrite — Escritura de archivo binario seguro.	Compatible.
glob — Encuentra nombres de ruta que coinciden con un patrón.	Compatible.
is_dir — Indica si el nombre de archivo es un directorio.	Compatible.
is_executable — Indica si el nombre de archivo es ejecutable.	No compatible.	Siempre muestra false.
is_file: Indica si el nombre de archivo es un archivo normal.	Compatible.
is_link — Indica si el nombre de archivo es un vínculo simbólico.	No compatible.	Siempre muestra false.
is_readable — Indica si el archivo existe y si es legible.	Compatible.
is_uploaded_file — Indica si el archivo se subió a través de HTTP POST.	Compatible.
is_writable — Indica si el nombre de archivo admite escritura.	Compatible.	El valor se almacena en caché y es posible que no refleje los cambios en los permisos de manera inmediata.
is_writeable — Alias de is_writable.
lchgrp — Cambia la propiedad del grupo del vínculo simbólico.	No compatible.	Está inhabilitada.
lchown — Cambia la propiedad del usuario del vínculo simbólico.	No compatible.	Está inhabilitada.
link — Crea un vínculo duro.	No compatible.	Está inhabilitada.
linkinfo — Obtiene información sobre un vínculo.	No compatible.	Siempre muestra -1.
lstat: Brinda información sobre un archivo o vínculo simbólico.	Compatible.
mkdir — Crea un directorio.	Compatible.
move_uploaded_file — Transfiere un archivo subido a una ubicación nueva.	Compatible.
parse_ini_file — Analiza un archivo de configuración.	Compatible.
pathinfo — Muestra información sobre una ruta de archivo.	Compatible.
pclose — Cierra el puntero de archivo de proceso.	No compatible.	Está inhabilitada.
popen — Abre el puntero de archivo de proceso.	No compatible.	Está inhabilitada.
readfile — Lee un archivo y lo pone en el búfer.	Compatible.
readlink — Muestra el objetivo de un vínculo simbólico.	No compatible.	Siempre muestra false.
realpath: Muestra el nombre de ruta absoluta canonicalizada.	No compatible.	Siempre muestra false.
rename: Cambia el nombre de un archivo o directorio.	Compatible.
rewind — Retrocede la posición de un puntero de archivo.	Compatible.	Compatible solo para modo lectura.
rmdir — Quita el directorio.	Compatible.
set_file_buffer — Alias de stream_set_write_buffer.
stat — Brinda información sobre un archivo.	Compatible.
symlink — Crea un vínculo simbólico.	No compatible.	Está inhabilitada.
tempnam — Crea un archivo con un nombre de archivo único.	Compatible.	Consulta estas notas.
tmpfile — Crea un archivo temporal.	Compatible.	Muestra un archivo con memoria con copia de seguridad similar a php://memory.
touch: Configura la hora de modificación y acceso de un archivo.	No compatible.	Siempre muestra false.
umask: Cambia la umask actual.	Compatible.	No se aplica a los archivos de Cloud Storage.
unlink — Borra un archivo.	Compatible.

Ten en cuenta que las funciones de estadísticas del archivo en la tabla anterior (file_exists, filemtime, filesize, fstat, is_file, is_dir, is_writable, y stat) se almacenan en caché por solicitud. Puedes borrar esta caché si llamas a clearstatcache.

Además, las siguientes funciones de lectura de directorio PHP son compatibles:

Nombre de la función
opendir
readdir
rewinddir
closedir

Nota: Debido a que las operaciones de listado de Cloud Storage tienen coherencia eventual, es posible que readdir no refleje el cambio de forma inmediata después de agregar, quitar o cambiar el nombre de un objeto.

Usa include y require de PHP 5.

Para ayudar a mantener la seguridad de la aplicación, la capacidad de include o require de un archivo de Cloud Storage se inhabilita de forma predeterminada, pero puedes habilitarla de la siguiente manera:

Para include o require código PHP de Google Cloud Storage en la aplicación, debes especificar qué depósitos contienen esos archivos mediante la directiva google_app_engine.allow_include_gs_buckets en el archivo php.ini.

Lee y escribe metadatos personalizados

Para conectar metadatos personalizados a un archivo que se escribe en Google Cloud Storage, agrega los metadatos a $options antes de crear el contexto de la transmisión que se usa para la llamada a file_put_contents.

En este ejemplo, los metadatos llamados foo reciben el valor far, y otros llamados bar reciben el valor boo. En el ejemplo, también se establece el tipo de contenido en text/plain. El contexto de transmisión se crea mediante esta información en $options como se muestra, y el archivo se escribe en Cloud Storage con file_put_contents(), junto con los metadatos y el tipo de contenido:

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

Si deseas leer los metadatos personalizados y el tipo de contenido de un archivo, llama a fopen en el archivo y, luego, usa CloudStorageTools::getContentType() a fin de obtener el tipo de contenido y CloudStorageTools::getMetaData() para obtener los metadatos.

Los metadatos personalizados y el tipo de contenido están disponibles una vez que la llamada a fopen muestra el puntero del archivo.

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

Lecturas de archivo en caché

De forma predeterminada, el wrapper de transmisión de App Engine para Cloud Storage almacena en caché las lecturas de archivos en memcache a fin de mejorar el rendimiento en lecturas posteriores. El almacenamiento en caché se puede desactivar mediante la directiva enable_cache en el contexto de transmisión.

Nota: Cuando el almacenamiento en caché está habilitado, los archivos que se leen de Cloud Storage se almacenan en caché a medida que se leen, y la caché también contiene la información del archivo relacionada con la capacidad de escritura. Por lo tanto, ten en cuenta que is_writable puede buscar información de un archivo inactivo. También, si cambias la LCA en un bucket de Cloud Storage para otorgar o denegar permisos de escritura a la aplicación, este cambio puede llevar un tiempo en reflejarse.

Para mejorar aún más el rendimiento, también puedes habilitar el almacenamiento en caché optimista, que leerá el objeto de archivo de la caché sin ver si el objeto subyacente se cambió en Google Cloud Storage desde la última vez que se almacenó en caché, mediante la directiva enable_optimistic_cache (configurada como false de forma predeterminada). El almacenamiento en caché optimista es ideal para situaciones de escritura única y lecturas múltiples.

También puedes cambiar el período de validez de un objeto almacenado en caché mediante la directiva read_cache_expiry_seconds; después de ese período el objeto se volverá a almacenar en caché en el próximo intento de lectura. Se configura de manera predeterminada en 1 hora (3600).

En este ejemplo, el almacenamiento en caché optimista está activado y los objetos de archivo están configurados para volver a almacenarse en caché desde Google Cloud Storage después de 5 minutos.

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