Gestione avanzata dei file PHP 5

Questa API è supportata per i runtime di prima generazione e può essere utilizzata durante 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 conoscere le opzioni di migrazione per i servizi in bundle legacy.

Opzioni relative ad autorizzazioni, memorizzazione nella cache e metadati

Il wrapper stream di 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 privato a progetto	Per descrizioni delle operazioni svolte in Cloud Storage, consulta ACL predefiniti. Se non imposti acl, Cloud Storage imposta questo parametro come null e utilizza l'ACL dell'oggetto predefinito associato al bucket che contiene il file.
Content-Type	Qualsiasi tipo MIME valido	Se non specifichi un tipo di contenuto quando carichi un oggetto, per impostazione predefinita il sistema di Google Cloud Storage utilizzerà binary/octet-stream quando gestisce l'oggetto.
Content-Disposition	Qualsiasi valore valido relativo alla disposizione dei contenuti	Un'intestazione che è possibile impostare su un oggetto che specifica informazioni di presentazione sulla modalità di trasmissione dei dati dell'oggetto.
Content-Encoding	Qualsiasi algoritmo di compressione valido	L'algoritmo di compressione dell'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 dei contenuti (per un elenco completo, consulta la sezione Codici per la rappresentazione dei nomi delle lingue).
enable_cache	true o false (vero 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 (falso per impostazione predefinita)	Puoi attivare la memorizzazione nella cache ottimistica per leggere l'oggetto file dalla cache senza verificare se l'oggetto sottostante sia stato modificato in Cloud Storage dall'ultima volta che è stato memorizzato nella cache. La memorizzazione nella cache ottimistica è ideale per scenari write-once e readmany.
metadata	Una matrice associativa, ad es.	['foo' => 'far', 'bar' => 'boo'] Consulta la sezione Leggere e scrivere metadati personalizzati.
read_cache_expiry_seconds	Il numero di secondi durante i quali un oggetto rimane valido nella cache	Puoi modificare il periodo di tempo durante il quale un oggetto memorizzato nella cache rimane valido utilizzando l'read_cache_expiry_seconds directive. Consente di specificare l'intervallo di tempo dopo il quale l'oggetto verrà rimemorizzato nella cache al successivo tentativo di lettura. Per impostazione predefinita, l'intervallo è 1 ora (3600).
writable_cache_expiry_seconds	Il numero di secondi durante i quali lo stato scrivibile di un bucket viene memorizzato nella cache	Il wrapper del flusso di Cloud Storage memorizza nella cache lo stato scrivibile 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 viene modificato. Per impostazione predefinita, l'obiettivo è 10 minuti (600).

Lo snippet seguente mostra come utilizzare le opzioni relative allo 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 riportato sopra, $options è un insieme di argomenti che lo stream utilizzerà durante la scrittura di nuovi oggetti. Questi argomenti possono essere impostati come opzioni predefinite utilizzando stream_context_set_default.

Supporto delle funzioni di file system PHP 5 su Cloud Storage

Il wrapper stream di App Engine per Cloud Storage supporta molte funzioni di file system PHP native. Alcune funzioni non sono supportate, mentre altre hanno modificato il supporto. La seguente tabella elenca ognuna di queste funzioni native, indicando se la funzione è supportata o meno. Se una funzione è supportata, ma con modifiche o limitazioni, 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 dei file.	Supportato.
copy: copia il file.	Supportato.
dirname: restituisce il percorso della directory padre.	Supportato.	Opzione supportata, ma è incluso il prefisso gs://.
disk_free_space: restituisce lo spazio disponibile sulla partizione del file system o 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 il puntatore di un file aperto.	Supportato.
feof: verifica la fine del file in un puntatore al file.	Supportato.
fflush: elimina 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 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: scrivi una stringa in un file.	Supportato.
file: legge l'intero file in un array.	Supportato.
fileatime: ottiene l'ora dell'ultimo accesso al file.	Non supportati.	Restituisce sempre 0.
filectime: ottiene l'ora di modifica inode del file.	Non supportati.	Restituisce sempre 0.
filegroup: recupera gruppo di file.	Non supportati.	Restituisce sempre 0.
fileinode: ottiene l'inode di file.	Non supportati.	Restituisce sempre 0.
filemtime: ottiene l'ora di modifica del file.	Supportato.
fileowner: acquisisce il proprietario del file.	Non supportati.	Restituisce sempre 0.
fileperms: ottiene le autorizzazioni dei file.	Supportato.	Il bit di esecuzione è sempre disattivato.
filesize: recupera le dimensioni del file.	Supportato.
filetype: recupera il tipo di file.	Supportato.
flock: blocco dei file di avviso portatile.	Non supportato.	Restituisce sempre false.
fopen: apre il file o l'URL.	Supportato.	Supporta solo queste modalità: r, rb, rt, w, wb, wt.
fpassthru: genera tutti i dati rimanenti in un puntatore file.	Supportato.
fputcsv: formatta la riga come CSV e scrivi nel puntatore del file.	Supportato.
fputs: alias di fwrite.
fread: lettura file sicura per binari.	Supportato.
fscanf: analizza l'input di un file secondo 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 aperto.	Supportato.
ftell: restituisce la posizione corrente del puntatore di lettura/scrittura file.	Supportato.
ftruncate: tronca un file a una lunghezza specificata.	Non supportati.	Restituisce sempre false.
fwrite: scrittura di file sicura per i file binari.	Supportato.
glob: consente di trovare i nomi di percorso che corrispondono a un pattern.	Supportato.
is_dir: indica se il nome del file è una directory.	Supportato.
is_executable: indica se il nome del file è eseguibile.	Non supportati.	Restituisce sempre false.
is_file: indica se il nome del file è un file normale.	Supportato.
is_link: indica se il nome del 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 del 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à dell'utente del link simbolico.	Non supportati.	Questa opzione è disabilitata.
link: crea un link fisico.	Non supportati.	Questa opzione è disabilitata.
linkinfo: riceve 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 sul percorso di un 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 nome di percorso assoluto canonico.	Non supportati.	Restituisce sempre false.
rename: rinomina un file o una directory.	Supportato.
rewind: riavvolgi la posizione del puntatore di un file.	Supportato.	Supportata 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 link simbolico.	Non supportati.	Questa opzione è disabilitata.
tempnam: crea file con un nome univoco.	Supportato.	Consulta queste note.
tmpfile: crea un file temporaneo.	Supportato.	Restituisce un file basato sulla 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 Cloud Storage.
unlink: elimina un file.	Supportato.

Tieni presente che le funzioni delle statistiche dei file nella tabella precedente (file_exists, filemtime, filesize, fstat, is_file, is_dir, is_writable e stat) vengono memorizzate nella cache in base alle richieste. Puoi svuotare la cache chiamando il numero clearstatcache.

Sono inoltre supportate le seguenti funzioni di lettura della directory PHP:

Nome funzione
opendir
readdir
rewinddir
closedir

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

Utilizzo di include e require PHP 5

Per garantire la sicurezza della tua applicazione, la possibilità di eseguire include o require da un file Cloud Storage è disabilitata per impostazione predefinita, ma puoi abilitarla come segue:

Per include o require utilizzare il codice PHP di Google Cloud Storage nella tua applicazione, devi specificare i bucket che contengono quei file utilizzando l'istruzione 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 del flusso utilizzato per la chiamata file_put_contents.

In questo esempio, ai metadati denominati foo viene assegnato il valore far, mentre a un altro nome bar viene assegnato il valore boo. Nell'esempio viene impostato anche il tipo di contenuti su text/plain. Il contesto del flusso 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 e il tipo di contenuti personalizzati di un file, chiama fopen nel file, quindi utilizza CloudStorageTools::getContentType() per ottenere il tipo di contenuti e CloudStorageTools::getMetaData() per ottenere i metadati.

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

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

Lettura dei file memorizzati nella cache

Per impostazione predefinita, il wrapper flusso di 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 l'istruzione 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 possibilità di scrittura. Tieni presente che is_writable potrebbe eseguire query su informazioni di file obsolete. Inoltre, se modifichi l'ACL in 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 un ulteriore miglioramento delle prestazioni, puoi anche attivare la memorizzazione nella cache ottimistica, che leggerà l'oggetto del file dalla cache senza vedere se l'oggetto sottostante è stato modificato in Google Cloud Storage dall'ultima volta che è stato memorizzato nella cache, utilizzando l'istruzione enable_optimistic_cache (impostata su false per impostazione predefinita). La memorizzazione nella cache ottimistica è ideale per scenari write-once e readmany.

Puoi anche modificare il periodo di tempo durante il quale un oggetto memorizzato nella cache rimane valido utilizzando l'istruzione read_cache_expiry_seconds, dopodiché l'oggetto verrà ri-memorizzato nella cache al successivo tentativo di lettura. Per impostazione predefinita, l'intervallo è 1 ora (3600).

In questo esempio, la memorizzazione nella cache ottimistica è attivata e gli oggetti file sono configurati per essere contrassegnati per la memorizzazione nuovamente 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);