Gestão de ficheiros PHP 5 avançada

Esta API é suportada para runtimes de primeira geração e pode ser usada quando atualizar para runtimes de segunda geração correspondentes. Se estiver a fazer a atualização para o tempo de execução do App Engine PHP 7/8, consulte o guia de migração para saber mais sobre as suas opções de migração para serviços agrupados antigos.

Opções de autorizações, colocação em cache e metadados

O wrapper de streams do App Engine para o Cloud Storage oferece as seguintes opções para configurar a sua stream:

Opção	Valores possíveis	Descrição
acl	Um dos seguintes valores: private public-read public-read-write authenticated-read bucket-owner-read bucket-owner-full-control project-private	Para ver descrições do que estas definições fazem no Cloud Storage, consulte o artigo ACLs predefinidas. Se não definir acl, o Cloud Storage define este parâmetro como nulo e usa a ACL de objeto predefinida associada ao contentor que contém o ficheiro.
Content-Type	Qualquer tipo MIME válido	Se não especificar um tipo de conteúdo quando carregar um objeto, o sistema do Google Cloud Storage usa o valor predefinido binary/octet-stream quando publica o objeto.
Content-Disposition	Qualquer valor de disposição de conteúdo válido	Um cabeçalho que pode definir num objeto que especifica informações de apresentação sobre como os dados do objeto devem ser transmitidos.
Content-Encoding	Qualquer algoritmo de compressão válido	O algoritmo de compressão do objeto, como gzip. Tenha em atenção que o Google Cloud Storage não comprime nem descomprime automaticamente objetos com base neste cabeçalho.
Content-Language	Qualquer código de idioma ISO 639-1 válido	O código de idioma ISO 639-1 do conteúdo (consulte os códigos para a representação de nomes de idiomas para ver uma lista completa).
enable_cache	verdadeiro ou falso (verdadeiro por predefinição)	Os ficheiros lidos do Cloud Storage são colocados em cache na memória (consulte memcache) para melhorar o desempenho. O armazenamento em cache pode ser desativado através da diretiva enable_cache no contexto da stream.
enable_optimistic_cache	verdadeiro ou falso (falso por predefinição)	Pode ativar a colocação em cache otimista para ler o objeto de ficheiro a partir da cache sem verificar se o objeto subjacente foi alterado no Cloud Storage desde a última vez que foi colocado em cache. O armazenamento em cache otimista é ideal para cenários de escrita única e leitura múltipla.
metadata	Uma matriz associativa, por exemplo:	['foo' => 'far', 'bar' => 'boo'] Consulte o artigo Ler e escrever metadados personalizados.
read_cache_expiry_seconds	O número de segundos durante os quais um objeto permanece válido na cache	Pode alterar o período durante o qual um objeto em cache permanece válido através do elemento read_cache_expiry_seconds directive. Isto especifica o tempo após o qual o objeto é novamente colocado em cache na próxima tentativa de leitura. Por predefinição, esta opção está definida como 1 hora (3600).
writable_cache_expiry_seconds	O número de segundos durante os quais o estado de gravação de um contentor é colocado em cache	O wrapper de streams do Cloud Storage coloca em cache o estado gravável dos contentores para melhorar o desempenho. Isto significa que os bits graváveis devolvidos por várias funções relacionadas com stat() podem estar temporariamente dessincronizados quando a ACL do contentor é alterada. Por predefinição, este valor está definido como 10 minutos (600).

O fragmento seguinte mostra como usar as opções de stream:

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

No fragmento acima, $options é um conjunto de argumentos que a stream vai usar quando escrever novos objetos, que podem ser definidos como as opções predefinidas através de stream_context_set_default.

Suporte das funções do sistema de ficheiros do PHP 5 no Cloud Storage

O wrapper de streams do App Engine para o Cloud Storage suporta muitas funções nativas do sistema de ficheiros PHP. Algumas funções não são suportadas e outras têm suporte modificado. A tabela seguinte apresenta cada uma destas funções nativas, indicando se a função é suportada ou não. Se uma função for suportada, mas com modificações ou limitações, estas são descritas.

