Gerenciamento avançado de arquivos PHP 5

Essa API é compatível com os ambientes de execução de primeira geração e pode ser usada ao fazer upgrade para os ambientes de execução de segunda geração correspondentes. Se você estiver atualizando para o ambiente de execução do PHP 7 ou 8 no App Engine, consulte o guia de migração para saber mais sobre as opções de migração para serviços incluídos no pacote.

Permissões, armazenamento em cache e opções de metadados

O wrapper de stream do App Engine para Cloud Storage fornece as seguintes opções para configurar seu 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 descrições da função dessas configurações no Cloud Storage, consulte ACLs predefinidas. Se você não definir acl, o Cloud Storage definirá esse parâmetro como nulo e usará a ACL padrão do objeto associada ao bucket que contém o arquivo.
Content-Type	Qualquer tipo MIME válido	Se você não especificar um tipo de conteúdo ao fazer o upload de um objeto, o sistema do Google Cloud Storage usará como padrão binary/octet-stream quando veicular o objeto.
Content-Disposition	Qualquer valor de disposição de conteúdo válido	Um cabeçalho que pode ser definido em um objeto que especifica as informações de apresentação sobre como os dados do objeto devem ser transmitidos.
Content-Encoding	Qualquer algoritmo de compactação válido	O algoritmo de compactação para o objeto, como gzip. Observe que o Google Cloud Storage não compacta nem descompacta objetos automaticamente com base nesse 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 Códigos para a representação de nomes de idiomas para uma lista completa.
enable_cache	true ou false (true por padrão)	Os arquivos lidos no Cloud Storage são armazenados em cache na memória (consulte memcache) para melhorar o desempenho. O armazenamento em cache pode ser desativado usando a diretiva enable_cache no contexto do stream.
enable_optimistic_cache	true ou false (false por padrão)	É possível ativar o cache otimizador para a leitura do objeto de arquivo do cache sem a verificação de alteração do objeto subjacente no Cloud Storage desde o último armazenamento. O armazenamento em cache otimizador é ideal para cenários de gravação única e várias leituras.
metadata	Uma matriz associativa, por exemplo	['foo' => 'far', 'bar' => 'boo'] Consulte Como ler e gravar metadados personalizados.
read_cache_expiry_seconds	O número de segundos que um objeto permanece válido no cache	É possível alterar o tempo que um objeto armazenado em cache permanece válido usando o read_cache_expiry_seconds directive. A diretiva especifica o tempo depois de que o objeto será armazenado novamente na próxima tentativa de leitura. Por padrão, o valor é definido como 1 hora (3600).
writable_cache_expiry_seconds	O número de segundos em que o estado gravável de um intervalo é armazenado em cache	No wrapper de stream do Cloud Storage, o estado gravável de buckets é armazenado em cache para melhoria do desempenho. Isso significa que os bits graváveis retornados por várias funções relacionadas a stat() podem estar temporariamente fora de sincronia quando a ACL do intervalo é alterada. Por padrão, o valor é definido como 10 minutos (600).

No snippet a seguir, mostramos 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 snippet acima, $options é um conjunto de argumentos que o stream usará ao gravar novos objetos, que podem ser definidos como as opções padrão usando stream_context_set_default.

Funções do sistema de arquivos PHP compatíveis com o Cloud Storage

O wrapper de stream do App Engine para Cloud Storage é compatível com muitas funções nativas do sistema de arquivos PHP. Algumas funções não são compatíveis e outras têm a compatibilidade modificada. Na tabela a seguir, estão listadas cada uma dessas funções nativas e se elas são compatíveis ou não. Se uma função for compatível, mas com modificações ou limitações, essas características serão descritas.

