Phar

Introdução

A extensão phar fornece uma maneira de colocar aplicações PHP inteiras em um único arquivo chamado "phar" (Arquivo PHP) para fácil distribuição e instalação. Além de fornecer este serviço, a extensão phar também fornece um método de abstração de formato de arquivo para criar e manipular arquivos tar e zip através da classe PharData, assim como o PDO fornece uma interface unificada para acessar diferentes bancos de dados. Ao contrário do PDO, que não pode converter entre bancos de dados diferentes, o Phar também pode converter entre os formatos de arquivo tar, zip e phar com uma única linha de código. Veja Phar::convertToExecutable() para um exemplo.

O que é phar? Arquivos phar são melhor caracterizados como uma maneira conveniente de agrupar vários arquivos em um único arquivo. Assim, um arquivo phar fornece uma maneira de distribuir uma aplicação PHP completa em um único arquivo e executá-la a partir desse arquivo sem a necessidade de extraí-la para o disco. Além disso, arquivos phar podem ser executados pelo PHP tão facilmente quanto qualquer outro arquivo, tanto na linha de comando quanto em um servidor web. Phar é como um pen drive para aplicações PHP.

Phar implementa essa funcionalidade por meio de um empacotador de fluxo. Normalmente, para usar um arquivo externo dentro de um script PHP, seria usado include:

Exemplo #1 Using an external file

<?php
 include '/caminho/para/arquivo/externo.php';
 ?>

Pode-se pensar que o PHP está, na verdade, traduzindo /caminho/para/arquivo/externo.php em um empacotador de fluxo como arquivo:///caminho/para/arquivo/externo.php e, nos bastidores, ele de fato usa as funções do empacotador de fluxo de arquivo simples para acessar todos os arquivos locais.

Para usar um arquivo chamado arquivo.php contido em um arquivo phar /caminho/para/meuphar.phar, a sintaxe é muito semelhante à sintaxe file:// acima.

Exemplo #2 Usando um arquivo dentro de um arquivo phar

<?php
 include 'phar:///caminho/para/meuphar.phar/arquivo.php';
 ?>

De fato, é possível tratar um arquivo phar exatamente como se fosse um disco externo, usando qualquer uma das funções relacionadas a fopen(), opendir() e funções relacionadas a mkdir() para ler, alterar ou criar novos arquivos e diretórios dentro do arquivo phar. Isso permite que aplicações PHP completas sejam distribuídas em um único arquivo e executadas diretamente a partir dele.

O uso mais comum de um arquivo phar é distribuir uma aplicação completa em um único arquivo. Por exemplo, o Instalador PEAR, que acompanha as versões do PHP é distribuído como um arquivo phar. Para usar um arquivo phar distribuído desta forma, o arquivo pode ser executado na linha de comando ou por meio de um servidor web.

Os arquivos Phar podem ser distribuídos como arquivos tar, arquivos zip ou como o formato de arquivo phar personalizado projetado especificamente para a extensão phar. Cada formato de arquivo tem vantagens e desvantagens. Os formatos de arquivo tar e zip podem ser lidos ou extraídos por qualquer ferramenta de terceiros que possa ler o formato, mas que requer a extensão phar para executar com PHP. O formato de arquivo phar é personalizado e exclusivo para a extensão phar, e só pode ser criado pela extensão phar ou pelo pacote PEAR » PHP_Archive, mas tem a vantagem de que as aplicações criadas neste formato serão executadas mesmo se a extensão phar não estiver habilitada.

Em outras palavras, mesmo com a extensão phar desabilitada, é possível executar ou incluir um arquivo baseado em phar. Acessar arquivos individuais dentro de um arquivo phar só é possível com a extensão phar, a menos que o arquivo phar tenha sido criado pelo PHP_Archive.

A extensão phar também é capaz de converter um arquivo phar de tar para zip ou para o formato de arquivo phar em um único comando:

Exemplo #3 Convertendo um arquivo phar do formato phar para tar

<?php
$phar = new Phar('meuphar.phar');
$pgz = $phar->convertToExecutable(Phar::TAR, Phar::GZ); // cria meuphar.phar.tar.gz
?>

O Phar pode compactar arquivos individuais ou um arquivo inteiro usando a compactação gzip ou bzip2, e pode verificar a integridade do arquivo automaticamente por meio do uso de assinaturas MD5, SHA-1, SHA-256 ou SHA-512.

Por fim, a extensão Phar é voltada para a segurança e desabilita o acesso de gravação aos arquivos Phar executáveis por padrão, além de exigir a desativação, em nível de sistema, da configuração phar.readonly do php.ini para criar ou modificar arquivos Phar. Arquivos tar e zip normais sem um stub executável sempre podem ser criados ou modificados usando a classe PharData.

Se aplicações para distribuição estiverem sendo criadas, leia Como criar arquivos Phar. Se quiser mais informações sobre as diferenças entre os três formatos de arquivo suportados pelo Phar, leia Phar, Tar e Zip.

