Gestione avanzata dei file PHP 5

Questa API è supportata per runtime di prima generazione e può essere utilizzata quando eseguire l'upgrade ai runtime di seconda generazione corrispondenti. Se esegui l'aggiornamento al runtime PHP 7/8 di App Engine, consulta la guida alla migrazione per scoprire di più sulle opzioni di migrazione per i servizi in bundle legacy.

Opzioni di autorizzazioni, memorizzazione nella cache e metadati

Il wrapper di flusso App Engine per Cloud Storage fornisce le seguenti opzioni per configurare il flusso:

Opzione	Valori possibili	Descrizione
acl	Uno dei seguenti valori: private public-read public-read-write authenticated-read bucket-owner-read bucket-owner-full-control project-private	Per le descrizioni di cosa fanno queste impostazioni in Cloud Storage, consulta ACL predefinite. Se non imposti acl, Cloud Storage imposta questo parametro come null e utilizza l'ACL oggetto predefinita associata al bucket che contiene il file.
Content-Type	Qualsiasi tipo MIME valido	Se non specifichi un tipo di contenuti quando carichi un oggetto, il sistema Google Cloud Storage utilizza binary/octet-stream come valore predefinito quando pubblica l'oggetto.
Content-Disposition	Qualsiasi valore di disposizione dei contenuti valido	Un'intestazione che puoi impostare su un oggetto che specifica le informazioni di presentazione su come devono essere trasmessi i dati dell'oggetto.
Content-Encoding	Qualsiasi algoritmo di compressione valido	L'algoritmo di compressione per l'oggetto, ad esempio gzip. Tieni presente che Google Cloud Storage non comprime o decomprime automaticamente gli oggetti in base a questa intestazione.
Content-Language	Qualsiasi codice lingua ISO 639-1 valido	Il codice lingua ISO 639-1 del contenuto (per un elenco completo, vedi Codes for the Representation of Names of Languages).
enable_cache	true o false (true per impostazione predefinita)	I file letti da Cloud Storage vengono memorizzati nella cache in memoria (vedi memcache) per migliorare le prestazioni. La memorizzazione nella cache può essere disattivata utilizzando l'istruzione enable_cache nel contesto dello stream.
enable_optimistic_cache	true o false (false per impostazione predefinita)	Puoi attivare la memorizzazione nella cache ottimistica per leggere l'oggetto file dalla cache senza verificare se l'oggetto sottostante è stato modificato in Cloud Storage dall'ultima volta che è stato memorizzato nella cache. La memorizzazione nella cache ottimistica è ideale per scenari di scrittura una sola volta e lettura molte volte.
metadata	Un array associativo, ad es.	['foo' => 'far', 'bar' => 'boo'] Consulta Lettura e scrittura di metadati personalizzati.
read_cache_expiry_seconds	Il numero di secondi per cui un oggetto rimarrà valido nella cache	Puoi modificare il periodo di tempo durante il quale un oggetto memorizzato nella cache rimane valido utilizzando read_cache_expiry_seconds directive. Specifica il tempo dopo il quale l'oggetto verrà memorizzato nuovamente nella cache al successivo tentativo di lettura. Per impostazione predefinita, questo valore è impostato su 1 ora (3600).
writable_cache_expiry_seconds	Il numero di secondi per cui viene memorizzato nella cache lo stato di scrittura di un bucket	Il wrapper di stream Cloud Storage memorizza nella cache lo stato di scrittura dei bucket per migliorare le prestazioni. Ciò significa che i bit scrivibili restituiti da varie funzioni correlate a stat() possono essere temporaneamente non sincronizzati quando l'ACL del bucket cambia. Per impostazione predefinita, questo valore è impostato su 10 minuti (600).

Il seguente snippet mostra come utilizzare le opzioni di stream:

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

Nello snippet precedente, $options è un insieme di argomenti che lo stream utilizzerà quando scrive nuovi oggetti, che possono essere impostati come opzioni predefinite utilizzando stream_context_set_default.

Supporto delle funzioni del file system PHP 5 su Cloud Storage

Il wrapper di stream App Engine per Cloud Storage supporta molte funzioni native del file system PHP. Alcune funzioni non sono supportate e alcune hanno un supporto modificato. La tabella seguente elenca ciascuna di queste funzioni native, indicando se la funzione è supportata o meno. Se una funzione è supportata, ma con modifiche o limitazioni, queste vengono descritte.