Função do sistema de arquivos	Compatível?	Detalhes
basename - o componente de nome à direita do caminho é retornado.	Compatível.
chgrp - o grupo de arquivos é alterado.	Incompatível.	O retorno é sempre false.
chmod - o modo de arquivo é alterado.	Incompatível.	O retorno é sempre false.
chown - o proprietário do arquivo é alterado.	Incompatível.	O retorno é sempre false.
clearstatcache - o cache de status do arquivo é limpo.	Compatível.
copy - o arquivo é copiado.	Compatível.
dirname - o caminho do diretório-pai é retornado.	Compatível.	Compatível, mas inclui o prefixo gs://.
disk_free_space - o espaço disponível no sistema de arquivos ou na partição de disco é retornado.	Incompatível.	Está desativada.
disk_total_space - o tamanho total do sistema de arquivos ou da partição de disco é retornado.	Incompatível.	Está desativada.
diskfreespace - alias de disk_free_space.
fclose - um ponteiro de arquivo aberto é fechado.	Compatível.
feof - o fim de arquivo em um ponteiro de arquivo é testado.	Compatível.
fflush - a saída de um arquivo é liberada.	Compatível.	Não tem efeito O retorno é sempre true.
fgetc - o caractere do ponteiro de arquivo é recebido.	Compatível.
fgetcsv - a linha do ponteiro de arquivo é recebida, e os campos CSV são analisados.	Compatível.
fgets - a linha do ponteiro de arquivo é recebida.	Compatível.
fgetss - a linha do ponteiro de arquivo, sem tags HTML, é recebida.	Compatível.
file_exists - verificação da existência de um arquivo ou diretório.	Compatível.
file_get_contents - leitura do arquivo inteiro em uma string.	Compatível.
file_put_contents - gravação de uma string em um arquivo.	Compatível.
arquivo - leitura de todo o arquivo em uma matriz.	Compatível.
fileatime - informa o último horário de acesso do arquivo.	Incompatível.	O retorno é sempre 0.
filectime - informa o tempo de alteração do inode do arquivo.	Incompatível.	O retorno é sempre 0.
filegroup - informa o grupo de arquivos.	Incompatível.	O retorno é sempre 0.
fileinode - informa o inode do arquivo.	Incompatível.	O retorno é sempre 0.
filemtime - informa a hora da modificação do arquivo.	Compatível.
fileowner - informa o proprietário do arquivo.	Incompatível.	O retorno é sempre 0.
fileperms - informa as permissões de arquivo.	Compatível.	O bit de execução está sempre desligado.
filesize - informa o tamanho do arquivo.	Compatível.
filetype - informa o tipo de arquivo.	Compatível.
flock - gerenciamento de arquivos de bloqueio portátil.	Incompatível.	O retorno é sempre false.
fopen - um arquivo ou URL é aberto.	Compatível.	Compatível apenas com estes modos: r, rb, rt, w, wb, wt.
fpassthru - saída de todos os dados restantes em um ponteiro de arquivo.	Compatível.
fputcsv - a linha é formatada como CSV e gravada em um ponteiro de arquivo.	Compatível.
fputs - alias de fwrite.
fread - leitura binary-safe de um arquivo.	Compatível.
fscanf - análise da entrada de um arquivo de acordo com um formato.	Compatível.
fseek - procura um ponteiro de arquivo.	Compatível.	Compatível apenas com arquivos abertos no modo de leitura.
fstat - uso de um ponteiro de arquivo aberto para recuperar informações sobre um arquivo.	Compatível.
ftell - a posição atual do ponteiro de leitura/gravação do arquivo é retornada.	Compatível.
ftruncate - um arquivo é truncado para determinado comprimento.	Incompatível.	O retorno é sempre false.
fwrite - gravação binary-safe de arquivos.	Compatível.
glob - localização de nomes de caminho correspondentes a um padrão.	Compatível.
is_dir - informa se o nome do arquivo é um diretório.	Compatível.
is_executable - informa se o nome do arquivo é executável.	Incompatível.	O retorno é sempre false.
is_file - informa se o nome do arquivo é um arquivo regular.	Compatível.
is_link - informa se o nome do arquivo é um link simbólico.	Incompatível.	O retorno é sempre false.
is_readable - informa se um arquivo existe e é legível.	Compatível.
is_uploaded_file - informa se o arquivo foi enviado via HTTP POST.	Compatível.
is_writable - informa se o nome de arquivo é gravável.	Compatível.	O valor é armazenado em cache e pode não refletir as alterações de permissão imediatamente.
is_writeable - alias de is_writable.
lchgrp - a propriedade do grupo do symlink é alterada.	Incompatível.	Está desativada.
lchown - a propriedade do usuário do symlink é alterada.	Incompatível.	Está desativada.
link - criação de um link físico.	Incompatível.	Está desativada.
linkinfo - recuperação de informações sobre um link.	Incompatível.	O retorno é sempre -1.
lstat - informações sobre um arquivo ou link simbólico.	Compatível.
mkdir - criação de um diretório.	Compatível.
move_uploaded_file - um arquivo carregado é movido para um novo local.	Compatível.
parse_ini_file - análise de um arquivo de configuração.	Compatível.
pathinfo - informações sobre um caminho de arquivo.	Compatível.
pclose - fechamento de um processo como ponteiro de arquivo.	Incompatível.	Está desativada.
popen - abertura de um processo como ponteiro de arquivo.	Incompatível.	Está desativada.
readfile - envio de um arquivo.	Compatível.
readlink - o destino de um link simbólico é retornado.	Incompatível.	O retorno é sempre false.
realpath - o caminho absoluto canonizado é retornado.	Incompatível.	O retorno é sempre false.
rename - um arquivo ou diretório é renomeado.	Compatível.
rewind - a posição de um ponteiro de arquivo é reinicializada.	Compatível.	Compatível apenas com o modo de leitura.
rmdir - remoção do diretório.	Compatível.
set_file_buffer - alias de stream_set_write_buffer.
stat - informações sobre um arquivo.	Compatível.
symlink - criação de um link simbólico.	Incompatível.	Está desativada.
tempnam - criação de um arquivo com um nome de arquivo único.	Compatível.	Consulte estas observações.
tmpfile - criação de um arquivo temporário.	Compatível.	Retorna um arquivo de memória de backup similar a php://memory.
touch - definição do tempo de acesso e modificação do arquivo.	Incompatível.	O retorno é sempre false.
umask - alteração de umask atual.	Compatível.	Não se aplica a arquivos do Cloud Storage.
unlink - um arquivo é excluído.	Compatível.