Função do sistema de ficheiros	Suportado?	Detalhes
basename: devolve o componente do nome final do caminho.	Compatível.
chgrp: altera o grupo de ficheiros.	Não suportado.	Devolve sempre false.
chmod: altera o modo do ficheiro.	Não suportado.	Devolve sempre false.
chown: altera o proprietário do ficheiro.	Não suportado.	Devolve sempre false.
clearstatcache: limpa a cache do estado do ficheiro.	Compatível.
copy: copia o ficheiro.	Compatível.
dirname: devolve o caminho do diretório principal.	Compatível.	Suportado, mas inclui o prefixo gs://.
disk_free_space: devolve o espaço disponível no sistema de ficheiros ou na partição do disco.	Não suportado.	Esta opção está desativada.
disk_total_space: devolve o tamanho total de um sistema de ficheiros ou de uma partição do disco.	Não suportado.	Esta opção está desativada.
diskfreespace: alias de disk_free_space.
fclose: fecha um ponteiro de ficheiro aberto.	Compatível.
feof: testa o fim do ficheiro num ponteiro de ficheiro.	Compatível.
fflush: envia a saída para um ficheiro.	Compatível.	Não tem efeito. (Devolve sempre true.)
fgetc: recebe um caráter do ponteiro do ficheiro.	Compatível.
fgetcsv: obtém a linha do ponteiro do ficheiro e analisa-a para encontrar campos CSV.	Compatível.
fgets: recebe uma linha de um ponteiro de ficheiro.	Compatível.
fgetss: obtém a linha do ponteiro do ficheiro e remove as etiquetas HTML.	Compatível.
file_exists: verifica se existe um ficheiro ou um diretório.	Compatível.
file_get_contents: lê todo o ficheiro numa string.	Compatível.
file_put_contents: escreve uma string num ficheiro.	Compatível.
file: lê o ficheiro inteiro para uma matriz.	Compatível.
fileatime: obtém a hora do último acesso ao ficheiro.	Não suportado.	Devolve sempre 0.
filectime: obtém a hora de alteração do inode do ficheiro.	Não suportado.	Devolve sempre 0.
filegroup: recebe o grupo de ficheiros.	Não suportado.	Devolve sempre 0.
fileinode: recebe o inode do ficheiro.	Não suportado.	Devolve sempre 0.
filemtime: obtém a hora de modificação do ficheiro.	Compatível.
fileowner: recebe o proprietário do ficheiro.	Não suportado.	Devolve sempre 0.
fileperms: recebe as autorizações de ficheiros.	Compatível.	O bit de execução está sempre desativado.
filesize: obtém o tamanho do ficheiro.	Compatível.
filetype: recebe o tipo de ficheiro.	Compatível.
flock: bloqueio de ficheiros consultivo portátil.	Não suportado.	Devolve sempre false.
fopen: abre um ficheiro ou um URL.	Compatível.	Só suporta estes modos: r, rb, rt, w, wb e wt.
fpassthru: produz todos os dados restantes num ponteiro de ficheiro.	Compatível.
fputcsv: formata a linha como CSV e escreve no ponteiro do ficheiro.	Compatível.
fputs: alias de fwrite.
fread: leitura de ficheiros segura para binários.	Compatível.
fscanf: analisa a entrada de um ficheiro de acordo com um formato.	Compatível.
fseek: procura um ponteiro de ficheiro.	Compatível.	Só suporta ficheiros abertos através do modo de leitura.
fstat: recebe informações sobre um ficheiro através de um ponteiro de ficheiro aberto.	Compatível.
ftell: devolve a posição atual do ponteiro de leitura/escrita do ficheiro.	Compatível.
ftruncate: trunca um ficheiro para um determinado comprimento.	Não suportado.	Devolve sempre false.
fwrite: gravação de ficheiros segura para binários.	Compatível.
glob: encontra nomes de caminhos que correspondem a um padrão.	Compatível.
is_dir: indica se o nome do ficheiro é um diretório.	Compatível.
is_executable: indica se o nome do ficheiro é executável.	Não suportado.	Devolve sempre false.
is_file: indica se o nome do ficheiro é um ficheiro normal.	Compatível.
is_link: indica se o nome do ficheiro é um link simbólico.	Não suportado.	Devolve sempre false.
is_readable: indica se um ficheiro existe e é legível.	Compatível.
is_uploaded_file: indica se o ficheiro foi carregado através de HTTP POST.	Compatível.
is_writable: indica se o nome do ficheiro é gravável.	Compatível.	O valor é colocado em cache e pode não refletir imediatamente as alterações de autorização.
is_writeable: alias de is_writable.
lchgrp: altera a propriedade do grupo do link simbólico.	Não suportado.	Esta opção está desativada.
lchown: altera a propriedade do utilizador do link simbólico.	Não suportado.	Esta opção está desativada.
link: cria um hard link.	Não suportado.	Esta opção está desativada.
linkinfo: recebe informações sobre um link.	Não suportado.	Devolve sempre -1.
lstat: fornece informações sobre um ficheiro ou um link simbólico.	Compatível.
mkdir: cria um diretório.	Compatível.
move_uploaded_file: move um ficheiro carregado para uma nova localização.	Compatível.
parse_ini_file: analisa um ficheiro de configuração.	Compatível.
pathinfo: devolve informações sobre um caminho de ficheiro.	Compatível.
pclose: fecha o ponteiro do ficheiro de processo.	Não suportado.	Esta opção está desativada.
popen: abre um ponteiro de ficheiro de processo.	Não suportado.	Esta opção está desativada.
readfile: gera um ficheiro.	Compatível.
readlink: devolve o destino de um link simbólico.	Não suportado.	Devolve sempre false.
realpath: devolve o caminho absoluto canónico.	Não suportado.	Devolve sempre false.
rename: muda o nome de um ficheiro ou de um diretório.	Compatível.
rewind: recua a posição de um ponteiro de ficheiro.	Compatível.	Apenas suportado para o modo de leitura.
rmdir: remove o diretório.	Compatível.
set_file_buffer: alias de stream_set_write_buffer.
stat: fornece informações sobre um ficheiro.	Compatível.
symlink: cria um link simbólico.	Não suportado.	Esta opção está desativada.
tempnam: crie um ficheiro com um nome de ficheiro exclusivo.	Compatível.	Consulte estas notas.
tmpfile: cria um ficheiro temporário.	Compatível.	Devolve um ficheiro suportado por memória semelhante a php://memory.
touch: define a hora de acesso e modificação do ficheiro.	Não suportado.	Devolve sempre false.
umask: altera a umask atual.	Compatível.	Não se aplica a ficheiros do Cloud Storage.
unlink: elimina um ficheiro.	Compatível.