Funzione Filesystem	Supportato?	Dettagli
basename: restituisce il componente del nome finale del percorso.	Supportato.
chgrp: modifica il gruppo di file.	Non supportati.	Restituisce sempre false.
chmod: modifica la modalità file.	Non supportati.	Restituisce sempre false.
chown: modifica il proprietario del file.	Non supportati.	Restituisce sempre false.
clearstatcache: svuota la cache dello stato del file.	Supportato.
copy: copia il file.	Supportato.
dirname: restituisce il percorso della directory principale.	Supportato.	Supportato, ma include il prefisso gs://.
disk_free_space: restituisce lo spazio disponibile sul file system o sulla partizione del disco.	Non supportati.	Questa opzione è disabilitata.
disk_total_space: restituisce la dimensione totale di un file system o di una partizione del disco.	Non supportati.	Questa opzione è disabilitata.
diskfreespace: alias di disk_free_space.
fclose: chiude un puntatore a un file aperto.	Supportato.
feof: verifica la fine del file su un puntatore al file.	Supportato.
fflush: scarica l'output in un file.	Supportato.	Non ha alcun effetto. Restituisce sempre true.
fgetc: recupera il carattere dal puntatore del file.	Supportato.
fgetcsv: recupera la riga dal puntatore del file e analizza i campi CSV.	Supportato.
fgets: recupera la riga dal puntatore del file.	Supportato.
fgetss: recupera la riga dal puntatore del file e rimuove i tag HTML.	Supportato.
file_exists: controlla se esiste un file o una directory.	Supportato.
file_get_contents: legge l'intero file in una stringa.	Supportato.
file_put_contents: scrive una stringa in un file.	Supportato.
file: legge l'intero file in un array.	Supportato.
fileatime: recupera l'ora dell'ultimo accesso al file.	Non supportati.	Restituisce sempre 0.
filectime: recupera l'ora di modifica dell'inode del file.	Non supportati.	Restituisce sempre 0.
filegroup: recupera il gruppo di file.	Non supportati.	Restituisce sempre 0.
fileinode: recupera l'inode del file.	Non supportati.	Restituisce sempre 0.
filemtime: recupera l'ora di modifica del file.	Supportato.
fileowner: recupera il proprietario del file.	Non supportati.	Restituisce sempre 0.
fileperms: recupera le autorizzazioni dei file.	Supportato.	Il bit di esecuzione è sempre disattivato.
filesize: recupera le dimensioni del file.	Supportato.
filetype: ottiene il tipo di file.	Supportato.
flock: blocco portatile dei file di consulenza.	Non supportato.	Restituisce sempre false.
fopen: apre il file o l'URL.	Supportato.	Supporta solo queste modalità: r, rb, rt, w, wb, wt.
fpassthru: restituisce tutti i dati rimanenti su un puntatore di file.	Supportato.
fputcsv: formatta la riga come CSV e scrivila nel puntatore del file.	Supportato.
fputs: alias di fwrite.
fread: lettura di file sicura per i file binari.	Supportato.
fscanf: analizza l'input di un file in base a un formato.	Supportato.
fseek: cerca un puntatore di file.	Supportato.	Supporta solo i file aperti in modalità di lettura.
fstat: recupera informazioni su un file utilizzando un puntatore di file aperto.	Supportato.
ftell: restituisce la posizione corrente del puntatore di lettura/scrittura del file.	Supportato.
ftruncate: tronca un file a una determinata lunghezza.	Non supportati.	Restituisce sempre false.
fwrite: scrittura di file binari sicura.	Supportato.
glob: trova i nomi dei percorsi che corrispondono a un pattern.	Supportato.
is_dir: indica se il nome file è una directory.	Supportato.
is_executable: indica se il nome file è eseguibile.	Non supportati.	Restituisce sempre false.
is_file: indica se il nome file è un file normale.	Supportato.
is_link: indica se il nome file è un link simbolico.	Non supportati.	Restituisce sempre false.
is_readable: indica se un file esiste ed è leggibile.	Supportato.
is_uploaded_file: indica se il file è stato caricato tramite HTTP POST.	Supportato.
is_writable: indica se il nome file è scrivibile.	Supportato.	Il valore viene memorizzato nella cache e potrebbe non riflettere immediatamente le modifiche alle autorizzazioni.
is_writeable: alias di is_writable.
lchgrp: modifica la proprietà del gruppo del link simbolico.	Non supportati.	Questa opzione è disabilitata.
lchown: modifica la proprietà utente del collegamento simbolico.	Non supportati.	Questa opzione è disabilitata.
link: crea un collegamento fisico.	Non supportati.	Questa opzione è disabilitata.
linkinfo: recupera informazioni su un link.	Non supportati.	Restituisce sempre -1.
lstat: fornisce informazioni su un file o un link simbolico.	Supportato.
mkdir: crea la directory.	Supportato.
move_uploaded_file: sposta un file caricato in una nuova posizione.	Supportato.
parse_ini_file: analizza un file di configurazione.	Supportato.
pathinfo: restituisce informazioni su un percorso del file.	Supportato.
pclose: chiude il puntatore del file di processo.	Non supportati.	Questa opzione è disabilitata.
popen: apre il puntatore del file di processo.	Non supportati.	Questa opzione è disabilitata.
readfile: restituisce un file.	Supportato.
readlink: restituisce la destinazione di un link simbolico.	Non supportati.	Restituisce sempre false.
realpath: restituisce il percorso assoluto canonico.	Non supportati.	Restituisce sempre false.
rename: rinomina un file o una directory.	Supportato.
rewind: riavvolge la posizione di un puntatore di file.	Supportato.	Supportato solo per la modalità di lettura.
rmdir: rimuove la directory.	Supportato.
set_file_buffer: alias di stream_set_write_buffer.
stat: fornisce informazioni su un file.	Supportato.
symlink: crea un collegamento simbolico.	Non supportati.	Questa opzione è disabilitata.
tempnam: crea un file con un nome univoco.	Supportato.	Consulta queste note.
tmpfile: crea un file temporaneo.	Supportato.	Restituisce un file supportato dalla memoria simile a php://memory.
touch: imposta l'ora di accesso e modifica del file.	Non supportati.	Restituisce sempre false.
umask: modifica l'umask corrente.	Supportato.	Non si applica ai file di Cloud Storage.
unlink: elimina un file.	Supportato.