Observe que as funções stat do arquivo na tabela acima (file_exists, filemtime, filesize, fstat, is_file, is_dir, is_writable e stat) são armazenadas em cache por solicitação. Você pode limpar esse cache chamando clearstatcache.

Além disso, as seguintes funções de leitura de diretório PHP são compatíveis:

Nome da função
opendir
readdir
rewinddir
closedir

Observação: como as operações de listagem do Cloud Storage têm consistência eventual, readdir pode não refletir a alteração imediatamente após um objeto ser adicionado, renomeado ou removido.

Como usar PHP 5 include e require

Para ajudar a manter a segurança do aplicativo, a capacidade de include ou require de um arquivo do Cloud Storage é desativada por padrão, mas você pode ativá-la da seguinte maneira:

Para o código PHP include ou require do Google Cloud Storage no seu aplicativo, especifique quais buckets contêm esses arquivos usando a diretiva google_app_engine.allow_include_gs_buckets em seu arquivo php.ini.

Como ler e gravar metadados personalizados

Para anexar metadados personalizados a um arquivo que está sendo gravado no Google Cloud Storage, adicione-os a $options antes de criar o contexto de stream usado para a chamada file_put_contents.

Neste exemplo, os metadados denominados foo recebem o valor far e outro, chamado bar, recebe o valor boo. O exemplo também define o tipo de conteúdo como text/plain. O contexto do stream é criado usando essas informações em $options, conforme mostrado, e o arquivo é gravado no Cloud Storage usando 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 arquivo, chame fopen no arquivo e use CloudStorageTools::getContentType() para receber o tipo de conteúdo e CloudStorageTools::getMetaData() para receber os metadados.

Os metadados personalizados e o tipo de conteúdo estão disponíveis depois que o ponteiro de arquivo é retornado da chamada de fopen.

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

Leituras de arquivos em cache

Por padrão, o wrapper de stream do App Engine para Cloud Storage armazena em cache as leituras de arquivos no memcache para melhorar o desempenho nas leituras subsequentes. O armazenamento em cache pode ser desativado usando a diretiva enable_cache no contexto do stream.

Observação: quando o armazenamento em cache está ativado, os arquivos lidos no Cloud Storage são armazenados em cache à medida que são lidos. O cache também contém as informações do arquivo sobre a capacidade de gravação. Portanto, esteja ciente de que is_writable pode estar consultando informações de arquivo desatualizadas. Além disso, se você alterar a ACL de um bucket do Cloud Storage para conceder ou negar permissões de gravação ao aplicativo, essa alteração poderá levar algum tempo para ser refletida.

Para melhorar ainda mais o desempenho, também é possível ativar o cache otimista, que lerá o objeto de arquivo do cache sem ver se o objeto subjacente foi alterado no Google Cloud Storage desde a última vez em que foi armazenado, usando a diretiva enable_optimistic_cache (definida como false por padrão). O armazenamento em cache otimizador é ideal para cenários de gravação única e várias leituras.

Também é possível alterar o tempo que um objeto em cache permanece válido usando a diretiva read_cache_expiry_seconds. Depois desse tempo, o objeto será armazenado em cache novamente na próxima tentativa de leitura. Por padrão, o valor é definido como 1 hora (3600).

Neste exemplo, o armazenamento em cache otimizador está ativado, e os objetos de arquivo são configurados para serem marcados para novo armazenamento no 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);