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 ad App Engine PHP 7/8, consulta la guida alla migrazione per scoprire di più sulle opzioni di migrazione per i servizi in bundle legacy.

Autorizzazioni, memorizzazione nella cache e opzioni dei metadati

Il wrapper dello stream di App Engine per Cloud Storage fornisce le seguenti opzioni per configurare lo stream:

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 descrizioni della funzione di queste impostazioni in Cloud Storage, consulta ACL predefinite. Se non imposti acl, Cloud Storage imposta questo parametro come nullo e utilizza l'ACL dell'oggetto predefinito associata al bucket che contiene il file.
Content-Type	Qualsiasi tipo MIME valido	Se non specifichi un tipo di contenuto quando carichi un oggetto, il sistema Google Cloud Storage utilizza per impostazione predefinita binary/octet-stream quando serve l'oggetto.
Content-Disposition	Qualsiasi valore valido per content-disposition	Un'intestazione che puoi impostare su un oggetto per specificare informazioni di presentazione su come devono essere trasmessi i 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 Codici per la rappresentazione dei nomi delle lingue).
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 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 la durata di validità di un oggetto memorizzato nella cache utilizzando read_cache_expiry_seconds directive. Questo specifica il momento dopo il quale l'oggetto verrà ricaricato al successivo tentativo di lettura. Per impostazione predefinita, è 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 dello 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).

Lo snippet seguente 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 riportato sopra, $options è un insieme di argomenti che lo stream utilizzerà prilikom pisanja novih objekata, che possono essere impostati come opzioni predefinite utilizzando stream_context_set_default.

Supporto delle funzioni del filesystem PHP 5 su Cloud Storage

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

Funzione file system	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 il modo del 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 è disattivata.
disk_total_space: restituisce le dimensioni totali di un file system o di una partizione del disco.	Non supportati.	Questa opzione è disattivata.
diskfreespace: alias di disk_free_space.
fclose: chiude un puntatore a file aperto.	Supportato.
feof: verifica la presenza di un indicatore di fine file in un puntatore a file.	Supportato.
fflush: svuota 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: verifica 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 la data e l'ora della 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 la data e l'ora di modifica del file.	Supportato.
fileowner: restituisce il proprietario del file.	Non supportati.	Restituisce sempre 0.
fileperms: recupera le autorizzazioni dei file.	Supportato.	Il bit di esecuzione è sempre disattivato.
filesize: restituisce le dimensioni del file.	Supportato.
filetype: restituisce il tipo di file.	Supportato.
flock: blocco dei file di consulenza portatili.	Non supportato.	Restituisce sempre false.
fopen: apre il file o l'URL.	Supportato.	Supporta solo queste modalità: r, rb, rt, w, wb, wt.
fpassthru: consente di visualizzare 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 del file in modo sicuro per i dati binari.	Supportato.
fscanf: analizza l'input da un file in base a un formato.	Supportato.
fseek: esegue ricerche su un puntatore del file.	Supportato.	Supporta solo i file aperti utilizzando la modalità di lettura.
fstat: recupera le informazioni su un file utilizzando un puntatore a file aperto.	Supportato.
ftell: restituisce la posizione corrente del cursore di lettura/scrittura del file.	Supportato.
ftruncate: tronca un file fino a una determinata lunghezza.	Non supportati.	Restituisce sempre false.
fwrite: scrittura di file compatibile con i dati binari.	Supportato.
glob: trova i 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 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 file è scrivibile.	Supportato.	Il valore viene memorizzato nella cache e potrebbe non riflettere immediatamente le modifiche alle autorizzazioni.
is_writeable: alias di è_scrivibile.
lchgrp: modifica la proprietà di gruppo del link simbolico.	Non supportati.	Questa opzione è disattivata.
lchown: modifica la proprietà del link simbolico da parte dell'utente.	Non supportati.	Questa opzione è disattivata.
link: crea un collegamento fisico.	Non supportati.	Questa opzione è Disattivata.
linkinfo: recupera le informazioni su un link.	Non supportati.	Restituisce sempre -1.
lstat: fornisce informazioni su un file o un link simbolico.	Supportato.
mkdir: crea una 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 del processo.	Non supportati.	Questa opzione è Disattivata.
popen: apre il puntatore del file del processo.	Non supportati.	Questa opzione è Disattivata.
readfile: genera un file.	Supportato.
readlink: restituisce la destinazione di un link simbolico.	Non supportati.	Restituisce sempre false.
realpath: restituisce il percorso assoluto canonizzato.	Non supportati.	Restituisce sempre false.
rename: rinomina un file o una directory.	Supportato.
rewind: torna indietro nella posizione di un cursore del file.	Supportato.	Supportato solo per la modalità 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 è Disattivata.
tempnam: crea un 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 di Cloud Storage.
unlink: elimina un file.	Supportato.

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

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

Nome funzione
opendir
readdir
rewinddir
closedir

Nota: poiché le operazioni di elenco di Cloud Storage sono coerenti in modo definitivo, readdir potrebbe non riflettere la modifica immediatamente dopo l'aggiunta, la rinominazione 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 è disabilitata per impostazione predefinita, ma puoi attivarla come segue:

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 associare 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, al metadato denominato foo viene assegnato il valore far e a un altro denominato bar viene assegnato il valore boo. L'esempio imposta anche il tipo di contenuto 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 contenuto sono disponibili una volta ottenuto il puntatore del file restituito 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 dello stream 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 la direttiva enable_cache nel contesto dello stream.

Nota: quando la memorizzazione nella cache è attivata, i file letti da Cloud Storage vengono memorizzati nella cache man mano che vengono letti e la cache contiene anche le informazioni sul file relative alla scrivibilità. Tieni presente che is_writable potrebbe eseguire query su informazioni su file non aggiornate. Inoltre, se modifichi l'ACL di un bucket Cloud Storage per concedere o negare le autorizzazioni di scrittura all'applicazione, questa modifica potrebbe richiedere un po' di tempo prima di essere applicata.

Per un ulteriore miglioramento delle 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 volta e lettura molte volte.

Puoi anche modificare il periodo di tempo per cui un oggetto memorizzato nella cache rimane valido utilizzando la direttiva read_cache_expiry_seconds, al termine del 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);