Tenha em atenção que as funções de estatísticas de ficheiros na tabela acima (file_exists, filemtime, filesize, fstat, is_file, is_dir, is_writable e stat) são colocadas em cache com base em cada pedido. Pode limpar esta cache ligando para clearstatcache.

Além disso, são suportadas as seguintes funções de leitura de diretórios PHP:

Nome da função
opendir
readdir
rewinddir
closedir

Nota: uma vez que as operações de listagem do Cloud Storage são eventualmente consistentes>, readdir pode não refletir a alteração imediatamente após a adição, a mudança de nome ou a remoção de um objeto.

Usar o PHP 5 include e require

Para ajudar a manter a segurança da sua aplicação, a capacidade de include ou require a partir de um ficheiro do Cloud Storage está desativada por predefinição, mas pode ativá-la da seguinte forma:

Para include ou require código PHP do Google Cloud Storage na sua aplicação, tem de especificar que contentores contêm esses ficheiros através da diretiva google_app_engine.allow_include_gs_buckets no ficheiro php.ini.

Ler e escrever metadados personalizados

Para anexar metadados personalizados a um ficheiro que está a ser escrito no Google Cloud Storage, adicione os metadados a $options antes de criar o contexto de fluxo usado para a chamada file_put_contents.

Neste exemplo, os metadados com o nome foo recebem o valor far e outros com o nome bar recebem o valor boo. O exemplo também define o tipo de conteúdo como text/plain. O contexto da stream é criado com estas informações em $options, conforme mostrado, e o ficheiro é escrito no Cloud Storage através de file_put_contents(), juntamente com os metadados e o tipo de conteúdo:

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

Para ler os metadados personalizados e o tipo de conteúdo de um ficheiro, chame fopen no ficheiro e, em seguida, use CloudStorageTools::getContentType() para obter o tipo de conteúdo e CloudStorageTools::getMetaData() para obter os metadados.

Os metadados personalizados e o tipo de conteúdo ficam disponíveis assim que tiver o ponteiro do ficheiro devolvido pela chamada fopen.

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

Leituras de ficheiros em cache

Por predefinição, o wrapper de streams do App Engine para o Cloud Storage armazena em cache as leituras de ficheiros no memcache para melhorar o desempenho nas leituras subsequentes. O armazenamento em cache pode ser desativado através da diretiva enable_cache no contexto da stream.

Nota: quando o armazenamento em cache está ativado, os ficheiros lidos do Cloud Storage são armazenados em cache à medida que são lidos, e a cache também contém as informações dos ficheiros relativas à capacidade de gravação. Por isso, tenha em atenção que is_writable pode estar a consultar informações desatualizadas do ficheiro. Além disso, se alterar a LCA num contentor do Cloud Storage para conceder ou negar autorizações de escrita à aplicação, esta alteração pode demorar algum tempo a ser refletida.

Para melhorar ainda mais o desempenho, também pode ativar o armazenamento em cache otimista, que lê o objeto de ficheiro da cache sem verificar se o objeto subjacente foi alterado no Google Cloud Storage desde a última vez que foi colocado em cache, usando a diretiva enable_optimistic_cache (definida como false por predefinição). O armazenamento em cache otimista é ideal para cenários de escrita única e leitura múltipla.

Também pode alterar o período de tempo durante o qual um objeto em cache permanece válido através da diretiva read_cache_expiry_seconds, após o qual o objeto é novamente colocado em cache na próxima tentativa de leitura. Por predefinição, esta opção está definida como 1 hora (3600).

Neste exemplo, o armazenamento em cache otimista está ativado e os objetos de ficheiros estão configurados para serem marcados para novo armazenamento em cache a partir do Google Cloud Storage após 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);