Tieni presente che le funzioni di statistica dei file nella tabella precedente (file_exists, filemtime, filesize, fstat, is_file, is_dir, is_writable e stat) vengono memorizzate nella cache in base alla richiesta. Puoi svuotare questa cache chiamando il numero clearstatcache.

Inoltre, sono supportate le seguenti funzioni di lettura delle directory PHP:

Nome funzione
opendir
readdir
rewinddir
closedir

Nota :poiché le operazioni di elenco di Cloud Storage sono alla fine coerenti, readdir potrebbe non riflettere la modifica immediatamente dopo l'aggiunta, la ridenominazione o la rimozione di un oggetto.

Utilizzo di include e require in PHP 5

Per contribuire a mantenere la sicurezza della tua applicazione, la possibilità di include o require da un file Cloud Storage è disattivata per impostazione predefinita, ma puoi attivarla nel seguente modo:

Per include o require codice PHP da Google Cloud Storage nella tua applicazione, devi specificare i bucket che contengono questi file utilizzando la direttiva google_app_engine.allow_include_gs_buckets nel file php.ini.

Lettura e scrittura di metadati personalizzati

Per allegare metadati personalizzati a un file in fase di scrittura in Google Cloud Storage, aggiungi i metadati a $options prima di creare il contesto dello stream utilizzato per la chiamata file_put_contents.

In questo esempio, ai metadati denominati foo viene assegnato il valore far e a un altro denominato bar viene assegnato il valore boo. L'esempio imposta anche il tipo di contenuti su text/plain. Il contesto dello stream viene creato utilizzando queste informazioni in $options come mostrato e il file viene scritto in Cloud Storage utilizzando file_put_contents(), insieme ai metadati e al tipo di contenuti:

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

Per leggere i metadati personalizzati e il tipo di contenuto di un file, chiama fopen sul file e poi utilizza CloudStorageTools::getContentType() per ottenere il tipo di contenuto e CloudStorageTools::getMetaData() per ottenere i metadati.

I metadati personalizzati e il tipo di contenuti sono disponibili una volta restituito il puntatore al file dalla chiamata fopen.

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

Letture di file memorizzati nella cache

Per impostazione predefinita, il wrapper di flusso App Engine per Cloud Storage memorizza nella cache le letture dei file in memcache per migliorare le prestazioni nelle letture successive. La memorizzazione nella cache può essere disattivata utilizzando la direttiva enable_cache nel contesto dello stream.

Nota :quando la memorizzazione nella cache è abilitata, i file letti da Cloud Storage vengono memorizzati nella cache durante la lettura e la cache contiene anche le informazioni sui file relative alla scrivibilità. Pertanto, tieni presente che is_writable potrebbe eseguire query su informazioni obsolete dei file. Inoltre, se modifichi la ACL di un bucket Cloud Storage per concedere o negare le autorizzazioni di scrittura all'applicazione, potrebbe essere necessario un po' di tempo prima che la modifica venga applicata.

Per migliorare ulteriormente le prestazioni, puoi anche attivare la memorizzazione nella cache ottimistica, che legge l'oggetto file dalla cache senza verificare se l'oggetto sottostante è stato modificato in Google Cloud Storage dall'ultima volta che è stato memorizzato nella cache, utilizzando la direttiva enable_optimistic_cache (impostata su false per impostazione predefinita). La memorizzazione nella cache ottimistica è ideale per scenari di scrittura una sola volta e lettura molte volte.

Puoi anche modificare il periodo di tempo durante il quale un oggetto memorizzato nella cache rimane valido utilizzando la direttiva read_cache_expiry_seconds, dopo il quale l'oggetto verrà memorizzato nuovamente nella cache al successivo tentativo di lettura. Per impostazione predefinita, questo valore è impostato su 1 ora (3600).

In questo esempio, la memorizzazione nella cache ottimistica è attivata e gli oggetti file sono configurati per essere contrassegnati per la memorizzazione nella cache da Google Cloud Storage dopo 5 minuti.

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