Se aplicações Phar estiverem sendo usadas, há dicas úteis em Como usar os Arquivos Phar.

A palavra phar é uma junção de PHP e Archive e é vagamente baseada no jar (Java Archive), familiar aos desenvolvedores Java.

A implementação para arquivos Phar é baseada no pacote PEAR » PHP_Archive, e os detalhes de implementação são semelhantes, embora a extensão Phar seja muito mais poderosa. Além disso, a extensão Phar permite que a maioria das aplicações PHP sejam executadas sem modificações, enquanto os arquivos Phar baseados em PHP_Archive geralmente exigem modificações extensas para funcionar.

Instalação/Configuração
Constantes predefinidas
Usando Arquivos Phar
Criando Arquivos Phar
- Criando Arquivos Phar: Introdução
O que faz um phar ser um phar e não um tar ou um zip?
Phar — A classe Phar
- Phar::addEmptyDir — Adiciona um diretório vazio ao arquivo phar
- Phar::addFile — Adiciona um arquivo do sistema de arquivos ao arquivo phar
- Phar::addFromString — Adiciona um arquivo a partir de uma string ao arquivo phar
- Phar::apiVersion — Retorna a versão da API
- Phar::buildFromDirectory — Constrói um arquivo phar a partir dos arquivos dentro de um diretório
- Phar::buildFromIterator — Constrói um arquivo phar a partir de um iterador
- Phar::canCompress — Retorna se a extensão phar suporta compactação usando zlib ou bzip2
- Phar::canWrite — Retorna se a extensão phar suporta a escrita e criação de phars
- Phar::compress — Compacta todo o arquivo Phar usando compactação Gzip ou Bzip2
- Phar::compressFiles — Compacta todos os arquivos no arquivo Phar atual
- Phar::__construct — Constrói um objeto de arquivo Phar
- Phar::convertToData — Converte um arquivo phar em um arquivo tar ou zip não executável
- Phar::convertToExecutable — Converte um arquivo phar em outro formato de arquivo executável phar
- Phar::copy — Copia um arquivo interno do arquivo phar para outro novo arquivo dentro do phar
- Phar::count — Retorna o número de entradas (arquivos) no arquivo Phar
- Phar::createDefaultStub — Cria um stup de formato específico de arquivo phar
- Phar::decompress — Descompacta todo o arquivo Phar
- Phar::decompressFiles — Descompacta todos os arquivos no arquivo Phar atual
- Phar::delMetadata — Exclui os metadados globais do phar
- Phar::delete — Exclui um arquivo dentro de um arquivo phar
- Phar::__destruct — Destrói um objeto de arquivo Phar
- Phar::extractTo — Extrai o conteúdo de um arquivo phar para um diretório
- Phar::getAlias — Obtém o apelido para o Phar
- Phar::getMetadata — Retorna metadados do arquivo phar
- Phar::getModified — Informa se o phar foi modificado
- Phar::getPath — Obtém o caminho real para o arquivo Phar no disco
- Phar::getSignature — Retorna a assinatura MD5/SHA1/SHA256/SHA512/OpenSSL de um arquivo Phar
- Phar::getStub — Retorna o carregador PHP ou o stub de inicialização de um arquivo Phar
- Phar::getSupportedCompression — Retorna um array de algoritmos de compactação suportados
- Phar::getSupportedSignatures — Retorna um array de tipos de assinatura suportados
- Phar::getVersion — Retorna informações da versão do arquivo Phar
- Phar::hasMetadata — Informa se o phar tem metadados globais
- Phar::interceptFileFuncs — Instrui phar a interceptar fopen, file_get_contents, opendir e todas as funções relacionadas a stat
- Phar::isBuffering — Usado para determinar se as operações de gravação Phar estão sendo armazenadas em buffer ou estão sendo liberadas diretamente no disco
- Phar::isCompressed — Retorna Phar::GZ ou PHAR::BZ2 se todo o arquivo phar estiver compactado (.tar.gz/tar.bz e assim por diante)
- Phar::isFileFormat — Informa se o arquivo phar é baseado no formato de arquivo tar/phar/zip dependendo do parâmetro
- Phar::isValidPharFilename — Informa se o nome de arquivo fornecido é um nome de arquivo phar válido
- Phar::isWritable — Informa se o arquivo phar pode ser modificado
- Phar::loadPhar — Carrega qualquer arquivo phar com um apelido
- Phar::mapPhar — Lê o arquivo atualmente em execução (um phar) e registra seu manifesto
- Phar::mount — Monta um caminho externo ou arquivo em um local virtual dentro do arquivo phar
- Phar::mungServer — Define uma lista de até 4 variáveis $_SERVER que devem ser modificadas para execução
- Phar::offsetExists — Determina se um arquivo existe no phar
- Phar::offsetGet — Obtém um objeto PharFileInfo para um arquivo específico
- Phar::offsetSet — Define o conteúdo de um arquivo interno para o de um arquivo externo
- Phar::offsetUnset — Remove um arquivo de um phar
- Phar::running — Retorna o caminho completo no disco ou a URL completa do arquivo Phar em execução no momento
- Phar::setAlias — Define o apelido para o arquivo Phar
- Phar::setDefaultStub — Usado para definir o carregador PHP ou o stub de bootstrap de um arquivo Phar para o carregador padrão
- Phar::setMetadata — Define metadados do arquivo phar
- Phar::setSignatureAlgorithm — Define o algoritmo de assinatura para um phar e o aplica
- Phar::setStub — Usado para definir o carregador PHP ou o stub de inicialização de um arquivo Phar
- Phar::startBuffering — Inicia o buffer das operações de gravação Phar, não modifica o objeto Phar no disco
- Phar::stopBuffering — Interrompe o buffer de solicitações de gravação no arquivo Phar e salva as alterações no disco
- Phar::unlinkArchive — Remove completamente um arquivo phar do disco e da memória
- Phar::webPhar — Encaminha uma solicitação de um navegador da web para um arquivo interno dentro do arquivo phar
PharData — A classe PharData
- PharData::addEmptyDir — Adiciona um diretório vazio ao arquivo tar/zip
- PharData::addFile — Adiciona um arquivo do sistema de arquivos ao arquivo tar/zip
- PharData::addFromString — Adiciona um arquivo de uma string ao arquivo tar/zip
- PharData::buildFromDirectory — Constrói um arquivo tar/zip a partir dos arquivos dentro de um diretório
- PharData::buildFromIterator — Constrói um arquivo tar ou zip a partir de um iterador
- PharData::compress — Compacta todo o arquivo tar/zip usando Gzip ou Bzip2
- PharData::compressFiles — Compacta todos os arquivos no arquivo tar/zip atual
- PharData::__construct — Constrói um objeto de arquivo tar ou zip não executável
- PharData::convertToData — Converte um arquivo phar em um arquivo tar ou zip não executável
- PharData::convertToExecutable — Converte um arquivo tar/zip não executável em um arquivo phar executável
- PharData::copy — Copia um arquivo interno do arquivo tar/zip para outro arquivo novo dentro do mesmo arquivo
- PharData::decompress — Descompacta todo o arquivo Phar
- PharData::decompressFiles — Descompacta todos os arquivos no arquivo zip atual
- PharData::delMetadata — Exclui os metadados globais de um arquivo zip
- PharData::delete — Exclui um arquivo dentro de um arquivo tar/zip
- PharData::__destruct — Destrói um objeto de arquivo tar ou zip não executável
- PharData::extractTo — Extrai o conteúdo de um arquivo tar/zip para um diretório
- PharData::isWritable — Informa se o arquivo tar/zip pode ser modificado
- PharData::offsetSet — Define o conteúdo de um arquivo dentro do tar/zip para o de um arquivo externo ou string
- PharData::offsetUnset — Remove um arquivo de um arquivo tar/zip
- PharData::setAlias — Função fictícia (Phar::setAlias não é válido para PharData)
- PharData::setDefaultStub — Função fictícia (Phar::setDefaultStub não é válido para PharData)
- PharData::setMetadata — Define metadados do arquivo phar
- PharData::setSignatureAlgorithm — Define o algoritmo de assinatura para um phar e o aplica
- PharData::setStub — Função fictícia (Phar::setStub não é válido para PharData)
PharFileInfo — A classe PharFileInfo
- PharFileInfo::chmod — Define bits de permissão específicos do arquivo
- PharFileInfo::compress — Compacta a entrada Phar atual com zlib ou bzip2
- PharFileInfo::__construct — Constrói um objeto de entrada Phar
- PharFileInfo::decompress — Descompacta a entrada Phar atual dentro do phar
- PharFileInfo::delMetadata — Exclui os metadados da entrada
- PharFileInfo::__destruct — Destrói um objeto de entrada Phar
- PharFileInfo::getCRC32 — Retorna o código CRC32 ou lança uma exceção se o CRC não tiver sido verificado
- PharFileInfo::getCompressedSize — Retorna o tamanho real do arquivo (com compactação) dentro do arquivo Phar
- PharFileInfo::getContent — Obtém o conteúdo completo do arquivo de entrada
- PharFileInfo::getMetadata — Retorna metadados específicos do arquivo salvos com um arquivo
- PharFileInfo::getPharFlags — Retorna os sinalizadores de entrada do arquivo Phar
- PharFileInfo::hasMetadata — Retorna os metadados da entrada
- PharFileInfo::isCRCChecked — Informa se a entrada do arquivo teve seu CRC verificado
- PharFileInfo::isCompressed — Informa se a entrada está compactada
- PharFileInfo::setMetadata — Define metadados específicos de arquivo salvos com um arquivo
PharException — A classe PharException