Manual do PHP
Copyright
Copyright © 1997 - 2012 para o PHP Documentation Group. Este material pode ser distribuído apenas sob os termos e condições determinadas pela Creative Commons Attribution 3.0 ou posteriores. Uma cópia da Creative Commons Attribution 3.0 license é distribuída com esse manual. A úlima versão está atualmente disponível em » http://creativecommons.org/licenses/by/3.0/.
Se você está interessado na redistribuição ou republicação deste documento no todo ou em parte, tanto modificao ou não, ou se você tem qualquer questão, basta contatar os responsáveis pelo copyright em » doc-license@lists.php.net. Note que esse endereço tem suas mensagens preservadas em um arquivo público.
Manual do PHP
Prefácio
PHP, que significa "PHP: Hypertext Preprocessor", é uma linguagem de programação de ampla utilização, interpretada, que é especialmente interessante para desenvolvimento para a Web e pode ser mesclada dentro do código HTML. A sintaxe da linguagem lembra C, Java e Perl, e é fácil de aprender. O objetivo principal da linguagem é permitir a desenvolvedores escreverem páginas que serão geradas dinamicamente rapidamente, mas você pode fazer muito mais do que isso com PHP.
Esse manual consiste primeiramente de uma referência de funções, mas ele também contém uma referência da linguagem, explicações sobre as mais importantes características do PHP, e outras informações suplementares.
Você pode fazer o download deste manual em vários formatos em » http://www.php.net/download-docs.php. Mais informações sobre como esse manual é desenvolvido podem ser encontradas no apêndice 'Sobre o manual'. Se você está interessado na história do PHP, veja o apêndice relevante.
Autores e colaboradores
Nós enfatizamos as pessoas mais ativas na capa do manual, mas há muitos mais colaboradores que atualmente nos ajudam no trabalho ou proveram uma enorme quantidade de ajuda no passado. Há uma enormidade de pessoas não citadas que ajudam com suas notas nas páginas do manual, que são continuamente inclúidas no corpo do manual, trabalho esse que nós somos muito gratos. A lista a seguir está em ordem alfabética.
Autores e Editores
Os seguintes colaboradores devem ser reconhecidos pelo impacto que tiveram e/ou continuam a ter pelo acréscimo de material ao manual: Bill Abt, Jouni Ahto, Alexander Aulbach, Daniel Beckham, Stig Bakken, Nilgün Belma Bugüner, Jesus M. Castagnetto, Ron Chmara, Sean Coates, John Coggeshall, Simone Cortesi, Peter Cowburn, Daniel Egeberg, Markus Fischer, Wez Furlong, Sara Golemon, Rui Hirokawa, Brad House, Pierre-Alain Joye, Etienne Kneuss, Moriyoshi Koizumi, Rasmus Lerdorf, Andrew Lindeman, Stanislav Malyshev, Justin Martin, Rafael Martinez, Rick McGuire, Moacir de Oliveira Miranda Júnior, Kalle Sommer Nielsen, Yasuo Ohgaki, Richard Quadling, Derick Rethans, Rob Richards, Sander Roobol, Egon Schmid, Thomas Schoefbeck, Sascha Schumann, Dan Scott, Masahiro Takagi, Yannick Torres, Michael Wallner, Lars Torben Wilson, Jim Winstead, Jeroen van Wolffelaar e Andrei Zmievski.
Os seguintes colaboradores já fizeram um significativo trabalho editando esse manual: Stig Bakken, Gabor Hojtsy, Hartmut Holzgraefe e Egon Schmid.
Mantenedores das notas de usuários
Mantenedores mais ativos: Daniel Brown, Nuno Lopes, Felipe Pena, Thiago Pojda e Maciek Sokolewicz.
Estas pessoas já fizeram um grande esforço cuidando das notas de usuários Mehdi Achour, Daniel Beckham, Friedhelm Betz, Victor Boivie, Jesus M. Castagnetto, Nicolas Chaillan, Ron Chmara, Sean Coates, James Cox, Vincent Gevers, Sara Golemon, Zak Greant, Szabolcs Heilig, Oliver Hinckel, Hartmut Holzgraefe, Etienne Kneuss, Rasmus Lerdorf, Matthew Li, Andrew Lindeman, Aidan Lister, Hannes Magnusson, Maxim Maletsky, Bobby Matthis, James Moore, Philip Olson, Sebastian Picklum, Derick Rethans, Sander Roobol, Damien Seguy, Jason Sheets, Tom Sommer, Jani Taskinen, Yasuo Ohgaki, Jakub Vrana, Lars Torben Wilson, Jim Winstead, Jared Wyles e Jeroen van Wolffelaar.
Começando
O que é PHP?
PHP (um acrônimo recursivo para PHP: Hypertext Preprocessor) é uma linguagem de script open source de uso geral, muito utilizada e especialmente guarnecida para o desenvolvimento de aplicações Web embútivel dentro do HTML.
Ótimo, mas o que isso significa?
Exemplo #1 Um exemplo introdutório
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Exemplo</title>
</head>
<body>
<?php
echo "Olá, Eu sou um script PHP!";
?>
</body>
</html>
Ao invés de muitos comandos para mostrar HTML (como visto em C ou Perl),
páginas PHP contém HTML juntamente com códigos que fazem "alguma coisa"
(neste caso, mostra "Olá, Eu sou um script PHP!")
O código PHP é delimitado por tags iniciais e finais
<?php e ?>
que lhe permitem pular pra dentro e pra fora do "modo PHP".
O que distingui o PHP de algo como Javascript no lado do cliente é que o código é executado no servidor, gerando HTML que é então enviado para o cliente. O cliente receberia os resultados da execução desse script, mas não saberia como é o código fonte. Você pode inclusive configurar seu servidor para processar todos os seus arquivos HTML como PHP, e então não haverá nenhum modo dos usuários descobrirem que se você usa essa linguagem ou não.
A melhor coisa em usar PHP está no fato de ele ser extremamente simples para um iniciante, mas oferece muitos recursos para o programador profissional. Não se preocupe em ler as longas listas de funções do PHP. Você pode pular essa parte (por enquanto) e começar a escrever scripts em poucas horas.
Apesar do desenvolvimento do PHP ser focado nos scripts do lado do servidor, você pode fazer muito mais com ele. Veja isso e leia mais na seção O que o PHP pode fazer?, ou diretamente no tutorial introdutório se você estiver interessado em programação web.
O que o PHP pode fazer?
Qualquer coisa. O PHP é focado para ser uma linguagem de script do lado do servidor, portanto, você pode fazer qualquer coisa que outro programa CGI pode fazer, como: coletar dados de formulários, gerar páginas com conteúdo dinâmico ou enviar e receber cookies. Mas o PHP pode fazer muito mais.
Esses são os maiores campos onde os scripts PHP podem ser utilizados:
- Script no lado do servidor (server-side). Este é o mais tradicional e principal campo de atuação do PHP. Você precisa de três coisas para seu trabalho. O interpretador do PHP (como CGI ou módulo), um servidor web e um browser. Basta rodar o servidor web conectado a um PHP instalado. Você pode acessar os resultados de seu programa PHP com um browser, visualizando a página PHP através do servidor web. Todos eles podem rodar na sua máquina, em casa, para você experimentar programação com o PHP. Veja a seção das instruções de instalação para mais informações.
- Script de linha de comando. Você pode fazer um script PHP funcionar sem um servidor web ou browser. A única coisa necessária é o interpretador. Esse tipo de uso é ideal para script executados usando o cron ou o Agendador de Tarefas (no Windows). Esses scripts podem ser usados também para rotinas de processamento de texto. Veja a seção Utilizando o PHP em linha de comando para maiores informações.
- Escrevendo aplicações desktop. O PHP provavelmente não é a melhor linguagem para criação de aplicações desktop com interfaces gráficas, mas se você conhece bem o PHP, e gostaria de usar alguns dos seus recursos avançados nas suas aplicações do lado do cliente, você pode usar o PHP-GTK para escrever programas assim. Isso ainda lhe habilita a escrever aplicações multi-plataformas. O PHP-GTK é uma extensão do PHP, não disponibilizada na distribuição oficial. Caso esteja interessado no PHP-GTK, visite » o site do projeto.
O PHP pode ser utilizado na maioria dos sistemas operacionais, incluindo Linux, várias variantes Unix (incluindo HP-UX, Solaris e OpenBSD), Microsoft Windows, Mac OS X, RISC OS, e provavelmente outros. O PHP também é suportado pela maioria dos servidores web atuais, incluindo Apache, Microsoft Internet Information Server, Personal Web Server, Netscape and iPlanet Servers, Oreilly Website Pro Server, Caudium, Xitami, OmniHTTPd, e muitos outros. O PHP pode ser configurado como módulo para a maioria dos servidores, e para os outros como um CGI comum.
Com o PHP, portanto, você tem a liberdade para escolher o sistema operacional e o servidor web. Do mesmo modo, você pode escolher entre utilizar programação estrutural ou programação orientada a objeto, ou ainda uma mistura deles. Mesmo sem todos os recursos da POO (Programação Orientada a Objetos) implementados no PHP 4, muitas bibliotecas de código e grandes aplicações (incluindo a biblioteca PEAR) são escritas somente em código POO. O PHP 5 corrige as fraquezas da POO do PHP 4, e introduz um modelo de objetos completo.
Com PHP você não está limitado a gerar somente HTML. As habilidades do PHP incluem geração de imagens, arquivos PDF e animações Flash (utilizando libswf ou Ming) criados dinamicamente, on the fly. Você pode facilmente criar qualquer padrão texto, como XHTML e outros arquivos XML. O PHP pode gerar esses padrões e os salvar no sistema de arquivos, em vez de imprimi-los, formando um cache dinâmico de suas informações no lado do servidor.
Talvez a mais forte e mais significativa característica do PHP é seu suporte a uma ampla variedade de banco de dados. Escrever uma página que consulte um banco de dados é incrivelmente simples. Os seguintes bancos de dados são atualmente suportados:
Também foi providenciado uma abstração de banco de dados (chamada PDO) permitindo a você utilizar qualquer banco de dados transparentemente com sua extensão. Adicionalmente, o PHP suporta ODBC (Open Database Connection, ou Padrão Aberto de Conexão com Bancos de Dados), permitindo que você utilize qualquer outro banco de dados que suporte esse padrão mundial.
- Adabas D
- dBase
- Empress
- FilePro (read-only)
- Hyperwave
- IBM DB2
- Informix
- Ingres
- InterBase
- FrontBase
- mSQL
- Direct MS-SQL
- MySQL
- ODBC
- Oracle (OCI7 and OCI8)
- Ovrimos
- PostgreSQL
- SQLite
- Solid
- Sybase
- Velocis
- Unix dbm
O PHP também tem suporte para comunicação com outros serviços utilizando protocolos como LDAP, IMAP, SNMP, NNTP, POP3, HTTP, COM (em Windows) e incontáveis outros. Você pode abrir sockets de rede e interagir diretamente com qualquer protocolo. O PHP também suporta o intercâmbio de dados complexos WDDX, utilizado em virtualmente todas as linguagens de programação para web. Falando de comunicação, o PHP implementa a instanciação de objetos Java e os utiliza transparentemente como objetos PHP. Você ainda pode usar sua extensão CORBA para acessar objetos remotos.
O PHP é extremamente útil em recursos de processamento de texto, do POSIX Estendido ou expressões regulares Perl até como interpretador para documentos XML. No processamento de XML, o PHP 4 suporta os padrões SAX e DOM, além de você também poder utilizar a extensão XSL para transformar documentos XML. O PHP 5 padroniza toda a extensão XML a partir da base sólida da libxml2, além de estender os recursos com o acréscimo ao SimpleXML e XMLReader.
Por último mas longe de terminar, temos também outras extensões interessantes: funções para o search engine mnoGoSearch, funções para Gateway IRC, vários utilitários de compressão (gzip, bz2, zip), calendário e conversões de datas, tradução...
Como você pode ver, esta página não é suficiente para descrever todos os recursos e benefícios que o PHP pode oferecer. Leia nas seções sobre a Instalação do PHP, e veja a referência das funções para detalhes das extensões mencionadas aqui.
Um simples tutorial
Índice
- O que eu preciso?
- Sua primeira página PHP
- Algo Útil
- Tratando Formulários
- Usando códigos antigos com a nova versão do PHP
- O que mais?
Aqui nós iremos mostrar o básico do básico do PHP em um curto tutorial. Este texto fala somente sobre a criação de páginas dinâmicas com o PHP, visto que o PHP pode criar mais do que somente webpages. Veja a seção entitulada O que o PHP pode fazer para mais informações.
Fazer páginas com PHP é o mesmo que criar páginas HTML e você pode criá-las e editá-las da mesma maneira que faz com suas páginas HTML normal.
O que eu preciso?
Neste tutorial nós presumimos que seu servidor tem suporte ao PHP ativado e que todos os arquivos terminam com a extensão .php são tratados pelo PHP. Na maioria dos servidores esta é a extensão padrão para os arquivos PHP, mas pergunte ao seu administrador só para ter certeza. Se o seu servidor suporta PHP então você não precisa fazer mais nada. Apenas crie seus arquivos .php e coloque-os no seu diretório web e o servidor irá com um passe de mágica mostrar suas páginas PHP. Não há nenhuma necessidade de compilação para qualquer ferramenta extra. Pense nesses arquivos PHP como se eles fossem páginas HTML com algumas tags à mais que deixaram você fazer coisas mais interessantes do que somente páginas HTML estáticas.
Digamos que você quer salvar sua preciosa conexão e desenvolver tudo localmente. Neste caso, você precisará instalar um servidor web, como o » Apache, e claro o » PHP. Você também irá querer instalar uma base de dados, como por exemplo o » MySQL. Você pode instalá-los separadamente ou pelo jeito mais simples que é » usar os pacotes pré-configurados. que irão instalar automaticamente todas as coisas com apenas alguns cliques. É super fácil configurar um servidor web com suporte ao PHP em qualquer sistema operacional, incluindo Linux e Windows. No Linux, você deve procurar o » rpmfind que é muito útil na localização de pacotes RPM.
Sua primeira página PHP
Crie um novo arquivo chamado ola.php e coloque-o em seu diretório root do seu servidor web (DOCUMENT_ROOT) com o seguinte conteúdo:
Exemplo #1 Nosso primeiro script PHP: ola.php
<html>
<head>
<title>PHP Teste</title>
</head>
<body>
<?php echo "<p>Olá Mundo</p>"; ?>
</body>
</html>
Use o seu navegador para acessar o arquivo pelo endereço de seu servidor web, ao final do endereço coloque o arquivo "/ola.php" como referência. Quando o desenvolvimento é local você usará uma url como esta http://localhost/ola.php ou http://127.0.0.1/ola.php mas dependendo da configuração do seu servidor web. Entretanto isto está fora do escopo deste tutorial, veja também as diretivas DocumentRoot e ServerName dos arquivos de configuração do seu servidor web. (no Apache o nome do arquivo é httpd.conf). Se tudo foi configurado corretamente, o arquivo irá ser interpretado pelo PHP e irá mostrar a seguinte mensagem de saída no seu navegador:
<html> <head> <title>PHP Teste</title> </head> <body> <p>Olá Mundo</p> </body> </html>
Note que isto não é como em um script CGI. O arquivo não precisa ser executável ou especial em nenhum aspecto. Pense nesse arquivo como um arquivo HTML normal mas com a diferença que ele pode conter algumas tags especiais a mais que permitem a você fazer coisas mais interessantes do que somente páginas HTML estáticas.
Este exemplo é extremamente simples e você realmente não precisa usar o PHP para criar uma página como esta. Tudo o que ele faz é mostrar uma mensagem Olá Mundo usando a declaração echo() do PHP.
Se você tentar rodar este exemplo e ele não mostrar nenhuma mensagem de saída, ou aparecer uma caixa de diálogo pedindo para você salvar o arquivo, ou você ver o arquivo em formato de texto, há uma grande chance do seu servidor não ter o PHP habilitado. Peça ao seu administrar para habilitar o PHP para você, usando o capítulo de Instalação do manual. Se você está desenvolvendo localmente, também leia o capítulo indicado acima para ter certeza de que configurou tudo corretamente. Se os problemas continuarem a persistir, não hesite em usar uma das várias formas de » ajuda que o PHP pode lhe oferecer.
O objetivo do exemplo é mostrar o formato especial das tags do PHP. Neste exemplo nós usamos <?php para indicar que à partir daquele ponto começa um código PHP. Então nós colocamos uma declaração de fechamento para indicar que o script PHP acabou, usando a tag ?>. Você pode usar o PHP em qualquer parte do seu código HTML, e também pode usar várias tags de abertura e fechamento no mesmo arquivo. Para mais detalhes, leia a seção do manual que fala da sintaxe básica do PHP.
Nota: Uma Nota sobre os Editores de Texto
Há muitos editores de textos e Integrated Development Enviroments (IDEs) que você pode usar para criar, editar e gerenciar arquivos PHP. Uma lista parcial destas ferramentas pode ser vista na » Lista de Editores para PHP. Se você gostaria de recomendar algum editor, por favor visite o endereço acima e pergunte ao administrador do site para adicionar o seu editor à lista. Ter um editor que colora as sintaxes das tags pode ser muito útil.
Nota: Uma Nota sobre os Processadores Word
Processadores Word como o StarOffice Write, Microsoft Word e Abiword não são boas escolhas para editar arquivos PHP. Se você deseja usar um desses para testar seus scripts, você precisa verificar se você está salvando os arquivos como TEXTO PLANO ou o PHP não irá ser capaz de ler e executar o seu script.
Nota: Uma Nota sobre o Bloco de Notas do Windows
Se você está escrevendo seus scripts PHP usando o Bloco de Notas do Windows, você precisará verificar que os arquivos estão sendo salvos com a extensão .php. (O Bloco de Notas do Windows adiciona automaticamente a extensão .txt aos arquivos a não ser que você siga um dos passos a seguir para previnir isto). Quando a caixa de diálogo Salvar estiver aberta e você for digitar o nome do seu arquivo, coloque o nome do arquivo entre aspas (i.e. "ola.php"). Uma alternativa, é você clicar na lista drop-down 'Documentos de Texto' na caixa de diálogo salvar e alterar para "Todos os tipos de arquivos". Você agora pode digitar o nome do seu arquivo sem usar as aspas.
Agora que você criou com sucesso um script simples em PHP, é hora de criar o mais famoso dos scripts PHP! Uma chamada à função phpinfo() e você verá todas as informações sobre seu sistema e configurações disponíveis como a de Variáveis Pré-definidas, módulos carregados pelo PHP, e as opções de configuração. Tire algum tempo para ver e rever estas importantes informações.
Algo Útil
Vamos fazer alguma coisa um pouco mais útil agora. Nós iremos checar qual é o tipo de navegador que o visitante está utilizando para ver a nossa página. De fato, para fazer isto nós teremos que checar qual é o valor da string agente que o navegador envia como parte de sua requisição HTTP. Esta informação é armazenada em uma variável. Variáveis sempre começam com um símbolo de cifrão no PHP. A variável que nos interessa no momento é a $_SERVER["HTTP_USER_AGENT"].
Nota: Nota sobre as Auto-Globais do PHP
$_SERVER é uma variável especial reservada do PHP que contém todas as informações sobre o servidor web. Ela é conhecida como uma Auto-Global (ou Superglobal). Veja a página do manual relacionada as Auto-globais para mais informações. Estas variáveis especiais foram introduzidas no PHP » 4.1.0. Antes desta versão, nós usávamos os velhos arrays $HTTP_*_VARS, como o $HTTP_SERVER_VARS. Entretanto, este estilo antigo foi removido, porém ainda existem. (Veja a nota sobre códigos antigos.)
Para chamar esta variável, nós podemos fazer isto:
Exemplo #1 Imprimindo a variável (Elemento Array)
<?php echo $_SERVER["HTTP_USER_AGENT"]; ?>
Um exemplo de saída deste script poderia ser:
Mozilla/4.0 (compatible; MSIE 5.01; Windows NT 5.0)
Há muitos tipos de variáveis disponíveis no PHP. No exemplo acima nós escrevemos um elemento Array. Arrays podem ser muito úteis.
$_SERVER é somente uma variável que é automaticamente disponibilizada para você pelo PHP. Uma lista de Variáveis Reservadas pode ser vista na seção Variáveis Reservadas do manual ou você pode pegar uma lista completa delas criando um arquivo como este:
Exemplo #2 Exibindo todas as variáveis pré-definidas usando a função phpinfo()
<?php phpinfo(); ?>
Se você carregar este arquivo no seu navegador você irá ver uma página com todas as informações sobre o PHP junto com uma lista de todos os tipos de variáveis disponíveis para você.
Você pode colocar múltiplas declarações PHP dentro da tag PHP e criar pequenos blocos de códigos que fazem muito mais do que um simples echo. Por exemplo, se você quer checar se o navegador é o Internet Explorer faça algo como isso:
Exemplo #3 Exemplo usando controles de declarações e funções
<?php
if (strstr($_SERVER["HTTP_USER_AGENT"], "MSIE")) {
echo "Você está usando o Internet Explorer<br />";
}
?>
Um exemplo de Saída seria:
Você está usando o Internet Explorer<br />
Aqui nós mostraremos alguns novos conceitos. Nós temos a declaração if. Se você é familiar com a sintaxe básica usada pela linguagem C isto parecerá ser lógico para você. Se você não conhece a linguagem C ou alguma outra linguagem onde a sintaxe usada acima é usada, você provavelmente precisará de um livro introdutório sobre o PHP, dê uma lida nos primeiros capítulos do livro, ou leia a parte sobre a Referência da Linguagem no manual. Você pode encontrar uma lista de livros sobre PHP em at » http://www.php.net/books.php.
O segundo conceito que iremos abordar é a chamada à função strstr(). A função strstr() é trazida junto com o PHP, ela faz uma busca em uma palavra por uma outra palavra. Neste caso nós procuramos pela palavra "MSIE" dentro de $_SERVER["HTTP_USER_AGENT"]. Se a palavra for encontrada, a função retorna TRUE e se ela não for encontrada a função retorna FALSE. Se o retorno for TRUE, a declaração if ocorre e o código dentro dela é executado. Caso contrário, o código não é executado. Sinta-se à vontade para criar exemplos similares com o if, else, e outras funções como a strtoupper() e strlen(). Cada uma delas está no manual com seus respectivos exemplos.
Nós podemos avançar agora e mostrar a você como alternar entre os modos PHP mesmo que você esteja executando blocos de códigos:
Exemplo #4 Mesclando entre os modos PHP e HTML
<?php
if (strstr($_SERVER["HTTP_USER_AGENT"], "MSIE")) {
?>
<h3>strstr retorna verdadeiro</h3>
<center><b>Você está usando o Internet Explorer</b></center>
<?php
} else {
?>
<h3>strstr retorna falso</h3>
<center><b>Você não está usando o Internet Explorer</b></center>
<?php
}
?>
Um exemplo de saída deste script poderia ser:
<h3>strstr retorna verdadeiro</h3> <center><b>Você está usando o Internet Explorer</b></center>
Ao invés de usar a declaração echo do PHP para imprimir a saída dos dados, nós saímos do modo do PHP e usamos o HTML normal. O importante à notar aqui é que a lógica do script continua intacta. Somente alguns blocos HTML será enviados de acordo com o que a declaração strstr() retornar, ou seja TRUE ou FALSE. Em outras palavras, se a palavra MSIE for encontrada ou não.
Tratando Formulários
Uma das características mais fortes do PHP é o jeito como ele trata formulários HTML. O conceito básico que é importante entender é que qualquer elemento de formulário em um formulário irá automaticamente ficar disponível para você usá-los em seus scripts PHP. Por favor leia a seção Variáveis externas do PHP para mais informações e exemplos de como usar formulários com PHP. Aqui vai um exemplo:
Exemplo #1 Um simples formulário HTML
<form action="acao.php" method="POST"> Seu nome <input type="text" name="nome" /> Sua idade: <input type="text" name="idade" /> <input type="submit"> </form>
Não há nada de especial neste formulário. É um formulário HTML comum sem nenhuma tag especial de qualquer tipo. Quando o usuário preencher este formulário e clicar no botão enviar, a página action.php é chamada. Neste arquivo nós teremos algo como este:
Exemplo #2 Imprimindo dados de nosso formulário
Oi <?php echo $_POST["nome"]; ?>.
Você tem <?php echo $_POST["idade"]; ?> anos.
Um exemplo de saída deste script seria:
Oi Thomas. Você tem 18 anos.
É óbvio o que este script faz. Não há nada de mais nele. As variáveis $_POST["nome"] e $_POST["idade"] são automaticamente criadas para você pelo PHP. Antigamente nós usávamos a auto-global $_SERVER, agora nós simplesmente usamos a auto-global $_POST que contém todos os dados vindos do POST. Se você usar o método GET então nossas informações residirão na auto-global $_GET. Você também pode usar a auto-global $_REQUEST se você não se importa com o tipo de dados que vêm do seu formulário. Esta auto-global contém uma mescla de GET, POST, COOKIE e FILE. Veja também a função import_request_variables().
Usando códigos antigos com a nova versão do PHP
Agora que o PHP cresceu e é uma linguagem de script popular, há recursos públicos que contém código que você pode reusar em seus próprios scripts. Os desenvolvedores do PHP tentaram largamente manter a compatibilidade, para que um script escrito em uma versão mais antiga do PHP (deva) rodar sem nenhuma alteração em uma versão mais nova do PHP. Na prática algumas alterações serão geralmente necessárias.
Duas das coisas mais importantes recentemente alteradas que afetam um código antigo é:
- O velho método que não está mais em uso, que é o de usar arrays $HTTP_*_VARS (que precisam ser indicados como sendo globais quando usados dentro de uma função ou método). A seguir nós abordaremos os arrays auto-globais no PHP » 4.1.0. Eles são: $_GET, $_POST, $_COOKIE, $_SERVER, $_ENV, $_REQUEST, e $_SESSION. Os antigos arrays $HTTP_*_VARS, como os $HTTP_POST_VARS, ainda existem até a versão do PHP 3.
- Variáveis externas não são mais registradas no escopo global por padrão. Em outras palavras, com o PHP » 4.2.0 a diretiva register_globals está desligada por padrão no arquivo php.ini. O método utilizado atualmente é o de acessar estes valores via arrays auto-globais como mencionado acima. Scripts antigos, livros, e tutoriais podem estar utilizando a diretiva ligada. Se ela estiver ligada, por exemplo, você poderá utilizar a variável $id da URL http://www.exemplo.com/pagina.php?id=42. Se a diretiva estiver desligada, você usará $_GET['id'].
O que mais?
Com o que você sabe agora você deverá estar apto à entender a maioria do manual e também os vários exemplos de scripts disponíveis no arquivo de exemplos. Você também pode encontrar outros exemplos nos sites do php.net e nos links da seção: » http://www.php.net/links.php.
Instalação e Configuração
Considerações Gerais sobre Instalação
Antes de começar a instalar o PHP, primeiro você deve saber o que você deseja fazer com ele. Existem três principais formas de se usar o PHP, como descrito na seção O que o PHP pode fazer? do manual:
- Websites e aplicações web (script do lado do servidor)
- Scripts para linha de comando
- Aplicações de Desktop (GUI)
Para a primeira forma, e mais comum, você precisa de três coisas: o prório PHP, um servidor web e um cliente (browser) web. Você provavelmente já tem um browser, e dependendo da configuração do seu sistema operacional, vocêo pode tambem ter um servidor web (Ex.: Apache no Linux e MacOS X; IIS no Windows). Você também pode alugar um host em uma companhia qualquer. Dessa maneira, você não precisa configurar nada por conta própria, apenas escrever os seus scripts PHP, enviar (upload) para o servidor que você alugou, e ver os resultados no seu browser.
No caso de você instalar o servidor e o PHP por contra própria, você tem duas escolhas para o método de conexão do PHP com o servidor. Para muitos servidores o PHP tem uma interface direta de módulo (também chamada de SAPI). Entre esses servidores estão Apache, Microsoft Internet Information Server, Netscape e iPlanet. Muitos outros servidores têm suporte para ISAPI, a interface de módulo da Microsoft (OmniHTTPd por exemplo). Se o PHP não tiver suporte de módulo para o seu servidor web, você também pode usá-lo como processador CGI ou FastCGI. Isso significar configurar seu servidor para usar executáveis CGI do PHP para processar todas as requisições à arquivos PHP no servidor.
Se você também estiver interessado em usar o PHP para criar scripts em linha de comandos (Ex.: criar scripts que geram imagens enquanto estão offline, ou processar arquivos de texto dependendo de alguns argumentos que você passar ao script), você pode precisar do executável de linha de comando. Para mais informações, leia a seção sobre criando aplicações de linha de comando com o PHP. Nesse caso, vocêo não precisa de servidor nem de um browser.
Com o PHP, você também pode criar aplicações para desktop com interface gráfica (GUI) usando a extenção PHP-GTK. Isso é uma abordagem completamente diferente da criação de páginas web, já que a saída não é em HTML, mas o manuseio de janelas e objetos dentro delas. Para mais informações sobre PHP-GTK, por favor » visite o site dedicado à essa extensão. PHP-GTK não é inclusa na distribuição oficial do PHP.
Por enquanto, essa seção trata da instalação do PHP em servidores web no Unix e Windows como módulos dos servidores e executáveis CGI. Você também pode encontrar inforamação sobre executáveis de linha de comando nas seções seguintes.
O código fonte do PHP e distribuições binárias para Windows podem ser encontradas em » http://www.php.net/downloads.php. Nós recomentandos que você escolha um » mirror mais próximo de vocêo para baixar as distribuições.
Instalação em sistemas Unix
Índice
- Apache 1.3.x em sistemas Unix
- Apache 2.0 em sistemas Unix
- Lighttpd 1.4 on Unix systems
- Caudium
- Notas relacionadas à fhttpd
- Sun, iPlanet e servidores Netscape no Solaris da Sun
- CGI e instalações de linha de comando
- Notas expecificas da instalação em HP-UX
- Notas de instalação para o OpenBSD
- Dicas de instalação específicas para o Solaris
- Notas de Instalação para o Debian GNU/Linux
Essa seção é um guia geral para configuração e instalação do PHP em sistemas Unix. Verifique se existe uma seção específica para usa plataforma ou servidor web antes de começar o processo.
Como nosso manual destaca na seção Considerações Gerais sobre Instalação, nós estamos lidando principalmente com configurações web do PHP nessa seção, embora cobriremos instalação do PHP para uso em linha de comando também.
Existem várias maneiras de instalar o PHP para a plataforma Unix, ou com um processo de compilar e configurar, ou atráves de vários métodos pré-empacotados. Essa documentação é focada principalmente no processo de compilação e configuração do PHP. Muitos sistemas baseados no Unix tem alguma forma de sistema de instalação de pacotes. Isso pode ajudar na instalação de uma configuração padrão, mas se você precisar ter uma série de características diferentes (como um servidor seguro, ou um driver de banco de dados diferente), você pode precisar montar o PHP e/ou servidor web. Se você não estiver familiarizado com o processo de montar e compilar seu próprio software, vale a pena checar se alguém já montou um pacote do PHP com as características que você precisa.
Pré-requisitos de software e de conhecimento para compilar:
- Conhecimento básico de Unix (ser capaz de operar o "make" e um compilador C)
- Um compilador ANSI C
- flex: Versão 2.5.4
- bison: Versão 1.28 (preferida), 1.35, ou 1.75
- Um servidor web
- Qualquer componentes específicos para os módulos (como gd, bibliotecas pdf, etc.)
O processo inicial de configuração de instalação do PHP é controlado pelo uso de opções de linha de comando do script configure. Você pode pegar a lista de todas as opções disponíveis junto com uma pequena explicação executando o comando ./configure --help. Nosso manual documenta as diferentes opções separadamente. Você encontrará as opções principais no apêndice, enquanto as opções específicas das diferentes extensões são descritas nas páginas de referência.
Quando o PHP é configurado, você está pronto para montá-lo como módulo e/ou executável. O comando make deve tomar conta disso. Se ele falhar e você não conseguir descobrir a razão, veja a Seção de Problemas.
Apache 1.3.x em sistemas Unix
Essa seção contem notas e dicas específicas para a instação do Apache e do PHP em plataformas Unix. Também temos instruções e notas para o Apache 2 em uma página separada.
Você pode selecionar argumentos para adicionar ao configure na linha 10 abaixo através da Lista completa de opções do configure e das opções específicas das extensões em seus respectivos lugares no manual. Os números de versões foram omitidos aqui, para assegurar que as instruções não estejam incorretas. Você deverá trocar o 'xxx' aqui com os valores corretos dos seus arquivos.
Exemplo #1 Instruções de Instalação (Apache Versão de Módulo Compartilhado) para PHP
1. gunzip apache_xxx.tar.gz
2. tar -xvf apache_xxx.tar
3. gunzip php-xxx.tar.gz
4. tar -xvf php-xxx.tar
5. cd apache_xxx
6. ./configure --prefix=/www --enable-module=so
7. make
8. make install
9. cd ../php-xxx
10. Agora, configure o seu PHP. É aqui que você personaliza seu PHP
com várias opções, como quais extensões serão habilitadas. Execute o
comando ./configure --help para uma lista das opções disponíveis. No nosso exemplo
nós faremos uma simples configuração com Apache 1 e suporte ao MySQL. Seu caminho
para o arquivo apxs pode ser diferente do exemplo.
./configure --with-mysql --with-apxs=/www/bin/apxs
11. make
12. make install
Se você decidir mudar as opções de seu configure depois da instalação
você precisará somente repetir os últimos 3 passos. Você somente precisará
reiniciar o Apache para o novo módulo funcionar. Não será necessário recompilar
o Apache.
Note que, por padrão, 'make install' também instalará PEAR, além
de várias ferramentas do PHP como phpize, instalar o CLI do PHP e mais.
13. Configurando seu arquivo php.ini:
cp php.ini-dist /usr/local/lib/php.ini
Você pode editar o seu arquivo .ini para configurar as opções do PHP. Se
você preferir que este arquivo fique em outro lugar, use a opção
--with-config-file-path=/caminho no passo 10.
Se ao invés de escolher o arquivo php.ini-dist, você escolher o arquivo php.ini-recommended,
leia a lista de mudanças dentro do mesmo, uma vez que elas afetam a maneira como o PHP se comporta.
14. Edite o seu arquivo httpd.conf para carregar o módulo do PHP. O caminho no lado direito
do comando LoadModule deve apontar para para o caminho do módulo PHP no seu sistema.
O comando make install acima já deve ter adicionado estas linhas, mas tenha certeza
de que as linhas abaixo foram adicionadas ao arquivo.
Para o PHP 4:
LoadModule php4_module libexec/libphp4.so
Para o PHP 5:
LoadModule php5_module libexec/libphp5.so
15. Em seguida, na seção AddModule do arquivo httpd.conf, em algum lugar
abaixo de ClearModuleList, adicione isto:
Para o PHP 4:
AddModule mod_php4.c
Para o PHP 5:
AddModule mod_php5.c
16. Diga ao Apache para avaliar certas extensões como PHP. Por exemplo,
vamos fazer o Apache interpretar a extensão .php como um script PHP. Você poderia
ter qualquer extensão(ões) avaliadas como PHP simplesmente adicionando-as, com
cada uma separada por um espaço. Vamos adicionar .phtml para demonstrar.
AddType application/x-httpd-php .php .phtml
Também é comum configurar a extensão .phps para mostrar o código-fonte
do script PHP com highlight, isso pode ser feito com:
AddType application/x-httpd-php-source .phps
17. Use seu procedimento normal para iniciar o servidor Apache. (Você deve
parar e reiniciar o servidor, não somente fazer um reinício enviando
um sinal HUP ou USR1.)
Outra maneira é instalar o PHP como um objeto estático:
Exemplo #2 Instruções de Instalação (Instalação como módulo estático do Apache) para o PHP
1. gunzip -c apache_1.3.x.tar.gz | tar xf -
2. cd apache_1.3.x
3. ./configure
4. cd ..
5. gunzip -c php-5.x.y.tar.gz | tar xf -
6. cd php-5.x.y
7. ./configure --with-mysql --with-apache=../apache_1.3.x
8. make
9. make install
10. cd ../apache_1.3.x
11. ./configure --prefix=/www --activate-module=src/modules/php5/libphp5.a
(A linha acima está correta! Sim, sabemos que libphp4.a não existe nesse
estágio. E nem deveria. Ele será criado.)
12. make
(você deve agora ter um binário httpd que você pode copiar para o diretório bin do Apache. Se
for sua primeira instalação então você precisa executar "make install" também)
13. cd ../php-5.x.y
14. cp php.ini-dist /usr/local/lib/php.ini
15. Você pode editar o arquivo /usr/local/lib/php.ini para editar as opçso do PHP.
Edite o seu arquivo httpd.conf ou srm.conf e adicione:
AddType application/x-httpd-php .php
Nota:
Substitua php-5 por php-4 e php5 por php4 no PHP 4.
Dependendo da sua instalação do Apache e das variações Unix, existem inúmeras maneiras possíveis de parar e reiniciar o servidor. Abaixo estão algumas linhas típicas usadas para reiniciar e o servidor, para instalações de versões de apache/unix. Você deve trocar /caminho/para/ pelo caminho destas aplicações nos seus sistemas.
Exemplo #3 Exemplo de comandos para reinicialização do Servidor Apache
1. Várias distribuições Linux e variantes do SysV: /etc/rc.d/init.d/httpd restart 2. Usando os scripts apachectl: /path/to/apachectl stop /path/to/apachectl start 3. httpdctl and httpsdctl (Usando OpenSSL), igual ao apachectl: /path/to/httpsdctl stop /path/to/httpsdctl start 4. Usando mod_ssl, ou outro servidor SSL, você pode querer iniciar ou reiniciar manualmente: /path/to/apachectl stop /path/to/apachectl startssl
As localizações dos binários apachectl e http(s)dctl geralmente variam. Se o seu sistema tem os comandos locate ou whereis ou which, estem podem lhe ajudar a encontrar os programas de controle do servidor.
Exemplos diferentes de compilação do PHP para apache estão a seguir:
./configure --with-apxs --with-pgsql
Isso criará uma biblioteca compartilhada libphp5.so (ou libphp4.so no PHP 4) que é carregada pelo Apache ao adicionar uma linha LoadModule no arquivo httpd.conf do Apache. O suporte ao PostgreSQL é embutido nessa biblioteca.
./configure --with-apxs --with-pgsql=shared
Isto irá criar uma biblioteca compartilhada libphp4.so para o Apache, mas isto também criará uma biblioteca compartilhada pgsql.so que é carregada com o PHP tanto ao usar a diretiva de extensão no arquivo php.ini ou então carregando ela explícitamente no script usando a função dl().
./configure --with-apache=/path/to/apache_source --with-pgsql
Isto irá criar uma biblioteca libmodphp5.a, o arquivo mod_php5.c e vários arquivos dependentes e copiará eles para o diretório src/modules/php5 na árvore de diretório do código fonte do Apache. Então você compilará o Apache usando a opção --activate-module=src/modules/php5/libphp5.a e o sistema de compilação do Apache irá criar o arquivo libphp5.a e fará um link estático dentro do binário httpd (substitua php5 por php4 no PHP 4). O suporte ao PostgreSQL estará incluído diretamente neste binário httpd, então o resultado final aqui será um único arquivo binário httpd que incluirá tudo do Apache e tudo do PHP.
./configure --with-apache=/path/to/apache_source --with-pgsql=shared
Mesmo que o anterior, exceto em vez de incluir o suporte ao PostgreSQL diretamente no binário httpd você terá uma biblioteca compartilhada pgsql.so que você poderá carregar com o PHP tanto do arquivo php.ini ou diretamente usando a função dl().
Quanto estiver decidindo compilar o PHP com maneiras diferentes, você deverá considerar as vantages e disvantagens de cada método. Complilando como uma biblioteca compartilhada significará que você poderá compilar o apache separadamente, e não terá que recompilar tudo quando quiser adicionar ou mudar o seu PHP. compilando o PHP dentro do apache (método estático) significará que o PHP irá carregar e rodar rapidamente. Para maiores informações, veja a página web do Apache que fala sobre » Suporte a Objetos Dinâmicos Compartilhados.
Nota:
O arquivo httpd.conf padrão do Apache atualmente já contém uma seção que se parece com isso:
A menos que você mude isto para "Group nogroup" ou algo assim ("Group daemon" é também muito comum) o PHP não estará apto a abrir arquivos.User nobody Group "#-1"
Nota:
Tenha certeza de especificar a versão instalada do apxs quando usar a opção --with-apxs=/caminho/para/apxs . Você NÂO deverá usar a versão do apxs que está nos fontes do apache e sim a que está atualmente instalada no seu sistema.
Apache 2.0 em sistemas Unix
Essa seção contém notas e dicas específicas para a instalação do Apache 2.0 com o PHP em sistemas Unix.
Nós não recomendamos a utilização de um threaded MPM em produção com o Apache2. Use ao invés prefork MPM, ou use Apache1. para informações sobre o motivo, leia este faq sobre usando Apache2 com um threaded MPM
Recomendamos a » Documentação do Apache para obter um entendimento básico do servidor Apache 2.0.
Nota: Notas de compatibilidade do PHP e Apache 2.0.x
As seguintes versões do PHP são compatíveis com a versão mais recente do Apache 2.0.x:
Essas versões do PHP são compatíveis com Apache 2.0.40 ou superior.
- PHP 4.3.0 ou superior, disponível em » http://www.php.net/downloads.php.
- A última versão estável de desenvolvimento. Pegue o código fonte » http://snaps.php.net/php5-latest.tar.gz ou baixe os binários para o Windows » http://snaps.php.net/win32/php5-win32-latest.zip.
- Uma versão pre-release disponível para download em » http://qa.php.net/.
- Você sempre tem a opção de obter o PHP através da conta » anônima do CVS.
Suporte a SAPI do Apache 2.0 começou no PHP 4.2.0. PHP 4.2.3 funciona com Apache 2.0.39, não use qualquer outra versão de Apache com PHP 4.2.3. No entando, a configuração recomendada é usar o 4.3.0 ou superior com a versão mais recente do Apache2.
Todas as versões mencionadas do PHP ainda funcionarão com Apache 1.3.x.
Baixe a versão mais recente do » Apache 2.0 e uma versão adequada do PHP dos lugares mencionados acima. Esse guia rápido cobre apenas o básico para para começar a usar o Apache 2.0 e o PHP. Para mais informação, leia a » Documentação do Apache Os número de versão foram omitidos para assegurar que as instruções não estejam incorretas. Você precisará substituir o 'NN' com os valores corretos dos seus arquivos.
Exemplo #1 Instruções de Instalação (Versão de Módulo Compartilhado do Apache 2)
1. gzip -d httpd-2_0_NN.tar.gz
2. tar xvf httpd-2_0_NN.tar
3. gunzip php-NN.tar.gz
4. tar -xvf php-NN.tar
5. cd httpd-2_0_NN
6. ./configure --enable-so
7. make
8. make install
Agora você tem o Apache 2.0.NN disponível no diretório /usr/local/apache2,
configurado com suporte a módulo compartilhado e o prefork MPM padrão.
Para testar a instalação use o procedimento normal para iniciar
o servidor Apache, ex.:
/usr/local/apache2/bin/apachectl start
e pare o servidor para ir para a configuração do PHP:
/usr/local/apache2/bin/apachectl stop.
9. cd ../php-NN
10. Agora, configure o seu PHP. É aqui que você personaliza seu PHP
com várias opções, como quais extensões serão habilitadas. Execute o
comando ./configure --help para uma lista das opções disponíveis. No nosso exemplo
nós faremos uma simples configuração com Apache 2 e suporte ao MySQL. Seu caminho
para o arquivo apxs pode ser diferente do exemplo. De fato, o binário pode até ser
chamado de apxs2 no seu sistema.
./configure --with-apxs2=/usr/local/apache2/bin/apxs --with-mysql
11. make
12. make install
Se você decidir mudar as opções de seu configure depois da instalação
você precisará somente repetir os últimos 3 passos. Você somente precisará
reiniciar o Apache para o novo módulo funcionar. Não será necessário recompilar
o Apache.
Note que, por padrão, 'make install' também instalará PEAR, além
de várias ferramentas do PHP como phpize, instalar o CLI do PHP e mais.
13. Configurando seu arquivo php.ini:
cp php.ini-dist /usr/local/lib/php.ini
Você pode editar o seu arquivo .ini para configurar as opções do PHP. Se
você preferir que este arquivo fique em outro lugar, use a opção
--with-config-file-path=/caminho no passo 10.
Se ao invés de escolher o arquivo php.ini-dist, você escolher o arquivo php.ini-recommended,
leia a lista de mudanças dentro do mesmo, uma vez que elas afetam a maneira como o PHP se comporta.
14. Edite o seu arquivo httpd.conf para carregar o módulo do PHP. O caminho no lado direito
do comando LoadModule deve apontar para para o caminho do módulo PHP no seu sistema.
O comando make install acima já deve ter adicionado estas linhas, mas tenha certeza
de que as linhas abaixo foram adicionadas ao arquivo.
Para o PHP 4:
LoadModule php4_module libexec/libphp4.so
Para o PHP 5:
LoadModule php5_module libexec/libphp5.so
15. Diga ao Apache para avaliar certas extensões como PHP. Por exemplo,
vamos fazer o Apache interpretar a extensão .php como um script PHP. Você poderia
ter qualquer extensão(ões) avaliadas como PHP simplesmente adicionando-as, com
cada uma separada por um espaço. Vamos adicionar .phtml para demonstrar.
AddType application/x-httpd-php .php .phtml
Também é comum configurar a extensão .phps para mostrar o código-fonte
do script PHP com highlight, isso pode ser feito com:
AddType application/x-httpd-php-source .phps
16. Use seu procedimento normal para iniciar o servidor Apache ex.:
/usr/local/apache2/bin/apachectl start
Seguindo os passos acima você terá rodando o Apache 2.0 com suporte para o PHP como um módulo SAPI. Claro que existem muitas outras opções de configuração disponível para ambos, Apache e o PHP. Para mais informações use o comando ./configure --help na árvore de arquivos fontes correspondente. Caso você desejar compilar uma versão multithreaded do Apache 2.0, você deve sobrescrever o Módulo-MPM padrão prefork ou com o módulo worker ou com o perchild. Para fazer isso, acrescente ao comando configure no passo 6 acima a opção --with-mpm=worker ou --with-mpm=perchild . Tome cuidado com as consequências e entenda o que está fazendo. Para mais informações, leia a documentação do Apache sobre os » Módulos-MPM.
Nota:
Se você quiser usar negociação de conteúdo, leia o FAQ relacionado à MultiViews.
Nota:
Para compilar uma versão multithreaded do Apache, seu sistema deve suportar threads. Isso também implica compilar o PHP com o Zend Thread Safety (ZTS) experimental. Portanto, nem todas as extensões podem estar disponíveis. A configuração recomendada para compilar o Apache é com o Módulo-MPM prefork padrão.
Lighttpd 1.4 on Unix systems
This section contains notes and hints specific to Lighttpd 1.4 installs of PHP on Unix systems.
Please use the » Lighttpd trac to learn how to install Lighttpd properly before continuing.
Fastcgi is the preferred SAPI to connect PHP and Lighttpd. Fastcgi is automagically enabled in php-cgi in PHP 5.3, but for older versions configure PHP with --enable-fastcgi. To confirm that PHP has fastcgi enabled, php -v should contain PHP 5.2.5 (cgi-fcgi) Before PHP 5.2.3, fastcgi was enabled on the php binary (there was no php-cgi).
Letting Lighttpd spawn php processes
To configure Lighttpd to connect to php and spawn fastcgi processes, edit lighttpd.conf. Sockets are preferred to connect to fastcgi processes on the local system.
Exemplo #1 Partial lighttpd.conf
server.modules += ( "mod_fastcgi" )
fastcgi.server = ( ".php" =>
((
"socket" => "/tmp/php.socket",
"bin-path" => "/usr/local/bin/php-cgi",
"bin-environment" => (
"PHP_FCGI_CHILDREN" => "16",
"PHP_FCGI_MAX_REQUESTS" => "10000"
),
"min-procs" => 1,
"max-procs" => 1,
"idle-timeout" => 20
))
)
The bin-path directive allows lighttpd to spawn fastcgi processes dynamically. PHP will spawn children according to the PHP_FCGI_CHILDREN environment variable. The "bin-environment" directive sets the environment for the spawned processes. PHP will kill a child process after the number of requests specified by PHP_FCGI_MAX_REQUESTS is reached. The directives "min-procs" and "max-procs" should generally be avoided with PHP. PHP manages its own children and opcode caches like APC will only share among children managed by PHP. If "min-procs" is set to something greater than 1, the total number of php responders will be multiplied PHP_FCGI_CHILDREN (2 min-procs * 16 children gives 32 responders).
Spawning with spawn-fcgi
Lighttpd provides a program called spawn-fcgi to ease the process of spawning fastcgi processes easier.
Spawning php-cgi
It is possible to spawn processes without spawn-fcgi, though a bit of heavy-lifting is required. Setting the PHP_FCGI_CHILDREN environment var controls how many children PHP will spawn to handle incoming requests. Setting PHP_FCGI_MAX_REQUESTS will determine how long (in requests) each child will live. Here's a simple bash script to help spawn php responders.
Exemplo #2 Spawning FastCGI Responders
#!/bin/sh
# Location of the php-cgi binary
PHP=/usr/local/bin/php-cgi
# PID File location
PHP_PID=/tmp/php.pid
# Binding to an address
#FCGI_BIND_ADDRESS=10.0.1.1:10000
# Binding to a domain socket
FCGI_BIND_ADDRESS=/tmp/php.sock
PHP_FCGI_CHILDREN=16
PHP_FCGI_MAX_REQUESTS=10000
env -i PHP_FCGI_CHILDREN=$PHP_FCGI_CHILDREN \
PHP_FCGI_MAX_REQUESTS=$PHP_FCGI_MAX_REQUESTS \
$PHP -b $FCGI_BIND_ADDRESS &
echo $! > "$PHP_PID"
Connecting to remote FCGI instances
Fastcgi instances can be spawned on multiple remote machines in order to scale applications.
Exemplo #3 Connecting to remote php-fastcgi instances
fastcgi.server = ( ".php" =>
(( "host" => "10.0.0.2", "port" => 1030 ),
( "host" => "10.0.0.3", "port" => 1030 ))
)
Caudium
O PHP pode ser compilado como um módulo do Pike para o » servidor web Caudium. Siga as instruções abaixo para instalar o PHP 4 para o Caudium.
Exemplo #1 Instruções de Instalação para o Caudium
1. Verifique que você tem o Caudium instalado antes de tentar
instalar o PHP 4. Para que o PHP funcione corretamente, você precisará do Pike
7.0.268 ou superior. Nesse exemplo, presumiremos que
o Caudium foi instalado no diretório /opt/caudium/server/.
2. Mude para o diretório php-x.y.z (onde x.y.z é o número da versão).
3. ./configure --with-caudium=/opt/caudium/server
4. make
5. make install
6. Reinicie o Caudium se ele estiver sendo executado.
7. Entre na interface gráfica de configuração e vá no
servidor virtual (virtual server) onde você adicionará suporte ao PHP 4.
8. Clique em Adicionar Módulo (Add Module) e localize e depois adicione o módulo PHP 4 Script Support.
9. Se a documentação disser que o 'O interpretador do PHP não está
disponível', verifique que você reiniciou o servidor. Se você
verificou, procure em /opt/caudium/logs/debug/default.1 por algum erro relacionado à
<filename>PHP4.so</filename>. Também certifique-se que o arquivo
<filename>caudium/server/lib/[pike-version]/PHP4.so</filename>
está presente.
10. Configure o módulo do PHP se necessário.
Você pode, é claro, compilar o módulo do Caudium com suporte para as várias extensões disponíveis no PHP 4. Veja as páginas de referência por opções específicas para a extensão que você deseja.
Nota:
Quando compilar o PHP 4 com suporte ao MySQL, você deve verificar que o código normal de cliente MySQL é usado. Caso contrário, pode haver conflitos se seu Pike já tiver suporte ao MySQL. Você faz isso especificando um diretório de instalação do MySQL com a opção --with-mysql .
Notas relacionadas à fhttpd
Para compilar o PHP como módulo fhttpd, responda "yes" para "Build as an fhttpd module?" (a opção do script configure --with-fhttpd=DIR deve ser usada) e especifique o diretório base dos fontes do fhttpd. O diretório padrão é /usr/local/src/fhttpd. Se você estiver rodando fhttpd, compilar o PHP como um módulo lhe dará melhor performance, mais controle e capacidade de execução remota.
Nota: Suporte para fhttpd não está mais disponível a partir do PHP 4.3.0.
Sun, iPlanet e servidores Netscape no Solaris da Sun
Essa seção contem notas e dicas específicas para instação do PHP nos servidores un Java System Web Server, Sun ONE Web Server, iPlanet e Netscape no Solaris.
A partir do PHP 4.3.3, você pode usar scripts PHP com o módulo NSAPI para gerar listagem de diretórios e páginas de erro personalizadas. Funções adicionais para compatibilidade com o Apache também estão disponíveis. Para suporte nos webservers atuais, leia a nota sobre sub-requisições.
Você pode achar mais informações sobre como instalar o PHP para o Servidor Netscape Enterprise (NES) aqui: » http://benoit.noss.free.fr/php/install-php4.html
Para compilar o PHP com servidores web Sun JSWS/Sun ONE WS/iPlanet/Netscape, entre o diretório apropriado de instalação para a opção --with-nsapi=[DIR] O diretório padrão é, normalmente /opt/netscape/suitespot/. Por favor, leia também /php-xxx-version/sapi/nsapi/nsapi-readme.txt.
-
Instale os seguintes pacotes de » http://www.sunfreeware.com/ ou outro site de download:
- autoconf-2.13
- automake-1.4
- bison-1_25-sol26-sparc-local
- flex-2_5_4a-sol26-sparc-local
- gcc-2_95_2-sol26-sparc-local
- gzip-1.2.4-sol26-sparc-local
- m4-1_4-sol26-sparc-local
- make-3_76_1-sol26-sparc-local
- mysql-3.23.24-beta (se você quiser suporte ao MySQL)
- perl-5_005_03-sol26-sparc-local
- tar-1.13 (GNU tar)
-
Assegure-se que seu PATH inclue os diretórios apropriados
PATH=.:/usr/local/bin:/usr/sbin:/usr/bin:/usr/ccs/bin
E está disponível para o seu sistema
export PATH. -
gunzip php-x.x.x.tar.gz(se você tiver uma distribuição .gz, caso contrário vá para o passo 4). -
tar xvf php-x.x.x.tar -
Mude para o diretório recém-criado:
cd ../php-x.x.x -
Para o passo seguinte, assegure-se de que /opt/netscape/suitespot/ é onde o seu servidor Netscape está instalado. Caso contrário, mude o comando abaixo para o caminho correto e execute:
./configure --with-mysql=/usr/local/mysql \ --with-nsapi=/opt/netscape/suitespot/ \ --enable-libgcc
- Execute make seguido de make install.
Depois de fazer a instalação básica e ler o arquivo readme apropriado, você pode precisar executar alguns passos extras de configuração.
Instruções de Configuração para o Sun/iPlanet/Netscape
Primeiramente, você pode preciasr adicionar alguns caminhos para a váriavel de ambiente LD_LIBRARY_PATH para que o servidor ache as bibliotecas compartilhadas. A melhor maneira de fazer isso é no script de inicialização do ser servidor web. Esse script normalmente está localizado em: /caminho/para/servidor/https-nome_do_servidor/start. Você pode precisar também de editar os arquivos de configuração que estão localizados em: /caminho/para/servidor/https-nome_do_servidor/config/.
-
Adicione a seguinte linha no arquivo mime.types (você pode fazer isso pelo servidor de administração):
type=magnus-internal/x-httpd-php exts=php
-
Edite o arquivo magnus.conf (para servidores >= 6) ou o arquivo obj.conf (para servidores < 6) e adicione a seguinte biblioteca compartilhada que pode variar dependendo do seu sistema, ela se parecererá com /opt/netscape/suitespot/bin/libphp4.so. Você deve colocar as seguintes linhas após mime types init.
(PHP >= 4.3.3) O parâmetro php_ini é opcional mas com ele você pode colocar seu arquivo php.ini no diretório config do seu servidor web.Init fn="load-modules" funcs="php4_init,php4_execute,php4_auth_trans" shlib="/opt/netscape/suitespot/bin/libphp4.so" Init fn="php4_init" LateInit="yes" errorString="Failed to initialize PHP!" [php_ini="/path/to/php.ini"]
-
Configure o objeto padrão no arquivo obj.conf (para classes de servidor virtuais [versão 6.0+] no arquivo vserver.obj.conf):
(PHP >= 4.3.3) Como parâmetros adicionais, você pode acrescentar valores especiais do php.ini, por exemplo, você pode editar um docroot="/path/to/docroot" específico para o contexto php4_execute chamado. Para valores booleanos, use 0/1 como valor, não "On","Off",... (isso não funcionará corretamente) ,ex.: zlib.output_compression=1 ao invés de zlib.output_compression="On"<Object name="default"> . . . .#NOTA Essa linha deve acontecer após todos as linhas 'ObjectType' e antes de todas as linas 'AddLog' Service fn="php4_execute" type="magnus-internal/x-httpd-php" [inikey=value inikey=value ...] . . </Object>
-
Isso só é necessários se você quiser configurar um diretório que apenas consiste de scripts PHP (assim como um diretório cgi-bin):
Depois que você pode configurar um diretório no servidor de Administração e atribuir a ele o estilo x-httpd-php. Todos os arquivo no diretório serão executados como PHP. Isso é bom para esconder uso do PHP renomeando os arquivos para .html.<Object name="x-httpd-php"> ObjectType fn="force-type" type="magnus-internal/x-httpd-php" Service fn=php4_execute [inikey=value inikey=value ...] </Object>
-
Configuração de autenticação: autenticação do PHP não pode ser usada com qualquer outra autenticação. TODA AUTENTICAÇÃO E PASSADA PARA O SEU SCRIPT PHP. Para configurar autenticação via PHP para o servidor todo, adicione a seguinte linha para o seu objeto padrão:
<Object name="default"> AuthTrans fn=php4_auth_trans . . . </Object>
-
Para usar autenticação via PHP em apenas um diretório, adicione o seguinte:
<Object ppath="d:\path\to\authenticated\dir\*"> AuthTrans fn=php4_auth_trans </Object>
Nota:
O tamanho da pilha que o PHP usa depende da configuração do servidor web. Se você tiver problemas com scripts PHP muito grandes, é recomendado aumentar o tamanho da pilha com o Admin Server (na seção "MAGNUS EDITOR").
Ambiente CGI e modificações recomendadas ao arquivo php.ini
É importante ter em mente quando escrever scripts PHP que os servidores web Sun JSWS/Sun ONE WS/iPlanet/Netscape são multithreaded. Por isso, todas as requisições estão rodando no mesmo espaço de processo (o espaço do servidor web em si) e esse espaço só tem um ambiente. Se você quiser usar variáveis CGI como PATH_INFO, HTTP_HOST etc, não é correto tentar fazer da maneira como PHP antigo faz, com a função getenv() ou de maneira similar (registrando globais ao ambiente, $_ENV). Você só pegaria o ambiente do servidor web sem qualquer variáveis CGI válidas.
Nota:
Por que existem variáveis CGI inválidas no ambiente?
Resposta: Isso é porque você iniciou o processo do servidor do admin server que roda o script de iniciação do mesmo, você queria iniciar como um script CGI (um script CGI dentro do admin server!). Isso é porque o ambiente do servidor web iniciado tem algumas variáveis CGI de ambiente nele. Você pode testar isso iniciando o servidor web sem ser do admin server. Use a linha de comando como usuário root e inicie-o manualmente - você verá que não exite nenhuma variável CGI de ambiente.
Simplesmente mudando seus scripts para pegar variáveis CGI é a maneira correta para o PHP 4.x usando o superglobal $_SERVER. Se você tiver scripts velhos que usam $HTTP_HOST, etc., você deve ligar register_globals no arquivo php.ini e mudar a ordem das variáveis também (importante: remova "E" de lá, porque voe não precisa do ambiente aqui):
variables_order = "GPCS" register_globals = On
Uso especial para páginas de erro e listagem de diretório auto-geradas (PHP >= 4.3.3)
Você pode usar o PHP para gerar as páginas de erro para "404 Not Found" ou similares. Adicione a seguinte linha no objeto do arquivo obj.conf para cada página de erro que você quiser sobrescrever:
Error fn="php4_execute" code=XXX script="/path/to/script.php" [inikey=value inikey=value...]
Outra possibilidade é criar uma listagem do diretório auto-gerada. Apenas crie um script PHP que mostra uma listagem do diretório e substitua o padrão correspondente Service line for type="magnus-internal/directory" no arquivo obj.conf pelo seguinte:
Service fn="php4_execute" type="magnus-internal/directory" script="/path/to/script.php" [inikey=value inikey=value...]
Nota sobre nsapi_virtual() e sub-requisições(PHP >= 4.3.3)
O módulo NSAPI agora suporta a função nsapi_virtual() (sinônima (alias): virtual()) para fazer sub-requisições no servidor web e inserir o resultado na página web. Essa função usa algumas funcionalidades não documentadas da biblioteca NSAPI. No Unix, o módulo procura automaticamente para as funções necessárias e as usa se estiverem disponíveis. Se não, nsapi_virtual() é desabilitada.
Nota:
Mas esteja avisado: Suporte para nsapi_virtual() é EXPERIMENTAL!!!
CGI e instalações de linha de comando
O padrão é compilar o PHP como um programa CGI. Isso cria um interpretador de linha de comando, que pode ser usado para processamento de CGI, ou para criação de scripts não relacionados com a web. Se você estiver executando um servidor web que suporta o PHP como módulo, você deve geralmente usar essa opção por razões de performance. No entanto, a versão CGI permite que usuários executem diferentes páginas com PHP usando diferentes ids de usuário.
Um servidor dispoto em modo CGI está aberto para várias vulnerabilidades possíveis. Por favor, leia nossa seção de segurança CGI para aprender em como se defender de tais ataques.
A partir do PHP 4.3.0, alguns acréscimos importentes aconteceram ao PHP. Um novo SAPI chamado CLI também existe e ele tem o mesmo nome que o binário CGI. O que é instalado no diretório {PREFIX}/bin/php depende das opções usadas com o comando configure e é descrito com mais detalhes na seção do manual chamada Usando o PHP da linha de comando. Para mais detalhes, por favor, leia essa seção do manual.
Testando
Se você compilou o PHP como um programa CGI, você pode testá-lo usando o comando make test. É sempre uma boa idéia testar os software que você compila. Dessa maneira, você pode achar um problema com o PHP na sua plataforma cedo, ao invés de ter de lidar com isso mais tarde.
Usando Variáveis
Algumas variáveis de ambientes fornecidas pelo servidor não são definidas na atual » especificação CGI/1.1. Apenas as seguintes variáveis são definidas lá: AUTH_TYPE, CONTENT_LENGTH, CONTENT_TYPE, GATEWAY_INTERFACE, PATH_INFO, PATH_TRANSLATED, QUERY_STRING, REMOTE_ADDR, REMOTE_HOST, REMOTE_IDENT, REMOTE_USER, REQUEST_METHOD, SCRIPT_NAME, SERVER_NAME, SERVER_PORT, SERVER_PROTOCOL, e SERVER_SOFTWARE. Todo o resto deve ser tratado como 'vendor extensions'.
Notas expecificas da instalação em HP-UX
Esta sessão contém notas e avisos especificos sobre a instalação do PHP em sistemas HP-UX.
Existem duas opções principais para instalar o PHP em sistemas HP-UX systems. Ou compila-lo, ou instalar um binário pré-compilado.
Pacotes oficiais pré-compilados podem ser encontrados aqui: » http://software.hp.com/
Até que esta sessão do manual seja rescrita, a documentação sobre compilar o PHP (e as extensões relacionadas) em sistemas HP-UX foi removida. Por enquanto, considere ler o seguinte recurso externo: » Construindo o Apache e o PHP em HP-UX 11.11
Notas de instalação para o OpenBSD
Essa seção contêm notas e dicas específicas para a instalação do PHP no » OpenBSD 3.6.
Usando Pacotes Binários
Usando pacotes binários para instalar o PHP no OpenBSD é o método recomendado e o mais simples. O pacote núcleo foi separado dos vários módulos, e cada um pode ser instalado e removido independentemente dos outros. Os arquivos necessários podem ser encontrados no CD do OpenBSD ou no FTP do site.
O pacote principal que você precisa instalar é o php4-core-4.3.8.tgz, que contem o engine básico (mais gettext e iconv). Depois, olhe os pacotes com módulos, como o php4-mysql-4.3.8.tgz ou php4-imap-4.3.8.tgz. Você precisa usar o comando phpxs para ativar e desativar esses módulos no seu arquivo php.ini.
Exemplo #1 Exemplo de instalação de pacote no OpenBSD
# pkg_add php4-core-4.3.8.tgz # /usr/local/sbin/phpxs -s # cp /usr/local/share/doc/php4/php.ini-recommended /var/www/conf/php.ini (adiciona o módulo mysql) # pkg_add php4-mysql-4.3.8.tgz # /usr/local/sbin/phpxs -a mysql (adiciona o módulo imap) # pkg_add php4-imap-4.3.8.tgz # /usr/local/sbin/phpxs -a imap (remove o módulo mysql para teste) # pkg_delete php4-mysql-4.3.8 # /usr/local/sbin/phpxs -r mysql (instala as bibliotecas do PEAR) # pkg_add php4-pear-4.3.8.tgz
Leia o manual de » packages(7) para mais informações sobre pacotes binários no OpenBSD.
Usando Ports
Você também pode compilar o PHP dos fontes usando a » árvore ports. No entanto, isso só é recomendado para usuários familiarizado com OpenBSD. O port do PHP 4 é dividido em dois sub-diretórios: núcleo e extensões. O diretório de extensões gera sub-pacotes para todos os módulos suportados pelo PHP. Se você achar que não quer criar alguns dos módulos, use o comando no_* FLAVOR. Por exemplo, se você quiser que o módulo imap seja ignorado, atribua à FLAVOR o valor no_imap.
Problemas Comuns
- A instalação padrão do Apache roda dentro de uma » prisão de chroot(2), que restrigirá os scripts PHP a acessar arquivos abaixo de /var/www. Você irá, portanto, precisar criar um diretório /var/www/tmp para que os arquivos de sessão do PHP sejam guardados, ou usar um backend alternativo para sessões. Além disso, sockets de bancos de dados devem ser colocados dentro da prisão ou escutar na interface localhost. Se você usar funções de rede, alguns arquivos do diretório /etc como /etc/resolv.conf e /etc/services precisarão ser movidos para /var/www/etc. O pacote PEAR do OpenBSD instala automaticamente nos diretórios corretos da prisão, então nenhuma modificação especial é necessária lá. Mais informação sobre o Apache do OpenBSD está disponível no » FAQ do OpenBSD.
- O pacote do OpenBSD 3.6 para a extensão » gd precisa do XFree86 instalado. Se você não deseja usar algumas das funcionalidaes de fontes que requerem o X11, instale o pacote php4-gd-4.3.8-no_x11.tgz.
Releases Antigas
Releases mais antigas do OpenBSD usam o sistema de FLAVORS para compilar um PHP estaticamente linkado. Já que é difícil gerar pacotes binários usando esse método, ele é depreciado agora. Você pode ainda usar as árvores de port velhas e estáveis se assim desejar, mas eles não tem suporte pelo time do OpenBSD. Se você tiver algum comentário sobre isso, o atual responsável pela manutenção do port é Anil Madhavapeddy (avsm at openbsd dot org).
Dicas de instalação específicas para o Solaris
Essa seção contêm notas e dicas específicas para a instalação do PHP em sistemas Solaris.
Software Necessário
Instalações do Solaris frequentemente não possuem compiladores C e suas ferramentas relacionadas. Leia esse FAQ para informação sobre porque usar versões GNU para algumas dessas ferramentas é necessário. Os softwares necessários são os seguintes:
- gcc (recomendado, outros compiladores C podem funcionar)
- make
- flex
- bison
- m4
- autoconf
- automake
- perl
- gzip
- tar
- GNU sed
Usando Pacotes
Você pode simplificar o processo de instalação no Solaris usando pkgadd para instalar a maioria dos componentes necessários.
Notas de Instalação para o Debian GNU/Linux
Essa seção contem notas e dicas específicas para a instalação do PHP no » Debian GNU/Linux.
Usando APT
Embora você possa apenas baixar o fonte do PHP e compilar por conta própria, usar o sistema de pacotes do Debian e o método mais simples e mais limpo de instalar o PHP. Se você não está familiarizado com compilar software no Linux, essa é maneira de se instalar.
A primeira decisão que você precisa fazer é se você quer instalar o Apache 1.3.x ou o Apache 2.x. Os pacotes correspondentes do PHP são, respectivamente, libapache-mod-php* e libapache2-mod-php*. Os passos abaixo usarão o Apache 1.3.x. Por favor, perceba que, até o fechamento desse documento, não há nenhum pacote oficial do Debian para o PHP 5. Então, o procedimento instalará o PHP4.
O PHP está disponível no Debian como CGI ou CLI também, pelos pacotes php4-cgi e php4-cli. Se você precisar deles, só terá que reproduzia os passos a seguir com o pacote desejado. Outro pacote especial que você pode querer instalar é o php4-pear. Ele contem um instalação PEAR mínima e a ferramenta de linha de comando pear.
Se você precisa de pacotes do PHP mais recentes que os do Debian stable ou se alguns módulos do PHP não se encontram no repositório oficial do Debian, talvez você deva procurar em » http://www.apt-get.org/. Um dos resultados encontrados deve ser » Dotdeb. Esse repositório não-oficial é mantido por » Guillaume Plessis e contem pacotes Debian das versões mais recentes do PHP 4 e 5. Para usá-lo, apenas adiciona as seguintes linhas ao seu arquivo /etc/apt/sources.lists e execute apt-get update :
Exemplo #1 Adicionando o repositório Dotdeb
deb http://packages.dotdeb.org stable all deb-src http://packages.dotdeb.org stable all
A última coisa a ser considade é se sua lista de pacotes está atualizada. Se você não atualizou recentemente, você precisa executar apt-get update antes de qualquer coisa. Dessa forma, você estará usando a versão estável mais recente dos pacotes do Apache e do PHP.
Agora que está tudo no lugar, você pode usar o seguinte exemplo para instalar o Apache e o PHP:
Exemplo #2 Exemplo de Instalação no Debian com o Apache 1.3
# apt-get install libapache-mod-php4
O APT instalará o módulo do PHP 4 para o Apache 1.3 automaticamente, e todas as suas dependências e então ativá-lo. Se o programa não pedir para reiniciar o Apache durante a instalação, você terá que fazê-lo manualmente:
Exemplo #3 Parando e iniciando o Apache depois que o PHP estiver instalado
# /etc/init.d/apache stop # /etc/init.d/apache start
Maior controle sobre a configuração
Na seção anterior, o PHP foi instalado apenas com os módulos principais. Isso pode não ser o que você quer e você discobrirá em breve que você precisa de mais módulos ativados, como MySQL, cURL, GD, etc.
Quando você compila o PHP do fonte, você precisa ativar os módulos através do comando configure. Com o APT, você só precisa instalar os pacotes adicionais. Todos eles tem o nome 'php4-*' (ou 'php5-*' se você instalou o PHP 5 de um repositório não-oficial).
Exemplo #4 Pegando a lista de pacotes adicionais do PHP
# dpkg -l 'php4-*'
Como você pode ver na saída do comando, existem vários módulos do PHP que você pode instalar (tirando os pacotes especiais php4-cgi, php4-cli ou php4-pear). Olhe com bastante atenção e escolha os que você precisar. Se você escolher um módulo e você não tiver as bibliotecas necessárias, o APT instalará todas as dependências automaticamente para você.
Se você escolher adicionar os módulos do MySQL, cURL e GD, o comando parecerá com esse:
Exemplo #5 Instalar o PHP com MySQL, cURL e GD
# apt-get install php4-mysql php4-curl php4-gd
O APT editará o seu arquivo php.ini (/etc/php4/apache/php.ini, /etc/php4/cgi/php.ini, etc) para dar suporte aos módulos novos.
Exemplo #6 Essas linhas ativam o MySQL, cURL e GD no PHP
extension=mysql.so extension=curl.so extension=gd.so
Você só terá que parar/iniciar o Apache como antes para ativar os módulos.
Problemas Comuns
-
Se você ver o código fonte do seus script ao invés do resultado que eles
deveriam produzir, o APT provavelmente não incluiu
/etc/apache/conf.d/php4 na configuração do
Apache. Verifique se a linha está presente no arquivo
/etc/apache/httpd.conf e então reinicie o Apache:
Exemplo #7 Essa linha ativa o PHP 4 no Apache
# Include /etc/apache/conf.d/
- Se você instalou um módulo adicional e se as funções desse módulo não estiverem disponíveis nos scripts, verifique que a linha apropriada está presente no seu arquivo php.ini, como visto antes. O APT pode falhar durante a instalação de módulos adicionais, devido a uma configuração confusa do debconf.
Instalação no Mac OS X
Índice
- Usando Pacotes
- Usando o pacote do PHP para Mac
- Compilando para o Mac OS X - Versão Servidor
- Compilando para o MacOS X - Versão Cliente
Essa seção contem notas e dicas específicas para instalação do PHP no Mac OS X. Existem duas versões do Mac OS X um pouquinho diferentes entre si, Cliente e Servidor, nosso manual trata da instalação do PHP em ambos os sistemas. Note que o PHP não está disponível para MacOS 9 e versões anteriores.
Usando Pacotes
Existem algumas versões do PHP empacotadas e pré-compiladas para o Mac OS X. Isso pode ajudar na instalação de uma configuração padrão, mas se você precisar ter algumas características diferentes (como um servidor seguro, ou um driver de banco de dados diferente), você pode precisar compilar o PHP e/ou seu servidor web por conta própria. Se você não estiver familiarizado com o procedimento de compilar seu próprio software, vale a pena checar se alguém já fez um pacote do PHP com as características que você precisa.
Os seguintes recursos oferecem pacotes de fácil instalação e binários pré-compilados para usar o PHP no Mac OS:
- MacPorts: » http://www.macports.org/
- Entropy: » http://www.entropy.ch/software/macosx/php/
- Fink: » http://www.finkproject.org/
Usando o pacote do PHP para Mac
PHP vem junto com Mac OS X desde a versão 10.0.0. Habilitar o PHP no servidor web padrão requer apenas descomentar algumas linhas no arquivo de configuração do Apache (httpd.conf) enquanto que a versão CGI e/ou CLI estão disponíveis automaticamente (facilmente acessíveis pelo programa Terminal).
Habilitar o PHP usando as instruções abaixo tem como objetivo configurar rapidamente um ambiente de desenvolvimento local. É altamente recomendado sempre atualizar o PHP para a versão mais nova. Como qualquer software ativo, novas versões são criadas para consertar bugs e adicionar funcionalidades e o PHP não é diferente. As seguintes instruções são direcionadas para iniciantes, os detalhes fornecidos permitem que uma configuração padrão funcionar. Todos os usuários são encorajados à compilar ou instalar uma versão nova do pacote.
O tipo de instalação padrão é usando mod_php, e habilitar o pacote mod_php no Mac OS X para o servidor Apache (o servidor web padrão, que é acessível via Preferências de Sistema) envolte os seguintes passos:
-
Localize e abra o arquivo de configuração do Apache. Normalmente, ele está
em: /etc/httpd/httpd.conf
Usar Finder ou Spotlight para encontrar
esse arquivo pode ser complicado, já que ele normalmente é privado e o dono
é o administrador (root).
Nota: Uma maneira de modificar o arquivo é usando um editor de texto baseado em Unix no Terminal, por exemplo nano, e, como o dono do arquivo é o root, nós usaremos o comando sudo para abrí-lo. Digite o seguinte comando na aplicação de Terminal (você precisará digitar a sua senha): sudo nano /etc/httpd/httpd.conf Comandos importantes do nano: ^w (busca), ^o (salvar), e ^x (sair) onde ^ representa a tecla Ctrl.
-
Com um editor de texto, descomente as linhas (removendo os #) que parecem com as linhas abaixo (essas duas linhas normalmente não estão juntas, localize ambas no arquivo):
Perceba a localização/caminho. Quando compilar o PHP no futuro, os arquivos acima devem ser substituidos ou comentados.# LoadModule php4_module libexec/httpd/libphp4.so # AddModule mod_php4.c
-
Certifique-se que as extensões desejadas serão avalidadas como códigos PHP (exemplos: .php .html e .inc)
Como a seguinte instrução já existe no httpd.conf (a partir do Mac Panther), uma vez que o PHP for habilitado, os arquivos .php serão automaticamente avaliados como códigos PHP.
<IfModule mod_php4.c> # If php is turned on, we respect .php and .phps files. AddType application/x-httpd-php .php AddType application/x-httpd-php-source .phps # Since most users will want index.php to work we # also automatically enable index.php <IfModule mod_dir.c> DirectoryIndex index.html index.php </IfModule> </IfModule> - Assegure-se de que a diretiva DirectoryIndex carrega o arquivo index desejado Isso também é configurável no arquivo httpd.conf. Tipicamente index.php e index.html são usados. Por padrão, index.php é habilitado porque também está na checagem mostrada abaixo. Modifique como desejar.
- Configure a localização do arquivo php.ini ou use a padrão Uma localização típica no Mac OS X é /usr/local/php/php.ini e uma chamada à phpinfo() revelerá essa informação. Se não for usado um arquivo php.ini, o PHP usará todos os valores padrão. Veja também o FAQ relacionado em encontrando php.ini.
- Localize ou configure DocumentRoot Esse é o diretório raiz para todos os arquivos do servidor. Arquivo nesse diretório serão servidos, então os arquivos PHP serão avaliados como PHP antes de terem seu resultado enviado para o servidor. Um caminho padrão para isso é /Library/WebServer/Documents mas isso pode ser modificado para qualquer um no arquivo httpd.conf. Além disso, o DocumentRoot para usuários individuais é /Users/yourusername/Sites
-
Crie um arquivo phpinfo()
A função phpinfo() mostrará informação sobre o PHP. Considere criar um arquivo no DocumentRoot com o seguinte código PHP:
<?php phpinfo(); ?> - Reinicie o Apache e carregue o arquivo PHP criado acima Para reiniciar, ou execute sudo apachectl graceful no shell ou stop/start na opção "Personal Web Server" em OS X System Preferences. Geralmente, carregar arquivos locais no browser pode ser feito usando uma URL assim: http://localhost/info.php ou se estiver usando o diretório DocumentRoot dentro de um diretório de usuário, seria assim: http://localhost/~yourusername/info.php
A versão CLI (ou CGI em versões mais antigas) tem nome php e provavelmente está em /usr/bin/php. Abra um terminal, leia a seção sobre linha de comando do manual desse binário. Uma chamada para phpinfo() também mostrará do PHP, e execute php -v para verificar a versão do PHP essa informação.
Compilando para o Mac OS X - Versão Servidor
Instalação para o Servidor Mac OS X
- Pegue a última distribuição do Apache e PHP.
-
Expanda o arquivo tar, e execute o programa configure do Apache dessa maneira (modifique para conformar com suas necessidades).
./configure --exec-prefix=/usr \ --localstatedir=/var \ --mandir=/usr/share/man \ --libexecdir=/System/Library/Apache/Modules \ --iconsdir=/System/Library/Apache/Icons \ --includedir=/System/Library/Frameworks/Apache.framework/Versions/1.3/Headers \ --enable-shared=max \ --enable-module=most \ --target=apache
-
Se você quiser que o compilador faça alguma otimização, você pode também querer adicionar essa linha:
setenv OPTIM=-O2
-
Depois, vá para o diretório onde os fontes do PHP 4 estão e configure ele.
Se você quiser qualquer outra extensão (MySQL, GD, etc.), adicione a opção a esse comando. Para a opção --with-apache , coloque o caminho do diretório dos fontes do Apache, por exemplo /src/apache_1.3.12../configure --prefix=/usr \ --sysconfdir=/etc \ --localstatedir=/var \ --mandir=/usr/share/man \ --with-xml \ --with-apache=/src/apache_1.3.12 - Digite make e make install. Isso irá adicionar um diretório para nos fontes do Apache em src/modules/php4.
-
Agora, reconfigure o Apache para montar junto com o PHP 4.
Você pode receber uma mensagem dizendo que libmodphp4.a está desatualizado. Se isso acontecer, vá para do diretório src/modules/php4 dentro do diretório dos fontes do Apache e execute o comando: ranlib libmodphp4.a. Depois volte para o diretório raiz dos fontes do Apache e execute o comando configure acima novamente. Isso fará a tabela de links ser atualizada. Execute make e make install novamente../configure --exec-prefix=/usr \ --localstatedir=/var \ --mandir=/usr/share/man \ --libexecdir=/System/Library/Apache/Modules \ --iconsdir=/System/Library/Apache/Icons \ --includedir=/System/Library/Frameworks/Apache.framework/Versions/1.3/Headers \ --enable-shared=max \ --enable-module=most \ --target=apache \ --activate-module=src/modules/php4/libphp4.a
-
Copie e renomei o arquivo php.ini-development que
está no diretório dos fontes do PHP para o
seu diretório bin:
cp php.ini-development /usr/local/bin/php.iniou (se você não tiver um diretório local)cp php.ini-development /usr/bin/php.ini.
Compilando para o MacOS X - Versão Cliente
As instruções seguintes ajudarão você a instalar o módulo PHP para o servidor web Apache incluso no MacOS X. Essa versão inclui suporte para os bancos de dados MySQL e PostgreSQL. Essas instruções foram providas por » Marc Liyanage.
Tenha cuidado quando for fazer isso, vocêo pode estragar seu servidor Apache!
Faça isso para instalar:
- Abra uma janela de terminal.
-
Digite
wget http://www.diax.ch/users/liyanage/software/macosx/libphp4.so.gz, e espere o download terminar. -
Digite
gunzip libphp4.so.gz. -
Digite
sudo apxs -i -a -n php4 libphp4.so -
Agora digite
sudo open -a TextEdit /etc/httpd/httpd.conf. TextEdit abrirá o arquivo de configuração do servidor web. Localize Locate essas duas linhas perto do final do arquivo: (Use o comando Localizar (Find))Remove os caracteres de comentários (#), e depois salve o arquivo e saia do TextEdit.#AddType application/x-httpd-php .php #AddType application/x-httpd-php-source .phps
-
Finalmente, digite
sudo apachectl gracefule reinicie o servidor web.
PHP deve estar funcionando. Você pode testar colocando um arquivo no seu diretório Sites chamado test.php. No arquivo, escreva essa linha: <?php phpinfo() ?>.
Agora abra 127.0.0.1/~your_username/test.php no seu navegador. Você deve ver uma tabela de status com informação sobre o módulo PHP.
Instalação em sistemas Windows
Índice
- Instalador do PHP para o Windows (PHP 5.1.0 e anterior)
- Instalador para Windows (PHP 5.2 ou posterior)
- Passos para Instalação Manual
- Microsoft IIS / PWS
- Microsoft IIS 5.1 and IIS 6.0
- Microsoft IIS 7.0 and later
- Apache 1.3.x no Microsoft Windows
- Apache 2.0.x no Microsoft Windows
- Servidores Sun, iPlanet e Netscape no Microsoft Windows
- Servidor Sambar no Microsoft Windows
- Xitami no Microsoft Windows
- Compilando a partir dos fontes
- Instalação de extensões no Windows
- Command Line PHP on Microsoft Windows
Essa seção aplica-se ao Windows 98/Me e Windows NT/2000/XP/2003. O PHP não funcionará em plataformas 16 bit como o Windows 3.1 e algumas vezes nos referimos às plataformas Windows suportadas como Win32.
Nota:
Os Windows 98/ME/NT4 não são mais suportados a partir do PHP 5.3.0.
Nota:
O Windows 95 não é mais suportado a partir do PHP 4.3.0.
Existem duas maneiras principais de instalar o PHP para o Windows: ou manualmente ou usando o instalador.
Se você tiver um ambiente de desenvolvimento como o Microsoft Visual Studio, você pode também compilar o PHP a partir do código-fonte original.
Uma vez que você tiver o PHP instalado no seu sistema Windows, você pode também querer carregar várias extensões para adicionar funcionalidades.
Existem vários instaladores completos na Internet, mas nenhum deles é apoioado pelo PHP.net, nós acreditamos que usando um dos pacotes oficial para Windows em » http://www.php.net/downloads.php seja a melhor maneira de ter seu sistema seguro e otimizado.
Instalador do PHP para o Windows (PHP 5.1.0 e anterior)
O Instalador do PHP para o Windows está disponível na página de downloads em » http://www.php.net/downloads.php. Ele instala a versão CGI do PHP e para IIS, PWS e Xitami, ele configura o servidor web também. O instalador não inclui qualquer extensão extra ao PHP (php_*.dll) uma vez que você só encontrará essas no pacote Zip para o Windows e nos downloads de PECL.
Nota:
Embora o instalador para o Windows seja uma maneira fácil de fazer o PHP funcionar, ele é restrito em muitos aspectos já que, por exemplo, a instalação automática de extensões não é suportada. Uso do instalador não é o método preferido para instalar o PHP.
Primeiro, instale o servidor HTTP (web) de sua preferência no seu sistema e teste se o mesmo funciona.
Execute o instalador e siga as instruções mostradas pelas telas de instalação. Dois tipos de instalação são suportadas - padrão, que provê padrões sensíveis para todas as configurações possíveis, e avançado, que pergunta tudo enquanto instala.
O auxiliar de instalação junta informação suficiente para configura o arquivo php.ini, e configura certos web server para usar o PHP. Um dos servidores web que o instalador não configura é o Apache, então você precisará configurá-lo manualmente.
Uma vez que a instalação tiver completado, o instalador informará a você se você precisa reiniciar seu sistema, reiniciar o servidor ou simplesmente começar a usar o PHP.
Cuidado, que essa configuração do PHP não é segura. Se você quiser ter uma configuração do PHP segura, é melhor usar a instalação manual, e editar cada opção com cuidado. Essa configuração automática te dé uma instalaço do PHP que funciona instantaneamente, mas ela não deve ser usada em servidores online.
Instalador para Windows (PHP 5.2 ou posterior)
O Instalador do PHP para Windows para versões recentes do PHP é feito usando a tecnologia MSI através do Wix Toolkit (» http://wix.sourceforge.net/). Ele instala e configura o PHP e todas as extensões PECL integradas, assim como configura muitos dos web servers mais populares, como IIS, Apache, e Xitami.
Primeiro, instale seu servidor HTTP (web) predileto no seu sistema e verifique que ele funciona. Então prossiga com um dos seguintes tipos de instação.
Instalação Normal
Execute o instalador MSI e siga as instruções fornecidas pelo programa. Ele primeiro perguntará qual Web Server você deseja configurar, assim como qualquer detalhe de configuração necessário.
Depois você deve selecionar quais funcionalidades e extensões você deseja instalar e habilitar. Para cada item disponível, você pode selecionar "Será instalado no disco local" no menu para determinar quais funcionalidades serão instaladas. Selcionado "Funcionalidade inteira será instalada no disco local", você poderá instalar todas as sub-funcionalidades vinculadas à funcionalidade (por exemplo, selecionar essa opção na extensão "PDO" você instalará todos os drivers PDO).
Não é recomendado instalar todas as extensões, já que muitas dependem de extensões externas ao PHP para funcionarem corretamente. Ao invés, use o Installation Repair Mode (Modo de Reparo) que pode ser acionado através da opção Add/Remove Programs (Adicionar/Remover Programas) do painel de controle para habilitar ou desabilitar extensões após a instalação.
O instalador então instala o PHP para ser usado no Windows e o arquivo php.ini, e configura certos servidores web para usá-lo. O instalador configura, atualmente, o IIS, Apache, Xitami e Sambar; se você estiver usando um servidor web diferente, você precisa configurá-lo manualmente.
Instalação silenciosa
O instalador também suporta um modo silencioso, que é útil para administradores de sistema implantarem o PHP facilmente. Para usar o modo silencioso:
msiexec.exe /i php-VERSION-win32-install.msi /q
Você pode controlar o diretório de instalação passando ele como parâmetro de linha de comando. Por exemplo, para instalar em e:\php:
msiexec.exe /i php-VERSION-win32-install.msi /q INSTALLDIR=e:\php
Você pode especificar quais funcionalidades instalar. Por exemplo, para instalar a extensão mysqli e o executável CGI:
msiexec.exe /i php-VERSION-win32-install.msi /q ADDLOCAL=cgi,ext_php_mysqli
A lista atual de funcionalidades para instalação é a seguinte:
MainExecutable - php.exe executable ScriptExecutable - php-win.exe executable ext_php_* - the various extensions ( for example: ext_php_mysql for MySQL ) apache13 - Apache 1.3 module apache20 - Apache 2.0 module apache22 - Apache 2,2 module apacheCGI - Apache CGI executable iis4ISAPI - IIS ISAPI module iis4CGI - IIS CGI executable NSAPI - Sun/iPlanet/Netscape server module Xitami - Xitami CGI executable Sambar - Sambar Server ISAPI module CGI - php-cgi.exe executable PEAR - PEAR installer Manual - PHP Manual in CHM Format
Para mais informações sobre instalando usando instaladores MSI a partir da linha de comando, visite » http://msdn.microsoft.com/en-us/library/aa367988.aspx
Atualizado o PHP com o instalador
Para fazer atualização, execute o instalador ou graficamente, ou a partir da linha de comando normalmente. O instalador lerá as opções atuais instalação, remover a instalação velha e reinstalará o PHP com as mesmas opções de antes. É recomendado que você use esse método para manter o PHP atualizado ao invés substituir manualmente os arquivos no diretório de instalação.
Passos para Instalação Manual
Esse guia de instalação ajudará você a instalar manualmente e configurar o PHP em um servidor web no Microsoft Windows. Para instruções de como utilizar o instalador do PHP para instalar e configurar um servidor web no Windows, veja o Instalador Windows (PHP 5.2 e posteriores).
Selecionando e baixando o pacote de distribuição do PHP
Baixe o binário do PHP em ZIP do link » PHP para Windows: Binários e fontes. Existem várias versões diferentes do pacote zip - escolha a versão que se encaixa com o servidor web sendo utilizado:
-
Se o PHP for usado com IIS, então escolha o PHP 5.3 VC9 Non Thread Safe ou PHP 5.2 VC6 Non Thread Safe;
-
Se o PHP for usado com IIS7 ou maior e PHP 5.3+, então os binários da VC9 devem ser utilizados.
-
Se o PHP for usado com Apache 1 ou Apache 2, então escolha o PHP 5.3 VC6 ou PHP 5.2 VC6.
Nota:
As versões VC9 são compiladas com o compilador do Visual Studio 2008 e têm melhorias de performance e estabilidade. As versões VC9 requerem que você tenha instalado o » Microsoft 2008 C++ Runtime (x86) ou o » Microsoft 2008 C++ Runtime (x64).
Estrutura e conteúdo do pacote PHP
Descompacte o conteúdo do arquivo zip em um diretório de sua escolha, por exemplo C:\PHP\. A estrutura de arquivos e diretórios extraídos serão conforme mostrado abaixo:
Exemplo #1 Estrutura do pacote PHP 5
c:\php | +--dev | | | |-php5ts.lib -- php5.lib em versão non thread safe | +--ext -- DLLS de extensões para o PHP | | | |-php_bz2.dll | | | |-php_cpdf.dll | | | |-... | +--extras -- vazio | +--pear -- cópia inicial do PEAR | | |-go-pear.bat -- script de setup do PEAR | |-... | |-php-cgi.exe -- executável CGI | |-php-win.exe -- executa scripts sem um prompt de comando aberto | |-php.exe -- executável PHP de Linha de Comando (CLI) | |-... | |-php.ini-development -- configurações php.ini padrão | |-php.ini-production -- configurações php.ini recomendadas | |-php5apache2_2.dll -- não existe na versão non thread safe | |-php5apache2_2_filter.dll -- não existe na versão non thread safe | |-... | |-php5ts.dll -- principal DLL do PHP ( php5.dll em versão non thread safe) | |-...
Abaixo está a lista de módulos e executáveis incluídos na distrubuição zip:
-
go-pear.bat - o script de setup do PEAR. Veja a » Instalação (PEAR) para mais detalhes.
-
php-cgi.exe - executável CGI que pode ser usado quando rodar o PHP no IIS via CGI ou FastCGI.
-
php-win.exe - executável do PHP para executar scripts PHP sem usar uma janela de linha de comando (por exemplo aplicativos PHP que usam a interface (GUI) do Windows).
-
php.exe - executável do PHP para executar scripts PHP dentro de uma interface de linha de comando (CLI).
-
php5apache2_2.dll - módulo para o Apache 2.2.X.
-
php5apache2_2_filter.dll - filtro para o Apache 2.2.X.
Alterando o arquivo php.ini
Depois que o conteúdo do pacote php foi extraído, copie o php.ini-production para php.ini dentro da mesma pasta. Se necessário, também é possível colocar o php.ini em qualquer outra localização de sua escolha, mas isso requer configurações adicionais conforme descrito em Configuração do PHP.
O arquivo php.ini diz para o PHP como se configurar, e como trabalhar com o ambiente em que ele está rodando. Aqui estão algumas configurações do arquivo php.ini que ajudarão o PHP a funcionar melhor com o Windows. Algumas delas são opcionais. Existem muitas outras diretivas que podem ser relevantes para o seu ambiente - veja a lista de diretivas do php.ini para mais informações.
Diretivas requeridas:
-
extension_dir = <caminho para o diretório de extesões> - A extension_dir precisa apontar para o diretório onde as extensões do PHP estão guardadas. O caminho pode ser absoluto (ex: "C:\PHP\ext") ou relativo (ex: ".\ext"). Extensões que estão listadas mais abaixo no arquivo php.ini precisam estar localizadas em extension_dir.
-
extension = xxxxx.dll - Para cada extensão que você deseja ativar, você precisa de uma diretiva "extension=" correspondente que diga o PHP que extensão no extension_dir para carregar durante a inicialização.
-
log_errors = On - O PHP tem um dispositivo de log de erros que pode ser usado para enviar erros para um arquivo, ou um serviço (ex: syslog) e funciona em conjunto com a diretiva abaixo error_log. Quando rodando sob o IIS, a log_errors pode ser ativada, com um error_log válido.
-
error_log = <caminho para o arquivo de log de erro> - A error_log deve especificar o caminho absoluto, ou relativo para o arquivo onde os erros do PHP devem ser logados. O servidor web precisa ter permissão de escrita para esse arquivo. Os caminhos mais comuns para esse arquivo são em diretórios TEMP, por exemplo "C:\inetpub\temp\php-errors.log".
-
cgi.force_redirect = 0 - Essa diretiva é requerida para rodar sob o IIS. É uma diretiva de segurança requerida por muitos outros servidores web. Entretanto, ativá-la sob o IIS fará com que o motor do PHP falhe no Windows.
-
cgi.fix_pathinfo = 1 - Isso permite que o PHP acesse a informação de caminho real dentro das especificações CGI. A implementação de IIS e FastCGI precisa que isso seja configurado.
-
fastcgi.impersonate = 1 - O FastCGI sob IIS tem a habilidade de imitar tokens de segurança do cliente que está chamando. Isso permite que o IIS defina o contexto de segurança da chamada.
-
fastcgi.logging = 0 - O log de FastCGI deve ser desativado no IIS. Se for deixado ativo, qualquer mensagem de qualquer classe é tratada pelo FastCGI como condições de erro que farão o IIS gerar uma excessão HTTP 500.
Diretivas opcionais
-
max_execution_time = ## - Essa diretiva diz ao PHP qual o máximo de tempo que ele pode gastar executando um determinado script. O padrão é 30 segundos. Aumente o valor dessa diretiva se as aplicações demoram muito tempo para executar.
-
memory_limit = ###M - A quantidade de memória disponível para o processo do PHP, em Megabytes. O padrão é 128, que é o suficiente para a maioria das aplicações PHP. Algumas mais complexas podem precisar de mais.
-
display_errors = Off - Essa diretiva diz ao PHP para incluir, ou não, qualquer mensagem de erro na corrente que ele retorna ao servidor Web. Se isso for configurado para "On", então o PHP irá enviar ao web server qualquer classe de erro que você definir na diretiva error_reporting como parte da corrente de erro. Por razões de segurança é recomendado que seja configurada para "Off" em servidores de produção, para não revelar qualquer informação de segurança sensível que é geralmente incluída nas mensagens de erro.
-
open_basedir = <caminhos para diretórios, separados por ponto-e-vírgula>, ex: openbasedir="C:\inetpub\wwwroot;C:\inetpub\temp". Essa diretiva especifica os caminhos para os diretórios onde o PHP pode executar operações de sistema de arquivos. Qualquer operação fora desses caminhos especificados resultará em um erro. Essa diretiva é especificamente útil para travar a instalação do PHP dentro de ambientes de hospedagem compartilhados para previnir scripts PHP de acessarem quaisquer arquivos fora do diretório raiz do web site.
-
upload_max_filesize = ###M e post_max_size = ###M - O tamanho máximo permitido de um arquivo subido e dados de post, respectivamente. Os valores dessas diretivas devem ser aumentados em aplicações PHP que precisam fazer grandes uploads, como por exemplo arquivo de fotos e vídeos.
O PHP agora está configurado no seu sistema. O próximo passo é escolher um servidor web, e fazer com que ele rode o PHP. Escolha um servidor na tabela de conteúdos.
Além de rodar o PHP em um servidor web, o PHP pode rodar a partir da linha de comando assim como um script .BAT. Veja PHP de linha de comando no Microsoft Windows para mais detalhes.
Microsoft IIS / PWS
Essa seção contêm notas e dicas específicas para o IIS (Microsoft Internet Information Server).
Um servidor dispoto em modo CGI está aberto para várias vulnerabilidades possíveis. Por favor, leia nossa seção de segurança CGI para aprender em como se defender de tais ataques.
Considerações Gerais para qualquer instalação do PHP com IIS ou PWS
- Primeiro, leia as Instruções de Instalação Manual. Não pule esse passo, já que ele provê informações cruciais para instalar o PHP no Windows.
- Usuários CGI devem configurar a diretiva cgi.force_redirect para o valor 0 no arquivo php.ini.Leia o FAQ sobre cgi.force_redirect para obter detalhes importantes. Também é aconselhável configurar a diretiva cgi.redirect_status_env. Quando usar diretiva, assegure-se que as mesmas não estejam comentadas no arquivo php.ini.
- O CGI do PHP 4 tem o nome php.exe e o do PHP 5 php-cgi.exe. No PHP 5, php.exe é o CLI, e não o CGI.
- Modifique a variável de ambiente PATH do Windows para conter o diretório do PHP. Dessa maneira, os arquivos DLL, executáveis do PHP podem ficar no diretório do PHP sem ocupar ainda mais o diretório system do Windows. Para mais detalhes, veja o FAQ sobre Configurando o PATH.
- O usuáiro IIS (normalmente IUSR_MACHINENAME) precisa de permissão para ler vários diretórios e arquivos, como o php.ini, docroot, e o diretório temporário de sessão.
- Tenha certeza que as diretivas extension_dir e doc_root estão configuradas corretamente no arquivo php.ini. Essas diretivas dependem do sistema onde o PHP foi instalado. No PHP 4, extension_dir é extensions e no PHP 5 é ext. Então, um exemplo de valor extensions_dir value no PHP 5 é "c:\php\ext" e um exemplo de valor doc_root para o IIS é "c:\Inetpub\wwwroot".
- Arquivos de DLL com extensões do PHP, tais como php_mysql.dll e php_curl.dll, são encontrados no arquivo zip do pacote do PHP (mas não no instalador do PHP). No PHP 5, muitas extensões são parte da PECL e podem ser baixadas no pacote "Coleção de módulos PECL". Arquivos como php_zip.dll e php_ssh2.dll. » Baixe arquivos do PHP aqui.
- Quando definir o executável, a caixa 'check that file exists' também pode ser selecionada. Pou um pequeno custo de performance, o IIS (ou PWS) checará se o arquivo do script existe e decide a autenticação antes de inicializar o PHP. Isso significa que o servidor web retornará uma página 404 ao invés de erros de CGI reclamando que o PHP não teve saída de dados.
- O executável do PHP é distribuido como um aplicação 32bit. Se você está usando uma versão 64bit do Windows, você irá também precisar recriar o binário você mesmo, ou tenha certeza que o IIS está configurado para também executar extensões 32bit. Você pode normalmente torna isto usando o IIS Administration script como segue: Cscript.exe adsutil.vbs SET W3SVC/AppPools/Enable32bitAppOnWin64 1
Windows NT/200x/XP e IIS 4 ou superior
O PHP pode ser instalado como binário CGI, ou como módulo ISAPI. Em ambos os casos, você precisa iniciar o Microsoft Management Console (pode aparecer como 'Internet Services Manager', ou no seu Windows NT 4.0 Option Pack ou no Control Panel=>Administrative Tools no Windows 2000/XP). Então clique no botão direito no seu ícone Web server (Provavelmente aparecerá como 'Default Web Server'), e selecione 'Properties'.
Se você quiser usar o binário CGI, faça o seguinte:
- Em 'Home Directory', 'Virtual Directory', ou 'Directory', faça o seguinte:
- Mude as Permissões de Execução para 'Scripts only'
- Clique no botão 'Configuration', e escolha a aba Application Mappings. Clique em Add e configure o caminho de execução do arquivo CGI apropriado. Um valor exemplo no PHP 5: C:\php\php-cgi.exe Marque .php como a extensão. Deixe 'Method exclusions' em branco, e marque a opção 'Script engine'. Agora clique OK algumas vezes.
- Configure a segurança apropriada. (Isso é feito no Internet Service Manager), e se seu Servidor NT usa o sistema de arquivos NTFS, adicione direito de execução para I_USR_ no diretório que contem php.exe / php-cgi.exe.
Para usuar o módulo ISAPI, faça o seguinte:
- Se você não quiser fazer Autenticação HTTP usando o PHP, você pode (e deve) pular esse passo. Em ISAPI Filters, adicione um novo filtro ISAPI. Use PHP como nome do filtro e dê o caminho para php4isapi.dll / php5isapi.dll.
- Em 'Home Directory', 'Virtual Directory', ou 'Directory', faça o seguinte:
- Mude as Permissões de Execução para 'Scripts only'
- Clique no botão 'Configuration', e escolha a aba Application Mappings. Clique em Add e configure o caminho de execução da DLL ISAPI apropriada. Um valor exemplo no PHP 5: C:\php\php5isapi.dll Marque .php como a extensão. Deixe 'Method exclusions' em branco, e marque a opção 'Script engine'. Agora clique OK algumas vezes.
- Pare o IIS completamente (NET STOP iisadmin)
- Inicialize o IIS novamente (NET START w3svc)
Com o IIS 6 (2003 Server), abra o IIS Manager, vá até Web Service Extensions, selecione "Add a new Web service extension", digite um nome como PHP, clique no botão Add e coloque no campo valor coloque ou o arquivo ISAPI (php4isapi.dll ou php5isapi.dll) ou do CGI (php.exe ou php-cgi.exe) e selecione a opção "Set extension status to Allowed" e clique OK.
Para usar index.php como página padrão de conteúdo, faça o seguinte: Na aba Documents, escolha Add. Digite index.php e clique OK. Ajuste a ordem clicando em Move Up ou Move Down. Isso é similar a configurar DirectoryIndex no Apache.
Os passos acima devem ser repetidos para cada extensão que será associada com scripts PHP. .php é a mais comum embora .php3 pode ser necessária para código legado.
Se ocorrer 100% de uso de CPU depois de um tempo, desligue a configuração do IIS Cache ISAPI Application.
Windows e PWS 4
PWS 4 não tem suporte a ISAPI, somente o CGI deve ser usado.
- Edite o arquivo pws-php4cgi.reg / pws-php5cgi.reg (procure no diretório SAPI no PHP 4, ou no diretório principal do PHP 5) para refletir a localização do seu php.exe / php-cgi.exe. Barras-invertidas devem ser escapadas, por exemplo: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\w3svc\parameters\Script Map] ".php"="C:\\php\\php.exe" (mude para C:\\php\\php-cgi.exe se você estiver usando PHP 5) Agora adicione o arquivo ao registro do seu sistema; você pode fazer isso clicando duas vezes nele.
- No PWS Manager, clique com o botão direito em um diretório que você queira adicionar suporte ao PHP, e selecione Properties. Marque a opção 'Execute' e confirme.
Windows e PWS/IIS 3
O método recomendado para configurar o PHP nesses servidores é usar o arquivo REG incluso na distribuição (pws-php4cgi.reg na pasta SAPI para o PHP 4, ou pws-php5cgi.reg na pasta principal para o PHP 5). Você pode querer editar o arquivo e assegurar-se que o diretório das extensões e do PHP estão corretos. Ou você pode seguir os passos abaixo para fazer manualmente.
Esses passos involvem trabalhar diretamente com o registro do Windows. Um erro aqui pode deixar seu sistema em um estado instável. Nós recomendamos que você faça um backup do seu registro primeiro. O time de desenvolvimento do PHP não será responsável se você danificar seu registro.
- Execute Regedit.
- Vá até: HKEY_LOCAL_MACHINE /System /CurrentControlSet /Services /W3Svc /Parameters /ScriptMap.
- No menu editar (edit) selecione: New->String Value.
- Digite a extensão que você quer para seus scripts PHP. Por exemplo .php
- Clique duas vezes no novo valor string e entre o caminho para php.exe no campo de valor. ex: C:\php\php.exe para o PHP 4, ou C:\php\php-cgi.exe para o PHP 5.
- Repita esses passos para cada extensão que você quiser associar com scripts PHP.
Os passos a seguir não afetam a instalação do servidor web e só se aplicam se você quiser que seus scripts sejam executados quando eles forem chamados da linha de comando (ex. run C:\myscripts\test.php) ou clicando duas vezes neles na janela de visualização de diretório. Você pode pular esses passos já que você pode preferir que os arquivos PHP sejam carregados em um editor de texto quando você clicar duas vezes neles.
- Vá até: HKEY_CLASSES_ROOT
- No menu de editar (edit) selecione: New->Key.
- Nomeie a chave com a extensão que você configurou na seção anterior. ex: .php
- Selecione a chave nova e no painel do lado direto, clique duas vezes no "default value" e digite phpfile.
- Repita o passo anterior para cada extensão que você configurou na seção anterior.
- Agora crie um outra chave (New->Key) em HKEY_CLASSES_ROOT e chame ela de phpfile.
- Selecione a chave nova phpfile e no painel do lado direito, clique duas vezes em "default value" e digite PHP Script.
- Clique com o botão direito na chave phpfile e selecione New->Key, e a chame de Shell.
- Clique com o botão direito na chave Shell e selecione New->Key, e a chame de open.
- Clique com o botão direito na chave open e selecione New->Key, e a chame de command.
- Selecione a chave nova command e no painel do lado direito, clique duas vezes em "default value" e entre o caminho para php.exe. ex: c:\php\php.exe -q %1. (não esqueça o %1).
- Saia do Regedit.
- Se estiver usando PWS no Windows, reinicie para recarrega o registro.
Usuários do PWS e do IIS 3 agora tem um sistema totalmente operacional. Usuários do IIS 3 pode usar uma » ferramenta legal de Steven Genusa para configurar os mapas dos seus scripts.
Microsoft IIS 5.1 and IIS 6.0
This section contains instructions for manually setting up Internet Information Services (IIS) 5.1 and IIS 6.0 to work with PHP on Microsoft Windows XP and Windows Server 2003. For instructions on setting up IIS 7.0 and later versions on Windows Vista, Windows Server 2008, Windows 7 and Windows Server 2008 R2 refer to Microsoft IIS 7.0 and later.
Configuring IIS to process PHP requests
Download and install PHP in accordance to the instructions described in manual installation steps
Nota:
Non-thread-safe build of PHP is recommended when using IIS. The non-thread-safe builds are available at » PHP for Windows: Binaries and Sources Releases.
Configure the CGI- and FastCGI-specific settings in php.ini file as shown below:
Exemplo #1 CGI and FastCGI settings in php.ini
fastcgi.impersonate = 1 fastcgi.logging = 0 cgi.fix_pathinfo=1 cgi.force_redirect = 0
Download and install the » Microsoft FastCGI Extension for IIS 5.1 and 6.0. The extension is available for 32-bit and 64-bit platforms - select the right download package for your platform.
Configure the FastCGI extension to handle PHP-specific requests by running the command shown below. Replace the value of the "-path" parameter with the absolute file path to the php-cgi.exe file.
Exemplo #2 Configuring FastCGI extension to handle PHP requests
cscript %windir%\system32\inetsrv\fcgiconfig.js -add -section:"PHP" ^ -extension:php -path:"C:\PHP\php-cgi.exe"
This command will create an IIS script mapping for *.php file extension, which will result in all URLs that end with .php being handled by FastCGI extension. Also, it will configure FastCGI extension to use the executable php-cgi.exe to process the PHP requests.
Nota:
At this point the required installation and configuration steps are completed. The remaining instructions below are optional but highly recommended for achieving optimal functionality and performance of PHP on IIS.
Impersonation and file system access
It is recommended to enable FastCGI impersonation in PHP when using IIS. This is controlled by the fastcgi.impersonate directive in php.ini file. When impersonation is enabled, PHP will perform all the file system operations on behalf of the user account that has been determined by IIS authentication. This ensures that even if the same PHP process is shared across different IIS web sites, the PHP scripts in those web sites will not be able to access each others' files as long as different user accounts are used for IIS authentication on each web site.
For example IIS 5.1 and IIS 6.0, in its default configuration, has anonymous authentication enabled with built-in user account IUSR_<MACHINE_NAME> used as a default identity. This means that in order for IIS to execute PHP scripts, it is necessary to grant IUSR_<MACHINE_NAME> account read permission on those scripts. If PHP applications need to perform write operations on certain files or write files into some folders then IUSR_<MACHINE_NAME> account should have write permission to those.
To determine which user account is used by IIS anonymous authentication, follow these steps:
-
In the Windows Start Menu choose "Run:", type "inetmgr" and click "Ok";
-
Expand the list of web sites under the "Web Sites" node in the tree view, right-click on a web site that is being used and select "Properties";
-
Click the "Directory Security" tab;
-
Take note of a "User name:" field in the "Authentication Methods" dialog
To modify the permissions settings on files and folders, use the Windows Explorer user interface or icacls command.
Exemplo #3 Configuring file access permissions
icacls C:\inetpub\wwwroot\upload /grant IUSR:(OI)(CI)(M)
Set index.php as a default document in IIS
The IIS default documents are used for HTTP requests that do not specify a document name. With PHP applications, index.php usually acts as a default document. To add index.php to the list of IIS default documents, follow these steps:
-
In the Windows Start Menu choose "Run:", type "inetmgr" and click "Ok";
-
Right-click on the "Web Sites" node in the tree view and select "Properties";
-
Click the "Documents" tab;
-
Click the "Add..." button and enter "index.php" for the "Default content page:".
FastCGI and PHP Recycling configuration
Configure IIS FastCGI extension settings for recycling of PHP processes by using the commands shown below. The FastCGI setting instanceMaxRequests controls how many requests will be processed by a single php-cgi.exe process before FastCGI extension shuts it down. The PHP environment variable PHP_FCGI_MAX_REQUESTS controls how many requests a single php-cgi.exe process will handle before it recycles itself. Make sure that the value specified for FastCGI InstanceMaxRequests setting is less than or equal to the value specified for PHP_FCGI_MAX_REQUESTS.
Exemplo #4 Configuring FastCGI and PHP recycling
cscript %windir%\system32\inetsrv\fcgiconfig.js -set -section:"PHP" ^ -InstanceMaxRequests:10000 cscript %windir%\system32\inetsrv\fcgiconfig.js -set -section:"PHP" ^ -EnvironmentVars:PHP_FCGI_MAX_REQUESTS:10000
Configuring FastCGI timeout settings
Increase the timeout settings for FastCGI extension if there are applications that have long running PHP scripts. The two settings that control timeouts are ActivityTimeout and RequestTimeout. Refer to » Configuring FastCGI Extension for IIS 6.0 for more information about those settings.
Exemplo #5 Configuring FastCGI timeout settings
cscript %windir%\system32\inetsrv\fcgiconfig.js -set -section:"PHP" ^ -ActivityTimeout:90 cscript %windir%\system32\inetsrv\fcgiconfig.js -set -section:"PHP" ^ -RequestTimeout:90
Changing the Location of php.ini file
PHP searches for php.ini file in several locations and it is possible to change the default locations of php.ini file by using PHPRC environment variable. To instruct PHP to load the configuration file from a custom location run the command shown below. The absolute path to the directory with php.ini file should be specified as a value of PHPRC environment variable.
Exemplo #6 Changing the location of php.ini file
cscript %windir%\system32\inetsrv\fcgiconfig.js -set -section:"PHP" ^ -EnvironmentVars:PHPRC:"C:\Some\Directory\"
Microsoft IIS 7.0 and later
This section contains instructions for manually setting up Internet Information Services (IIS) 7.0 and later to work with PHP on Microsoft Windows Vista SP1, Windows 7, Windows Server 2008 and Windows Server 2008 R2. For instructions on setting up IIS 5.1 and IIS 6.0 on Windows XP and Windows Server 2003 refer to Microsoft IIS 5.1 and IIS 6.0.
Enabling FastCGI support in IIS
FastCGI module is disabled in default installation of IIS. The steps to enable it differ based on the version of Windows being used.
To enable FastCGI support on Windows Vista SP1 and Windows 7:
-
In the Windows Start Menu choose "Run:", type "optionalfeatures.exe" and click "Ok";
-
In the "Windows Features" dialog expand "Internet Information Services", "World Wide Web Services", "Application Development Features" and then enable the "CGI" checkbox;
-
Click OK and wait until the installation is complete.
To enable FastCGI support on Windows Server 2008 and Windows Server 2008 R2:
-
In the Windows Start Menu choose "Run:", type "CompMgmtLauncher" and click "Ok";
-
If the "Web Server (IIS)" role is not present under the "Roles" node, then add it by clicking "Add Roles";
-
If the "Web Server (IIS)" role is present, then click "Add Role Services" and then enable the "CGI" checkbox under "Application Development" group;
-
Click "Next" and then "Install" and wait for the installation to complete.
Configuring IIS to process PHP requests
Download and install PHP in accordance to the instructions described in manual installation steps
Nota:
Non-thread-safe build of PHP is recommended when using IIS. The non-thread-safe builds are available at » PHP for Windows: Binaries and Sources Releases.
Configure the CGI- and FastCGI-specific settings in php.ini file as shown below:
Exemplo #1 CGI and FastCGI settings in php.ini
fastcgi.impersonate = 1 fastcgi.logging = 0 cgi.fix_pathinfo=1 cgi.force_redirect = 0
Configure IIS handler mapping for PHP by using either IIS Manager user interface or a command line tool.
Using IIS Manager user interface to create a handler mapping for PHP
Follow these steps to create an IIS handler mapping for PHP in IIS Manager user interface:
-
In the Windows Start Menu choose "Run:", type "inetmgr" and click "Ok";
-
In the IIS Manager user interface select the server node in the "Connections" tree view;
-
In the "Features View" page open the "Handler Mappings" feature;
-
In the "Actions" pane click "Add Module Mapping...";
-
In the "Add Module Mapping" dialog enter the following:
- Request path: *.php
- Module: FastCgiModule
- Executable: C:\[Path to PHP installation]\php-cgi.exe
- Name: PHP_via_FastCGI
-
Click "Request Restrictions" button and then configure the mapping to invoke handler only if request is mapped to a file or a folder;
-
Click OK on all the dialogs to save the configuration.
Using command line tool to create a handler mapping for PHP
Use the command shown below to create an IIS FastCGI process pool which will use php-cgi.exe executable for processing PHP requests. Replace the value of the fullPath parameter with the absolute file path to the php-cgi.exe file.
Exemplo #2 Creating IIS FastCGI process pool
%windir%\system32\inetsrv\appcmd set config /section:system.webServer/fastCGI ^ /+[fullPath='c:\PHP\php-cgi.exe']
Configure IIS to handle PHP specific requests by running the command shown below. Replace the value of the scriptProcessor parameter with the absolute file path to the php-cgi.exe file.
Exemplo #3 Creating handler mapping for PHP requests
%windir%\system32\inetsrv\appcmd set config /section:system.webServer/handlers ^ /+[name='PHP_via_FastCGI', path='*.php',verb='*',modules='FastCgiModule',^ scriptProcessor='c:\PHP\php-cgi.exe',resourceType='Either']
This command creates an IIS handler mapping for *.php file extension, which will result in all URLs that end with .php being handled by FastCGI module.
Nota:
At this point the required installation and configuration steps are completed. The remaining instructions below are optional but highly recommended for achieving optimal functionality and performance of PHP on IIS.
Impersonation and file system access
It is recommended to enable FastCGI impersonation in PHP when using IIS. This is controlled by the fastcgi.impersonate directive in php.ini file. When impersonation is enabled, PHP will perform all the file system operations on behalf of the user account that has been determined by IIS authentication. This ensures that even if the same PHP process is shared across different IIS web sites, the PHP scripts in those web sites will not be able to access each other's files as long as different user accounts are used for IIS authentication on each web site.
For example IIS 7, in its default configuration, has anonymous authentication enabled with built-in user account IUSR used as a default identity. This means that in order for IIS to execute PHP scripts, it is necessary to grant IUSR account read permission on those scripts. If PHP applications need to perform write operations on certain files or write files into some folders then IUSR account should have write permission to those.
To determine what user account is used as an anonymous identity in IIS 7 use the following command. Replace the "Default Web Site" with the name of IIS web site that you use. In the output XML configuration element look for the userName attribute.
Exemplo #4 Determining the account used as IIS anonymous identity
%windir%\system32\inetsrv\appcmd.exe list config "Default Web Site" ^
/section:anonymousAuthentication
<system.webServer>
<security>
<authentication>
<anonymousAuthentication enabled="true" userName="IUSR" />
</authentication>
</security>
</system.webServer>
Nota:
If userName attribute is not present in the anonymousAuthentication element, or is set to an empty string, then it means that the application pool identity is used as an anonymous identity for that web site.
To modify the permissions settings on files and folders, use the Windows Explorer user interface or icacls command.
Exemplo #5 Configuring file access permissions
icacls C:\inetpub\wwwroot\upload /grant IUSR:(OI)(CI)(M)
Set index.php as a default document in IIS
The IIS default documents are used for HTTP requests that do not specify a document name. With PHP applications, index.php usually acts as a default document. To add index.php to the list of IIS default documents, use this command:
Exemplo #6 Set index.php as a default document in IIS
%windir%\system32\inetsrv\appcmd.exe set config ^ -section:system.webServer/defaultDocument /+"files.[value='index.php']" ^ /commit:apphost
FastCGI and PHP Recycling configuration
Configure IIS FastCGI settings for recycling of PHP processes by using the commands shown below. The FastCGI setting instanceMaxRequests controls how many requests will be processed by a single php-cgi.exe process before IIS shuts it down. The PHP environment variable PHP_FCGI_MAX_REQUESTS controls how many requests a single php-cgi.exe process will handle before it recycles itself. Make sure that the value specified for FastCGI InstanceMaxRequests setting is less than or equal to the value specified for PHP_FCGI_MAX_REQUESTS.
Exemplo #7 Configuring FastCGI and PHP recycling
%windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi ^
/[fullPath='c:\php\php-cgi.exe'].instanceMaxRequests:10000
%windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi ^
/+"[fullPath='C:\{php_folder}\php-cgi.exe'].environmentVariables.^
[name='PHP_FCGI_MAX_REQUESTS',value='10000']"
FastCGI timeout settings
Increase the timeout settings for FastCGI if it is expected to have long running PHP scripts. The two settings that control timeouts are activityTimeout and requestTimeout. Use the commands below to change the timeout settings. Make sure to replace the value in the fullPath parameter to contain the absolute path to the php-cgi.exe file.
Exemplo #8 Configuring FastCGI timeout settings
%windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi ^ /[fullPath='C:\php\php-cgi.exe',arguments=''].activityTimeout:"90" /commit:apphost %windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/fastCgi ^ /[fullPath='C:\php\php-cgi.exe',arguments=''].requestTimeout:"90" /commit:apphost
Changing the Location of php.ini file
PHP searches for php.ini file in several locations and it is possible to change the default locations of php.ini file by using PHPRC environment variable. To instruct PHP to load the configuration file from a custom location run the command shown below. The absolute path to the directory with php.ini file should be specified as a value of PHPRC environment variable.
Exemplo #9 Changing the location of php.ini file
appcmd.exe set config -section:system.webServer/fastCgi ^ /+"[fullPath='C:\php\php.exe',arguments=''].environmentVariables.^ [name='PHPRC',value='C:\Some\Directory\']" /commit:apphost
Apache 1.3.x no Microsoft Windows
Essa seção contem notas e dicas específicas para instalação do Apache 1.3.x com o PHP nos sistemas Microsoft Windows. Também há instruções e notas para o Apache 2 em uma página separada.
Nota:
Por favor, leia os passos da instalação manual primeiro!
Existem duas maneiras de configurar o PHP para funcionar com o Apache 1.3.x no Windows. Uma é usar o binário CGI (php.exe para o PHP 4 e php-cgi.exe para o PHP 5), e a outra é usar o DLL do módulo do Apache. Em ambos os casos você precisa editar o arquivo httpd.conf para configurar o Apache para funcionar com o PHP e, então, reiniciar o servidor.
Vale a pena notar que agora o módulo SAPI tornou-se mais estável no Windows, nós recomendamos o seu uso ao invés do binário CGI, uma vez que é mais transparente e seguro.
Embora existam algumas pequenas variações de configuração do PHP com o Apache, elas são simples o suficiente para ser usado por iniciantes. Por favor, consulte a Documentação do Apache para mais diretivas de configuração.
Depois de mudar o arquivo de configuração, lembre-se de reiniciar o servidor, por exemplo, executando NET STOP APACHE seguido de NET START APACHE, se você rodar o Apache como um Windows Service, ou user os atalhos normais.
Nota: Lembre-se que quando acrescentando valores de caminhos nos arquivos de configuração do Apache para Windows, todas as contrabarras como em c:\directory\file.ext precisam ser convertidas para barras, como em c:/directory/file.ext. Uma barra ao final também é necessária para diretórios.
Instalando como um módulo do Apache
Você deve adicionar as seguintes linhas para o seu arquivo httpd.conf:
Exemplo #1 PHP como um módulo do Apache 1.3.x
Presume-se que o PHP esteja instalado em c:\php. Ajuste o caminho se não for o seu caso.
Para o PHP 4:
# Adicione ao fim da seção LoadModule # Não se esqueça de copiar esse arquivo do diretório sapi LoadModule php4_module "c:/php/php4apache.dll" # Adicione ao fim da seção AddModule AddModule mod_php4.c
Para o PHP 5:
# Adicione ao fim da seção LoadModule LoadModule php5_module "c:/php/php5apache.dll" # Adicione ao fim da seção AddModule AddModule mod_php5.c
Para ambos:
# Adicione essa linha dentro das tags condicionais <IfModule mod_mime.c> AddType application/x-httpd-php .php # Para arquivos .phps com highlight de sintaxe adicione também AddType application/x-httpd-php-source .phps
Instalando como um binário CGI
Se você dezipou o pacote PHP para o diretório C:\php\ como descrito na seção Passos da Instalação Manual, você precisa inserir as seguintes linhas ao arquivo de configuração do Apache para configurar o uso do binário CGI:
Exemplo #2 PHP e Apache 1.3.x como CGI
ScriptAlias /php/ "c:/php/" AddType application/x-httpd-php .php # Para o PHP 4 Action application/x-httpd-php "/php/php.exe" # Para o PHP 5 Action application/x-httpd-php "/php/php-cgi.exe" # especifica o diretório onde o php.ini está SetEnv PHPRC C:/php
Um servidor dispoto em modo CGI está aberto para várias vulnerabilidades possíveis. Por favor, leia nossa seção de segurança CGI para aprender em como se defender de tais ataques.
Se você gostaria de apresentar os códigos-fonte dos PHP com highlight de sintaxe, não exites uma opção conveniente como na versão de módulo. Se você escolheu configura o Apache para usar o PHP como um binário CGI, você precisará usar a função highlight_file(). Para fazer isso, simplesmente crie um script PHP e adicione esse código: <?php highlight_file('some_php_script.php'); ?>.
Apache 2.0.x no Microsoft Windows
Essa seção contem notas e dicas específicas para instalação do Apache 2.0.x com o PHP nos sistemas Microsoft Windows.Também há instruções e notas para o Apache 1.3.x em uma página separada.
Nota:
Por favor, leia os passos da instalação manual primeiro!
Nota: Suporte a Apache 2.2.x
Usuários do Apache 2.2.x devem usar a documentação abaixo exceto que o nome do arquivo da dll apropriada é php5apache2_2.dll e lea só existe a partir do 5.2.0. Veja também » http://snaps.php.net/
Nós não recomendamos a utilização de um threaded MPM em produção com o Apache2. Use ao invés prefork MPM, ou use Apache1. para informações sobre o motivo, leia este faq sobre usando Apache2 com um threaded MPM
Encorajamos que você olhe a » Documentação do Apache para entender o básico do Servidor Apache 2.0.x. Também considere ler as » notas específicas para o Windows para o Apache 2.0.x antes de continuar.
Nota: Notas de compatibilidade do PHP e Apache 2.0.x
As seguintes versões do PHP são compatíveis com a versão mais recente do Apache 2.0.x:
Essas versões do PHP são compatíveis com Apache 2.0.40 ou superior.
- PHP 4.3.0 ou superior, disponível em » http://www.php.net/downloads.php.
- A última versão estável de desenvolvimento. Pegue o código fonte » http://snaps.php.net/php5-latest.tar.gz ou baixe os binários para o Windows » http://snaps.php.net/win32/php5-win32-latest.zip.
- Uma versão pre-release disponível para download em » http://qa.php.net/.
- Você sempre tem a opção de obter o PHP através da conta » anônima do CVS.
Suporte a SAPI do Apache 2.0 começou no PHP 4.2.0. PHP 4.2.3 funciona com Apache 2.0.39, não use qualquer outra versão de Apache com PHP 4.2.3. No entando, a configuração recomendada é usar o 4.3.0 ou superior com a versão mais recente do Apache2.
Todas as versões mencionadas do PHP ainda funcionarão com Apache 1.3.x.
Apache 2.0.x foi desenhado para rodar no Windows NT 4.0, Windows 2000 ou Windows XP. Até o momento, suporte para Windows 9x está incompleto. Apache 2.0.x não tem planos para funcionar nessas plataformas.
Baixe a versão mais recente do » Apache 2.0.x e uma versão apropriada do PHP. Siga os Passos da Instalação Manual e volte para continuar com a integração do PHP e Apache.
Existem duas maneiras de configurar o PHP para funcionar com Apache 2.0.x no Windows. Uma é usar o binário CGI e a outra é usar o DLL do módulo do Apache. Em ambos os casos você precisa editar o arquivo httpd.conf para configurar o Apache para funcionar com o PHP e, então, reiniciar o servidor.
Nota: Lembre-se que quando acrescentando valores de caminhos nos arquivos de configuração do Apache para Windows, todas as contrabarras como em c:\directory\file.ext precisam ser convertidas para barras, como em c:/directory/file.ext. Uma barra ao final também é necessária para diretórios.
Instalando como um binário CGI
Você precisa inserir essas três linhas para o arquivo httpd.conf de configuração do Apache para configura o binário CGI:
Exemplo #1 PHP e Apache 2.0 como CGI
ScriptAlias /php/ "c:/php/" AddType application/x-httpd-php .php # Para o PHP 4 Action application/x-httpd-php "/php/php.exe" # Para o PHP 5 Action application/x-httpd-php "/php/php-cgi.exe"
Um servidor dispoto em modo CGI está aberto para várias vulnerabilidades possíveis. Por favor, leia nossa seção de segurança CGI para aprender em como se defender de tais ataques.
Instalando como um módulo do Apache
Você precisa inserir essas duas linhas ao arquivo de configuração de Apache httpd.conf para configurar o módulo PHP para o Apache 2.0:
Exemplo #2 PHP e Apache 2.0 como Módulo
# Para o PHP 4 faça algo assim: LoadModule php4_module "c:/php/php4apache2.dll" # Não esqueça de copiar o arquivo php4apache2.dll do diretório sapi para o principal do PHP! AddType application/x-httpd-php .php # Para o PHP 5 faça algo assim: LoadModule php5_module "c:/php/php5apache2.dll" AddType application/x-httpd-php .php # configure o caminho para o arquivo php.ini PHPIniDir "C:/php"
Nota: Lembre-se de substituir o caminho c:/php/ para o caminho onde você instalou o PHP na sua máquina. Tome o cuidade de usar ou php4apache2.dll ou php5apache2.dll na sua diretiva LoadModule e não php4apache.dll ou php5apache.dll já que essas últimas são feitas para rodar com o Apache 1.3.x.
Nota:
Se você quiser negociação de conteúdo, leia o FAQ relacionado.
Não misture sua instalação com arquivos DLL de versões diferentes do PHP. Você só pode escolher usar as DLL's e extensões inclusas na versão do PHP que você baixou.
Servidores Sun, iPlanet e Netscape no Microsoft Windows
Essa seção contem notas e dicas específicas para instalação do PHP em servidores Sun Java System Web Server, Sun ONE Web Server, iPlanet e Netscape no Windows.
A partir do PHP 4.3.3 você pode usar seus scripts PHP com o módulo NSAPI para gerar listagens personalizadas de diretórios e páginas de erro. Funções adicionais para compatibilidade com o Apache também estão disponíveis. Para suporte nos servidores web atuais leia a nota sobre subrequests.
Configurando como CGI em servidores Sun, iPlanet e Netscape
Para instalar o PHP como um tratador de CGI, faça o seguinte:
- Copie o arquivo php4ts.dll para a pasta raiz do seu sistema (o diretório onde você instalou o Windows)
-
Faça uma associação de arquivo a partir da linha de comando. Digite as duas linhas a seguir:
assoc .php=PHPScript ftype PHPScript=c:\php\php.exe %1 %*
- No Netscape Enterprise Administration Server crie um diretório dummy para o shellcgi e remova-o em seguida (esse passo cria 5 linhas importantes no obj.conf e permite que o servidor web trate scripts shellcgi).
- No Netscape Enterprise Administration Server crie um novo tipo mime (Category: type, Content-Type: magnus-internal/shellcgi, File Suffix:php).
- Faça isso para cada instância do servidor web que você quiser que rode o PHP
Mais detalhes sobre configuração do PHP como um executável CGI pode ser encontrado aqui: » http://benoit.noss.free.fr/php/install-php.html
Configurando como NSAPI em servidores Sun, iPlanet e Netscape
Para instalar o PHP com NSAPI, faça o seguinte:
- Copie php4ts.dll para a pasta raiz do seu sistema (o diretório onde você instalou o Windows)
-
Faça uma associação de arquivo a partir da linha de comando. Digite as duas linhas a seguir:
assoc .php=PHPScript ftype PHPScript=c:\php\php.exe %1 %*
- No Netscape Enterprise Administration Server crie um novo tipo mime (Category: type, Content-Type: magnus-internal/x-httpd-php, File Suffix: php).
-
Edite o arquivo magnus.conf (para servidores >= 6) ou obj.conf (para servidores < 6) e adicione o seguinte: Você deve colocar as linhas depois de mime types init.
(PHP >= 4.3.3) O parâmetro php_ini é opcional, mas com ele você pode colocar seu arquivo php.ini no diretório de configuração do seu servidor web.Init fn="load-modules" funcs="php4_init,php4_execute,php4_auth_trans" shlib="c:/php/sapi/php4nsapi.dll" Init fn="php4_init" LateInit="yes" errorString="Failed to initialise PHP!" [php_ini="c:/path/to/php.ini"]
-
Configure o objeto padrão no arquivo obj.conf (para classes de servidor virtual [Sun Web Server 6.0+] no arquivo vserver.obj.conf): Na seção <Object name="default">, coloque essa linha necessariamente após todas as linhas do tipo 'ObjectType' e antes das do tipo 'AddLog':
(PHP >= 4.3.3) Como parâmetros adicionais,você pode adicionar alguns valores especiais do arquivo php.ini, por exemplo, você pode atribuir um docroot="/path/to/docroot" específico ao contexto no qual php4_execute é chamado. Para valores booleanos do php.ini, use 0/1 como valor, e não "On","Off",... (Isso não funcionará), ex.: zlib.output_compression=1 ao invés de zlib.output_compression="On"Service fn="php4_execute" type="magnus-internal/x-httpd-php" [inikey=value inikey=value ...]
-
Isso só é necessário se você quiser configurar um diretório que só consiste de scripts PHP (como em um diretório cgi-bin):
Depois disso você pode configurar um diretório na ferramenta de Administração do servidor e atribuir a ele um estilo x-httpd-php. Todos os arquivos neles serão executados como PHP. Isso é bom para esconder o uso do PHP renomeando os arquivos como .html.<Object name="x-httpd-php"> ObjectType fn="force-type" type="magnus-internal/x-httpd-php" Service fn=php4_execute [inikey=value inikey=value ...] </Object>
- Reinicie seu servidor web e aplique as mudanças
- Faça isso para cada instância do servidor web que você quiser que execute o PHP
Nota:
Mais detalhes sobre configurar o PHP como um filtro NSAPI pode ser achado aqui: » http://benoit.noss.free.fr/php/install-php4.html
Nota:
O tamanho de pilha que o PHP usa depende da configuração do servidor web. Se você tiver problemas com scripts muito grandes, é recomendado aumentar esse tamanho com o Administrador do Servidor (na seção "MAGNUS EDITOR").
Ambiente CGI e modificações recomendadas ao arquivo php.ini
É importante quando escrevendo scripts PHP levar em conta o fato que Sun JSWS/Sun ONE WS/iPlanet/Netscape são servidores multithreaded. Por isso, todas as requisições estão sendo executadas no mesmo espaço de processo (o espaço do servidor web) e esse espaço só tem um ambiente. Se você quiser usar variáveis CGI como PATH_INFO, HTTP_HOST etc, não é correto tentar pegá-las da maneira do PHP antigo, usando a função getenv() ou uma maneira similar (registrar globais para o ambiente, $_ENV). Você só iria pegar o ambiente do servidor web sem quaisquer variáveis CGI válidas!
Nota:
Porque existem variáveis CGI (inválidas) no ambiente?
Resposta: Isso é porque você inicializou o processo do servidor a partir do administrador do servidor que executa o script de inicialização do servidor web, você queria iniciar, como um script CGI (um script CGI dentro do administrador do servidor!). Isso é porque o ambiente do servidor tem algumas variáveis CGI do ambiente nele. Você pode testar isso inicializando o servidor web de outra forma que não pelo administrador do servidor. Use a linha de comando como usuário root e inicialize-o manualmente - você verá que não há variáveis ambientes do tipo CGI.
Simplesmente mude seus scripts para pegar variáveis CGI da maneira correta para o PHP 4.x, usando o array superglobal $_SERVER. Se você tiver scripts mais antigos que usem $HTTP_HOST, etc., você deve ligar a diretiva register_globals no arquivo php.ini e mudar a ordem das variáveis também (importante: remova "E" da diretiva, porque você não precisa das variávies de ambiente aqui):
variables_order = "GPCS" register_globals = On
Uso especial para páginas de erro ou listagens de conteúdo de diretório auto-geradas (PHP >= 4.3.3)
Você pode usar o PHP para gerar as páginas de erro para "404 Not Found" ou similar. Adicione a seguinte linha ao objeto no arquivo obj.conf para cada página de erro que você queira sobrescrever:
Error fn="php4_execute" code=XXX script="/path/to/script.php" [inikey=value inikey=value...]
Outra possibilidade é gerar listagens de conteúdo de diretório. Apenas crie um script PHP que mostre uma listagem do diretório e substitua o valor padrão da linha Service type="magnus-internal/directory" no arquivo obj.conf com a seguinte:
Service fn="php4_execute" type="magnus-internal/directory" script="/path/to/script.php" [inikey=value inikey=value...]
Nota sobre nsapi_virtual() e subrequisições (subrequests) (PHP >= 4.3.3)
O módulo NSAPI agora suporta a função nsapi_virtual() (sinônimo (alias): virtual()) para fazer subrequisições no servidor web e inserir o resultado em uma página web. O problema é que essa função usa algumas características não documentadas da biblioteca NSAPI.
No Unix, isso não é um problema, porque o módulo procura automaticamente pelas funções necessárias e usa elas se disponíveis. Se não, nsapi_virtual() é desabilitada.
Limitações de tratamento de DLLs no Windows precisam da detecção automática do arquivo ns-httpdXX.dll mais recente. Isso é testado pelos servidores até a versão 6.1. Se uma versão mais nova do servidor Sun é usado, a detecção falha e nsapi_virtual() é desabilitada.
Se esse for o caso, tente o seguinte: Adicione o seguinte parâmetro para php4_init em magnus.conf/obj.conf:
Init fn=php4_init ... server_lib="ns-httpdXX.dll"
Você pode verificar o status usando a função phpinfo().
Nota:
Mas esteja avisado: O suporte para nsapi_virtual() é EXPERIMENTAL!!!
Servidor Sambar no Microsoft Windows
Essa seção contem notas e dicas específicas para o » Sambar Server para Windows.
Nota:
Você deve ler os passos de instalação do manual antes!
Essa lista descreve como instalar o módulo ISAPI para que funcione com o servidor Sambar no Windows.
-
Ache o arquivo chamado mappings.ini (no diretório de configuração) no diretório de instalação dp Sambar.
-
Abra o arquivo mappings.ini e adicione a seguinte linha sob [ISAPI]:
(Essa linha presume que o PHP foi instalado em c:\php.)Exemplo #1 Configuração ISAPI do Sambar
#para o PHP 4 *.php = c:\php\php4isapi.dll #para o PHP 5 *.php = c:\php\php5isapi.dll
-
Agora reinicie o servidor Sambar para que as mudanças tenha efeito.
Nota:
Se você deseja usar o PHP para se comunicar com recursos que estão guardados em um computador diferente em sua rede, então você precisará alterar a conta de usuário usada pelo Sambar Server Service. A conta padrão usada pelo Sambar Server Service é LocalSystem, que não tem acesso a recursos remotos. A conta pode ser modifica usando a opção Serviços (Services) dentro do das Ferramentas Administrativas (Administation Tools) do Painel de Controle (Control Panel) do Windows.
Xitami no Microsoft Windows
Essa seção contem notas e dicas específicas para o » Xitami no Windows.
Nota:
Você deve ler os passos de instalação manual primeiro!
Essa lista descreve como configura o binário CGI do PHP para funcionar com Xitami no Windows.
Nota: Importante para usuários que instalaram o CGI
Leia o faq sobre cgi.force_redirect para detalhes importantes. Essa diretiva precisa ser editada para 0. Se você quiser usar $_SERVER['PHP_SELF'] você tem que habilitar a diretiva cgi.fix_pathinfo.
Um servidor dispoto em modo CGI está aberto para várias vulnerabilidades possíveis. Por favor, leia nossa seção de segurança CGI para aprender em como se defender de tais ataques.
-
Assegure-se que o servidor web está rodando e aponte o seu browser para o console de administração do Xitami (normalmente http://127.0.0.1/admin), e clique em Configuração (Configuration).
-
Navegue para os Filtros (Filters), e ponha a extensão que o PHP deve avaliar (ex.: .php) no campo extensões de Arquivo (.xxx).
-
No comando ou script Filtro (Filter) ponha o caminho e o nome do seu executável CGI, ex.: C:\php\php.exe para o PHP 4, ou C:\php\php-cgi.exe para o PHP 5.
-
Pressione o ícone Salvar (Save).
-
Reinicie o servidor para as mudanças terem efeito.
Compilando a partir dos fontes
Esse capítulo ensina como compilar PHP a partir dos fontes no Windows, usando as ferramentas da Microsoft. Para compilar o PHP com cygwin, veja o Instalação em sistemas Unix.
Veja a documentação no Wiki em: » http://wiki.php.net/internals/windows/stepbystepbuild
Instalação de extensões no Windows
Depois de instalar o PHP e um servidor web no Windows, você provavelmente desejará instalar algumas extensões para ter funcionalidades extras. Você pode escolher quais extensões você quer que o PHP carregue quando é iniciado modificando o arquivo php.ini. Você também pode carregar um módulo dinamicamente no seu script usando dl().
Os DLLs para extensões do PHP são prefixadas com php_.
Muitas extensões são compiladas dentro da versão para Windows. Isso significa que arquivos DLL adicionais, e a diretiva extension, não são utilizadas para carregar essas extensões. A tabela de Extensões PHP lista extensões que requerem, ou costumavam requerer, arquivos DLL adicionais do PHP. Aqui está uma lista das extensões já compiladas dentro do PHP:
No PHP 4 (atualizado PHP 4.3.11): BCMath, Caledar, COM, Ctype, FTP, MySQL, ODBC, Overload, PCRE, Session, Tokenizer, WDDX, XML e Zlib
No PHP 5 (atualizado PHP 5.0.4), as seguintes mudanças existem. Embutido: DOM, LibXML, Iconv, SimpleXML, SPL e SQLite. E os seguintes não são mais embutidos: MySQL e Overload.
A localização padrão que o PHP procura por extensões é C:\php4\extensions no PHP 4 e C:\php5 no PHP 5. Para mudar esta configuração para refletir sua instalação do PHP, edite o arquivo php.ini:
-
Você precisará mudar a configuração extension_dirpara apontar o diretório onde suas extensões estão guardadas, ou onde você colocou os arquivos php_*.dll. Por exemplo:
extension_dir = C:\php\extensions
-
Habilite a(s) extensão(ões) no arquivo php.ini que você quiser descomentando as linhas extension=php_*.dll. Isso é feito removendo o ; na antes da linha com a extensão que você quer carregar.
Exemplo #1 Habilitar a extensão Bzip2 para o PHP-Windows
// Mude a seguinte linha de ... ;extension=php_bz2.dll // ... para extension=php_bz2.dll
-
Algumas das extensões precisam de DLLs extras para funcionarem. Algumas delas podem ser encontradas no pacote da distribuição, na pasta C:\php\dlls\ no PHP 4 ou na pasta principal no PHP 5, mas algumas, por exemplo o Oracle (php_oci8.dll) requerem DLLs que não estão agregadas ao pacote da distribuição. Se você estiver instalando o PHP 4, copie as DLLs agregadas da pasta C:\php\dlls para a pasta principal C:\php. Não se esqueça de incluir C:\php na variável de ambiente PATH (esse processo é explicado em outra página, nesse FAQ).
-
Algumas destas dlls não sao embutidas com a distribuição do PHP. Veja a documentação de cada extensão para maiores detalhes. Também leia o manual na sessão entitulada Instalação de extensões PECL para detalhes sobre PECL. Um crestente número de extensões para o PHP são encontradas no PECL, e estas extensões precisam de um download separado.
Nota: Se você estiver executando a versão de módulo do servidor do PHP lembre de reiniciar o servidor web para que as mudanças no arquivo php.ini sejam efetivadas.
A tabela a seguir descreve algumas das extensões disponíveis e as dlls adicionais requeridas.
| Extensão | Descrição | Notas |
|---|---|---|
| php_bz2.dll | Funções de Compressão de bzip2 | Nenhuma |
| php_calendar.dll | Funções de Conversão de Calendar | Integrado desde o PHP 4.0.3 |
| php_crack.dll | Funções de Crack | Nenhuma |
| php_ctype.dll | Família de Funções ctype | Integrado desde o PHP 4.3.0 |
| php_curl.dll | Biblioteca de Funções de Cliente URL - CURL | Requer: libeay32.dll, ssleay32.dll (agregado) |
| php_dba.dll | Camada de Funções de Abstração de Banco de Dados DBA | Nenhuma |
| php_dbase.dll | Funções de dBase | Nenhuma |
| php_dbx.dll | Funções dbx | |
| php_domxml.dll | Funções DOM XML | PHP <= 4.2.0 requer: libxml2.dll (agregado) PHP >= 4.3.0 requer: iconv.dll (agregado) |
| php_dotnet.dll | Funções .NET | PHP <= 4.1.1 |
| php_exif.dll | Funções EXIF | php_mbstring.dll. e, php_exif.dll devem ser carregados depois de php_mbstring.dll no arquivo php.ini. |
| php_fbsql.dll | Funções FrontBase | PHP <= 4.2.0 |
| php_fdf.dll | Funções de Formato de Dados de Formulários (Forms Data Format) FDF. | Requer: fdftk.dll (agregado) |
| php_filepro.dll | Funções de filePro | Acesso apenas de Leitura |
| php_ftp.dll | Funções de FTP | Integrado desde o PHP 4.0.3 |
| php_gd.dll | Funções da biblioteca de imagens GD | Removido no PHP 4.3.2. Note também que funções truecolor functions não estão disponíveis no GD1, ao invés, use php_gd2.dll. |
| php_gd2.dll | Funções da biblioteca de imagens GD | GD2 |
| php_gettext.dll | Funções de Gettext | PHP <= 4.2.0 requer gnu_gettext.dll (agregado), PHP >= 4.2.3 requer libintl-1.dll, iconv.dll (agregado). |
| php_hyperwave.dll | Funções de HyperWave | Nenhuma |
| php_iconv.dll | Conversão de tabela de caracteres ICONV | Requer: iconv-1.3.dll (agregado), PHP >=4.2.1 iconv.dll |
| php_ifx.dll | Funções de Informix | Requer: Informix libraries |
| php_iisfunc.dll | Funções de manuseio de IIS | Nenhuma |
| php_imap.dll | Funções de IMAP POP3 e NNTP | Nenhuma |
| php_ingres.dll | Funções de Ingres II | Requer: Ingres II libraries |
| php_interbase.dll | Funções de InterBase | Requer: gds32.dll (agregado) |
| php_java.dll | Funções de Java | PHP <= 4.0.6 requer: jvm.dll (agregado) |
| php_ldap.dll | Funções de LDAP | PHP <= 4.2.0 requer libsasl.dll (agregado), PHP >= 4.3.0 requer libeay32.dll, ssleay32.dll (agregado) |
| php_mbstring.dll | Funções de Multi-Byte String | Nenhuma |
| php_mcrypt.dll | Funções de Mcrypt Encryption | Requer: libmcrypt.dll |
| php_mhash.dll | Funções de Mhash | PHP >= 4.3.0 requer: libmhash.dll (agregado) |
| php_mime_magic.dll | Funções de Mimetype | Requer: magic.mime (agregado) |
| php_ming.dll | Funções de Ming para Flash | Nenhuma |
| php_msql.dll | Funções de mSQL | Requer: msql.dll (agregado) |
| php_mssql.dll | Funções de MSSQL | Requer: ntwdblib.dll (agregado) |
| php_mysql.dll | Funções de MySQL | PHP >= 5.0.0, requer libmysql.dll (agregado) |
| php_mysqli.dll | Funções de MySQLi | PHP >= 5.0.0, requer libmysql.dll (libmysqli.dll in PHP <= 5.0.2) (agregado) |
| php_oci8.dll | Funções de Oracle 8 | Requer: Oracle 8.1+ client libraries |
| php_openssl.dll | Funções de OpenSSL | Requer: libeay32.dll (agregado) |
| php_overload.dll | Funções de sobrecarga de objetos | Integrado desde o PHP 4.3.0 |
| php_pdf.dll | Funções de PDF | Nenhuma |
| php_pgsql.dll | Funções de PostgreSQL | Nenhuma |
| php_printer.dll | Funções de Impressora | Nenhuma |
| php_shmop.dll | Funções de Memória Compartilhada | Nenhuma |
| php_snmp.dll | Funções de get and walk de SNMP | Apenas no NT! |
| php_soap.dll | Funções de SOAP | PHP >= 5.0.0 |
| php_sockets.dll | Funções de Socket | Nenhuma |
| php_sybase_ct.dll | Funções de Sybase | Requer: bibliotecas de cliente do Sybase |
| php_tidy.dll | Funções de Tidy | PHP >= 5.0.0 |
| php_tokenizer.dll | Funções de Tokenizer | Integrado desde o PHP 4.3.0 |
| php_w32api.dll | Funções de W32api | Nenhuma |
| php_xmlrpc.dll | Funções de XML-RPC | PHP >= 4.2.1 requer: iconv.dll (agregado) |
| php_xslt.dll | Funções de XSLT | PHP <= 4.2.0 requer sablot.dll, expat.dll (agregado). PHP >= 4.2.1 requer sablot.dll, expat.dll, iconv.dll (agregado). |
| php_yaz.dll | Funções do YAZ | Requer: yaz.dll (agregado) |
| php_zip.dll | Funções para Arquivos Zip | Acesso apenas de leitura |
| php_zlib.dll | Funções de compressão de ZLib | Integrado desde o PHP 4.3.0 |
Command Line PHP on Microsoft Windows
This section contains notes and hints specific to getting PHP running from the command line for Windows.
Nota:
You should read the manual installation steps first!
Getting PHP to run from the command line can be performed without making any changes to Windows.
C:\PHP5\php.exe -f "C:\PHP Scripts\script.php" -- -arg1 -arg2 -arg3
But there are some easy steps that can be followed to make this simpler. Some of these steps should already have been taken, but are repeated here to be able to provide a complete step-by-step sequence.
-
Add the location of the PHP executable (php.exe, php-win.exe or php-cli.exe depending upon your PHP version and display preferences) to the PATH environment variable. Read more about how to add your PHP directory to PATH in the corresponding FAQ entry.
-
Add the .PHP extension to the PATHEXT environment variable. This can be done at the same time as amending the PATH environment variable. Follow the same steps as described in the FAQ but amend the PATHEXT environment variable rather than the PATH environment variable.
Nota:
The position in which you place the .PHP will determine which script or program is executed when there are matching filenames. For example, placing .PHP before .BAT will cause your script to run, rather than the batch file, if there is a batch file with the same name.
-
Associate the .PHP extension with a file type. This is done by running the following command:
assoc .php=phpfile
-
Associate the phpfile file type with the appropriate PHP executable. This is done by running the following command:
ftype phpfile="C:\PHP5\php.exe" -f "%1" -- %~2
Following these steps will allow PHP scripts to be run from any directory without the need to type the PHP executable or the .PHP extension and all parameters will be supplied to the script for processing.
The example below details some of the registry changes that can be made manually.
Exemplo #1 Registry changes
Windows Registry Editor Version 5.00 [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\.php] @="phpfile" "Content Type"="application/php" [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile] @="PHP Script" "EditFlags"=dword:00000000 "BrowserFlags"=dword:00000008 "AlwaysShowExt"="" [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\DefaultIcon] @="C:\\PHP5\\php-win.exe,0" [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell] @="Open" [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell\Open] @="&Open" [HKEY_LOCAL_MACHINE\SOFTWARE\Classes\phpfile\shell\Open\command] @="\"C:\\PHP5\\php.exe\" -f \"%1\" -- %~2"
With these changes the same command can be written as:
"C:\PHP Scripts\script" -arg1 -arg2 -arg3
script -arg1 -arg2 -arg3
Nota:
There is a small problem if you intend to use this technique and use your PHP scripts as a command line filter, like the example below:
ordir | "C:\PHP Scripts\script" -arg1 -arg2 -arg3You may find that the script simply hangs and nothing is output. To get this operational, you need to make another registry change.dir | script -arg1 -arg2 -arg3Further information regarding this issue can be found in this » Microsoft Knowledgebase Article : 321788.Windows Registry Editor Version 5.00 [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\policies\Explorer] "InheritConsoleHandles"=dword:00000001
Installation on Cloud Computing platforms
Índice
PHP installs on the cloud. To the PHP cloud!
FastCGI Process Manager (FPM)
Índice
FPM (FastCGI Process Manager) is an alternative PHP FastCGI implementation with some additional features (mostly) useful for heavy-loaded sites.
These features include:
-
advanced process management with graceful stop/start;
-
ability to start workers with different uid/gid/chroot/environment, listening on different ports and using different php.ini (replaces safe_mode);
-
stdout and stderr logging;
-
emergency restart in case of accidental opcode cache destruction;
-
accelerated upload support;
-
"slowlog" - logging scripts (not just their names, but their PHP backtraces too, using ptrace and similar things to read remote process' execute_data) that are executed unusually slow;
-
fastcgi_finish_request() - special function to finish request and flush all data while continuing to do something time-consuming (video converting, stats processing etc.);
-
dynamic/static child spawning;
-
basic SAPI status info (similar to Apache mod_status);
-
php.ini-based config file.
Installation
Compiling from sources
In order to enable FPM in your PHP build you need to add --enable-fpm to your configure line.
There are several other FPM-specific configure options (all of them optional):
-
--with-fpm-user - set FPM user (default - nobody).
-
--with-fpm-group - set FPM group (default - nobody).
Configuration
FPM uses php.ini syntax for its configuration file - php-fpm.conf.
List of global php-fpm.conf directives
- pid string
-
Path to PID file. Default value: none.
- error_log string
-
Path to error log file. Default value: #INSTALL_PREFIX#/log/php-fpm.log.
- log_level string
-
Error log level. Possible values: alert, error, warning, notice, debug. Default value: notice.
- emergency_restart_threshold int
-
If this number of child processes exit with SIGSEGV or SIGBUS within the time interval set by emergency_restart_interval then FPM will restart. A value of 0 means 'Off'. Default value: 0 (Off).
- emergency_restart_interval mixed
-
Interval of time used by emergency_restart_interval to determine when a graceful restart will be initiated. This can be useful to work around accidental corruptions in an accelerator's shared memory. Available Units: s(econds), m(inutes), h(ours), or d(ays). Default Unit: seconds. Default value: 0 (Off).
- process_control_timeout mixed
-
Time limit for child processes to wait for a reaction on signals from master. Available units: s(econds), m(inutes), h(ours), or d(ays) Default Unit: seconds. Default value: 0.
- daemonize boolean
-
Send FPM to background. Set to 'no' to keep FPM in foreground for debugging. Default value: yes.
List of pool directives
With FPM you can run several pools of processes with different setting. These are settings that can be tweaked per pool.
- listen string
-
The address on which to accept FastCGI requests. Valid syntaxes are: 'ip.add.re.ss:port', 'port', '/path/to/unix/socket'. This option is mandatory for each pool.
- listen.backlog int
-
Set listen(2) backlog. A value of '-1' means unlimited. Default value: -1.
- listen.allowed_clients string
-
List of ipv4 addresses of FastCGI clients which are allowed to connect. Equivalent to the FCGI_WEB_SERVER_ADDRS environment variable in the original PHP FastCGI (5.2.2+). Makes sense only with a tcp listening socket. Each address must be separated by a comma. If this value is left blank, connections will be accepted from any ip address. Default value: any.
- listen.owner string
-
Set permissions for unix socket, if one is used. In Linux, read/write permissions must be set in order to allow connections from a web server. Many BSD-derived systems allow connections regardless of permissions. Default values: user and group are set as the running user, mode is set to 0666.
- listen.group string
-
See listen.owner.
- listen.mode string
-
See listen.owner.
- user string
-
Unix user of FPM processes. This option is mandatory.
- group string
-
Unix group of FPM processes. If not set, the default user's group is used.
- pm string
-
Choose how the process manager will control the number of child processes. Possible values: static, dynamic. This option is mandatory.
static - the number of child processes is fixed (pm.max_children).
dynamic - the number of child processes is set dynamically based on the following directives: pm.max_children, pm.start_servers, pm.min_spare_servers, pm.max_spare_servers.
- pm.max_children int
-
The number of child processes to be created when pm is set to static and the maximum number of child processes to be created when pm is set to dynamic. This option is mandatory.
This option sets the limit on the number of simultaneous requests that will be served. Equivalent to the ApacheMaxClients directive with mpm_prefork and to the PHP_FCGI_CHILDREN environment variable in the original PHP FastCGI.
- pm.start_servers in
-
The number of child processes created on startup. Used only when pm is set to dynamic. Default Value: min_spare_servers + (max_spare_servers - min_spare_servers) / 2.
- pm.min_spare_servers int
-
The desired minimum number of idle server processes. Used only when pm is set to dynamic. Also mandatory in this case.
- pm.max_spare_servers int
-
The desired maximum number of idle server processes. Used only when pm is set to dynamic. Also mandatory in this case.
- pm.max_requests int
-
The number of requests each child process should execute before respawning. This can be useful to work around memory leaks in 3rd party libraries. For endless request processing specify '0'. Equivalent to PHP_FCGI_MAX_REQUESTS. Default value: 0.
- pm.status_path string
-
The URI to view the FPM status page. If this value is not set, no URI will be recognized as a status page. Default value: none.
- ping.path string
-
The ping URI to call the monitoring page of FPM. If this value is not set, no URI will be recognized as a ping page. This could be used to test from outside that FPM is alive and responding. Please note that the value must start with a leading slash (/).
- ping.response string
-
This directive may be used to customize the response to a ping request. The response is formatted as text/plain with a 200 response code. Default value: pong.
- request_terminate_timeout mixed
-
The timeout for serving a single request after which the worker process will be killed. This option should be used when the 'max_execution_time' ini option does not stop script execution for some reason. A value of '0' means 'Off'. Available units: s(econds)(default), m(inutes), h(ours), or d(ays). Default value: 0.
- request_slowlog_timeout mixed
-
The timeout for serving a single request after which a PHP backtrace will be dumped to the 'slowlog' file. A value of '0' means 'Off'. Available units: s(econds)(default), m(inutes), h(ours), or d(ays). Default value: 0.
- slowlog string
-
The log file for slow requests. Default value: #INSTALL_PREFIX#/log/php-fpm.log.slow.
- rlimit_files int
-
Set open file descriptor rlimit. Default value: system defined value.
- rlimit_core int
-
Set max core size rlimit. Possible Values: 'unlimited' or an integer greater or equal to 0. Default value: system defined value.
- chroot string
-
Chroot to this directory at the start. This value must be defined as an absolute path. When this value is not set, chroot is not used.
- chdir string
-
Chdir to this directory at the start. This value must be an absolute path. Default value: current directory or / when chroot.
- catch_workers_output boolean
-
Redirect worker stdout and stderr into main error log. If not set, stdout and stderr will be redirected to /dev/null according to FastCGI specs. Default value: no.
It's possible to pass additional environment variables and update PHP settings of a ceratian pool. To do this, you need to add the following options to php-fpm.conf
Exemplo #1 Passing environment variables and PHP settings to a pool
env[HOSTNAME] = $HOSTNAME
env[PATH] = /usr/local/bin:/usr/bin:/bin
env[TMP] = /tmp
env[TMPDIR] = /tmp
env[TEMP] = /tmp
php_admin_value[sendmail_path] = /usr/sbin/sendmail -t -i -f www@my.domain.com
php_flag[display_errors] = off
php_admin_value[error_log] = /var/log/fpm-php.www.log
php_admin_flag[log_errors] = on
php_admin_value[memory_limit] = 32M
Settings defined with php_admin_value and php_admin_flag cannot be overriden with ini_set().
Instalação das extensões PECL
Índice
- Introdução para instalações PECL
- Baixando extensões PECL
- PECL para usuários Windows
- Compilando extensões compartilhadas PECL com o comando pecl
- Compilando extensões compartilhadas PECL com phpize
- Compilando extensões PECL estaticamente no PHP
Introdução para instalações PECL
» PECL é um repositório de extensões PHP que estão disponíveis à você pelo sistema de pacote » PEAR. Essa seção do manual é destinada para demonstrar como obter e instalar extensões PECL.
Essas instruções presumem que /your/phpsrcdir/ seja o caminho para o código-fonte do PHP, e extname é o nome da extensão PECL. Ajuste de acordo com suas necessidades. Essas instruções também presumem uma familiaridade com o » comando pear. A informação no manual do PEAR para o comando pear também se aplica ao comando pecl.
Para ser útil, uma extensão deve ser compilada, instalada e carregada. Os métodos descritos abaixo descrevem várias instruções de como compilar e instalar as extensões, mas elas não são carregadas automaticamente. Extensões pode ser carregadas adicionando uma diretiva extension no arquivo php.ini ou pelo uso da função dl().
Quando montar módulos do PHP, é importante ter as versões apropriadas das ferramentas requiridas (autoconf, automake, libtool, etc). Veja as » Instruções para leitura anônima do CVS para detalhes sobre as ferramentas e versões necessárias.
Baixando extensões PECL
Existem várias opções para baixar extensões PECL, tais como:
- » http://pecl.php.net/ O web site do PECL contém informação sobre as várias extensões que são disponibilizadas pelo Time de Desenvolvimento do PHP. As informações disponíveis aqui são: ChangeLog, informação de release, requerimentos e outros detalhes similares.
- pecl download extname Extensões PECL que têm releases listadas no web-site do PECL estão disponíveis para download e instalação usando o » comando pecl. Revisões específicas também podem ser especificadas.
-
CVS
A maioria das extensões PECL também residem no CVS. Um visualizado web
pode ser acessado em » http://cvs.php.net/pecl/.
Para baixar direto do CVS, a seguinte seqüência de
comando pode ser usada. Perceba que phpfi é a senha para o
usuário cvsread:
$ cvs -d:pserver:cvsread@cvs.php.net:/repository login
$ cvs -d:pserver:cvsread@cvs.php.net:/repository co pecl/extname
- Downloads do Windows Usuários do Windows podem encontrar binários compilados das extensões PECL baixando a Coleção de módulos PECL da página de » Downloads do PHP, e baixando um » Snapshot do PECL ou uma extensão DLL em » PECL4WIN. Para compilar o PHP no Windows, leia o capítulo apropriado.
PECL para usuários Windows
Como qualquer outra extensão DLL do PHP, mova as DLLs das extensões no diretório extension_dir e inclua elas no arquivo php.ini. Por exemplo:
extension=php_extname.dll
Depois disso, reinicie o servidor web.
Compilando extensões compartilhadas PECL com o comando pecl
PECL torna fácil criar extensões compartilhadas do PHP. Usando o » comando pecl, faça o seguinte:
$ pecl install extname
Isso baixará o código-fonte de extname, compilará e instalará extname.so no seu extension_dir. extname.so pode, então, ser carregado no arquivo php.ini
Por padrão, o comando pecl não instalará pacotes que estão marcados como alpha ou beta. Se nenhum pacote estável estiver disponível, você pode instalar um pacote beta usando o seguinte comando:
$ pecl install extname-beta
Você também pode instalar uma versão específica, usando essa forma:
$ pecl install extname-0.1
Nota:
Depois de habilitada a extensão no php.ini, reiniciar o servidor web é requerido para as modificações funcionarem.
Compilando extensões compartilhadas PECL com phpize
Algumas vezes, usar o instalador pecl não é uma opção. Isso pode acontecer se você estiver atrás de um firewall, ou porque a extensão que você quer instalar não está disponível como um pacote compatível com PECL, por exemplo, extensões ainda sem release no CVS. Se você precisar compilar tal extensão, você pode usar as ferramentas de compilação de baixo nível para realizar a compilação manualmente.
O comando phpize é usado para preparar o ambiente de compilação para uma extensão do PHP. No exemplo seguinte, os fontes para uma extensão estão em um diretório com nome extname:
$ cd extname $ phpize $ ./configure $ make # make install
Uma instalação bem sucedida criará um arquivo extname.so e o colocará no diretório de extensões do PHP. Você precisará ajustar o arquivo php.ini e acidionar uma linha extension=extname.so antes de usar a extensão.
Se o sistema não tiver o comando phpize, e pacotes pré-compilados são usados (como RPM's), certifique-se de instalar a versão devel apropriada do pacote do PHP, uma vez que eles freqüentemente contém o comando phpize assim como os arquivos de cabeçalho para compilar o PHP e suas extensões.
Execute phpize --help para mostra informações de uso adicionais.
Compilando extensões PECL estaticamente no PHP
Você pode decidir que precisa montar uma extensão PECL estaticamente no seu binário do PHP. Para isso, você precisará colocar os fontes da extensão no diretório php-src/ext/ e dizer para o sistema de montagem do PHP para regenerar o script configure.
$ cd /your/phpsrcdir/ext $ pecl download extname $ gzip -d < extname.tgz | tar -xvf - $ mv extname-x.x.x extname
Isso resultará no seguinte diretório:
/your/phpsrcdir/ext/extname
Daqui, faça o PHP reconstruir o script configure e monte o PHP normalmente:
$ cd /your/phpsrcdir
$ rm configure
$ ./buildconf --force
$ ./configure --help
$ ./configure --with-extname --enable-someotherext --with-foobar
$ make
$ make install
Nota: Para executar o script 'buildconf' você precisa de autoconf 2.13 e automake 1.4+ (versões mais novas do autoconf podem funcionar, mas não são suportadas).
Se --enable-extname ou --with-extname são usadas depende da extensão. Tipicamente, uma extensão que não requer bibliotecas externa usa --enable. Para ter certeza, rode o seguinte comando após buildconf:
$ ./configure --help | grep extname
Problemas?
Índice
Leia o FAQ
Alguns problemas são mais comuns que outros. Os mais comuns estão listados no FAQ do PHP, parte desse manual.
Outros problemas
Se você ainda estiver sem solução, alguém na lista de e-mail de instalação do PHP pode te ajudar. Você deve checar o histórico de mensagens antes, no caso de alguém já ter respondido outra pessoa que tenha tido o mesmo problema que você. Os históricos estão disponíveis na página de suporta em » http://www.php.net/support.php. Para se inscrever na lista de e-mail de instalação do PHP, envie um e-mail vazio para » php-install-subscribe@lists.php.net. O endereço da lista de e-mail é » php-install@lists.php.net.
Se você quiser pedir ajuda na lista de e-mail, por favor, tente ser preciso e dar os detalhes necessários sobre seu ambiente (qual sistema operacional, que versão do PHP, qual servidor web, se você está executando PHP com CGI ou módulo de servidor, safe mode, etc...), e, de preferência, código suficiente para permitir que outros reproduzam e testem seu problema.
Relatos de Bug
Se você acha que encontrou um bug (falha) no PHP, por favor, relate. Os desenvolvedores do PHP provavelmente não sabem sobre ele, e, a não ser que você o relate, provavelmente ele não será reparado. Você pode relatar bugs usando o sistema de caça-bugs em » http://bugs.php.net/. Por favor, não mande relatos de bug nas listas de e-mail ou e-mails pessoais. O sistema de bugs também é adequado para o envio de requisição de características (features).
Leia o documento » Como relatar um bug antes de enviar qualquer relato de bug!
Configuração em tempo de execução
Índice
O arquivo de configuração
O arquivo de configuração (php.ini) é lido quando o PHP inicia. Para as versões de módulo de servidor, isso acontece apenas quando o servidor web for inicializado. Para as versões CGI e CLI, isso acontece à cada invocação.
php.ini é procurado nesses lugares (na ordem):
-
Local específico do módulo SAPI (diretiva PHPIniDir no Apache 2, -c opção de linha de comando quando CGI e CLI, parâmetro php_ini no NSAPI, variável de ambiente PHP_INI_PATH no THTTPD)
-
A variável de ambiênte PHPRC. Antes do PHP 5.2.0 isto era conferido depois da chave de registro mencionada abaixo.
-
A partir do PHP 5.2.0, a localização do arquivo php.ini pode ser definida para versões diferentes do PHP. As seguintes chaves do registro são examinadas na ordem: [HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z], [HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y] e [HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x], aonde x, y e z significam a versão maior, menor e release do PHP. Se houver um valor para IniFilePath nestas chaves, então o primeiro encontrado será utilizado para a localização do php.ini (apenas Windows).
-
HKEY_LOCAL_MACHINE\SOFTWARE\PHP\IniFilePath (Local no registro do Windows)
-
Diretório de trabalho atual (exceto CLI)
-
O diretório do servidor web (para módulo SAPI), ou diretório do PHP (caso contrário, no Windows)
-
Diretório do Windows (C:\windows ou C:\winnt) (para o Windows), ou ou a opção de tempo de compilação --with-config-file-path
Se php-SAPI.ini existe (onde SAPI é o SAPI usado, então o nome de arquivo é, por exemplo, php-cli.ini ou php-apache.ini), é usado ao invés do arquivo php.ini. nome SAPI pode ser determinado pela função php_sapi_name().
Nota:
O servidor web Apache muda o diretório para raiz durante a inicialização, causando com que o PHP tente ler o arquivo php.ini da raiz do arquivo de sistema, se ele existir.
As diretivas do arquivo php.ini tratadas por extensões são documentadas respectivamente nas páginas das próprias extensões. A lista de diretivas principais está disponível no apêdice. No entanto, provavelmente nem todas as diretivas do PHP estão documentadas no manual. Para uma lista completa das diretivas disponíveis na sua versão do PHP, por favor leia seu arquivo php.ini. Também há alternativa de baixar a » última versão do arquivo php.ini dos repositórios do CVS, que pode ser de ajuda também.
Exemplo #1 php.ini example
; any text on a line after an unquoted semicolon (;) is ignored
[php] ; section markers (text within square brackets) are also ignored
; Boolean values can be set to either:
; true, on, yes
; or false, off, no, none
register_globals = off
track_errors = yes
; you can enclose strings in double-quotes
include_path = ".:/usr/local/lib/php"
; backslashes are treated the same as any other character
include_path = ".;c:\php\lib"
A partir do PHP 5.1.0, é possível acessar as variáveis .ini dentro dos arquivos .ini. Exemplo:open_basedir = ${open_basedir} ":/new/dir".
Aonde uma configuração deve ser definida
Estes modos determinam quando e aonde uma diretiva do PHP pode ou não pode ser definida, e cada diretiva no manual faz referencia a um destes modos. Por exemplo, algumas definições podem ser feitas em um script PHP usando ini_set(), aonde outros podem requerer php.ini ou httpd.conf.
Por exemplo, a configuração output_buffering é PHP_INI_PERDIR portanto não pode ser definida usando ini_set(). Entretanto a diretiva display_errors é PHP_INI_ALL portanto pode ser definida em qualquer lugar incluindo com ini_set().
| Modo | Significado |
|---|---|
| PHP_INI_USER | A entrada pode ser definida nos scripts do usuário (como com ini_set()) ou no registro do Windows |
| PHP_INI_PERDIR | A entrada pode ser definida no php.ini, .htaccess ou httpd.conf |
| PHP_INI_SYSTEM | A entrada pode ser definida no php.ini ou httpd.conf |
| PHP_INI_ALL | Entrada pode ser definida em qualquer lugar |
Como mudar as configurações
Executando PHP como módulo do Apache
Quando usar o PHP como módulo do Apache, você pode mudar as configurações usando diretivas nos arquivos de configuração do Apache (ex.: httpd.conf e .htaccess). Você precisa de privilégios "AllowOverride Options" ou "AllowOverride All" para isso.
Há vários diretivas do Apache que você pode mudar a configuração do PHP de dentro dos arquivos dos arquivos de configuração do Apache. Para uma lista de quais diretivas são PHP_INI_ALL, PHP_INI_PERDIR, or PHP_INI_SYSTEM, olhe no apêndice Lista de diretivas do arquivo php.ini.
-
php_valuenome valor -
Configura o valor da diretiva especificada. Pode ser usado apenas com diretivas do tipo PHP_INI_ALL e PHP_INI_PERDIR. Para limpar um valor configurado anteriormente, use o valor none.
Nota: Não use
php_valuepara configurar valores booleanos.php_flag(veja abaixo) deve ser usada, ao invés. -
php_flagnome on|off -
Usado para configurar diretivas de configuração booleanas. Pode ser usada apenas com diretivas do tipo PHP_INI_ALL e PHP_INI_PERDIR.
-
php_admin_valuenome valor -
Configura o valor da diretiva especificada. Isso não pode ser usado em arquivos .htaccess. Qualquer tipo diretiva configurada com
php_admin_valuenão pode ser sobrescrita por diretivas .htaccess ou ini_set().. Para limpar um valor configurado anteriormente, use o valor none. -
php_admin_flagnome on|off -
Usado para configura diretiva de configuração booleana. Isso não pode ser usado em arquivos .htaccess. Qualquer tipo diretiva configurada com
php_admin_flagnão pode ser sobrescrita por diretivas .htaccess. Para limpar um valor configurado anteriormente, use o valor none.
Exemplo #1 Exemplo de configuração do Apache
<IfModule mod_php5.c>
php_value include_path ".:/usr/local/lib/php"
php_admin_flag safe_mode on
</IfModule>
<IfModule mod_php4.c>
php_value include_path ".:/usr/local/lib/php"
php_admin_flag safe_mode on
</IfModule>
Constantes PHP não existem fora do PHP. Por exemplo, no arquivo httpd.conf você não pode usar constantes do PHP como E_ALL ou E_NOTICE para configurar a diretiva error_reporting, já que elas não terão significado algum e serão avaliadas como 0. Ao invés, use os valores de bitmask associados. Essas constantes podem ser usados no arquivo php.ini
Mudando configuração do PHP através do registro do Windows
Quando executar o PHP no Windows, os valores de configuração pode ser modificados para cada diretório, usando o registro do Windows. Os valores de configuração são guardados na chave de registro HKLM\SOFTWARE\PHP\Per Directory Values, nas sub-chaves correspondentes aos caminhos dos diretórios. Por exemplo, valores para o diretório c:\inetpub\wwwroot estariam guardadas na chave HKLM\SOFTWARE\PHP\Per Directory Values\c\inetpub\wwwroot. As configurações para o diretório estariam ativos para qualquer script rodando desse diretório ou qualquer subdiretório dele. Os valores na chave devem ter o nome da diretiva de configuração do PHP e um valor string. Constantes do PHP nos valores não são avaliados. Entretanto, apenas valores de configurações modificáveis no PHP_INI_USER podem ser definidos desta maneira, valores PHP_INI_PERDIR não podem.
Outras interfaces para PHP
Independente de como você execute PHP, você pode mudar certos valore durante a execução de seus scripts através ini_set(). Veja a documentação na página ini_set() para mais informações.
Se você estiver interessado na lista completa de configurações no seu sistema com o valores atuais, você pode executar a função phpinfo() , e revisar a página resultante. Você pode também acessar os valores de configurações de diretivas individuais em tempo de execução usando ini_get() ou get_cfg_var().
- Considerações Gerais sobre Instalação
- Instalação em sistemas Unix
- Apache 1.3.x em sistemas Unix
- Apache 2.0 em sistemas Unix
- Lighttpd 1.4 on Unix systems
- Caudium
- Notas relacionadas à fhttpd
- Sun, iPlanet e servidores Netscape no Solaris da Sun
- CGI e instalações de linha de comando
- Notas expecificas da instalação em HP-UX
- Notas de instalação para o OpenBSD
- Dicas de instalação específicas para o Solaris
- Notas de Instalação para o Debian GNU/Linux
- Instalação no Mac OS X
- Instalação em sistemas Windows
- Instalador do PHP para o Windows (PHP 5.1.0 e anterior)
- Instalador para Windows (PHP 5.2 ou posterior)
- Passos para Instalação Manual
- Microsoft IIS / PWS
- Microsoft IIS 5.1 and IIS 6.0
- Microsoft IIS 7.0 and later
- Apache 1.3.x no Microsoft Windows
- Apache 2.0.x no Microsoft Windows
- Servidores Sun, iPlanet e Netscape no Microsoft Windows
- Servidor Sambar no Microsoft Windows
- Xitami no Microsoft Windows
- Compilando a partir dos fontes
- Instalação de extensões no Windows
- Command Line PHP on Microsoft Windows
- Installation on Cloud Computing platforms
- FastCGI Process Manager (FPM)
- Instalação das extensões PECL
- Problemas?
- Configuração em tempo de execução
Referência da Linguagem
Sintaxe Básica
Índice
Escapando o HTML
Quando o PHP interpreta um arquivo, ele procura pelas tags de abertura e fechamento, as quais indicam para o PHP começar e parar de interpretar o código entre elas. Interpretar desta maneira permite ao PHP ser embutido em todos os tipos de documentos, já que tudo, fora o par de tags de abertura e fechamento é ignorado pelo interpretador do PHP. Na maioria das vezes você verá o PHP embutido em documentos HTML como neste exemplo.
<p>Isto vai ser ignorado.</p>
<?php echo 'Enquanto isto vai ser interpretado.'; ?>
<p>Isto também vai ser ignorado.</p>
Você também pode usar estruturas mais avançadas:
Exemplo #1 Escapando de modo avançado
<?php
if ($expression) {
?>
<strong>Isto é verdadeiro.</strong>
<?php
} else {
?>
<strong>Isto é falso.</strong>
<?php
}
?>
Existem quatro diferentes pares de tags de abertura e fechamento que podem ser usados com o PHP. Duas dessas, <?php ?> e <script language="php"> </script>, estão sempre disponíveis. As outras duas são tags curtas e tags no estilo ASP, e podem ser ativadas e desativadas a partir do arquivo de configuração php.ini. Assim, ao passo que algumas pessoas acham as tags curtas e tags no estilo ASP conveniente, elas são menos portáveis, e geralmente não recomendadas.
Nota:
Também note que se você está embutindo o PHP no XML ou XHTML você irá precisar usar as tags <?php ?> para continuar cumprindo com os padrões.
Exemplo #2 Abrindo e Fechando as Tags do PHP
1. <?php echo 'se você quer servir documentos XHTML ou XML, faça assim'; ?>
2. <script language="php">
echo 'alguns editores (como o FrontPage) não
gostam de instruções de processamento';
</script>
3. <? echo 'esta é a mais simples, uma instrução de processamento SGML'; ?>
<?= expressão ?> Isto é um atalho para "<? echo expressão ?>"
4. <% echo 'Você pode opcionalmente usar tags no estilo ASP'; %>
<%= $variavel; # Isto é um atalho para "<% echo . . ." %>
Enquanto as tags vistas nos exemplos um e dois estão ambas sempre disponíveis, o exemplo um é mais comumente usado, e recomendado, das duas.
Tags curtas (exemplo três) estão disponíveis apenas quando são ativadas pela configuração short_open_tag no arquivo php.ini ou se o PHP foi configurado com a opção --enable-short-tags .
Tags no estilo ASP (exemplo quatro estão disponíveis apenas quando elas estão ativadas atráves da diretiva de configuração asp_tags no arquivo php.ini.
Nota:
O uso de tags curtas deve ser evitado ao desenvolver aplicações ou bibliotecas que serão redistribuídas, ou serão usadas em servidores PHP que não estão sobre o seu controle, porque as tags curtas podem não ser suportadas no servidor em questão. Para código portável, redistribuível, tenha certeza de não usar tags curtas.
Separação de instruções
Como no C ou Perl, o PHP requer que as instruções sejam terminadas com um ponto-e-vírgula ao final de cada comando. A tag de fechamento de um bloco de código PHP automaticamente implica em um ponto-e-vírgula; você não precisa ter um ponto-e-vírgula terminando a última linha de um bloco PHP. A tag de fechamento irá incluir uma nova linha logo após, se estiver presente.
<?php
echo 'Isto é um teste';
?>
<?php echo 'Isto é um teste' ?>
<?php echo 'Nós omitimos a última tag de fechamento';
Nota:
A tag de fechamento de um bloco PHP ao final de um arquivo é opcional, e em alguns casos omiti-la é útil ao usar include() ou require(), assim espaço em branco indesejado não irá aparecer ao final dos arquivos, e você ainda será capaz de adicionar cabeçalhos a resposta após. Também é útil se você usar output buffering, e você não quer ter adicionado um espaço em branco ao final das partes geradas por arquivos incluídos.
Comentários
O PHP suporta comentários no estilo 'C', 'C++' e shell do Unix shell (estilo Perl). Por exemplo:
<?php
echo 'Isto é um teste'; // Estilo de comentário de uma linha em c++
/* Este é um comentário de múltiplas linhas
ainda outra linha de comentário */
echo 'Isto é ainda outro teste';
echo 'Um teste final'; # Este é um comentário de uma linha no estilo shell
?>
Os comentários de estilo "uma linha" apenas comentam até o final da linha ou do bloco PHP de código corrente, o que chegar primeiro. Isto significa que o código HTML após // ... ?> ou # ... ?> SERÁ exibido: ?> Interrompe o modo PHP e retorna para o modo HTML, e // ou # não podem influenciar isto. Se a diretiva de configuração asp_tags estiver ativa, ela funciona da mesma maneira que // %> e # %>. Entretando, a tag </script> não interrompe o modo PHP em um comentário de uma linha.
<h1>Isto é um <?php # echo 'simples';?> exemplo.</h1>
<p>O cabeçalho acima irá dizer 'Isto é um exemplo'.</p>
Comentários no estilo 'C' termina ao primeiro */ encontrado. Tenha certeza de não aninhar comentários no estilo 'C'. É fácil fazer este engano se você esta tentando comentar grandes blocos de código.
<?php
/*
echo 'Isto é um teste'; /* Este comentário irá causar um problema */
*/
?>
Tipos
Índice
- Introdução
- Booleanos
- Inteiros
- Números de ponto flutuante
- Strings
- Arrays
- Objects
- Resource
- NULL
- Pseudo-tipos e variáveis utilizados nesta documentação
- Manipulação de tipos
Introdução
O PHP suporta oito tipos primitivos.
São quatro tipos básicos:
Dois tipos compostos:
E finalmente dois tipos especiais:
Este manual também introduz alguns pseudo-tipos por razões de legibilidade:
E a pseudo-variável $....
Algumas referências para o tipo "double" podem aparecer no manual. Considere o tipo double como sendo o float; os dois nomes existem por razões históricas.
O tipo de uma variável geralmente não é definido pelo programador: isto é decidido em tempo de execução pelo PHP, dependendo do contexto na qual a variável é usada.
Nota: Para checar o tipo e valor de uma expressão, utilize a função var_dump().
Para ter uma representação legível de um tipo para debugar, use a função gettype(). Para verificar por um certo tipo, não use gettype(), mas sim as funções is_tipo. Vejamos alguns exemplos:
<?php
$a_bool = TRUE; // um booleano
$a_str = "foo"; // uma string
$a_str2 = 'foo'; // uma string
$an_int = 12; // um inteiro
echo gettype($a_bool); // mostra: boolean
echo gettype($a_str); // mostra: string
// Se ele é um inteiro, incrementa-o com quatro
if (is_int($an_int)) {
$an_int += 4;
}
// Se $bool é uma string, mostre-a
// (não imprime nada)
if (is_string($a_bool)) {
echo "String: $a_bool";
}
?>
Para forçar a conversão de uma variável para um certo tipo, você pode converter (cast) a variável ou usar a função settype() nela.
Note que uma variável pode ser avaliada com valores diferentes em certas situações, dependendo de qual tipo ela é no momento. Para mais informações, veja a seção Manipulação de tipos. A tabela de conversão de tipos também pode ser útil, como mostra exemplos de comparações de vários tipos.
Booleanos
Este é o tipo mais simples. Um booleano expressa um valor verdade. Ele pode ser TRUE ou FALSE.
Nota: O tipo booleano foi introduzido no PHP 4.
Sintaxe
Para especificar um literal booleano, use as palavras-chave TRUE ou FALSE. Ambas são case-insensitive.
<?php
$foo = True; // atribui o valor True para $foo
?>
Tipicamente você pode utilizar algum tipo de operador que retorne um valor booleano, e passá-lo para uma estrutura de controle.
<?php
// == É um operador que testa
// igualdade e retorna um booleano.
if ($action == "mostrar_versao") {
echo "A versão é 1.23";
}
// isto não é necessário ...
if ($exibir_separadores == TRUE) {
echo "<hr>\n";
}
// ... porque você pode simplesmente escrever isso:
if ($exibir_separadores) {
echo "<hr>\n";
}
?>
Convertendo para booleano
Para converter explicitamente um valor para booleano, utilize-se dos modificadores (bool) ou (boolean). Entretanto, na maioria dos casos, você não precisa utilizar o modificador, desde que qualquer valor será convertido automaticamente se um operador, função ou estrutura de controle requerer um argumento booleano.
Veja também Manipulação de tipos.
Ao converter para booleano, os seguintes valores são considerados FALSE:
- o próprio booleano FALSE
- o inteiro 0 (zero)
- o ponto flutuante 0.0 (zero)
- uma string vazia e a string "0"
- um array sem elementos
- um objeto sem elementos membros (somente PHP 4)
- o tipo especial NULL (incluindo variáveis não definidas)
- o objeto SimpleXML criado de tags vazias
-1 é considerado TRUE, como qualquer valor não zero (negativos ou positivos)!
<?php
var_dump((bool) ""); // bool(false)
var_dump((bool) 1); // bool(true)
var_dump((bool) -2); // bool(true)
var_dump((bool) "foo"); // bool(true)
var_dump((bool) 2.3e5); // bool(true)
var_dump((bool) array(12)); // bool(true)
var_dump((bool) array()); // bool(false)
var_dump((bool) "false"); // bool(true)
?>
Inteiros
Um inteiro é um número do conjunto Z = {..., -2, -1, 0, 1, 2, ...}.
Veja também: Inteiros de tamanho arbitrário / GMP, Números de ponto flutuante e Precisão arbitrária / BCMath.
Sintaxe
Inteiros podem ser especificados em notação decimal (base 10), hexadecimal (base 16) ou octal (base 8), opcionalmente precedido de sinal (- ou +).
Para usar a notação octal, você precisa preceder o número com um 0 (zero). Para utilizar a notação hexadecimal, preceda número com 0x.
Exemplo #1 Literais inteiras
<?php
$a = 1234; // número decimal
$a = -123; // um número negativo
$a = 0123; // número octal (equivalente a 83 em decimal)
$a = 0x1A; // número hexadecimal (equivalente a 26 em decimal)
?>
decimal : [1-9][0-9]*
| 0
hexadecimal : 0[xX][0-9a-fA-F]+
octal : 0[0-7]+
integer : [+-]?decimal
| [+-]?hexadecimal
| [+-]?octal
Se um dígito inválido é passado para inteiro octal (i.e. 8 ou 9), o resto do número é ignorado.
Exemplo #2 Octal weirdness
<?php
var_dump(01090); // 010 octal = 8 decimal
?>
Overflow de inteiros
Se você especifica um número além dos limites do tipo inteiro, ele será interpretado como um ponto flutuante. Assim, uma operação que resulte em um número além dos limites do tipo inteiro, um ponto flutuante será retornado.
<?php
$ numero_grande = 2147483647;
var_dump($numero_grande);
// saida: int(2147483647)
$numero_grande = 2147483648;
var_dump($numero_grande);
// saida: float(2147483648)
// é válido também para inteiros hexadecimais entre 2^31 e 2^32-1:
var_dump( 0xffffffff );
// output: float(4294967295)
// porém não é válido para hexadecimais com valores acima de 2^32-1:
var_dump( 0x100000000 );
// output: int(2147483647)
$milhao = 1000000;
$numero_grande = 50000 * $milhao;
var_dump($numero_grande);
// saida: float(50000000000)
?>
Infelizmente, há um bug no PHP que faz que ele nem sempre trabalhe corretamente quando há números negativos envolvidos. Por exemplo, quando você faz -50000 * $milhao, o resultado será -429496728. Entretanto, quando ambos os operadores são positivos, isso não ocorre.
Isto foi resolvido no PHP 4.1.0.
Não há operador de divisão inteira no PHP. 1/2 retorna o ponto flutuante 0.5. Você pode moldar (cast) o valor para inteiro para sempre truncar o número, ou você pode usar a função round().
<?php
var_dump(25/7); // float(3.5714285714286)
var_dump((int) (25/7)); // int(3)
var_dump(round(25/7)); // float(4)
?>
Convertendo para inteiro
Para converter explicitamente um valor para inteiro, utilize-se dos modificadores (int) ou (integer). Entretanto, na maioria dos casos, você não precisa utilizar o modificador, desde que qualquer valor será automaticamente convertido se um operador, função ou estrutura de controle requerer um argumento inteiro. Você também pode converter o valor de um inteiro com a função intval().
Veja também Manipulação de tipos.
de booleanos
FALSE será retornado como 0 (zero), e TRUE como 1 (um).
De números de ponto flutuante
Quando convertendo de números de ponto flutuante para inteiros, o número será truncado.
Se o número convertido estiver além dos limites de um inteiro (usualmente +/- 2.15e+9 = 2^31), o resultado é indefinido, mesmo porque o ponto flutuante não tem a mesma precisão para fornecer um resultado inteiro exato. Não se preocupe, pois nenhum aviso será emitido neste caso!
Nunca modifique uma fração desconhecida para inteiro, porque isto pode fornecer resultados inesperados as vezes.
<?php
echo (int) ( (0.1+0.7) * 10 ); // imprime 7!
?>
De strings
De outros tipos
O comportamento da conversão de um inteiro é indefinido de outros tipos. Atualmente, o comportamento é o mesmo como se primeiro o valor fosse convertido para booleano. Entretanto, não confie neste comportamento, pois ele pode mudar sem aviso.
Números de ponto flutuante
Números de ponto flutuante (também conhecidos como "floats", "doubles" ou "números reais") podem ser especificados utilizando qualquer uma das seguintes sintaxes:
<?php
$a = 1.234;
$b = 1.2e3;
$c = 7E-10;
?>
LNUM [0-9]+
DNUM ([0-9]*[\.]{LNUM}) | ({LNUM}[\.][0-9]*)
EXPONENT_DNUM ( ({LNUM} | {DNUM}) [eE][+-]? {LNUM})
Precisão de números de ponto flutuante
É típico que frações simples como 0.1 ou 0.7 não podem ser convertidos em sua representação binária interna sem uma pequena perda de precisão. Isto pode causar erros confusos: por exemplo, floor((0.1+0.7)*10) irá retornar 7 em vez do esperado 8, como resultado da representação interna realmente ser algo como 7.9999999999....
Isto está relacionado ao fato de que é impossível expressar, exatamente, algumas frações em notação decimal com um número finito de dígitos. Por exemplo, 1/3 na forma decimal se torna 0.3333333. . ..
Então, nunca confie em resultados com números de ponto flutuante até a última casa e nunca compare números de ponto flutuante em igualdades. Se você realmente precisar de alta precisão, você pode utilizar as funções matemáticas de precisão arbitrária ou as funções relacionadas ao gmp.
Convertendo para float
Para informações sobre a conversão de strings para floats, veja a seção entitulada Conversão de Strings para números. Para valores de outros tipos, o valor é primeiro convertido para inteiro e então para float. Veja a seção Convertendo para inteiros para mais informações. No PHP 5, um aviso é emitido se você tentar converter um objeto para float.
Strings
Uma string é uma série de caracteres. Antes do PHP 6, um caracter é o mesmo que um byte. Ou seja, há exatamente 256 caracteres diferentes possíveis. Isto implica que o PHP não tem suporte nativo ao Unicode. Veja utf8_encode() e utf8_decode() para algumas funcionalidades básicas de Unicode.
Nota: Não é problema para uma string ser bastante longa. PHP não impõe limite de tamanho de uma string; o único limite é o de memória disponível do computador no qual o PHP está sendo executado.
Sintaxe
Uma string literal pode ser especificada de quatro formas diferentes.
- apóstrofo
- aspas
- sintaxe heredoc
- sintaxe nowdoc (desde o PHP 5.3.0)
Apóstrofos
A maneira mais simples para especificar uma string é delimitá-la entre apóstrofos (o caracter ').
Para especificar um apóstrofo. você precisará "escapá-la" com uma contra barra (\), como em muitas outras linguagens. Se uma contra barra precisa ocorrer antes de um apóstrofo ou no final da string, você precisa duplicá-la. Note que se você tentar escapar qualquer outro caracter, a contra barra também será impressa! Então geralmente não é necessário escapar a própria contra barra. Para especificar um apóstrofo, use escape (\). Para especificar uma barra invertida antes de uma apóstrofo, ou no final da string, use-o duas vezes (\\). Note que tentando usar escape qualquer outro caractere imprimirá a barra invertida também.
Nota: Diferentemente das duas outras sintaxes, variables e seqüências de escape para caracteres especiais não serão substituídas quando elas ocorrerem dentro de strings delimitadas por apóstrofes.
<?php
echo 'isto é uma string comum';
echo 'Você pode incluir novas linhas em strings,
dessa maneira que estará
tudo bem';
// Imprime: Arnold disse uma vez: "I'll be back"
echo 'Arnold disse uma vez: "I\'ll be back"';
// Imprime: Você tem certeza em apagar C:\*.*?
echo 'Você tem certeza em apagar C:\\*.*?';
// Imprime: Você tem certeza em apagar C:\*.*?
echo 'Você tem certeza em apagar C:\*.*?';
// Imprime: Isto não será substituido: \n uma nova linha
echo 'Isto não será substituido: \n uma nova linha';
// Imprime: Variaveis $também não $expandem
echo 'Variaveis $também não $expandem';
?>
Aspas
Se a string é delimitada entre aspas ("), o PHP irá interpretar mais seqüências de escape para caracteres especiais:
| Seqüência | Significado |
|---|---|
| \n | fim de linha (linefeed ou LF ou 0x0A (10) em ASCII) |
| \r | retorno de carro (carriage return ou CR ou 0x0D (13) em ASCII) |
| \t | TAB horizontal (HT ou 0x09 (9) em ASCII) |
| \v | TAB vertical (VT ou 0x0B (11) em ASCII) (desde o PHP 5.2.5) |
| \f | form feed (FF ou 0x0C (12) em ASCII) (desde o PHP 5.2.5) |
| \\ | contra barra ou barra invertida |
| \$ | sinal de cifrão |
| \" | aspas |
| \[0-7]{1,3} | a seqüência de caracteres batendo a expressão regular dos caracteres em notação octal |
| \x[0-9A-Fa-f]{1,2} | a seqüência de caracteres batendo a expressão regular de um caracter em notação hexadecimal |
Como em uma string entre apóstrofos, usar escape em qualquer outro caractere resultará em uma barra invertida sendo mostrada também. Antes do PHP 5.1.1, a barra invertida em \{$var} não era mostrada.
O mais importante recurso de strings delimitadas por aspas está no fato de que nome de variáveis serão substituídos. Veja interpretação de strings para detalhes.
Heredoc
Uma terceira maneira para delimitar strings é a sintaxe heredoc: <<<. Após este operador, um identificador é fornecido, e após, um newline. Então vem a própria string, e então o mesmo identificador para fechar a string.
O identificador de fechamento precisa começar na primeira coluna da linha. Além, o identificador precisa seguir as mesmas regras de nomeação que qualquer outro rótulo no PHP: só pode conter caracteres alfanuméricos e sublinhados, e precisa começar com um caracter não numérico ou sublinhado.
É muito importante verificar que a linha do identificador de fechamento não contenha nenhum outro caracter, exceto, possivelmente um ponto e vírgula (;). O que significa que o identificador não pode ser indentado, e que não pode haver nenhum espaço ou tabulações antes ou depois do ponto e vírgula. É também importante perceber que o primeiro caracter antes do identificador de fechamento precisa ser um caracter de nova linha como esperada por seu sistema operacional. Por exemplo, \n em sistemas UNIX, incluindo Mac OS X. O delimitador de fechamento (possivelmente seguido por um ponto e vírgula) precisa também ser seguido por newline.
Se essa regra for quebrada e o identificador de fechamento não estiver perfeito, então ele não será considerado como identificador de fechamento e o PHP irá continuar procurando por um. Se, neste caso, um identificador de fechamento apropriado não for encontrado antes do final do arquivo atual, um erro de interpretação (parse) será lançado na linha final do script.
Heredocs não podem ser usados para inicializar membros de classes. Use ao invés, nowdocs.
Exemplo #1 Exemplo inválido
<?php
class foo {
public $bar = <<<EOT
bar
EOT;
}
?>
Textos heredoc se comportam como string delimitadas por aspas, com apenas uma diferença. Você não precisa escapar apóstrofos e aspas em seus heredocs, mas você ainda pode continuar utilizando os códigos de escape listados acima. Variáveis são substituídas, mas o mesmo cuidado precisa ser tomado quando expressando variáveis complexas dentro de heredocs assim como nas strings.
Exemplo #2 Exemplo de delimitação de strings heredoc
<?php
$str = <<<EOD
Exemplo de uma string
distribuída em várias linhas
utilizando a sintaxe heredoc.
EOD;
/* Exemplo mais complexo, com variáveis */
class foo
{
var $foo;
var $bar;
function foo()
{
$this->foo = 'Foo';
$this->bar = array('Bar1', 'Bar2', 'Bar3');
}
}
$foo = new foo();
$name = 'Meu nome';
echo <<<EOT
Meu nome é "$name". Eu estou imprimindo $foo->foo.
Agora, eu estou imprimindo {$foo->bar[1]}.
Isto deve imprimir um 'A' maiúsculo: \x41
EOT;
?>
O exemplo acima irá imprimir:
My name is "MyName". I am printing some Foo. Now, I am printing some Bar2. This should print a capital 'A': A
É também possível usar sintaxe Heredoc para passar dados para argumento de funções:
Exemplo #3 Exemplo de Heredoc em argumentos
<?php
var_dump(array(<<<EOD
foobar!
EOD
));
?>
Nota:
O suporte a heredoc foi acrescentado no PHP 4.
Nowdoc
Nowdocs são para apóstrofos o que heredocs são para aspas dupla em strings. Um nowdoc é especificado similarmente a um heredoc, mas nenhuma análise é feito dentro de um nowdoc. A construção é ideal para colocar códigos PHP ou outros blocos grandes de texto sem a necessidade de usar escapes. Ele compartilha algumas características em comum com a construção SGML <![CDATA[ ]]>, assim é declarado um bloco de texto onde nada será analisado.
Um nowdoc é identificado com a mesma seqüência <<< usada para heredocs, mas o identificador precisa ficar entre aspas simples, e.g. <<<'EOT'. Todas as regras para identificadores heredoc se aplicam para identificadores nowdoc, especialmente aqueles considerando o identificador de fechamento.
Exemplo #4 Exemplo de string em Nowdoc
<?php
$str = <<<'EOD'
Example of string
spanning multiple lines
using nowdoc syntax.
EOD;
/* Exemplo mais complexo, com variáveis. */
class foo
{
public $foo;
public $bar;
function foo()
{
$this->foo = 'Foo';
$this->bar = array('Bar1', 'Bar2', 'Bar3');
}
}
$foo = new foo();
$name = 'MyName';
echo <<<'EOT'
My name is "$name". I am printing some $foo->foo.
Now, I am printing some {$foo->bar[1]}.
This should not print a capital 'A': \x41
EOT;
?>
O exemplo acima irá imprimir:
My name is "$name". I am printing some $foo->foo.
Now, I am printing some {$foo->bar[1]}.
This should not print a capital 'A': \x41Nota:
Diferente de heredocs, nowdocs pode ser usado no contexto de dado estático. O exemplo típico é inicializando membros de classes ou constantes:
Exemplo #5 Exemplo com dado estático
<?php
class foo {
public $bar = <<<'EOT'
bar
EOT;
}
?>
Nota:
Suporte a Nowdoc foi adicionado no PHP 5.3.0.
Interpretação de variáveis
Quando uma string é especificada dentro de aspas ou heredoc, variáveis são interpretadas dentro delas.
Há dois tipos de sintaxe: um simples e um complexo . A sintaxe simples é a mais comum e conveniente, provendo uma maneira de interpretar uma variável, um valor de array ou uma propriedade de object em uma string com o menor esforço.
A sintaxe completa foi introduzida no PHP 4, e pode ser reconhecida por chaves ({}) envolvendo a expressão.
Sintaxe simples
Se um sinal de cifrão ($) é encontrado, o interpretador tentará obter tantos identificadores quanto possíveis para formar um nome de variável válido. Envolva o nome da variável com chaves se você deseja explicitamente especificar o fim do nome.
<?php
$cerveja = 'Heineken';
echo "O sabor das '$cerveja's é otimo"; // funciona, "'" é um caracter inválido para nome de variáveis
echo "Ele bebeu algumas $cervejas"; // não funciona, 's' é um caracter válido para nome de variáveis
echo "Ele bebeu algumas ${cerveja}s"; // funciona
echo "Ele bebeu algumas {$cerveja}s"; // funciona
?>
Similarmente, um índice de array ou uma propriedade de object pode ser analisado. Com índices de array, o fechamento de colchete (]) marca o final do índice. A mesma regra aplica-se para propriedade de objetos como para simples variáveis.
<?php
// Esses exemplos são específicos para utilização de arrays dentro de strings
// Quando fora de strings, sempre delimite suas chaves de array strings
// e não use {colchetes}.
// Mostra todos os erros
error_reporting(E_ALL);
$fruits = array('morango' => 'vermelho', 'banana' => 'amarelo');
// Funciona, mas note que funciona de maneira diferente fora dos delimitadores de strings
echo "A banana é $fruits[banana].";
// Funciona
echo "A banana é {$fruits['banana']}.";
// Funciona, mas o PHP procura por uma constante chamada 'banana' antes,
// como descrito a abaixo.
echo "A banana é {$fruits[banana]}.";
// Nao funciona, use colchetes. Isto lanca um parse error.
echo "A banana é $fruits['banana'].";
// Funciona
echo "A banana é " . $fruits['banana'] . ".";
// Funciona
echo "Este quadrado tem $square->width metros de lado.";
// Nao funciona. Para uma solução, veja a sintaxe complexa.
echo "Este quadrado tem $square->width00 centímetros de lado.";
?>
Para qualquer coisa mais complexa, você precisa utilizar a sintaxe complexa.
Sintaxe complexa (chaves)
Isto não é chamado sintaxe complexa porque a sintaxe em si é complexa, mas porque você pode incluir expressões complexas.
De fato, qualquer valor no namespace pode ser incluido em uma string com esta sintaxe. Simplesmente escreva a expressão da mesma forma como apareceria fora da string, e então coloque-o em { e }. Desde que { não pode escapado, esta sintaxe somente mostrará ser reconhecida quando o $ imediatamente seguir o {. Use {\$ para ter um literal {$. Alguns exemplos para fazê-lo claro:
<?php
// Mostra todos os erros
error_reporting(E_ALL);
$bom = 'fantastico';
// Não funciona, imprimindo: Isto é { fantastico}
echo "Isto é { $bom}";
// Funciona, imprimindo: Isto é fantástico
echo "Isto é {$bom}";
echo "Isto é ${bom}";
// Funciona
echo "Este quadrado tem {$square->width}00 centímetros de lado.";
// Funciona
echo "Isto funciona: {$arr[4][3]}";
// Isto está errado pela mesma razão que $foo[bar] é errado fora de uma string.
// Em outras palavras, isto ainda funciona MAS porque o PHP primeiro procura pro uma
// constante nomeada foo; um erro do tipo E_NOTICE (undefined constant) será
// disparado.
echo "Isto é errado: {$arr[foo][3]}";
// Funciona. Quanto mexendo com arrays multi dimensionais, sempre use colchetes em volta dos arrays
// quando detro de strings
echo "Isto funciona: {$arr['foo'][3]}";
// Funciona
echo "Isto funciona: " . $arr['foo'][3];
echo "Isto funciona também {$obj->values[3]->name}";
echo "Este é o valor da variável chamada $name: {${$name}}";
echo "Este é o valor da variável usando o valor retornado da getName(): {${getName()}}";
echo "Este é o valor da variável usando o valor retornado da \$object->getName(): {${$object->getName()}}";
?>
Nota:
Chamada de funções e métodos dentro de {$} funcionam desde o PHP 5.
Acesso e modificação de caracteres da string
Caracteres nas strings podem ser acessados e modificados apenas especificando o deslocamento baseado em zero do caracter desejado depois da string dentro de colchetes, como um array, $str[42] então pense na string como um array de caracteres.
Nota: Strings podem também ser acessada usando colchetes, como $str{42} para o mesmo propósito. Contudo, esta sintaxe está obsoleto a partir do PHP 6. Use colchetes ao invés.
Escrevendo em um offset fora do intervalo, preenche a string com espaços. Tipos diferentes de inteiro são convertidos para inteiro. Tipo ilegal de offset emite E_NOTICE. Offset negativo emite E_NOTICE na escrita mas na leitura uma string vazia. Somente o primeiro caractere de uma string atribuída é usada. Atribuindo uma string vazia designa NUL byte.
Exemplo #6 Alguns exemplos com strings
<?php
// Pega o primeiro caracter da string
$str = 'Isto é um teste.';
$first = $str[0];
// Pega o terceiro caracter da string
$third = $str[2];
// Pega o último caracter da string
$str = 'Isto ainda é um teste.';
$last = $str[strlen($str)-1];
// Modifica o ultimo caracter da string
$str = 'Olhe o mal';
$str[strlen($str)-1] = 'r';
?>
Nota:
Acessando variáveis de outros tipos usando [] ou {} silenciosamente retorna NULL.
Funções e operadores úteis
Strings podem ser concatenados utilizando o operador '.' (ponto). Note que o operador '+' (adição) não funciona para isso. Veja operadores de string para mais informações.
Há bastante funções úteis para modificação de strings.
Veja a seção de funções de string para funções gerais e funções de expressões regulares ou a funções para expressão regular compatível com Perl para busca avançada & funcionalidade para substituições.
Há também funções para strings URL e funções para criptografia e descriptografia de strings (mcrypt e mhash).
Finalmente, veja também as funções de tipos de caracteres.
Convertendo para strings
Você pode converter um valor para string utilizando o molde (string), ou a função strval(). Conversão para string é automaticamente realizada no escopo de uma expressão para você onde uma string é necessária. Isto acontece quando você usa as funções echo() ou print(), ou quando você compara o valor de uma variável com uma string. Lendo as seções do manual sobre Tipos e Conversão de Tipos tornará o que se segue um pouco mais claro. Veja também a função settype().
O valor boolean TRUE é convertido para a string "1", o valor FALSE é representado como "" (uma string vazia). Desta forma, você pode converter livremente entre os tipos booleano e string.
Um integer ou um float é convertido para a representação string do número em dígitos arábicos (incluindo a parte expoente para um float). Números de ponto flutuante podem ser convertidos usando a notação exponencial (4.1E+6).
Nota:
O caractere de ponto decimal é definido no locale do script (categoria LC_NUMERIC). Veja setlocale().
Arrays são sempre convertidos para uma string "Array"; por causa disso echo() e print() não podem por eles mesmo mostrar o conteúdo de um array. Para ver um elemento, use a construção como echo $arr['foo']. Veja abaixo dicas de como exportar/ver todo seu conteúdo.
Objects no PHP 4 são sempre convertidos para a string "Object". Se você quiser imprimir os valores das variáveis membro de um object por razão de debug, leia os parágrafos abaixo. Se você quiser encontrar o nome da classe do qual o objeto é uma instância, use get_class(). No PHP 5, o método __toString é usado se aplicável.
Resources são sempre convertidos para strings na estrutura "Resource id #1" onde 1 é o número único do resource assimilado pelo PHP na execução. Se você quiser obter o tipo do recurso, utilize get_resource_type().
NULL é sempre convertido para uma string vazia.
Como você viu acima, imprimir arrays, objetos ou recursos não fornece qualquer informação útil sobre os seus próprios valores. Veja as funções print_r() e var_dump() para melhores maneiras de imprimir valores para debug.
Você também pode converter valores PHP para strings para armazená-los permanentemente. Este método é chamado serialização, e pode ser feito com a função serialize(). Você também pode serializar valores PHP para estruturas XML , se você ativou o suporte a WDDX na configuração do seu PHP.
Conversão de strings para números
Quando uma string é avaliada como um valor numérico, o valor resultante e o tipo é determinado como segue.
A string será avaliada como um ponto flutuante se conter qualquer um dos caracteres '.', 'e', ou 'E'. Em outros casos, ela será avaliada como um inteiro.
O valor é obtido da porção inicial da string. Se a string começa com dados numéricos válidos, esse será o valor utilizado. Em outro caso, o valor será 0 (zero). Dados numéricos válidos são: um sinal opcional, seguido por um ou mais dígitos (opcionalmente contendo um ponto decimal), seguido de um expoente, também opcional. O expoente é um 'e' ou 'E' seguido de um ou mais dígitos.
<?php
$foo = 1 + "10.5"; // $foo é float (11.5)
$foo = 1 + "-1.3e3"; // $foo é float (-1299)
$foo = 1 + "bob-1.3e3"; // $foo é integer (1)
$foo = 1 + "bob3"; // $foo é integer (1)
$foo = 1 + "10 Small Pigs"; // $foo é integer (11)
$foo = 4 + "10.2 Little Piggies"; // $foo é float (14.2)
$foo = "10.0 pigs " + 1; // $foo é float (11)
$foo = "10.0 pigs " + 1.0; // $foo é float (11)
?>
Para mais informações sobre esta conversão, veja página do manual UNIX de strtod(3).
Para testar qualquer exemplo nesta seção, copie e cole os exemplos e insira a seguinte linha para ver como funciona:
<?php
echo "\$foo==$foo; tipo " . gettype ($foo) . "<br />\n";
?>
Não espere obter o código de um caracter por convertê-lo para inteiro, como é feito em C. Use as funções ord() e chr() para converter entre código de caracteres e os próprios caracteres.
Arrays
Um array no PHP é atualmente um mapa ordenado. Um mapa é um tipo que relaciona valores para chaves. Este tipo é otimizado de várias maneiras, então você pode usá-lo como um array real, ou uma lista (vetor), hashtable (que é uma implementação de mapa), dicionário, coleção, pilha, fila e provavelmente mais. Como você pode ter outro array PHP como um valor, você pode facilmente simular árvores.
A explicação dessas estruturas estão além do escopo desse manual, mas você pode encontrar exemplos para cada uma dessas estruturas a seguir. Para mais informações sobre estruturas, refira-se a literatura externa sobre esses tópicos.
Sintaxe
Especificando com array()
Um array pode ser criado com o construtor de linguagem array(). Ele pega um certo número de pares separados por vírgula chave => valor .
array( chave => valor , ... ) // chave pode ser tanto string ou um integer // valor pode ser qualquer coisa
<?php
$arr = array("foo" => "bar", 12 => true);
echo $arr["foo"]; // bar
echo $arr[12]; // 1
?>
A chave pode ser tanto um integer ou uma string. Se a chave é uma representação padrão de um integer, ele será interpretado assim (por exemplo, "8" será interpretado como 8, enquanto "08" será interpretado como "08"). Flotas em key são truncados para integer. Não há diferença entre arrais indexados e associativos em PHP, apenas um tipo de array, que pode ter índices inteiros ou string.
O valor pode ser qualquer tipo PHP:
<?php
$arr = array("somearray" => array(6 => 5, 13 => 9, "a" => 42));
echo $arr["somearray"][6]; // 5
echo $arr["somearray"][13]; // 9
echo $arr["somearray"]["a"]; // 42
?>
Se omitir a chave quando fornece um novo item, o maior índice inteiro é obtido, e a nova chave será esse máximo + 1. Se você especificar uma chave que já possui um valor assimilada a ela, então o valor é sobrescrito.
<?php
// Esse array é como ...
array(5 => 43, 32, 56, "b" => 12);
// ... este array
array(5 => 43, 6 => 32, 7 => 56, "b" => 12);
?>
A partir do PHP 4.3.0, o comportamento da geração de índice descrito acima foi modificado. Agora, se você aumentar um array em que o maior índice atual for negativo, então a próxima chave criada será zero (0). Antes, o novo índice seria o maior índice existente mais 1, do mesmo jeito que os índices positivos.
Utilizar TRUE como chave será interpretado como o integer 1 na chave. Utilizando FALSE como chave será avaliado como o integer 0. Usar NULL como chave é interpretado como uma string vazia. Usar uma string vazia como chave irá criar (ou sobrescerver) uma chave com uma string vazia e seu valor, e isto não é o mesmo que usar colchetes vazios.
Você não pode usar arrays ou objetos como chaves. Fazendo isso resultará em um alerta: Illegal offset type.
Criando/modificando com a sintaxe de colchetes
Você pode também modificar um array existente explicitamente assimilando valores nele.
Isto é feito apenas assimilando valores para o array enquanto especificando a chave em colchetes. Você pode omitir a chave, colocando um par vazio de colchetes ("[]").
$arr[chave] = valor; $arr[] = valor; // chave tanto um integer ou string // valor pode ser qualquer coisaSe $arr não existir ainda, ele será criado. Então isto é um meio alternativo para especificar um array. Para mudar um certo valor, apenas assimile um novo valor para um elemento especificado por sua chave. Se você quiser remover um par chave/valor, você precisa aplicar unset() nele.
<?php
$arr = array(5 => 1, 12 => 2);
$arr[] = 56; // Isto é o mesmo que $arr[13] = 56;
// nesse ponto do script
$arr["x"] = 42; // Isto acrescenta um novo elemento
// para o array com a chave "x"
unset($arr[5]); // Isto remove um elemento do array
unset($arr); // E isto apaga todo o array
?>
Nota:
Como mencionado acima, não informar a chave dentro dos colchetes, então o maior índice inteiro é obtido, e a nova chave será esse máximo + 1. Se nenhum índice inteiro existir ainda, a chave será 0 (zero). Se você especificar uma chave que já possui um valor assimilada a ela, então o valor é sobrescrito.
AvisoA partir do PHP 4.3.0, o comportamento da geração de índice descrito acima foi modificado. Agora, se você aumentar um array em que o maior índice atual for negativo, então a próxima chave criada será zero (0). Antes, o novo índice seria o maior índice existente mais 1, do mesmo jeito que os índices positivos.
Note que a chave inteira maior utilizada para isso não precisa necessariamente existir no array. Ele pode ter existido no array desde a última vez que o array foi indexado. Veja o seguinte exemplo:
<?php
// Criando um array normal
$array = array(1, 2, 3, 4, 5);
print_r($array);
// Agora apagando todos os itens, mas deixando o array intacto:
foreach ($array as $i => $value) {
unset($array[$i]);
}
print_r($array);
// Acrescentando um item (note que a chabe é 5, em vez de zero
// como voce pode ter esperado).
$array[] = 6;
print_r($array);
// Reindexando:
$array = array_values($array);
$array[] = 7;
print_r($array);
?>O exemplo acima irá imprimir:
Array ( [0] => 1 [1] => 2 [2] => 3 [3] => 4 [4] => 5 ) Array ( ) Array ( [5] => 6 ) Array ( [0] => 6 [1] => 7 )
Funções úteis
Há uma série de funções muito úteis para trabalhar com arrays. Veja a seção sobre arrays.
Nota:
A função unset() permite apagar chaves de um array. Esteja avisado que o array NÃO vai ser reindexado. Se você somente usa "índices inteiros comuns" (começando do zero, aumentando um a um), você pode conseguir reindexar o aaray utilizando array_values().
<?php
$a = array( 1 => 'um', 2 => 'dois', 3 => 'três' );
unset( $a[2] );
/* irá produzir um array que pode ser definido como
$a = array( 1=>'um', 3=>'três');
e NÃO
$a = array( 1 => 'um', 2 => 'três');
*/
$b = array_values($a);
// Agora $b é o array(1 => 'um', 2 =>'três')
?>
foreach existe especificamente para lidar com arrays. Ele provém uma maneira fácil de percorrer qualquer array.
Array: faça e não faça
Porque $foo[bar] está errado?
Você sempre deve usar delimitadores em volta um índice de um array associativo. Por exemplo, utilizar $foo['bar'] e não $foo[bar]. Mas porque $foo[bar] está errado? Afinal de contas, você vê essa sintaxe nos scripts antigos:
<?php
$foo[bar] = 'inimigo';
echo $foo[bar];
// etc
?>
Nota: Isto não significa que você sempre deve delimitar as chaves nos arrays. Você não deve delimitar chaves que sejam constantes ou variáveis, porque isso vai impedir o PHP de interpretá-las.
<?php
error_reporting(E_ALL);
ini_set('display_errors', true);
ini_set('html_errors', false);
// Arrays simples:
$array = array(1, 2);
$count = count($array);
for ($i = 0; $i < $count; $i++) {
echo "\nVerificando $i: \n";
echo "Ruim: " . $array['$i'] . "\n";
echo "Bom: " . $array[$i] . "\n";
echo "Ruim: {$array['$i']}\n";
echo "Bom: {$array[$i]}\n";
}
?>O exemplo acima irá imprimir:
Verificando 0: Notice: Undefined index: $i in /path/to/script.html on line 9 Ruim: Bom: 1 Notice: Undefined index: $i in /path/to/script.html on line 11 Ruim: Bom: 1 Verificando 1: Notice: Undefined index: $i in /path/to/script.html on line 9 Ruim: Bom: 2 Notice: Undefined index: $i in /path/to/script.html on line 11 Ruim: Bom: 2
Mais exemplos para demonstrar esse fato:
<?php
// Vamos ver todos os erros
error_reporting(E_ALL);
$arr = array('fruta' => 'maçã', 'legume' => 'cenoura');
// Correto
print $arr['fruta']; // maçã
print $arr['legume']; // cenoura
// Errado. Isto funciona mas lança um erro PHP do
// nível E_NOTICE porque é utilizada uma constante indefinida (fruta)
//
// Repare: Quando utiliza-se a constrante indefinida fruta, o PHP assume 'fruta'
print $arr[fruta]; // maçã
// Agora vamos definir uma constante para demonstrar o que pode acontecer. Nós
// vamos assimilar o valor 'legume' para a constante de nome fruta
define('fruta', 'legume');
// Observe a diferenca agora
print $arr['fruit']; // maçã
print $arr[fruit]; // cenoura
// O exemplo seguinte é normal dentro de uma string. Constantes não são
// observadas dentro de strings e por isso nenhum E-NOTICE não é lançado aqui
print "Olá $arr[fruta]"; // Olá maçã
// Com uma exceção: chaves envolvendo arrays dentro de strings
// ativam a checagem de constantes, como em
print "Olá {$arr[fruta]}"; // Hello cenoura
print "Olá {$arr['fruta']}"; // Hello maçã
// E isso não funciona, resultando em um erro de interpretação do tipo:
// Parse error: parse error, expecting T_STRING' or T_VARIABLE' or T_NUM_STRING'
// Isso se aplica ao uso de superglobais em strings
print "Olá $arr['fruta']";
print "Olá $_GET['foo']";
// Nesse caso, use concatenacao
print "Olá " . $arr['fruta']; // Olá maçã
?>
Quando você ativa error_reporting() para mostrar erros de nível E_NOTICE (como configurando-a para E_ALL) você vê esses erros. Por padrão, error_reporting esté configurada para não mostrar esse nível de erro.
Como explicado na seção sintaxe, a chave precisa estar entre colchetes ('[' e ']'). Isto significa que você pode escrever coisas como isso:
<?php
echo $arr[algumafuncao($bar)];
?>
<?php
$error_descriptions[E_ERROR] = "Um erro fatal ocorreu";
$error_descriptions[E_WARNING] = "O PHP emitiu um alarme";
$error_descriptions[E_NOTICE] = "Apenas um aviso informal";
?>
<?php
$error_descriptions[1] = "Um erro fatal ocorreu";
$error_descriptions[2] = "O PHP emitiu um alarme";
$error_descriptions[8] = "Apenas um aviso informal";
?>
Como nós mostramos nos exemplos anteriores, $foo[bar] funciona mas está errado. Funciona porque bar, na sintaxe onde é utilizada é esperada como uma expressão constante. Entretanto, nesse caso não existe constante com o nome bar. O PHP, hoje, assume que você quer bar literalmente, como a string "bar", mas que você esqueceu de escrever os delimitadores.
Então, porque isso é tão mal?
Se em algum ponto do futuro, o time do PHP quiser acrescentar outra constante ou palavra chave, ou você mesmo introduzir outra constante na sua aplicação, você terá problemas. Por exemplo, se você já não pode utilizar as palavras empty e default dessa maneira, desde que elas são palavras reservadas especiais.
Nota: Só para fixar, dentro de uma string delimitada por aspas, é válido não englobar índices de arrays com apóstrofos, de forma que "$foo[bar]" é válido. Veja os exemplos anteriores para detalhes bem como na seção sobre interpretação de variáveis em strings.
Convertendo para array
Para qualquer dos tipos: integer, float, string, boolean e resource, se você converte um valor para um array, você obtêm um array com um elemento (de índice 0) contendo o valor escalar informado.
Se você converte um tipo object para um array, você obtêm as propriedades (variáveis membro) do objeto com elementos do array. As chaves serão o nome das variáveis membro com pequenas notáveis exceções: variáveis privada tem o nome da classe prefixado no nome da variável; variáveis protegidas tem um '*' prefixando o nome da variável. Estes prefixos tem null bytes em ambos os lados. Isto pode resultado em algum comportamente inesperado.
<?php
class A {
private $A; // This will become '\0A\0A'
}
class B extends A {
private $A; // This will become '\0B\0A'
public $AA; // This will become 'AA'
}
var_dump((array) new B());
?>
Se você converter um valor NULL para um array, você terá um array vazio.
Comparando
É possível comparar arrays através de array_diff() e operadorores de array.
Exemplos
O tipo array do PHP é muito versátil, por isso temos aqui alguns exemplos para mostrar todo o poder dos arrays.
<?php
// isto
$a = array( 'cor' => 'vermelha',
'sabor' => 'doce',
'forma' => 'redonda',
'nome' => 'maçã',
4 // a chave será 0
);
// isto é equivalente a acima
$a['cor'] = 'vermelha';
$a['sabor'] = 'doce';
$a['forma'] = 'redonda';
$a['nome'] = 'maçã';
$a[] = 4; // a chave será 0
$b[] = 'a';
$b[] = 'b';
$b[] = 'c';
// o mesmo de array( 0 => 'a' , 1 => 'b' , 2 => 'c' ),
// ou simplesmente array('a', 'b', 'c')
?>
Exemplo #1 Utilizando array()
<?php
// Array como (propriedade-)mapa
$map = array( 'versao' => 4,
'OS' => 'Linux',
'lang' => 'inglês',
'short_tags' => true
);
// apenas chaves numéricas
$array = array( 7,
8,
0,
156,
-10
);
// que é o mesmo que array( 0 => 7, 1 => 8, ...)
$switching = array( 10, // chave = 0
5 => 6,
3 => 7,
'a' => 4,
11, // chave = 6 (o índice máximo era 5)
'8' => 2, // chave = 8 (inteiro!)
'02' => 77, // chave = '02'
0 => 12 // o valor 10 será sobrescrito por 12
);
// array vazio
$empty = array();
?>
Exemplo #2 Coleção
<?php
$cores = array('vermelho', 'azul', 'verde', 'amarelo');
foreach ($cores as $cor) {
echo "Você gosta de $cor?\n";
}
?>
O exemplo acima irá imprimir:
Você gosta de vermelho? Você gosta de azul? Você gosta de verde? Você gosta de amarelo?
Mudando diretamente valores de array é possível desde o PHP 5, passando-os como referência. Em versões anteriores precisava de um workaround:
Exemplo #3 Coleção
<?php
// PHP 5
foreach ($colors as &$color) {
$color = strtoupper($color);
}
unset($color); /* ensure that following writes to
$color will not modify the last array element */
// Workaround for older versions
foreach ($colors as $key => $color) {
$colors[$key] = strtoupper($color);
}
print_r($colors);
?>
O exemplo acima irá imprimir:
Array
(
[0] => RED
[1] => BLUE
[2] => GREEN
[3] => YELLOW
)
Este exemplo cria um array na base 1.
Exemplo #4 Array baseado em 1
<?php
$primeiroquarto = array(1 => 'Janeiro', 'Fevereiro', 'Março');
print_r($primeiroquarto);
?>
O exemplo acima irá imprimir:
Array
(
[1] => 'Janeiro'
[2] => 'Fevereiro'
[3] => 'Março'
)
Exemplo #5 Preenchendo um array real
<?php
// preenchendo um array com todos os itens de um diretório
$handle = opendir('.');
while (false !== ($file = readdir($handle))) {
$files[] = $file;
}
closedir($handle);
?>
Arrays são ordenados. Você pode mudar sua ordem utilizando vários funções de ordenação. Veja as funções de arrays para mais informações. Você pode contar o número de itens de um array com a função count().
Exemplo #6 Ordenando arrays
<?php
sort($files);
print_r($files);
?>
Porque o valor de um array pode ser qualquer coisa, isto pode ser outro array. Isto pode criar arrays recursivos e multidimensionais.
Exemplo #7 Arrays recursivos e multidimensionais
<?php
$fruits = array ( "frutas" => array ( "a" => "laranja",
"b" => "banana",
"c" => "maçã",
),
"numeros" => array ( 1,
2,
3,
4,
5,
6
),
"buracos" => array ( "primeiro",
5 => "segundo",
"terceiro",
),
);
// Alguns exemplo de enderecos dos valores do array acima
echo $fruits["buracos"][5]; // prints "segundo"
echo $fruits["frutas"]["a"]; // prints "laranja"
unset($fruits["buracos"][0]); // remove "primeiro"
// Criando um novo array multidimensional
$sucos["maca"]["verde"] = "bom";
?>
Você precisa estar ciente que a atribuição sempre envolve cópia de valor. Também significa que o ponteiro interno do array usado por current() e funções similares são resetados. Você precisa utilizar o operador de referência para copiar um array por referência.
<?php
$arr1 = array(2, 3);
$arr2 = $arr1;
$arr2[] = 4; // $arr2 é modificado,
// $arr1 continua sendo apenas array(2, 3)
$arr3 = &$arr1;
$arr3[] = 4; // agora $arr1 e $arr3 sao os mesmos
?>
Objects
Object Initialization
To create a new object, use the new statement to instantiate a class:
<?php
class foo
{
function do_foo()
{
echo "Doing foo.";
}
}
$bar = new foo;
$bar->do_foo();
?>
For a full discussion, see the Classes and Objects chapter.
Converting to object
If an object is converted to an object, it is not modified. If a value of any other type is converted to an object, a new instance of the stdClass built-in class is created. If the value was NULL, the new instance will be empty. Arrays convert to an object with properties named by keys, and corresponding values. For any other value, a member variable named scalar will contain the value.
<?php
$obj = (object) 'ciao';
echo $obj->scalar; // outputs 'ciao'
?>
Resource
Um recurso é uma variável especial, que mantém uma referência a um recurso externo. Recursos são criados e usados por funções especiais. Veja o apêndice para uma lista de todas essas funções e seus tipos correspondentes.
Nota: O tipo resource foi incluído no PHP 4.
Veja também get_resource_type().
Convertendo para recurso
Como as variáveis resource mantém manipuladores especiais para arquivos abertos, conexões de bancos de dados, canvas de imagens e coisas do tipo, converter para resource não faz sentido algum.
Liberando recursos
Através ao sistema de contagem de referência introduzido com o engine da Zend no PHP 4, quando um recurso não é mais referenciado, ele é automaticamente detectado (assim como no Java). Quando isto acontece, todos os recursos em uso por esse resource são liberados pelo coletor de lixo. Por essa razão, é raramente necessário liberar memória manualmente utilizando alguma função free_result.
Nota: Conexões persistentes de bancos são especiais. Eles não são destruídos pelo coletor de lixo. Veja também conexões permanentes.
NULL
O valor especial NULL representa que a variável não tem valor. NULL é o único valor possível do tipo NULL.
Nota: O tipo NULL foi incluído no PHP 4.
A variável é considerada null se:
-
ela foi assimilada com a constante NULL.
-
ela ainda não recebeu nenhum valor ainda.
-
ela foi apagada com unset().
Sintaxe
Há apenas um único valor do tipo null, e é a palavra-chave case-insensitive NULL.
<?php
$var = NULL;
?>
Convertendo para NULL
Convertendo uma variável para null removerá a variável e apagar seu valor.
Pseudo-tipos e variáveis utilizados nesta documentação
mixed
mixed indica que um parâmetro pode aceitar vários (mas não necessariamente todos) os tipos
gettype(), por exemplo, aceita todos os tipos do PHP, enquanto str_replace() somente aceita strings e arrays.
callback
Algumas funções como call_user_func() ou usort() aceitam callback de funções definidas por usuário como parâmetro. Funções de callback não podem ser somente simples funções, mas também métodos de objetos incluindo métodos estáticos de classes.
Uma função PHP é simplesmente passado pelo seu nome como uma string. Você pode passar qualquer função nativa ou definida por usuário. Note que construtores da linguagem como array(), echo(), empty(), eval(), exit(), isset(), list(), print() ou unset() não podem ser chamados usando um callback.
A method of an instantiated object is passed as an array containing an object as the element with index 0 and a method name as the element with index 1.
Static class methods can also be passed without instantiating an object of that class by passing the class name instead of an object as the element with index 0.
Apart from common user-defined function, create_function() can be used to create an anonymous callback function.
Exemplo #1 Exemplo de funções callback
<?php
// Exemplo simples de callback
function my_callback_function() {
echo 'Olá Mundo!';
}
call_user_func('my_callback_function');
// Exemplo de método callback
class MyClass {
static function myCallbackMethod() {
echo 'Olá Mundo!';
}
}
// Type 1: Simple callback
call_user_func('my_callback_function');
// Type 2: Static class method call
call_user_func(array('MyClass', 'myCallbackMethod'));
// Type 3: Chamada de método de objeto
$obj = new MyClass();
call_user_func(array(&$obj, 'myCallbackMethod'));
// Type 4: Static class method call (As of PHP 5.2.3)
call_user_func('MyClass::myCallbackMethod');
// Type 5: Relative static class method call (As of PHP 5.3.0)
class A {
public static function who() {
echo "A\n";
}
}
class B extends A {
public static function who() {
echo "B\n";
}
}
call_user_func(array('B', 'parent::who')); // A
?>
Nota: No PHP 4, vocÊ irá ter que usar a referência para criar um callback que aponta para o objeto atual, e não uma cópia dele. Para mais detalhes, veja Referências explicadas.
void
void no tipo de retorno indica que não há valor a ser retornado. void na lista de parâmetros indica que a função não aceita parâmetros.
...
$... no protótipo de uma função significa e assim por diante. O nome desta variável é usado quando a função suporta infinito número de argumentos.
Manipulação de tipos
O PHP não requer (ou suporta) a definição de tipo explícita na declaração de variáveis: o tipo de uma variável é determinado pelo contexto em que a variável é utilizada. Isto significa que, se você atribuir um valor string para a variável $var, $var se torna uma string. Se você então atribuir um valor inteiro para $var, ela se torna um inteiro.
Um exemplo da conversão automática do PHP é o operador de adição '+'. Se qualquer um dos operadores for float, então todos os operadores são avaliados como floats, e o resultado será um float. De outra forma, se os operadores forem interpretados como integers então o resultado será um integer. Note que isso não muda os tipos dos operadores: apenas muda em como esses operadores são avaliados.
<?php
$foo = "0"; // $foo é string (ASCII 48)
$foo += 2; // $foo é agora um interio (2)
$foo = $foo + 1.3; // $foo é agora um float (3.3)
$foo = 5 + "10 pequenos porcos"; // $foo é inteiro (15)
$foo = 5 + "10 minúsculos porcos"; // $foo é inteiro (15)
?>
Se os últimos dois exemplos lhe parecerem estranhos, veja Conversão de strings para números.
Para forçar uma variável para ser avaliada como um certo tipo, veja a seção Moldando o tipo (casting). Se você deseja mudar o tipo de uma variável, veja settype().
Para testar qualquer um dos exemplo desta seção, você pode usar a função var_dump().
Nota:
O comportamento de uma conversão automática para array é atualmente indefinida.
Também, pelo PHP suporta indexação em strings via índice usando a mesma sintaxe de array, o seguinte exemplo é válido para todas versões do PHP:
<?php
$a = 'car'; // $a é uma string
$a[0] = 'b'; // $a é ainda uma string
echo $a; // bar
?>Veja a seção entitulada Acessando caracteres da string para mais informações.
Conversão de Tipos - Type Casting
A conversão de tipos no PHP funciona como no C: o nome de um tipo desejado é escrito entre parênteses antes da variável em que se deseja a moldagem.
<?php
$foo = 10; // $foo é um inteiro
$bar = (boolean) $foo; // $bar é um booleano
?>
As moldagens permitidas são:
- (int), (integer) - molde para inteiro
- (bool), (boolean) - converte para booleano
- (float), (double), (real) - converte para número de ponto flutuante
- (string) - converte para string
- (binary) - converte para string binária (PHP 6)
- (array) - converte para array
- (object) - converte para objeto
- (unset) - converte para NULL (PHP 5)
(binary) e o prefixo b é foram adicionados no PHP 5.2.1
Note que tabulações e espaços são permitidos dentro dos parênteses, então o seguinte são funcionalmente equivalentes:
<?php
$foo = (int) $bar;
$foo = ( int ) $bar;
?>
Convertendo uma string literal e variáveis para strings binárias:
<?php
$binary = (binary)$string;
$binary = b"binary string";
?>
Nota:
Em vez de converter uma variável para string, você também pode englobar a variável entre aspas duplas.
<?php
$foo = 10; // $foo é um interio
$str = "$foo"; // $str é uma string
$fst = (string) $foo; // $fst tambem é uma string
// Isto imprimirah "eles são o mesmo"
if ($fst === $str) {
echo "eles são o mesmo";
}
?>
Pode não ser tão óbvio o que exatamente ocorre quando se converte entre certos tipos. Para mais informações, veja essas seções:
Variáveis
Índice
Introdução
As variáveis no PHP são representadas por um cifrão ($) seguido pelo nome da variável. Os nomes de variável no PHP fazem distinção entre maiúsculas e minúsculas.
Os nomes de variável seguem as mesmas regras como outros rótulos no PHP. Um nome de variável válido se inicia com uma letra ou sublinhado, seguido de qualquer número de letras, algarismos ou sublinhados. Em uma expressão regular isto poderia ser representado desta forma: '[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*'
Nota: Para nosso propósito, as letras a-z, A-Z e os bytes de 127 a 255 (0x7f-0xff).
Nota: $this é uma variável especial que não pode ser atribuída.
Veja também o Guia de nomenclatura em espaço de usuário.
Para informação sobre funções relacionadas a variáveis, veja a Referência de funções para variáveis.
<?php
$var = 'Bob';
$Var = 'Joe';
echo "$var, $Var"; // exibe "Bob, Joe"
$4site = 'not yet'; // inválido; começa com um número
$_4site = 'not yet'; // válido; começa com um sublinhado
$täyte = 'mansikka'; // válido; 'ä' é um caracter ASCII (extendido) 228
?>
Por padrão, as variáveis são sempre atribuídas por valor. Isto significa que quando você atribui uma expressão a uma variável, o valor da expressão original é copiado integralmente para a variável de destino. Isto significa também que, após atribuir o valor de uma variável a outra, a alteração de uma destas variáveis não afetará a outra. Para maiores informações sobre este tipo de atribuição, veja o capítulo em Expressões.
O PHP oferece um outro meio de atribuir valores a variáveis: atribuição por referência. Isto significa que a nova variável simplesmente referencia (em outras palavras, "torna-se um apelido para" ou "aponta para") a variável original. Alterações na nova variável afetam a original e vice versa.
Para atribuir por referência, simplesmente adicione um e-comercial (&) na frente do nome da variável que estiver sendo atribuída (variável de origem) Por exemplo, o trecho de código abaixo imprime 'My name is Bob' duas vezes:
<?php
$foo = 'Bob'; // Atribui o valor 'Bob' a variável $foo
$bar = &$foo; // Referecia $foo através de $bar.
$bar = "My name is $bar"; // Altera $bar...
echo $bar;
echo $foo; // $foo é alterada também.
?>
Uma observação importante a se fazer: somente variáveis nomeadas podem ser atribuídas por referência.
<?php
$foo = 25;
$bar = &$foo; // Esta atribuição é válida.
$bar = &(24 * 7); // Inválido; referencia uma expressão sem nome.
function test()
{
return 25;
}
$bar = &test(); // Inválido.
?>
Não é necessário variáveis inicializadas no PHP, contudo é uma ótima prática. Variáveis não inicializadas tem um valor padrão do tipo dela dependendo do contexto no qual eles são usados - padrão de booleanos é FALSE, de inteiros e ponto-flutuantes é zero, strings (e.g. usado em echo()) são definidos como uma string vazia e arrays tornam-se um array vazio.
Exemplo #1 Valores padrões de variáveis não inicializadas
<?php
// Limpa e remove referência (sem uso de contexto) a variável; imprime NULL
var_dump($unset_var);
// Uso de booleano; imprime 'false' (Veja sobre operadores ternário para saber mais sobre a sintaxe)
echo ($unset_bool ? "true" : "false"); // false
// Uso de string; imprime 'string(3) "abc"'
$unset_str .= 'abc';
var_dump($unset_str);
// Uso de inteiro; imprime 'int(25)'
$unset_int += 25; // 0 + 25 => 25
var_dump($unset_int);
// Uso de float/double; imprime 'float(1.25)'
$unset_float += 1.25;
var_dump($unset_float);
// Uso de array; imprime array(1) { [3]=> string(3) "def" }
$unset_arr[3] = "def"; // array() + array(3 => "def") => array(3 => "def")
var_dump($unset_arr);
// Uso de objeto; cria novo objeto stdClass (veja http://www.php.net/manual/en/reserved.classes.php)
// Imprime: object(stdClass)#1 (1) { ["foo"]=> string(3) "bar" }
$unset_obj->foo = 'bar';
var_dump($unset_obj);
?>
Confiar no valor padrão de uma variável não inicializada é problemático no caso de incluir um arquivo em outro que usa variável com mesmo nome. E também um principal risco de segurança com register_globals estando on. Erros E_NOTICE são emitidos no caso de ter variáveis não inicializadas, contudo não no caso de adicionar elementos para um array não inicializado. O construtor da linguagem isset() pode ser usado para detectar se uma variável não foi inicializada.
Variáveis Pré-definidas
O PHP oferece um grande número de variáveis pré-definidas para qualquer script que ele execute. Muitas destas variáveis, entretanto, não podem ser completamente documentadas uma vez dependem de diversos fatores, como o servidor no qual scripts são executados, a versão e configuração deste servidor e outros. Algumas destas variáveis não estarão disponíveis quando o PHP for executado na linha de comando. Para uma lista destas variáveis, veja a seção Variáveis reservadas.
No PHP 4.2.0 e posteriores, o valor default da diretiva register_globals é off. Esta é a maior modificação no PHP. Tendo register_globals off afeta o conjunto de variáveis pré-definidas disponíveis no escopo global. POr exemplo, para ler DOCUMENT_ROOT você usará $_SERVER['DOCUMENT_ROOT'] em vez de $DOCUMENT_ROOT, ou $_GET['id'] da URL http://www.example.com/test.php?id=3 em vez de $id, or $_ENV['HOME'] em vez de $HOME.
Para informações relacionadas desta modificação, veja detalhes da diretiva register_globals, no capítulo de segurança em Usando register_globals , assim como o detalhamento de lançamento das versões do PHP » 4.1.0 e » 4.2.0.
Utilizar as Variáveis Pré-definidas do PHP, como os arrays superglobais, é muito mais preferível.
Desde a versão 4.1.0, o PHP fornece um conjunto adicional de arrays predefinidos contendo as variáveis do servidor web (se aplicável), as variáveis ambiente e as entradas do usuário. Esses novos arrays são especiais pelo motivo que são automaticamente globais (significa que são automaticamente disponíveis em qualquer escopo. Por causa disso, são também conhecidas como 'superglobais' (Não há um mecanismo no PHP para superglobais definidas pelo usuário) As superglobais são listadas abaixo. Entretanto, para uma explicação de seu conteúdo e detalhes sobre as variáveis pré-definidas do PHP e sua natureza, veja a seção Variáveis Pré-definidas. Veja também que todas as outras variáveis pré-definidas antigas ($HTTP_*_VARS) ainda existem. A partir do PHP 5.0.0, os grandes arrays de variáveis pré-definidas podem ser desativadas através da diretiva register_long_arrays .
Nota: Variáveis variáveis
Superglobais não podem ser utilizadas como variáveis variáveis dentro de funções ou métodos de classe.
Nota:
Mesmo que superglobal e HTTP_*_VARS existam; elas não são idênticas, então modificando uma não irá alterar a outra.
Se todos os indicadores não estiverem configurados no variables_order, seus arrays superglobais predefinidos respectivos estarão vazios.
Escopo de variáveis
O escopo de uma variável é o contexto onde ela foi definida. A maior parte das variáveis do PHP tem somente escopo local. Este escopo local inclui os arquivos incluídos. Por exemplo:
<?php
$a = 1;
include 'b.inc';
?>
Aqui a variável $a estará disponível no script incluído b.inc. Entretanto, com as funções definidas pelo usuário, um escopo local é introduzido. Quaisquer variáveis utilizadas dento da função é por default limitada dentro do escopo local da função. Por exemplo:
<?php
$a = 1; /* escopo global */
function Teste()
{
echo $a; /* referencia uma variável do escopo local (não definida) */
}
Teste();
?>
Este script não produz nenhuma saída porque a instrução echo() refere-se a uma versão local da variável $a, e ela não tem nenhum valor assimilado nesse escopo. Essa é uma pequena diferença da linguagem C quando variáveis globais são automaticamente disponíveis para funções sem sobreescrever uma eventual definição local. Isto causa problemas quando as pessoas mudam inadivertidamente uma variável global. No PHP, as variáveis globais precisam ser declaradas globais dentro de uma função se ela vai ser utilizada naquela função.
A palavra chave global
Primeiro, um exemplo de global:
Exemplo #1 Usando global
<?php
$a = 1;
$b = 2;
function Soma()
{
global $a, $b;
$b = $a + $b;
}
Soma();
echo $b;
?>
O script acima imprimirá "3". Declarando $a e $b globais na função, todas as referências a essas variáveis referem-se a versão global. Não há um limite para o número de variáveis globais que podem ser manipuladas por uma função.
Uma segunda maneira de acessar variáveis do escopo global é utilizando o array especial $GLOBALS definido pelo PHP. O exemplo anterior poderia ser rescrito como:
Exemplo #2 Usando $GLOBALS no lugar de global
<?php
$a = 1;
$b = 2;
function Soma()
{
$GLOBALS['b'] = $GLOBALS['a'] + $GLOBALS['b'];
}
Soma();
echo $b;
?>
O array $GLOBALS é um array associativo onde o nome da variável global é a chave do array e o seu conteúdo da variável como o valor do elemento do array. Veja que $GLOBALS existe em qualquer escopo, isto porque $GLOBALS é uma superglobal. Segue um exemplo demonstrando o poder das superglobais:
Exemplo #3 Exemplo demonstrando superglobals e escopos
<?php
function test_global()
{
// A maioria das variaveis pré-definidas nao sao 'super' e requerem
// 'global' para serem disponiveis para funcoes em qualquer escopo.
global $HTTP_POST_VARS;
echo $HTTP_POST_VARS['name'];
// Superglobais são disponiveis em qualquer escopo e
// nao precisam de 'global'. Superglobais existem
// desde o PHP 4.1.0, e HTTP_POST_VARS é agora
// tida como obsoleta.
echo $_POST['name'];
}
?>
Utilizando variáveis estáticas
Outro recurso importante do escopo de variáveis é a variável estática. Uma variável estática existe somente no escopo local da função, mas ela não perde seu valor quando o nível de execução do programa deixa o escopo. Considere o seguinte exemplo:
Exemplo #4 Exemplo demonstrando a necessidade de variáveis estáticas
<?php
function Teste ()
{
$a = 0;
echo $a;
$a++;
}
?>
Essa função é inútil partindo de que cada vez que ela é chamada, ela coloca em $a o valor 0 e imprime "0". A instrução $a++ , que aumenta o valor da variável não tem sentido desde que a função sai e a variável $a desaparece. Para faze-la mais útil como contadora sem deixar de perder o sua conta atual, a variável $a é declarada como estática:
Exemplo #5 Exemplo de uso de variáveis estáticas
<?php
function Teste()
{
static $a = 0;
echo $a;
$a++;
}
?>
Agora, cada vez que a função Teste() for chamada ele imprimirá o valor de $a e o incrementará.
Variáveis estáticas fornecem uma solução ideal para funções recursivas. Uma função recursiva é aquela se chama a si mesma. Cuidados especiais precisam ser tomados quando escrevendo funções recursivas porque é possível que ela continue na recursão indefinidamente. Você tem de ter certeza que há uma maneira segura de terminar a recursão. A seguinte função recursiva conta até 10, utilizando a variável estática $count para saber quando parar:
Exemplo #6 Variáveis estáticas em funções recursivas
<?php
function Teste()
{
static $count = 0;
$count++;
echo $count;
if ($count < 10) {
Test ();
}
$count--;
}
?>
Nota:
Variáveis estáticas podem ser declaradas como nos exemplos acima. A tentativa de assimilar valores para essas variáveis com resultados de expressões causarão um erro de interpretação (parse).
Exemplo #7 Declarando variáveis static
<?php
function foo(){
static $int = 0; // correro
static $int = 1+2; // errado (é uma expressão)
static $int = sqrt(121); // wrong (é uma expressão também)
$int++;
echo $int;
}
?>
Referencias em variáveis globais e estáticas
A Zend Engine 1, base do PHP 4, implementa os modificadores static e global para variáveis na questão de referências. Por exemplo, uma veriável global importada dentro do escopo de uma função com a instrução global atualmente cria uma referência para a variável global. Isto pode causar comportamentos impresíveis para os seguintes casos:
<?php
function test_global_ref() {
global $obj;
$obj = &new stdclass;
}
function test_global_noref() {
global $obj;
$obj = new stdclass;
}
test_global_ref();
var_dump($obj);
test_global_noref();
var_dump($obj);
?>
Executando esse exemplo você terá as seguites saídas:
NULL
object(stdClass)(0) {
}
Uma situação similar se aplica ao modificador static. Referências não são armazenadas estaticamente:
<?php
function &get_instance_ref() {
static $obj;
echo 'Objeto estatico: ';
var_dump($obj);
if (!isset($obj)) {
// Assimila uma referencia a variavel estatica
$obj = &new stdclass;
}
$obj->property++;
return $obj;
}
function &get_instance_noref() {
static $obj;
echo "Objeto estatico: ";
var_dump($obj);
if (!isset($obj)) {
// Assimila o objeto para a veriavel estatica
$obj = new stdclass;
}
$obj->property++;
return $obj;
}
$obj1 = get_instance_ref();
$still_obj1 = get_instance_ref();
echo "\n";
$obj2 = get_instance_noref();
$still_obj2 = get_instance_noref();
?>
Executando esse exemplo você terá as seguites saídas:
Objeto estatico: NULL
Objeto estatico: NULL
Objeto estatico: NULL
Objeto estatico: object(stdClass)(1) {
["property"]=>
int(1)
}
Este exemplo demonstra que quando assimilando uma referência para uma variável estática, ela não se lembra quando você chama a função &get_instance_ref() uma segunda vez.
Variáveis variáveis
As vezes é conveniente poder trabalhar com variáveis variáveis. Isto é, nomes de variáveis que pode ser criadas e utilizadas dinamicamente. Uma variável normal é criada numa instrução como:
<?php
$a = 'hello';
?>
Uma variável variável pega o valor de uma variável e a trata como o nome de uma variável. No exemplo acima, hello pode ser utilizada como o nome de uma variável utilizando dois sinais de cifrão:
<?php
$$a = "world";
?>
Neste ponto, duas variáveis foram definidas e preservadas na árvore de símbolos do PHP: $a contendo "hello" e $hello contendo "world". Da mesma forma, esta instrução:
<?php
echo "$a ${$a}";
?>
produz a mesma saida que:
<?php
echo "$a $hello";
?>
no caso: hello world.
Para poder utilizar variáveis variáveis com arrays, você precisa resolver um problema de ambigüidade. Assim, se você escrever $$a[1] então o interpretador pode entender que você quer usar $a[1] como uma variável ou que você quer usar $$a como uma variável e [1] como o índice dessa variável. A sintaxe para resolver essa ambigüidade é ${$a[1]} para o primeiro caso e ${$a}[1] para o segundo.
Note que variáveis variáveis não podem ser utilizadas com os novos arrays superglobais dentro de funções ou métodos de classes. A variável $this é também uma variável especial e não pode ser referenciada dinamicamente.
Variáveis de fontes externas
Formulários HTML (GET and POST)
Quando um formulário é submetido para um script PHP, qualquer variável do formulário será automaticamente disponível para o script. Há várias maneiras de acessar estas informações, por exemplo:
Exemplo #1 Um formulário HTML simples
<form action="foo.php" method="post">
Nome: <input type="text" name="username" /><br />
Email: <input type="text" name="email" /><br />
<input type="submit" name="submit" value="Me aperte!" />
</form>
Dependendo da configuração local e suas preferencias pessoais, essas são as vias pela qual você pode acessar os dados de seus formulários:
Exemplo #2 Acessando dados de um formulário HTML via POST
<?php
// Disponível desde o PHP 4.1.0
echo $_POST['username'];
echo $_REQUEST['username'];
import_request_variables('p', 'p_');
echo $p_username;
// Indisponivel desde o PHP 6. A partir do PHP 5.0.0, essas longas
// variaveis pré-definidas podem ser desabilitadas pela diretiva register_long_arrays.
echo $HTTP_POST_VARS['username'];
// Disponível se a diretiva register_globals = on.
// Desde o PHP 4.2.0 o valor default de register_globals é off
// Usar/manter esse método é preferível.
echo $username;
?>
Utilizar um formulário GET é similar, exceto que você use a variável GET pré-definida. O metodo GET obtem os dados da QUERY_STRING (a informação depois do '?' numa URL). Então, por exemplo, http://www.example.com/test.php?id=3 contém os dados GET que serão acessíveis com $_GET['id']. Veja também $_REQUEST e import_request_variables().
Nota:
Arrays superglobais, como $_POST e $_GET, estão disponíveis desde o PHP 4.1.0.
Como explicado, antes do PHP 4.2.0 o valor default de register_globals era on. E no PHP ele era sempre on. A comunidade PHP está encorajando todos a não alterarem essa diretiva, assumindo-a sempre como off e codificando em conformidade com isso.
Nota:
A diretiva de configuração magic_quotes_gpc afeta os valores de GET, POST e Cookies. Se estiver ativada, o valor (It's "PHP!") se tornará automaticamente (It\'s \"PHP!\"). Escaping é necessário para inserção em bancos de dados. Veja também addslashes(), stripslashes() e magic_quotes_sybase.
O PHP entende arrays no contexto de variáveis de formulários (veja o FAQ relacionado). Você pode, por exemplo, agrupar variáveis relacionadas juntas, ou usar esse recurso para receber valores de um campo de seleção múltipla. Por exemplo, podemos ter um formulario que manda informações para si mesmo até um comando submetido para mostrar todos os dados.
Exemplo #3 Variáveis de formulários mais complexos
<?php
if ($_POST) {
echo '<pre>';
echo htmlspecialchars(print_r($_POST, true));
echo '</pre>';
} else {
?>
<form action="" method="post">
Nome: <input type="text" name="personal[name]" /><br />
Email: <input type="text" name="personal[email]" /><br />
Cerveja: <br />
<select multiple name="beer[]">
<option value="antartica">Antartica</option>
<option value="brahma">Brahma</option>
<option value="skol">Skol</option>
</select><br />
<input type="submit" value="Enviar dados!" />
</form>
Nomes de variáveis SUBMIT IMAGE
Quando submetendo um formulário, é possível de se utilizar imagens ao invés do botão de submit padrão com uma tag do tipo:
<input type="image" src="image.gif" name="sub" />
Quando o usuário clica em algum lugar da imagem, o formulário que o acompanha é transmitido para o servidor com duas variáveis adicionais, sub_x e sub_y. Eles contém a coordenadas do clique do usuário na imagem. Os mais experientes percebem que os atuais nomes dessas variáveis enviados pelo browser contém um ponto ao invés de um sublinhado, mas o PHP converte o ponto para um sublinhado automaticamente.
Cookies HTTP
O PHP suporta transparentemente cookies HTTP como os definidos pela » especificação da Netscape. Cookies são um mecanismo de armazenamento de dados no browser cliente e permite o rastreamento ou identificação do retorno de usuários. Você pode criar cookies com a função setcookie(). Cookies são parte do header HTTP, então, a função setcookie() precisa ser chamada antes de qualquer saída ser enviada ao browser. Esta é a mesma restrição da função header(). Dados de cookies são disponíveis nos arrays de dados de cookies apropriados, como $_COOKIE, $HTTP_COOKIE_VARS como também em $_REQUEST. Veja o manual de setcookie() para mais detalhes e exemplos.
Se você deseja assimilar vários valores para uma única variável cookie, você pode fazer dele um array:
<?php
setcookie("MeuCookie[foo]", 'Testando 1', time()+3600);
setcookie("MeuCookie[bar]", 'Testando 2', time()+3600);
?>
Isso irá criar dois cookies separados enquanto MeuCookie será um único array em seu script. Se você quiser colocar em apenas um cookie vários valores, considere utilizar serialize() ou explode() nos valores primeiro.
Note que um cookie substituirá um anterior com o mesmo nome em seu browser mesmo se o nome ou o caminho for diferente. Então, para uma aplicação de carrinho de compras em que você quer ter um contador e repassá-lo:
Exemplo #4 Exemplo setcookie()
<?php
if (isset($_COOKIE['count'])) {
$count = $_COOKIE['count'] + 1;
} else {
$count = 1;
}
setcookie('count', $count, time()+3600);
setcookie("Cart[$count]", $item, time()+3600);
?>
Pontos em nomes de variáveis postadas
Normalmente o PHP não altera o nome de variáveis quando elas são passadas para o script. Entretanto, é necessário notar que o ponto (ponto final) não é um caracter válido no nomes de variáveis do PHP. Para ilustrar, veja o seguinte exemplo:
<?php
$varname.ext; /* nome de variável inválido */
?>
Nessa situação, é importante saber que o PHP automaticamente substituirá qualquer ponto nos nomes de variáveis recebidas com sublinhados.
Determinando o tipo das variáveis
Porque o PHP determina os tipos de variáveis e faz conversões (geralmente) quando necessárias, nem sempre é óbvio o tipo de uma variável tem em todos os momentos. O PHP incluí várias funções que permitem determinar qual o tipo de uma variável, por exemplo: gettype(), is_array(), is_float(), is_int(), is_object(), e is_string(). Veja também o capítulo Tipos.
Constantes
Índice
Uma constante é um identificador (nome) para um único valor. Como o nome sugere, esse valor não pode mudar durante a execução do script (exceção às constantes mágicas, que não são constantes de verdade). As constantes são "Case Sensitive" (Sensível ao tamanho de letras) por padrão. Por convenção, o nomes de constantes são sempre em maiúsculas.
O nome de uma constante tem as mesmas regras de qualquer identificador no PHP. Um nome de constante válida começa com uma letra ou sublinhado, seguido por qualquer número de letras, números ou sublinhados. Em expressões regulares, ela pode ser representada por: [a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*
Veja também o Guia de nomenclatura em espaço de usuário.
Exemplo #1 Nomes de constantes válidos e inválidos
<?php
// Nomes de constantes válidos
define("FOO", "alguma coisa");
define("FOO2", "alguma outra coisa");
define("FOO_BAR", "alguma coisa mais");
// Nomes de constantes inválidas
define("2FOO", "alguma coisa");
// Isto é válido, mas deve ser evitado:
// O PHP pode vir a fornercer uma constante mágica
// que danificará seu script
define("__FOO__", "alguma coisa");
?>
Nota: Para nossos exemplos, uma letra é a-z, A-Z e os caracteres ASCII do 127 ao 255 (0x7f-0xff).
Como as superglobals, o escopo de uma constante é global. Você pode acessar constantes de qualquer lugar em seu script sem se preocupar com o escopo. Para mais informações sobre o escopo no PHP, leia a seção do manual escopo de variáveis.
Sintaxe
Você pode definir uma constante utilizando-se da função define(), ou utilizando a palavra-chave const fora da definição de uma classe a partir dor PHP 5.3.0. Quando uma constante é definida, ela nunca mais poderá ser modificada ou anulada.
Somente dados escalares (boolean, integer, float e string) podem ser colocados em constantes. É possível ter consntantes com um resource (recurso), mas deve ser evitado já que pode causar resultados não esperados.
Você pode obter o valor de uma constante simplesmente especificando seu nome. Diferentemente de variáveis, você não prefixa uma constante com um sinal de $. Você também pode utilizar a função constant() para ler o valor de uma constante, se você precisar obter seu valor dinamicamente. Utilize get_defined_constants() para obter a lista de todas as constantes definidas.
Nota: As constantes e variáveis (globais) estão em espaços de nomes diferentes. Isto implica, por exemplo, que TRUE e $TRUE são geralmente diferentes.
Se você usar uma constante indefinida, o PHP assume o nome da constante como seu próprio valor, como se você tivesse uma string (CONSTANT vs "CONSTANT"). Um erro de nível E_NOTICE será lançado quando isso acontecer. Veja também a referência do manual sobre como $foo[bar] é errado (a não ser que você primeiro define() bar como uma constante). Se você simplesmente quer checar se uma constante foi definida, utilize a função defined().
Estas são as diferenças entre constantes e variáveis:
- Constantes não podem ter um sinal de cifrão ($) antes delas;
- Constantes só podem ser definidas utilizando a função define(), e não por simples assimilação;
- Constantes podem ser definidas e acessadas de qualquer lugar sem que a regras de escopo de variáveis seja aplicadas;
- Constantes não podem ser redefinidas ou eliminadas depois que elas são criadas; e
- Constantes só devem conter valores escalares.
Exemplo #1 Definindo Constantes
<?php
define("CONSTANT", "Hello world.");
echo CONSTANT; // imprime "Hello world."
echo Constant; // imprime "Constant" e gera um alerta notice.
?>
Exemplo #2 Definindo Constantes usando a palavra-chave const
<?php
// Funciona a partir do PHP 5.3.0
const CONSTANT = 'Hello World';
echo CONSTANT;
?>
Nota:
Ao contrário das funções definidas através de define(), as constantes definidas usando a palavra-chave const devem ser declarados no escopo de topo (principal) pois são definidas no tempo de compilação. Isso significa que elas não podem ser definidas dentro de funções, laços ou ifs.
Veja também Constantes de Classe.
Constantes Mágicas
O PHP fornece um grande número de consntantes predefinidas para qualquer script que ele execute. A maioria dessas constantes, entretanto, são criadas por várias extensões, e somente estarão presentes quando essas extensões estiverem disponíveis, tanto por carregamento dinâmico quanto por compilação direta.
Há sete constantes "mágicas", que mudam dependendo de onde elas são utilizadas. Por exemplo, o valor de __LINE__ depende do número da linha em que é utilizada em seu script. Essas constantes especiais são insensíveis a maiúsculas e minúsculas (case insensitive):
| Nome | Descrição |
|---|---|
| __LINE__ | A linha atual do script. |
| __FILE__ | O caminho completo e nome do arquivo. Se utilizado dentro de um include, o nome do arquivo incluído será retornado. Desde o PHP 4.0.2, __FILE__ sempre contém um caminho absoluto com links simbólicos resolvidos enquanto em versões antigas ela continha um caminho relativo sob certas circunstâncias. |
| __DIR__ | O diretório do arquivo. Se usado dentro de um include, o diretório do arquivo incluído é retornado. Isto é equivalente a dirname(__FILE__). Este nome do diretório não possui barra no final, a não ser que seja o diretório raiz. (Adicionado no PHP 5.3.0.) |
| __FUNCTION__ | O nome da função (Acrescentado no PHP 4.3.0). A partir do PHP 5 esta constante retorna o nome da função como ela foi declarada (sensível a maiúsculas e minúsculas). No PHP 4 sempre retorna o nome em minúsculas. |
| __CLASS__ | O nome da classe (Adicionado no PHP 4.3.0). A partir do PHP 5 esta constante retorna o nome da função como ela foi declarada (sensível a maiúsculas e minúsculas). No PHP 4 sempre retorna o nome em minúsculas. O nome da classe inclui o namespace em que foi declarado (ex: Foo\Bar). Note que a partir do PHP 5.4, __CLASS__ funciona também em traits. Quando utilizada em um método trait, __CLASS__ é o nome da classe do trait em que foi utilizada. |
| __TRAIT__ | O nome do trait. (Adicionado no PHP 5.4.0) A partir do PHP 5.4 essa constante retorna o trait em que fo delcarado (sensível a maiúsculas e minúsculas). O nome do trait incluir o namespace em que foi declarado (ex: Foo\Bar). |
| __METHOD__ | O nome do método de classe. (Adicionado no PHP 5.0.0). O nome do método é retornado como foi declarado (sensível a maiúsculas e minúsculas). |
| __NAMESPACE__ | O nome do namespace atual (sensível a maiúsculas e minúsculas). Esta constante é definida em tempo de compilação (Adicionada no PHP 5.3.0). |
Veja também get_class(), get_object_vars(), file_exists() e function_exists().
Expressões
Expressões são as peças de construção mais importantes do PHP. No PHP, quase tudo o que você escreve são expressões. A maneira mais simples e ainda mais precisa de definir uma expressão é "tudo o que tem um valor".
As formas mais básicas de expressões são constantes e variáveis. Quando você digita "$a = 5", você está atribuindo '5' para $a. '5', obviamente, tem o valor 5, ou, em outras palavras, '5' é uma expressão com o valor 5 (neste caso, '5' é uma constante inteira).
Depois desta atribuição, você pode esperar que o valor de $a seja 5 também, assim se você escrever $b = $a, você pode esperar que $b se comporte da mesma forma que se você escrevesse $b = 5. Em outras palavras, $a é uma expressão com valor 5 também. Se tudo funcionou bem, isto é exatamente o que acontecerá.
Exemplos ligeiramente mais complexos para expressões são as funções. Por exemplo, considere a seguinte função:
<?php
function foo ()
{
return 5;
}
?>
Assumindo que você está familiarizado com o conceito de funções (se não estiver, dê uma olhada no capítulo sobre functions), você pode assumir que digitar $c = foo() é essencialmente a mesma coisa que escrever $c = 5, e você está certo. Funções são expressões com o valor igual ao seu valor de retorno. Como foo() retorna 5, o valor da expressão 'foo()' é 5. Geralmente, as funções não retornam apenas um valor estático, mas computam algo.
Claro, valores em PHP não tem que ser inteiros, e muito comumente eles não são. o PHP suporta quatro tipos de valores escalares: valores integer (inteiros), valores de ponto flutuante (float), valores string (caracteres) e valores boolean (booleano) (valores escalares são valores que você não pode partir em peças menores, diferentemente de matrizes, por exemplo). O PHP também suporta dois tipos compostos (não escalar): matrizes e objetos. Cada um desses valores podem ser definidos em uma variável ou retornados de uma função.
O PHP leva as expressões muito além, da mesma maneira que muitas outras linguagens fazem. O PHP é uma linguagem orientada a expressões, no sentido de que quase tudo são expressões. Considere o exemplo com o qual já lidamos, '$a = 5'. É fácil ver que há dois valores envolvidos aqui, o valor da constante inteira '5', e o valor de $a que está sendo atualizado para 5 também. Mas a verdade é que há um valor adicional envolvido aqui, e que é o próprio valor da atribuição. A própria atribuição é avaliada com o valor atribuído, neste caso 5. Na prática, significa que '$a = 5', independente do que faça, é uma expressão com o valor 5. Portanto, escrever algo como '$b = ($a = 5)' é como escrever '$a = 5; $b = 5;' (um ponto-e-vírgula marca o fim do comando). Como atribuições são analisadas da direita para a esquerda, você também pode escrever '$b = $a = 5'.
Outro bom exemplo de orientação de expressão é o pré e o pós-incremento e decremento. Usuários de PHP 2 e muitas outras linguagens podem estar familiarizados com a notação de variável++ e variable--. Este são operadores de incremento e decrimento. No PHP/FI 2, o comando '$a++' não tem valor (não é uma expressão), e portanto você não pode atribuir desta forma ou usá-la de jeito nenhum. O PHP evoluiu a capacidade de incremento/decremento criando estas expressões também, como em C. Em PHP, como em C, há dois tipos de incremento - pré-incremento e pós-incremento. Tanto o pré-incremento quanto o pós-incremento, essencialmente, incrementam as variáveis, e o efeito sobre a variável é idêntico. A diferença é com o valor da expressão de incremento. O pré-incremento, que é escrito '++$variavel', é avaliado como o valor de incremento (o PHP incrementa a variável antes de ler seu valor, por isso o nome pré-incremento). O pós-incremento, que é escrito '$variavel++' é avaliado como o valor original da variável, antes de ser incrementada (o PHP incrementa a variável depois de ler seu valor, por isso o nome 'pós-incremento').
Um tipo muito comum de expressões são expressões de comparação. Estas expressões avaliam para ser FALSE ou TRUE. O PHP suporta > (maior que), >= (maior ou igual a), == (igual), != (diferente), < (menor que) and <= (menor ou igual a). A linguagem também suporta um conjunto de operador de equivalencia estrita: === (igual a e do mesmo tipo) and !== (diferente de ou não do mesmo tipo). Estas expressões são mais comumente usada dentro de execução condicional como comandos if.
O último exemplo de expressões com que nós vamos lidar aqui são as expressões combinadas operador-atribuição. Você já sabe que se você quer incrementar $a de 1, você só precisa escrever '$a++' ou '++$a'. Mas e se você quiser somar mais que um a ele, por exemplo 3? Você poderia escrever '$a++' várias vezes, mas esta obviamente não é uma forma muito eficiente ou confortável. Uma prática muito mais comum é escrever '$a = $a + 3'. '$a + 3' é avaliada como o valor de $a mais 3, e é atribuído de volta a $a, que resulta em incrementar $a de 3. Em PHP, como em várias outras linguagens como o C, você pode escrever isto de uma forma mais curta, que com o tempo se torna mais limpa e rápida de se entender também. Somar 3 ao valor corrente de $a pode ser escrito '$a +=3'. Isto significa exatamente "pegue o valor de $a, some 3 a ele, e atribua-o de volta a $a." Além de ser mais curto e mais limpo, isto também resulta em execução mais rápida. O valor de '$a += 3', como o valor de uma atribuição regular, é o valor atribuído. Note que NÃO é 3, mas o valor combinado de $a mais 3 (este é o valor que é atribuído a $a). Qualquer operador de dois parâmetros pode ser usado neste modo operador-atribuição, por exemplo '$a -= 5' (subtrai 5 do valor de $a), '$ b *= 7' (multiplica o valor de $b por 7), etc.
Há mais uma expressão que podem parecer estranha se você não a viu em outras linguagens, o operador condicional ternário:
<?php
$primeira ? $segunda : $terceira
?>
Se o valor da primeira sub-expressão é verdadeiro (TRUE, não-zero), então a segunda sub-expressão é avaliada, e este é o resultado da expressão condicional. Caso contrário, a terceira sub-expressão é avaliada e este é o valor.
O seguinte exemplo deve ajudá-lo a entender um pouco melhor pré e pós-incremento e expressões em geral:
<?php
function double($i)
{
return $i*2;
}
$b = $a = 5; /* atribui o valor cinco às variáveis $a e $b */
$c = $a++; /* pós-incremento, atribui o valor original de $a
(5) para $c */
$e = $d = ++$b; /* pré-incremento, atribui o valor incrementado de
$b (6) a $d e $e */
/* neste ponto, tanto $d quanto $e são iguais a 6 */
$f = double($d++); /* atribui o dobro do valor de $d antes
do incremento, 2*6 = 12 a $f */
$g = double(++$e); /* atribui o dobro do valor de $e depois
do incremento, 2*7 = 14 a $g */
$h = $g += 10; /* primeiro, $g é incrementado de 10 e termina com o
valor 24. o valor da atribuição (24) é
então atribuído a $h, e $h termina com o valor
24 também. */
?>
Algumas expressões podem ser consideradas instruções. Neste caso, uma instrução na forma 'expr' ';' ou seja, uma expressão seguida de um ponto e vírgula. Em '$b=$a=5;', $a=5 é uma expressão válida, mas não é um comando por si só. '$b=$a=5;' porém é um comando válido.
Uma última coisa que vale mencionar é o valor-verdade de expressões. Em muitos eventos, principalmente em instruções condicionais e loops, você não está interessado no valor específico da expressão, mas somente se ela significa TRUE ou FALSE (o PHP não tem um tipo booleano dedicado). As constantes TRUE e FALSE (insensitivas ao caso) são seus dois valores booleanos possíveis. As vezes uma expressão é automaticamente convertida para um booleano. Veja a seção sobre type-casting para detalhes de como isso é feito.
O PHP fornece uma implementação completa e poderosa de expressões, e a completa documentação dela vai além do escopo deste manual. Os exemplos acima devem dar a você uma boa idéia sobre o que são as expressões e como você pode construir expressões úteis. Através do restante do manual nós escreveremos expr ou expressao para indicar qualquer expressão PHP válida.
Operadores
Índice
- Precedência de Operadores
- Operadores Aritméticos
- Operadores de Atribuição
- Operador Bit-a-bit
- Operadores de Comparação
- Operadores de controle de erro
- Operadores de Execução
- Operadores de Incremento/Decremento
- Operadores Lógicos
- Operadores de String
- Operadores de Arrays
- Operadores de tipo
Um operador é algo que você alimenta com um ou mais valores (ou expressões, no jargão de programação) e que devolve outro valor (e por isso os próprios construtores se tormam expressões). Assim, você pode pensar que as funções e os construtores que retornam valores (como o print) são operadores e os outros que não retornam nada (como echo) como uma outra coisa.
Há três tipos de operadores. Primeiramente, os operadores unários, que operam em apenas um valor. Por exemplo, ! (operador de negação) ou o ++ (operador de incremento). No segundo grupo estão os operadores binários, o o grupo que contém a maioria dos operadores que o PHP suporta, com uma lista completa logo abaixo na seção Precedência de operadores.
O terceiro grupo é do operador ternário: ?:. Ele pode ser usado para selecionar entre dois valores dependendo de uma terceira, em vez de selecionar duas sentenças ou encadeamentos de execução. Englobar expressões ternárias com parênteses é uma boa idéia.
Precedência de Operadores
A precedência de um operador especifica quem tem mais prioridade quando há duas delas juntas. Por exemplo, na expressão, 1 + 5 * 3, a resposta é 16 e não 18 porque o operador de multiplicação ("*") tem prioridade de precedência que o operador de adição ("+"). Parênteses podem ser utilizados para forçar a precedência, se necessário. Assim, (1 + 5) * 3 é avaliado como 18. Se a precedência do operador é igual, a associatividade da esquerda para direita é usada.
A tabela seguinte mostra a precedência dos operadores, da maior precedência no começo. Operadores com a mesma precedência estão na mesma linha, no caso a associatividade deles decidide qual ordem eles são avaliados.
| Associação | Operador | Informação adicional |
|---|---|---|
| não associativo | clone new | clone e new |
| esquerda | [ | array() |
| não associativo | ++ -- | incremento/decremento |
| não associativo | ~ - (int) (float) (string) (array) (object) (bool) @ | tipos |
| não associativo | instanceof | tipos |
| direita | ! | lógico |
| esquerda | * / % | aritmético |
| esquerda | + - . | aritmético e string |
| esquerda | << >> | Bit-a-bit |
| não associativo | < <= > >= <> | comparação |
| não associativo | == != === !== | comparação |
| esquerda | & | Bit-a-bit e referências |
| esquerda | ^ | Bit-a-bit |
| esquerda | | | Bit-a-bit |
| esquerda | && | lógico |
| esquerda | || | lógico |
| esquerda | ? : | ternário |
| direita | = += -= *= /= .= %= &= |= ^= <<= >>= | atribuição |
| esquerda | and | lógico |
| esquerda | xor | lógico |
| esquerda | or | lógico |
| esquerda | , | muitos usos |
Associatividade a esquerda significa que a expressão é avaliada da esquerda para direita, associatividade a direita o oposto.
Exemplo #1 Associatividade
<?php
$a = 3 * 3 % 5; // (3 * 3) % 5 = 4
$a = true ? 0 : true ? 1 : 2; // (true ? 0 : true) ? 1 : 2 = 2
$a = 1;
$b = 2;
$a = $b += 3; // $a = ($b += 3) -> $a = 5, $b = 5
?>
Nota:
Mesmo tendo = menor precedência que que outros operadores, o PHP ainda permitirá expressões similares à seguinte: if (!$a = foo()), que no caso o retorno de foo() é recebido em $a.
Operadores Aritméticos
Lembra-se da aritmética básica da escola? Estes operadores funcionam exatamente como aqueles.
| Exemplo | Nome | Resultado |
|---|---|---|
| -$a | Negação | Oposto de $a. |
| $a + $b | Adição | Soma de $a e $b. |
| $a - $b | Subtração | Diferença entre $a e $b. |
| $a * $b | Multiplicação | Produto de $a e $b. |
| $a / $b | Divisão | Quociente de $a por $b. |
| $a % $b | Módulo | Resto de $a dividido por $b. |
O operador de divisão ("/") sempre retorna um valor com ponto flutuante, a não ser que os dois operados seja inteiros (ou strings que são convertidas para inteiros) e numéros inteiramente divisíveis, em outro caso um inteiro é retornado.
Operandos de módulo são convertidos para inteiros (removendo a parte decimal) antes de processar.
Nota: O resto de $a % $b é negativo se $a for negativo.
Veja também a página do manual funções matemáticas.
Operadores de Atribuição
O operador básico de atribuição é "=". A sua primeira inclinação deve ser a de pensar nisto como "é igual". Não. Isto quer dizer, na verdade, que o operando da esquerda recebe o valor da expressão da direita (ou seja, "é configurado para").
O valor de uma expressão de atribuição é o valor atribuído. Ou seja, o valor de "$a = 3" é 3. Isto permite que você faça alguns truques:
<?php
$a = ($b = 4) + 5; // $a é igual a 9 agora e $b foi configurado como 4.
?>
Além do operador básico de atribuição, há "operadores combinados" para todos os operadores aritméticos, de array e string que permitem a você pegar um valor de uma expressão e então usar seu próprio valor para o resultado daquela expressão. Por exemplo:
<?php
$a = 3;
$a += 5; // configura $a para 8, como se disséssemos: $a = $a + 5;
$b = "Bom ";
$b .= "Dia!"; // configura $b para "Bom Dia!", como em $b = $b . "Dia!";
?>
Note que a atribuição copia a variável original para a nova (atribuição por valor), assim a mudança de uma não afeta a outra. Isto pode ter relevância se você precisa copiar algo como uma grande matriz dentro de um loop longo. Atribuições por referência é também suportada, usando a sintaxe $var = &$outra_var;. 'Atribuição por referência' significa que ambas as variáveis acabam apontando para os mesmos dados, e nada é copiado para lugar nenhum. Para aprender mais sobre referências, leia Referências explicadas. No PHP 5, objetos são atribuídos por referência a menos que explícitamente feito o contrário com a nova palavra chave clone.
Operador Bit-a-bit
Operadores bit-a-bit permitem que você acione ou desligue bits específicos dentro de um inteiro. Se ambos os parâmetros da esquerda e da direita forem strings, esses operadores irão trabalhar nos valores ASCII dos caracteres.
<?php
echo 12 ^ 9; // Imprime '5'
echo "12" ^ "9"; // Imprime o caracter de volta (backspace - ASCII 8)
// ('1' (ASCII 49)) ^ ('9' (ASCII 57)) = #8
echo "hallo" ^ "hello"; // Imprime os valores ASCII #0 #4 #0 #0 #0
// 'a' ^ 'e' = #4
echo 2 ^ "3"; // Imprime '1'
// 2 ^ ((int)"3") == 1
echo "2" ^ 3; // Imprime '1'
// ((int)"2") ^ 3 == 1
?>
| Exemplo | Nome | Resultado |
|---|---|---|
| $a & $b | E | Os bits que estão ativos tanto em $a quanto em $b são ativados. |
| $a | $b | OU | Os bits que estão ativos em $a ou em $b são ativados. |
| $a ^ $b | XOR | Os bits que estão ativos em $a ou em $b, mas não em ambos, são ativados. |
| ~ $a | NÃO | Os bits que estão ativos em $a não são ativados, e vice-versa. |
| $a << $b | Deslocamento à esquerda | Desloca os bits de $a $b passos para a esquerda (cada passo significa "multiplica por dois") |
| $a >> $b | Deslocamento à direita | Desloca os bits de $a $b passos para a direita (cada passo significa "divide por dois") |
Não desloque bits à direita maiores que 32 bits em sistemas 32 bits. E também a esquerda no caso do resultado ser um número maior que 32 bits.
Operadores de Comparação
Operadores de comparação, como os seus nomes implicam, permitem que você compare dois valores. Você pode se interessar em ver as tabelas de comparação de tipos, que tem exemplo das várias comparações entre tipos relacionadas.
| Exemplo | Nome | Resultado |
|---|---|---|
| $a == $b | Igual | Verdadeiro (TRUE) se $a é igual a $b. |
| $a === $b | Idêntico | Verdadeiro (TRUE) se $a é igual a $b, e eles são do mesmo tipo (introduzido no PHP4). |
| $a != $b | Diferente | Verdadeiro se $a não é igual a $b. |
| $a <> $b | Diferente | Verdadeiro se $a não é igual a $b. |
| $a !== $b | Não idêntico | Verdadeiro de $a não é igual a $b, ou eles não são do mesmo tipo (introduzido no PHP4). |
| $a < $b | Menor que | Verdadeiro se $a é estritamente menor que $b. |
| $a > $b | Maior que | Verdadeiro se $a é estritamente maior que $b. |
| $a <= $b | Menor ou igual | Verdadeiro se $a é menor ou igual a $b. |
| $a >= $b | Maior ou igual | Verdadeiro se $a é maior ou igual a $b. |
Se você comparar um inteiro com uma string, a string é convertida para um número. Se você comparar 2 strings numéricas, elas serão comparadas como inteiras. Estas regras também se aplicam ao comando switch.
<?php
var_dump(0 == "a"); // 0 == 0 -> true
var_dump("1" == "01"); // 1 == 1 -> true
var_dump("1" == "1e0"); // 1 == 1 -> true
switch ("a") {
case 0:
echo "0";
break;
case "a": // nunca é alcançado porque "a" já foi combinado com 0
echo "a";
break;
}
?>
Para vários tipos, comparações são feitas de acordo com a seguinte tabela (em ordem).
| Tipo do 1º operando | Tipo do 2º operando | Resultado |
|---|---|---|
| null ou string | string | Converte NULL para "", numérico ou comparação léxica |
| bool or null | qualquer | Converte para bool, FALSE < TRUE |
| object | object | Classes nativas podem definir como são comparadas, classes diferentes são incomparáveis, mesma classe - compara propriedades igual faz arrays (PHP 4), PHP 5 tem sua explicação |
| string, resource ou number | string, resource ou number | Transforma strings e resources para números |
| array | array | Array com menos membros é menor, se a chave do operando 1 não é encontrada no operando 2, então os arrays são incomparáveis, caso contrário - compara valor por valor (veja o seguinte exemplo) |
| array | qualquer | array é sempre maior |
| object | qualquer | object é sempre maior |
Exemplo #1 Transcrição do padrão de comparação de array
<?php
// Arrays are compared like this with standard comparison operators
function standard_array_compare($op1, $op2)
{
if (count($op1) < count($op2)) {
return -1; // $op1 < $op2
} elseif (count($op1) > count($op2)) {
return 1; // $op1 > $op2
}
foreach ($op1 as $key => $val) {
if (!array_key_exists($key, $op2)) {
return null; // uncomparable
} elseif ($val < $op2[$key]) {
return -1;
} elseif ($val > $op2[$key]) {
return 1;
}
}
return 0; // $op1 == $op2
}
?>
Veja também strcasecmp(), strcmp(), operadores de array, e a seção do manual sobre Tipos.
Operador Ternário
Outro operador condicional é o operador "?:" (ou ternário).
Exemplo #2 Atribuindo um valor padrão
<?php
// Example usage for: Ternary Operator
$action = (empty($_POST['action'])) ? 'default' : $_POST['action'];
// The above is identical to this if/else statement
if (empty($_POST['action'])) {
$action = 'default';
} else {
$action = $_POST['action'];
}
?>
Nota: Note que o operador ternário é um comando, e ele não é avaliado para uma variável, mas para o resultado do comando. Isto é importante saber se você quer retornar uma variável por referência. O comando return $var == 42 ? $a : $b; em uma função que retorna por referência conseqüêntemente não irá funcionar e será avisado nas últimas versões do PHP.
Nota:
É recomendado para evitar "stacking" de expressões ternárias. O comportamento do PHP quando usando mais de um operador ternário no único comando não é óbvio:
Exemplo #3 Não-óbvio comportamento do ternário
<?php
// o seguinte aparenta imprimir 'true'
echo (true?'true':false?'t':'f');
// conteudo, a saída acima é 't'
// isto por causa da expressão ternário se avaliada da esquerda pra direita
// o seguinte é a versão mais óbvia do mesmo código acima
echo ((true ? 'true' : 'false') ? 't' : 'f');
// aqui, você pode ver que a primeira expressão é avaliada para 'true', que
// por sua vez avalia para (bool)true, assim retornando a parte true da
// segunda expressão ternária.
?>
Operadores de controle de erro
O PHP suporta um operador de controle de erro: o sinal 'arroba' (@). Quando ele precede uma expressão em PHP, qualquer mensagem de erro que possa ser gerada por aquela expressão será ignorada.
Se o recurso track_errors estiver habilitado, qualquer mensagem de erro gerada pela expressão será gravada na variável $php_errormsg. Esta variável será sobrescrita em cada erro, assim verifique-a constantemente se você quiser usá-la.
<?php
/* Erro de arquivo intencional */
$my_file = @file ('arquivo_nao_existente') or
die ("Falha abrindo arquivo: '$php_errormsg'");
// Isto funciona para qualquer expressão, não apenas para funções:
$value = @$cache[$key];
// você não receberá nenhum aviso se a chave $key não existir.
?>
Nota: O operador @ funciona somente em expressões. Uma regra simples para lembrar disso: se você pode pegar o valor de alguma coisa, você pode prefixar isso com o @. Assim, você pode prefixar chamadas de variáveis, funções e include()s, constantes e afins. Você não pode prefixar definições de funções ou classe, estruturas condicionais como o if, foreach e assim por diante.
Veja também error_reporting() e a seção do manual sobre funções de Manipulação de Erros e Logging.
Nota:
O prefixo de controle de erro "@" não desabilita mensagens que são resultado de erros de interpretação (parse errors).
Atualmente, o operador de controle de erro "@" sempre desativa mensagens de erro, mesmo para erros críticos, que terminam a execução de scripts. Além de outras coisas, isto significa que se você usar "@" para suprimir erros de certas funções e elas não estiverem disponíveis ou com tipos incorretos, o script vai parar exatamente aí sem nenhuma indicação da razão.
Operadores de Execução
O PHP suporta um operador de execução: acentos graves (``). Note que não são apóstrofes! O PHP tentará executar o conteúdo dos acentos graves como um comando do shell; a saída será retornada (isto é, ela não será simplesmente descarregada para a saída; ela pode ser atribuída a uma variável). A utilização do operador contra-apóstrofo é idêntica a função shell_exec().
<?php
$output = `ls -al`;
echo "<pre>$output</pre>";
?>
Nota:
O operador de execução fica desabilitado quando safe mode está ativo ou shell_exec() está desabilitado.
Veja também a seção do manual sobre funções de execução de programas, popen() proc_open() e Utilizando o PHP em linha de comando.
Operadores de Incremento/Decremento
O PHP suporta operadores de pré e pós-incremento e decremento no estilo C.
Nota: Os operadores incremento/decremento não afetam valores booleanos. Decrementando valores NULL não há efeito também, mas incrementando resulta em 1.
| Exemplo | Nome | Efeito |
|---|---|---|
| ++$a | Pré-incremento | Incrementa $a em um, e então retorna $a. |
| $a++ | Pós-incremento | Retorna $a, e então incrementa $a em um. |
| --$a | Pré-decremento | Decrementa $a em um, e então retorna $a. |
| $a-- | Pós-decremento | Retorna $a, e então decrementa $a em um. |
Aqui está um script de exemplo simples:
<?php
echo "<h3>Pós-incremento</h3>";
$a = 5;
echo "Deve ser 5: " . $a++ . "<br />\n";
echo "Deve ser 6: " . $a . "<br />\n";
echo "<h3>Pré-incremento</h3>";
$a = 5;
echo "Deve ser 6: " . ++$a . "<br />\n";
echo "Deve ser 6: " . $a . "<br />\n";
echo "<h3>Pós-decremento</h3>";
$a = 5;
echo "Deve ser 5: " . $a-- . "<br />\n";
echo "Deve ser 4: " . $a . "<br />\n";
echo "<h3>Pré-decremento</h3>";
$a = 5;
echo "Deve ser 4: " . --$a . "<br />\n";
echo "Deve ser 4: " . $a . "<br />\n";
?>
O PHP segue a convenção Perl quando tratando operações aritmétricas em variavéis caracter em vez da convenção C. Por exemplo, em Perl 'Z'+1 se torna 'AA', enquanto que no C 'Z'+1 se torna '[' ( ord('Z') == 90, ord('[') == 91 ). Note que variáveis caracter podem ser incrementadas mas não decrementadas e somente caracteres plain ASCII (a-z e A-Z) são suportados.
Exemplo #1 Operações aritmétricas em variáveis caractere
<?php
$i = 'W';
for ($n=0; $n<6; $n++) {
echo ++$i . "\n";
}
?>
O exemplo acima irá imprimir:
X Y Z AA AB AC
Incrementar ou decrementar booleanos não há efeito.
Operadores Lógicos
| Exemplo | Nome | Resultado |
|---|---|---|
| $a and $b | E | Verdadeiro (TRUE) se tanto $a quanto $b são verdadeiros. |
| $a or $b | OU | Verdadeiro se $a ou $b são verdadeiros. |
| $a xor $b | XOR | Verdadeiro se $a ou $b são verdadeiros, mas não ambos. |
| ! $a | NÃO | Verdadeiro se $a não é verdadeiro. |
| $a && $b | E | Verdadeiro se tanto $a quanto $b são verdadeiros. |
| $a || $b | OU | Verdadeiro se $a ou $b são verdadeiros. |
A razão para as duas variantes dos operandos "and" e "or" é que eles operam com precedências diferentes. (Veja Precedência de Operadores.)
Exemplo #1 Ilustrando operadores lógicos
<?php
// foo() nunca será chamada como estes operadores são short-circuit
$a = (false && foo());
$b = (true || foo());
$c = (false and foo());
$d = (true or foo());
// "||" tem maior precedência que "or"
$e = false || true; // $e will be assigned to (false || true) which is true
$f = false or true; // $f will be assigned to false
var_dump($e, $f);
// "&&" tem maior precedência que "and"
$g = true && false; // $g will be assigned to (true && false) which is false
$h = true and false; // $h will be assigned to true
var_dump($g, $h);
?>
O exemplo acima irá imprimir algo similar a:
bool(true) bool(false) bool(false) bool(true)
Operadores de String
Há dois operadores de string. O primeiro é o operador de concatenação ('.'), que retorna a concatenação dos seus argumentos direito e esquerdo. O segundo é o operador de atribuição de concatenação ('.='), que acrescenta o argumento do lado direito no argumento do lado esquerdo. Veja em Operadores de Atribuição para mais informações.
<?php
$a = "Olá ";
$b = $a . "mundo!"; // agora $b contém "Olá mundo!"
$a = "Olá ";
$a .= "mundo!"; // agora $a contém "Olá mundo!"
?>
Veja também as seções do manual sobre o tipo String e as funções de manipulação de Strings.
Operadores de Arrays
| Exemplo | Nome | Resultado |
|---|---|---|
| $a + $b | União | União de $a e $b. |
| $a == $b | Igualdade | TRUE se $a e $b tem os mesmos pares de chave/valor. |
| $a === $b | Identidade | TRUE se $a e $b tem os mesmos pares de chave/valor na mesma ordem e do mesmo tipo. |
| $a != $b | Desigualdade | TRUE se $a não é igual a $b. |
| $a <> $b | Desigualdade | TRUE se $a não é igual a $b. |
| $a !== $b | Não identidade | TRUE se $a não é identico a $b. |
O operador + acrescenta os elementos da direita no array da esquerda, contudo, chaves duplicadas NÃO são sobrescritas.
<?php
$a = array("a" => "maçã", "b" => "banana");
$b = array("a" =>"pêra", "b" => "framboesa", "c" => "morango");
$c = $a + $b; // Uniao de $a e $b
echo "União de \$a e \$b: \n";
var_dump($c);
$c = $b + $a; // União de $b e $a
echo "União de \$b e \$a: \n";
var_dump($c);
?>
União de $a e $b:
array(3) {
["a"]=>
string(5) "maçã"
["b"]=>
string(6) "banana"
["c"]=>
string(6) "morango"
}
União de $b e $a:
array(3) {
["a"]=>
string(4) "pêra"
["b"]=>
string(10) "framboesa"
["c"]=>
string(6) "morango"
}
Elementos do array são iguais para efeitos de comparação se eles possuem o mesmo valor e chave.
Exemplo #1 Comparando arrays
<?php
$a = array("maçã", "banana");
$b = array(1 => "banana", "0" => "maçã");
var_dump($a == $b); // bool(true)
var_dump($a === $b); // bool(false)
?>
Veja também as seções do manual sobre o tipo Array e funções de manipulação de Arrays.
Operadores de tipo
instanceof é usado para determinar se um variável do PHP é uma objeto instânciado de uma certa classe:
Exemplo #1 Usando instanceof com classes
<?php
class MyClass
{
}
class NotMyClass
{
}
$a = new MyClass;
var_dump($a instanceof MyClass);
var_dump($a instanceof NotMyClass);
?>
O exemplo acima irá imprimir:
bool(true) bool(false)
instanceof pode também ser usado para determinar se uma variável é um objeto instânciado de uma classe que herda de uma classe pai:
Exemplo #2 Usando instanceof com herança
<?php
class ParentClass
{
}
class MyClass extends ParentClass
{
}
$a = new MyClass;
var_dump($a instanceof MyClass);
var_dump($a instanceof ParentClass);
?>
O exemplo acima irá imprimir:
bool(true) bool(true)
Para verificar se um objeto não é uma instância de uma classe, o operador lógico not pode ser usado.
Exemplo #3 Usando instanceof para verificar se o objeto não é uma instância da classe
<?php
class MyClass
{
}
$a = new MyClass;
var_dump(!($a instanceof stdClass));
?>
O exemplo acima irá imprimir:
bool(true)
Por fim, instanceof pode também ser usado para determinar se uma variável é um objeto instânciado de uma classe que implementa uma interface:
Exemplo #4 Usando instanceof para classe
<?php
interface MyInterface
{
}
class MyClass implements MyInterface
{
}
$a = new MyClass;
var_dump($a instanceof MyClass);
var_dump($a instanceof MyInterface);
?>
O exemplo acima irá imprimir:
bool(true) bool(true)
Embora instanceof é usualmente usado com um nome de classe literal, ele pode também ser usado com outro objeto ou uma variável string:
Exemplo #5 Usando instanceof com outras variáveis
<?php
interface MyInterface
{
}
class MyClass implements MyInterface
{
}
$a = new MyClass;
$b = new MyClass;
$c = 'MyClass';
$d = 'NotMyClass';
var_dump($a instanceof $b); // $b é umn objeto da classe MyClass
var_dump($a instanceof $c); // $c é uma string 'MyClass'
var_dump($a instanceof $d); // $d é uma string 'NotMyClass'
?>
O exemplo acima irá imprimir:
bool(true) bool(true) bool(false)
Há algumas detalhes para estar ciente. Antes do PHP 5.1.0, instanceof podia chamar __autoload() quando o nome da classe não existe. Em adicional, se a classe não foi carregada, um erro fatal poderia ocorrer. Isto pode funcionar usando a dynamic class reference, ou uma variável string contendo o nome da classe:
Exemplo #6 Evitando que o nome da classe seje verificado e fatal erros com instanceof no PHP 5.0
<?php
$d = 'NotMyClass';
var_dump($a instanceof $d); // não causa erro fatal
?>
O exemplo acima irá imprimir:
bool(false)
O operador instanceof foi introduzido no PHP 5. Antes disso is_a() era usado mas is_a() tornou-se obsoleto pelo instanceof.
Veja também get_class() e is_a().
Estruturas de Controle
Índice
- Introdução
- if
- else
- elseif/else if
- Alternative syntax for control structures
- while
- do-while
- for
- foreach
- break
- continue
- switch
- declare
- return
- require
- include
- require_once
- include_once
- goto
Introdução
Qualquer script PHP é construído por uma série de instruções. Uma instrução pode ser uma atribuição, uma chamada de função, um 'loop', uma instrução condicional, ou mesmo uma instrução que não faz nada (um comando vazio). Instruções geralmente terminam com um ponto e vírgula. Além disso, as instruções podem ser agrupados em um grupo de comandos através do encapsulamento de um grupo de comandos com chaves. Um grupo de comandos é uma instrução também. Os vários tipos de instruções são descritos neste capítulo.
if
(PHP 4, PHP5)
The if construct is one of the most important features of many languages, PHP included. It allows for conditional execution of code fragments. PHP features an if structure that is similar to that of C:
if (expr) statement
As described in the section about expressions, expression is evaluated to its Boolean value. If expression evaluates to TRUE, PHP will execute statement, and if it evaluates to FALSE - it'll ignore it. More information about what values evaluate to FALSE can be found in the 'Converting to boolean' section.
The following example would display a is bigger than b if $a is bigger than $b:
<?php
if ($a > $b)
echo "a is bigger than b";
?>
Often you'd want to have more than one statement to be executed conditionally. Of course, there's no need to wrap each statement with an if clause. Instead, you can group several statements into a statement group. For example, this code would display a is bigger than b if $a is bigger than $b, and would then assign the value of $a into $b:
<?php
if ($a > $b) {
echo "a is bigger than b";
$b = $a;
}
?>
If statements can be nested infinitely within other if statements, which provides you with complete flexibility for conditional execution of the various parts of your program.
else
(PHP 4, PHP5)
Often you'd want to execute a statement if a certain condition is met, and a different statement if the condition is not met. This is what else is for. else extends an if statement to execute a statement in case the expression in the if statement evaluates to FALSE. For example, the following code would display a is greater than b if $a is greater than $b, and a is NOT greater than b otherwise:
<?php
if ($a > $b) {
echo "a is greater than b";
} else {
echo "a is NOT greater than b";
}
?>
elseif/else if
(PHP 4, PHP5)
elseif, as its name suggests, is a combination of if and else. Like else, it extends an if statement to execute a different statement in case the original if expression evaluates to FALSE. However, unlike else, it will execute that alternative expression only if the elseif conditional expression evaluates to TRUE. For example, the following code would display a is bigger than b, a equal to b or a is smaller than b:
<?php
if ($a > $b) {
echo "a is bigger than b";
} elseif ($a == $b) {
echo "a is equal to b";
} else {
echo "a is smaller than b";
}
?>
There may be several elseifs within the same if statement. The first elseif expression (if any) that evaluates to TRUE would be executed. In PHP, you can also write 'else if' (in two words) and the behavior would be identical to the one of 'elseif' (in a single word). The syntactic meaning is slightly different (if you're familiar with C, this is the same behavior) but the bottom line is that both would result in exactly the same behavior.
The elseif statement is only executed if the preceding if expression and any preceding elseif expressions evaluated to FALSE, and the current elseif expression evaluated to TRUE.
Nota: Note that elseif and else if will only be considered exactly the same when using curly brackets as in the above example. When using a colon to define your if/elseif conditions, you must not separate else if into two words, or PHP will fail with a parse error.
<?php
/* Incorrect Method: */
if($a > $b):
echo $a." is greater than ".$b;
else if($a == $b): // Will not compile.
echo "The above line causes a parse error.";
endif;
/* Correct Method: */
if($a > $b):
echo $a." is greater than ".$b;
elseif($a == $b): // Note the combination of the words.
echo $a." equals ".$b;
else:
echo $a." is neither greater than or equal to ".$b;
endif;
?>
Alternative syntax for control structures
(PHP 4, PHP5)
PHP offers an alternative syntax for some of its control structures; namely, if, while, for, foreach, and switch. In each case, the basic form of the alternate syntax is to change the opening brace to a colon (:) and the closing brace to endif;, endwhile;, endfor;, endforeach;, or endswitch;, respectively.
<?php if ($a == 5): ?>
A is equal to 5
<?php endif; ?>
In the above example, the HTML block "A is equal to 5" is nested within an if statement written in the alternative syntax. The HTML block would be displayed only if $a is equal to 5.
The alternative syntax applies to else and elseif as well. The following is an if structure with elseif and else in the alternative format:
<?php
if ($a == 5):
echo "a equals 5";
echo "...";
elseif ($a == 6):
echo "a equals 6";
echo "!!!";
else:
echo "a is neither 5 nor 6";
endif;
?>
Nota:
Mixing syntaxes in the same control block is not supported.
while
(PHP 4, PHP5)
while loops are the simplest type of loop in PHP. They behave just like their C counterparts. The basic form of a while statement is:
while (expr)
statement
The meaning of a while statement is simple. It tells PHP to execute the nested statement(s) repeatedly, as long as the while expression evaluates to TRUE. The value of the expression is checked each time at the beginning of the loop, so even if this value changes during the execution of the nested statement(s), execution will not stop until the end of the iteration (each time PHP runs the statements in the loop is one iteration). Sometimes, if the while expression evaluates to FALSE from the very beginning, the nested statement(s) won't even be run once.
Like with the if statement, you can group multiple statements within the same while loop by surrounding a group of statements with curly braces, or by using the alternate syntax:
while (expr):
statement
...
endwhile;
The following examples are identical, and both print the numbers 1 through 10:
<?php
/* example 1 */
$i = 1;
while ($i <= 10) {
echo $i++; /* the printed value would be
$i before the increment
(post-increment) */
}
/* example 2 */
$i = 1;
while ($i <= 10):
echo $i;
$i++;
endwhile;
?>
do-while
(PHP 4, PHP5)
do-while loops are very similar to while loops, except the truth expression is checked at the end of each iteration instead of in the beginning. The main difference from regular while loops is that the first iteration of a do-while loop is guaranteed to run (the truth expression is only checked at the end of the iteration), whereas it may not necessarily run with a regular while loop (the truth expression is checked at the beginning of each iteration, if it evaluates to FALSE right from the beginning, the loop execution would end immediately).
There is just one syntax for do-while loops:
<?php
$i = 0;
do {
echo $i;
} while ($i > 0);
?>
The above loop would run one time exactly, since after the first iteration, when truth expression is checked, it evaluates to FALSE ($i is not bigger than 0) and the loop execution ends.
Advanced C users may be familiar with a different usage of the do-while loop, to allow stopping execution in the middle of code blocks, by encapsulating them with do-while (0), and using the break statement. The following code fragment demonstrates this:
<?php
do {
if ($i < 5) {
echo "i is not big enough";
break;
}
$i *= $factor;
if ($i < $minimum_limit) {
break;
}
echo "i is ok";
/* process i */
} while (0);
?>
Don't worry if you don't understand this right away or at all. You can code scripts and even powerful scripts without using this 'feature'. Since PHP 5.3.0, it is possible to use goto operator instead of this hack.
for
(PHP 4, PHP5)
for loops are the most complex loops in PHP. They behave like their C counterparts. The syntax of a for loop is:
for (expr1; expr2; expr3)
statement
The first expression (expr1) is evaluated (executed) once unconditionally at the beginning of the loop.
In the beginning of each iteration, expr2 is evaluated. If it evaluates to TRUE, the loop continues and the nested statement(s) are executed. If it evaluates to FALSE, the execution of the loop ends.
At the end of each iteration, expr3 is evaluated (executed).
Each of the expressions can be empty or contain multiple expressions separated by commas. In expr2, all expressions separated by a comma are evaluated but the result is taken from the last part. expr2 being empty means the loop should be run indefinitely (PHP implicitly considers it as TRUE, like C). This may not be as useless as you might think, since often you'd want to end the loop using a conditional break statement instead of using the for truth expression.
Consider the following examples. All of them display the numbers 1 through 10:
<?php
/* example 1 */
for ($i = 1; $i <= 10; $i++) {
echo $i;
}
/* example 2 */
for ($i = 1; ; $i++) {
if ($i > 10) {
break;
}
echo $i;
}
/* example 3 */
$i = 1;
for (; ; ) {
if ($i > 10) {
break;
}
echo $i;
$i++;
}
/* example 4 */
for ($i = 1, $j = 0; $i <= 10; $j += $i, print $i, $i++);
?>
Of course, the first example appears to be the nicest one (or perhaps the fourth), but you may find that being able to use empty expressions in for loops comes in handy in many occasions.
PHP also supports the alternate "colon syntax" for for loops.
for (expr1; expr2; expr3):
statement
...
endfor;
Its a common thing to many users to iterate though arrays like in the example below.
<?php
/*
* This is an array with some data we want to modify
* when running through the for loop.
*/
$people = Array(
Array('name' => 'Kalle', 'salt' => 856412),
Array('name' => 'Pierre', 'salt' => 215863)
);
for($i = 0; $i < sizeof($people); ++$i)
{
$people[$i]['salt'] = rand(000000, 999999);
}
?>
The problem lies in the second for expression. This code can be slow because it has to calculate the size of the array on each iteration. Since the size never change, it can be optimized easily using an intermediate variable to store the size and use in the loop instead of sizeof. The example below illustrates this:
<?php
$people = Array(
Array('name' => 'Kalle', 'salt' => 856412),
Array('name' => 'Pierre', 'salt' => 215863)
);
for($i = 0, $size = sizeof($people); $i < $size; ++$i)
{
$people[$i]['salt'] = rand(000000, 999999);
}
?>
foreach
(PHP 4, PHP5)
The foreach construct provides an easy way to iterate over arrays. foreach works only on arrays and objects, and will issue an error when you try to use it on a variable with a different data type or an uninitialized variable. There are two syntaxes:
foreach (array_expression as $value)
statement
foreach (array_expression as $key => $value)
statement
The first form loops over the array given by array_expression. On each iteration, the value of the current element is assigned to $value and the internal array pointer is advanced by one (so on the next iteration, you'll be looking at the next element).
The second form will additionally assign the current element's key to the $key variable on each iteration.
It is possible to customize object iteration.
Nota:
When foreach first starts executing, the internal array pointer is automatically reset to the first element of the array. This means that you do not need to call reset() before a foreach loop.
As foreach relies on the internal array pointer changing it within the loop may lead to unexpected behavior.
In order to be able to directly modify array elements within the loop precede $value with &. In that case the value will be assigned by reference.
<?php
$arr = array(1, 2, 3, 4);
foreach ($arr as &$value) {
$value = $value * 2;
}
// $arr is now array(2, 4, 6, 8)
unset($value); // break the reference with the last element
?>
Referencing $value is only possible if the iterated array can be referenced (i.e. if it is a variable). The following code won't work:
<?php
foreach (array(1, 2, 3, 4) as &$value) {
$value = $value * 2;
}
?>
Reference of a $value and the last array element remain even after the foreach loop. It is recommended to destroy it by unset().
Nota:
foreach does not support the ability to suppress error messages using '@'.
You may have noticed that the following are functionally identical:
<?php
$arr = array("one", "two", "three");
reset($arr);
while (list(, $value) = each($arr)) {
echo "Value: $value<br />\n";
}
foreach ($arr as $value) {
echo "Value: $value<br />\n";
}
?>
The following are also functionally identical:
<?php
$arr = array("one", "two", "three");
reset($arr);
while (list($key, $value) = each($arr)) {
echo "Key: $key; Value: $value<br />\n";
}
foreach ($arr as $key => $value) {
echo "Key: $key; Value: $value<br />\n";
}
?>
Some more examples to demonstrate usages:
<?php
/* foreach example 1: value only */
$a = array(1, 2, 3, 17);
foreach ($a as $v) {
echo "Current value of \$a: $v.\n";
}
/* foreach example 2: value (with its manual access notation printed for illustration) */
$a = array(1, 2, 3, 17);
$i = 0; /* for illustrative purposes only */
foreach ($a as $v) {
echo "\$a[$i] => $v.\n";
$i++;
}
/* foreach example 3: key and value */
$a = array(
"one" => 1,
"two" => 2,
"three" => 3,
"seventeen" => 17
);
foreach ($a as $k => $v) {
echo "\$a[$k] => $v.\n";
}
/* foreach example 4: multi-dimensional arrays */
$a = array();
$a[0][0] = "a";
$a[0][1] = "b";
$a[1][0] = "y";
$a[1][1] = "z";
foreach ($a as $v1) {
foreach ($v1 as $v2) {
echo "$v2\n";
}
}
/* foreach example 5: dynamic arrays */
foreach (array(1, 2, 3, 4, 5) as $v) {
echo "$v\n";
}
?>
break
(PHP 4, PHP5)
break ends execution of the current for, foreach, while, do-while or switch structure.
break accepts an optional numeric argument which tells it how many nested enclosing structures are to be broken out of.
<?php
$arr = array('one', 'two', 'three', 'four', 'stop', 'five');
while (list(, $val) = each($arr)) {
if ($val == 'stop') {
break; /* You could also write 'break 1;' here. */
}
echo "$val<br />\n";
}
/* Using the optional argument. */
$i = 0;
while (++$i) {
switch ($i) {
case 5:
echo "At 5<br />\n";
break 1; /* Exit only the switch. */
case 10:
echo "At 10; quitting<br />\n";
break 2; /* Exit the switch and the while. */
default:
break;
}
}
?>
continue
(PHP 4, PHP5)
continue is used within looping structures to skip the rest of the current loop iteration and continue execution at the condition evaluation and then the beginning of the next iteration.
Nota: Note that in PHP the switch statement is considered a looping structure for the purposes of continue.
continue accepts an optional numeric argument which tells it how many levels of enclosing loops it should skip to the end of.
Nota:
continue 0; and continue 1; is the same as running continue;.
<?php
while (list($key, $value) = each($arr)) {
if (!($key % 2)) { // skip odd members
continue;
}
do_something_odd($value);
}
$i = 0;
while ($i++ < 5) {
echo "Outer<br />\n";
while (1) {
echo " Middle<br />\n";
while (1) {
echo " Inner<br />\n";
continue 3;
}
echo "This never gets output.<br />\n";
}
echo "Neither does this.<br />\n";
}
?>
Omitting the semicolon after continue can lead to confusion. Here's an example of what you shouldn't do.
<?php
for ($i = 0; $i < 5; ++$i) {
if ($i == 2)
continue
print "$i\n";
}
?>
One can expect the result to be:
0 1 3 4
but this script will output:
2
because the entire continue print "$i\n"; is evaluated as a single expression, and so print() is called only when $i == 2 is true. (The return value of print is passed to continue as the numeric argument.)
switch
(PHP 4, PHP5)
The switch statement is similar to a series of IF statements on the same expression. In many occasions, you may want to compare the same variable (or expression) with many different values, and execute a different piece of code depending on which value it equals to. This is exactly what the switch statement is for.
Nota: Note that unlike some other languages, the continue statement applies to switch and acts similar to break. If you have a switch inside a loop and wish to continue to the next iteration of the outer loop, use continue 2.
Nota:
Note that switch/case does loose comparision.
The following two examples are two different ways to write the same thing, one using a series of if and elseif statements, and the other using the switch statement:
Exemplo #1 switch structure
<?php
if ($i == 0) {
echo "i equals 0";
} elseif ($i == 1) {
echo "i equals 1";
} elseif ($i == 2) {
echo "i equals 2";
}
switch ($i) {
case 0:
echo "i equals 0";
break;
case 1:
echo "i equals 1";
break;
case 2:
echo "i equals 2";
break;
}
?>
Exemplo #2 switch structure allows usage of strings
<?php
switch ($i) {
case "apple":
echo "i is apple";
break;
case "bar":
echo "i is bar";
break;
case "cake":
echo "i is cake";
break;
}
?>
It is important to understand how the switch statement is executed in order to avoid mistakes. The switch statement executes line by line (actually, statement by statement). In the beginning, no code is executed. Only when a case statement is found with a value that matches the value of the switch expression does PHP begin to execute the statements. PHP continues to execute the statements until the end of the switch block, or the first time it sees a break statement. If you don't write a break statement at the end of a case's statement list, PHP will go on executing the statements of the following case. For example:
<?php
switch ($i) {
case 0:
echo "i equals 0";
case 1:
echo "i equals 1";
case 2:
echo "i equals 2";
}
?>
Here, if $i is equal to 0, PHP would execute all of the echo statements! If $i is equal to 1, PHP would execute the last two echo statements. You would get the expected behavior ('i equals 2' would be displayed) only if $i is equal to 2. Thus, it is important not to forget break statements (even though you may want to avoid supplying them on purpose under certain circumstances).
In a switch statement, the condition is evaluated only once and the result is compared to each case statement. In an elseif statement, the condition is evaluated again. If your condition is more complicated than a simple compare and/or is in a tight loop, a switch may be faster.
The statement list for a case can also be empty, which simply passes control into the statement list for the next case.
<?php
switch ($i) {
case 0:
case 1:
case 2:
echo "i is less than 3 but not negative";
break;
case 3:
echo "i is 3";
}
?>
A special case is the default case. This case matches anything that wasn't matched by the other cases. For example:
<?php
switch ($i) {
case 0:
echo "i equals 0";
break;
case 1:
echo "i equals 1";
break;
case 2:
echo "i equals 2";
break;
default:
echo "i is not equal to 0, 1 or 2";
}
?>
The case expression may be any expression that evaluates to a simple type, that is, integer or floating-point numbers and strings. Arrays or objects cannot be used here unless they are dereferenced to a simple type.
The alternative syntax for control structures is supported with switches. For more information, see Alternative syntax for control structures.
<?php
switch ($i):
case 0:
echo "i equals 0";
break;
case 1:
echo "i equals 1";
break;
case 2:
echo "i equals 2";
break;
default:
echo "i is not equal to 0, 1 or 2";
endswitch;
?>
It's possible to use a semicolon instead of a colon after a case like:
<?php
switch($beer)
{
case 'tuborg';
case 'carlsberg';
case 'heineken';
echo 'Good choice';
break;
default;
echo 'Please make a new selection...';
break;
}
?>
declare
(PHP 4, PHP5)
The declare construct is used to set execution directives for a block of code. The syntax of declare is similar to the syntax of other flow control constructs:
declare (directive)
statement
The directive section allows the behavior of the declare block to be set. Currently only two directives are recognized: the ticks directive (See below for more information on the ticks directive) and the encoding directive (See below for more information on the encoding directive).
Nota: The encoding directive was added in PHP 5.3.0
The statement part of the declare block will be executed - how it is executed and what side effects occur during execution may depend on the directive set in the directive block.
The declare construct can also be used in the global scope, affecting all code following it (however if the file with declare was included then it does not affect the parent file).
<?php
// these are the same:
// you can use this:
declare(ticks=1) {
// entire script here
}
// or you can use this:
declare(ticks=1);
// entire script here
?>
Ticks
A tick is an event that occurs for every
N low-level tickable statements executed
by the parser within the declare block.
The value for N is specified
using ticks=N
within the declare blocks's
directive section.
Not all statements are tickable. Typically, condition expressions and argument expressions are not tickable.
The event(s) that occur on each tick are specified using the register_tick_function(). See the example below for more details. Note that more than one event can occur for each tick.
Exemplo #1 Tick usage example
<?php
declare(ticks=1);
// A function called on each tick event
function tick_handler()
{
echo "tick_handler() called\n";
}
register_tick_function('tick_handler');
$a = 1;
if ($a > 0) {
$a += 2;
print($a);
}
?>
Exemplo #2 Ticks usage example
<?php
function tick_handler()
{
echo "tick_handler() called\n";
}
$a = 1;
tick_handler();
if ($a > 0) {
$a += 2;
tick_handler();
print($a);
tick_handler();
}
tick_handler();
?>
See also register_tick_function() and unregister_tick_function().
Encoding
A script's encoding can be specified per-script using the encoding directive.
Exemplo #3 Declaring an encoding for the script.
<?php
declare(encoding='ISO-8859-1');
// code here
?>
When combined with namespaces, the only legal syntax for declare is declare(encoding='...'); where ... is the encoding value. declare(encoding='...') {} will result in a parse error when combined with namespaces.
The encoding declare value is ignored in PHP 5.3 unless php is compiled with --enable-zend-multibyte.
Note that PHP does not expose whether --enable-zend-multibyte was used to compile PHP other than by phpinfo().
return
(PHP 4, PHP5)
If called from within a function, the return() statement immediately ends execution of the current function, and returns its argument as the value of the function call. return() will also end the execution of an eval() statement or script file.
If called from the global scope, then execution of the current script file is ended. If the current script file was include()ed or require()ed, then control is passed back to the calling file. Furthermore, if the current script file was include()ed, then the value given to return() will be returned as the value of the include() call. If return() is called from within the main script file, then script execution ends. If the current script file was named by the auto_prepend_file or auto_append_file configuration options in php.ini, then that script file's execution is ended.
For more information, see Returning values.
Nota: Note that since return() is a language construct and not a function, the parentheses surrounding its arguments are not required. It is common to leave them out, and you actually should do so as PHP has less work to do in this case.
Nota: If no parameter is supplied, then the parentheses must be omitted and NULL will be returned. Calling return() with parentheses but with no arguments will result in a parse error.
Nota: You should never use parentheses around your return variable when returning by reference, as this will not work. You can only return variables by reference, not the result of a statement. If you use return ($a); then you're not returning a variable, but the result of the expression ($a) (which is, of course, the value of $a).
require()
(PHP 4, PHP5)
require() is identical to include() except upon failure it will also produce a fatal E_COMPILE_ERROR level error. In other words, it will halt the script whereas include() only emits a warning (E_WARNING) which allows the script to continue.
See the include() documentation for how this works.
include()
(PHP 4, PHP5)
The include() statement includes and evaluates the specified file.
The documentation below also applies to require().
Files are included based on the file path given or, if none is given, the include_path specified. If the file isn't found in the include_path, include() will finally check in the calling script's own directory and the current working directory before failing. The include() construct will emit a warning if it cannot find a file; this is different behavior from require(), which will emit a fatal error.
If a path is defined — whether absolute (starting with a drive letter or \ on Windows, or / on Unix/Linux systems) or relative to the current directory (starting with . or ..) — the include_path will be ignored altogether. For example, if a filename begins with ../, the parser will look in the parent directory to find the requested file.
For more information on how PHP handles including files and the include path, see the documentation for include_path.
When a file is included, the code it contains inherits the variable scope of the line on which the include occurs. Any variables available at that line in the calling file will be available within the called file, from that point forward. However, all functions and classes defined in the included file have the global scope.
Exemplo #1 Basic include() example
vars.php
<?php
$color = 'green';
$fruit = 'apple';
?>
test.php
<?php
echo "A $color $fruit"; // A
include 'vars.php';
echo "A $color $fruit"; // A green apple
?>
If the include occurs inside a function within the calling file, then all of the code contained in the called file will behave as though it had been defined inside that function. So, it will follow the variable scope of that function. An exception to this rule are magic constants which are evaluated by the parser before the include occurs.
Exemplo #2 Including within functions
<?php
function foo()
{
global $color;
include 'vars.php';
echo "A $color $fruit";
}
/* vars.php is in the scope of foo() so *
* $fruit is NOT available outside of this *
* scope. $color is because we declared it *
* as global. */
foo(); // A green apple
echo "A $color $fruit"; // A green
?>
When a file is included, parsing drops out of PHP mode and into HTML mode at the beginning of the target file, and resumes again at the end. For this reason, any code inside the target file which should be executed as PHP code must be enclosed within valid PHP start and end tags.
If "URL fopen wrappers" are enabled in PHP (which they are in the default configuration), you can specify the file to be included using a URL (via HTTP or other supported wrapper - see Supported Protocols and Wrappers for a list of protocols) instead of a local pathname. If the target server interprets the target file as PHP code, variables may be passed to the included file using a URL request string as used with HTTP GET. This is not strictly speaking the same thing as including the file and having it inherit the parent file's variable scope; the script is actually being run on the remote server and the result is then being included into the local script.
A versões Windows do PHP anteriores ao PHP 4.3.0 não suportam acesso a arquivos remotos através desta função, mesmo se allow_url_fopen estiver ativado.
Exemplo #3 include() through HTTP
<?php
/* This example assumes that www.example.com is configured to parse .php
* files and not .txt files. Also, 'Works' here means that the variables
* $foo and $bar are available within the included file. */
// Won't work; file.txt wasn't handled by www.example.com as PHP
include 'http://www.example.com/file.txt?foo=1&bar=2';
// Won't work; looks for a file named 'file.php?foo=1&bar=2' on the
// local filesystem.
include 'file.php?foo=1&bar=2';
// Works.
include 'http://www.example.com/file.php?foo=1&bar=2';
$foo = 1;
$bar = 2;
include 'file.txt'; // Works.
include 'file.php'; // Works.
?>
Security warning
Remote file may be processed at the remote server (depending on the file extension and the fact if the remote server runs PHP or not) but it still has to produce a valid PHP script because it will be processed at the local server. If the file from the remote server should be processed there and outputted only, readfile() is much better function to use. Otherwise, special care should be taken to secure the remote script to produce a valid and desired code.
See also Remote files, fopen() and file() for related information.
Handling Returns: It is possible to execute a return() statement inside an included file in order to terminate processing in that file and return to the script which called it. Also, it's possible to return values from included files. You can take the value of the include call as you would for a normal function. This is not, however, possible when including remote files unless the output of the remote file has valid PHP start and end tags (as with any local file). You can declare the needed variables within those tags and they will be introduced at whichever point the file was included.
Because include() is a special language construct, parentheses are not needed around its argument. Take care when comparing return value.
Exemplo #4 Comparing return value of include
<?php
// won't work, evaluated as include(('vars.php') == 'OK'), i.e. include('')
if (include('vars.php') == 'OK') {
echo 'OK';
}
// works
if ((include 'vars.php') == 'OK') {
echo 'OK';
}
?>
Exemplo #5 include() and the return() statement
return.php
<?php
$var = 'PHP';
return $var;
?>
noreturn.php
<?php
$var = 'PHP';
?>
testreturns.php
<?php
$foo = include 'return.php';
echo $foo; // prints 'PHP'
$bar = include 'noreturn.php';
echo $bar; // prints 1
?>
$bar is the value 1 because the include was successful. Notice the difference between the above examples. The first uses return() within the included file while the other does not. If the file can't be included, FALSE is returned and E_WARNING is issued.
If there are functions defined in the included file, they can be used in the main file independent if they are before return() or after. If the file is included twice, PHP 5 issues fatal error because functions were already declared, while PHP 4 doesn't complain about functions defined after return(). It is recommended to use include_once() instead of checking if the file was already included and conditionally return inside the included file.
Another way to "include" a PHP file into a variable is to capture the output by using the Output Control Functions with include(). For example:
Exemplo #6 Using output buffering to include a PHP file into a string
<?php
$string = get_include_contents('somefile.php');
function get_include_contents($filename) {
if (is_file($filename)) {
ob_start();
include $filename;
return ob_get_clean();
}
return false;
}
?>
In order to automatically include files within scripts, see also the auto_prepend_file and auto_append_file configuration options in php.ini.
Nota: Este é um construtor de linguagem e não uma função, por isso não é possível chamá-lo através de funções variáveis
See also require(), require_once(), include_once(), get_included_files(), readfile(), virtual(), and include_path.
require_once()
(PHP 4, PHP5)
The require_once() statement is identical to require() except PHP will check if the file has already been included, and if so, not include (require) it again.
See the include_once() documentation for information about the _once behaviour, and how it differs from its non _once siblings.
include_once()
(PHP 4, PHP5)
The include_once() statement includes and evaluates the specified file during the execution of the script. This is a behavior similar to the include() statement, with the only difference being that if the code from a file has already been included, it will not be included again. As the name suggests, it will be included just once.
include_once() may be used in cases where the same file might be included and evaluated more than once during a particular execution of a script, so in this case it may help avoid problems such as function redefinitions, variable value reassignments, etc.
See the include() documentation for information about how this function works.
Nota:
With PHP 4, _once functionality differs with case-insensitive operating systems (like Windows) so for example:
Exemplo #1 include_once() with a case insensitive OS in PHP 4
<?php
include_once "a.php"; // this will include a.php
include_once "A.php"; // this will include a.php again! (PHP 4 only)
?>This behaviour changed in PHP 5, so for example with Windows the path is normalized first so that C:\PROGRA~1\A.php is realized the same as C:\Program Files\a.php and the file is included just once.
goto
(PHP 5 >= 5.3.0)
The goto operator can be used to jump to another section in the program. The target point is specified by a label followed by a colon, and the instruction is given as goto followed by the desired target label. This is not a full unrestricted goto. The target label must be within the same file and context, meaning that you cannot jump out of a function or method, nor can you jump into one. You also cannot jump into any sort of loop or switch structure. You may jump out of these, and a common use is to use a goto in place of a multi-level break.
Exemplo #1 goto example
<?php
goto a;
echo 'Foo';
a:
echo 'Bar';
?>
O exemplo acima irá imprimir:
Bar
Exemplo #2 goto loop example
<?php
for($i=0,$j=50; $i<100; $i++) {
while($j--) {
if($j==17) goto end;
}
}
echo "i = $i";
end:
echo 'j hit 17';
?>
O exemplo acima irá imprimir:
j hit 17
Exemplo #3 This will not work
<?php
goto loop;
for($i=0,$j=50; $i<100; $i++) {
while($j--) {
loop:
}
}
echo "$i = $i";
?>
O exemplo acima irá imprimir:
Fatal error: 'goto' into loop or switch statement is disallowed in script on line 2
Nota:
The goto operator is available as of PHP 5.3.
Funções
Índice
- Funções definidas pelo usuário
- Argumentos de funções
- Retornando valores
- Funções variáveis
- Funções internas (built-in)
- Funções anonimas
Funções definidas pelo usuário
Uma função pode ser definida usando a seguinte sintaxe:
Exemplo #1 Pseudo-código de demonstração de uma função
<?php
function foo ($arg_1, $arg_2, /* ..., */ $arg_n)
{
echo "Exemplo de função.\n";
return $valor_retornado;
}
?>
Qualquer código PHP válido pode aparecer dentro de uma função, mesmo outras funções e definições de classes.
Nomes de funções seguem as mesmas regras que outros rótulo no PHP. Um nome de função válido começa com uma letra ou um sublinhado, seguido, seguido por qualquer número de letras, números ou sublinhado. Com uma expressão regular, seria expressado com: [a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*.
Veja também o Guia de nomenclatura em espaço de usuário.
As funções não precisam ser criadas antes de serem referenciadas, exceto quando uma função é condicionalmente definida como mostrado nos dois exemplos abaixo.
Quando uma função é definida condicionalmente como nos dois exemplos abaixo, sua definição precisa ser processada antes de ser chamada.
Exemplo #2 Funções definidas condicionalmente
<?php
$makefoo = true;
/* Nos nao podemos chamar foo() daqui
porque ela ainda não existe,
mas nos podemos chamar bar() */
bar();
if ($makefoo) {
function foo ()
{
echo "Eu não existo até que o programa passe por aqui.\n";
}
}
/* Agora nos podemos chamar foo()
porque $makefoo foi avaliado como true */
if ($makefoo) foo();
function bar()
{
echo "Eu existo imediatamente desde o programa começar.\n";
}
?>
Exemplo #3 Funções dentro de funções
<?php
function foo()
{
function bar()
{
echo "Eu não existo até foo() ser chamada.\n";
}
}
/* Nós não podemos chamar bar() ainda
porque ela ainda não foi definida. */
foo();
/* Agora nós podemos chamar bar(),
porque o processamento de foo()
tornou a primeira acessivel */
bar();
?>
Todas as funções e classes no PHP tem escopo global - elas podem ser chamadas fora de uma função mesmo que tenham sido definidas dentro e vice-versa.
O PHP não suporta sobrecarga de funções, e também não é possível cancelar ou alterar a definição de funções previamente declaradas.
Nota: Nomes de funções são insensíveis ao caso, mas é melhor chamar as funções da mesma forma que ela aparecem nas declarações.
Ambos número variável de argumentos e argumentos padrões são suportados em funções. veja também as referencias das funções func_num_args(), func_get_arg() e func_get_args() para mais informações.
É possível chamar funções recursivas no PHP. Entretanto evite o uso de funções/métodos recursivos com mais de 100-200 níveis de recursão já que isso pode estourar a pilha e causar o encerramento do script atual.
Exemplo #4 Funções Recursivas
<?php
function recursion($a)
{
if ($a < 20) {
echo "$a\n";
recursion($a + 1);
}
}
?>
Argumentos de funções
Informações podem ser passadas para funções através da lista de argumentos, que é uma lista de expressões delimitados por vírgulas.
O PHP suporta a passagem de argumentos por valor (the default), passagem por referência, e valores padrões de argumentos. lista de argumentos de tamanho variável também são suportadas, veja também a referência das funções func_num_args(), func_get_arg(), e func_get_args() para maiores informações.
Exemplo #1 Passando arrays para funções
<?php
function takes_array($input)
{
echo "$input[0] + $input[1] = ", $input[0]+$input[1];
}
?>
Fazendo argumentos serem passados por referência
Por padrão, argumentos de função são passados por valor (de forma que se você mudar o valor do parâmetro dentro da função, ele não é alterado fora da função). Para permitir que uma função modifique os seus argumentos, eles devem ser passados por referência.
Para ter um argumento para uma função sempre passado por referência, adicione antes dele um "e comercial" (&) ao nome do argumento na definição da função:
Exemplo #2 Passando parâmetros de função por referência
<?php
function add_some_extra(&$string)
{
$string .= ' e alguma coisa mais.';
}
$str = 'Isto é uma string,';
add_some_extra($str);
echo $str; // imprime 'Isto é uma string, e alguma coisa mais.'
?>
Valores padrão de argumentos
Uma função pode definir valores padrão no estilo C++ para argumentos escalares, como a seguir:
Exemplo #3 Utilizando parâmetros padrão em funções
<?php
function cafeteira ($tipo = "cappuccino")
{
return "Fazendo uma xícara de café $tipo.\n";
}
echo cafeteira ();
echo makecoffee(null);
echo cafeteira ("expresso");
?>
A saída do código acima será:
Fazendo uma xícara de café cappucino.
Fazendo uma xícara de .
Fazendo uma xícara de café expresso.
O PHP também permite o uso def arrays e do tipo especial NULL como valores padrões, por exemplo:
Exemplo #4 Usando tipos não escalares como valores padrões
<?php
function makecoffee($types = array("cappuccino"), $coffeeMaker = NULL)
{
$device = is_null($coffeeMaker) ? "hands" : $coffeeMaker;
return "Making a cup of ".join(", ", $types)." with $device.\n";
}
echo makecoffee();
echo makecoffee(array("cappuccino", "lavazza"), "teapot");
?>
O valor padrão precisa ser uma expressão constante, não (por exemplo) uma variável, um membro de classe ou uma chamada de função.
Note que usando argumentos padrão, qualquer padrão deve vir após os argumentos sem padrão: caso contrário, as coisas não funcionarão como esperado. Considere o seguinte trecho de código:
Exemplo #5 Uso incorreto de parâmetros padrão de função
<?php
function iogurtera ($tipo = "azeda", $sabor)
{
return "Fazendo uma taça de $sabor $tipo.\n";
}
echo iogurtera ("framboesa"); // não funciona como esperado
?>
A saída do exemplo acima é:
Warning: Missing argument 2 in call to iogurtera() in
/usr/local/etc/httpd/htdocs/php3test/functest.html on line 41
Fazendo uma taça de framboesa.
Agora, compare o que está acima com este:
Exemplo #6 Uso correto de parâmetros padrão de função
<?php
function iogurtera ($sabor, $tipo = "azeda")
{
return "Fazendo uma taça de $sabor $tipo.\n";
}
echo iogurtera ("framboesa"); // funciona
?>
A saída deste exemplo é:
Fazendo uma taça de framboesa azeda.
Nota: A partir do PHP 5, os valores padrões são passados por referência.
Número variável de argumentos
O PHP4 e posteriores tem suporte para um número variável de argumentos nas funções definidas pelo usuário. Isto é realmente bem fácil, usando as funções func_num_args(), func_get_arg() e func_get_args().
Nenhuma sintaxe especial é requerida, e a lista de argumentos ainda pode ser fornecida explicitamente com as definições de funções e se comportarão normalmente.
Retornando valores
Valores podem ser retornados utilizando a instrução opcional return. Qualquer tipo pode ser retornado, incluindo arrays e objetos. Isto faz com que as função termine sua execução imediatamente e passa o controle de volta para a linha de onde ela foi chamada. Veja a documentação da função return() para maiores informações.
Exemplo #1 O uso de return()
<?php
function quadrado ($num)
{
return $num * $num;
}
echo quadrado (4); // imprime '16'.
?>
Você não pode retornar múltiplos valores a partir de uma função, mas resultados similares podem ser obtidos retornando um array.
Exemplo #2 Retornando um array para devolver vários valores
<?php
function numeros_pequenos()
{
return array (0, 1, 2);
}
list ($zero, $um, $dois) = numeros_pequenos();
?>
Para retornar uma referência de uma função, use o operador de referência & em ambas a declaração da função e quando definindo o valor para a variável.
Exemplo #3 Retornando uma referência de uma função
<?php
function &retorna_referencia()
{
return $alguma_referencia;
}
$nova_referencia =& retorna_referencia();
?>
Para mais detalhes sobre referências, leia a seção Referências.
Funções variáveis
O PHP suporta o conceito de funções variáveis. Isto significa que se um nome de variável tem parênteses no final dela, o PHP procurará uma função com o mesmo nome, qualquer que seja a avaliação da variável, e tentará executá-la. Entre outras coisas, isto pode ser usado para implementar callbacks, tabelas de função e assim por diante.
Funções variáveis não funcionam com construtores de linguagem como echo(), print(), unset(), isset(), empty(), include(), require() e outras assim. Utilize uma função de wrapper para usar quaisquer um destes construtores como uma função variável.
Exemplo #1 Exemplo de funções variáveis
<?php
function foo() {
echo "Chamou foo()<br>\n";
}
function bar($arg = '')
{
echo "Chamou bar(); com argumento '$arg'.<br />\n";
}
// Essa eh uma funcao wrapper para echo()
function echoit($string)
{
echo $string;
}
$func = 'foo';
$func(); // Chama foo()
$func = 'bar';
$func('test'); // Chama bar()
$func = 'echoit';
$func('test'); // Chama echoit()
?>
Um metodo de um objeto também pode ser chamado com a sintaxe de funções variáveis.
Exemplo #2 Exemplo de chama de método variável
<?php
class Foo
{
function MetodoVariavel()
{
$name = 'Bar';
$this->$name(); // Isto chama o método Bar()
}
function Bar()
{
echo "Bar foi chamada!";
}
}
$foo = new Foo();
$funcname = "MetodoVariavel";
$foo->$funcname(); // Isto chama $foo->MetodoVariavel()
?>
Veja também call_user_func(), variáveis variáveis e function_exists().
Funções internas (built-in)
O PHP vem por padrão com muitas funções e contrutores. Também existem funções que necessitam que uma extenção especifica esteja compilada, se não erros fatais "undefined function" (função não definida) irão aparecer. Por exemplo, para usar as funções image como imagecreatetruecolor(), o PHP deve ser compilado com suporte GD. Ou, para usar mysql_connect(), PHP deve ser compilado com suporte MySQL. Existem muitas funções do núcleo que são incluídas em cada versão do PHP, como string e variable. Uma chamada a phpinfo() ou get_loaded_extensions() irá mostras quais extenções estão carregadas no PHP. Note também que várias extenções são ativadas por padrão e que o manual do PHP é dividido por extenção. Veja configução, instalação, e os capitulos individuais das extenções para como configurar o PHP.
A leitura e entendimento de um protótipo de função é explicado na seção do manual entitulada como ler uma definição de função. É importante perceber o que a função retorna ou se a função trabalha diretamente no valor passado como argumento. Por exemplo, str_replace() irá retornar a string modificada enquanto usort() trabalha na própria variável passada no argumento. Cada página do manual também contém informações específicas de cada função, como: parâmetros da função, mudanças de comportamento, valores de retorno tanto para sucesso e erros, como outras informações disponíveis. O conhecimento destas diferenças importantes é crucial para escrever corretamente seu código PHP.
Nota: Se os parâmetros dados a uma função não forem o que ela espera, como passar um array aonde um string é esperado, o valor de retorno da função é indefinido. Neste caso provavelmente irá retornar NULL mas isto é apenas uma convenção, e você não pode depender disso.
Veja também function_exists(), a referência de funções, get_extension_funcs() e dl().
Funções anonimas
funções anonimas, também conhecidas como closures, permitem a criação de funções que não tem o nome especificado. Elas são mais úteis como o valor de parâmetros callback, mas podem tem vários outros usos.
Exemplo #1 Exemplo de Função Anonima
<?php
echo preg_replace_callback('~-([a-z])~', function ($match) {
return strtoupper($match[1]);
}, 'hello-world');
// outputs helloWorld
?>
Closures também podem ser usadas como valores de variáveis; PHP automaticamente converte expessões assim em instancias da classe interna Closure. Definindo um closure a uma variável usa a mesma sintaxe que qualquer outra definição, incluindo o ponto-e-vírgula:
Exemplo #2 Exemplo de como definir uma função anonima para uma variável
<?php
$greet = function($name)
{
printf("Hello %s\r\n", $name);
};
$greet('World');
$greet('PHP');
?>
Closures também podem herdar variáveis do escopo pai. Quaisquer variável assim deve ser declarada no cabeçalho da função. Herdar variáveis do escopo pai não é o mesmo que usar variáveis globais. Variáveis globais existem no escopo global, o qual é o mesmo não importa a função sendo executada. O escopo pai de um closure é a função no qual o closure foi declarado (não necessáriamente a função apartir do qual ele foi chamado). Veja o exemplo a seguir:
Exemplo #3 Closures e escopo
<?php
// A basic shopping cart which contains a list of added products
// and the quantity of each product. Includes a method which
// calculates the total price of the items in the cart using a
// closure as a callback.
class Cart
{
const PRICE_BUTTER = 1.00;
const PRICE_MILK = 3.00;
const PRICE_EGGS = 6.95;
protected $products = array();
public function add($product, $quantity)
{
$this->products[$product] = $quantity;
}
public function getQuantity($product)
{
return isset($this->products[$product]) ? $this->products[$product] :
FALSE;
}
public function getTotal($tax)
{
$total = 0.00;
$callback =
function ($quantity, $product) use ($tax, &$total)
{
$pricePerItem = constant(__CLASS__ . "::PRICE_" .
strtoupper($product));
$total += ($pricePerItem * $quantity) * ($tax + 1.0);
};
array_walk($this->products, $callback);
return round($total, 2);;
}
}
$my_cart = new Cart;
// Add some items to the cart
$my_cart->add('butter', 1);
$my_cart->add('milk', 3);
$my_cart->add('eggs', 6);
// Print the total with a 5% sales tax.
print $my_cart->getTotal(0.05) . "\n";
// The result is 54.29
?>
Funções anonimas são atualmente implementadas usando a classe Closure. Este é um detalhe da implementação e você não deve se importar.
Nota: Funções anonimas estão disponíveis desde PHP 5.3.0.
Nota: É possível usar func_num_args(), func_get_arg(), e func_get_args() de um closure.
Classes e Objetos
Índice
- Introdução
- O Básico
- Properties
- Constantes do Objeto
- Autoloading Objects
- Construtores e Destrutores
- Visibilidade
- Object Inheritance
- Operador de Resolução de Escopo (::)
- Palavra-Chave 'static'
- Abstração de Objetos
- Interfaces de Objetos
- Traits
- Sobrecarga
- Iteração de Objetos
- Patterns
- Métodos Mágicos
- Palavra-Chave 'final'
- Clonando objetos
- Comparando objetos
- Indução de Tipo
- Late Static Bindings
- Objetos e Referências
- Object Serialization
- OOP Changelog
Introdução
Apartir do PHP 5, o modelo de objetos foi rescrito para permitir melhor performance e mais funcionalidades. Esta é uma grande modificação do PHP 4. PHP 5 tem um modelo de objetos completo.
Entre outras novidades do PHP 5 estão a inclusão de visibility, classes e metodos abstract e final, additional metodos mágicos, interfaces, clonagem e dica de tipo.
O PHP trata objetos da mesma maneira que referencias ou manipuladores, significando que cada variável contém uma referencia a um objeto ao invés de uma cópia de todo o objeto. Veja Objetos e Referencias
Veja também o Guia de nomenclatura em espaço de usuário.
O Básico
Classe
Toda definição de classe começa com a palavra-chave class, seguido por um nome da classe, que pode ser qualquer nome que não seja uma palavra reservada no PHP, seguido por um par de chaves, que contém a definição dos membros e métodos da classe. Uma pseudo variável, $this, está disponível quando um método é chamado dentro de um contexto de objeto. $this é uma referência para o objeto chamador do método (normalmente o objeto ao qual o método pertence, mas pode ser outro objeto, se o método é chamado estaticamente no contexto de um objeto secundário). Isso é ilustrado no exemplo a seguir:
Exemplo #1 Variável $this em linguagens com orientação a objetos
<?php
class A
{
function foo()
{
if (isset($this)) {
echo '$this está definida (';
echo get_class($this);
echo ")\n";
} else {
echo "\$this não está definida.\n";
}
}
}
class B
{
function bar()
{
A::foo();
}
}
$a = new A();
$a->foo();
A::foo();
$b = new B();
$b->bar();
B::bar();
?>
O exemplo acima irá imprimir:
$this está definida (A) $this não está definida. $this está definida (B) $this não está definida.
Exemplo #2 Definição de SimpleClass
<?php
class SimpleClass
{
// declaração de membro
public $var = 'um valor padrão';
// declaração de método
public function displayVar() {
echo $this->var;
}
}
?>
O valor padrão deve ser uma expressão constante, não (por exemplo) uma variável, um membro da classe ou uma chamada de função.
Exemplo #3 Valor padrão de membros da classe
<?php
class SimpleClass
{
// declarações de membro inválidas
public $var1 = 'olá '.'mundo';
public $var2 = <<<EOD
olá mundo
EOD;
public $var3 = 1+2;
public $var4 = self::myStaticMethod();
public $var5 = $myVar;
// declarações de membro válidas
public $var6 = myConstant;
public $var7 = self::classConstant;
public $var8 = array(true, false);
}
?>
Nota:
Existem algumas funções legais para lidar com classes e objetos. É bom dar uma olhada nas funções de Classe/Objeto.
Diferente de heredocs, nowdocs pode ser usado no contexto de dado estático.
Exemplo #4 Exemplo com dado estático
<?php
class foo {
// A partir do PHP 5.3.0
public $bar = <<<'EOT'
bar
EOT;
}
?>
Nota:
Suporte a Nowdoc foi adicionado no PHP 5.3.0.
new
Para criar uma instância de uma classe, um novo objeto deve ser criado e atribuído a uma variável. Um objeto sempre será atribuído quando for criado um novo objeto, a não ser que o objeto tenha um construtor definido que dispare uma exceção por um erro. Classes devem ser definidas antes de serem instanciadas (e em alguns casos isso é um requerimento).
Exemplo #5 Criando uma instância
<?php
$instance = new SimpleClass();
?>
No contexto da classe, é possível criar um novo objeto por new self and new parent.
Quando atribuir uma instância já criada de um objeto a uma variável nova, a variável nova irá acessar a mesma instância do objeto que foi atribuído. Esse comportamento se mantém quando passando instâncias a uma função. Uma nova instância de um objeto já criado pode ser feita clonando o mesmo.
Exemplo #6 Atribuição de Objetos
<?php
$assigned = $instance;
$reference =& $instance;
$instance->var = '$assigned terá esse valor';
$instance = null; // $instance e $reference tornam-se nulos
var_dump($instance);
var_dump($reference);
var_dump($assigned);
?>
O exemplo acima irá imprimir:
NULL
NULL
object(SimpleClass)#1 (1) {
["var"]=>
string(30) "$assigned terá esse valor"
}
extends
Uma classe pode herdar métodos e membros de outra classe usando a palavra-chave extends na sua declaração. Não é possível herdar classes múltiplas, uma classe só pode herdar uma classe base.
Os métodos e membros herdados podem ser sobrescritos, a não ser que a classe pai definiu um método como final, redeclarando eles com o mesmo nome definido na classe pai. É possível acessar os métodos sobrescritos ou membros estáticos referenciado-os com parent::
Exemplo #7 Herança da Classe Simples
<?php
class ExtendClass extends SimpleClass
{
// Redefine o método pai
function displayVar()
{
echo "Classe Herdeira\n";
parent::displayVar();
}
}
$extended = new ExtendClass();
$extended->displayVar();
?>
O exemplo acima irá imprimir:
Classe Herdeira um valor padrão
Properties
Class member variables are called "properties". You may also see them referred to using other terms such as "attributes" or "fields", but for the purposes of this reference we will use "properties". They are defined by using one of the keywords public, protected, or private, followed by a normal variable declaration. This declaration may include an initialization, but this initialization must be a constant value--that is, it must be able to be evaluated at compile time and must not depend on run-time information in order to be evaluated.
See Visibilidade for more information on the meanings of public, protected, and private.
Nota:
In order to maintain backward compatibility with PHP 4, PHP 5 will still accept the use of the keyword var in property declarations instead of (or in addition to) public, protected, or private. However, var is no longer required. In versions of PHP from 5.0 to 5.1.3, the use of var was considered deprecated and would issue an E_STRICT warning, but since PHP 5.1.3 it is no longer deprecated and does not issue the warning.
If you declare a property using var instead of one of public, protected, or private, then PHP 5 will treat the property as if it had been declared as public.
Within class methods the properties, constants, and methods may be accessed by using the form $this->property (where property is the name of the property) unless the access is to a static property within the context of a static class method, in which case it is accessed using the form self::$property. See Static Keyword for more information.
The pseudo-variable $this is available inside any class method when that method is called from within an object context. $this is a reference to the calling object (usually the object to which the method belongs, but possibly another object, if the method is called statically from the context of a secondary object).
Exemplo #1 property declarations
<?php
class SimpleClass
{
// invalid property declarations:
public $var1 = 'hello ' . 'world';
public $var2 = <<<EOD
hello world
EOD;
public $var3 = 1+2;
public $var4 = self::myStaticMethod();
public $var5 = $myVar;
// valid property declarations:
public $var6 = myConstant;
public $var7 = array(true, false);
// This is allowed only in PHP 5.3.0 and later.
public $var8 = <<<'EOD'
hello world
EOD;
}
?>
Nota:
There are some nice functions to handle classes and objects. You might want to take a look at the Class/Object Functions.
Unlike heredocs, nowdocs can be used in any static data context, including property declarations.
Exemplo #2 Example of using a nowdoc to initialize a property
<?php
class foo {
// As of PHP 5.3.0
public $bar = <<<'EOT'
bar
EOT;
}
?>
Nota:
Nowdoc support was added in PHP 5.3.0.
Constantes do Objeto
É possível definir valores constantes em cada classe permanecendo a mesma e imutável. Constantes diferem de variáveis normais no não uso do símbolo $ para declará-las ou usá-las.
O valor deve ser uma expressão constante, não podendo ser (por exemplo) uma variável, um membro de uma classe, o resultado de uma operação matemática, ou uma chamada de função.
É possível também interfaces terem constantes. Veja na documentação de interface os exemplos.
No PHP 5.3.0, é possível referenciar a classe usando uma variável. O valor da variável não pode ser uma palavra chave (e.g. self, parent e static).
Exemplo #1 Definindo e usando uma constante
<?php
class MinhaClasse
{
const constante = 'valor constante';
function mostrarConstante() {
echo self::constante . "\n";
}
}
echo MinhaClasse::constante . "\n";
$classname = "MinhaClasse";
echo $classname::constante; // A partir do PHP 5.3.0
$classe = new MinhaClasse();
$classe->mostrarConstante();
echo $classe::constante; // A partir do PHP 5.3.0
?>
Exemplo #2 Exemplo com informação estática
<?php
class foo {
// A partir do PHP 5.3.0
const bar = <<<'EOT'
bar
EOT;
}
?>
Diferente de heredocs, nowdocs pode ser usado no contexto de dado estático.
Nota:
Suporte a nowdoc foi adicionado no PHP 5.3.0.
Autoloading Objects
Muitos desenvolvedores ao desenvolver aplicações orientadas a objeto criam um arquivo PHP para cada definição de classe. Um dos maiores contratempos é ter de escrever uma longa lista de includes no início de cada script(um include para cada classe necessária).
Com PHP 5 isso não é mais necessário. Você pode definir uma função __autoload que é automaticamente chamada no caso de você tentar usar uma classe/interface que ainda não foi definida. Ao chamar essa função o 'scripting engine' tem uma última chance para carregar a classe antes que o PHP falhe com erro.
Nota:
Exceções disparadas em função __autoload não pode ser obtida num bloco catch, resultando em um erro fatal.
Nota:
Autoloading não é disponível usando PHP em modo interativo CLI.
Nota:
Se o nome da classe é usado e.g. em call_user_func() então ela pode conter alguns perigosos caracteres como ../. É recomendado não usar entrada de usuário nestas funções ou verificar a entrada na __autoload().
Exemplo #1 Exemplo de Autoload
Essse exemplo tenta carregar as classes MyClass1 e MyClass2 dos arquivos MyClass1.php e MyClass2.php respectivamente.
<?php
function __autoload($class_name) {
require_once $class_name . '.php';
}
$obj = new MyClass1();
$obj2 = new MyClass2();
?>
Exemplo #2 Outro exemplo de Autoload
Este exemplo tenta carregar a interface ITest.
<?php
function __autoload($name) {
var_dump($name);
}
class Foo implements ITest {
}
/*
string(5) "ITest"
Fatal error: Interface 'ITest' not found in ...
*/
?>
Construtores e Destrutores
Construtores
PHP 5 permite que os desenvolvedores declarem métodos construtores para as classes. Classes que tem um método construtor chamam esse método cada vez que um objeto novo é criado, então é apropriado para qualquer inicialização que o objeto possa vir a precisar antes de ser usado.
Nota: Construtores pais não são chamados implicitamente se a classe filha define um construtor. Para executar o construtor da classe pai, uma chamada a parent::__construct() dentro do construtor da classe filha é necessária.
Exemplo #1 Usando novos construtores unificados
<?php
class BaseClass {
function __construct() {
print "In BaseClass constructor\n";
}
}
class SubClass extends BaseClass {
function __construct() {
parent::__construct();
print "In SubClass constructor\n";
}
}
$obj = new BaseClass();
$obj = new SubClass();
?>
Para garantir compatibilidade reversa, se o PHP 5 não conseguir achar uma __construct() para uma determinada classe, ele procurará pela função construtora à moda-antiga, que tenha o mesmo nome da classe. Efetivamente, significa que o único caso que pode gerar problemas de compatibilidade seria se a classe tiver um método chamado __construct() que fosse usado para outra finalidade que não inicializar o objeto.
Diferente de outros métodos, PHP não irá gerar uma mensagem de erro de nível E_STRICT quando __construct() é sobreescrito com parâmetros diferentes que o método __construct() pai foi definido.
A partir do PHP 5.3.3, métodos com o mesmo nome como último elemento de uma classe dentro de namespace não será mais tratado como construtor. Esta mudança não afeta classe fora de namespace.
Exemplo #2 Construtores em classes dentro de namespace
<?php
namespace Foo;
class Bar {
public function Bar() {
// tratado como construtor no PHP 5.3.0-5.3.2
// tratado como método comum a partir do PHP 5.3.3
}
}
?>
Destrutor
PHP 5 introduz um conceito de destrutor similar ao de outras linguagens orientadas a objeto, como o Java. O método destrutor será chamado assim que todas as referências a um objeto particular forem removidas ou quando o objeto for explicitamente destruído ou qualquer ordem na sequência de encerramento.
Exemplo #3 Exemplo de Destrutor
<?php
class MinhaClasseDestruivel {
function __construct() {
print "No construtor\n";
$this->name = "MinhaClasseDestruivel";
}
function __destruct() {
print "Destruindo " . $this->name . "\n";
}
}
$obj = new MinhaClasseDestruivel();
?>
Como os construtores, destrutores pais não serão chamados implicitamente pelo engine. Para executar o destrutor pai, deve-se fazer uma chamada explicitamente a parent::__destruct() no corpo do destrutor.
Destrutores são chamados durante o encerramento do script tendo os cabeçalhos HTTP enviados. No diretório atual do script a fase de encerramento pode ser diferente com algumas SAPIs (e.g. Apache).
Nota:
Destrutores chamados durante o encerramento da execução do script tem os cabeçalhos HTTP já enviados. O diretório atual na fase de encerramento do script pode ser diferente em alguns SAPIs (e.g. Apache).
Nota:
Tentar disparar uma exceção em um destrutor (chamado no término do script) causa um erro fatal.
Visibilidade
A visibilidade de uma propriedade ou método pode ser definida prefixando a declaração com as palavras-chave: 'public','protected' ou 'private'. Itens declarados como public podem ser acessados por todo mundo. Protected limita o acesso a classes herdadas (e para a classe que define o item). Private limita a visibilidade para apenas a classe que define o item.
Visibilidade dos membros
Membros de uma classe devem ser definidos com public, private, ou protected.
Exemplo #1 Declaração de Membros
<?php
/**
* Define MinhaClasse
*/
class MinhaClasse
{
public $publica = 'Public';
protected $protegida = 'Protected';
private $privada = 'Private';
function imprimeAlo()
{
echo $this->publica;
echo $this->protegida;
echo $this->privada;
}
}
$obj = new MinhaClasse();
echo $obj->publica; // Funciona
echo $obj->protegida; // Erro Fatal
echo $obj->privada; // Erro Fatal
$obj->imprimeAlo(); // Mostra Public, Protected e Private
/**
* Define MinhaClasse2
*/
class MinhaClasse2 extends MinhaClasse
{
// Nós podemos redeclarar as propriedades públicas e protegidas mas não as privadas
protected $protegida = 'Protected2';
function imprimeAlo()
{
echo $this->publica;
echo $this->protegida;
echo $this->privada;
}
}
$obj2 = new MinhaClasse2();
echo $obj2->publica; // Works
echo $obj2->privada; // Undefined
echo $obj2->protegida; // Fatal Error
$obj2->imprimeAlo(); // Mostra Public, Protected2, Undefined
?>
Nota: O uso da declaração de variável com a palavra-chave var ainda é suportada por razões de compatibilidade (como um sinônicom para a palavra-chave public). No PHP 5 antes do 5.1.3, seu uso geraria um aviso do tipo E_STRICT.
Visibilidades de métodos
Métodos de classe devem ser definidos com public, private, ou protected. Métodos sem qualquer declaração são definidas como public.
Exemplo #2 Declaração de método
<?php
/**
* Define MinhaClasse
*/
class MinhaClasse
{
// Declara um construtor público
public function __construct() { }
// Declara um método public
public function MeuPublico() { }
// Declara um método protected
protected function MeuProtegido() { }
// Declara um método private
private function MeuPrivado() { }
// Esse é public
function Foo()
{
$this->MeuPublico();
$this->MeuProtegido();
$this->MeuPrivado();
}
}
$minhaclasse = new MinhaClasse;
$minhaclasse->MeuPublico(); // Funciona
$minhaclasse->MeuProtegido(); // Erro Fatal
$minhaclasse->MeuPrivado(); // Erro Fatal
$minhaclasse->Foo(); // Public, Protected e Private funcionam
/**
* Define MinhaClasse2
*/
class MinhaClasse2 extends MinhaClasse
{
// Esse é public
function Foo2()
{
$this->MeuPublico();
$this->MeuProtegido();
$this->MeuPrivado(); // Erro Fatal
}
}
$minhaclasse2 = new MinhaClasse2;
$minhaclasse2->MeuPublico(); // Funciona
$minhaclasse2->Foo2(); // Public e Protected funcionam, Private não
class Bar
{
public function test() {
$this->testPrivate();
$this->testPublic();
}
public function testPublic() {
echo "Bar::testPublic\n";
}
private function testPrivate() {
echo "Bar::testPrivate\n";
}
}
class Foo extends Bar
{
public function testPublic() {
echo "Foo::testPublic\n";
}
private function testPrivate() {
echo "Foo::testPrivate\n";
}
}
$myFoo = new foo();
$myFoo->test(); // Bar::testPrivate
// Foo::testPublic
?>
Object Inheritance
Inheritance is a well-established programming principle, and PHP makes use of this principle in its object model. This principle will affect the way many classes and objects relate to one another.
For example, when you extend a class, the subclass inherits all of the public and protected methods from the parent class. Unless a class overrides those methods, they will retain their original functionality.
This is useful for defining and abstracting functionality, and permits the implementation of additional functionality in similar objects without the need to reimplement all of the shared functionality.
Nota:
Unless autoloading is used, then classes must be defined before they are used. If a class extends another, then the parent class must be declared before the child class structure. This rule applies to class that inherit other classes and interfaces.
Exemplo #1 Inheritance Example
<?php
class foo
{
public function printItem($string)
{
echo 'Foo: ' . $string . PHP_EOL;
}
public function printPHP()
{
echo 'PHP is great.' . PHP_EOL;
}
}
class bar extends foo
{
public function printItem($string)
{
echo 'Bar: ' . $string . PHP_EOL;
}
}
$foo = new foo();
$bar = new bar();
$foo->printItem('baz'); // Output: 'Foo: baz'
$foo->printPHP(); // Output: 'PHP is great'
$bar->printItem('baz'); // Output: 'Bar: baz'
$bar->printPHP(); // Output: 'PHP is great'
?>
Operador de Resolução de Escopo (::)
O Operador de Resolução de Escopo, também chamado de Paamayim Nekudotayim, ou em termos mais simples, dois pontos duplo, é um token que permite acesso a métodos ou membros estáticos, constantes, e sobrecarregados de uma classe.
Quando referenciando esses itens de fora da definição da classe, você usa o nome da classe.
No PHP 5.3.0, é possível referenciar o nome da classe usando uma variável. O valor da variável não pode ser uma palavra chave (e.g. self, parent e static).
Paamayim Nekudotayim pode parecer, de inicio, uma escolha estranha para um dois pontos duplo. No entanto, na hora de escrever o Engine da Zend 0.5 (que provia o PHP3), foi o que a equipe da Zend decidiu. Realmente significa dois pontos duplo - em Hebreu!
Exemplo #1 :: de fora da definição da classe
<?php
class MinhaClasse {
const VALOR_CONST = 'Um valor constante';
}
$classname = 'MinhaClasse';
echo $classname::VALOR_CONST; // No PHP 5.3.0
echo MinhaClasse::VALOR_CONST;
?>
Duas palavras-chaves especiais self e parent são usadas para acessar membros ou métodos de dentro da definição da classe.
Exemplo #2 :: de dentro da definição da classe
<?php
class OutraClasse extends MinhaClasse {
public static $meu_estatico = 'variável estática';
public static function doisPontosDuplo() {
echo parent::VALOR_CONST . "\n";
echo self::$meu_estatico . "\n";
}
}
$classname = 'OutraClasse';
echo $classname::doisPontosDuplo(); // No PHP 5.3.0
OutraClasse::doisPontosDuplo();
?>
Quando uma subclasse sobrecarrega a definição de um método do pai, php não chamará o método pai. Fica a cargo da subclasse chamar o método pai ou não. Isso também aplica a definições de métodos Construtores and Destrutores, Sobrecarregados e Mágicos também.
Exemplo #3 Chamando um método pai
<?php
class MinhaClasse {
protected function minhaFuncao() {
echo "MinhaClasse::minhaFuncao()\n";
}
}
class OutraClasse extends MinhaClasse {
/* Sobrecarrega a definição do pai */
public function minhaFuncao() {
/* Mas ainda chama a função pai */
parent::minhaFuncao();
echo "OutraClasse::minhaFuncao()\n";
}
}
$classe = new OutraClasse();
$classe->minhaFuncao();
?>
Palavra-Chave 'static'
Declarar membros ou métodos de uma classe como estáticos faz deles acessíveis sem precisar instanciar a classe. Um membro declarados como estático não pode ser acessado com um objeto instanciado da classe (embora métodos estáticos podem).
Por compatibilidade com o PHP 4, se nenhuma declaração de visibilidade for usada, então o membro ou método será tratado como se fosse declarado como public.
Como métodos estáticos podem ser chamados sem uma instância do objeto ter sido criada, a pseudo-variável $this não é disponível dentro do método declarado como estático.
Propriedades estáticas não podem ser acessadas pelo objeto usando o operador seta ->.
Chamar métodos não estáticos de maneira estática gera um aviso de nível E_STRICT.
Como qualquer outra variável estática do PHP, propriedades estáticas podem somente ser inicializadas usando um valor literal ou constante; expressões não são permitidas. Então você pode inicializar uma propriedade estática para um inteiro ou array (por exemplo), você não pode inicializar com outra variável, com um retorno de função, ou um objeto.
No PHP 5.3.0, é possível referenciar a classe usando uma variável. O valor da variável não pode ser uma palavra chave (e.g. self, parent e static).
Exemplo #1 Exemplo de membro estático
<?php
class Foo
{
public static $meu_estatico = 'foo';
public function valorEstatico() {
return self::$meu_estatico;
}
}
class Bar extends Foo
{
public function fooEstatico() {
return parent::$meu_estatico;
}
}
print Foo::$meu_estatico . "\n";
$foo = new Foo();
print $foo->valorEstatico() . "\n";
print $foo->$meu_estatico . "\n"; // "Propriedade" Indefinida $meu_estatico
print $foo::$meu_estatico . "\n";
$classname = 'Foo';
print $classname::$meu_estatico . "\n"; // No PHP 5.3.0
print Bar::$meu_estatico . "\n";
$bar = new Bar();
print $bar->fooEstatico() . "\n";
?>
Exemplo #2 Exemplo de método estático
<?php
class Foo {
public static function umMetodoEstatico() {
// ...
}
}
Foo::umMetodoEstatico();
$classname = 'Foo';
$classname::umMetodoEstatico(); // No PHP 5.3.0
?>
Abstração de Objetos
PHP 5 introduz métodos e classes abstratos. Não é permitido criar uma instância de uma class que foi definida como abstrata. Qualquer classe que contém pelo menos um método abstrato deve também ser abstrata. Métodos definidos como abstratos simplesmente declaram a assinatura do método, eles não podem definir a implementação.
Quando uma classe herda uma classe abstrata, todos os métodos marcados como abstratos na declaração da classe-pai devem ser definidos na classe filha; além disso, esses métodos devem ser definidos com a mesma (ou menos restrita) visibilidade. Por exemplo, se um método abstrado é definido como protected, a implementação da função deve ser definida ou como protected ou public, mas não private.
Exemplo #1 Exemplo de classe abstrata
<?php
abstract class ClasseAbstrata
{
// Força a classe que extende (a subclasse) a definir esse método
abstract protected function pegarValor();
abstract protected function valorComPrefixo( $prefixo );
// Método comum
public function imprimir() {
print $this->pegarValor();
}
}
class ClasseConcreta1 extends ClasseAbstrata
{
protected function pegarValor() {
return "ClasseConcreta1";
}
public function valorComPrefixo( $prefixo ) {
return "{$prefixo}ClasseConcreta1";
}
}
class ClasseConcreta2 extends ClasseAbstrata
{
protected function pegarValor() {
return "ClasseConcreta2";
}
public function valorComPrefixo( $prefixo ) {
return "{$prefixo}ClasseConcreta2";
}
}
$classe1 = new ClasseConcreta1;
$classe1->imprimir();
echo $classe1->valorComPrefixo('FOO_') ."\n";
$classe2 = new ClasseConcreta2;
$classe2->imprimir();
echo $classe2->valorComPrefixo('FOO_') ."\n";
?>
O exemplo acima irá imprimir:
ConcreteClass1 FOO_ConcreteClass1 ConcreteClass2 FOO_ConcreteClass2
Código antigo que não tem classes ou funções definidas pelo usuário como 'abstract' deve ser executado sem modificações.
Interfaces de Objetos
Interfaces de Objetos permite a criação de código que especifica quais métodos e variáveis uma classe deve implementar, sem ter que definir como esses métodos serão tratados.
Interfaces são definidas usando a palavra-chave 'interface', da mesma maneira que uma classe comum, mas sem nenhum dos métodos ter seu conteúdo definido.
Todos os métodos declarados em uma interface devem ser public, essa é a natureza de uma interface.
implements
Para implementar uma interface, o operador implements é usado. Todos os métodos na interface devem ser implementados na classe; não fazer isso resultará em um erro fatal. Classes podem implementar mais de uma interface se assim for desejado, separando cada interface com uma vírgula.
Nota:
Uma classe não pode implementar duas interfaces que compartilham o mesmo nome uma vez que isso causaria ambigüidade.
Nota:
Interfaces podem ser estendidas como classes, usando o operador extends.
Constants
É possível as interfaces terem constantes. Constantes de interfaces funcionam exatamente como class constants. Elas não podem ser sobrescritas por uma classe/interface que a herda.
Exemplos
Exemplo #1 Exemplo de Interface
<?php
// Declara a interface 'iTemplate'
interface iTemplate
{
public function setVariable($name, $var);
public function getHtml($template);
}
// Implementa a interface
// Isso funcionará
class Template implements iTemplate
{
private $vars = array();
public function setVariable($name, $var)
{
$this->vars[$name] = $var;
}
public function getHtml($template)
{
foreach($this->vars as $name => $value) {
$template = str_replace('{' . $name . '}', $value, $template);
}
return $template;
}
}
// Isso NÃO funcionará
// Fatal error: Class BadTemplate contains 1 abstract methods
// and must therefore be declared abstract (iTemplate::getHtml)
class BadTemplate implements iTemplate
{
private $vars = array();
public function setVariable($name, $var)
{
$this->vars[$name] = $var;
}
}
?>
Exemplo #2 Interfaces estendíveis
<?php
interface a
{
public function foo();
}
interface b extends a
{
public function baz(Baz $baz);
}
// Isto irá funcionar
class c implements b
{
public function foo()
{
}
public function baz(Baz $baz)
{
}
}
// Isto não irá funcionar e resultará em um erro fatal
class d implements b
{
public function foo()
{
}
public function baz(Foo $foo)
{
}
}
?>
Exemplo #3 Interface com herança múltipla
<?php
interface a
{
public function foo();
}
interface b
{
public function bar();
}
interface c extends a, b
{
public function baz();
}
class d implements c
{
public function foo()
{
}
public function bar()
{
}
public function baz()
{
}
}
?>
Exemplo #4 Interfaces com constantes
<?php
interface a
{
const b = 'Interface constant';
}
// Imprime: Interface constant
echo a::b;
// Isto não funcionará porque não é permitido
// sobreescrever constantes. É o mesmo conceito como
// constantes de classes
class b implements a
{
const b = 'Class constant';
}
?>
Veja também o operador instanceof.
Traits
As of PHP 5.4.0, PHP implements a method of code reuse called Traits.
Traits is a mechanism for code reuse in single inheritance languages such as PHP. A Trait is intended to reduce some limitations of single inheritance by enabling a developer to reuse sets of methods freely in several independent classes living in different class hierarchies. The semantics of the combination of Traits and classes is defined in a way which reduces complexity, and avoids the typical problems associated with multiple inheritance and Mixins.
A Trait is similar to a class, but only intended to group functionality in a fine-grained and consistent way. It is not possible to instantiate a Trait on its own. It is an addition to traditional inheritance and enables horizontal composition of behavior; that is, the application of class members without requiring inheritance.
Exemplo #1 Trait example
<?php
trait ezcReflectionReturnInfo {
function getReturnType() { /*1*/ }
function getReturnDescription() { /*2*/ }
}
class ezcReflectionMethod extends ReflectionMethod {
use ezcReflectionReturnInfo;
/* ... */
}
class ezcReflectionFunction extends ReflectionFunction {
use ezcReflectionReturnInfo;
/* ... */
}
?>
Precedence
An inherited member from a base class is overridden by a member inserted by a Trait. The precedence order is that members from the current class override Trait methods, which in return override inherited methods.
Exemplo #2 Precedence Order Example
An inherited method from a base class is overridden by the method inserted into MyHelloWorld from the SayWorld Trait. The behavior is the same for methods defined in the MyHelloWorld class. The precedence order is that methods from the current class override Trait methods, which in turn override methods from the base class.
<?php
class Base {
public function sayHello() {
echo 'Hello ';
}
}
trait SayWorld {
public function sayHello() {
parent::sayHello();
echo 'World!';
}
}
class MyHelloWorld extends Base {
use SayWorld;
}
$o = new MyHelloWorld();
$o->sayHello();
?>
O exemplo acima irá imprimir:
Hello World!
Exemplo #3 Alternate Precedence Order Example
<?php
trait HelloWorld {
public function sayHello() {
echo 'Hello World!';
}
}
class TheWorldIsNotEnough {
use HelloWorld;
public function sayHello() {
echo 'Hello Universe!';
}
}
$o = new TheWorldIsNotEnough();
$o->sayHello();
?>
O exemplo acima irá imprimir:
Hello Universe!
Multiple Traits
Multiple Traits can be inserted into a class by listing them in the use statement, separated by commas.
Exemplo #4 Multiple Traits Usage
<?php
trait Hello {
public function sayHello() {
echo 'Hello ';
}
}
trait World {
public function sayWorld() {
echo ' World';
}
}
class MyHelloWorld {
use Hello, World;
public function sayExclamationMark() {
echo '!';
}
}
$o = new MyHelloWorld();
$o->sayHello();
$o->sayWorld();
$o->sayExclamationMark();>
?>
O exemplo acima irá imprimir:
Hello World!
Conflict Resolution
If two Traits insert a method with the same name, a fatal error is produced, if the conflict is not explicitly resolved.
To resolve naming conflicts between Traits used in the same class, the insteadof operator needs to be used to chose exactly one of the conflicting methods.
Since this only allows one to exclude methods, the as operator can be used to allow the inclusion of one of the conflicting methods under another name.
Exemplo #5 Conflict Resolution
In this example, Talker uses the traits A and B. Since A and B have conflicting methods, it defines to use the variant of smallTalk from trait B, and the variant of bigTalk from trait A.
The Aliased_Talker makes use of the as operator to be able to use B's bigTalk implementation under an additional alias talk.
<?php
trait A {
public function smallTalk() {
echo 'a';
}
public function bigTalk() {
echo 'A';
}
}
trait B {
public function smallTalk() {
echo 'b';
}
public function bigTalk() {
echo 'B';
}
}
class Talker {
use A, B {
B::smallTalk insteadof A;
A::bigTalk insteadof B;
}
}
class Aliased_Talker {
use A, B {
B::smallTalk insteadof A;
A::bigTalk insteadof B;
B::bigTalk as talk;
}
}
?>
Changing Method Visibility
Using the as syntax, one can also adjust the visibility of the method in the exhibiting class.
Exemplo #6 Changing Method Visibility
<?php
trait HelloWorld {
public function sayHello() {
echo 'Hello World!';
}
}
// Change visibility of sayHello
class MyClass1 {
use HelloWorld { sayHello as protected; }
}
// Alias method with changed visibility
// sayHello visibility not changed
class MyClass2 {
use HelloWorld { sayHello as private myPrivateHello; }
}
?>
Traits Composed from Traits
Just as classes can make use of traits, so can other traits. By using one or more traits in a trait definition, it can be composed partially or entirely of the members defined in those other traits.
Exemplo #7 Traits Composed from Traits
<?php
trait Hello {
public function sayHello() {
echo 'Hello ';
}
}
trait World {
public function sayWorld() {
echo 'World!';
}
}
trait HelloWorld {
use Hello, World;
}
class MyHelloWorld {
use HelloWorld;
}
$o = new MyHelloWorld();
$o->sayHello();
$o->sayWorld();
?>
O exemplo acima irá imprimir:
Hello World!
Abstract Trait Members
Traits support the use of abstract methods in order to impose requirements upon the exhibiting class.
Exemplo #8 Express Requirements by Abstract Methods
<?php
trait Hello {
public function sayHelloWorld() {
echo 'Hello'.$this->getWorld();
}
abstract public function getWorld();
}
class MyHelloWorld {
private $world;
use Hello;
public function getWorld() {
return $this->world;
}
public function setWorld($val) {
$this->world = $val;
}
}
?>
Static Trait Members
Static variables can be referred to in trait methods, but cannot be defined by the trait. Traits can, however, define static methods for the exhibiting class.
Exemplo #9 Static Variables
<?php
trait Counter {
public function inc() {
static $c = 0;
$c = $c + 1;
echo "$c\n";
}
}
class C1 {
use Counter;
}
class C2 {
use Counter;
}
$o = new C1(); $o->inc(); // echo 1
$p = new C2(); $p->inc(); // echo 1
?>
Exemplo #10 Static Methods
<?php
trait StaticExample {
public static function doSomething() {
return 'Doing something';
}
}
class Example {
use StaticExample;
}
Example::doSomething();
?>
Properties
Traits can also define properties.
Exemplo #11 Defining Properties
<?php
trait PropertiesTrait {
public $x = 1;
}
class PropertiesExample {
use PropertiesTrait;
}
$example = new PropertiesExample;
$example->x;
?>
If a trait defines a property then a class can not define a property with the same name, otherwise an error is issued. It is an E_STRICT if the class definition is compatible (same visibility and initial value) or fatal error otherwise.
Exemplo #12 Conflict Resolution
<?php
trait PropertiesTrait {
public $same = true;
public $different = false;
}
class PropertiesExample {
use PropertiesTrait;
public $same = true; // Strict Standards
public $different = true; // Fatal error
}
?>
Sobrecarga
Sobrecarga em PHP provê recursos para "criar" dinamicamente membros e métodos. Estas entidades dinâmicas são processadas via métodos mágicos que podem estabelecer em uma classe para vários tipos de ações.
Os métodos sobrecarregados são invocados quando interagem com membros ou métodos que não foram declarados ou não são visíveis no escopo corrente. O resto desta seção usará os termos "membros inacessíveis" e "métodos inacessíveis" para se referirir a esta combinação de declaração e visibilidade.
Todos os métodos sobrecarregados devem ser definidos como públicos.
Nota:
Nenhum dos argumentos destes métodos mágicos podem ser passados por referência.
Nota:
A interpretação do PHP de "sobrecarga" é diferente da maioria das linguagens orientadas a objeto. Sobrecarga tradicionalmente provê a habilidade de ter múltiplos métodos com o mesmo nome, mas diferentes quantidades e tipos de argumentos.
Histórico
| Versão | Descrição |
|---|---|
| 5.3.0 | Adicionado __callStatic(). Adicionado warning para reforçar a visibilidade pública e a declaração não estática. |
| 5.1.0 | Adicionados __isset() e __unset(). |
Sobrecarga de membros
__set() é executado ao se escrever dados para membros inacessíveis.
__get() é utilizados para ler dados de membros inacessíveis.
__isset() é disparado para chamar isset() ou empty() em membros inacessíveis.
__unset() é invocado quando unset() é usado em membros inacessíveis.
O argumento $name é o nome do membro com o qual se está interagindo. O argumento $value do método __set() especifica o valor para o qual o membro $name deveria ser setado.
Sobrecarga de membros somente trabalha no contexto de objetos. Estes métodos mágicos não serão disparados no contexto estático. Portanto estes métodos não podem ser declarados static. A partir do PHP 5.3.0, um warning é emitido se algum método mágico sobrecarregado é declarado como static.
Nota:
O valor de retorno de __set() é ignorado por causa da forma que o PHP processa o operador de assimilação. Da mesma forma, __get() nunca é chamado quando encadeando assimilações como essa:
$a = $obj->b = 8;
Nota:
Não é possível utilizar propriedades sobrecarregadas em outros constructos de linguagem além de isset(). Isto significa que se empty() é chamado em uma propriedade sobrecarregada, o método sobrecarregado não é chamado.
Para contornar essa limitação, a propriedade sobrecarregada precisa ser copiada em uma variável local dentro do escopo e então ser manipulada por empty().
Exemplo #1 Sobrecarregando propriedades via __get(), __set(), __isset() and __unset()
<?php
class PropertyTest
{
/** Location for overloaded data. */
private $data = array();
/** Overloading not used on declared properties. */
public $declared = 1;
/** Overloading only used on this when accessed outside the class. */
private $hidden = 2;
public function __set($name, $value)
{
echo "Setting '$name' to '$value'\n";
$this->data[$name] = $value;
}
public function __get($name)
{
echo "Getting '$name'\n";
if (array_key_exists($name, $this->data)) {
return $this->data[$name];
}
$trace = debug_backtrace();
trigger_error(
'Undefined property via __get(): ' . $name .
' in ' . $trace[0]['file'] .
' on line ' . $trace[0]['line'],
E_USER_NOTICE);
return null;
}
/** As of PHP 5.1.0 */
public function __isset($name)
{
echo "Is '$name' set?\n";
return isset($this->data[$name]);
}
/** As of PHP 5.1.0 */
public function __unset($name)
{
echo "Unsetting '$name'\n";
unset($this->data[$name]);
}
/** Not a magic method, just here for example. */
public function getHidden()
{
return $this->hidden;
}
}
echo "<pre>\n";
$obj = new PropertyTest;
$obj->a = 1;
echo $obj->a . "\n\n";
var_dump(isset($obj->a));
unset($obj->a);
var_dump(isset($obj->a));
echo "\n";
echo $obj->declared . "\n\n";
echo "Let's experiment with the private property named 'hidden':\n";
echo "Privates are visible inside the class, so __get() not used...\n";
echo $obj->getHidden() . "\n";
echo "Privates not visible outside of class, so __get() is used...\n";
echo $obj->hidden . "\n";
?>
O exemplo acima irá imprimir:
Setting 'a' to '1' Getting 'a' 1 Is 'a' set? bool(true) Unsetting 'a' Is 'a' set? bool(false) 1 Let's experiment with the private property named 'hidden': Privates are visible inside the class, so __get() not used... 2 Privates not visible outside of class, so __get() is used... Getting 'hidden' Notice: Undefined property via __get(): hidden in <file> on line 70 in <file> on line 29
Sobrecarga de método
__call() é disparado quando invocando métodos inacessíveis em um contexto de objeto.
__callStatic() é disparado quando invocando métodos inacessíveis em um contexto estático.
O argumento $name é o nome do método sendo chamado. O argumento $arguments é um array enumerado contendo os parâmetros passados para o método $name.
Exemplo #2 Sobrecarga de métodos instanciados com __call() e __callStatic()
<?php
class MethodTest
{
public function __call($name, $arguments)
{
// Note: value of $name is case sensitive.
echo "Calling object method '$name' "
. implode(', ', $arguments). "\n";
}
/** As of PHP 5.3.0 */
public static function __callStatic($name, $arguments)
{
// Note: value of $name is case sensitive.
echo "Calling static method '$name' "
. implode(', ', $arguments). "\n";
}
}
$obj = new MethodTest;
$obj->runTest('in object context');
MethodTest::runTest('in static context'); // As of PHP 5.3.0
?>
O exemplo acima irá imprimir:
Calling object method 'runTest' in object context Calling static method 'runTest' in static context
Iteração de Objetos
PHP 5 fornece uma maneira de definir objetos para que seja possível iterar por uma lista de items, como, por exemplo, uma instrução foreach . Por padrão, todas as propriedades visíveis serão usadas para a iteração.
Exemplo #1 Simple Object Iteration
<?php
class MyClass
{
public $var1 = 'value 1';
public $var2 = 'value 2';
public $var3 = 'value 3';
protected $protected = 'protected var';
private $private = 'private var';
function iterateVisible() {
echo "MyClass::iterateVisible:\n";
foreach($this as $key => $value) {
print "$key => $value\n";
}
}
}
$class = new MyClass();
foreach($class as $key => $value) {
print "$key => $value\n";
}
echo "\n";
$class->iterateVisible();
?>
O exemplo acima irá imprimir:
var1 => value 1 var2 => value 2 var3 => value 3 MyClass::iterateVisible: var1 => value 1 var2 => value 2 var3 => value 3 protected => protected var private => private var
Como a saída mostra, o foreach iteragiu por cada uma das variáveis visíveis que podem ser acessadas. Indo um pouco mais longe, você pode implementar uma das interfaces internas do PHP5 chamada Iterator. Isso permite que o objeto decida o que e como o objeto será iterado.
Exemplo #2 Iteração de Objeto implmentando Iterator
<?php
class MyIterator implements Iterator
{
private $var = array();
public function __construct($array)
{
if (is_array($array) ) {
$this->var = $array;
}
}
public function rewind() {
echo "rewinding\n";
reset($this->var);
}
public function current() {
$var = current($this->var);
echo "current: $var\n";
return $var;
}
public function key() {
$var = key($this->var);
echo "key: $var\n";
return $var;
}
public function next() {
$var = next($this->var);
echo "next: $var\n";
return $var;
}
public function valid() {
$var = $this->current() !== false;
echo "valid: {$var}\n";
return $var;
}
}
$values = array(1,2,3);
$it = new MyIterator($values);
foreach ($it as $a => $b) {
print "$a: $b\n";
}
?>
O exemplo acima irá imprimir:
rewinding current: 1 valid: 1 current: 1 key: 0 0: 1 next: 2 current: 2 valid: 1 current: 2 key: 1 1: 2 next: 3 current: 3 valid: 1 current: 3 key: 2 2: 3 next: current: valid:
Você também pode definir sua classe para que ela não tenha que definir todas as funções do Iterator simplesmente implementando a interface IteratorAggregate do PHP 5.
Exemplo #3 Iteração de Objeto implementado IteratorAggregate
<?php
class MyCollection implements IteratorAggregate {
private $items = array();
private $count = 0;
/* Definição requirida da interface IteratorAggregate */
public function getIterator() {
return new MyIterator($this->items);
}
public function add($value) {
$this->items[$this->count++] = $value;
}
}
$coll = new MyCollection();
$coll->add('value 1');
$coll->add('value 2');
$coll->add('value 3');
foreach ($coll as $key => $val) {
echo "key/value: [$key -> $val]\n\n";
}
?>
O exemplo acima irá imprimir:
rewinding current: value 1 valid: 1 current: value 1 key: 0 key/value: [0 -> value 1] next: value 2 current: value 2 valid: 1 current: value 2 key: 1 key/value: [1 -> value 2] next: value 3 current: value 3 valid: 1 current: value 3 key: 2 key/value: [2 -> value 3] next: current: valid:
Nota:
Para mais exemplos de iteração, veja a Extensão SPL.
Patterns
Padrões (Patterns) são formas de descrever melhores práticas e bons projetos. Eles mostram soluções flexíveis para problemas comuns de programação.
Factory
O padrão Factory permite a instanciação de objetos em tempo de execução. É chamado de Factory uma vez que é responsável por "produzir" um objeto. O Factory parametrizado recebe como argumento o nome da classe para instanciar.
Exemplo #1 Método Factory Parametrizado
<?php
class Exemplo
{
// Método Factory parametrizado
public static function factory($type)
{
if (include_once 'Drivers/' . $type . '.php') {
$classname = 'Driver_' . $type;
return new $classname;
} else {
throw new Exception ('Driver não encontrado');
}
}
}
?>
Definir esse método numa classe permite que drivers sejam carregados em tempo de execução. Se a classe Exemplo fosse uma classe de abstração de banco de dados, carregar um driver MySQL e um driver SQLite poderia ser feito como se segue:
<?php
// Carregar um driver MySQL
$mysql = Exemplo::factory('MySQL');
// Carregar um driver SQLite
$sqlite = Exemplo::factory('SQLite');
?>
Singleton
O padrão Singleton se aplica em situações em que é preciso haver uma só instância de uma classe. O exemplo mais comum é uma conexão com um banco de dados. Implementar esse padrão permite ao programador fazer essa instância única ser facilmente acessível por muitos outros objetos.
Exemplo #2 Função Singleton
<?php
class Exemplo
{
// Guarda uma instância da classe
private static $instance;
// Um construtor privado; previne a criação direta do objeto
private function __construct()
{
echo 'Sou um construtor';
}
// O método singleton
public static function singleton()
{
if (!isset(self::$instance)) {
$c = __CLASS__;
self::$instance = new $c;
}
return self::$instance;
}
// Método exemplo
public function latir()
{
echo 'Au!';
}
// Previne que o usuário clone a instância
public function __clone()
{
trigger_error('Clone is not allowed.', E_USER_ERROR);
}
}
?>
Isso permite que uma instância única de Exemplo seja recuperada.
<?php
// Isso falharia porque o construtor é privado
$test = new Exemplo;
// Isso sempre vai recuperar uma instância da classe
$test = Exemplo::singleton();
$test->latir();
// Isso irá emitir um E_USER_ERROR.
$test_clone = clone $test;
?>
Métodos Mágicos
Os nomes de funções __construct, __destruct, __call, __callStatic, __get, __set, __isset, __unset, __sleep, __wakeup, __toString, __invoke, __set_state and __clone são mágicos nas classes do PHP. Você não pode ter funções com esses nomes em nenhuma de suas classes a não ser que queria que a funcionalidade mágica associada com eles.
PHP reserva todas as funções com nomes começando com __ como mágicas. É recomendado que você não use funções com nomes com __ no PHP a não ser que você queira alguma funcionalidade mágica documentada.
__sleep() e __wakeup()
serialize() checa se sua classe tem uma função com o nome mágico __sleep(). Se tiver, a função é executa antes de qualquer serialização. Ela pode limpar o objeto e deve retornar um array com os nomes de todas as variáveis do objeto que devem ser serializadas. Se o método não retornar nada, então NULL é serializada e um E_NOTICE é disparado.
Nota:
Não é possível que __sleep() retorne nomes de propriedades privadas da classe ancestral. Isso causará um erro nível E_NOTICE. Pode-se ser utilizada a interface Serializable se for o caso.
O intuito do método __sleep() enviar dados pendentes ou realizar tarefas similares de limpeza. Além disso, a função é útil se você tiver objetos muito grandes que não precisarão ser salvos completamente.
Inversamente, unserialize() checa pela presença da função com o nome mágico __wakeup(). Se achar, essa função pode reconstruir qualquer recursos que o objeto pode ter.
O intuito do método __wakeup() é reestabelecer qualquer conexão com banco de dados que podem ter sido perdidas durante a serialização e realizar tarefas de reinicialização.
Exemplo #1 Sleep e wakeup
<?php
class Connection
{
protected $link;
private $server, $username, $password, $db;
public function __construct($server, $username, $password, $db)
{
$this->server = $server;
$this->username = $username;
$this->password = $password;
$this->db = $db;
$this->connect();
}
private function connect()
{
$this->link = mysql_connect($this->server, $this->username, $this->password);
mysql_select_db($this->db, $this->link);
}
public function __sleep()
{
return array('server', 'username', 'password', 'db');
}
public function __wakeup()
{
$this->connect();
}
}
?>
__toString()
O método __toString() permite que uma classe decida como se comportar quando for convertida para uma string. Por exemplo, o que echo $obj; irá imprimir. Este método precisa retornar uma string, senão um erro nível E_RECOVERABLE_ERROR é gerado.
Exemplo #2 Exemplo Simples
<?php
// Declare a simple class
class TestClass
{
public $foo;
public function __construct($foo)
{
$this->foo = $foo;
}
public function __toString()
{
return $this->foo;
}
}
$class = new TestClass('Hello');
echo $class;
?>
O exemplo acima irá imprimir:
Hello
Vale lembrar que antes do PHP 5.2.0 o método __toString() só era chamado quando diretamente combinado com echo() ou print(). Desde o PHP 5.2.0, ele é chamado no contexto de string (e.g. em printf() com modificador %s) mas não em outros tipos de contextos (e.g. como modificador %d). Desde o PHP 5.2.0, convertendo objetos sem o método __toString() para string causa E_RECOVERABLE_ERROR.
__invoke()
O método __invoke() é chamado quando um script tenta chamar um objeto como uma função.
Nota:
Esta funcionalidade esta disponível desde o PHP 5.3.0.
Exemplo #3 Usando __invoke
<?php
class CallableClass
{
public function __invoke($x)
{
var_dump($x);
}
}
$obj = new CallableClass;
$obj(5);
var_dump(is_callable($obj));
?>
O exemplo acima irá imprimir:
int(5) bool(true)
__set_state()
Esse método estático é chamado para classes exportadas por var_export() desde PHP 5.1.0.
O único parâmetro para esse método é um array contendo propriedades exportadas no formato array('property' => value, ...).
Exemplo #4 Usando __set_state() (desde o PHP 5.1.0)
<?php
class A
{
public $var1;
public $var2;
public static function __set_state($an_array) // As of PHP 5.1.0
{
$obj = new A;
$obj->var1 = $an_array['var1'];
$obj->var2 = $an_array['var2'];
return $obj;
}
}
$a = new A;
$a->var1 = 5;
$a->var2 = 'foo';
eval('$b = ' . var_export($a, true) . ';'); // $b = A::__set_state(array(
// 'var1' => 5,
// 'var2' => 'foo',
// ));
var_dump($b);
?>
O exemplo acima irá imprimir:
object(A)#2 (2) {
["var1"]=>
int(5)
["var2"]=>
string(3) "foo"
}
Palavra-Chave 'final'
PHP 5 introduz a palavra-chave 'final', que previne que classes filhas sobrecarreguem um método ou variável. Basta prefixar a definição com 'final'.
Exemplo #1 Exemplo de métodos 'final'
<?php
class ClasseBase {
public function teste() {
echo "ClasseBase::teste() chamado\n";
}
final public function maisTeste() {
echo "ClasseBase::maisTeste() chamado\n";
}
}
class ClasseFilha extends ClasseBase {
public function maisTeste() {
echo "ClasseFilha::maisTeste() called\n";
}
}
// Resulta em erro Fatal: Não pode sobrescrever método final ClasseBase::maisTeste()
?>
Exemplo #2 Exemplo de classe Final
<?php
final class ClasseBase {
public function teste() {
echo "Método ClasseBase::teste() chamado\n";
}
// Aqui não importa se você especificar a função como Final ou não
final public function maisTeste() {
echo "Método ClasseBase::maisTeste() chamado\n";
}
}
class ClasseFilha extends ClasseBase {
}
// Resulta em erro Fatal: A classe ClasseFilha não pode herdar de uma classe Final (ClasseBase)
?>
Clonando objetos
Criar uma cópia de um objeto com propriedades totalmente replicadas nem sempre é o comportamento desejado. Um bom exemplo da necessidade para construtores de cópia é se você tem um objeto que representa uma janela do GTK e um objeto guarda o resource dessa janela. Quando você criar uma duplicata, você pode querer criar uma nova janela com as mesmas propriedades e fazer o novo objeto quarda o resource da nova janela. Outro exemplo é se seu objeto guarda uma referência a outro objeto o qual ele usa e quando você replicar o objeto pai, você quer que seja criada uma nova instância desse outro objeto para que a réplica tenha sua própria cópia separada.
Uma cópia de objeto é criada usando a palavra-chave 'clone' (que chama o método __clone() do objeto, se possível). O método __clone() de um objeto não pode ser chamado diretamente.
$copia_do_objeto = clone $objeto;
Quando um objeto é clonado, PHP 5 fará uma cópia superficial de todas as propriedades do objeto. Qualquer propriedade que seja referência a outra variável, permanecerá referência. Se um método __clone() for definido, então este será chamado, permitindo definir qualquer alteração necessária nas propriedades.
Exemplo #1 Clonando um objeto
<?php
class SubObjeto {
static $instancias = 0;
public $instancia;
public function __construct() {
$this->$instancia = ++self::$instancias;
}
public function __clone() {
$this->$instancia = ++self::$instancias;
}
}
class MeuClonavel {
public $objeto1;
public $objeto2;
function __clone() {
// Força uma cópia de this->objeto, ou então
// apontará para o mesmo objeto
$this->objeto1 = clone $this->objeto1;
}
}
$obj = new MeuClonavel();
$obj->objeto1 = new SubObjeto();
$obj->objeto2 = new SubObjeto();
$obj2 = clone $obj;
print("Objeto Original:\n");
print_r($obj);
print("Objeto Clonado:\n");
print_r($obj2);
?>
O exemplo acima irá imprimir:
Objeto Original:
MeuClonavel Object
(
[objeto1] => SubObjeto Object
(
[instancia] => 1
)
[objeto2] => SubObjeto Object
(
[instancia] => 2
)
)
Objeto Clonado:
MeuClonavel Object
(
[objeto1] => SubObjeto Object
(
[instancia] => 3
)
[objeto2] => SubObjeto Object
(
[instancia] => 2
)
)
Comparando objetos
No PHP 5, comparação de objetos é mais complicada que no PHP 4 e mais de acordo com o que é esperado de uma Linguagem Orientada a Objetos (não que PHP 5 seja uma delas).
Quando usar o operador de comparação (==), variáveis objeto são comparadas de maneira simples, nominalmente: Duas instâncias de objetos são iguais se tem os mesmos atributos e valores, e são instâncias da mesma classe.
Por outro lado, quando usando o operador de identidade (===), variáveis objetos são identicas se e somente se elas se referem a mesma instância da mesma classe.
Um exemplo evidenciará essas regras.
Exemplo #1 Exemplo de comparação de objetos no PHP 5
<?php
function bool2str($bool)
{
if ($bool === false) {
return 'FALSO';
} else {
return 'VERDADEIRO';
}
}
function compareObjetos(&$o1, &$o2)
{
echo 'o1 == o2 : '.bool2str($o1 == $o2)."\n";
echo 'o1 != o2 : '.bool2str($o1 != $o2)."\n";
echo 'o1 === o2 : '.bool2str($o1 === $o2)."\n";
echo 'o1 !== o2 : '.bool2str($o1 !== $o2)."\n";
}
class Flag
{
var $flag;
function Flag($flag=true) {
$this->flag = $flag;
}
}
class OutraFlag
{
var $flag;
function OutraFlag($flag=true) {
$this->flag = $flag;
}
}
$o = new Flag();
$p = new Flag();
$q = $o;
$r = new OutraFlag();
echo "Duas instâncias da mesma classe\n";
compareObjetos($o, $p);
echo "\nDuas referências para a mesma instância\n";
compareObjetos($o, $q);
echo "\nInstâncias de duas classes diferentes\n";
compareObjetos($o, $r);
?>
O exemplo acima irá imprimir:
Duas instâncias da mesma classe o1 == o2 : VERDADEIRO o1 != o2 : FALSO o1 === o2 : FALSO o1 !== o2 : VERDADEIRO Duas referências para a mesma instância o1 == o2 : VERDADEIRO o1 != o2 : FALSO o1 === o2 : VERDADEIRO o1 !== o2 : FALSO Instâncias de duas classes diferentes o1 == o2 : FALSO o1 != o2 : VERDADEIRO o1 === o2 : FALSO o1 !== o2 : VERDADEIRO
Nota:
Extensões podem definir suas regras para comparação de objetos.
Indução de Tipo
PHP 5 introduz Indução de Tipo. Funções podem forçar que os parâmetros sejam objetos (especificando o nome da classe no protótipo da função) ou array (a partir do PHP 5.1). Contudo, se NULL é usado como o valor padrão do parametro, ele será permitido como um argumento nas chamadas à função.
Exemplo #1 Exemplo Indução de Tipo
<?php
// Uma classe de exemplo
class MinhaClasse
{
/**
* Uma função de teste
*
* Primeiro parâmetro deve ser um objeto do tipo OutraClasse
*/
public function teste(OutraClasse $outraclasse) {
echo $outraclasse->var;
}
/**
* Outra função de teste
*
* Primeiro parâmetro deve ser um array
*/
public function testa_array(array $array_de_entrada) {
print_r($array_de_entrada);
}
}
// Outro classe de exemplo
class OutraClasse {
public $var = 'Alô Mundo';
}
?>
Não satisfazer a indução de tipo resulta em erro fatal (Catchable fatal error).
<?php
// Uma instância de cada classe
$minhaclasse = new MinhaClasse;
$outraclasse = new OutraClasse;
// Erro Fatal: Argumento 1 deve ser um objeto da classe OutraClasse
$minhaclasse->teste('hello');
// Erro Fatal: Argumento 1 deve ser uma instância de OutraClasse
$foo = new stdClass;
$minhaclasse->teste($foo);
// Erro Fatal: Argumento 1 deve ser diferente de null
$minhaclasse->teste(null);
// Funciona: Imprime Alô Mundo
$minhaclasse->teste($outraclasse);
// Erro Fatal: Argumento 1 deve ser um array
$minhaclasse->testa_array('a string');
// Funciona: Imprime o array
$minhaclasse->testa_array(array('a', 'b', 'c'));
?>
Indução de tipo também funciona com funções:
<?php
// Um exemplo de classe
class MinhaClasse {
public $var = 'Alô Mundo';
}
/**
* Uma função de teste
*
* Primeiro parâmetro deve ser um objeto do tipo MinhaClasse
*/
function MinhaFuncao (MinhaClasse $foo) {
echo $foo->var;
}
// Funciona
$minhaclasse = new MinhaClasse;
MinhaFuncao($minhaclasse);
?>
Type hinting permitindo valor NULL:
<?php
/* Aceitando valor NULL value */
function test(stdClass $obj = NULL) {
}
test(NULL);
test(new stdClass);
?>
Indução de tipo só pode ser usado com tipos objetos. Indução tradicional com int e string não são suportados.
Late Static Bindings
No PHP 5.3.0, o PHP implementa um recurso chamado late static bindings que pode ser usado para referenciar a classe chamada no contexto de herança estática.
Este recurso foi nomeado "late static bindings" com um pespectiva interna em mente. "Late binding" vem do fato que static:: não ser mais resolvido usando a classe onde o mesmo é definido mas ele será avaliado usando informação em tempo de execução. Ele foi também chamado "static binding" como pode ser usado para (mas não é limitado para) chamada de métodos estáticos.
Limitações do self::
Referências estáticas para a atual classe como self:: ou __CLASS__ são resolvidas usando a classe na qual a função pertence, como onde ele foi definido:
Exemplo #1 Uso do self::
<?php
class A {
public static function who() {
echo __CLASS__;
}
public static function test() {
self::who();
}
}
class B extends A {
public static function who() {
echo __CLASS__;
}
}
B::test();
?>
O exemplo acima irá imprimir:
A
Uso de Late Static Bindings
Late static bindings tenta resolver a limitação introduzindo uma palavra-chave que referencia a classe que foi inicialiamente chamada em runtime. Basicamente, uma palavra-chave que permite você referenciar B em test() no exemplo anterior. Foi decidido não introduzir uma nova palavra-chave, mas usar static que já foi reservado.
Exemplo #2 Simples uso do static::
<?php
class A {
public static function who() {
echo __CLASS__;
}
public static function test() {
static::who(); // Here comes Late Static Bindings
}
}
class B extends A {
public static function who() {
echo __CLASS__;
}
}
B::test();
?>
O exemplo acima irá imprimir:
B
Nota:
static:: não funciona como $this para métodos estáticos! $this-> segue a regra de herança quando static:: não o faz. Esta diferença é detalhada depois nesta página.
Exemplo #3 Uso do static:: em um contexto não-estático
<?php
class TestChild extends TestParent {
public function __construct() {
static::who();
}
public function test() {
$o = new TestParent();
}
public static function who() {
echo __CLASS__."\n";
}
}
class TestParent {
public function __construct() {
static::who();
}
public static function who() {
echo __CLASS__."\n";
}
}
$o = new TestChild;
$o->test();
?>
O exemplo acima irá imprimir:
TestChild TestParent
Nota:
A resolução do Late static bindings termina em uma chamada estática inteiramente resolvida sem volta. Por outro lado, chamadas estáticas usando palavras-chave como parent:: ou self:: encaminharão a informação.
Exemplo #4 Chamadas encaminhadas e não-encaminhadas
<?php
class A {
public static function foo() {
static::who();
}
public static function who() {
echo __CLASS__."\n";
}
}
class B extends A {
public static function test() {
A::foo();
parent::foo();
self::foo();
}
public static function who() {
echo __CLASS__."\n";
}
}
class C extends B {
public static function who() {
echo __CLASS__."\n";
}
}
C::test();
?>O exemplo acima irá imprimir:
A C C
Edge cases
Há várias diferentes formas de ser chamado um método no PHP, como callbacks ou métodos mágicos. Como late static bindings baseia sua resolução em informação em runtine, ele pode dar resultados inesperados em então chamados edge cases.
Exemplo #5 Late static bindings em métodos mágicos
<?php
class A {
protected static function who() {
echo __CLASS__."\n";
}
public function __get($var) {
return static::who();
}
}
class B extends A {
protected static function who() {
echo __CLASS__."\n";
}
}
$b = new B;
$b->foo;
?>
O exemplo acima irá imprimir:
B
Objetos e Referências
Um dos pontos-chave da programação orientada a objetos no PHP5 que é frequentemente mencionado é que "objetos são passados por referências por padrão". Isto não é completamente verdade. Esta seção retifica esse pensamento geral usando alguns exemplos.
Uma referência PHP é um alias, que permite duas variáveis diferentes escreverem para o mesmo valor. A partir do PHP5, uma variável objeto não contém mais o próprio objeto como valor. Ela contém um identificador do objeto que permite que os acessadores do objeto encontrem o objeto real. Quando um objeto é enviado por argumento, retornado ou atribuído para outra variável, as variáveis diferentes não são aliases: elas armazenam uma cópia do identificador, que aponta para o mesmo objeto.
Exemplo #1 Referências e Objetos
<?php
class A {
public $foo = 1;
}
$a = new A;
$b = $a; // $a and $b are copies of the same identifier
// ($a) = ($b) = <id>
$b->foo = 2;
echo $a->foo."\n";
$c = new A;
$d = &$c; // $c and $d are references
// ($c,$d) = <id>
$d->foo = 2;
echo $c->foo."\n";
$e = new A;
function foo($obj) {
// ($obj) = ($e) = <id>
$obj->foo = 2;
}
foo($e);
echo $e->foo."\n";
?>
O exemplo acima irá imprimir:
2 2 2
Object Serialization
Serializing objects - objects in sessions
serialize() returns a string containing a byte-stream representation of any value that can be stored in PHP. unserialize() can use this string to recreate the original variable values. Using serialize to save an object will save all variables in an object. The methods in an object will not be saved, only the name of the class.
In order to be able to unserialize() an object, the class of that object needs to be defined. That is, if you have an object of class A and serialize this, you'll get a string that refers to class A and contains all values of variables contained in it. If you want to be able to unserialize this in another file, an object of class A, the definition of class A must be present in that file first. This can be done for example by storing the class definition of class A in an include file and including this file or making use of the spl_autoload_register() function.
<?php
// classa.inc:
class A {
public $one = 1;
public function show_one() {
echo $this->one;
}
}
// page1.php:
include("classa.inc");
$a = new A;
$s = serialize($a);
// store $s somewhere where page2.php can find it.
file_put_contents('store', $s);
// page2.php:
// this is needed for the unserialize to work properly.
include("classa.inc");
$s = file_get_contents('store');
$a = unserialize($s);
// now use the function show_one() of the $a object.
$a->show_one();
?>
If an application is using sessions and uses session_register() to register objects, these objects are serialized automatically at the end of each PHP page, and are unserialized automatically on each of the following pages. This means that these objects can show up on any of the application's pages once they become part of the session. However, the session_register() is removed since PHP 5.4.0.
It is strongly recommended that if an application serializes objects, for use later in the application, that the application include the class definition for that object throughout the application. Not doing so might result in an object being unserialized without a class definition, which will result in PHP giving the object a class of __PHP_Incomplete_Class_Name, which has no methods and would render the object useless.
So if in the example above $a became part of a session by running session_register("a"), you should include the file classa.inc on all of your pages, not only page1.php and page2.php.
OOP Changelog
Changes to the PHP 5 OOP model are logged here. Descriptions and other notes regarding these features are documented within the OOP 5 documentation.
| Versão | Descrição |
|---|---|
| 5.4.0 | Changed: If an abstract class defines a signature for the constructor it will now be enforced. |
| 5.3.3 | Changed: Methods with the same name as the last element of a namespaced class name will no longer be treated as constructor. This change doesn't affect non-namespaced classes. |
| 5.3.0 | Changed: Classes that implement interfaces with methods that have default values in the prototype are no longer required to match the interface's default value. |
| 5.3.0 | Changed: It's now possible to reference the class using a variable (e.g., echo $classname::constant;). The variable's value can not be a keyword (e.g., self, parent or static). |
| 5.3.0 | Changed: An E_WARNING level error is issued if the magic overloading methods are declared static. It also enforces the public visibility requirement. |
| 5.3.0 | Changed: Prior to 5.3.0, exceptions thrown in the __autoload() function could not be caught in the catch block, and would result in a fatal error. Exceptions now thrown in the __autoload function can be caught in the catch block, with one proviso. If throwing a custom exception, then the custom exception class must be available. The __autoload function may be used recursively to autoload the custom exception class. |
| 5.3.0 | Added: The __callStatic method. |
| 5.3.0 | Added: heredoc and nowdoc support for class const and property definitions. Note: heredoc values must follow the same rules as double-quoted strings, (e.g., no variables within). |
| 5.3.0 | Added: Late Static Bindings. |
| 5.3.0 | Added: The __invoke() method. |
| 5.2.0 | Changed: The __toString() method was only called when it was directly combined with echo() or print(). But now, it is called in any string context (e.g. in printf() with %s modifier) but not in other types contexts (e.g. with %d modifier). Since PHP 5.2.0, converting objects without a __toString method to string emits a E_RECOVERABLE_ERROR level error. |
| 5.1.3 | Changed: In previous versions of PHP 5, the use of var was considered deprecated and would issue an E_STRICT level error. It's no longer deprecated, therefore does not emit the error. |
| 5.1.0 | Changed: The __set_state() static method is now called for classes exported by var_export(). |
| 5.1.0 | Added: The __isset() and __unset() methods. |
Namespaces
Índice
- Namespaces - Visão geral
- Definição de Namespace
- Usando namespaces
- Espaço global
- __NAMESPACE__
- Regras de resolução de nomes
Namespaces - Visão geral
Namespaces no PHP são projetados para resolver problema de escopo em bibliotecas PHP extensas. No PHP, todas as definições de classes são globais. Assim, quando uma autor de uma biblioteca cria vários utilitários ou públicas classes para uma biblioteca, ele precisa ter cuidado com a possibilidade de outra biblioteca com mesma funcionalidade exista e assim escolher nomes únicos para que estas bibliotecas possam ser usadas juntas. Normalmente isto é resolvido prefixando o nome da classe com uma string única - e.g., classes de banco de dados tem prefixo My_Library_DB, etc. Com o crescimento da biblioteca, mais prefixos são adicionados, criando então nomes grandes.
Os namespaces permitem o desenvolvedor manusear nomes num escopo sem usar nomes grandes cada vez que a classe for referenciada, e resolver o problema de espaço global compartilhado sem fazer um código ilegível.
Namespaces está disponível a partir do PHP 5.3.0. Esta seção é experimental e sujeita a mudanças.
Definição de Namespace
O namespace é declarado usando a palavra chave namespace, que deve ser usada logo no começo do arquivo. Exemplo:
Exemplo #1 Defining namespace
<?php
namespace MyProject\DB;
const CONNECT_OK = 1;
class Connection { /* ... */ }
function connect() { /* ... */ }
?>
Namespace pode conter definições de classes, constantes e funções, mas não código livre.
Definição do Namespace fazem seguinte:
- Dentro do namespace, todas os nomes de as classes, funções e constantes na definição são automaticamente prefixados com o nome do namespace. O nome da classe é sempre o nome completo, i.e. no exemplo acima a classe é chamada MyProject\DB\Connection.
- Definição de constantes criam constantes que são compostas do nome do namespace e o nome da constante. Com constantes de classes, constantes do namespace podem somente conter valores estáticos.
-
Nome não qualificado de classe (i.e., nome não contém \) são resolvido em runtime seguindo este procedimento:
- A classe é verificada dentro do atual namespace (i.e. prefixando o nome com o atual nome do namespace) sem tentar fazer autoload.
- A classe é verificada dentro do namespace global sem tentar fazer autoload.
- É tentado autoloading para nomes no namespace atual.
- Se anteriormente falhou, a verificação falha.
-
Nome não qualificado de função (i.e., nome não contém \) é verificado em tempo de execução primeiro no namespace atual e então no espaço global.
-
Nome de constantes não qualificada são verificadas primeiro no namespace atual e então entre as constantes globalmente definidas.
Usando namespaces
Cada classe e função em um namespace pode ser referenciado pelo nome completo - e.g. MyProject\DB\Connection ou MyProject\DB\connect - em algum momento.
Exemplo #1 Usando o nome com namespace
<?php
require 'MyProject/Db/Connection.php';
$x = new MyProject\DB\Connection;
MyProject\DB\connect();
?>
Namespaces podem ser importados para o contexto atual (global ou namespace) usando o operador use. A sintaxe para o operador é:
<?php
/* ... */
use Some\Name as Othername;
// The simplified form of use:
use Foo\Bar;
// which is the same as :
use Foo\Bar as Bar;
?>
use pode ser usado somente no escopo global, não dentro de função ou classe. Nomes importados tem efeito a partir do ponto do import até o final do arquivo atual. Ele é recomendado colocá-lo no início do arquivo para evitar confusão.
Exemplo #2 Importando e acessando namespace
<?php
require 'MyProject/Db/Connection.php';
use MyProject\DB;
use MyProject\DB\Connection as DbConnection;
$x = new MyProject\DB\Connection();
$y = new DB\connection();
$z = new DbConnection();
DB\connect();
?>
Nota: A operação import é apenas em tempo de compilação, todos nomes locais são convertidos para seus equivalentes nomes completos pelo compilador. Note que não é traduzido nomes em strings, então callbacks não respeitará regras do import.
Espaço global
Sem definição de namespace, todas as definições de classes e funções são colocadas no espaço global - como era feito no PHP antes dos namespaces serem suportado. Prefixando o nome com \ especificará que o nome é requerido do espaço global até mesmo no contexto do namespace.
Exemplo #1 Usando a especificação de espaço global
<?php
namespace A\B\C;
/* This function is A\B\C\fopen */
function fopen() {
/* ... */
$f = \fopen(...); // call global fopen
return $f;
}
?>
__NAMESPACE__
A constante __NAMESPACE__ em tempo de compilação é definida para o nome do atual namespace. Fora do namespace esta constante tem o valor de string vazia. Esta constante é útil quando precisa compor nome completo para nomes do namespace local.
Exemplo #1 Usando __NAMESPACE__
<?php
namespace A\B\C;
function foo() {
// do stuff
}
set_error_handler(__NAMESPACE__ . "\foo");
?>
Regras de resolução de nomes
Nomes são resolvidos seguindo estas regras de resolução:
-
Todos nomes qualificados são traduzidos durante a compilação de acordo com a
atual regra do import. Por exemplo, se o namespace A\B\C é importado, uma chamada para
C\D\e()é traduzida paraA\B\C\D\e(). -
Nomes não qualificados de classes são traduzidos durante compilação de acordo com a atual
regra de import (nome completo substituído pelo pequeno nome importado). Por exemplo, se
o namespace A\B\C é importado,
new C()é traduzido paranew A\B\C(). - Dentro do namespace, chamadas para nomes não qualificados de funções que são definidos no atual namespace (e é conhecido na hora que a chamada é analisada) são interpretados como chamadas para estas funções do namespace, em tempo de compilação.
-
Dentro do namespace (digo A\B), chamadas para funções não qualificadas que não são
definidas no atual namespace são resolvidos em tempo de execução. Veja
como uma chamada para uma função foo() é resolvida:
- Ele procura por uma função do atual namespace: A\B\foo().
- Ele procura e tenta chamar a função interna foo().
-
Dentro do namespace (digo A\B), chamadas para não
qualificados nomes de classes são resolvidos em tempo de execução.
Veja como uma chamada para
new C()é resolvida:- Ele verifica por uma classe do namespace atual: A\B\C.
- Ele tenta buscar e chamar a classe interna C.
- Ele tenta fazer autoload A\B\C.
new \C()tem que ser usado. -
Chamadas para qualificadas funções são resolvidas em tempo de execução.
Veja como a chamada para A\B\foo() é resolvida:
- Ele verifica por uma função foo() no namespace A\B.
- Ele verifica por uma classe A\B e chama o método estático foo(). Irá fazer autoload da class se necessário.
-
Qualificados nomes de classes são resolvidos em tempo de compilação como classes
correspondentes do namespace. Por exemplo,
new A\B\C()refere-se a classe C do namespace A\B.
Exemplo #1 Ilustrando resolução de nomes
<?php
namespace A;
// function calls
foo(); // first tries to call "foo" defined in namespace "A"
// then calls internal function "foo"
\foo(); // calls function "foo" defined in global scope
// class references
new B(); // first tries to create object of class "B" defined in namespace "A"
// then creates object of internal class "B"
new \B(); // creates object of class "B" defined in global scope
// static methods/namespace functions from another namespace
B\foo(); // first tries to call function "foo" from namespace "A\B"
// then calls method "foo" of internal class "B"
\B\foo(); // first tries to call function "foo" from namespace "B"
// then calls method "foo" of class "B" from global scope
// static methods/namespace functions of current namespace
A\foo(); // first tries to call function "foo" from namespace "A\A"
// then tries to call method "foo" of class "A" from namespace "A"
// then tries to call function "foo" from namespace "A"
// then calls method "foo" of internal class "A"
\A\foo(); // first tries to call function "foo" from namespace "A"
// then calls method "foo" of class "A" from global scope
?>
Exceções
Índice
PHP 5 tem um modelo de exceção similar ao de outras linguagens de programação. Uma exceção pode ser disparada (thrown), ou pega (caught ou "catched") no PHP. Código pode ser rodeado em um block try, para facilitar a captura de exceções em potencial. Cada bloco try, deve ter pelo menos um bloco catch correspondente. Vários blocos catch pode ser usado para pegar diferentes classes de exceções. A execução normal (quando nenhuma exceção é disparada dentro de um bloco try ou quando um catch compatível com a classe da exceção disparada não estiver presente) continuará após o último bloco catch definido na seqüência. Exceções podem ser disparadas (ou re-disparadas) dentro de um bloco catch.
Quando uma exceção é disparada, código logo após à instrução não será executada, e o PHP tentará achar o primeiro bloco catch correspondente à exceção disparada. Se uma exceção não for pega, um Erro Fatal do PHP será lançado com uma mensagem "Uncaught Exception ...", a não ser que um tratador tenha sido definido com set_exception_handler().
Nota:
Funções internas do PHP usam principalmente Error reporting, somente extensões modernas usam exceções. Contudo, os erros podem ser simplesmente traduzidos para exceções com ErrorException.
Exemplo #1 Disparando uma Exceção
<?php
function inverse($x) {
if (!$x) {
throw new Exception('Division by zero.');
}
else return 1/$x;
}
try {
echo inverse(5) . "\n";
echo inverse(0) . "\n";
} catch (Exception $e) {
echo "Exceção pega: ", $e->getMessage(), "\n";
}
// continua a execução
echo 'Hello World';
?>
O exemplo acima irá imprimir:
0.2 Exceção pega: Division by zero. Hello World
Exemplo #2 Exceções aninhadas
<?php
class MyException extends Exception { }
class Test {
public function testing() {
try {
try {
throw new MyException('foo!');
} catch (MyException $e) {
/* rethrow it */
throw $e;
}
} catch (Exception $e) {
var_dump($e->getMessage());
}
}
}
$foo = new Test;
$foo->testing();
?>
O exemplo acima irá imprimir:
string(4) "foo!"
Herdando Exceções
Uma classe de exceção definida pelo usuário pode ser criada herdando a classe Exception. Os membros e propriedades abaixo mostram o que é acessível a partir da classe filha que deriva da Exception.
Exemplo #1 A classe nativa Exception
<?php
class Exception {
protected $message = 'Unknown exception'; // Mensagem da exceção
protected $code = 0; // Código da exceção definido pelo usuário
protected $file; // Arquivo gerador da exceção
protected $line; // Linha geradora da exceção
function __construct(string $message=NULL, int code=0);
final function getMessage(); // Mensagem da exceção
final function getCode(); // Código da exceção
final function getFile(); // Arquivo gerador
final function getTrace(); // um array com o backtrace()
final function getTraceAsString(); // String formatada do trace
/* Sobrecarregável */
function _toString(); // String formatada para ser mostrada
}
?>
Se uma classe herda da classe Exception e redefine o construtor, é altamente recomendado que o mesmo chame parent::__construct() para garantir que todas as informações disponíveis sejam devidamente atribuídas. O método __toString() pode ser sobrecarregado para permitir uma saída personalizada quando o objeto é apresentado como string.
Exemplo #2 Herdando a classe Exception
<?php
class MyException extends Exception {
/* Redefine a exceção para que a mensagem não seja opcional */
public function __construct($message, $code = 0) {
// coisas personalizadas que você queira fazer
// ...
/* Garante que tudo é atribuído corretamente */
parent::__construct($message, $code);
}
/* Representação do objeto personalizada no formato string */
public function __toString() {
return __CLASS__ . ": [{$this->code}]: {$this->message}\n";
}
public function customFunction() {
echo "Uma função personalizada para esse tipo de exceção\n";
}
}
/**
* Cria uma classe para testar a exceção
*/
class TestException {
public $var;
const THROW_NONE = 0;
const THROW_CUSTOM = 1;
const THROW_DEFAULT = 2;
function __construct($avalue = self::THROW_NONE) {
switch ($avalue) {
case self::THROW_CUSTOM:
// dispara exceção personalizada
throw new MyException('1 é um parâmetro inválido', 5);
break;
case self::THROW_DEFAULT:
// dispara a padrão
throw new Exception('2 não é permitido como parâmetro', 6);
break;
default:
// Nenhuma exceção, objeto será criado.
$this->var = $avalue;
break;
}
}
}
// Exemplo 1
try {
$o = new TestException(TestException::THROW_CUSTOM);
}
catch (MyException $e) { /* Será pega */
echo "Pegou minha exceção\n", $e;
$e->customFunction();
}
catch (Exception $e) { /* Ignorado */
echo "Pegou Exceção Padrão\n", $e;
}
var_dump($o); /* continua execução */
echo "\n\n";
// Exemplo 2
try {
$o = new TestException(TestException::THROW_DEFAULT);
}
catch (MyException $e) { /* Tipos não batem */
echo "Pegou minha exceção\n", $e;
$e->customFunction();
}
catch (Exception $e) { /* Será pega */
echo "Pegou Exceção Padrão\n", $e;
}
var_dump($o); /* continua execução */
echo "\n\n";
// Exemplo 3
try {
$o = new TestException(TestException::THROW_CUSTOM);
}
catch (Exception $e) { /* Será pega */
echo "Default Exception caught\n", $e;
}
var_dump($o); /* continua execução */
echo "\n\n";
// Exemplo 4
try {
$o = new TestException();
}
catch (Exception $e) { /* Ignorada, nenhuma exceção */
echo "Default Exception caught\n", $e;
}
var_dump($o); /* continua execução */
echo "\n\n";
Referências
Índice
- O que são referências
- O que as referências fazem
- O que as referências não são
- Passagem por referência
- Retornando referências
- Destruindo referências
- Demonstrando referências
O que são referências
Referências, em PHP, significa acessar o mesmo conteúdo de variável através de vários nomes. Isto não é parecido com os ponteiros em C; ao invés, aqui temos apelidos numa tabela simbólica. Note que no PHP nomes de variáveis e conteúdo de variável são tratados diferentemente, então um mesmo conteúdo pode ter nomes diferentes. A analogia mais próxima é a dos arquivos e seus nomes em sistemas UNIX: nomes de variáveis são o caminho completo dos arquivos, enquanto o conteúdo da variável são os dados desse arquivo. Assim, referências podem ser tomadas como os links físicos dentro do sistema de arquivos UNIX.
O que as referências fazem
Referências PHP permitem fazer duas variáveis se referirem ao mesmo conteúdo. Ou seja:
<?php
$a =& $b;
?>
Nota:
$a e $b são completamente iguais aqui, mas não porque $a está apontando para $b ou vice versa, mas sim que $a e $b apontam para o mesmo lugar.
Nota:
Se o array com referências é copiado, seus valores não são referenciados. Isto é válido também para arrays passados por valor para funções.
Nota:
Se você atribuir, passar ou retornar uma variável indefinida por referência, ela irá ser criada.
Exemplo #1 Usando referência com variáveis indefinidas
<?php
function foo(&$var) { }
foo($a); // $a é "criada" e setada par null
$b = array();
foo($b['b']);
var_dump(array_key_exists('b', $b)); // bool(true)
$c = new StdClass;
foo($c->d);
var_dump(property_exists($c, 'd')); // bool(true)
?>
A mesma sintaxe pode ser utilizada com funções, que retornem referências, e com o operador new (a partir do PHP 4.0.4):
<?php
$bar =& new fooclass();
$foo =& find_var ($bar);
?>
Nota:
A não utilização do operador & causará a cópia do objeto. Se você utiliza $this em classes, ele operará na instância atual do objeto. A assimilação sem & irá copiar a instância (o objeto em si) e $this irá operar na cópia, podendo não ser esse procedimento sempre desejável. Normalmente você precisará trabalhar com uma instância única, seja por motivos de performance ou de consumo de memória.
Você pode utilizar o operador @ para esconder quaisquer erros em construtores na forma @new, mas isto não funciona quando utilizada a instrução &new. Esta é uma limitação da Zend Engine e irá gerar um erro de interpretação (parser error).
Se você atribuir uma referência para uma variável declarada global dentro da função, a referência irá ser visível somente dentro da função. Você pode evitar isto usando o array $GLOBALS.
Exemplo #2 Referenciando variáveis globais de dentro de funções
<?php
$var1 = "Example variable";
$var2 = "";
function global_references($use_globals)
{
global $var1, $var2;
if (!$use_globals) {
$var2 =& $var1; // visível somente dentro da função
} else {
$GLOBALS["var2"] =& $var1; // visível também no contexto global
}
}
global_references(false);
echo "var2 is set to '$var2'\n"; // var2 is set to ''
global_references(true);
echo "var2 is set to '$var2'\n"; // var2 is set to 'Example variable'
?>
Nota:
Se você atribuir um valor para uma variável com referência no comando foreach, a referência é modificada também.
Exemplo #3 Referências e o comando foreach
<?php
$ref = 0;
$row =& $ref;
foreach (array(1, 2, 3) as $row) {
// faz alguma coisa
}
echo $ref; // 3 - último elemento do array iterado
?>
A segunda coisa que referências permitem é passar variáveis por referência. Isto é feito marcando uma variável local de uma função e a variável do escopo chamador como referências ao mesmo conteúdo. Exemplo:
<?php
function foo (&$var)
{
$var++;
}
$a=5;
foo ($a);
?>
Em terceiro lugar, referências permitem também retorno por referência.
O que as referências não são
Como dito anteriormente, referências não são ponteiros. Isto significa que o construtor seguinte não fará o que você espera:
<?php
function foo (&$var)
{
$var =& $GLOBALS["baz"];
}
foo($bar);
?>
Acontece que $var na função foo estará apontada para $bar na chamada, mas ela será re-apontada para $GLOBALS["baz"]. Não existe maneira de apontar $bar no escopo chamador para qualquer outra coisa utilizando o mecanismo de referências, desde que $bar não está disponível na função foo (ela é representa por $var, mas $var somente tem o conteúdo da variável e não um relacionamento nome para valor na tabela simbólica). Você pode retornar referências para referenciar variáveis selecionadas por função.
Passagem por referência
Você pode passar variáveis para funções por referência, então a função poderá modificar seus argumentos. A sintaxe é a seguinte:
<?php
function foo (&$var)
{
$var++;
}
$a=5;
foo ($a);
// $a é 6 aqui
?>
As coisas a seguir podem ser passadas por referência:
- Variáveis. Exemplo: foo($a)
- Instrução new. Exemplo foo(new foobar())
-
Outra referência, retornada de uma função. Exemplo:
Veja explicações sobre isso em retorno por referência.<?php
function &bar()
{
$a = 5;
return $a;
}
foo(bar());
?>
Nenhuma outra expressão poderá ser passada por referência, com resultados indefinidos. Por exemplo, o exemplo seguinte de passagem por referência é inválido:
<?php
function bar() // Note a falta do &
{
$a = 5;
return $a;
}
foo(bar());
foo($a = 5); // Expressão, não é variável
foo(5); // Constante, não é variável
?>
Retornando referências
Retorno por referência é útil quando você precisa utilizar uma função para localizar variável cuja referência precisa ser obtida. Não use retorno por referência para aumentar performance, a engine é esperta o bastante para otimizar isto para você. Somente retorne referências quando você tem uma razão técnica para isso! Para retornar referências, use a sintaxe:
<?php
class foo {
public $value = 42;
public function &getValue() {
return $this->value;
}
}
$obj = new foo;
$myValue = &$obj->getValue(); // $myValue is a reference to $obj->value, which is 42.
$obj->value = 2;
echo $myValue; // prints the new value of $obj->value, i.e. 2.
?>
Nota: Diferentemente da passagem de parâmetros por referência, aqui você precisa utilizar & em ambos os lugares - primeiro para indicar o retorno por referência (e não a cópia), e depois para indicar a ligação da referência (em vez da assimilação convencional) que precisa ser explícita para $myValue.
Se você tentar retornar uma referência de uma função com a sintaxe: return ($this->value); isto não irá funcionar como você espera, para retornar o resultado de uma expressão, e não uma variável, por referência. Você pode somente retornar variáveis por referência para uma função - nada além. Erro E_NOTICE é emitido desde o PHP 4.4.0 e PHP 5.1.0 se o código tenta retornar uma expressão dinâmica ou um resultado do operador new.
Destruindo referências
Quando você quebra uma referência, ela apenas pára de fazer o apontamento entre o nome da variável e o conteúdo. Mas isto não significa que o conteúdo da variável será destruído. Por exemplo:
<?php
$a = 1;
$b =& $a;
unset ($a);
?>
Novamente, é mais fácil pensar em analogia ao comando UNIX unlink.
Demonstrando referências
Vários construtores sintáticos do PHP são implementados através de mecanismos de referência, assim, tudo o explicado até aqui sobre referências também se aplica a esses construtores. Alguns desses construtores, como a passagem e o retorno de referências foram mencionados acima. Outros construtores que também utilizam referências são:
global
Quando você declara uma variável com global, você está de fato criando um referência para a variável global. Isto significa que isto é o mesmo que:
<?php
$var =& $GLOBALS["var"];
?>
O que significa também que destruir $var não apaga a variável global.
$this
Num método de objeto, $this é sempre uma referência à instância atual.
Variáveis pré-definidas
PHP provê um grande número de variáveis pré-definidas para todos scripts. As variáveis representam tudo de variáveis externas à variáveis nativas de ambiente, última mensagem de erro à último cabeçalho recebido.
Veja também o FAQ intitulado "Como register_globals pode afetar?"
Superglobais
Superglobais — Superglobais são variáveis nativas que estão sempre disponíveis em todos escopos
Descrição
Várias variáveis pré-definidas no PHP são "superglobais", que significa que elas estão disponível em todos escopos para todo o script. Não há necessidade de fazer global $variable; para acessá-lo dentro de funções ou métodos.
Estas variáveis superglobais são:
Histórico
| Versão | Descrição |
|---|---|
| 4.1.0 | Superglobais foram introduzidas no PHP. |
Notas
Nota: Disponibilidade da variável
Por padrão, todas as superglobais estão disponíveis, mas há diretivas que afetam esta disponibilidade. Para mais informação, consulte na documentação sobre variables_order.
Nota: Lidando com register_globals
Se a obsoleta diretiva register_globals é definida para on então variáveis contidas irão também estar disponíveis no escopo global do script. Por exemplo, $_POST['foo'] também existiria como $foo.
Para informação relacionada, veja o FAQ intitulado "Como register_globals pode afetar?"
Nota: Variável variáveis
Superglobais não podem ser usadas como variável variáveis dentro de função ou métodos de classes.
$GLOBALS
$GLOBALS — Referencia todas variáveis disponíveis no escopo global
Descrição
Um array associativo contendo referências para todas as variáveis que estão atualmente definidas no escopo global do script. O nome das variáveis são chaves do array.
Exemplos
Exemplo #1 Exemplo da $GLOBALS
<?php
function test() {
$foo = "local variable";
echo '$foo in global scope: ' . $GLOBALS["foo"] . "\n";
echo '$foo in current scope: ' . $foo . "\n";
}
$foo = "Example content";
test();
?>
O exemplo acima irá imprimir algo similar a:
$foo in global scope: Example content $foo in current scope: local variable
Notas
Nota:
Esta é uma 'superglobal', ou global automática, variável. Isto simplismente significa que ela está disponível em todos escopos pelo script. Não há necessidade de fazer global $variable; para acessá-la dentro de uma função ou método.
Nota: Disponibilidade da variável
Diferente de todas as outras superglobais, $GLOBALS tem essencialmente sempre estado disponível no PHP.
$_SERVER
$HTTP_SERVER_VARS [deprecated]
$_SERVER -- $HTTP_SERVER_VARS [deprecated] — Informação do servidor e ambiente de execução
Descrição
$_SERVER é um array contendo informação como cabeçalhos, paths, e localizações do script. As entradas neste array são criadas pelo servidor web. Não há garantia que cada servidor web proverá algum destes; servidores podem omitir alguns, ou fornecer outros não listados aqui. Dito isso, um grande número dessas variáveis são previstas pela » CGI 1.1 specification, então você deve estar hábil para esperá-las.
$HTTP_SERVER_VARS contém a mesma informação inicial, mas não é uma superglobal. (Note que $HTTP_SERVER_VARS e $_SERVER são variáveis diferentes e que o PHP manuseia-as diferentemente)
Você pode ou não encontrar algum dos seguintes elementos em $_SERVER. Note que poucas, se alguma, dessas estarão disponíveis (ou ter algum significado) se executando o PHP na linha de comando.
- 'PHP_SELF'
- O nome do arquivo do script que está executando, relativa à raiz do documento. Por exemplo, $_SERVER['PHP_SELF'] em um script no endereço http://example.com/test.php/foo.bar seria /test.php/foo.bar. A constante __FILE__ contém o caminho completo e nome do atual arquivo (i.e. incluído). Se estiver rodando o PHP em linha de comando, esta variável contém o nome do script desde o PHP 4.3.0. Anteriormente ela não estava disponível.
- 'argv'
- Array de argumentos passado para o script. Quando o script é executado na linha de comando, isto permite um acesso aos parâmetros de linha de comando no estilo do C. Quando chamado via método GET, ele conterá a query string.
- 'argc'
- Contém o número de parâmetros da linha de comando passados para o script (se executando da linha de comando).
- 'GATEWAY_INTERFACE'
- O número de revisão da especificação CGI que o servidor está utilizando, por exemplo : 'CGI/1.1'.
- 'SERVER_ADDR'
- O endereço IP do servidor onde está o script em execução.
- 'SERVER_NAME'
- O nome host do servidor onde o script atual é executado. Se o script está rodando em um host virtual, este será o valor definido para aquele host virtual.
- 'SERVER_SOFTWARE'
- A string de identificação do servidor, fornecida nos headers quando respondendo a requests.
- 'SERVER_PROTOCOL'
- Nome e número de revisão do protocolo de informação pelo qual a página foi requerida, por exemplo 'HTTP/1.0';
- 'REQUEST_METHOD'
-
Contém o método de request utilizando para acessar a página. Geralmente 'GET',
'HEAD', 'POST' ou 'PUT'.
Nota:
O script PHP é terminado depois de enviado cabeçalhos (significa depois de produzir alguma saída sem saída do buffer) se o método da requisição for HEAD.
- 'REQUEST_TIME'
- O timestamp do início da requisição. Disponível desde o PHP 5.1.0.
- 'QUERY_STRING'
- A query string (string de solicitação), se houver, pela qual a página foi acessada.
- 'DOCUMENT_ROOT'
- O diretório raiz sob onde o script atual é executado, como definido no arquivos de configuração do servidor.
- 'HTTP_ACCEPT'
- O conteúdo do header Accept: da requisição atual, se houver.
- 'HTTP_ACCEPT_CHARSET'
- O conteúdo do header Accept-Charset: da requisição atual, se houver. Exemplo: 'iso-8859-1,*,utf-8'.
- 'HTTP_ACCEPT_ENCODING'
- O conteúdo do header Accept-Encoding: da requisição atual, se houver. Exemplo: 'gzip'.
- 'HTTP_ACCEPT_LANGUAGE'
- O conteúdo do header Accept-Language: da requisição atual, se houver. Exemplo 'en'.
- 'HTTP_CONNECTION'
- O conteúdo do header Connection: da requisição atual, se houver. Exemplo: 'Keep-Alive'.
- 'HTTP_HOST'
- O conteúdo do header Host: da requisição atual, se houver.
- 'HTTP_REFERER'
- O endereço da página (se houver) através da qual o agente do usuário acessou a página atual. Essa diretiva é informada pelo agente do usuário. Nem todos os browsers geram esse header, e alguns ainda possuem a habilidade de modificar o conteúdo do HTTP_REFERER como recurso. Em poucas palavras, não é confiável.
- 'HTTP_USER_AGENT'
- O conteúdo do header User-Agent: da requisição atual, se houver. É uma string denotando o agente de usuário pelo qual a página é acessada. Um exemplo típico é: Mozilla/4.5 [en] (X11; U; Linux 2.2.9 i586). Além de outras coisas, você pode utilizar este valor com get_browser() para personalizar a geração de suas páginas para as capacidades do agente do usuário.
- 'HTTPS'
- Define para um valor não vazio se o script foi requisitado através do protocolo HTTPS. Note que quando usando ISAPI com IIS, o valor será off se a requisição não for feita por protocolo HTTPS.
- 'REMOTE_ADDR'
- O endereço IP de onde o usuário está visualizado a página atual.
- 'REMOTE_HOST'
-
O nome do host que o usuário utilizou para chamar a página
atual. O DNS reverso (lookup) do
REMOTE_ADDR do usuário.
Nota: Seu servidor web precisa estar configurado para criar essa variável. Por exemplo, no Apache você precisa colocar um HostnameLookups On dentro do httpd.conf. Veja também gethostbyaddr().
- 'REMOTE_PORT'
- A porta TCP na máquina do usuário utilizada para comunicação com o servidor web.
- 'SCRIPT_FILENAME'
-
O caminho absoluto o script atualmente em execução.
Nota:
Se o script for executado pela CLI com um caminho relativo, como file.php ou ../file.php, $_SERVER['SCRIPT_FILENAME'] irá conter o caminho relativo especificado pelo usuário.
- 'SERVER_ADMIN'
- O valor fornecido pela diretiva SERVER_ADMIN (do Apache) no arquivo de configuração do servidor. Se o script está sendo executado em um host virtual, este será os valores definidos para aquele host virtual.
- 'SERVER_PORT'
- A porta na máquina servidora utilizada pelo servidor web para comunicação. Como default, este valor é '80'. Utilizando SSL, entretanto, mudará esse valor para a porta de comunicação segura HTTP.
- 'SERVER_SIGNATURE'
- String contendo a versão do servidor e nome do host virtual que é adicionado às páginas geradas no servidor, se ativo.
- 'PATH_TRANSLATED'
-
O caminho real do script relativo ao sistema de arquivos
(não o document root), depois realizou todos os mapeamentos
de caminhos (virtual-to-real).
Nota: A partir do PHP 4.3.2, PATH_TRANSLATED não mais existe implicitamente sob a SAPI do Apache 2, ao contrário da mesma situação no Apache 1, onde ela tinha o mesmo valor da variável de servidor SCRIPT_FILENAME, quando a mesma não era configurada pelo Apache. Essa mudança foi realizada para conformidade com a especificação CGI, onde PATH_TRANSLATED deve existir somente se PATH_INFO estiver definida. Apache 2 users may use AcceptPathInfo = On inside httpd.conf to define PATH_INFO.
- 'SCRIPT_NAME'
- Contém o caminho completo do script atual. Útil para páginas que precisam apontar para elas mesmas (dinamicamente). A constante __FILE__ contém o caminho completo e nome do arquivo (mesmo incluído) atual.
- 'REQUEST_URI'
- O URI fornecido para acessar a página atual, por exemplo, '/index.html'.
- 'PHP_AUTH_DIGEST'
- Quando executando no Apache como módulo fazendo autenticação HTTP esta variável é definida para o cabeçalho 'Authorization' enviado pelo cliente (que você pode então usar para fazer apropriada validação).
- 'PHP_AUTH_USER'
- Quando executando sob o Apache ou IIS (ISAPI no PHP 5) como módulo e fazendo autenticaçào HTTP, esta variável estará definida com o username fornecido pelo usuário.
- 'PHP_AUTH_PW'
- Quando executando sob o Apache ou IIS (ISAPI no PHP 5) como módulo e fazendo autenticaçào HTTP, esta variável estará definida com a senha fornecida pelo usuário.
- 'AUTH_TYPE'
- Quando executando sob o Apache como módulo e fazendo autenticaçào HTTP, esta variável estará definida com o tipo de autenticação utilizado.
Histórico
| Versão | Descrição |
|---|---|
| 4.1.0 | Introduzida $_SERVER que torna obsoleta a $HTTP_SERVER_VARS. |
Exemplos
Exemplo #1 Exemplo da $_SERVER
<?php
echo $_SERVER['SERVER_NAME'];
?>
O exemplo acima irá imprimir algo similar a:
www.example.com
Notas
Nota:
Esta é uma 'superglobal', ou global automática, variável. Isto simplismente significa que ela está disponível em todos escopos pelo script. Não há necessidade de fazer global $variable; para acessá-la dentro de uma função ou método.
$_GET
$HTTP_GET_VARS [obsoleta]
$_GET -- $HTTP_GET_VARS [obsoleta] — HTTP GET variáveis
Descrição
Um array associativo de variáveis passadas para o script atual via o método HTTP GET.
$HTTP_GET_VARS contém a mesma informação inicial, mas não é uma superglobal. (Note que $HTTP_GET_VARS e $_GET são variáveis diferentes e que o PHP manuseia-as diferentemente)
Histórico
| Versão | Descrição |
|---|---|
| 4.1.0 | Introduzida a $_GET que torna obsoleta a $HTTP_GET_VARS. |
Exemplos
Exemplo #1 Exemplo da $_GET
<?php
echo 'Hello ' . htmlspecialchars($_GET["name"]) . '!';
?>
Assumindo que o usuário entrou por http://example.com/?name=Hannes
O exemplo acima irá imprimir algo similar a:
Hello Hannes!
Notas
Nota:
Esta é uma 'superglobal', ou global automática, variável. Isto simplismente significa que ela está disponível em todos escopos pelo script. Não há necessidade de fazer global $variable; para acessá-la dentro de uma função ou método.
$_POST
$HTTP_POST_VARS [deprecated]
$_POST -- $HTTP_POST_VARS [deprecated] — HTTP POST variables
Descrição
Um array associativo de variáveis passados para o script atual via método HTTP POST.
$HTTP_POST_VARS contém a mesma informação inicial, mas não é uma superglobal. (Note que $HTTP_POST_VARS e $_POST são variáveis diferentes e que o PHP manuseia-as diferentemente)
Histórico
| Versão | Descrição |
|---|---|
| 4.1.0 | Introduzida a $_POST que torna obsoleta a $HTTP_POST_VARS. |
Exemplos
Exemplo #1 Exemplo da $_POST
<?php
echo 'Hello ' . htmlspecialchars($_POST["name"]) . '!';
?>
Assumindo que o usuário tenha postado name=Hannes
O exemplo acima irá imprimir algo similar a:
Hello Hannes!
Notas
Nota:
Esta é uma 'superglobal', ou global automática, variável. Isto simplismente significa que ela está disponível em todos escopos pelo script. Não há necessidade de fazer global $variable; para acessá-la dentro de uma função ou método.
$_FILES
$HTTP_POST_FILES [obsoleta]
$_FILES -- $HTTP_POST_FILES [obsoleta] — HTTP File Upload variáveis
Descrição
Um array associativo de items enviado através do script atual via o método HTTP POST.
$HTTP_POST_FILES contém a mesma informação inicial, mas não é uma superglobal. (Note que $HTTP_POST_FILES e $_FILES são variáveis diferentes e que o PHP manuseia-as diferentemente)
Histórico
| Versão | Descrição |
|---|---|
| 4.1.0 | Introduzida a $_FILES que torna obsoleta a $HTTP_POST_FILES. |
Notas
Nota:
Esta é uma 'superglobal', ou global automática, variável. Isto simplismente significa que ela está disponível em todos escopos pelo script. Não há necessidade de fazer global $variable; para acessá-la dentro de uma função ou método.
Veja Também
- move_uploaded_file() - Move um arquivo enviado para uma nova localização
- Manuseamento de upload de arquivos
$_REQUEST
$_REQUEST — Variáveis de requisição HTTP
Histórico
| Versão | Descrição |
|---|---|
| 5.3.0 | Introduzida a request_order. Esta diretiva afeta o conteúdo de $_REQUEST. |
| 4.3.0 | Informação da $_FILES foi removida de $_REQUEST. |
| 4.1.0 | Introduzida a $_REQUEST. |
Notas
Nota:
Esta é uma 'superglobal', ou global automática, variável. Isto simplismente significa que ela está disponível em todos escopos pelo script. Não há necessidade de fazer global $variable; para acessá-la dentro de uma função ou método.
Nota:
Quando executando em linha de comando , esta não incluirá as entradas argv e argc; estas estão presentes no array $_SERVER.
Nota:
As variáveis em $_REQUEST são providas para o script via mecanismos de entradas GET, POST, e COOKIE e portando poderia ser modificadas por um usuário remoto e não podem ser confiadas. A presença e ordem das variáveis listadas neste array é definido de acordo com a diretiva de configuração do PHP variables_order.
Veja Também
- import_request_variables() - Importa variáveis GET/POST/Cookie para o escopo global
- Manuseamento de variáveis externas
- A extensão filter
$_SESSION
$HTTP_SESSION_VARS [obsoleta]
$_SESSION -- $HTTP_SESSION_VARS [obsoleta] — Variáveis de sessão
Descrição
Um array associativo contendo variáveis de sessão disponíveis para o atual script. Veja a documentação das funções de Sessão para mais informação em como usar isto.
$HTTP_SESSION_VARS contém a mesma informação inicial, mas não é uma superglobal. (Note que $HTTP_SESSION_VARS e $_SESSION são diferentes variáveis e que o PHP manuseia-as diferentemente)
Histórico
| Versão | Descrição |
|---|---|
| 4.1.0 | Introduzida $_SESSION que torna obsoleta a $HTTP_SESSION_VARS. |
Notas
Nota:
Esta é uma 'superglobal', ou global automática, variável. Isto simplismente significa que ela está disponível em todos escopos pelo script. Não há necessidade de fazer global $variable; para acessá-la dentro de uma função ou método.
$_ENV
$HTTP_ENV_VARS [obsoleta]
$_ENV -- $HTTP_ENV_VARS [obsoleta] — Environment variables
Descrição
Um array associativo de variáveis passadas para o script atual via o método do ambiente.
Estas variáveis são importadas para o PHP do ambiente sob o qual o parser do PHP é executado. Muitas são providas pelo shell sob o qual o PHP é executado e diferentes sistemas são prováveis executar diferentes tipos de shells, uma lista definitiva é impossível. Veja a documentação de shellp para saber a lista de variáveis de ambiente definidas.
Outras variáveis de ambiente incluem variáveis CGI, elas aparecem desconsiderando se o PHP é executado como um módulo do servidor ou processador CGI.
$HTTP_ENV_VARS contém a mesma informação inicial, mas não é uma superglobal. (Note que $HTTP_ENV_VARS e $_ENV são variáveis diferentes e que o PHP manuseia-as diferentemente)
Histórico
| Versão | Descrição |
|---|---|
| 4.1.0 | Introduzida a $_ENV que torna obsoleta a $HTTP_ENV_VARS. |
Exemplos
Exemplo #1 Exemplo da $_ENV
<?php
echo 'My username is ' .$_ENV["USER"] . '!';
?>
Assumindo que "bjori" executou este script
O exemplo acima irá imprimir algo similar a:
My username is bjori!
Notas
Nota:
Esta é uma 'superglobal', ou global automática, variável. Isto simplismente significa que ela está disponível em todos escopos pelo script. Não há necessidade de fazer global $variable; para acessá-la dentro de uma função ou método.
$php_errormsg
$php_errormsg — A mensagem de erro anterior
Descrição
$php_errormsg é uma variável contendo o texto da última mensagem de erro gerado pelo PHP. Esta variável somente estará disponível dentro do escopo no qual o erro ocorreu, e somente se a opção de configuração track_errors estiver on (o padrão é off).
Nota: Esta variável está somente disponível quando a track_errors estiver habilitada no php.ini.
Se um manuseador de erro definido pelo usuário é usado, $php_erromsg somente será definida se o manuseador de erro retornar FALSE
Exemplos
Exemplo #1 Exemplo da $php_errormsg
<?php
@strpos();
echo $php_errormsg;
?>
O exemplo acima irá imprimir algo similar a:
Wrong parameter count for strpos()
$HTTP_RAW_POST_DATA
$HTTP_RAW_POST_DATA — Informação não-tratada do POST
Descrição
$HTTP_RAW_POST_DATA contém informação não-tratada do POST. Veja always_populate_raw_post_data
$http_response_header
$http_response_header — Cabeçalhos de resposta HTTP
Descrição
O array $http_response_header é similar a função get_headers(). Quando usando o HTTP wrapper, $http_response_header será populada com os cabeçalhos de resposta HTTP.
Exemplos
Exemplo #1 Exemplo da $http_response_header
<?php
file_get_contents("http://example.com");
var_dump($http_response_header);
?>
O exemplo acima irá imprimir algo similar a:
array(9) {
[0]=>
string(15) "HTTP/1.1 200 OK"
[1]=>
string(35) "Date: Sat, 12 Apr 2008 17:30:38 GMT"
[2]=>
string(29) "Server: Apache/2.2.3 (CentOS)"
[3]=>
string(44) "Last-Modified: Tue, 15 Nov 2005 13:24:10 GMT"
[4]=>
string(27) "ETag: "280100-1b6-80bfd280""
[5]=>
string(20) "Accept-Ranges: bytes"
[6]=>
string(19) "Content-Length: 438"
[7]=>
string(17) "Connection: close"
[8]=>
string(38) "Content-Type: text/html; charset=UTF-8"
}
$argc
$argc — O número de argumentos passados para o script
Descrição
Contém o número de argumentos passados para o atual script quando executando através da linha de comando.
Nota: O nome do arquivo do script é sempre passado como um argumento para o script, portanto o valor mínimo de $argc é 1.
Nota: Esta variável está sempre disponível quando register_argc_argv está habilitada.
Exemplos
Exemplo #1 Exemplo da $argc
<?php
var_dump($argc);
?>
Quando executando o exemplo com: php script.php arg1 arg2 arg3
O exemplo acima irá imprimir algo similar a:
int(4)
$argv
$argv — Array de argumentos passados para o script
Descrição
Contém um array de todos argumentos passados para o script quando executando através da linha de comando.
Nota: O primeiro argumento é sempre o nome do arquivo do script atual, portanto $argv[0] é o nome do script.
Nota: Esta variável está sempre disponível quando register_argc_argv está habilitada.
Exemplos
Exemplo #1 Exemplo da $argv
<?php
var_dump($argv);
?>
Quando executando o exemplo com: php script.php arg1 arg2 arg3
O exemplo acima irá imprimir algo similar a:
array(4) {
[0]=>
string(10) "script.php"
[1]=>
string(4) "arg1"
[2]=>
string(4) "arg2"
[3]=>
string(4) "arg3"
}
Índice
- Superglobais — Superglobais são variáveis nativas que estão sempre disponíveis em todos escopos
- $GLOBALS — Referencia todas variáveis disponíveis no escopo global
- $_SERVER — Informação do servidor e ambiente de execução
- $_GET — HTTP GET variáveis
- $_POST — HTTP POST variables
- $_FILES — HTTP File Upload variáveis
- $_REQUEST — Variáveis de requisição HTTP
- $_SESSION — Variáveis de sessão
- $_ENV — Environment variables
- $_COOKIE — HTTP Cookies
- $php_errormsg — A mensagem de erro anterior
- $HTTP_RAW_POST_DATA — Informação não-tratada do POST
- $http_response_header — Cabeçalhos de resposta HTTP
- $argc — O número de argumentos passados para o script
- $argv — Array de argumentos passados para o script
Exceções pré-definidas
Índice
Exception
(PHP 5 >= 5.1.0)
Introdução
Exception é a classe base para todas Exceptions.
Sinopse da classe
Propriedades
- message
-
A mensagem da exceção
- string
-
Nome interno da exceção
- code
-
O código da exceção
- file
-
O nome do arquivo onde a exceção foi disparada
- line
-
A linha onde a exceção foi disparada
- trace
-
A stack trace
Exception::__construct
(PHP 5 >= 5.1.0)
Exception::__construct — Construtor da exceção
Descrição
Construtor da exceção.
Parâmetros
- message
-
A mensagem da exceção a ser disparada.
- code
-
O código da exceção.
Exception::getMessage
(PHP 5 >= 5.1.0)
Exception::getMessage — Obtém a mensagem da exceção
Descrição
Retorna a mensagem da exceção.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Retorna a mensagem da exceção como uma string.
Exemplos
Exemplo #1 Exemplo da Exception::getMessage()
<?php
try {
throw new Exception("Some error message");
} catch(Exception $e) {
echo $e->getMessage();
}
?>
O exemplo acima irá imprimir algo similar a:
Some error message
Exception::getCode
(PHP 5 >= 5.1.0)
Exception::getCode — Obtém o código da exceção
Descrição
Retorna o código da exceção.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Retorna o código da Exceção como um integer.
Exemplos
Exemplo #1 Exemplo da Exception::getCode()
<?php
try {
throw new Exception("Some error message", 30);
} catch(Exception $e) {
echo "The exception code is: " . $e->getCode();
}
?>
O exemplo acima irá imprimir algo similar a:
The exception code is: 30
Exception::getFile
(PHP 5 >= 5.1.0)
Exception::getFile — Obtém o arquivo no qual a exceção ocorreu
Descrição
Obtém o nome do arquivo de onde a exceção foi disparada.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Retorna o nome do arquivo no qual a exceção foi disparada.
Exemplos
Exemplo #1 Exemplo da Exception::getFile()
<?php
try {
throw new Exception;
} catch(Exception $e) {
echo $e->getFile();
}
?>
O exemplo acima irá imprimir algo similar a:
/home/bjori/tmp/ex.php
Exception::getLine
(PHP 5 >= 5.1.0)
Exception::getLine — Obtém a linha na qual a exceção ocorreu
Descrição
Retorna o número da linha onde a exceção foi disparada.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Retorna o número da linha onde a exceção foi disparada.
Exemplos
Exemplo #1 Exemplo da Exception::getLine()
<?php
try {
throw new Exception("Some error message");
} catch(Exception $e) {
echo "The exception was thrown on line: " . $e->getLine();
}
?>
O exemplo acima irá imprimir algo similar a:
The exception was thrown on line: 3
Exception::getTrace
(PHP 5 >= 5.1.0)
Exception::getTrace — Obtém a stack trace
Descrição
Retorna a stack trace da exceção.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Retorna a stack trace da exceção como um array.
Exemplos
Exemplo #1 Exemplo da Exception::getTrace()
<?php
function test() {
throw new Exception;
}
try {
test();
} catch(Exception $e) {
var_dump($e->getTrace());
}
?>
O exemplo acima irá imprimir algo similar a:
array(1) {
[0]=>
array(4) {
["file"]=>
string(22) "/home/bjori/tmp/ex.php"
["line"]=>
int(7)
["function"]=>
string(4) "test"
["args"]=>
array(0) {
}
}
}
Exception::getTraceAsString
(PHP 5 >= 5.1.0)
Exception::getTraceAsString — Obtém a stack trace como uma string
Descrição
Retorna a stack trace da exceção como uma string.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Retorna a stack trace da exceção como uma string.
Exemplos
Exemplo #1 Exemplo da Exception::getTraceAsString()
<?php
function test() {
throw new Exception;
}
try {
test();
} catch(Exception $e) {
echo $e->getTraceAsString();
}
?>
O exemplo acima irá imprimir algo similar a:
#0 /home/bjori/tmp/ex.php(7): test()
#1 {main}
Exception::__toString
(PHP 5 >= 5.1.0)
Exception::__toString — Representação string da exceção
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Retorna a representação string da exceção.
Exemplos
Exemplo #1 Exemplo da Exception::__toString()
<?php
try {
throw new Exception("Some error message");
} catch(Exception $e) {
echo $e;
}
?>
O exemplo acima irá imprimir algo similar a:
exception 'Exception' with message 'Some error message' in /home/bjori/tmp/ex.php:3
Stack trace:
#0 {main}
Exception::__clone
(PHP 5 >= 5.1.0)
Exception::__clone — Clona a exceção
Descrição
Tenta clonar a exceção, o que resulta em um erro fatal.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Não há valor retornado.
Erros
Exceções não são clonáveis.
Índice
- Exception::__construct — Construtor da exceção
- Exception::getMessage — Obtém a mensagem da exceção
- Exception::getCode — Obtém o código da exceção
- Exception::getFile — Obtém o arquivo no qual a exceção ocorreu
- Exception::getLine — Obtém a linha na qual a exceção ocorreu
- Exception::getTrace — Obtém a stack trace
- Exception::getTraceAsString — Obtém a stack trace como uma string
- Exception::__toString — Representação string da exceção
- Exception::__clone — Clona a exceção
ErrorException
(PHP 5 >= 5.1.0)
Introdução
Uma Exception de erro.
Sinopse da classe
Propriedades
- severity
-
O nível da exceção
Exemplos
Exemplo #1 Tornando todas mensagens de erro em ErrorException.
<?php
function exception_error_handler($errno, $errstr, $errfile, $errline ) {
throw new ErrorException($errstr, 0, $errno, $errfile, $errline);
}
set_error_handler("exception_error_handler");
/* Trigger exception */
strpos();
?>
O exemplo acima irá imprimir algo similar a:
Fatal error: Uncaught exception 'ErrorException' with message 'Wrong parameter count for strpos()' in /home/bjori/tmp/ex.php:8
Stack trace:
#0 [internal function]: exception_error_handler(2, 'Wrong parameter...', '/home/bjori/php...', 8, Array)
#1 /home/bjori/php/cleandocs/test.php(8): strpos()
#2 {main}
thrown in /home/bjori/tmp/ex.php on line 8
ErrorException::__construct
(PHP 5 >= 5.1.0)
ErrorException::__construct — Construct the exception
Descrição
Construtor da Exception.
Parâmetros
- message
-
A mensagem da exceção a ser disparada.
- code
-
O código da exceção.
- severity
-
O nível da exceção.
- filename
-
O nome do arquivo onde a exceção é disparada.
- lineno
-
A número da linha onde a exceção é disparada.
ErrorException::getSeverity
(PHP 5 >= 5.1.0)
ErrorException::getSeverity — Obtém o nível da exceção
Descrição
Retorna o nível da exceção.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Retorna o nível da exceção.
Exemplos
Exemplo #1 Exemplo da ErrorException()
<?php
try {
throw new ErrorException("Exception message", 0, 75);
} catch(ErrorException $e) {
echo "This exception severity is: " . $e->getSeverity();
}
?>
O exemplo acima irá imprimir algo similar a:
This exception severity is: 75
Índice
- ErrorException::__construct — Construct the exception
- ErrorException::getSeverity — Obtém o nível da exceção
Predefined Interfaces
Índice
See also the SPL Interfaces
The Traversable interface
(No version information available, might only be in SVN)
Introdução
Interface to detect if a class is traversable using foreach.
Abstract base interface that cannot be implemented alone. Instead it must be implemented by either IteratorAggregate or Iterator.
Nota:
Internal (built-in) classes that implement this interface can be used in a foreach construct and do not need to implement IteratorAggregate or Iterator.
Nota:
This is an internal engine interface which cannot be implemented in PHP scripts. Either IteratorAggregate or Iterator must be used instead.
Resumo da Interface
This interface has no methods, its only purpose is to be the base interface for all traversable classes.
The Iterator interface
(PHP 5 >= 5.0.0)
Introdução
Interface for external iterators or objects that can be iterated themselves internally.
Resumo da Interface
Predefined iterators
PHP already provides a number of iterators for many day to day tasks. See SPL iterators for a list.
Exemplos
Exemplo #1 Basic usage
This example demonstrates in which order methods are called when using foreach with an iterator.
<?php
class myIterator implements Iterator {
private $position = 0;
private $array = array(
"firstelement",
"secondelement",
"lastelement",
);
public function __construct() {
$this->position = 0;
}
function rewind() {
var_dump(__METHOD__);
$this->position = 0;
}
function current() {
var_dump(__METHOD__);
return $this->array[$this->position];
}
function key() {
var_dump(__METHOD__);
return $this->position;
}
function next() {
var_dump(__METHOD__);
++$this->position;
}
function valid() {
var_dump(__METHOD__);
return isset($this->array[$this->position]);
}
}
$it = new myIterator;
foreach($it as $key => $value) {
var_dump($key, $value);
echo "\n";
}
?>
O exemplo acima irá imprimir algo similar a:
string(18) "myIterator::rewind" string(17) "myIterator::valid" string(19) "myIterator::current" string(15) "myIterator::key" int(0) string(12) "firstelement" string(16) "myIterator::next" string(17) "myIterator::valid" string(19) "myIterator::current" string(15) "myIterator::key" int(1) string(13) "secondelement" string(16) "myIterator::next" string(17) "myIterator::valid" string(19) "myIterator::current" string(15) "myIterator::key" int(2) string(11) "lastelement" string(16) "myIterator::next" string(17) "myIterator::valid"
Iterator::current
(PHP 5 >= 5.0.0)
Iterator::current — Return the current element
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Can return any type.
Iterator::key
(PHP 5 >= 5.0.0)
Iterator::key — Return the key of the current element
Descrição
Returns the key of the current element.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Returns scalar on success, or NULL on failure.
Erros
Issues E_NOTICE on failure.
Iterator::next
(PHP 5 >= 5.0.0)
Iterator::next — Move forward to next element
Descrição
Moves the current position to the next element.
Nota:
This method is called after each foreach loop.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Any returned value is ignored.
Iterator::rewind
(PHP 5 >= 5.0.0)
Iterator::rewind — Rewind the Iterator to the first element
Descrição
Rewinds back to the first element of the Iterator.
Nota:
This is the first method called when starting a foreach loop. It will not be executed after foreach loops.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Any returned value is ignored.
Iterator::valid
(PHP 5 >= 5.0.0)
Iterator::valid — Checks if current position is valid
Descrição
This method is called after Iterator::rewind() and Iterator::next() to check if the current position is valid.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
The return value will be casted to boolean and then evaluated. Retorna TRUE em caso de sucesso ou FALSE em falhas.
Índice
- Iterator::current — Return the current element
- Iterator::key — Return the key of the current element
- Iterator::next — Move forward to next element
- Iterator::rewind — Rewind the Iterator to the first element
- Iterator::valid — Checks if current position is valid
The IteratorAggregate interface
(PHP 5 >= 5.0.0)
Introdução
Interface to create an external Iterator.
Resumo da Interface
Exemplo #1 Basic usage
<?php
class myData implements IteratorAggregate {
public $property1 = "Public property one";
public $property2 = "Public property two";
public $property3 = "Public property three";
public function __construct() {
$this->property4 = "last property";
}
public function getIterator() {
return new ArrayIterator($this);
}
}
$obj = new myData;
foreach($obj as $key => $value) {
var_dump($key, $value);
echo "\n";
}
?>
O exemplo acima irá imprimir algo similar a:
string(9) "property1" string(19) "Public property one" string(9) "property2" string(19) "Public property two" string(9) "property3" string(21) "Public property three" string(9) "property4" string(13) "last property"
IteratorAggregate::getIterator
(PHP 5 >= 5.0.0)
IteratorAggregate::getIterator — Retrieve an external iterator
Descrição
Returns an external iterator.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
An instance of an object implementing Iterator or Traversable
Erros
Throws an Exception on failure.
Índice
- IteratorAggregate::getIterator — Retrieve an external iterator
The ArrayAccess interface
(PHP 5 >= 5.0.0)
Introdução
Interface to provide accessing objects as arrays.
Resumo da Interface
Exemplo #1 Basic usage
<?php
class obj implements arrayaccess {
private $container = array();
public function __construct() {
$this->container = array(
"one" => 1,
"two" => 2,
"three" => 3,
);
}
public function offsetSet($offset, $value) {
if (is_null($offset)) {
$this->container[] = $value;
} else {
$this->container[$offset] = $value;
}
}
public function offsetExists($offset) {
return isset($this->container[$offset]);
}
public function offsetUnset($offset) {
unset($this->container[$offset]);
}
public function offsetGet($offset) {
return isset($this->container[$offset]) ? $this->container[$offset] : null;
}
}
$obj = new obj;
var_dump(isset($obj["two"]));
var_dump($obj["two"]);
unset($obj["two"]);
var_dump(isset($obj["two"]));
$obj["two"] = "A value";
var_dump($obj["two"]);
$obj[] = 'Append 1';
$obj[] = 'Append 2';
$obj[] = 'Append 3';
print_r($obj);
?>
O exemplo acima irá imprimir algo similar a:
bool(true)
int(2)
bool(false)
string(7) "A value"
obj Object
(
[container:obj:private] => Array
(
[one] => 1
[three] => 3
[two] => A value
[0] => Append 1
[1] => Append 2
[2] => Append 3
)
)
ArrayAccess::offsetExists
(PHP 5 >= 5.0.0)
ArrayAccess::offsetExists — Whether a offset exists
Descrição
Whether or not an offset exists.
This method is executed when using isset() or empty() on objects implementing ArrayAccess.
Nota:
When using empty() ArrayAccess::offsetGet() will be called and checked if empty only if ArrayAccess::offsetExists() returns TRUE.
Parâmetros
- offset
-
An offset to check for.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Nota:
The return value will be casted to boolean if non-boolean was returned.
Exemplos
Exemplo #1 ArrayAccess::offsetExists() example
<?php
class obj implements arrayaccess {
public function offsetSet($offset, $value) {
var_dump(__METHOD__);
}
public function offsetExists($var) {
var_dump(__METHOD__);
if ($var == "foobar") {
return true;
}
return false;
}
public function offsetUnset($var) {
var_dump(__METHOD__);
}
public function offsetGet($var) {
var_dump(__METHOD__);
return "value";
}
}
$obj = new obj;
echo "Runs obj::offsetExists()\n";
var_dump(isset($obj["foobar"]));
echo "\nRuns obj::offsetExists() and obj::offsetGet()\n";
var_dump(empty($obj["foobar"]));
echo "\nRuns obj::offsetExists(), *not* obj:offsetGet() as there is nothing to get\n";
var_dump(empty($obj["foobaz"]));
?>
O exemplo acima irá imprimir algo similar a:
Runs obj::offsetExists() string(17) "obj::offsetExists" bool(true) Runs obj::offsetExists() and obj::offsetGet() string(17) "obj::offsetExists" string(14) "obj::offsetGet" bool(false) Runs obj::offsetExists(), *not* obj:offsetGet() as there is nothing to get string(17) "obj::offsetExists" bool(true)
ArrayAccess::offsetGet
(PHP 5 >= 5.0.0)
ArrayAccess::offsetGet — Offset to retrieve
Descrição
Returns the value at specified offset.
This method is executed when checking if offset is empty().
Parâmetros
- offset
-
The offset to retrieve.
Notas
Nota:
Starting with PHP 5.3.4, the prototype checks were relaxed and it's possible for implementations of this method to return by reference. This makes indirect modifications to the overloaded array dimensions of ArrayAccess objects possible.
A direct modification is one that replaces completely the value of the array dimension, as in $obj[6] = 7. An indirect modification, on the other hand, only changes part of the dimension, or attempts to assign the dimension by reference to another variable, as in $obj[6][7] = 7 or $var =& $obj[6]. Increments with ++ and decrements with -- are also implemented in a way that requires indirect modification.
While direct modification triggers a call to ArrayAccess::offsetSet(), indirect modification triggers a call to ArrayAccess::offsetGet(). In that case, the implementation of ArrayAccess::offsetGet() must be able to return by reference, otherwise an E_NOTICE message is raised.
Valor Retornado
Can return all value types.
ArrayAccess::offsetSet
(PHP 5 >= 5.0.0)
ArrayAccess::offsetSet — Offset to set
Descrição
Assigns a value to the specified offset.
Parâmetros
- offset
-
The offset to assign the value to.
- value
-
The value to set.
Valor Retornado
Não há valor retornado.
Notas
Nota:
The offset parameter will be set to NULL if another value is not available, like in the following example.
<?php
$arrayaccess[] = "first value";
$arrayaccess[] = "second value";
print_r($arrayaccess);
?>O exemplo acima irá imprimir:
Array ( [0] => first value [1] => second value )
Nota:
This function is not called in assignments by reference and otherwise indirect changes to array dimensions overloaded with ArrayAccess (indirect in the sense they are made not by changing the dimension directly, but by changing a sub-dimension or sub-property or assigning the array dimension by reference to another variable). Instead, ArrayAccess::offsetGet() is called. The operation will only be successful if that method returns by reference, which is only possible since PHP 5.3.4.
ArrayAccess::offsetUnset
(PHP 5 >= 5.0.0)
ArrayAccess::offsetUnset — Offset to unset
Parâmetros
- offset
-
The offset to unset.
Valor Retornado
Não há valor retornado.
Índice
- ArrayAccess::offsetExists — Whether a offset exists
- ArrayAccess::offsetGet — Offset to retrieve
- ArrayAccess::offsetSet — Offset to set
- ArrayAccess::offsetUnset — Offset to unset
The Serializable interface
(PHP 5 >= 5.1.0)
Introdução
Interface for customized serializing.
Classes that implement this interface no longer support __sleep() and __wakeup(). The method serialize is called whenever an instance needs to be serialized. This does not invoke __destruct() or has any other side effect unless programmed inside the method. When the data is unserialized the class is known and the appropriate unserialize() method is called as a constructor instead of calling __construct(). If you need to execute the standard constructor you may do so in the method.
Resumo da Interface
Exemplo #1 Basic usage
<?php
class obj implements Serializable {
private $data;
public function __construct() {
$this->data = "My private data";
}
public function serialize() {
return serialize($this->data);
}
public function unserialize($data) {
$this->data = unserialize($data);
}
public function getData() {
return $this->data;
}
}
$obj = new obj;
$ser = serialize($obj);
var_dump($ser);
$newobj = unserialize($ser);
var_dump($newobj->getData());
?>
O exemplo acima irá imprimir algo similar a:
string(38) "C:3:"obj":23:{s:15:"My private data";}"
string(15) "My private data"
Serializable::serialize
(PHP 5 >= 5.1.0)
Serializable::serialize — String representation of object
Descrição
Should return the string representation of the object.
Nota:
This method acts as the destructor of the object. The __destruct() method will not be called after this method.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Returns the string representation of the object or NULL
Erros
Throws Exception when returning other types then strings and NULL
Serializable::unserialize
(PHP 5 >= 5.1.0)
Serializable::unserialize — Constructs the object
Descrição
Called during unserialization of the object.
Nota:
This method acts as the constructor of the object. The __construct() method will not be called after this method.
Parâmetros
- serialized
-
The string representation of the object.
Valor Retornado
The return value from this method is ignored.
Índice
- Serializable::serialize — String representation of object
- Serializable::unserialize — Constructs the object
The Closure class
(No version information available, might only be in SVN)
Introdução
Class used to represent anonymous functions.
Anonymous functions, implemented in PHP 5.3, yield objects of this type. This fact used to be considered an implementation detail, but it can now be relied upon. Starting with PHP 5.4, this class has methods that allow further control of the anonymous function after it has been created.
Besides the methods listed here, this class also has an __invoke method. This is for consistency with other classes that implement calling magic, as this method is not used for calling the function.
Closure::__construct
(No version information available, might only be in SVN)
Closure::__construct — Constructor that disallows instantiation
Descrição
This method exists only to disallow instantiation of the Closure class. Objects of this class are created in the fashion described on the anonymous functions page.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
This method has no return value; it simply emits an error (of type E_RECOVERABLE_ERROR).
Veja Também
Closure::bind
(No version information available, might only be in SVN)
Closure::bind — Duplicates a closure with a specific bound object and class scope
Descrição
This method is a static version of Closure::bindTo(). See the documentation of that method for more information.
Parâmetros
- closure
-
The anonymous functions to bind.
- newthis
-
The object to which the given anonymous function should be bound, or NULL for the closure to be unbound.
- newscope
-
The class scope to which associate the closure is to be associated, or 'static' to keep the current one. If an object is given, the type of the object will be used instead. This determines the visibility of protected and private methods of the bound object.
Valor Retornado
Returns a new Closure object or FALSE on failure
Exemplos
Exemplo #1 Closure::bind() example
<?php
class A {
private static $sfoo = 1;
private $ifoo = 2;
}
$cl1 = static function() {
return A::$sfoo;
};
$cl2 = function() {
return $this->ifoo;
};
$bcl1 = Closure::bind($cl1, null, 'A');
$bcl2 = Closure::bind($cl2, new A(), 'A');
echo $bcl1(), "\n";
echo $bcl2(), "\n";
?>
O exemplo acima irá imprimir algo similar a:
1 2
Veja Também
- Anonymous functions
- Closure::bindTo() - Duplicates the closure with a new bound object and class scope
Closure::bindTo
(No version information available, might only be in SVN)
Closure::bindTo — Duplicates the closure with a new bound object and class scope
Descrição
Create and return a new anonymous function with the same body and bound variables as this one, but possibly with a different bound object and a new class scope.
The “bound object” determines the value $this will have in the function body and the “class scope” represents a class which determines which private and protected members the anonymous function will be able to access. Namely, the members that will be visible are the same as if the anonymous function were a method of the class given as value of the newscope parameter.
Static closures cannot have any bound object (the value of the parameter newthis should be NULL), but this function can nevertheless be used to change their class scope.
This function will ensure that for a non-static closure, having a bound instance will imply being scoped and vice-versa. To this end, non-static closures that are given a scope but a NULL instance are made static and non-static non-scoped closures that are given a non-null instance are scoped to an unspecified class.
Nota:
If you only want to duplicate the anonymous functions, you can use cloning instead.
Parâmetros
- newthis
-
The object to which the given anonymous function should be bound, or NULL for the closure to be unbound.
- newscope
-
The class scope to which associate the closure is to be associated, or 'static' to keep the current one. If an object is given, the type of the object will be used instead. This determines the visibility of protected and private methods of the bound object.
Valor Retornado
Returns the newly created Closure object or FALSE on failure
Exemplos
Exemplo #1 Closure::bindTo() example
<?php
class A {
function __construct($val) {
$this->val = $val;
}
function getClosure() {
//returns closure bound to this object and scope
return function() { return $this->val; };
}
}
$ob1 = new A(1);
$ob2 = new A(2);
$cl = $ob1->getClosure();
echo $cl(), "\n";
$cl = $cl->bindTo($ob2);
echo $cl(), "\n";
?>
O exemplo acima irá imprimir algo similar a:
1 2
Veja Também
- Anonymous functions
- Closure::bind() - Duplicates a closure with a specific bound object and class scope
Índice
- Closure::__construct — Constructor that disallows instantiation
- Closure::bind — Duplicates a closure with a specific bound object and class scope
- Closure::bindTo — Duplicates the closure with a new bound object and class scope
Context options and parameters
PHP offers various context options and parameters which can be used with all filesystem and stream wrappers. The context is created with stream_context_create(). Options are set with stream_context_set_option() and parameters with stream_context_set_params().
Socket context options
Socket context options — Socket context option listing
Descrição
Socket context options are available for all wrappers that work over sockets, like tcp, http and ftp.
Histórico
| Versão | Descrição |
|---|---|
| 5.1.0 | Added bindto. |
| 5.3.3 | Added backlog. |
Exemplos
Exemplo #1 Basic bindto usage example
<?php
// connect to the internet using the '192.168.0.100' IP
$opts = array(
'socket' => array(
'bindto' => '192.168.0.100:0',
),
);
// connect to the internet using the '192.168.0.100' IP and port '7000'
$opts = array(
'socket' => array(
'bindto' => '192.168.0.100:7000',
),
);
// connect to the internet using port '7000'
$opts = array(
'socket' => array(
'bindto' => '0:7000',
),
);
// create the context...
$context = stream_context_create($opts);
// ...and use it to fetch the data
echo file_get_contents('http://www.example.com', false, $context);
?>
HTTP context options
HTTP context options — HTTP context option listing
Descrição
Context options for http:// and https:// transports.
Histórico
| Versão | Descrição |
|---|---|
| 5.3.4 | Added follow_location. |
| 5.3.0 | The protocol_version supports chunked transfer decoding when set to 1.1. |
| 5.2.10 | Added ignore_errors. |
| 5.2.10 | The header can now be an numerically indexed array. |
| 5.2.1 | Added timeout. |
| 5.1.0 | Added HTTPS proxying through HTTP proxies. |
| 5.1.0 | Added max_redirects. |
| 5.1.0 | Added protocol_version. |
Exemplos
Exemplo #1 Fetch a page and send POST data
<?php
$postdata = http_build_query(
array(
'var1' => 'some content',
'var2' => 'doh'
)
);
$opts = array('http' =>
array(
'method' => 'POST',
'header' => 'Content-type: application/x-www-form-urlencoded',
'content' => $postdata
)
);
$context = stream_context_create($opts);
$result = file_get_contents('http://example.com/submit.php', false, $context);
?>
Exemplo #2 Ignore redirects but fetch headers and content
<?php
$url = "http://www.example.org/header.php";
$opts = array('http' =>
array(
'method' => 'GET',
'max_redirects' => '0',
'ignore_errors' => '1'
)
);
$context = stream_context_create($opts);
$stream = fopen($url, 'r', false, $context);
// header information as well as meta data
// about the stream
var_dump(stream_get_meta_data($stream));
// actual data at $url
var_dump(stream_get_contents($stream));
fclose($stream);
?>
Notas
Nota: Underlying socket stream context options
Additional context options may be supported by the underlying transport For http:// streams, refer to context options for the tcp:// transport. For https:// streams, refer to context options for the ssl:// transport.
Nota: HTTP status line
When this stream wrapper follows a redirect, the wrapper_data returned by stream_get_meta_data() might not necessarily contain the HTTP status line that actually applies to the content data at index 0.The first request returned a 301 (permanent redirect), so the stream wrapper automatically followed the redirect to get a 200 response (index = 4).array ( 'wrapper_data' => array ( 0 => 'HTTP/1.0 301 Moved Permantenly', 1 => 'Cache-Control: no-cache', 2 => 'Connection: close', 3 => 'Location: http://example.com/foo.jpg', 4 => 'HTTP/1.1 200 OK', ...
FTP context options
FTP context options — FTP context option listing
Descrição
Context options for ftp:// and ftps:// transports.
Histórico
| Versão | Descrição |
|---|---|
| 5.1.0 | Added proxy. |
| 5.0.0 | Added overwrite and resume_pos. |
Notas
Nota: Underlying socket stream context options
Additional context options may be supported by the underlying transport For ftp:// streams, refer to context options for the tcp:// transport. For ftps:// streams, refer to context options for the ssl:// transport.
SSL context options
SSL context options — SSL context option listing
Descrição
Context options for ssl:// and tls:// transports.
Histórico
| Versão | Descrição |
|---|---|
| 5.3.2 | Added SNI_enabled and SNI_server_name. |
| 5.0.0 | Added capture_peer_cert, capture_peer_chain and ciphers. |
Notas
Nota: Because ssl:// is the underlying transport for the https:// and ftps:// wrappers, any context options which apply to ssl:// also apply to https:// and ftps://.
Nota: For SNI (Server Name Indication) to be available, then PHP must be compiled with OpenSSL 0.9.8j or greater. Use the OPENSSL_TLSEXT_SERVER_NAME to determine whether SNI is supported.
CURL context options
CURL context options — CURL context option listing
Descrição
CURL context options are available when the CURL extension was compiled using the --with-curlwrappers configure option.
Exemplos
Exemplo #1 Fetch a page and send POST data
<?php
$postdata = http_build_query(
array(
'var1' => 'some content',
'var2' => 'doh'
)
);
$opts = array('http' =>
array(
'method' => 'POST',
'header' => 'Content-type: application/x-www-form-urlencoded',
'content' => $postdata
)
);
$context = stream_context_create($opts);
$result = file_get_contents('http://example.com/submit.php', false, $context);
?>
Phar context options
Phar context options — Phar context option listing
Descrição
Context options for phar:// wrapper.
Context parameters
Context parameters — Context parameter listing
Descrição
These parameters can be set on a context using the stream_context_set_params() function.
Índice
- Socket context options — Socket context option listing
- HTTP context options — HTTP context option listing
- FTP context options — FTP context option listing
- SSL context options — SSL context option listing
- CURL context options — CURL context option listing
- Phar context options — Phar context option listing
- Context parameters — Context parameter listing
Supported Protocols and Wrappers
PHP comes with many built-in wrappers for various URL-style protocols for use with the filesystem functions such as fopen(), copy(), file_exists() and filesize(). In addition to these wrappers, it is possible to register custom wrappers using the stream_wrapper_register() function.
Nota: The URL syntax used to describe a wrapper only supports the scheme://... syntax. The scheme:/ and scheme: syntaxes are not supported.
file://
file:// — Accessing local filesystem
Descrição
Filesystem is the default wrapper used with PHP and represents the local filesystem. When a relative path is specified (a path which does not begin with /, \, \\, or a Windows drive letter) the path provided will be applied against the current working directory. In many cases this is the directory in which the script resides unless it has been changed. Using the CLI sapi, this defaults to the directory from which the script was called.
With some functions, such as fopen() and file_get_contents(), include_path may be optionally searched for relative paths as well.
Opções
- /path/to/file.ext
- relative/path/to/file.ext
- fileInCwd.ext
- C:/path/to/winfile.ext
- C:\path\to\winfile.ext
- \\smbserver\share\path\to\winfile.ext
- file:///path/to/file.ext
Histórico
| Versão | Descrição |
|---|---|
| 5.0.0 | Added file://. |
http://
https://
http:// -- https:// — Accessing HTTP(s) URLs
Descrição
Allows read-only access to files/resources via HTTP 1.0, using the HTTP GET method. A Host: header is sent with the request to handle name-based virtual hosts. If you have configured a user_agent string using your php.ini file or the stream context, it will also be included in the request.
The stream allows access to the body of the resource; the headers are stored in the $http_response_header variable.
If it's important to know the URL of the resource where your document came from (after all redirects have been processed), you'll need to process the series of response headers returned by the stream.
The from directive will be used for the From: header if set and not overwritten by the Context options and parameters.
Opções
- http://example.com
- http://example.com/file.php?var1=val1&var2=val2
- http://user:password@example.com
- https://example.com
- https://example.com/file.php?var1=val1&var2=val2
- https://user:password@example.com
Histórico
| Versão | Descrição |
|---|---|
| 4.3.7 | Detect buggy IIS servers to avoid "SSL: Fatal Protocol Error" errors. |
| 4.3.0 | Added https://. |
| 4.0.5 | Added support for redirects. |
Exemplos
Exemplo #1 Detecting which URL we ended up on after redirects
<?php
$url = 'http://www.example.com/redirecting_page.php';
$fp = fopen($url, 'r');
$meta_data = stream_get_meta_data($fp);
foreach ($meta_data['wrapper_data'] as $response) {
/* Were we redirected? */
if (strtolower(substr($response, 0, 10)) == 'location: ') {
/* update $url with where we were redirected to */
$url = substr($response, 10);
}
}
?>
Exemplo #2 Sending custom headers with an HTTP request
Custom headers may be sent using context options. It is also possible to use this hack: Custom headers may be sent with an HTTP request by taking advantage of a side-effect in the handling of the user_agent INI setting. Set user_agent to any valid string (such as the default PHP/version setting) followed by a carriage-return/line-feed pair and any additional headers.
<?php
ini_set('user_agent', "PHP\r\nX-MyCustomHeader: Foo");
$fp = fopen('http://www.example.com/index.php', 'r');
?>
Results in the following request being sent:
GET /index.php HTTP/1.0 Host: www.example.com User-Agent: PHP X-MyCustomHeader: Foo
Notas
Nota: HTTPS is only supported when the openssl extension is enabled.
HTTP connections are read-only; writing data or copying files to an HTTP resource is not supported.
Sending POST and PUT requests, for example, can be done with the help of HTTP Contexts.
Veja Também
- HTTP context options
- $http_response_header
- stream_get_meta_data() - Retrieves header/meta data from streams/file pointers
ftp://
ftps://
ftp:// -- ftps:// — Accessing FTP(s) URLs
Descrição
Allows read access to existing files and creation of new files via FTP. If the server does not support passive mode ftp, the connection will fail.
You can open files for either reading or writing, but not both simultaneously. If the remote file already exists on the ftp server and you attempt to open it for writing but have not specified the context option overwrite, the connection will fail. If you need to overwrite existing files over ftp, specify the overwrite option in the context and open the file for writing. Alternatively, you can use the FTP extension.
If you have set the from directive in php.ini, then this value will be sent as the anonymous FTP password.
Opções
- ftp://example.com/pub/file.txt
- ftp://user:password@example.com/pub/file.txt
- ftps://example.com/pub/file.txt
- ftps://user:password@example.com/pub/file.txt
Histórico
| Versão | Descrição |
|---|---|
| 4.3.0 | Added ftps://. |
Notas
Nota:
FTPS is only supported when the openssl extension is enabled.
If the server does not support SSL, then the connection falls back to regular unencrypted ftp.
Nota: Appending
As of PHP 5.0.0 files may be appended via the ftp:// URL wrapper. In prior versions, attempting to append to a file via ftp:// will result in failure.
Veja Também
php://
php:// — Accessing various I/O streams
Descrição
PHP provides a number of miscellaneous I/O streams that allow access to PHP's own input and output streams, the standard input, output and error file descriptors, in-memory and disk-backed temporary file streams, and filters that can manipulate other file resources as they are read from and written to.
php://stdin, php://stdout and php://stderr
php://stdin, php://stdout and php://stderr allow direct access to the corresponding input or output stream of the PHP process. The stream references a duplicate file descriptor, so if you open php://stdin and later close it, you close only your copy of the descriptor-the actual stream referenced by STDIN is unaffected. Note that PHP exhibited buggy behavior in this regard until PHP 5.2.1. It is recommended that you simply use the constants STDIN, STDOUT and STDERR instead of manually opening streams using these wrappers.
php://stdin is read-only, whereas php://stdout and php://stderr are write-only.
php://input
php://input is a read-only stream that allows you to read raw data from the request body. In the case of POST requests, it is preferable to use php://input instead of $HTTP_RAW_POST_DATA as it does not depend on special php.ini directives. Moreover, for those cases where $HTTP_RAW_POST_DATA is not populated by default, it is a potentially less memory intensive alternative to activating always_populate_raw_post_data. php://input is not available with enctype="multipart/form-data".
Nota: A stream opened with php://input can only be read once; the stream does not support seek operations. However, depending on the SAPI implementation, it may be possible to open another php://input stream and restart reading. This is only possible if the request body data has been saved. Typically, this is the case for POST requests, but not other request methods, such as PUT or PROPFIND.
php://output
php://output is a write-only stream that allows you to write to the output buffer mechanism in the same way as print() and echo().
php://fd
php://fd allows direct access to the given file descriptor. For example, php://fd/3 refers to file descriptor 3.
php://memory and php://temp
php://memory and php://temp are read-write streams that allow temporary data to be stored in a file-like wrapper. The only difference between the two is that php://memory will always store its data in memory, whereas php://temp will use a temporary file once the amount of data stored hits a predefined limit (the default is 2 MB). The location of this temporary file is determined in the same way as the sys_get_temp_dir() function.
The memory limit of php://temp can be controlled by appending /maxmemory:NN, where NN is the maximum amount of data to keep in memory before using a temporary file, in bytes.
php://filter
php://filter is a kind of meta-wrapper designed to permit the application of filters to a stream at the time of opening. This is useful with all-in-one file functions such as readfile(), file(), and file_get_contents() where there is otherwise no opportunity to apply a filter to the stream prior the contents being read.
The php://filter target takes the following parameters as part of its path. Please refer to the examples for specifics on using these parameters.
| Name | Description |
|---|---|
| resource=<stream to be filtered> | This parameter is required. It specifies the stream that you would like to filter. |
| read=<filter list to apply to read chain> | This parameter is optional. One or more filter names can be provided here, separated by the pipe character (|). |
| write=<filter list to apply to write chain> | This parameter is optional. One or more filter names can be provided here, separated by the pipe character (|). |
| <filter list to apply to both chains> | Any filter lists which are not prefixed by read= or write= will be applied to both the read and write chains as appropriate. |
Histórico
| Versão | Descrição |
|---|---|
| 5.3.6 | php://fd was added. |
| 5.1.0 | php://memory and php://temp were added. |
| 5.0.0 | php://filter was added. |
Exemplos
Exemplo #1 php://temp/maxmemory
This optional parameter allows setting the memory limit before php://temp starts using a temporary file.
<?php
// Set the limit to 5 MB.
$fiveMBs = 5 * 1024 * 1024;
$fp = fopen("php://temp/maxmemory:$fiveMBs", 'r+');
fputs($fp, "hello\n");
// Read what we have written.
rewind($fp);
echo stream_get_contents($fp);
?>
Exemplo #2 php://filter/resource=<stream to be filtered>
This parameter must be located at the end of your php://filter specification and should point to the stream which you want filtered.
<?php
/* This is equivalent to simply:
readfile("http://www.example.com");
since no filters are actually specified */
readfile("php://filter/resource=http://www.example.com");
?>
Exemplo #3 php://filter/read=<filter list to apply to read chain>
This parameter takes one or more filternames separated by the pipe character |.
<?php
/* This will output the contents of
www.example.com entirely in uppercase */
readfile("php://filter/read=string.toupper/resource=http://www.example.com");
/* This will do the same as above
but will also ROT13 encode it */
readfile("php://filter/read=string.toupper|string.rot13/resource=http://www.example.com");
?>
Exemplo #4 php://filter/write=<filter list to apply to write chain>
This parameter takes one or more filternames separated by the pipe character |.
<?php
/* This will filter the string "Hello World"
through the rot13 filter, then write to
example.txt in the current directory */
file_put_contents("php://filter/write=string.rot13/resource=example.txt","Hello World");
?>
zlib://
bzip2://
zip://
zlib:// -- bzip2:// -- zip:// — Compression Streams
Descrição
zlib: PHP 4.0.4 - PHP 4.2.3 (systems with fopencookie only)
compress.zlib:// and compress.bzip2:// PHP 4.3.0 and up
zlib: works like gzopen(), except that the stream can be used with fread() and the other filesystem functions. This is deprecated as of PHP 4.3.0 due to ambiguities with filenames containing ':' characters; use compress.zlib:// instead.
compress.zlib:// and compress.bzip2:// are equivalent to gzopen() and bzopen() respectively, and operate even on systems that do not support fopencookie.
ZIP extension registers zip: wrapper.
Opções
- zlib:
- compress.zlib://
- compress.bzip2://
data://
data:// — Data (RFC 2397)
Descrição
The data: (» RFC 2397) stream wrapper is available since PHP 5.2.0.
Opções
- data://text/plain;base64,
Exemplos
Exemplo #1 Print data:// contents
<?php
// prints "I love PHP"
echo file_get_contents('data://text/plain;base64,SSBsb3ZlIFBIUAo=');
?>
Exemplo #2 Fetch the media type
<?php
$fp = fopen('data://text/plain;base64,', 'r');
$meta = stream_get_meta_data($fp);
// prints "text/plain"
echo $meta['mediatype'];
?>
glob://
glob:// — Find pathnames matching pattern
Descrição
The glob: stream wrapper is available since PHP 5.3.0.
Opções
- glob://
Exemplos
Exemplo #1 Basic usage
<?php
// Loop over all *.php files in ext/spl/examples/ directory
// and print the filename and its size
$it = new DirectoryIterator("glob://ext/spl/examples/*.php");
foreach($it as $f) {
printf("%s: %.1FK\n", $f->getFilename(), $f->getSize()/1024);
}
?>
tree.php: 1.0K findregex.php: 0.6K findfile.php: 0.7K dba_dump.php: 0.9K nocvsdir.php: 1.1K phar_from_dir.php: 1.0K ini_groups.php: 0.9K directorytree.php: 0.9K dba_array.php: 1.1K class_tree.php: 1.8K
phar://
phar:// — PHP Archive
Descrição
The phar:// stream wrapper is available since PHP 5.3.0. See Phar stream wrapper for detailed description.
Opções
- phar://
Veja Também
ssh2://
ssh2:// — Secure Shell 2
Descrição
ssh2.shell:// ssh2.exec:// ssh2.tunnel:// ssh2.sftp:// ssh2.scp:// PHP 4.3.0 and up (PECL)
Nota: This wrapper is not enabled by default
In order to use the ssh2.*:// wrappers you must install the » SSH2 extension available from » PECL.
In addition to accepting traditional URI login details, the ssh2 wrappers will also reuse open connections by passing the connection resource in the host portion of the URL.
Opções
- ssh2.shell://user:pass@example.com:22/xterm
- ssh2.exec://user:pass@example.com:22/usr/local/bin/somecmd
- ssh2.tunnel://user:pass@example.com:22/192.168.0.1:14
- ssh2.sftp://user:pass@example.com:22/path/to/filename
Exemplos
Exemplo #1 Opening a stream from an active connection
<?php
$session = ssh2_connect('example.com', 22);
ssh2_auth_pubkey_file($session, 'username', '/home/username/.ssh/id_rsa.pub',
'/home/username/.ssh/id_rsa', 'secret');
$stream = fopen("ssh2.tunnel://$session/remote.example.com:1234", 'r');
?>
rar://
rar:// — RAR
Descrição
The wrapper takes the url encoded path to the RAR archive (relative or absolute), an optional asterik (*), an optional number sign (#) and an optional url encoded entry name, as stored in the archive. Specifying an entry name requires the number sign; a leading forward slash in the entry name is optional.
This wrapper can open both files and directories. When opening directories, the asterisk sign forces the directory entries names to be returned unencoded. If it's not specified, they will be returned url encoded – the reason for this is to allow the wrapper to be correctly used with built-in functionality like the RecursiveDirectoryIterator in the presence of file names that seem like url encoded data.
If the pound sign and the entry name part are not included, the root of the archive will be displayed. This differs from regular directories in that the resulting stream will not contain information such as the modification time, as the root directory is not stored in an individual entry in the archive. The usage of the wrapper with RecursiveDirectoryIterator requires the number sign to be included in the URL when accessing the root, so that the URLs of the children may be constructed correctly.
Nota: This wrapper is not enabled by default
In order to use the rar:// wrapper, you must install the » rar extension available from » PECL.
rar:// Available since PECL rar 3.0.0
Opções
- rar://<url encoded archive name>[*][#[<url encoded entry name>]]
Exemplos
Exemplo #1 Traversing a RAR archive
<?php
class MyRecDirIt extends RecursiveDirectoryIterator {
function current() {
return rawurldecode($this->getSubPathName()) .
(is_dir(parent::current())?" [DIR]":"");
}
}
$f = "rar://" . rawurlencode(dirname(__FILE__)) .
DIRECTORY_SEPARATOR . 'dirs_and_extra_headers.rar#';
$it = new RecursiveTreeIterator(new MyRecDirIt($f));
foreach ($it as $s) {
echo $s, "\n";
}
?>
O exemplo acima irá imprimir algo similar a:
|-allow_everyone_ni [DIR]
|-file1.txt
|-file2_אּ.txt
|-with_streams.txt
\-אּ [DIR]
|-אּ\%2Fempty%2E [DIR]
| \-אּ\%2Fempty%2E\file7.txt
|-אּ\empty [DIR]
|-אּ\file3.txt
|-אּ\file4_אּ.txt
\-אּ\אּ_2 [DIR]
|-אּ\אּ_2\file5.txt
\-אּ\אּ_2\file6_אּ.txt
Exemplo #2 Opening an encrypted file (header encryption)
<?php
$stream = fopen("rar://" .
rawurlencode(dirname(__FILE__)) . DIRECTORY_SEPARATOR .
'encrypted_headers.rar' . '#encfile1.txt', "r", false,
stream_context_create(
array(
'rar' =>
array(
'open_password' => 'samplepassword'
)
)
)
);
var_dump(stream_get_contents($stream));
/* creation and last access date is opt-in in WinRAR, hence most
* files don't have them */
var_dump(fstat($stream));
?>
O exemplo acima irá imprimir algo similar a:
string(26) "Encrypted file 1 contents."
Array
(
[0] => 0
[1] => 0
[2] => 33206
[3] => 1
[4] => 0
[5] => 0
[6] => 0
[7] => 26
[8] => 0
[9] => 1259550052
[10] => 0
[11] => -1
[12] => -1
[dev] => 0
[ino] => 0
[mode] => 33206
[nlink] => 1
[uid] => 0
[gid] => 0
[rdev] => 0
[size] => 26
[atime] => 0
[mtime] => 1259550052
[ctime] => 0
[blksize] => -1
[blocks] => -1
)
ogg://
ogg:// — Audio streams
Descrição
Files opened for reading via the ogg:// wrapper are treated as compressed audio encoded using the OGG/Vorbis codec. Similarly, files opened for writing or appending via the ogg:// wrapper are writen as compressed audio data. stream_get_meta_data(), when used on an OGG/Vorbis file opened for reading will return various details about the stream including the vendor tag, any included comments, the number of channels, the sampling rate, and the encoding rate range described by: bitrate_lower, bitrate_upper, bitrate_nominal, and bitrate_window.
ogg:// PHP 4.3.0 and up (PECL)
Nota: This wrapper is not enabled by default
In order to use the ogg:// wrapper you must install the » OGG/Vorbis extension available from » PECL.
Opções
- ogg://soundfile.ogg
- ogg:///path/to/soundfile.ogg
- ogg://http://www.example.com/path/to/soundstream.ogg
Exemplos
expect://
expect:// — Process Interaction Streams
Descrição
Streams opened via the expect:// wrapper provide access to process'es stdio, stdout and stderr via PTY.
Nota: This wrapper is not enabled by default
In order to use the expect:// wrapper you must install the » Expect extension available from » PECL.
expect:// PHP 4.3.0 and up (PECL)
Opções
- expect://command
Exemplos
Índice
- file:// — Accessing local filesystem
- http:// — Accessing HTTP(s) URLs
- ftp:// — Accessing FTP(s) URLs
- php:// — Accessing various I/O streams
- zlib:// — Compression Streams
- data:// — Data (RFC 2397)
- glob:// — Find pathnames matching pattern
- phar:// — PHP Archive
- ssh2:// — Secure Shell 2
- rar:// — RAR
- ogg:// — Audio streams
- expect:// — Process Interaction Streams
- Sintaxe Básica
- Tipos
- Variáveis
- Constantes
- Expressões
- Operadores
- Estruturas de Controle
- Funções
- Classes e Objetos
- Introdução
- O Básico
- Properties
- Constantes do Objeto
- Autoloading Objects
- Construtores e Destrutores
- Visibilidade
- Object Inheritance
- Operador de Resolução de Escopo (::)
- Palavra-Chave 'static'
- Abstração de Objetos
- Interfaces de Objetos
- Traits
- Sobrecarga
- Iteração de Objetos
- Patterns
- Métodos Mágicos
- Palavra-Chave 'final'
- Clonando objetos
- Comparando objetos
- Indução de Tipo
- Late Static Bindings
- Objetos e Referências
- Object Serialization
- OOP Changelog
- Namespaces
- Exceções
- Referências
- Variáveis pré-definidas
- Superglobais — Superglobais são variáveis nativas que estão sempre disponíveis em todos escopos
- $GLOBALS — Referencia todas variáveis disponíveis no escopo global
- $_SERVER — Informação do servidor e ambiente de execução
- $_GET — HTTP GET variáveis
- $_POST — HTTP POST variables
- $_FILES — HTTP File Upload variáveis
- $_REQUEST — Variáveis de requisição HTTP
- $_SESSION — Variáveis de sessão
- $_ENV — Environment variables
- $_COOKIE — HTTP Cookies
- $php_errormsg — A mensagem de erro anterior
- $HTTP_RAW_POST_DATA — Informação não-tratada do POST
- $http_response_header — Cabeçalhos de resposta HTTP
- $argc — O número de argumentos passados para o script
- $argv — Array de argumentos passados para o script
- Exceções pré-definidas
- Predefined Interfaces
- Traversable — The Traversable interface
- Iterator — The Iterator interface
- IteratorAggregate — The IteratorAggregate interface
- ArrayAccess — The ArrayAccess interface
- Serializable — The Serializable interface
- Closure — The Closure class
- Context options and parameters
- Socket context options — Socket context option listing
- HTTP context options — HTTP context option listing
- FTP context options — FTP context option listing
- SSL context options — SSL context option listing
- CURL context options — CURL context option listing
- Phar context options — Phar context option listing
- Context parameters — Context parameter listing
- Supported Protocols and Wrappers
- file:// — Accessing local filesystem
- http:// — Accessing HTTP(s) URLs
- ftp:// — Accessing FTP(s) URLs
- php:// — Accessing various I/O streams
- zlib:// — Compression Streams
- data:// — Data (RFC 2397)
- glob:// — Find pathnames matching pattern
- phar:// — PHP Archive
- ssh2:// — Secure Shell 2
- rar:// — RAR
- ogg:// — Audio streams
- expect:// — Process Interaction Streams
Segurança
Introdução
PHP é uma linguagem poderosa e um interpretador, seja incluído em um servidor web como um módulo ou executado separadamente como binário CGI, é possível acessar arquivos, executar comandos e abrir conexões de rede no servidor. Essas propriedades fazem qualquer coisa executando em um servidor web inseguras por padrão. PHP é desenhado especificamente para ser uma linguagem mais segura para escrever programas CGI que Perl ou C, e com a escolha correta de opções de configuração em tempo compilação ou de execução, e práticas corretas de programação, ela pode dar a combinação exata de liberdade e segurança que você precisa.
Como existem diferentes maneiras de utilizar o PHP, existem várias opções de configuração controlando seu comportamento. Um grande leque de opções garante que você pode usar o PHP para vários propósitos, mas também significa que existem combinações dessas opções e configurações do servidor que resultam em uma instalação insegura.
A flexibilidade de configuração do PHP é comparável com a flexibilidade de código. PHP pode ser usado para montar um servidor de aplicações completo, com todo o poder de um usuário shell, ou pode ser usado para inclusão simples de arquivos no lado do servidor com pouco risco em um ambiente bem controlado. Como montar o ambiente, e o quão seguro ele é, depende muito do desenvolvedor.
Esse capítulo começa com alguns conselhos genéricos de segurança, explica as diferentes combinações de opções de configuração e as situações nas quais elas podem ser usadas com segurança e descreve diferentes considerações quanto ao desenvolvimento para diferentes níveis de segurança.
Considerações Gerais
Um sistema completamente seguro é virtualmente impossível de se conseguir, então uma abordagem freqüentemente usada em segurança é um compromisso entre risco e usabilidade. Se cada variável enviada pelo usuário precias de duas formas de validação biométrica (como escaneamento de retina e impressão digital), você teria um nível de checagem extremamente alto. Demoraria meia hora para preencher um formulário mais ou menos complexo, o que incentivaria os usuários a achar maneiras de burlar a segurana.
A melhor segurança é frequentemente aquele preenche os requerimentos sem obstruir o usuário de fazer o seu trabalho, ou sobrecarregando o programador com complexidade excessiva. De fato, alguns ataques de segurança exploram esse tipo de segurança super-produzida, que tende a degradar com o tempo.
Uma frase que vale a pena lembrar: Um sistema é tão bom quanto o elo mais fraco na corrente. Se todas as transações são maciçamente registradas baseado no tempo, localização, tipo de transação, etc. mas o usuário só é verificado baseado em um único cookie, a validade de ligar os usuários ao registro de transação torna-se muito fraca.
Quando estiver testando, tenha em mente que você não será capaz de testar todas as possibilidades nem mesmo para as páginas mais simples. A entrada que você pode esperar será totalmente diferente da entrada dada por um empregado irritado, um cracker com meses livres para tentar quebrar o sistema, ou um gato andando pelo teclado. Por isso é melhor olhar ao código da perspectiva lógica, para discernir onde dados inesperados podem ser introduzidos, e depois seguir aonde o mesmo é modificado, reduzido ou amplificado.
A Internet está cheia de gente tentando fazer o próprio nome quebrando o código dos outros, derrubando sites, enviando conteúdo indevido e de outras formas fazendo seu dia interessante. Não importa se você tem um site grande ou pequeno, você é um alvo simplesmente por estar online, tendo um servidor que pode ser conectado. Muitos programas de cracking não discernem por tamanho, eles simplesmente vasculham blocos gigantes de IPs procurando por vítimas. Tente não se tornar um.
Instalando como binário CGI
Índice
- Ataque Possível
- Caso 1: apenas arquivos públicos são disponibilizados
- Caso 2: usando --enable-force-cgi-redirect
- Caso 3: configurando doc_root ou user_dir
- Caso 4: Interpretador do PHP fora da árvore de diretórios do servidor web
Ataque Possível
Usando o PHP como binário CGI é uma opção de instalação que por alguma razão não deseja integrar o PHP como um módulo no servidor (como o Apache), ou usará o PHP com tipos diferentes de CGI wrappers para criar ambientes chroot e setuid seguros para os scripts. Esse tipo de instalação normalmente involve copiar o binário executável para o diretório cgi-bin do servidor web. CERT advisory » CA-96.11 recomenda não colocar qualquer interpretador nesse diretório. Mesmo se o binário do PHP pode ser usado como um interpretador autônomo, o PHP foi desenhado para previnir os ataques que essa forma de instalação torna possível:
- Acessar arquivos de sistema: http://my.host/cgi-bin/php?/etc/passwd A informação de consulta em uma URML depois da interrogração (?) é passada como argumentos de linha de comando para o interpretador pea interface CGI. Normalmente os interpretadores abrem e executam o arquivo especificado como primeiro argumento na linha de comando. Quando invocado como binárgio CGI, o PHP se recusa a interpretar os argumentos de linha de comando.
- Acessar qualquer domento web no servidor: http://my.host/cgi-bin/php/secret/doc.html A parte de informação de caminho da URL depois do nome do binário do PHP, /secret/doc.html é convencionalmente usada para especificar o nome do arquivo a ser aberto e interpretado pelo programa CGI Normalmente algumas diretivas de configuração do servidor web (Apache: Action) são usadas para redirecionar requisições para documentos como http://my.host/secret/script.php para o interpretados do PHP. Dessa maneira, o servidor web primeiro checa as permissões de acesso ao diretório /secret, e depois cria a requisição redirecionada http://my.host/cgi-bin/php/secret/script.php. Infelizmente, se a requisição é dada originalmente nessa forma, a checagem de permissão não é feita para o arquivo /secret/script.php, mas apenas para o arquivo /cgi-bin/php. Dessa maneira qualquer usuário que pode acessar /cgi-bin/php pode acessar quaisquer documentos protegidos no servidor web. No PHP, a opção de configuração em tempo de compilação --enable-force-cgi-redirect e as diretivas de configuração de tempo de execução doc_root e user_dir podem ser usadas para previnir esse ataque, se a árvore de documentos do servidor tiver qualquer diretório com restrições de acesso. Veja abaixo para uma explicação completa de combinações diferentes.
Caso 1: apenas arquivos públicos são disponibilizados
Se o seu servidor não tiver qualquer conteúdo que não é restringido por senha ou por IP, não há necessidade para essas opções de configuração. Se seu servidor web não permitir que você faça redirecionamento, ou o servidor não tem uma maneira de comunicar ao binário PHP que a requisição é uma redirecionada de maneira segura, você pode especificar a opção --enable-force-cgi-redirect no script configure. Você ainda tem que assegura que o seus scripts PHP não confiem com uma ou outra maneira de chamar o script, nem diretamente http://my.host/cgi-bin/php/dir/script.php nem por redirecionamento http://my.host/dir/script.php.
Redirecionamento pode ser configurado no Apache usando AddHandler e diretivas Action (veja abaixo).
Caso 2: usando --enable-force-cgi-redirect
Essa opção em tempo de compilação previne que qualquer usuário chame o PHP diretamente com uma URL como http://my.host/cgi-bin/php/secretdir/script.php. Ao invés disso, o PHP só executará nesse mode se passar por uma regra de redirecionamento do servidor.
Normalmente o redirecionamento na configuração do Apache é feita com as seguintes diretivas:
Action php-script /cgi-bin/php AddHandler php-script .php
Essa opção só foi testada com o servidor Apache, e confia no Apache para configura a variável de ambiente não-padrão do CGI REDIRECT_STATUS em requisições redirecionadas. Se seu servidor web não suporta nenhuma maneira de dizer se a requisição é direta ou rediracionada, você não pode usar essa opção e você deve usar uma das outras maneira de executar a versão do CGI documentada aqui.
Caso 3: configurando doc_root ou user_dir
Para incluir conteúdo ativo, como script e executáveis, nos diretórios de documentos do servidor é algumas vezes consideread uma prática insegura. Se, por conta de um erro de configuração, os scripts não são executados mas mostrados como documentos HTML normais, isso pode resultar em vazamento de propriedade intelectual ou informação de segurança, como senhas. Portanto, muitos administradores preferirão configura outra estrutura de diretório para scripts que são acessíveis apenas pelo CGI do PHP, e, portanto, sempre interpretados e não enviado ao navegador.
Além disso, se o método para assegura que as requisições não são redirecionadas, como descrito na seção anterior, não estiver disponível, é necessário configura um doc_root para os script que é diferente do doc_root do servidor web.
Você pode configura a raiz de documentos dos scripts PHP pela diretiva de configuração doc_root no arquivo de configuração, ou você pode criar a variável de ambiente PHP_DOCUMENT_ROOT. Se ela existir, a versão CGI do PHP sempre construirá o nome de arquivo para ser aberto com esse doc_root e a informação de caminho na requisição, para assegurar que nenhum script é executado fora desse diretório (exceto por user_dir abaixo).
Outra opção utilizável é user_dir. Quando user_dir não existir, a única coisa controlando o nome do arquivo aberto é doc_root. Abrir uma URL como http://my.host/~user/doc.php não resulta em abrir um arquivo no diretório home de users, mas um arquivo chamado ~user/doc.php dentro de doc_root (sim, um nome de diretório começando com til [~]).
Se user_dir existir e tiver valor de, por exemplo, public_php, uma requisição como http://my.host/~user/doc.php abrirá o arquivo chamado doc.php no diretório chamado public_php dentro do diretório home do usuário. Se o home do usuário é /home/user, o arquivo executado é /home/user/public_php/doc.php.
A expansão de user_dir acontece independente da configuração de doc_root, para que você possa controlar a raiz de documentos e de acesso de diretório do usuário separadamente.
Caso 4: Interpretador do PHP fora da árvore de diretórios do servidor web
Uma maneira muito segura é colocar o interpretador do PHP em algum lugar longe dos arquivos da árvore de diretórios do servidor. Em /usr/local/bin, por exemplo. A única desvantagem real para essa opção é que você terá que colocar uma linha similar à:
#!/usr/local/bin/php
Para fazer o PHP tratar as informações de PATH_INFO e PATH_TRANSLATED corretamente com essa configuração, o interpretador do PHP deve ser compilado com a opção de configure --enable-discard-path.
Instalado como módulo do Apache
Quando o PHP é usado como módulo do Apache, ele herda as permissões do usuário do Apache (normalmente as do usuário "nobody"). Isso tem vários impactos de segurança e autorização. Por exemplo, se você estiver usando o PHP para acessar um banco de dados, a menos que o banco de dados tenha um controle de acesso interno, você terá que faz o banco de dados acessível ao usuário "nobody". Isso significa que um script malicioso pode acessar e modificar o banco de dados, mesmo sem um usuário e senha. É possível que um web spider pode passar em uma página web de administração do banco de dados e remover todos os bancos de dados. Você pode se proteger contra isso usando autorização do Apache, ou você pode desenvolver seu modelo de acesso prório usando LDAP, arquivos .htaccess, etc. e incluir esse código como parte dos seus scripts PHP.
Normalmente, uma vez que a segurança está estabelecida até esse ponto onde o usuário do PHP (no caso, o usuário apache) tem pouco risco atribuído a ele, você descobre que o PHP não tem permissão de escrita nos diretórios dos usuários. Ou talvez tenha sido proibido de acessar ou alterar bancos de dados. Também foi proibido de escrever arquivos, bons ou ruins, ou fazer transações de bancos de dados, boas ou ruins.
Um erro freqüente de segurança feito até esse ponto é permiter ao apache permissões de administrador (root), ou aumentar as habilidades do apahce de qualquer outra forma.
Aumentar as permissões do usuário do Apache para a de administrador é extremamente perigoso e pode comprometer o sistema inteiro, então sudo'ing, chroot'ing, ou então executar como root não deve ser considerados por aqueles que não são profissionais em segurança.
Existem algumas soluções mais simples. Usando a diretiva open_basedir você pode controlar e restringir quais diretórios o PHP tem permissão de usar. Você também pode configurar area exclusivas para o Apache, restringir todas as atividades web para arquivo que não sejam de algum usuário ou do sistema.
Segurança do Sistema de Arquivos
Índice
O PHP está sujeito à segurança encontrada na maioria dos sistemas de servidor com respeito à permissões de arquivos e diretórios. Isso permite que você controle quais arquivos no sistema podem ser lidos e por quem. É preciso ter cuidado com quaisquer arquivos que são lidos por todos para assegurar que eles podem ser lidos por todos os usuários que tem acesso ao sistema de arquivos.
Já que o PHP foi desenhado para permitir acesso em nível de usuário ao sistema de aruqivos, é possível escrever um script PHP que permitirá ler arquivos do sistema com /etc/passwd, modificar suas conexões de ethernet, enviar trabalhos de impressão gigantes, etc. Isso tem algumas implicações óbvias, já que você precisa ter certeza que os arquivos que você lê e escreve são apropriados.
Considere o seguinte script, onde um usuário indica que ele quer apagar um arquivo no seu diretório home. Isso presume uma situação onde uma interface web PHP é usada regularmente para controle de arquivos, então o usuário do Apache tem permissão de apagar arquivos nos diretórios home dos usuários.
Exemplo #1 Checagem fraca de variáveis resulta em....
<?php
// remove a file from the user's home directory
$username = $_POST['user_submitted_name'];
$userfile = $_POST['user_submitted_filename'];
$homedir = "/home/$username";
unlink("$homedir/$userfile");
echo "The file has been deleted!";
?>
Exemplo #2 ... um ataque ao sistema de arquivos
<?php
// remove um arquivo de qualquer lugar no disco rígido
// que o usuário do PHP tenha acesso. Se o PHP tiver acesso de administrador (root):
$username = $_POST['user_submitted_name']; // "../etc"
$userfile = $_POST['user_submitted_filename']; // "passwd"
$homedir = "/home/$username"; // "/home/../etc"
unlink("$homedir/$userfile"); // "/home/../etc/passwd"
echo "The file has been deleted!";
?>
- Só dar permissões limitadas ao usuário executando o binário do PHP.
- Checar todas as variáveis que são enviadas.
Exemplo #3 Checagem mais segura do nome do arquivo
<?php
// remove um arquivo do disco rígido que o
// usuário do PHP tenha acesso.
$username = $_SERVER['REMOTE_USER']; // usando um mecanismo de autenticação
$userfile = basename($_POST['user_submitted_filename']);
$homedir = "/home/$username";
$filepath = "$homedir/$userfile";
if (file_exists($filepath) && unlink($filepath)) {
$logstring = "Deleted $filepath\n";
} else {
$logstring = "Failed to delete $filepath\n";
}
$fp = fopen("/home/logging/filedelete.log", "a");
fwrite($fp, $logstring);
fclose($fp);
echo htmlentities($logstring, ENT_QUOTES);
?>
Exemplo #4 Checagem mais segura do nome do arquivo
<?php
$username = $_SERVER['REMOTE_USER']; // usando um mecanismo de autenticação
$userfile = $_POST['user_submitted_filename'];
$homedir = "/home/$username";
$filepath = "$homedir/$userfile";
if (!ctype_alnum($username) || !preg_match('/^(?:[a-z0-9_-]|\.(?!\.))+$/iD', $userfile)) {
die("Bad username/filename");
}
//etc...
?>
Dependendo do seu sistema operacional, existe uma variedade enorme de arquivos que você tem que se preocupar, incluindo dispositivos (/dev/ or COM1), arquivos de configuração (arquivos /etc/ e .ini), áres de armazenamento conhecidas (/home/, My Documents), etc. Por essa razão, normalmente é mais fácil criar uma política onde você proibe tudo exceto aquilo que for explicitamente permitido.
Problemas relacionados a bytes nulos (Null)
Como o PHP usa funções em C para operações relacionadas ao sistema de arquivos, ele pode lidar com bytes nulos de maneira inexperada. Como bytes nules denotam fim de string em C, strings contendo eles não serão consideradas por inteiro, mas apenas até que um byte nulo ocorra. O seguinte exemplo mostra um código vulnerável que demonstra esse problema:
Exemplo #1 Script vulnerável à bytes nulos
<?php
$file = $_GET['file']; // "../../etc/passwd\0"
if (file_exists('/home/wwwrun/'.$file.'.php')) {
// file_exists will return true as the file /home/wwwrun/../../etc/passwd exists
include '/home/wwwrun/'.$file.'.php';
// the file /etc/passwd will be included
}
?>
Portanto, qualquer string comprometida que é usada em uma operação de sistema de arquivos deve sempre ser validada corretamente. Aqui está uma versão melhorada do exemplo anterior:
Exemplo #2 Validando entrada corretamente
<?php
$file = $_GET['file'];
// Whitelisting possible values
switch ($file) {
case 'main':
case 'foo':
case 'bar':
include '/home/wwwrun/include/'.$file.'.php';
break;
default:
include '/home/wwwrun/include/main.php';
}
?>
Segurança de Bancos de Dados
Índice
- Desenhando Bancos de Dados
- Conectando com o Banco de Dados
- Modelo de Armazenamento Criptografado
- Injeção de SQL
Hoje em dia, bancos de dados são componentes cardinais de qualquer aplicação web permitindo que websites forneçam conteúdo dinâmico variável. uma ves que informação muito sensível e/ou secreta pode ser guardada em um banco de dados, proteger seus bancos de dados é essencial.
Para retirar ou guardar qualquer informação, você precisa conectar-se ao banco de dados, enviar uma consulta (query) legítima, puxar o resultado e fechar a conexão. Atualmente, a linguagem mais usada para consulta nessa interação é a Structured Query Language (SQL). Veja como um atacante pode manipular uma consulta SQL.
Como você pode perceber, o PHP não pode proteger seu banco de dados sozinho. As seções a seguir tentam ser uma introdução básica em relação a como acessa e manipular banco de dados a partir de scripts PHP.
Mantenha em mente essa regra simples: defesa em profundidade. Quanto mais lugares você faz ações para aumentar a proteção do seu banco, menor a probabilidade de um atacante ter suceso em expor ou abusar de qualquer informação guardada. Bom desenho do esquema (schema) de banco de dados e da aplicação lida com seus maiores medos.
Desenhando Bancos de Dados
O primeiro passo é sempre criar o banco de dados, a não ser que você queira usar um de terceiros. Quando um banco de dados é criado, ele é atribuído a um dono, que executou os comandos de criação. Normalmente, só o dono (ou um superusuário) pode faz algo com os objetos naquele banco de dados, e para permitir que outros usuários usem, privilégios devem ser concedidos.
Aplicações nunca devem conecta ao banco de dados como seu dono ou um superusuário, porque esses usuários podem executar qualquer consulta que quiserem, por exemplo, modificar o esquema (ex.: destruindo tabelas) ou removendo seu conteúdo completamente.
Você pode criar usuários de bancos de dados diferentes para cada aspecto da sua aplicação com direitos muito limitados aos objetos do banco de dados. Apenas os privilégios mais necessários devem ser concedidos, e evitar que o mesmo usuário possa interagir com o banco de dados em casos de uso diferentes. Isso significa que se invasores conseguirem acessar seu bando usando credenciais da sua aplicação, eles só podem afetar o banco tanto quanto sua aplicação.
Encorajamos não implementar toda a lógica de negócio na aplicação web (ex.: seu script). Ao invés disso, faça parte no esquema do banco, usando view, triggers ou rules. Se o sistema evoluir, crescerá a vontade de criar novas maneiras de usar o banco, e você terá que reimplementar a lógica em cada cliente separado do banco. Além disso, triggers podem ser usados para lidar com certos campos de maneira automática e transparente, o que permite dar informações quando depurar problemas com sua aplicação ou rastreando transações.
Conectando com o Banco de Dados
Você pode querer estabelecer as conexões sobre SSL para criptografar comunicações cliente/servidor para aumentar a segurança, ou você pode usar ssh para criptografar a conexão de rede entre clientes e o servidor de banco de dados. Se uma dessa opções for usada, monitoramento do seu tráfego e obtenção de informação sobre seu banco de dados serão dificultados por um atacante.
Modelo de Armazenamento Criptografado
SSL/SSH protege dados transitando de um cliente para o servidor, mas não protege os dados guardados em um banco de dados. SSL é um protocolo on-the-wire.
Uma vez que o atacante ganha acesso direto ao seu banco de dados(desviando do servidor web), os dados armazenados podem ser expostos ou sofre uso nocivo, a não ser que a informação seja protegida pelo banco em si. Criptografa os dados é uma boa maneira de diminuir essa ameaça, mas poucos bancos de dados oferecem esse tipo de criptografia de dados.
A maneira mais fácil de contornar esse problema é primeiro criar seu próprio pacote de criptografia, e então usá-lo no seus scripts PHP. O PHP pode ajudá-lo com várias extensões, tais como Mcrypt e Mhash, cobrindo uma grande variedade de algoritmos de criptografia. O script criptografa os dados antes de inserí-los no banco de dados e descriptografa quando os recupera. Veja as referência para outros exemplos de como criptografia funciona.
No caso de dados realmente escondidos, se sua representação crua não é necessária (ex.: não será mostrada), usar uma função de hash pode ser levada em consideração. Um exemplo bem conhecido disso é guardar o hash MD5 de uma senha no banco de dados ao invés da senha em si. Veja também crypt() e md5().
Exemplo #1 Usando campo de senha hasheado
<?php
// guardando hash da senha
$query = sprintf("INSERT INTO users(name,pwd) VALUES('%s','%s');",
pg_escape_string($username), md5($password));
$result = pg_query($connection, $query);
// consultando se o usuário enviou a senha correta
$query = sprintf("SELECT 1 FROM users WHERE name='%s' AND pwd='%s';",
pg_escape_string($username), md5($password));
$result = pg_query($connection, $query);
if (pg_num_rows($result) > 0) {
echo 'Welcome, $username!';
} else {
echo 'Authentication failed for $username.';
}
?>
Injeção de SQL
Muitos desenvolvedores web não sabem de como consultas SQL podem ser manipuladas e presumem que uma consulta de SQL é um comando confiável. Significa que consultas SQL são capazes de passar indetectado por controles de acesso, portanto desviando da autenticação padrão e de checagens de autorização, e algumas vezes consultas SQL podem permitir acesso à comando em nível do sistema operacional do servidor.
Injeção direta de comandos SQL é uma técnica onde um atacante cria ou altera comandos SQL existentes para expor dados escondidos, ou sobrescrever dados valiosos, ou ainda executar comandos de sistema perigosos no servidor. Isso é possível se a aplicação pegar a entrada do usuário e combinar com parâmetros estáticos para montar uma consulta SQL. Os exemplos a seguir são baseados em histórias verdadeiras, infelizmente.
Devido à falta de validação de entrada e conectando ao banco de dados usando o super-usuário ou um usuário que pode criar usuário, o atacante pode criar um super-usuário no seu banco de dados.
Exemplo #1 Dividinto o result set em páginas ... e criando super-usuários (PostgreSQL)
<?php
$offset = $argv[0]; // Cuidado, sem validação de entrada!
$query = "SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET $offset;";
$result = pg_query($conn, $query);
?>
0;
insert into pg_shadow(usename,usesysid,usesuper,usecatupd,passwd)
select 'crack', usesysid, 't','t','crack'
from pg_shadow where usename='postgres';
--
Nota:
É uma técnica comum forçar o avaliador de SQL ignorar o resto da consulta escrita pelo desenvolvedor com --, que é o sinal de comentário no SQL.
Uma maneira de ganhar senha é desviar suas páginas de resultado de busca. A única coisa que o atacante precisa fazer é ver se alguma variável enviada é usada em um comando SQL que não é tratado corretamente. Esses filtros podem ser configurados de forma a personalizar cláusulas WHERE, ORDER BY, LIMIT e OFFSET em comandos SELECT Se seu banco de dados suporta o construtor UNION, o atacante pode tentar adicionar uma consulta inteira à consulta original para listar senhas de uma tabela arbitrária. Uso de campos de senha criptografados é fortemente incentivado.
Exemplo #2 Listando artigos ... e algumas senhas (qualquer banco de dados)
<?php
$query = "SELECT id, name, inserted, size FROM products
WHERE size = '$size'
ORDER BY $order LIMIT $limit, $offset;";
$result = odbc_exec($conn, $query);
?>
' union select '1', concat(uname||'-'||passwd) as name, '1971-01-01', '0' from usertable; --
Comandos de UPDATE também são suscetíveis a ataques. Essas consultas também são ameaçadas por cortes e acréscimos de uma nova consulta. Mas o atacante pode brincar com a cláusula SET. Nesse caso ele precisa estar de posse de alguma informação sobre o esquema para manipular a consulta com sucesso. Isso pode ser conseguido examinando os nomes das variáveis do formulário, ou simplesmente por força bruta. Não existem muitas convenções para campos guardando senhas ou nomes de usuários.
Exemplo #3 De reinicializando uma senha ... para ganhando mais privilégios (qualquer banco de dados)
<?php
$query = "UPDATE usertable SET pwd='$pwd' WHERE uid='$uid';";
?>
<?php
// $uid == ' or uid like'%admin%'; --
$query = "UPDATE usertable SET pwd='...' WHERE uid='' or uid like '%admin%'; --";
// $pwd == "hehehe', admin='yes', trusted=100 "
$query = "UPDATE usertable SET pwd='hehehe', admin='yes', trusted=100 WHERE
...;";
?>
Um exemplo assustador de como comandos do sistema operacional podem ser acessados em alguns bancos de dados.
Exemplo #4 Atacando o sistema operacional do servidor (MSSQL Server)
<?php
$query = "SELECT * FROM products WHERE id LIKE '%$prod%'";
$result = mssql_query($query);
?>
<?php
$query = "SELECT * FROM products
WHERE id LIKE '%a%'
exec master..xp_cmdshell 'net user test testpass /ADD'--";
$result = mssql_query($query);
?>
Nota:
Alguns dos exemplos acima estão ligados a bancos específicos. Isso não significa que um ataque similar é impossível contra outros produtos. Seu servidor de banco de dados pode ter uma vulnerabilidade similar de outa maneira.
Técnicas para Evitar Ataques
Você pode dizer que o atacante precisa possuir um pouco de informação sobre o esquema de banco de dados na maioria dos exemplos. Você tem razão, mas você nunca sabe quando e como isso pode ser obtido e, se acontecer, seu banco de dados pode ficar exposto. Se você estiver usando um pacote open source publicamente disponível para lidar com banco de deados, que pode pertencer a um sistema de controle de conteúdo ou forum, os invasores facilmente produzem uma cópia de parte de seu código. Também pode ser um risco de segurança se este for for mal desenhado.
Esses ataques se baseam principalmente em explorar falhas no código escrito sem se preocupar com segurança. Nunca confie em nenhum tipo de entrada, especialmente aquela que vem do lado do cliente, mesmo que venha de um combobox, um campo de entrada escondido (hidden) ou um cookie. O primeiro exemplo mostra como uma consulta inocente pode causar desastres.
- Nunca conecte ao banco de dados como um super-usuário ou como o dono do banco de dados. Use sempre usuários personalidados com privilégios bem limitados.
- Verifique se uma entrada qualquer tem o tipo de dados experado. O PHP tem um grande número de funções de validação de entrada, desde as mais simples encontrada em Funções de Variáveis e em Funções de Tipo de Caracteres (ex.: is_numeric(), ctype_digit() respectivamente) além de usar o suporte a Expressões Regulares Compatível com Perl.
-
Se a aplicação espera por entradas numéricas, considere verificar os dados com a função is_numeric(), ou silenciosamente mudar o seu tipo usando settype(), ou usar a representação númerica usando a função sprintf().
Exemplo #5 Uma maneira mais segura para compor consultas de paginação
<?php
settype($offset, 'integer');
$query = "SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET $offset;";
// por favor perceba o %d na string de formato, usando %s seria inútil
$query = sprintf("SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET %d;",
$offset);
?> - Adicione aspas para cada valor não numérico especificado pelo usuário que será passado para o banco de dados com as funções de caracteres de escape (ex.: mysql_real_escape_string(), sqlite_escape_string(), etc.). Se um mecanismo de escape de caracter específico para o seu banco de dados não for disponível, as funções addslashes() e str_replace() podem ser úteis (dependendo do tipo de banco de dados). Veja o o primeiro exemplo. Como o exemplo mostra, adicionar aspas à parte estática da consulta não é suficiente, fazendo com que a consulta seja facilmente atacada.
- Não imprima qualquer informação específica do banco de dados, especialmente sobre o esquema, custe o que custar. Veja também Relatório de Erros e Funções de Tratamento e Relatório de Erros.
- Você pode usar stored procedures e cursores previamente definidas para abstrair acesso aos dados para que os usuários não acessem tabelas ou views diretamente, mas essa solução pode ter outros impactos.
Além disso, você ganha em relatar consultas ou dentro do script ou no próprio banco de dados, se esse suportar. Obviamente, o relatório é para previnir qualquer tentativa danosa, mas pode ser útil para ajudar a rastrear qual aplicação foi atacada. O relatório não é útil em si, mas atráves da informação que ele contém. Mais detalhes geralmente é melhor que menos.
Relatando Erros
Com relação a segurança, relatório de erros é uma faca de dois gumes. Pode beneficiar o aumento da segurança, ou fornecer informaçao ao atacante.
Uma tática padrão de ataque involve determinar como um sistema funciona entrando dados incorretos e checando os tipos e contextos dos erros que são retornados. Isso permite que um cracker sonde por informações sobre o servidor, para determinar possíveis fraquezas. Por exemplo, se um atacantes tinha recolhido informação sobre uma página baseado em uma submissão de dados anterior, ele pode tentar sobrescrever variáveis, ou modificá-las:
Exemplo #1 Atacando variáveis com uma página HTML personalizada
<form method="post" action="attacktarget?username=badfoo&password=badfoo"> <input type="hidden" name="username" value="badfoo" /> <input type="hidden" name="password" value="badfoo" /> </form>
Os erros do PHP que são retornados normalmente podem ser úteis para um desenvolvedor que está tentando depurar um script, indicando coisas como a função ou arquivo que falhou, o arquivo PHP no qual a falha ocorreu, e o número da linha de código causadora da falha. Toda essa informação pode ser explorada. Não é incomum para um desenvolvedor PHP usar show_source(), highlight_string(), ou highlight_file() como medidas de depuração, mas em um site de produção, isso pode expor variáveis ocultas, sintaxe incorreta, ou outra informações perigosas. Especialmente perigoso é rodar código de fontes conhecidas com tratadores de depuração integrados, ou usar técnicas de depuração comuns. Se o atacante pode determinar qual técnica gerá você estiver usando, eles podem tentar, por força-bruta, enviar várias strings de depuração comuns para a página:
Exemplo #2 Explorando variáveis comuns de depuração
<form method="post" action="attacktarget?errors=Y&showerrors=1&debug=1"> <input type="hidden" name="errors" value="Y" /> <input type="hidden" name="showerrors" value="1" /> <input type="hidden" name="debug" value="1" /> </form>
Independente do método de tratamento de erros, a habilidade de sondar um sistema por erros acaba dando informações úteis a um atacante.
Por exemplo, o próprio estilo de um erro genérico do PHP indica que o sistema está rodando o PHP. Se o atacante estava procurando por uma página .html, e queria sondar qual o back-end (para procurar fraquezas conhecidas no sistema) enviando dados incorretos, ele pode ser capaz de determinar que um sistema foi feito com PHP.
Uma função de erro pode indicar se o sistema pode está executando um engine de banco de dados específico, ou dar dicas de como uma página foi programada ou desenhada. Isso permite uma investigação profunda sobre portas abertas de bancos de dados, ou procurar por bugs específicos ou fraquezas de uma página. Enviando diferentes pedaços de dados ruins, por exemplo, um atacante pode determinar a ordem de autenticação em um script, (a partir da linha do erro) assim como sondar por exploits que podem ser aproveitados em diferentes partes do script.
Um erro geral do PHP ou do sistema de arquivos indicam quais permissões o servidor web tem, assim como a estrutura e organização dos arquivos no servidor web. Códigos de erros escritos pelo desenvolvedor podem agravar o problema, levando pela exploração fácil de informação até então "escondida".
Existem três soluções principais para esse problema. A primeira é verificar exaustivamente todas as funções, e tentar compensar pelo volume dos erros. A segunda é desabilitar completamente os relatórios de erros no código de produção. A terceira é usar as funções personalizávies de tratamento de erro do PHP para criar seu próprio tratador de erro. Dependendo da sua política de segurança, você pode perceber que todas são aplicáveis à sua situação.
Uma maneira de perceber esse problema antes que o pior aconteça é usar a diretiva error_reporting(), para ajudar a aumentar a segurança de seu código e achar uso de variáveis que pode ser perigoso. Ao testar o seu código, antes de colocar em produção, com E_ALL, você pode rapidamente encontrar áreas onde suas variáveis podem sofrer alterações nocivas ou modificações quaisquer. Uma vez que estiver pronto para produção, você deve ou desabilitar mensagens de erro completamente configurando a diretiva error_reporting() com o valor 0, ou desligar o envio de erros usando a opção display_errors do arquivo php.ini, para evitar sondagem do seu código. Se você escolher a segunda opção, você deve também definir o caminho para o arquivo de registro usando a diretiva error_log, e ligar a diretiva log_errors.
Exemplo #3 Encontrado variáveis perigosas com E_ALL
<?php
if ($username) { // Not initialized or checked before usage
$good_login = 1;
}
if ($good_login == 1) { // If above test fails, not initialized or checked before usage
readfile ("/highly/sensitive/data/index.html");
}
?>
Usando a diretiva Register Globals
Este recurso tornou-se OBSOLETO a partir do PHP 5.3.0 REMOVIDO do PHP 6.0.0. Confiar neste recurso é extremamente não recomendado.
Talvez a mudança mais controversa no PHP foi quando o valor padrão da diretiva do PHP register_globals passou de ON (Ligado) para OFF (Desligado) na versão » 4.2.0. Era muito comum as pessoas dependerem da diretiva e muitas delas nem sabiam que ela existia e presumiam que era a maneira como o PHP funcionava. Essa página explica como alguém pode escrever código inseguro com essa diretiva, mas tenha em mente que a diretiva em si não é insegura, o uso incorreto dela é que é.
Quando ligada, a diretiva register_globals criará para seus scripts vários tipos de variáveis, como as variáveis oriundas de formulários HTML. Isso, combinado com o fato de que o PHP não requer inicialização de variáveis, significa que é mais fácil escrever código inseguro. Foi uma decisão difícil, mas a comunidade do PHP decidiu que, por padrão, essa diretiva deveria ser desabilitada. Quando habilitada, é possível usar variáveis sem saber ao certo de onde elas vieram. Variáveis internas que são definidas no script em si se misturam com dados enviados pelos usuários e desabilitando a diretiva muda isso. Vamos demonstrar um exemplo de uso incorreto de register_globals:
Exemplo #1 Exemplo de uso incorreto de register_globals = on
<?php
// define $authorized = true somente se o usuário for autenticado
if (authenticated_user()) {
$authorized = true;
}
// Porque nós não inicializamos $authorized como false, ela pode ser
// definida através de register_globals, como usando GET auth.php?authorized=1
// Dessa maneira, qualquer um pode ser visto como autenticado!
if ($authorized) {
include "/highly/sensitive/data.php";
}
?>
Quando register_globals estiver habilitada, sua lógica pode ser comprometida. Quando desligada $authorized não pode ser configurada via GET, então estará correto, embora geralmente seja uma boa prática de programação inicializar as variáveis primeiro. Por exemplo, no nosso exemplo acima nós podemos executar primeiro $authorized = false. Dessa forma o código funcionaria com register_globals ligada ou desligada, já que os usuário não seriam autorizados a não ser que a autenticação tenha sucesso.
Outro exemplo é o quando usando sessions. Quando a diretiva está ligada, nós também podemos usar $username no exemplo mas novamente é preciso perceber que $username também pode vir de outro lugar, como via GET (através da URL).
Exemplo #2 Exemplo de uso de sessões com register_globals ligada ou desligada
<?php
// Nós não saberiamos de onde $username veio mas sabemos que $_SESSION
// guarda dados da sessão.
if (isset($_SESSION['username'])) {
echo "Hello <b>{$_SESSION['username']}</b>";
} else {
echo "Hello <b>Guest</b><br />";
echo "Would you like to login?";
}
?>
Além disso tudo, é possível tomar medidas preventivas para avisar quando alguém está tentando criação de variáveis falsas. Se você sabe de antemão de onde uma variável deve vir, você pode verificar se os dados enviados estão chegando de maneira incorreta. Embora isso não seja garantia de que os dados não são forjados, torna necessário ao atacante adivinhar o tipo certo de falsificação. Se você não se importar de onde os dados vierão, você pode usar o array $_REQUEST, que contêm a mistura dos dados de GET, POST e COOKIE. Veja também a seção do manual sobre como usar variáveis de fora do PHP.
Exemplo #3 Detecção simples de falsificação de variáveis
<?php
if (isset($_COOKIE['MAGIC_COOKIE'])) {
// MAGIC_COOKIE vem de um cookie.
// Valide os dados do cookie!
} elseif (isset($_GET['MAGIC_COOKIE']) || isset($_POST['MAGIC_COOKIE'])) {
mail("admin@example.com", "Possível tentativa de ataque", $_SERVER['REMOTE_ADDR']);
echo "Violação de Segurança, o Administrador foi alertado.";
exit;
} else {
// MAGIC_COOKIE não foi criada por essa REQUEST
}
?>
É óbvio que só desligar register_globals não significa que seu código está seguro. Cada dado que é enviado deve ser validado de outras maneiras. Sempre valide os dados enviados pelos usuário e inicialize suas variáveis! Para checar por variáveis não inicializadas, você pode configurar error_reporting() para mostrar erros do nível E_NOTICE.
Para mais informações sobre emulação de register_globals como ligada ou desligada, veja esse FAQ.
Nota: Disponibilidade das superglobais:
Arrays superglobais como $_GET, $_POST, e $_SERVER, etc. estão disponíveis desde o PHP 4.1.0. Para mais informação, leia a seção do manual em superglobals
Dados Enviados pelo Usuário
A maior fraqueza na maioria dos programas PHP não é inerente a linguagem em si, mas meramente um problema de código escrito desconsiderando a segurança. Por essa razão, você sempre deve investir um pouco de tempo considerando as implicações de um certo pedaço de código, para ter certeza que o dano possível se uma variável não esperada for submetida ao mesmo.
Exemplo #1 Uso Perigoso de Variáveis
<?php
// remove um arquivo do diretório home do usuário... ou talvez
// de outra pessoa?
unlink ($evil_var);
// Escreve registro do acesso... ou talvez uma entrada em /etc/passwd?
fwrite ($fp, $evil_var);
// Executa algo trivial... ou rm -rf *?
system ($evil_var);
exec ($evil_var);
?>
Você sempre deve examinar cuidadosamente seu código para se assegurar que quaisquer variáveis sendo enviadas do navegador web estão sendo checadas de maneira correta, e faz a si mesmo as seguintes perguntas:
- Seu script só afetará os arquivos desejados?
- Dados incomuns ou indesejados podem ser utilizados?
- Esse script pode ser usado de maneiras não intencionadas?
- Ele pode ser usado in conjunto com outros scripts de maneira negativa?
- As transações serão registradas adequadamente?
Respondendo essas perguntas adequadamente enquanto escrevendo o script, ao invés de depois, previne a reescrita indesejada quando você precisar aumentar a segurança. Começando com essa linha de raciocínio, você não garante a segurança do seu sistema, mas pode ajudar a aumentá-la.
Você também pode considerar desligar as diretivas register_globals, magic_quotes, ou outras configurações convenientes que pode confundir você em relação a validade, origem, ou valor de uma variável qualquer. Trabalhar com PHP em modo error_reporting(E_ALL) também pode ajudar avisando sobre variáveis sendo usadas antes de serem checadas ou inicializadas (então você pode previnir que dados incomuns sejam operados).
Magic Quotes
Índice
- O que são Magic Quotes
- Porque nós usamos Magic Quotes
- Por que não usar Magic Quotes?
- Desabilitando Magic Quotes
Este recurso tornou-se OBSOLETO a partir do PHP 5.3.0 REMOVIDO do PHP 6.0.0. Confiar neste recurso é extremamente não recomendado.
Magic Quotes é um processo de inserção automática de caracteres de escape (\) em todos os dados indo para o script PHP. É preferível escrever código com essa opção desligada e adicionar esses caracteres manualmente quando necessário.
O que são Magic Quotes
Este recurso tornou-se OBSOLETO a partir do PHP 5.3.0 REMOVIDO do PHP 6.0.0. Confiar neste recurso é extremamente não recomendado.
Quando ligada, qualquer ' (aspas simples), " (aspas duplas), \ (barra invertida) e NULL será colocado uma barra-invertida antes (' vira \') automaticamente. Isso é identico ao que a função addslashes() faz.
Existem três diretivas relacionadas a Magic Quotes:
- magic_quotes_gpc Afeta os dados de requisições HTTP GET, POST, e COOKIE). Não pode ser alterada em tempo de execução e tem o valor padrão on no PHP. Veja também get_magic_quotes_gpc().
- magic_quotes_runtime Se habilitada, a maioria das funções que retorna dados de uma fonte externa, incluindo bancos de dados e arquivos de texto, serão alterados. Pode ser alterado em tempo de execução e tem o valor padrão de off no PHP. Veja também set_magic_quotes_runtime() e get_magic_quotes_runtime().
- magic_quotes_sybase Se habilitada, uma aspa simples é usada como caracter de escape quando encontrar outra aspa simples (' vira ''). Se ligada, sobrepõe completamente magic_quotes_gpc. Ligar ambas as diretivas significa que apenas aspas simples são substituídas por ''. Aspas duplas, barras invertidas e NULLs permanecerão intocados e não serão escapados. Veja também ini_get() para pegar esse valor.
Porque nós usamos Magic Quotes
Este recurso tornou-se OBSOLETO a partir do PHP 5.3.0 REMOVIDO do PHP 6.0.0. Confiar neste recurso é extremamente não recomendado.
- Não existe mais razão para usar magic quotes porque não é mais uma parte suportada do PHP. Entretanto, a função existe e ajuda alguns iniciantes a contruir um código melhor(mais seguro). Mas, ao lidar com código que utiliza este recurso é melhor atualizar o código do que ativar magic quotes. Assim, porque isso existe? Simples, para ajuda a previnir injeção de SQL. Os desenvolvedores de hoje estão mais a par de segurança e acabam usando mecanismos especificos do banco de dados para escapar e/ou comandos preparados ao invés de depender de coisas como magical quotes.
Por que não usar Magic Quotes?
Este recurso tornou-se OBSOLETO a partir do PHP 5.3.0 REMOVIDO do PHP 6.0.0. Confiar neste recurso é extremamente não recomendado.
- Portabilidade Presumir que ela está ligada, ou desligada, afeta portabilitade. Use get_magic_quotes_gpc() para verificar isso e codifique de acordo com a situação.
- Performance Como nem todos os dados escapados são inseridos em um banco de dados, existe uma perda de performance por escapar todos os dados. Chamar funções de escape (como addslashes()) em tempo de execução é mais eficiente. Embora o arquivo php.ini-dist habilita essas diretivas por padrão, php.ini-recommended desabilita ela. Essa recomendação é principalmente por razões de performance.
- Inconviniência Porque nem todos os dados precisam ter caracteres de escape inseridos, é irritante ver caracteres de escape onde não deviam. Por exemplo, mandar um e-mail por um formulário, e ver um monte de \' na mensagem. Para consertar isso, pode ser necessário o uso excessivo da função stripslashes().
Desabilitando Magic Quotes
A diretiva magic_quotes_gpc só pode ser desabilita em nível de sistema, e não em tempo de execução. Em outras palavras, uso da função ini_set() não é uma opção.
Exemplo #1 Desabilitando magic quotes no lado do servidor
Um exemplo que configuração dessa diretiva para Off (Desligada) no arquivo php.ini. Para detalhes adicionais, leia a seção do manual entitulada Como mudar os valores das configurações.
; Magic quotes ; ; Magic quotes para dados vindos via GET/POST/Cookie. magic_quotes_gpc = Off ; Magic quotes para dados gerados em tempo de execução,ex.: dados vindo de SQL, de chamadas à exec(), etc. magic_quotes_runtime = Off ; Usar magic quotes no estilo Sybase (escapar ' com '' ao invés de \'). magic_quotes_sybase = Off
Se acesso à configuração do servidor não estiver disponível, uso do arquivo .htaccess também é uma opção. Por exemplo:
php_flag magic_quotes_gpc Off
No interesse de escrever código portável (código que funciona em qualquer ambiente), como onde configurar a opção em nível de servidor não for possível, aqui está um exemplo de como desabilitar magic_quotes_gpc em tempo de execução. Esse método é ineficiente então é preferível configurar as diretivas apropriadas em outros lugares.
Exemplo #2 Desabilitando magic quotes em tempo de execução
<?php
if (get_magic_quotes_gpc()) {
$process = array(&$_GET, &$_POST, &$_COOKIE, &$_REQUEST);
while (list($key, $val) = each($process)) {
foreach ($val as $k => $v) {
unset($process[$key][$k]);
if (is_array($v)) {
$process[$key][stripslashes($k)] = $v;
$process[] = &$process[$key][stripslashes($k)];
} else {
$process[$key][stripslashes($k)] = stripslashes($v);
}
}
}
unset($process);
}
?>
Escondendo o PHP
Em geral, segurança por obscuridade é uma das maneiras mais fracas de segurança. Mas em alguns casos, cada pequena medida de segurança extra é desejável.
Algumas técnicas simples podem ajudar a esconder o PHP, possivelmente retardando um atacante que está tentando descobrir fraquezas no seu sistema. Ao configura a diretiva expose_php = off no seu arquivo php.ini, reduz a quantidade de informação disponível à eles.
Outra tática é configura o servidor web, como o Apache, para executar tipos de arquivos diferentes pelo PHP, ou por uma diretiva de arquivo .htaccess, ou no próprio arquivo de configuração do Apache. Você pode então usar extensões de arquivos falsas:
Exemplo #1 Escondendo o PHP como outra linguagem
# Fazer código PHP parecer com outros tipos de códigos AddType application/x-httpd-php .asp .py .pl
Exemplo #2 Usando extensões desconhecidas para o PHP
# Fazer código PHP parecer com tipos desconhecidos AddType application/x-httpd-php .bop .foo .133t
Exemplo #3 Usando extensão HTML para o PHP
# Fazer código PHP parecer com HTML AddType application/x-httpd-php .htm .html
Mantendo-se Atualizado
PHP, como qualquer outro sistema grande, está sobre constante revisão e melhoramento. Cada versão nova normalmente incluirá mudanças, sejam grandes ou pequenas, para melhorar a segurança e reparar falhas, erros de configuração, e outros problemas que podem afetar a segurança geral e estabilitade do seu sistema.
Como outras linguagens de script e programas de nível de sistema, a melhor política é atualizar frequentemente e manter-se atento as novas versões e suas mudanças.
Características
Autenticação HTTP com PHP
Autenticação via HTTP no PHP só é disponível quando o mesmo for executado como módulo do Apache e, portanto, não é disponível na versão CGI. Em um script PHP no módulo Apache, é possível usar a função header() para enviar uma janela de entrada "Authentication Required" que causará que o browser cliente abra um diálogo de entrada de usuário/senha. Uma vez que o usuário preencheu seu nome de usuário e senha, a URL contendo o script PHP será chamada de novo com as variáveis pré-definidas PHP_AUTH_USER, PHP_AUTH_PW, e AUTH_TYPE contendo o nome de usuário, senha e tipo de autenticação, respectivamente. Essas variáveis pré-definidas são achadas nos arrays $_SERVER e $HTTP_SERVER_VARS. Somente autenticação "Basic" (Básica) é suportada. Veja a função header() para mais informações.
Nota: Nota de Versão do PHP
Superglobais, como o $_SERVER, tornaram-se disponíveis no PHP » 4.1.0.
Um script de exemplo que forçaria autenticação do cliente em uma página:
Exemplo #1 Exemplo de Autenticação HTTP
<?php
if (!isset($_SERVER['PHP_AUTH_USER'])) {
header('WWW-Authenticate: Basic realm="My Realm"');
header('HTTP/1.0 401 Unauthorized');
echo 'Texto a ser enviado caso o usuário aperte o botão Cancelar';
exit;
} else {
echo "<p>Olá, {$_SERVER['PHP_AUTH_USER']}.</p>";
echo "<p>Você digitou {$_SERVER['PHP_AUTH_PW']} como sua senha.</p>";
}
?>
Exemplo #2 Exemplo de Autenticação HTTP do tipo Digest
Esse exemplo mostra como implementar um script simples Autenticação HTTP do tipo Digest. Para mais informação leia o » RFC 2617.
<?php
$realm = 'Restricted area';
//user => password
$users = array('admin' => 'mypass', 'guest' => 'guest');
if (empty($_SERVER['PHP_AUTH_DIGEST'])) {
header('HTTP/1.1 401 Unauthorized');
header('WWW-Authenticate: Digest realm="'.$realm.
'",qop="auth",nonce="'.uniqid().'",opaque="'.md5($realm).'"');
die('Text to send if user hits Cancel button');
}
// analyze the PHP_AUTH_DIGEST variable
if (!($data = http_digest_parse($_SERVER['PHP_AUTH_DIGEST'])) ||
!isset($users[$data['username']]))
die('Wrong Credentials!');
// generate the valid response
$A1 = md5($data['username'] . ':' . $realm . ':' . $users[$data['username']]);
$A2 = md5($_SERVER['REQUEST_METHOD'].':'.$data['uri']);
$valid_response = md5($A1.':'.$data['nonce'].':'.$data['nc'].':'.$data['cnonce'].':'.$data['qop'].':'.$A2);
if ($data['response'] != $valid_response)
die('Wrong Credentials!');
// ok, valid username & password
echo 'Your are logged in as: ' . $data['username'];
// function to parse the http auth header
function http_digest_parse($txt)
{
// protect against missing data
$needed_parts = array('nonce'=>1, 'nc'=>1, 'cnonce'=>1, 'qop'=>1, 'username'=>1, 'uri'=>1, 'response'=>1);
$data = array();
preg_match_all('@(\w+)=(?:([\'"])([^\2]+)\2|([^\s,]+))@', $txt, $matches, PREG_SET_ORDER);
foreach ($matches as $m) {
$data[$m[1]] = $m[3] ? $m[3] : $m[4];
unset($needed_parts[$m[1]]);
}
return $needed_parts ? false : $data;
}
?>
Nota: Nota de Compatibilidade
Por favor, tenha cuidado quando codificar as linhas do cabeçalho do HTTP. Para garantir compatibilidade máxima com todos os clientes, a palavra chave "Basic" deve ser escrita com "B" maiúsculo, deve se usar aspas duplas (não simples) em volta da string realm, e exatamente um espaço deve preceder o código 401 na linha do cabeçalho HTTP/1.0 401. Parâmetros de autenticação devem ser separados por vírgula, como visto no exemplo acima.
Ao invés de simplesmente mostrar o valor de PHP_AUTH_USER e PHP_AUTH_PW, como foi feito no exemplo acima, você deve querer checar a validade do nome de usuário e a senha. Talvez enviando uma query para um banco de dados, ou procurando o usuário em um arquivo dbm.
Cuidado com browsers Internet Explorer bugados por aí. Eles parecem muito minuciosos sobre a ordem dos cabeçalhos. Enviar o cabeçalho WWW-Authenticate antes do cabeçalho HTTP/1.0 401 resolve isso por enquanto.
A partir do PHP 4.3.0, para evitar que alguém escreva um script que revele a senha para uma página que foi autenticada através de um mecanismo externo tradicional, as variáveis PHP_AUTH não serão configuradas se autenticação externa estiver disponível para aquela página em particular e se safe mode estiver ligado. No entanto, REMOTE_USER pode ser usada para identificar um usuário autenticado externamente. Então, você pode usar $_SERVER['REMOTE_USER'].
Nota: Nota de Configuração
PHP usa a presença de uma diretiva chamada AuthType para determinar se autenticação externa está em efeito.
Perceba, no entanto, que a diretiva citada não previne que alguém que controle uma URL não autenticada de roubar senhas de URLs autenticadas no mesmo servidor.
Tanto o Netscape Navigator quanto o Internet Explorer limparão o cache de autenticação da janela do navegador para o realm após receber uma resposta 401 do servidor. Isso pode efetivamente "deslogar" um usuário, forçando o mesmo a re-entrar seu nome de usuário e senha. Algumas pessoas usam isso para delimitar o tempo de um login, ou fazer um botão de "log-out".
Exemplo #3 Exemplo de Autenticação via HTTP forçando um(a) novo(a) nome/senha
<<?php
function authenticate() {
header('WWW-Authenticate: Basic realm="Test Authentication System"');
header('HTTP/1.0 401 Unauthorized');
echo "Você deve usar um login e uma senha válidos para acessar esse recurso\n";
exit;
}
if (!isset($_SERVER['PHP_AUTH_USER']) ||
($_POST['SeenBefore'] == 1 && $_POST['OldAuth'] == $_SERVER['PHP_AUTH_USER'])) {
authenticate();
} else {
echo "<p>Bem vindo: {$_SERVER['PHP_AUTH_USER']}<br />";
echo "Login antigo: {$_REQUEST['OldAuth']}";
echo "<form action='{$_SERVER['PHP_SELF']}' METHOD='post'>\n";
echo "<input type='hidden' name='SeenBefore' value='1' />\n";
echo "<input type='hidden' name='OldAuth' value='{$_SERVER['PHP_AUTH_USER']}' />\n";
echo "<input type='submit' value='Re Autenticar' />\n";
echo "</form></p>\n";
}
?>
Esse comportamento não é necessário pelo padrão autenticação básica via HTTP, então você nunca deve depender disso. Testando com Lynx mostrou que Lynx não limpa as credenciais de autenticação com uma resposta 401 do servidor, então apertar voltar e depois avançar novamente abrirá o recurso enquanto os requerimentos de credenciais não mudarem. Porém, o usuário pode apertar a tecla '_' para limpar a sua informação de autenticação.
Também perceba que até o PHP 4.3.3, Autenticação HTTP não funcionava usando o servidor IIS da Microsoft com a versão CGI do PHP devido a limitação do IIS. Para fazer ela funcionar no PHP 4.3.3 ou superior, você deve editar a configuração "Directory Security" do IIs. Clique em "Editar" e apenas marque "Anonymous Access", todos os outros campos devem ser mantidos desmarcados.
Outra limitação é se você estiver usando o módulo IIS (ISAPI), você não deve usar as variáveis PHP_AUTH_* mas sim, a variável HTTP_AUTHORIZATION. Por exemplo, considere o seguinte código: list($user, $pw) = explode(':', base64_decode(substr($_SERVER['HTTP_AUTHORIZATION'], 6)));
Nota: IIS Note:
Para autenticação via HTTP funcionar no IIS, a diretiva do PHP cgi.rfc2616_headers deve estar configurada para 0 (o valor padrão).
Nota:
Se modo de segurança estiver ligado, o uid do script é adicionado a parte realm do cabeçalho WWW-Authenticate.
Sessões
Suporte a sessões no PHP consiste de uma maneira de presevar dados através de acessos subsequentes. Isso permite a criação de aplicações mais personalizadas e aumenta o apelo do seu web site. Todas as informações estão na sessões Session reference..
Lidando com XForms
» XForms define uma mudança com relação a formulários tradicionais que permite que sejam usados em uma variedade mais ampla de plataformas e browsers ou até mesmo em mídias não tradicionais tais como documentos PDF.
A primeira diferença chave nos XForms é como o formulário é enviado ao cliente. » XForms para autores de HTML contem uma descrição detalhada de como criar XForms. Para o propósito deste tutorial nós veremos apenas exemplos simples.
Exemplo #1 Um formulário XForms simples de busca
<h:html xmlns:h="http://www.w3.org/1999/xhtml"
xmlns="http://www.w3.org/2002/xforms">
<h:head>
<h:title>Search</h:title>
<model>
<submission action="http://example.com/search"
method="post" id="s"/>
</model>
</h:head>
<h:body>
<h:p>
<input ref="q"><label>Find</label></input>
<submit submission="s"><label>Go</label></submit>
</h:p>
</h:body>
</h:html>
O formulário acima mostra uma caixa de entrada de texto (chamada q), e um botão de submit (envio). Quando o botão de submit é clicado, o formulário será enviado para a página referenciada por action.
Aqui é onde começa a parecer diferente do ponto de vista da sua aplicação web. Em um formulário HTML normal, a informação seria enviada como application/x-www-form-urlencoded, no mundo dos XForms, porém, essa informação é enviada no formato XML.
Se você está escolhendo trabalhar com XForms então você, provavelmente, quer aquela informação como XML. Nesse caso, procure em $HTTP_RAW_POST_DATA, onde você achará o documento XML gerado pelo navegador e que você pode passar para o seu engine XSLT ou parser favorito.
Se você não estiver interessado em formatação e só quer que sua informação seja carregada na variável tradicional $_POST, você pode encarregar o navegador do cliente para enviar como um application/x-www-form-urlencoded mudando o atributo method para urlencoded-post.
Exemplo #2 Usando um XForm para popular o $_POST
<h:html xmlns:h="http://www.w3.org/1999/xhtml"
xmlns="http://www.w3.org/2002/xforms">
<h:head>
<h:title>Search</h:title>
<model>
<submission action="http://example.com/search"
method="urlencoded-post" id="s"/>
</model>
</h:head>
<h:body>
<h:p>
<input ref="q"><label>Find</label></input>
<submit submission="s"><label>Go</label></submit>
</h:p>
</h:body>
</h:html>
Nota: Até o término dessa edição, muitos navegadores não suportam XForms. Verifique a versão do seu navegador se os exemplos acima falharem.
Gerenciar o upload de arquivos
Índice
- Upload de arquivos com o método POST
- Explicação das mensagens de erro
- Problemas comuns
- Carregando múltiplos arquivos
- Suporte ao método PUT
Upload de arquivos com o método POST
O PHP é capaz de receber o upload de qualquer browser que siga a norma RFC-1867 (o que inclui Netscape Navigator 3 ou posterior, Microsoft Internet Explorer 3 com um patch da Microsoft, ou posterior sem patch). Isto permite que se faça o upload de arquivos de texto e binários. Com as funções de autenticação e manipulação de arquivos do PHP, você tem o controle completo de quem pode fazer o upload de arquivo e o que fazer com o arquivo após seu upload.
Nota: Nota Sobre Configurações Relacionadas
Veja também file_uploads, upload_max_filesize, upload_tmp_dir, post_max_size, max_input_time no php.ini
Note que o PHP também suporta o método PUT para upload de arquivos como o usado por Netscape Composer e W3C's Amaya clients. Veja Suporte ao Método Put para maiores detalhes.
Uma tela para upload de arquivo pode ser criada com um formulário especial parecido com este:
Exemplo #1 Formulário para Upload de Arquivo
<form enctype="multipart/form-data" action="_URL_" method="post"> <input type="hidden" name="MAX_FILE_SIZE" value="30000" /> Send this file: <input name="userfile" type="file" /> <input type="submit" value="Send File" /> </form>
A "_URL_" no exemplo acima deve ser substituida e apontar para um arquivo PHP. O campo escondido MAX_FILE_SIZE (medido em bytes) deve preceder o campo de input do arquivo, e seu valor é o tamanho limite aceito para o arquivo. Também tenha certeza que seu formulário de upload de arquivo tenha enctype="multipart/form-data" em outro caso o upload do arquivo não irá funcionar.
O valor de MAX_FILE_SIZE é um aviso para o browser. É fácil contornar este limite. Então não conte que o browser irá obedecer a sua vontade. O que foi estabelecido para maximum-size no PHP não pode ser enganado. Mas você deve adicionar MAX_FILE_SIZE em qualquer caso, já que salva os usuários do problema de esperar por um grande arquivo ser transferido somente para descobrir depois de tudo que ele é muito grande.
As variáveis definidas para o upload de arquivos são diferentes dependendo da versão e da configuração. A autoglobal $_FILES existe desde o PHP 4.1.0. A array $HTTP_POST_FILES existe desde o PHP 4.0.0. Estas array irão conter toda a informação do upload do arquivo. Usar $_FILES é preferido. Se a opção register_globals é on, os nomes de variáveis relacionados também existirão. O padrão de register_globals é off desde o PHP » 4.2.0.
Os conteúdos de $_FILES do nosso script de exemplo é como segue. Note que isso assume que o nome do upload do arquivo é userfile, como o usado no exemplo acima. Pode ser qualquer nome.
- $_FILES['userfile']['name']
-
O nome original do arquivo no computador do usuário.
- $_FILES['userfile']['type']
-
O tipo mime do arquivo, se o browser deu esta informação. Um exemplo pode ser "image/gif".
- $_FILES['userfile']['size']
-
O tamanho, em bytes, do arquivo.
- $_FILES['userfile']['tmp_name']
-
O nome temporário do arquivo, como foi guardado no servidor.
- $_FILES['userfile']['error']
-
O código de erro associado a este upload de arquivo. ['error'] foi adicionado no PHP 4.2.0
Nota:
Em versões anteriores a 4.1.0 o nome era $HTTP_POST_FILES e não é uma variável autoglobal como $_FILES é. PHP 3 não suporta $HTTP_POST_FILES.
Quando register_globals esta em on no php.ini, variáveis adicionais estão disponíveis. Por exemplo, $userfile_name será igual a $_FILES['userfile']['name'], $userfile_type será igual a $_FILES['userfile']['type'], etc. Lembre-se que desde o PHP 4.2.0, o padrão para register_globals é off. É preferível não depender desta opção.
Os arquivos serão guardados no diretório temporário do servidor, a menos que outro lugar seja especificado com a opção upload_tmp_dir no php.ini. O diretório padrão do servidor pode ser mudado se mudando o valor da variável de ambiente TMPDIR no ambiente onde o PHP esta sendo executado PHP. Mudando-a com putenv() de um script PHP não irá funcionar. Esta variável de ambiente também pode ser usada para se ter certeza que outras operações estão funcionando no arquivo do upload.
Note que deve se definir upload_temp_dir no php.ini ou TMPDIR, não podendo estarem ambos vazios, sendo recomendado no mínimo upload_tmp_dir.
Exemplo #2 Validando o upload de arquivos
Veja também as funções is_uploaded_file() e move_uploaded_file() para maiores informações. O seguinte exemplo irá processar o envio de um arquivo que vem de um formulário.
<?php
// Nas versões do PHP anteriores a 4.1.0, deve ser usado $HTTP_POST_FILES
// ao invés de $_FILES.
$uploaddir = '/var/www/uploads/';
$uploadfile = $uploaddir . $_FILES['userfile']['name'];
print "<pre>";
if (move_uploaded_file($_FILES['userfile']['tmp_name'], $uploaddir . $_FILES['userfile']['name'])) {
print "O arquivo é valido e foi carregado com sucesso. Aqui esta alguma informação:\n";
print_r($_FILES);
} else {
print "Possivel ataque de upload! Aqui esta alguma informação:\n";
print_r($_FILES);
}
print "</pre>";
?>
O script PHP que irá receber o arquivo do upload deve implementar qualquer lógica que for necessária para determinar o que deve ser feito com o arquivo do upload. Você pode, por exemplo, usar a variável $_FILES['userfile']['size'] para descartar qualquer arquivo que seja muito pequeno ou muito grande. Você pode usar a variável $_FILES['userfile']['type'] que não sejam de um certo tipo. Desde o PHP 4.2.0, você pode usar $_FILES['userfile']['error'] e planejar a sua lógica de acordo com os códigos de erro. Qualquer que seja a lógica, você deve excluir o arquivo do diretório temporário ou move-lo para outro lugar.
Se nenhum arquivo for selecionado em seu formulário, o PHP irá retornar $_FILES['userfile']['size'] como 0, e $_FILES['userfile']['tmp_name'] como none.
O arquivo será excluído do diretório temporário ao fim do script se não tiver sido movido ou renomeado.
Explicação das mensagens de erro
Desde o PHP 4.2.0, PHP retorna um código de erro apropriado na array do arquivo. O código de erro pode ser encontrado em ['error'] na array que é criada durante o upload do arquivo. Em outras palavras, o erro deve ser encontrado em $_FILES['userfile']['error'].
- UPLOAD_ERR_OK
-
Valor: 0; não houve erro, o upload foi bem sucedido.
- UPLOAD_ERR_INI_SIZE
-
Valor 1; O arquivo no upload é maior do que o limite definido em upload_max_filesize no php.ini.
- UPLOAD_ERR_FORM_SIZE
-
Valor: 2; O arquivo ultrapassa o limite de tamanho em MAX_FILE_SIZE que foi especificado no formulário HTML.
- UPLOAD_ERR_PARTIAL
-
Valor: 3; o upload do arquivo foi feito parcialmente.
- UPLOAD_ERR_NO_FILE
-
Valor: 4; Não foi feito o upload do arquivo.
Nota:
Estas tornaram-se constantes no PHP 4.3.0
Problemas comuns
O item MAX_FILE_SIZE não pode especificar um tamanho de arquivo com tamanho maior do que o especificado no php.ini em upload_max_filesize. O padrão é 2 Megabytes.
Se o limite de memória esta ativado, um maior memory_limit pode ser necessário. tenha certeza de estabelecer um memory_limit grande o suficiente.
Se max_execution_time for muito pequeno, a execução do script pode ultrapassar o limite de tempo. Tenha certeza de estabelecer um max_execution_time grande o suficiente.
Nota: max_execution_time somente afeta o tempo de execução do script em sí. Qualquer tempo gasto com atividades que aconteçam fora da execução do script como chamadas de sistema usando system(), a função sleep(), pesquisas em banco de dados, tempo gasto pelo processo de carregar(upload) um arquivo, etc. nâo é incluso na hora de determinar o lmite de tempo que o script esta sendo executado.
max_input_time define o tempo máximo em segundos, que é permitido ao script receber entradas, isto inclui uploads de arquivos. Para um arquivo grande ou multiplos arquivos, ou usuários em conexões lentas, o padrão de 60 segundos pode ser ultrapassado.
Se post_max_size for muito pequeno, arquivos grandes não poderão ser carregados. Tenha certeza de estabelecer post_max_size grande o suficiente.
Não validar o arquivo que você esta operando pode permitir que os usuários acessem informações sensíveis em outros diretórios.
Por favor note que o CERN httpd aparenta cortar tudo iniciando após o primeiro espaço do header content-type que ele recebe do cliente. Se for este o caso, CERN httpd não irá suportar o upload de arquivos.
Devido ao grande número de estilos de listagem de diretórios nós não podemos garantir que arquivos com nomes exóticos(como que contém espaço) sejam manuseados corretamente.
Um desenvolvedor não deve misturar campos de entrada e campos de upload de arquivo na mesma variável de formulário (usando um nome de campo como foo[]).
Carregando múltiplos arquivos
Múltiplos arquivos podem ser carregados usando-se diferentes name para input.
Também é possível carregar vários arquivos simultaneamente e ter a informação organizada automaticamente para você em arrays. Para fazer assim, você precisa usar a mesma sintaxe no formulário HTML que você usa para múltiplos selects e checkboxes:
Nota:
O Suporte para carregar múltiplos arquivos foi adicionado na versão PHP 3.0.10.
Exemplo #1 Carregando múltiplos arquivos
<form action="file-upload.php" method="POST" enctype="multipart/form-data"> Send these files:<br /> <input name="userfile[]" type="file" /><br /> <input name="userfile[]" type="file" /><br /> <input type="submit" value="Send files" /> </form>
Quando o formulário acima é submetido, as matrizes $_FILES['userfile'], $_FILES['userfile']['name'], e $_FILES['userfile']['size'] serão inicializadas (assim como $HTTP_POST_FILES para versões do PHP anterior a 4.1.0). Quando register_globals esta em on, globals para os arquivos carregados também são inicializadas. Cada um destes será uma array indexada numericamente dos valores apropriados para os arquivos submetidos.
Por exemplo, assuma que os nomes de arquivos tenham sido submetidos /home/test/review.html e /home/test/xwp.out. Neste caso, $_FILES['userfile']['name'][0] deve conter o valor review.html, e $_FILES['userfile']['name'][1] deve conter o valor xwp.out. Similarmente, $_FILES['userfile']['size'][0] deve conter o tamanho de review.html, e assim por diante.
$_FILES['userfile']['name'][0], $_FILES['userfile']['tmp_name'][0], $_FILES['userfile']['size'][0], e $_FILES['userfile']['type'][0] também são definidas.
Suporte ao método PUT
O suporte ao método PUT mudou entre PHP 3 e PHP 4. No PHP 4, deve se usar a entrada padrão para ler os conteúdos de um PUT.
Exemplo #1 Salvando arquivos HTTP PUT com o PHP 4
<?php
/* PUT data vem do stdin stream */
$putdata = fopen("php://stdin", "r");
/* Abre um arquivo para escrita */
$fp = fopen("myputfile.ext", "w");
/* Lê os dados 1KB de cada vez
e escreve no arquivo */
while ($data = fread($putdata,1024))
fwrite($fp,$data);
/* Fecha os streams */
fclose($fp);
fclose($putdata);
?>
Nota:
Toda a documentação abaixo aplica-se ao PHP 3 somente.
PHP prove suporte para o método HTTP PUT usado por clientes como Netscape Composer e W3C Amaya. Requisições PUT são muito mais simples do que o upload de arquivo e se parecem com isto:
PUT /path/filename.html HTTP/1.1
Isto normalmente indica que o cliente remoto gostaria de salvar o conteúdo que se segue como: /path/filename.html na sua arvore web. É obvio que não é uma boa idéia para o Apache ou o PHP automaticamente permitir que todos possam sobrescrever arquivos na sua arvore web. Então, para manusear este tipo de requisição você tem primeiro que dizer ao seu servidor web que você quer que um certo script PHP cuide da requisição. No apache você faz isto com a diretiva Script. Pode ser colocada praticamente em qualquer lugar do seu arquivo de configuração do Apache. Um lugar comum é dentro de um bloco <Directory> ou talvez dentro de um bloco <Virtualhost>. Uma linha como esta deve fazer o truque:
Script PUT /put.php
Isto diz para o apache enviar todas as requisições PUT que estejam no contexto que você colocou esta linha para o script put.php. Isto assume, é claro, que você tem o PHP ativado para a extensão .php e que o PHP esta ativo.
Dentro do seu arquivo put.php você deve então fazer algo parecido com isto:
<?php copy($PHP_UPLOADED_FILE_NAME, $DOCUMENT_ROOT . $REQUEST_URI); ?>
Isto deve copiar o arquivo para a localização requisitada pelo cliente remoto. Você provavelmente quer fazer alguma checagem e/ou autenticar o usuário antes de fazer esta copia de arquivo. O único truque aqui é que quando o php vê uma requisição com o método PUT ele guarda o arquivo carregado em um arquivo temporário justo como se fosse manuseado pelo método POST. Quando a requisição termina, este arquivo temporário é apagado. Assim seu script de manuseio do PUT tem que copiar este arquivo em outro lugar. O nome deste arquivo temporário esta na variável $PHP_PUT_FILENAME, e você pode ver o nome de arquivo de destino sugerido em $REQUEST_URI (deve variar em servidores diferentes do apache). Este nome do arquivo de destino é o que o cliente remoto especificou. Você não tem que ouvir o cliente. Você pode, por exemplo, copiar todos os arquivos carregados para um diretório especial de uploads.
Usando arquivos remotos
Enquanto allow_url_fopen estiver disponível no arquivo php.ini, você pode usar URLs HTTP e FTP com a maioria das funções que recebem um nome de arquivo como parâmetro. Além disso, URLs podem ser usadas com as funções include(), include_once(), require() e require_once() (desde o PHP 5.2.0, allow_url_include precisa estar habilitado para isto). Veja Supported Protocols and Wrappers para mais informações sobre protocolos suportados pelo PHP.
Nota:
No PHP 4.0.3 e inferiores, para usar URL wrappers, você precisava configurar o PHP usando a opção do script configure --enable-url-fopen-wrapper .
Nota:
As versões para Windows do PHP mais novas que o PHP 4.3 não suportam acesso a arquivos remoto para as seguintes funções: include(), include_once(), require(), require_once(), e as funções imagecreatefromXXX na extensão Funções da GD.
Por exemplo, você pode usar isso para abrir um arquivo em um web server remoto, avaliar a saída para a informação que você precisa, e então usar a informação em uma query de banco de dados, ou simplesmente mostrar em um estilo que combine com o resto do seu website.
Exemplo #1 Pegando o título de uma página remota
<?php
$file = fopen ("http://www.example.com/", "r");
if (!$file) {
echo "<p>Incapaz de abrir arquivo remoto.\n";
exit;
}
while (!feof ($file)) {
$line = fgets ($file, 1024);
/* Isso só funciona se o título e suas tags estiverem na mesma linha */
if (eregi ("<title>(.*)</title>", $line, $out)) {
$title = $out[1];
break;
}
}
fclose($file);
?>
Você também pode escrever arquivos em um servidor FTP (presumindo que você conectou como um usuário com os direitos de acesso corretos). Você só pode criar arquivos novos usando esse método. Se você tentar sobrescrever um arquivo que já existe, a chamada para fopen() falhará.
Para conectar como usuário que não o 'anonymous', você precisa especificar o nome de usuário (e possivelmente a senha) dentro da URL, como 'ftp://usuario:senha@ftp.example.com/caminho/para/arquivo'. (Você pode usar o mesmo tipo de sintaxe para acessar arquivos via HTTP quando eles requerem autenticação Basic).
Exemplo #2 Guardando informação em um servidor remoto
<?php
$file = fopen ("ftp://ftp.example.com/incoming/outputfile", "w");
if (!$file) {
echo "<p>Incapaz de abrir arquivo remoto para escrita.\n";
exit;
}
/* Escreva informação aqui. */
fwrite ($file, $_SERVER['HTTP_USER_AGENT'] . "\n");
fclose ($file);
?>
Nota:
Você talvez tenha tido a idéia, pelo exemplo acima, de usar essa técnica para escrever para um arquivo de log remoto. Infelizmente isso não funcionaria porque a chamada a fopen() falhará se o arquivo remoto já existir. Para fazer logs distrubuídos dessa maneira, você deve dar uma olhada na função syslog().
Tratamento de Conexões
O status de uma conexão é mantido internamente no PHP. Existem 3 estados possíveis:
- 0 - NORMAL
- 1 - ABORTED
- 2 - TIMEOUT
Quando um script PHP está sendo executado normalmente, o estado NORMAL está ativo. Se o cliente remoto desconecta, o estado ABORTED (abortado) é ligado. Uma desconexão do cliente remoto é normalmente causada pelo usuário apertando o botão STOP. Se o tempo limite imposto pelo PHP (veja set_time_limit()) é alcançado, o estado TIMEOUT (tempo acabado) é ligado.
Você pode decidir se quer ou não que a desconexão do cliente cause que seu script seja abortado. As vezes é útil sempre fazer o seu script rodar até completar mesmo se não há nenhum navegador remoto recebendo a saída. O comportamento padrão, no entanto, é de seu script ser abortado quando o cliente remoto desconecta. Esse comportamento pode ser configurado através da diretiva ignore_user_abort php.ini assim como pela diretiva correspondente do Apache .conf, "php_value ignore_user_abort" ou com a função ignore_user_abort(). Se você não disser para o PHP ignorar o abort do usuário e ele abortar, seu script será finalizado. A única exceção é se você tiver registrado uma função de finalização usando register_shutdown_function(). Com uma função de finalização, quando um usuário remoto clica no botão STOP, a próxima vez que seu script tentar gerar alguma saída, o PHP detectará que a conexão foi abortada e a função de finalização é chamada. Essa função de finalização também será chamada no fim do seu script mesmo terminando normalmente, então para fazer algo diferente caso o cliente desconecte, você pode usar a função connection_aborted(). Essa função retorna TRUE se a conexão foi abortada.
Seu script também pode ser finalizado pelo timer interno. O tempo limite padrão é de 30 segundos. Pode ser mudado usando a diretiva max_execution_time php.ini ou a diretiva do Apache .conf correspondente php_value max_execution_time assim como com a função set_time_limit(). Quando o timer chega ao limite, o script será abortado e assim como o caso acima de desconexão, se uma função de finalização foi registrada, ela será chamada. Dentro da função de finalização você pode checar se a causa da finalização foi estouro do tempo limite chamando a função connection_timeout(). Essa função retornará TRUE se o a função de finalização foi chamada pelo tempo ter acabado.
Uma coisa a ser notada é que ambos os estados ABORTED e TIMEOUT podem estar ligados ao mesmo tempo. Isso é possível se você disser ao PHP para ignorar o abort do usuário. O PHP continuará a notar o fato que o usuário pode ter quebrado a conexão, mas o script continuará executando. Se então ele alcançar o tempo limite, ele será abortado e sua função de finalização, se houver, será chamada. Nesse ponto, você terá que connection_status() retorna 3.
Conexão Permanente com o Banco de Dados
Conexões persistentes são conexões que não fecham quando a execução do seu script termina. Quando uma conexão persistente é requisitada, o PHP checa se já existe uma conexão persistente idêntica (que foi mantida aberta anteriormente) - e, se ela existe, ele a usa. Se não existir, ele cria uma nova. Uma conexão 'idêntica' é uma conexão que foi aberta ao mesmo host, com o mesmo nome de usuário e a mesma senha (onde for aplicável).
Pessoas que não estão totalmente familiarizadas com a maneira como servidores web trabalham e distribuem a carga podem confundir conexões persistentes com o que elas não são. In particular, elas não dão a você a habilidade de abrir 'sessões de usuários' na mesma conexão, elas não dão a habilidade de construir uma transação eficientemente, e elas não fazem um monte de outras coisas. De fato, para ser extremamente claro sobre o assunto, conexões persistentes não te dão nenhuma funcionalidade que não era possível com as suas correspondentes não-persistentes.
Por que?
Tem a ver com a maneira como os servidores web funcionam. Existem três maneiras de seu servidor web utilizar o PHP para gerar páginas.
O primeiro método é usar o PHP como um CGI "wrapper". Quando executado dessa maneira, uma instância do interpretador do PHP é criada e destruída para cada requisição de página (por uma página PHP) para o seu servidor web. Como ela é destruída após cada requisição, quaisquer recursos que ela adquirir (como uma conexão para um banco de dados) são fechados quando ela é destruída. Nesse caso, não há nenhum ganho ao tentar usar conexões persistentes -- elas simplesmente não persistem.
O segundo método, o mais popular, é rodar o PHP como um módulo em um servidor com multi-processos, que atualmente só inclue o Apache. Um servidor com multi-processos tipicamente tem um processo (pai) que coordena uma série de processos (filhos) que são os que realmente fazem o trabalho de servir as páginas. Quando uma requisição chega de um cliente, ela é entregue à um dos filhos que não estiver ocupado servindo outro cliente. Isso significa que quando o mesmo cliente faz uma segunda requisição ao servidor, ele pode ser servido por um processo filho diferente do da primeira vez. Quando abre-se uma conexão persistente, cada página que requisitar serviços de SQL pode reusar a mesma conexão estabelecida ao servidor SQL.
O último método é usar o PHP como um plug-in para um servidor web multithreaded. Atualmente, o PHP4 tem suporte para ISAPI, WSAPI, e NSAPI (no Windows), todos permitindo PHP ser usado como um plug-in em servidores multithreaded como Netscape FastTrack (iPlanet), Internet Information Server (IIS) da Microsoft, e O'Reilly's WebSite Pro. O comportamento é essencialmente o mesmo do modelo multiprocessado descrito anteriormente.
Se conexões persistentes não tem nenhuma funcionalidade a mais, para que elas servem?
A resposta é extremamente simples -- eficiência. Conexôes persistentes são boas se o sobrecarga (overhead) de criar uma conexão ao seu servidor SQL for alta. Saber se essa sobrecarga é alta depende de vários fatores. Como que tipo de banco de dados é, se está ou não na mesma máquina onde o servidor web está, o quão carregada de trabalho está a máquina hospedando o servidor SQL e assim por diante. O ponto é que se a sobrecarga de conexão for alta, conexões persistentes ajudam consideravelmente. Elas fazem com que os processos filhos simplesmente conectam-se uma vez só durante toda sua duração, ao invés de cada vez que eles processam uma página que requer uma conexão ao servidor SQL. Isso significa que cada filho que abriu uma conexão persistente terá sua própria conexão aberta ao servidor. Por exemplo, se você tiver 20 processos filhos diferentes que rodassem um script que fizesse uma conexão persistente à um servidor SQL, você teria 20 conexões diferentes ao banco, uma de cada filho.
Perceba, no entanto, que isso pode ter algumas desvantagens se você estiver usando um banco com limite de conexões que é excedido pela conexões persistentes filhas. Se seu banco tem um limite de 16 conexões simultâneas, e durante um momento de pico de acessos, 17 processos filhos tentam fazer a conexão, um deles não será capaz. Se houver bugs no seus scripts que não permitem que as conexões se fechem (como loops infinitos) o banco de dados com apenas 16 conexões pode rapidamente ficar sobrecarregado. Procure na documentação do seu banco por informações sobre como lidar com conexões ociosas ou abandonadas.
Existem mais alguns cuidados a se tomar quando usando conexões persistentes. Um deles é que, quando usando travamento de tabela em uma conexão persistente, se o script por qualquer razão não pode destravar a mesma, então scripts subsequentes usando a mesma conexão serão bloqueados indefinidamente e pode ser preciso reiniciar o servidor http ou o banco de dados. Outro cuidado a se ter é, quando usando transações, um bloco de transação também será carregado para o próximo script que usar a conexão se a execução do script terminar primeiro que o bloco de transação. Em ambos os casos, você pode usar register_shutdown_function() para registrar uma função simples de limpeza para destravar suas tabelas e fazer roll back de suas transação. O ideal é evitar o problema completamente não usando conexões persistentes em scripts que usam travamento de tabelas ou transações (você ainda pode usar elas nos outros casos).
Um resumo importante. Conexões persistente foram feitas para ter um mapeamento de um-para-um com conexões normais. Isso significa que você deve sempre ser capaz de substituir conexões persistentes com conexões não-persistentes e isso não mudará a maneira como seu script se comporta. Pode (e provavelmente irá) mudar a eficiência do mesmo, mas não o seu comportamento!
Veja também fbsql_pconnect(), ibase_pconnect(), ifx_pconnect(), ingres_pconnect(), msql_pconnect(), mssql_pconnect(), mysql_pconnect(), ociplogon(), odbc_pconnect(), ora_plogon(), pfsockopen(), pg_pconnect(), e sybase_pconnect().
Modo Seguro (Safe Mode)
Índice
O modo seguro do PHP é uma tentativa de resolver o problema de servidores compartilhados. É arquiteturalmente incorreto tentar resolver esse problema no nível do PHP, mas já que as alternativas no nível dos servidores e dos sistemas operacionais não são muito eficientes, muitas pessoas, especialmente provedores de internet, usam o modo seguro por enquanto.
O modo seguro foi removido no PHP 6.0.0.
Segurança e Modo Seguro
| Nome | Valor Padrão | Alterável | Changelog |
|---|---|---|---|
| safe_mode | "0" | PHP_INI_SYSTEM | Removido no PHP 6.0.0. |
| safe_mode_gid | "0" | PHP_INI_SYSTEM | Disponível desde o PHP 4.1.0. Removido no PHP 6.0.0. |
| safe_mode_include_dir | NULL | PHP_INI_SYSTEM | Disponível desde o PHP 4.1.0. Removido no PHP 6.0.0. |
| safe_mode_exec_dir | "" | PHP_INI_SYSTEM | Removido no PHP 6.0.0. |
| safe_mode_allowed_env_vars | "PHP_" | PHP_INI_SYSTEM | Removido no PHP 6.0.0. |
| safe_mode_protected_env_vars | "LD_LIBRARY_PATH" | PHP_INI_SYSTEM | Removido no PHP 6.0.0. |
| open_basedir | NULL | PHP_INI_ALL | PHP_INI_SYSTEM no PHP < 6. |
| disable_functions | "" | php.ini only | Disponível desde o PHP 4.0.1. |
| disable_classes | "" | php.ini only | Disponível desde o PHP 4.3.2. |
Breve descrição das diretivas de configuração.
- safe_mode boolean
-
Determina se o modo seguro estará habilitado ou não.
- safe_mode_gid boolean
-
Por padrão, o modo seguro faz checagem comparando o UID quando abre arquivos. Se você quiser diminuir a especificidade do teste para compara com o GID, então ligue a diretiva safe_mode_gid. Escolher entre usar checagem de UID (FALSE) ou de GID quando acessar um arquivo.
- safe_mode_include_dir string
-
Checagem de UID/GID não são feitas quando é feita inclusão de arquivos desse diretório e seus subdiretórios (diretório também deve estar no include_path ou o caminho completo deve ser incluso).
A partir do PHP 4.2.0, essa diretiva pode receber vários diretórios separados por dois pontos (ponto-e-vírgula no Windows) similar à diretiva include_path, ao contrário de apenas um diretório A restrição especificada é, na verdade, um prefixo, não um nome de diretório. Isso significa que "safe_mode_include_dir = /dir/incl" também permite acesso a "/dir/include" e "/dir/incls" se eles existirem. Quando você quiser restringir o acesso apenas ao diretório especificado, termine com uma barra. Por exemplo: "safe_mode_include_dir = /dir/incl/" Se o valor dessa diretiva estiver vazio, nenhum arquivo com UID/GID diferente pode ser incluído no PHP 4.2.3 e a partir do PHP 4.3.3. Em versões anteriores, todos os arquivos podiam ser incluídos. - safe_mode_exec_dir string
-
Se o PHP for usado no modo seguro, system() e as outras funções que executam programas do sistema se recusam a executar programas que não estão no diretório atual. Você deve usar / como separador diretório em todos os ambientes, inclusive o Windows.
- safe_mode_allowed_env_vars string
-
Editar certas variáveis de ambientes pode ser uma falha de segurança em potencial. Essa diretiva contem uma lista de prefixos delimitados por vírgulas. No modo seguro, o usuário só pode alterar as variáveis de ambiente cujo nome começa com um dos prefixos dessa lista. Por padrão, os usuários só poderão ser capazser de editar variáveis de ambiente que começão com PHP_ (ex.: PHP_FOO=BAR).
Nota:
Se essa diretiva estiver vazia, o PHP deixará o usuário modificar QUALQUER variável de ambiente!
- safe_mode_protected_env_vars string
-
Essa diretiva contem uma lista delimitada por vírgulas de varáveis de ambiente que o usuário final não será capaz de mudar usando putenv(). Essas variáveis serão protegidas mesmo que safe_mode_allowed_env_vars esteja configurada para permitir que elas sejam mudadas.
- open_basedir string
-
Limita os arquivos que podem ser abertos ao diretório especificado e seus subdiretórios, incluindo o arquivo em si. Essa diretiva NÃO é afetada pelo estado do modo seguro, seja este ligado ou desligado.
Quando um script tenta abrir um arquivo com, por exemplo, fopen() ou gzopen(), a localização do arquivo é checada. Quando o arquivo está fora do diretório especificado, o PHP se recusará a abrí-lo. Todos os links simbólicos também passam pelo teste, não sendo possível evitar essa restrição com um symlink. Se o arquivo não existe então o symlink não deveria ser resolvido e o nome do arquivo é comparado com (um resolvido) open_basedir.
O valor especial
.indica que o diretório de trabalho, onde o script é rodado, será usado como o diretório base. Isso é, no entanto, um pouco perigoso, já que o diretório de trabalho do script pode ser facilmente alterado com a função chdir().In httpd.conf, open_basedir can be turned off (e.g. for some virtual hosts) the same way as any other configuration directive with "php_admin_value open_basedir none".
No Windows, separe os diretórios com ponto-e-vírgula. Em todos os outros sistemas, separe os diretórios com dois pontos. Como módulo do Apache, caminhos do open_basedir dos diretórios pais são herdados automaticamente agora.
A restrição especificada com open_basedir é na verdade um prefixo, não um nome de diretório. Isso significa que "open_basedir = /dir/incl" também permite acesso à "/dir/include" e "/dir/incls" se eles existirem. Quando você quiser restringir o acesso para apenas o diretório especificado, termine com uma barrra. Por exemplo: "open_basedir = /dir/incl/"
O padrão é permitir que todos os arquivos sejam abertos.
- disable_functions string
- A diretiva permite que você desabilite certas funções por razões de segurança. Ela recebe uma lista de nomes de funções separadas por vírgula. disable_functions não é afetada pela diretiva Safe Mode. Essa diretiva deve ser configurada no php.ini Você não pode, por exemplo, configurá-la no httpd.conf.
- disable_classes string
-
Essa diretiva permite que você desabilite certas classes por
razões de segurança. Ela recebe
uma lista de nomes de funções separadas por vírgula. disable_functions
não é afetada pela diretiva Safe Mode.
Essa diretiva deve ser configurada no php.ini Você não pode,
por exemplo, configurá-la no httpd.conf.
Nota: Availability note
Essa diretiva está disponível na versão 4.3.2 ou superior.
Veja também: register_globals, display_errors, e log_errors
Quando o safe_mode está ligado, o PHP checa se o proprietário do script atual bate com o proprietário do arquivo a ser operado por uma função de arquivo. Por exemplo:
-rw-rw-r-- 1 rasmus rasmus 33 Jul 1 19:20 script.php -rw-r--r-- 1 root root 1116 May 26 18:01 /etc/passwd
<?php
readfile('/etc/passwd');
?>
Warning: SAFE MODE Restriction in effect. The script whose uid is 500 is not allowed to access /etc/passwd owned by uid 0 in /docroot/script.php on line 2
No entando, em certos ambientes uma checagem rígida de UID não é apropriada e uma checagem mais leve de GID é suficiente. Isso é suportado através da diretiva safe_mode_gid. Atribuindo a ela o valor On faz a checagem de GID, mais leve e atribuindo a ela o valor Off (o padrão) faz a checagem UID.
Se, ao invés de safe_mode, você editou um diretório em open_basedir, então todas as operações de arquivos serão limitadas a arquivos no diretório especificado e seus subdiretórios. Por exemplo (httpd.conf do Apache de exemplo):
<Directory /docroot> php_admin_value open_basedir /docroot </Directory>
Warning: open_basedir restriction in effect. File is in wrong directory in /docroot/script.php on line 2
Você também pode desabilitar funções individuais. Perceba que a diretiva disable_functions não pode ser usada fora do arquivo php.ini file o que significa que você não pode desabilitar funções em um virtualhost ou diretório específico no seu arquivo httpd.conf Se nós acrescentarmos isso ao nosso arquivo php.ini:
disable_functions = readfile,system
Warning: readfile() has been disabled for security reasons in /docroot/script.php on line 2
Essas restrições do PHP não são validas em binários executados, é claro.
Funções restringidas/desabilitadas pelo modo seguro
Essa lista provavelmente ainda está incomplete e possivelmente incorreta das funções limitadas pelo modo seguro.
| Função | Limitações | |
|---|---|---|
| dbmopen() | Verifica se os arquivos ou diretórios que estão sendo operados tem o mesmo UID (proprietário) do script que está sendo executado. | |
| dbase_open() | Verifica se os arquivos ou diretórios que estão sendo operados tem o mesmo UID (proprietário) do script que está sendo executado. | |
| filepro() | Verifica se os arquivos ou diretórios que estão sendo operados tem o mesmo UID (proprietário) do script que está sendo executado. | |
| filepro_rowcount() | Verifica se os arquivos ou diretórios que estão sendo operados tem o mesmo UID (proprietário) do script que está sendo executado. | |
| filepro_retrieve() | Verifica se os arquivos ou diretórios que estão sendo operados tem o mesmo UID (proprietário) do script que está sendo executado. | |
| ifx_* | sql_safe_mode restrictions, (!= safe mode) | |
| ingres_* | sql_safe_mode restrictions, (!= safe mode) | |
| mysql_* | sql_safe_mode restrictions, (!= safe mode) | |
| pg_lo_import() | Verifica se os arquivos ou diretórios que estão sendo operados tem o mesmo UID (proprietário) do script que está sendo executado. | |
| posix_mkfifo() | Verifica se o diretório que será afetado por esta operação tem o mesmo UID (proprietário) do script que está sendo executado. | |
| putenv() | Obedece as diretivas safe_mode_protected_env_vars e safe_mode_allowed_env_vars. Também veja a documentação on putenv() | |
| move_uploaded_file() | Verifica se os arquivos ou diretórios que estão sendo operados tem o mesmo UID (proprietário) do script que está sendo executado. | |
| chdir() | Verifica se o diretório que será afetado por esta operação tem o mesmo UID (proprietário) do script que está sendo executado. | |
| dl() | Esta função é desabilitada quando o PHP é executado em safe-mode | |
| operador backtick (``) | Esta função é desabilitada quando o PHP é executado em safe-mode | |
| shell_exec() (função equivalente de backticks) | Esta função é desabilitada quando o PHP é executado em safe-mode | |
| exec() | Você só pode rodar executáveis que estejam no safe_mode_exec_dir. Por razões práticas, não é permitido atualmente ter .. compondo o caminho para o executável. escapeshellcmd() é executada no argumento dessa função. | |
| system() | Você só pode rodar executáveis que estejam no safe_mode_exec_dir. Por razões práticas, não é permitido atualmente ter .. compondo o caminho para o executável. escapeshellcmd() é executada no argumento dessa função. | |
| passthru() | Você só pode rodar executáveis que estejam no safe_mode_exec_dir. Por razões práticas, não é permitido atualmente ter .. compondo o caminho para o executável. escapeshellcmd() é executada no argumento dessa função. | |
| popen() | Você só pode rodar executáveis que estejam no safe_mode_exec_dir. Por razões práticas, não é permitido atualmente ter .. compondo o caminho para o executável. escapeshellcmd() é executada no argumento dessa função. | |
| fopen() | Verifica se o diretório que será afetado por esta operação tem o mesmo UID (proprietário) do script que está sendo executado. | |
| mkdir() | Verifica se o diretório que será afetado por esta operação tem o mesmo UID (proprietário) do script que está sendo executado. | |
| rmdir() | Verifica se o diretório que será afetado por esta operação tem o mesmo UID (proprietário) do script que está sendo executado. | |
| rename() | Verifica se os arquivos ou diretórios que estão sendo operados tem o mesmo UID (proprietário) do script que está sendo executado. Verifica se o diretório que será afetado por esta operação tem o mesmo UID (proprietário) do script que está sendo executado. | |
| unlink() | Verifica se os arquivos ou diretórios que estão sendo operados tem o mesmo UID (proprietário) do script que está sendo executado. Verifica se o diretório que será afetado por esta operação tem o mesmo UID (proprietário) do script que está sendo executado. | |
| copy() | Verifica se os arquivos ou diretórios que estão sendo operados tem o mesmo UID (proprietário) do script que está sendo executado. Verifica se o diretório que será afetado por esta operação tem o mesmo UID (proprietário) do script que está sendo executado. (on source and target) | |
| chgrp() | Verifica se os arquivos ou diretórios que estão sendo operados tem o mesmo UID (proprietário) do script que está sendo executado. | |
| chown() | Verifica se os arquivos ou diretórios que estão sendo operados tem o mesmo UID (proprietário) do script que está sendo executado. | |
| chmod() | Verifica se os arquivos ou diretórios que estão sendo operados tem o mesmo UID (proprietário) do script que está sendo executado. Além disso, você não pode editar os bits SUID, SGID e sticky | |
| touch() | Verifica se os arquivos ou diretórios que estão sendo operados tem o mesmo UID (proprietário) do script que está sendo executado. Verifica se o diretório que será afetado por esta operação tem o mesmo UID (proprietário) do script que está sendo executado. | |
| symlink() | Verifica se os arquivos ou diretórios que estão sendo operados tem o mesmo UID (proprietário) do script que está sendo executado. Verifica se o diretório que será afetado por esta operação tem o mesmo UID (proprietário) do script que está sendo executado. (nota: apenas o alvo é checado) | |
| link() | Verifica se os arquivos ou diretórios que estão sendo operados tem o mesmo UID (proprietário) do script que está sendo executado. Verifica se o diretório que será afetado por esta operação tem o mesmo UID (proprietário) do script que está sendo executado. (nota: apenas o alvo é checado) | |
| apache_request_headers() | No modo seguro, cabeçalhos começando com 'authorization' (não diferenciando maiúsculas e minúsculas) não serão retornados. | |
| header() | No modo seguro, o uid do script é adicionado a parte realm do cabeçalho WWW-Authenticate se você configurar esse cabeçalho (usado para Autenticação HTTP). | |
| variáveis PHP_AUTH | No modo seguro, as variáveis PHP_AUTH_USER, PHP_AUTH_PW, e AUTH_TYPE não estão disponíveis no array $_SERVER. Apesar de tudo, você ainda pode usar REMOTE_USER para o USER. (nota: só afetado desde o PHP 4.3.0) | |
| highlight_file(), show_source() | Verifica se os arquivos ou diretórios que estão sendo operados tem o mesmo UID (proprietário) do script que está sendo executado. Verifica se o diretório que será afetado por esta operação tem o mesmo UID (proprietário) do script que está sendo executado. (nota: só afetado desde o PHP 4.2.1) | |
| parse_ini_file() | Verifica se os arquivos ou diretórios que estão sendo operados tem o mesmo UID (proprietário) do script que está sendo executado. Verifica se o diretório que será afetado por esta operação tem o mesmo UID (proprietário) do script que está sendo executado. (nota: só afetado desde o PHP 4.2.1) | |
| set_time_limit() | Não tem efeito quando o PHP é executado em safe mode. | |
| max_execution_time | Não tem efeito quando o PHP é executado em safe mode. | |
| mail() | Em modo seguro, o quinto parâmetro é desabilitado. (nota: só afetado desde o PHP 4.2.3) | |
| Todos filesystem e funções de stream. | Verifica se os arquivos ou diretórios que estão sendo operados tem o mesmo UID (proprietário) do script que está sendo executado. Verifica se o diretório que será afetado por esta operação tem o mesmo UID (proprietário) do script que está sendo executado. (veja a opção safe_mode_include_dir php.ini. | ?? |
Utilizando o PHP na linha de comando
A partir versão 4.3.0, o PHP suporta um novo tipo SAPI (Server Application Programming Interface) chamado CLI que significa Command Line Interface. Como o próprio nome indica, essa SAPI tem foco no desenvolvimento de aplicações shell (ou no terminal/linha de comando) com o PHP. Há algumas diferenças entre a a CLI SAPI e outras SAPIs que são explicadas neste capítulo. Mas é errado dizer que a versão CLI e CGI são SAPIs diferentes pelo motivo que elas compartilham muitos comportamentos idênticos.
A CLI SAPI foi liberada primeiramente com o PHP 4.2.0, mas ainda em estágio experimental, sendo necessário ativá-la explicitamente com a opção --enable-cli durante o ./configure. Desde o PHP 4.3.0 a CLI SAPI não mais é experimental e a opção --enable-cli está ligada por default. você pode usar a opção --disable-cli para desativá-la.
Desde o PHP 4.3.0, o nome, localização e existência dos executáveis CLI e CGI podem mudar dependendo de como o PHP foi instalado no seu sistema. Por padrão, quando executado o make, ambos CGI e CLI são compilados e colocados em sapi/cgi/php e sapi/cli/php, respectivamente, no seu diretório de fontes PHP. Note que que ambas tem o nome php. O que acontece durante o make install depende dos parâmetros do configure. Se o módulo SAPI é escolhido durante o configure, como o apxs, ou a opção --disable-cgi é utilizada, a versão CLI é copiada para {PREFIX}/bin/php durante o make install em vez da versão CGI ser colocada aqui. Então, por exemplo, se você tiver --with--apxs na sua linha de configuração, então a versão CLI é copiada para {PREFIX}/bin/php durante o make install. Se você quiser sobrescrever a instalação do executável CGI, use make install-cli depois do make install. Alternativamente, você pode especificar --disable-cgi em seu configure.
Nota:
Por serem ambos --enable-cli e --enable-cgi ligados por padrão, ter um --enable-cli em seu configure não significa necessariamente que a versão CLI será copiada para {PREFIX}/bin/php durante o make install.
Os pacotes para Windows distribuidos entre o PHP 4.2.0 e PHP 4.2.3 forneciam a versão CLI com o nome php-cli.exe, na mesma pasta que a versão CGI php.exe. A partir do PHP 4.3.0, os pacotes Windows distribuem a versão CLI como php.exe em uma pasta separada, chamada cli ou seja: cli/php.exe . A partir do PHP 5, a versão CLI também é distribuída no diretório principal, com o nome php.exe. A versão CGI é distribuída com o nome php-cgi.exe.
A partir do PHP 5, um novo arquivo php-win.exe começou a ser distribuído. Esta versão é igual a versão CLI, exceto que esse php-win não exibe nenhum output e também não disponibiliza nenhum console (nenhuma caixa de texto aparece na tela). Este comportamento é semelhante ao do php-gtk. Você pode configurar esse modo com --enable-cli-win32 .
Nota: Que versão de SAPI eu tenho?
Na linha de comando, digitando php -v, ele lhe dirá se o php é CGI ou CLI. Veja também a função php_sapi_name() e a constante PHP_SAPI.
Nota:
Um manual Unix man foi acrescentado no PHP 4.3.2. Você pode vê-lo digitando man php em seu ambiente shell.
Diferenças importantes das CLI SAPI comparada com outras SAPIs:
-
Diferentemente da CGI SAPI, nenhum header é impresso na saída.
A CGI SAPI possui um meio de suprimir os headers HTTP, mas não há uma chave equivalente para ativá-los na CLI SAPI.
A versão CLI é definida silenciosa por padrão. Mas as chaves -q e --no-header são mantidas para compatibilidade, de forma que você possa utilizar scripts CGI antigos.
Ela não altera o diretório de execução para o do script. (as chaves -C e --no-chdir também são mantidas para compatibilidade).
Mensagens de erro em texto simples (sem formatação HTML).
-
Estas são as diretivas do php.ini que são sobrescritas pela CLI SAPI porque não fazem sentido no ambiente shell:
Diretivas php.ini sobrescritas Diretiva Valor default CLI SAPI Comentários html_errors FALSE Pode ser bem difícil de ler mensagens de erro no seu shell quando elas estão embebidas dentro de tags HTML, por isso essa diretiva tem default para FALSE. implicit_flush TRUE Essa diretiva causa que qualquer saída gerada de um print(), echo() e semelhantes sejam imediatamente escritas para o output e não cacheadas em nenhum buffer. Você ainda pode usar o output buffering se você precisa atrasar ou manipular a saída padrão. max_execution_time 0 (unlimited) Devido as infinitas possibilidades da utilização do PHP em ambientes shell, o tempo máximo de execução foi configurado para ilimitado. Enquanto aplicações escritas para web são geralmente executadas em poucos segundos, aplicações no shell tendem a ter um tempo de execução mais longo. register_argc_argv TRUE Como essa diretiva é TRUE você sempre terá acesso as variáveis argc (número de argumentos passados para a aplicação) e argv (array dos argumentos informados) na CLI SAPI.
A partir do PHP 4.3.0, as variáveis do PHP $argc e $argv são registradas e preenchidas com os valores apropriados quando utilizando a CLI SAPI. Antes dessa versão, a criação dessas variáveis era controlada da mesma forma que as versões CGI e MODULE e precisava da diretiva PHP register_globals configurada para on. Independentemente da versão ou da configuração de register_globals, você sempre poderá acessar esses dados através de $_SERVER ou $HTTP_SERVER_VARS. Exemplo: $_SERVER['argv']
Nota:
Estas diretivas não podem ser inicializadas com outros valores do arquivo de configuração php.ini ou um arquivo personalizado (se informado). Esta limitação existe porque estes valores são aplicados depois que todos os arquivos de configuração são analisados. Entretanto, seus valores podem ser modificados durante a execução (o que pode não fazer sentido para todas elas, por exemplo, register_argc_argv).
-
Para facilicar a operação no ambiente shell, as seguintes constantes estão definidas:
Constantes específicas CLI Constante Descrição STDIN Um stream já aberto para o stdin. Isto economiza ter de abrí-lo com Se você precisa ler apenas uma linha do stdin, você pode utilizar<?php
$stdin = fopen('php://stdin', 'r');
?><?php
$line = trim(fgets(STDIN)); // lê uma linha do STDIN
fscanf(STDIN, "%d\n", $number); // carrega number a partir do STDIN
?>STDOUT Um stream já aberto para o stdout. Isto economiza ter de abrí-lo com <?php
$stdout = fopen('php://stdout', 'w');
?>STDERR Um stream já aberto para o stderr. Isto economiza ter de abrí-lo com <?php
$stderr = fopen('php://stderr', 'w');
?>Considerando isso, você não precisará mais abrí-los, por exemplo o stderr você mesmo, mas simplesmente usar a constante em vez do recurso stream:
Você não precisa fechar explicitamente esses streams. Isto é realizado automaticamente pelo PHP.php -r 'fwrite(STDERR, "stderr\n");'
-
A CLI SAPI não modifica o diretório de execução atual para o diretório onde o script é interpretado!
Exemplo mostrando a diferença da CGI SAPI:
<?php
/* Nossa aplicação de teste chamada test.php */
echo getcwd(), "\n";
?>Quando utilizando a versão CGI, a saída é:
Isto mostra como o PHP modifica o diretório atual para aquela onde o script é executado.$ pwd /tmp $ php -q outro_diretorio/test.php /tmp/outro_diretorio
Utilizando a versão CLI SAPI:
E isto mostra a grande flexibilidade ferramentas shell em PHP.$ pwd /tmp $ php -f outro_diretorio/test.php /tmp
Nota:
A CGI SAPI suporta o comportamento da CLI SAPI utilizando a chave -C quando de sua execução na linha de comando.
A lista de opções de linha de comando fornecidas pelo binário do PHP pode ser solicitada a qualquer tempo executando o PHP com a opção -h :
Usage: php [options] [-f] <file> [args...]
php [options] -r <code> [args...]
php [options] [-- args...]
-s Display colour syntax highlighted source.
-w Display source with stripped comments and whitespace.
-f <file> Parse <file>.
-v Version number
-c <path>|<file> Look for php.ini file in this directory
-a Run interactively
-d foo[=bar] Define INI entry foo with value 'bar'
-e Generate extended information for debugger/profiler
-z <file> Load Zend extension <file>.
-l Syntax check only (lint)
-m Show compiled in modules
-i PHP information
-r <code> Run PHP <code> without using script tags <?..?>
-h This help
args... Arguments passed to script. Use -- args when first argument
starts with - or script is read from stdin
A CLI SAPI fornecer três maneiras diferentes para você executar seu código PHP:
-
Chamando o PHP para executar um arquivo determinado.
De ambas maneiras (utilizando ou não a opção -f ) o arquivo my_script.php é executado. Você pode escolher qualquer arquivo para executar --- seus scripts PHP não precisam terminar com a extensão .php, podendo ter qualquer nome ou extensão que você deseje.php my_script.php php -f my_script.php
-
Passar o código PHP para execução diretamente a linha de comando.
É preciso ter especial cuidado com a substituição de variáveis shell e delimitação de strings utilizada.php -r 'print_r(get_defined_constants());'
Nota:
Leia o exemplo cuidadosamente, observando que não há tags de abertura ou fechamento! A opção -r simplesmente não precisa delas. Utilizando-as você obterá erros de interpretação.
-
Fornece código PHP para interpretação via a entrada padrão (stdin).
Isto mostra a habilidade poderosa de como criar dinamicamente código PHP e fornecê-lo ao binário, como demonstrado neste exemplo (apenas demonstrativo):
$ alguma_aplicacao | algum_filtro | php | sort -u >final_output.txt
Assim como qualquer aplicação shell, não somente o binário do PHP aceita um certo número de argumentos, mas também seu script PHP também pode recebê-los. O número de argumentos que podem ser passados para seu script não é limitado ao PHP (mas o shell tem um certo limite de tamanho em caracteres que podem ser informados, e não há um padrão para esse limite). Os argumentos passados para seu script são disponibilizados no array global $argv. No índice zero sempre conterá o nome do script (podendo ser - no caso de código PHP estar vindo da entrada padrão ou da opção de linha de comando -r ). O segunda variável global $argc contém o número de elementos no array $argv (mas não o número de argumentos passados para seu script.
Os argumentos que você deseja passar para seu script não podem começar com o caracter - e isso não pode ser modificado. Passando argumentos para seu script que comecem com um - causará problemas porque o PHP tentará manuseá-los. Para prevenir isso, utilize o separador de argumentos --. Depois que esse separador é passado para o PHP, todos os argumentos restantes são repassados intocados para seu script.
# Isto não executará o código fornecido e irá fazer o PHP mostrar sua ajuda
$ php -r 'var_dump($argv);' -h
Usage: php [options] [-f] <file> [args...]
[...]
# Isto passará o argumento '-h' para seu script e prevenirá o PHP de usá-lo
$ php -r 'var_dump($argv);' -- -h
array(2) {
[0]=>
string(1) "-"
[1]=>
string(2) "-h"
}
Entretanto, há ainda uma outra maneira de se utilizar o PHP no shell. Você pode escrever um script que na primeira linha tenha #!/usr/bin/php e em seguida código PHP normal, incluindo as tags de início e fim do PHP. Você também precisa configurar os atributos de execução do arquivo (por exemplo, chmod +x test) de forma que seu script seja executado normalmente como um script shell/Perl:
#!/usr/bin/php
<?php
var_dump($argv);
?>
$ chmod +x teste
$ ./test -h -- foo
array(4) {
[0]=>
string(6) "./teste"
[1]=>
string(2) "-h"
[2]=>
string(2) "--"
[3]=>
string(3) "foo"
}
Opções com nomes "longos" foram disponibilizados a partir do PHP 4.3.3.
| Opção | Opção Longa | Descrição |
|---|---|---|
| -s | --syntax-highlight |
Mostra o código fonte com destaque de cores. Esta opção usa o mecanismo interno para interpretar o arquivo e produzir uma versão HTML do fonte com destaque de cores e a envia para a saída padrão. Note que ele somente gerará blocos de <code> [...] </code>, mas não headers HTML.
|
| -s | --syntax-highlighting |
Apelido para --syntax-highlight . |
| -w | --strip |
Mostra o fonte sem comentários e espaços em branco.
|
| -f | --file |
Interpreta e executa o arquivo informado com a opção -f Esta diretiva é opcional e pode ser deixada de lado. Informar somente o nome do arquivo para execução é suficiente. |
| -v | --version |
Imprime as versões o PHP, PHP SAPI e Zend para a saída padrão, por exemplo: $ php -v PHP 4.3.0 (cli), Copyright (c) 1997-2002 The PHP Group Zend Engine v1.3.0, Copyright (c) 1998-2002 Zend Technologies |
| -c | --php-ini |
Esta opção informa um diretório onde procurar pelo php.ini ou especifica um arquivo INI personalizado diretamente (não presisa ser obrigatoriamente php.ini), por exemplo: $ php -c /custom/directory/ my_script.php $ php -c /custom/directory/custom-file.ini my_script.php |
| -n | --no-php-ini |
Ignora todo o php.ini. Esta chave está disponível desde o PHP 4.3.0. |
| -d | --define |
Esta opção permite definir um valor personalizado para qualquer diretiva de configuração permitida no php.ini. Sintaxe: -d diretiva[=valor] Exemplos (linhas cortadas para melhor visualização):
# Omitindo a parte do valor irá configurar a diretiva para "1"
$ php -d max_execution_time
-r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(1) "1"
# Passando um valor vazio irá configurar a diretiva para ""
php -d max_execution_time=
-r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(0) ""
# A diretiva de configuração será preenchida com qualquer coisa informada depois do caracter =''
$ php -d max_execution_time=20
-r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(2) "20"
$ php
-d max_execution_time=instonaofazsentido
-r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(15) "instonaofazsentido"
|
| -a | --interactive |
Roda o PHP em modo interativo. |
| -e | --profile-info |
Gera informações estendidas para o debugador/profiler. |
| -z | --zend-extension |
Carrega a extensão Zend. Se somente o nome de arquivo é fornecido, o PHP tenta carregar essa extensão do caminho default de bibliotecas do seu sistema (geralmente especificado em /etc/ld.so.conf em sistemas Linux). Passando um nome de arquivo com o caminho absoluto irá evitar a procura no caminho das bibliotecas de sistema. Um nome de arquivo com uma informação de diretório relativa fará com que o PHP apenas tente carregar a extensão no caminho relativo ao diretório atual. |
| -l | --syntax-check |
Esta opção fornece uma maneira conveniente apenas realizar uma checagem de sintaxe no código PHP fornecido. No sucesso, o texto No syntax errors detected in <arquivo> é impresso na saída padrão e informado o código de saida de sistema 0. Em caso de erro, o texto Errors parsing <filename> juntamente com o a mensagem do interpretador interno é impressa para a saída padrão e o código de saída de sistema é 255. Esta opção não procura por erros fatais (como funções não definidas). Use -f se você deseja detectar erros fatais também.
|
| -m | --modules |
Utilizando essa opção, o PHP imprime os módulos PHP e Zend compilados (e carregados): $ php -m [PHP Modules] xml tokenizer standard session posix pcre overload mysql mbstring ctype [Zend Modules] |
| -i | --info | Esta opção de linha de comando chama a função phpinfo() e imprime seus resultados. Se o PHP não está funcionando bem, é interessante fazer um php -i para observar qualquer mensagem de erro impressa antes ou dentro das tabelas de informação. Utilizando o modo CGI o resultado impresso está em HTML, e ela por isso é um pouco grande. |
| -r | --run |
Esta opção permite a execução de código PHP direto da linha de comando. As tags de início e fim do PHP (<?php e ?>) não são necessárias e causarão erros de interpretação se informadas.
|
| -h | --help | Com essa opção, você pode obter informações sobre a lista atual de opções de linha de comando pequenas descrições sobre o que elas fazem. |
| -? | --usage | Apelido para --help . |
O PHP executável pode ser utilizando para rodar scripts PHP absolutamente independente de um servidor web. Se você está num sistema Unix, você pode acrescentar uma linha especial na primeira linha de seu script e torná-lo executável, então o sistema operacional saberá que programa deverá rodar o script. Na plataforma Windows, você pode associar php.exe com o clique duplo em arquivos .php ou fazer um arquivo batch para rodar seus scripts através do PHP. A primeira linha acrescentada ao script nos Unix não funcionam no Windows, por isso você não pode escrever programas independentes de plataforma desse jeito. Um exemplo simples de como escrever um programa para a linha de comando segue abaixo:
Exemplo #1 Um script para rodar na linha de comando (script.php)
#!/usr/bin/php
<?php
if ($argc != 2 || in_array($argv[1], array('--help', '-help', '-h', '-?'))) {
?>
Este é um script de linha de comando com um parâmetro.
Uso:
<?php echo $argv[0]; ?> <opcao>
<opcao> pode ser qualquer palavra que
você queira imprimir. Com as opções --help, -help, -h
ou -?, você pode obter essa ajuda.
<?php
} else {
echo $argv[1];
}
?>
No script acima, nós utilizamos uma primeira linha especial para indicar que este arquivo precisa rodar pelo PHP. Como nós trabalhamos com a versão CLI aqui, não serão impressos headers HTTP. Há duas variáveis que você precisa conhecer para escrever aplicações em linha de comando com o PHP: $argc e $argv. O primeiro é o número de argumentos mais um (o nome do script executando). O segundo é um array contendo os argumentos, começando com o nome do script no índice zero ($argv[0]).
No programa acima é verificado se há apenas um argumento fornecido. Se o argumento for --help , -help , -h ou -? , é impresso uma mensagem de ajuda, imprimindo o nome do script dinamicamente. Qualquer outro argumento é exibido como informado.
Para rodar esse aplicativo nos Unix, basta torná-lo executável e o chamar diretamente como script.php exibaisso ou script.php -h. No Windows, você pode fazer um arquivo batch para esta tarefa:
Exemplo #2 Arquivo batch para rodar um script em linha de comando (script.bat)
@c:\php\cli\php.exe script.php %1 %2 %3 %4
Assumindo que você nomeou o programa acima como script.php, e que tem sua versão CLI php.exe em c:\php\cli\php.exe este arquivo batch irá rodar com os seguintes parâmetros: script.bat exibaisso ou script.bat -h.
Veja também a documentação da extensão Readline para mais funções que você pode usar para incrementar suas aplicações para linha de comando em PHP.
Garbage Collection
Índice
This section explains the merits of the new Garbage Collection (also known as GC) mechanism that is part of PHP 5.3.
Reference Counting Basics
A PHP variable is stored in a container called a "zval". A zval container contains, besides the variable's type and value, two additional bits of information. The first is called "is_ref" and is a boolean value indicating whether or not the variable is part of a "reference set". With this bit, PHP's engine knows how to differentiate between normal variables and references. Since PHP allows user-land references, as created by the & operator, a zval container also has an internal reference counting mechanism to optimize memory usage. This second piece of additional information, called "refcount", contains how many variable names (also called symbols) point to this one zval container. All symbols are stored in a symbol table, of which there is one per scope. There is a scope for the main script (i.e., the one requested through the browser), as well as one for every function or method.
A zval container is created when a new variable is created with a constant value, such as:
Exemplo #1 Creating a new zval container
<?php
$a = "new string";
?>
In this case, the new symbol name, a, is created in the current scope, and a new variable container is created with the type string and the value new string. The "is_ref" bit is by default set to FALSE because no user-land reference has been created. The "refcount" is set to 1 as there is only one symbol that makes use of this variable container. Note that if "refcount" is 1, "is_ref" is always FALSE. If you have » Xdebug installed, you can display this information by calling xdebug_debug_zval().
Exemplo #2 Displaying zval information
<?php
xdebug_debug_zval('a');
?>
O exemplo acima irá imprimir:
a: (refcount=1, is_ref=0)='new string'
Assigning this variable to another variable name will increase the refcount.
Exemplo #3 Increasing refcount of a zval
<?php
$a = "new string";
$b = $a;
xdebug_debug_zval( 'a' );
?>
O exemplo acima irá imprimir:
a: (refcount=2, is_ref=0)='new string'
The refcount is 2 here, because the same variable container is linked with both a and b. PHP is smart enough not to copy the actual variable container when it is not necessary. Variable containers get destroyed when the "refcount" reaches zero. The "refcount" gets decreased by one when any symbol linked to the variable container leaves the scope (e.g. when the function ends) or when unset() is called on a symbol. The following example shows this:
Exemplo #4 Decreasing zval refcount
<?php
$a = "new string";
$c = $b = $a;
xdebug_debug_zval( 'a' );
unset( $b, $c );
xdebug_debug_zval( 'a' );
?>
O exemplo acima irá imprimir:
a: (refcount=3, is_ref=0)='new string' a: (refcount=1, is_ref=0)='new string'
If we now call unset($a);, the variable container, including the type and value, will be removed from memory.
Compound Types
Things get a tad more complex with compound types such as arrays and objects. Instead of a scalar value, arrays and objects store their properties in a symbol table of their own. This means that the following example creates three zval containers:
Exemplo #5 Creating a array zval
<?php
$a = array( 'meaning' => 'life', 'number' => 42 );
xdebug_debug_zval( 'a' );
?>
O exemplo acima irá imprimir algo similar a:
a: (refcount=1, is_ref=0)=array ( 'meaning' => (refcount=1, is_ref=0)='life', 'number' => (refcount=1, is_ref=0)=42 )
Or graphically
The three zval containers are: a, meaning, and number. Similar rules apply for increasing and decreasing "refcounts". Below, we add another element to the array, and set its value to the contents of an already existing element:
Exemplo #6 Adding already existing element to an array
<?php
$a = array( 'meaning' => 'life', 'number' => 42 );
$a['life'] = $a['meaning'];
xdebug_debug_zval( 'a' );
?>
O exemplo acima irá imprimir algo similar a:
a: (refcount=1, is_ref=0)=array ( 'meaning' => (refcount=2, is_ref=0)='life', 'number' => (refcount=1, is_ref=0)=42, 'life' => (refcount=2, is_ref=0)='life' )
Or graphically
From the above Xdebug output, we see that both the old and new array elements now point to a zval container whose "refcount" is 2. Although Xdebug's output shows two zval containers with value 'life', they are the same one. The xdebug_debug_zval() function does not show this, but you could see it by also displaying the memory pointer.
Removing an element from the array is like removing a symbol from a scope. By doing so, the "refcount" of a container that an array element points to is decreased. Again, when the "refcount" reaches zero, the variable container is removed from memory. Again, an example to show this:
Exemplo #7 Removing an element from an array
<?php
$a = array( 'meaning' => 'life', 'number' => 42 );
$a['life'] = $a['meaning'];
unset( $a['meaning'], $a['number'] );
xdebug_debug_zval( 'a' );
?>
O exemplo acima irá imprimir algo similar a:
a: (refcount=1, is_ref=0)=array ( 'life' => (refcount=1, is_ref=0)='life' )
Now, things get interesting if we add the array itself as an element of the array, which we do in the next example, in which we also sneak in a reference operator, since otherwise PHP would create a copy:
Exemplo #8 Adding the array itself as an element of it self
<?php
$a = array( 'one' );
$a[] =& $a;
xdebug_debug_zval( 'a' );
?>
O exemplo acima irá imprimir algo similar a:
a: (refcount=2, is_ref=1)=array ( 0 => (refcount=1, is_ref=0)='one', 1 => (refcount=2, is_ref=1)=... )
Or graphically
You can see that the array variable (a) as well as the second element (1) now point to a variable container that has a "refcount" of 2. The "..." in the display above shows that there is recursion involved, which, of course, in this case means that the "..." points back to the original array.
Just like before, unsetting a variable removes the symbol, and the reference count of the variable container it points to is decreased by one. So, if we unset variable $a after running the above code, the reference count of the variable container that $a and element "1" point to gets decreased by one, from "2" to "1". This can be represented as:
Exemplo #9 Unsetting $a
(refcount=1, is_ref=1)=array ( 0 => (refcount=1, is_ref=0)='one', 1 => (refcount=1, is_ref=1)=... )
Or graphically
Cleanup Problems
Although there is no longer a symbol in any scope pointing to this structure, it cannot be cleaned up because the array element "1" still points to this same array. Because there is no external symbol pointing to it, there is no way for a user to clean up this structure; thus you get a memory leak. Fortunately, PHP will clean up this data structure at the end of the request, but before then, this is taking up valuable space in memory. This situation happens often if you're implementing parsing algorithms or other things where you have a child point back at a "parent" element. The same situation can also happen with objects of course, where it actually is more likely to occur, as objects are always implicitly used by reference.
This might not be a problem if this only happens once or twice, but if there are thousands, or even millions, of these memory losses, this obviously starts being a problem. This is especially problematic in long running scripts, such as daemons where the request basically never ends, or in large sets of unit tests. The latter caused problems while running the unit tests for the Template component of the eZ Components library. In some cases, it would require over 2 GB of memory, which the test server didn't quite have.
Collecting Cycles
Traditionally, reference counting memory mechanisms, such as that used previously by PHP, fail to address circular reference memory leaks. As of 5.3.0 PHP however implements the synchronous algorithm from the » Concurrent Cycle Collection in Reference Counted Systems paper which addresses that issue.
A full explanation of how the algorithm works would be slightly beyond the scope of this section, but the basics are explained here. First of all, we have to establish a few ground rules. If a refcount is increased, it's still in use and therefore, not garbage. If the refcount is decreased and hits zero, the zval can be freed. This means that garbage cycles can only be created when a refcount argument is decreased to a non-zero value. Secondly, in a garbage cycle, it is possible to discover which parts are garbage by checking whether it is possible to decrease their refcount by one, and then checking which of the zvals have a refcount of zero.
To avoid having to call the checking of garbage cycles with every possible decrease of a refcount, the algorithm instead puts all possible roots (zvals) in the "root buffer" (marking them "purple"). It also makes sure that each possible garbage root ends up in the buffer only once. Only when the root buffer is full does the collection mechanism start for all the different zvals inside. See step A in the figure above.
In step B, the algorithm runs a depth-first search on all possible roots to decrease by one the refcounts of each zval it finds, making sure not to decrease a refcount on the same zval twice (by marking them as "grey"). In step C, the algorithm again runs a depth-first search from each root node, to check the refcount of each zval again. If it finds that the refcount is zero, the zval is marked "white" (blue in the figure). If it's larger than zero, it reverts the decreasing of the refcount by one with a depth-first search from that point on, and they are marked "black" again. In the last step (D), the algorithm walks over the root buffer removing the zval roots from there, and meanwhile, checks which zvals have been marked "white" in the previous step. Every zval marked as "white" will be freed.
Now that you have a basic understanding of how the algorithm works, we will look back at how this integrates with PHP. By default, PHP's garbage collector is turned on. There is, however, a php.ini setting that allows you to change this: zend.enable_gc .
When the garbage collector is turned on, the cycle-finding algorithm as described above is executed whenever the root buffer runs full. The root buffer has a fixed size of 10,000 possible roots (although you can alter this by changing the GC_ROOT_BUFFER_MAX_ENTRIES constant in Zend/zend_gc.c in the PHP source code, and re-compiling PHP). When the garbage collector is turned off, the cycle-finding algorithm will never run. However, possible roots will always be recorded in the root buffer, no matter whether the garbage collection mechanism has been activated with this configuration setting.
If the root buffer becomes full with possible roots while the garbage collection mechanism is turned off, further possible roots will simply not be recorded. Those possible roots that are not recorded will never be analyzed by the algorithm. If they were part of a circular reference cycle, they would never be cleaned up and would create a memory leak.
The reason why possible roots are recorded even if the mechanism has been disabled is because it's faster to record possible roots than to have to check whether the mechanism is turned on every time a possible root could be found. The garbage collection and analysis mechanism itself, however, can take a considerable amount of time.
Besides changing the zend.enable_gc configuration setting, it is also possible to turn the garbage collecting mechanism on and off by calling gc_enable() or gc_disable() respectively. Calling those functions has the same effect as turning on or off the mechanism with the configuration setting. It is also possible to force the collection of cycles even if the possible root buffer is not full yet. For this, you can use the gc_collect_cycles() function. This function will return how many cycles were collected by the algorithm.
The rationale behind the ability to turn the mechanism on and off, and to initiate cycle collection yourself, is that some parts of your application could be highly time-sensitive. In those cases, you might not want the garbage collection mechanism to kick in. Of course, by turning off the garbage collection for certain parts of your application, you do risk creating memory leaks because some possible roots might not fit into the limited root buffer. Therefore, it is probably wise to call gc_collect_cycles() just before you call gc_disable() to free up the memory that could be lost through possible roots that are already recorded in the root buffer. This then leaves an empty buffer so that there is more space for storing possible roots while the cycle collecting mechanism is turned off.
Performance Considerations
We have already mentioned in the previous section that simply collecting the possible roots had a very tiny performance impact, but this is when you compare PHP 5.2 against PHP 5.3. Although the recording of possible roots compared to not recording them at all, like in PHP 5.2, is slower, other changes to the PHP runtime in PHP 5.3 prevented this particular performance loss from even showing.
There are two major areas in which performance is affected. The first area is reduced memory usage, and the second area is run-time delay when the garbage collection mechanism performs its memory cleanups. We will look at both of those issues.
Reduced Memory Usage
First of all, the whole reason for implementing the garbage collection mechanism is to reduce memory usage by cleaning up circular-referenced variables as soon as the prerequisites are fulfilled. In PHP's implementation, this happens as soon as the root-buffer is full, or when the function gc_collect_cycles() is called. In the graph below, we display the memory usage of the script below, in both PHP 5.2 and PHP 5.3, excluding the base memory that PHP itself uses when starting up.
Exemplo #1 Memory usage example
<?php
class Foo
{
public $var = '3.1415962654';
}
$baseMemory = memory_get_usage();
for ( $i = 0; $i <= 100000; $i++ )
{
$a = new Foo;
$a->self = $a;
if ( $i % 500 === 0 )
{
echo sprintf( '%8d: ', $i ), memory_get_usage() - $baseMemory, "\n";
}
}
?>
In this very academic example, we are creating an object in which a property is set to point back to the object itself. When the $a variable in the script is re-assigned in the next iteration of the loop, a memory leak would typically occur. In this case, two zval-containers are leaked (the object zval, and the property zval), but only one possible root is found: the variable that was unset. When the root-buffer is full after 10,000 iterations (with a total of 10,000 possible roots), the garbage collection mechanism kicks in and frees the memory associated with those possible roots. This can very clearly be seen in the jagged memory-usage graph for PHP 5.3. After each 10,000 iterations, the mechanism kicks in and frees the memory associated with the circular referenced variables. The mechanism itself does not have to do a whole lot of work in this example, because the structure that is leaked is extremely simple. From the diagram, you see that the maximum memory usage in PHP 5.3 is about 9 Mb, whereas in PHP 5.2 the memory usage keeps increasing.
Run-Time Slowdowns
The second area where the garbage collection mechanism influences performance is the time taken when the garbage collection mechanism kicks in to free the "leaked" memory. In order to see how much this is, we slightly modify the previous script to allow for a larger number of iterations and the removal of the intermediate memory usage figures. The second script is here:
Exemplo #2 GC performance influences
<?php
class Foo
{
public $var = '3.1415962654';
}
for ( $i = 0; $i <= 1000000; $i++ )
{
$a = new Foo;
$a->self = $a;
}
echo memory_get_peak_usage(), "\n";
?>
We will run this script two times, once with the zend.enable_gc setting turned on, and once with it turned off:
Exemplo #3 Running the above script
time php -dzend.enable_gc=0 -dmemory_limit=-1 -n example2.php # and time php -dzend.enable_gc=1 -dmemory_limit=-1 -n example2.php
On my machine, the first command seems to take consistently about 10.7 seconds, whereas the second command takes about 11.4 seconds. This is a slowdown of about 7%. However, the maximum amount of memory used by the script is reduced by 98% from 931Mb to 10Mb. This benchmark is not very scientific, or even representative of real-life applications, but it does demonstrate the memory usage benefits that this garbage collection mechanism provides. The good thing is that the slowdown is always the same 7%, for this particular script, while the memory saving capabilities save more and more memory as more circular references are found during script execution.
PHP's Internal GC Statistics
It is possible to coax a little bit more information about how the garbage collection mechanism is run from within PHP. But in order to do so, you will have to re-compile PHP to enable the benchmark and data-collecting code. You will have to set the CFLAGS environment variable to -DGC_BENCH=1 prior to running ./configure with your desired options. The following sequence should do the trick:
Exemplo #4 Recompiling PHP to enable GC benchmarking
export CFLAGS=-DGC_BENCH=1 ./config.nice make clean make
When you run the above example code again with the newly built PHP binary, you will see the following being shown after PHP has finished execution:
Exemplo #5 GC statistics
GC Statistics
-------------
Runs: 110
Collected: 2072204
Root buffer length: 0
Root buffer peak: 10000
Possible Remove from Marked
Root Buffered buffer grey
-------- -------- ----------- ------
ZVAL 7175487 1491291 1241690 3611871
ZOBJ 28506264 1527980 677581 1025731
The most informative statistics are displayed in the first block. You can see here that the garbage collection mechanism ran 110 times, and in total, more than 2 million memory allocations were freed during those 110 runs. As soon as the garbage collection mechanism has run at least one time, the "Root buffer peak" is always 10000.
Conclusion
In general the garbage collector in PHP will only cause a slowdown when the cycle collecting algorithm actually runs, whereas in normal (smaller) scripts there should be no performance hit at all.
However, in the cases where the cycle collection mechanism does run for normal scripts, the memory reduction it will provide allows more of those scripts to run concurrently on your server, since not so much memory is used in total.
The benefits are most apparent for longer-running scripts, such as lengthy test suites or daemon scripts. Also, for » PHP-GTK applications that generally tend to run longer than scripts for the Web, the new mechanism should make quite a bit of a difference regarding memory leaks creeping in over time.
Referência das Funções
Veja também Categorização/Lista das Extensões.
Afetando o comportamento do PHP
Alternative PHP Cache
Introdução
O Cache Alternativo do PHP (APC) é um cache livre e aberto para o PHP. Foi desenvolvido para prover um framework livre, aberto e robusto para cache e otimização do código intermediário do PHP.
Instalação/Configuração
Índice
Dependências
Nenhuma biblioteca externa é necessária para compilar esta extensão.
Instalação
Esta extensão » PECL não vem compilada com o PHP.
Informações para a instalação desta extensão PECL podem ser encontradas no manual no capitulo intitulado Instalação de extensões PECL. Informações adicionais como novas versões, downloads, arquivos fontes, manutenções, e um Changelog, podem ser obtidos aqui: » http://pecl.php.net/package/apc.
Uma DLL para esta extenção PECL esta atualmente indisponível. Veja também a seção compilando no Windows section.
Nota: No Windows, APC necessita que um diretório temporário exista, e o web server possa escrever. Ele verifica as variáveis de ambiente TMP, TEMP, USERPROFILE nessa ordem e, no final, tenta o diretório WINDOWS se nenhum deles estiver configurado.
Nota: Para detalhes de implementação mais aprofundados, veja o » arquivo de notas técnicas fornecida pelo desenvolvedor .
Configurações em Execução
O comportamento dessas funções podem ser modificado pelas configurações do php.ini.
Embora as configurações padrões do APC são suficientes para muitas instalações, usuários sérios devem considerar alterar os seguintes parâmetros.
São duas decisões principais que você deve fazer. A primeira, a quantidade de memória compartilhada que você quer alocar para o APC, e a segunda, se você quer que o APC verifique se um arquivo foi modificado em cada requisição. As duas diretivas do arquivo php.ini envolvidas aqui são apc.shm_size e apc.stat. Leia as seções sobre essas duas diretivas com muita atenção.
Uma vez que você tiver um servidor operando, você deve copiar o script apc.php que vem com a extensão para algum lugar no seu DocumentRoot e carregue-o no seu navegador. Ele fornece uma visão detalhada sobre o que está acontecendo com o cache. Se você tiver a extensão GD habilitada no PHP, ele até gerará gráficos bonitinhos. Primeira coisa a ser verificada é se ele está de fato cacheando arquivos. Presumindo que está funcionando, você deve prestar atenção para o número Cache full count na esquerda. Isso te diz o número de vezes que o cache foi preenchido e precisou limpar à força todas as entradas que não foram acessados nos últimos segundos. O tempo varia dependendo da diretiva apc.ttl. Você deve configurar seu cache para minimizar esse número. Se você estiver com o cache cheio constantemente, o resultado disso afetará a performance. Você deve ou alocar mais memória para o APC ou usar os filtros (apc.filters) para cachear menos scripts.
| Nome | Valor Padrão | Alterável | Changelog |
|---|---|---|---|
| apc.enabled | "1" | PHP_INI_SYSTEM | PHP_INI_SYSTEM no APC 2. PHP_INI_ALL no APC <= 3.0.12. |
| apc.shm_segments | "1" | PHP_INI_SYSTEM | |
| apc.shm_size | "30" | PHP_INI_SYSTEM | |
| apc.optimization | "0" | PHP_INI_ALL | PHP_INI_SYSTEM no APC 2. Removido no APC 3.0.13. |
| apc.num_files_hint | "1000" | PHP_INI_SYSTEM | |
| apc.user_entries_hint | "4096" | PHP_INI_SYSTEM | Disponível desde o APC 3.0.0. |
| apc.ttl | "0" | PHP_INI_SYSTEM | Disponível desde o APC 3.0.0. |
| apc.user_ttl | "0" | PHP_INI_SYSTEM | Disponível desde o APC 3.0.0. |
| apc.gc_ttl | "3600" | PHP_INI_SYSTEM | |
| apc.cache_by_default | "1" | PHP_INI_ALL | PHP_INI_SYSTEM no APC <= 3.0.12p. Disponível desde o APC 3.0.0. |
| apc.filters | NULL | PHP_INI_SYSTEM | |
| apc.mmap_file_mask | NULL | PHP_INI_SYSTEM | |
| apc.slam_defense | "0" | PHP_INI_SYSTEM | Disponível desde o APC 3.0.0. |
| apc.file_update_protection | "2" | PHP_INI_SYSTEM | Disponível desde o APC 3.0.6. |
| apc.enable_cli | "0" | PHP_INI_SYSTEM | Disponível desde o APC 3.0.7. |
| apc.max_file_size | "1M" | PHP_INI_SYSTEM | Disponível desde o APC 3.0.7. |
| apc.stat | "1" | PHP_INI_SYSTEM | Disponível desde o APC 3.0.10. |
| apc.write_lock | "1" | PHP_INI_SYSTEM | Disponível desde o APC 3.0.11. |
| apc.report_autofilter | "0" | PHP_INI_SYSTEM | Disponível desde o APC 3.0.11. |
| apc.include_once_override | "0" | PHP_INI_SYSTEM | Disponível desde o APC 3.0.12. |
| apc.rfc1867 | "0" | PHP_INI_SYSTEM | Disponível desde o APC 3.0.13. |
| apc.rfc1867_prefix | "upload_" | PHP_INI_SYSTEM | |
| apc.rfc1867_name | "APC_UPLOAD_PROGRESS" | PHP_INI_SYSTEM | |
| apc.rfc1867_freq | "0" | PHP_INI_SYSTEM | |
| apc.localcache | "0" | PHP_INI_SYSTEM | Disponível desde o APC 3.0.14. |
| apc.localcache.size | "512" | PHP_INI_SYSTEM | Disponível desde o APC 3.0.14. |
Breve descrição das diretivas de configuração.
- apc.enabled boolean
-
apc.enabled pode ser configurado para 0 para desabilitar APC. Isso é primeiramente útil quando APC for compilado estaticamente no PHP, já que não existe outra maneira de desabilitá-lo (quando compilado como um DSO, a linha extension do arquivo php.ini pode ser comentada).
- apc.shm_segments integer
-
O número de segmentos de memória compartilhada para alocar para o cache do compilador. Se APC estiver ficando sem memória compartilhada mas você já configurou apc.shm_size para o valor mais alto que seu sistema permite, tente aumentar esse valor.
- apc.shm_size integer
-
O tamanho de cada segmento de memória compartilhado em MB. Por padrão, alguns sistemas (incluindo a maioria dos BSDs) tem limites muito baixos no tamanho de um segmento de memória compartilhada.
- apc.optimization integer
-
O nível de otimização. Zero disabilita o otimizador, e valores mais algos usam otimizações mais agressivas. Espere melhoras muito modestas de velocidade. Isso é experimental.
- apc.num_files_hint integer
-
Uma "dica" sobra o número de arquivos-fonte distintos serão incluídos ou requisitados no seu servidor web. Configura para zero ou omita o valor se não tiver certeza; Essa configuração é útil principalmente para sites que tem milhares de arquivos-fonte.
- apc.user_entries_hint integer
-
Assim como apc.num_files_hint, dá uma "dica" sobre o número de variáveis de usuários distintos são armazenados. Dê o valor zero ou omit se não tiver certeza.
- apc.ttl integer
-
O número de segundos que uma entrada no cache é permitida a ficar ociosa em uma posição, caso essa posição for necessária para outra entrada. Deixando o valor zero significa que o cache pode potencialmente encher de entradas paradas enquanto novas entradas não serão guardadas.
- apc.user_ttl integer
-
O número de segundos que uma entrada de cache do usuário fica ociosa em cache se a posição que ele está ocupando for necessária. Atribuir zero significa que seu cache pode, potencialmente, ficar cheio de entradas não usadas enquanto novas entradas não serão guardadas.
- apc.gc_ttl integer
-
O número de segundos que uma entrada do cache pode ficar na lista do coletor de lixo (garbage-collection). Esse valor prove uma segurança caso um processo do servidor morra enquanto executando um arquivo-fonte cacheado; Se o arquivo-fonte for modificado, a memória alocada para a versão antiga não será reclamada até que TTL seja alcançado. Configure para zero para desabilitar essa funcionalidade.
- apc.cache_by_default boolean
-
Ligado por padrão, mas pode ser desligado e usado em conjunto com apc.filters positivos para que arquivos só sejam guardados se validados por um filtro positivo.
- apc.filters string
-
Uma lista separada por vírgulas de expressões regulares extendidas POSIX. Se qualquer padrão bater com o nome do arquivo-fonte, o arquivo não será guardado. Perceba que o nome de arquivo usado para comparação é o que é passado para a include/require, não o caminho absoluto. Se o primeiro caracter da expressão é um +, então a expressão será aditiva no sentido que quaisquer arquivos que baterem com a expressão serão guardados, e se o primeiro caracter for -, então qualquer arquivo que não bater com o padrão não será guardado. O caso - é o padrão, então pode ser deixado de fora.
- apc.mmap_file_mask string
-
Se compilado com suporte à MMAP usando --enable-mmap essa é a máscara de arquivo em estilo mktemp a ser passada para o módulo mmap para determinar se sua região mapeada de memória será guardada em arquivo ou memória compartilhada. Para guardar em arquivo, configure para um valor como /tmp/apc.XXXXXX (exatamente 6 Xs). Para usar shm_open/mmap no estilo POSIX ponha um .shm em algum lugar da sua máscara. Por exemplo, /apc.shm.XXXXXX Você também pode configura para /dev/zero usar a interface /dev/zero do kernel para memória mapeada de forma anônima. Deixar em branco forçará mapeamento anônimo.
- apc.slam_defense integer
-
Em servidores muito ocupados sempre que você inicializar o servidor ou modificar arquivos, você pode criar uma "race condition" de muitos processos todos tentando guardar o mesmo arquivo ao mesmo tempo. Essa opção configura a percentagem de processos que não tentarão guardar um arquivo que ainda não esteja no cache. Ou pense como sendo a probabilidade de um único processo não guardar o arquivo. Por exemplo, configurar apc.slam_defense para 75 significaria que existe uma chance de 75% que o processo não guardará um arquivo em cache. Então, quanto maior o valor, maior a defesa contra uma "race condition". Configurando isso para 0 desabilita essa funcionalidade.
Obsoleto por apc.write_lock.
- apc.file_update_protection integer
-
Quando você modifica um arquivo em um servidor web, você realmente devia fazê-lo de uma maneira atômica. Isso é, escreva para um arquivo temporário e renomeie o arquivo (mv) para sua posição permanente quando estiver pronto. Muito editores de texto, cp, tar e outros programas não fazem isso. Isso significa que existe uma chance de que um arquivo é acessado (e guardado em cache) enquanto ele ainda está sendo escrito. Essa configuração apc.file_update_protection coloca um atraso ao fazer o cache de arquivos recém-criados. O valor padrão é 2 segundos, o que significa que se o horário de modificação do arquivo (mtime) tiver menos do que 2 segundos de diferença do tempo atual, ele não será guarado. O infeliz que acessar esse arquivo incompleto ainda verá coisas estranhas, mas pelo menos não persistirá. Se você tiver certeza que você sempre atualiza seus arquivos atomicamente usando algo como rsync que faz isso corretamente, você pode desligar essa proteção ao atribuir o valor de 0. Se você tiver um sistema que é carregado com IO, csuando algum procedimento de atualização que leva mais do que dois segundos, você pode querer aumentar esse valor um pouco.
- apc.enable_cli integer
-
Principalmente para teste e depuração. Ligando essa diretiva habilita o APC para a versão CLI do PHP. Normalmente você não iria querer criar, popular e destrui o cache do APC a cada requisição CLI, mas em vários cenários de teste isso é muito útil ser capaz de habilitar APC para a versão CLI facilmente.
- apc.max_file_size integer
-
Previne que arquivos maiores que esse valor sejam cacheados. O padrão é 1M.
- apc.stat integer
-
Tenha cuidado ao mudar essa configuração. O padrão para ela é On (ligado) o que significa que APC verificará o script em cada requisição para certificar-se que ele não foi modificado. Se ele foi modificado, ele recompilará e cacheará a nova versão. Se você desligar essa configuração, essa verificação não será feita. Isso significa que para que mudanças sejam ativadas, você precisará reiniciar o seu servidor web. Em um servidor de produção, onde você raramente modifica o código, desligar essa configuração pode significar um aumento de performance.
Essa opção aplica-se também para arquivos requeridos ou incluídos, mas perceba que se você estiver usando caminhos relativos para os includes (qualquer caminho que não começa com / no Unix ), o APC precisa chegar para indentificar univocamente o arquivo. Se você usar o caminho absoluto, o APC pode pular o teste e usar o caminho absoluto como identificador único do arquivo.
- apc.write_lock boolean
-
Em servidores muito ocupados, quando você inicializa o servidor, ou quando muitos arquivos são modificados, você pode acabar com todos os processos tentando compilar e cachear os mesmos arquivos. Com write_lock habilitado, apenas um processo por vez tentará compilar um script não cacheado enquanto os outros processos executarão sem cache, ao invés de esperar por sua vez para poder escrever o arquivo.
- apc.report_autofilter boolean
-
Registra qualquer script que são excluídos automaticamente do cache por problemas de binding prévio ou tardio.
- apc.include_once_override boolean
-
Otimiza chamadas à include_once() e require_once() e evita o custo das chamadas de sistema usadas.
- apc.rfc1867 boolean
-
RFC1867 File Upload Progress só está disponível se você compilou o APC com o PHP 5.2.0 ou posterior. Quando habilitado, qualquer upload de arquivo que inclui um campo chamado APC_UPLOAD_PROGRESS antes do campo arquivo em um formulário de upload fará com que o APC crie uma entrada no cache upload_key onde key é o valor da entrada APC_UPLOAD_PROGRESS do formulário.
Perceba que o rastrear uploads de arquivos não é threadsafe até agora, então novos uploads que acontecem enquanto um anterior ainda está sendo executado desabilitará o rastreamento do anterior.
Exemplo #1 An apc.rfc1867 example
<?php
print_r(apc_fetch("upload_$_POST[APC_UPLOAD_PROGRESS]"));
?>O exemplo acima irá imprimir algo similar a:
Array ( [total] => 1142543 [current] => 1142543 [rate] => 1828068.8 [filename] => test [name] => file [temp_filename] => /tmp/php8F [cancel_upload] => 0 [done] => 1 ) - apc.rfc1867_prefix string
-
Chave do prefixo para usar por entrada de cache do usuário gerado pela funcionalidade de progresso de upload rfc1867.
- apc.rfc1867_name string
-
Especifica o escondido nome de entrada de formulário que ativa o progresso de upload do APC e especifica o sufixo da chave de cache do usuário.
- apc.rfc1867_freq string
-
A freqüência de atualização que deve ser feita para a entrada de cache do usuário para o progresso do upload. Isto pode ser obtido do formulário de uma porcentagem do total do tamanho do arquivo em bytes opcionalmente sufixado com 'k', 'm', ou 'g' por kilobytes, megabytes, ou gigabytes respectivamente (case insensitive). Definindo para 0 atualizações serão feitas sempre que possível, que pode causar lentidão no upload.
- apc.localcache boolean
-
Isso permite um shadow-cache sem lock no processo local que reduz contenção de locks quando o cache está sendo escrito.
- apc.localcache.size integer
-
O tamanho do shadow-cache do processo local, deve ser um valor suficientemente grande, aproximadamente metade de apc.num_files_hint.
Tipos Resource
Esta extensão não possui nenhum tipo resource.
Constantes pré-definidas
Esta extensão não possui nenhuma constante.
APC Funções
apc_add
(PECL apc >= 3.0.13)
apc_add — Cache a variable in the data store
Descrição
Caches a variable in the data store, only if it's not already stored.
Nota: Unlike many other mechanisms in PHP, variables stored using apc_add() will persist between requests (until the value is removed from the cache).
Parâmetros
- key
-
Store the variable using this name. keys are cache-unique, so attempting to use apc_add() to store data with a key that already exists will not overwrite the existing data, and will instead return FALSE. (This is the only difference between apc_add() and apc_store().)
- var
-
The variable to store
- ttl
-
Time To Live; store var in the cache for ttl seconds. After the ttl has passed, the stored variable will be expunged from the cache (on the next request). If no ttl is supplied (or if the ttl is 0), the value will persist until it is removed from the cache manually, or otherwise fails to exist in the cache (clear, restart, etc.).
- values
-
Names in key, variables in value.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas. Second syntax returns array with error keys.
Exemplos
Exemplo #1 A apc_add() example
<?php
$bar = 'BAR';
apc_add('foo', $bar);
var_dump(apc_fetch('foo'));
echo "\n";
$bar = 'NEVER GETS SET';
apc_add('foo', $bar);
var_dump(apc_fetch('foo'));
echo "\n";
?>
O exemplo acima irá imprimir:
string(3) "BAR" string(3) "BAR"
Veja Também
- apc_store() - Guarda uma variável no cache
- apc_fetch() - Retorna uma variável guardado do cache
- apc_delete() - Remove uma variável guardado no cache.
apc_bin_dump
(PECL apc >= 3.1.4)
apc_bin_dump — Get a binary dump of the given files and user variables
Descrição
Returns a binary dump of the given files and user variables from the APC cache. A NULL for files or user_vars signals a dump of every entry, whereas array() will dump nothing.
Parâmetros
Valor Retornado
Returns a binary dump of the given files and user variables from the APC cache, FALSE if APC is not enabled, or NULL if an unknown error is encountered.
Veja Também
- apc_bin_dumpfile() - Output a binary dump of cached files and user variables to a file
- apc_bin_load() - Load a binary dump into the APC file/user cache
apc_bin_dumpfile
(PECL apc >= 3.1.4)
apc_bin_dumpfile — Output a binary dump of cached files and user variables to a file
Descrição
Outputs a binary dump of the given files and user variables from the APC cache to the named file.
Parâmetros
- files
-
The file names being dumped.
- user_vars
-
The user variables being dumped.
- filename
-
The filename where the dump is being saved.
- flags
-
Flags passed to the filename stream. See the file_put_contents() documentation for details.
- context
-
The context passed to the filename stream. See the file_put_contents() documentation for details.
Valor Retornado
The number of bytes written to the file, otherwise FALSE if APC is not enabled, filename is an invalid file name, filename can't be opened, the file dump can't be completed (e.g., the hard drive is out of disk space), or an unknown error was encountered.
Veja Também
- apc_bin_dump() - Get a binary dump of the given files and user variables
- apc_bin_load() - Load a binary dump into the APC file/user cache
apc_bin_load
(PECL apc >= 3.1.4)
apc_bin_load — Load a binary dump into the APC file/user cache
Descrição
Loads the given binary dump into the APC file/user cache.
Parâmetros
- data
-
The binary dump being loaded, likely from apc_bin_dump().
- flags
-
Either APC_BIN_VERIFY_CRC32, APC_BIN_VERIFY_MD5, or both.
Valor Retornado
Returns TRUE if the binary dump data was loaded with success, otherwise FALSE is returned. FALSE is returned if APC is not enabled, or if the data is not a valid APC binary dump (e.g., unexpected size).
Exemplos
Exemplo #1 apc_bin_load() example
<?php
$data = apc_bin_dump(NULL, NULL);
apc_bin_load($data, APC_BIN_VERIFY_MD5 | APC_BIN_VERIFY_CRC32);
?>
Veja Também
- apc_bin_dump() - Get a binary dump of the given files and user variables
- apc_bin_loadfile() - Load a binary dump from a file into the APC file/user cache
apc_bin_loadfile
(PECL apc >= 3.1.4)
apc_bin_loadfile — Load a binary dump from a file into the APC file/user cache
Descrição
Loads a binary dump from a file into the APC file/user cache.
Parâmetros
- filename
-
The file name containing the dump, likely from apc_bin_dumpfile().
- context
-
The files context.
- flags
-
Either APC_BIN_VERIFY_CRC32, APC_BIN_VERIFY_MD5, or both.
Valor Retornado
Returns TRUE on success, otherwise FALSE Reasons it may return FALSE include APC is not enabled, filename is an invalid file name or empty, filename can't be opened, the file dump can't be completed, or if the data is not a valid APC binary dump (e.g., unexpected size).
Veja Também
- apc_bin_dumpfile() - Output a binary dump of cached files and user variables to a file
- apc_bin_load() - Load a binary dump into the APC file/user cache
apc_cache_info
(PECL apc >= 2.0.0)
apc_cache_info — Retorna informação guardada (e meta-dados) de registros do APC
Descrição
Recupera informação do cache e meta-data de dados armazenado do APC.
Valor Retornado
Array de dados guardados (e meta-dados), ou FALSE em caso de falha
Nota: apc_cache_info() lançará um aviso se for incapaz de retorna os dados guardados. Isso tipicamente acontece quando APC não estiver habilitado.
Parâmetros
- cache_type
-
Se cache_type for "user", informações sobre o cache do usuário será retornado.
Se cache_type é "filehits", informação sobre quais arquivos estão sendo servidos do cache de bytecode para a requisição atual será retornada. Este recurso precisa ser habilitado na compilação usando --enable-filehits .
Se cache_type é inválido ou não é especificado, informação sobre o sistema de cache (arquivos em cache) será retornada.
- limited
-
Se limited tiver valor TRUE, o valor retornado excluirá a lista individual de entradas do cache. Isso é útil quando estiver tentando otimizar chamadas para obter estatísiticas.
Histórico
| Versão | Descrição |
|---|---|
| 3.0.11 | O parâmetro limited foi introduzido. |
| 3.0.16 | A opção "filehits" para o parâmetro cache_type foi introduzida. |
Exemplos
Exemplo #1 Um exemplo de apc_cache_info()
<?php
print_r(apc_cache_info());
?>
O exemplo acima irá imprimir algo similar a:
Array
(
[num_slots] => 2000
[ttl] => 0
[num_hits] => 9
[num_misses] => 3
[start_time] => 1123958803
[cache_list] => Array
(
[0] => Array
(
[filename] => /path/to/apc_test.php
[device] => 29954
[inode] => 1130511
[type] => file
[num_hits] => 1
[mtime] => 1123960686
[creation_time] => 1123960696
[deletion_time] => 0
[access_time] => 1123962864
[ref_count] => 1
[mem_size] => 677
)
[1] => Array (...iterates for each cached file)
)
apc_cas
(PECL apc >= 3.1.1)
apc_cas — Updates an old value with a new value
Descrição
apc_cas() updates an already existing integer value if the old parameter matches the currently stored value with the value of the new parameter.
Parâmetros
- key
-
The key of the value being updated.
- old
-
The old value (the value currently stored).
- new
-
The new value to update to.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 apc_cas() example
<?php
apc_store('foobar', 2);
echo '$foobar = 2', PHP_EOL;
echo '$foobar == 1 ? 2 : 1 = ', (apc_cas('foobar', 1, 2) ? 'ok' : 'fail'), PHP_EOL;
echo '$foobar == 2 ? 1 : 2 = ', (apc_cas('foobar', 2, 1) ? 'ok' : 'fail'), PHP_EOL;
echo '$foobar = ', apc_fetch('foobar'), PHP_EOL;
echo '$f__bar == 1 ? 2 : 1 = ', (apc_cas('f__bar', 1, 2) ? 'ok' : 'fail'), PHP_EOL;
apc_store('perfection', 'xyz');
echo '$perfection == 2 ? 1 : 2 = ', (apc_cas('perfection', 2, 1) ? 'ok' : 'epic fail'), PHP_EOL;
echo '$foobar = ', apc_fetch('foobar'), PHP_EOL;
?>
O exemplo acima irá imprimir algo similar a:
$foobar = 2 $foobar == 1 ? 2 : 1 = fail $foobar == 2 ? 1 : 2 = ok $foobar = 1 $f__bar == 1 ? 2 : 1 = fail $perfection == 2 ? 1 : 2 = epic fail $foobar = 1
Veja Também
- apc_dec() - Decrease a stored number
- apc_store() - Guarda uma variável no cache
apc_clear_cache
(PECL apc >= 2.0.0)
apc_clear_cache — Limpa o cache do APC.
Descrição
Limpa o cache do usuário/sistema.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Parâmetros
- cache_type
-
Se cache_type for "user", o cache do usuário será limpado; caso contrário, o sistema de cache (arquivos cacheados) será limpo.
apc_compile_file
(PECL apc >= 3.0.13)
apc_compile_file — Stores a file in the bytecode cache, bypassing all filters.
Descrição
Stores a file in the bytecode cache, bypassing all filters.
Parâmetros
- filename
-
Full or relative path to a PHP file that will be compiled and stored in the bytecode cache.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Veja Também
- apc_bin_dumpfile() - Output a binary dump of cached files and user variables to a file
- apc_bin_loadfile() - Load a binary dump from a file into the APC file/user cache
apc_dec
(PECL apc >= 3.1.1)
apc_dec — Decrease a stored number
Descrição
Decreases a stored integer value.
Parâmetros
- key
-
The key of the value being decreased.
- step
-
The step, or value to decrease.
- success
-
Optionally pass the success or fail boolean value to this referenced variable.
Valor Retornado
Returns the current value of key's value on success, or FALSE on failure
Exemplos
Exemplo #1 apc_dec() example
<?php
echo "Let's do something with success", PHP_EOL;
apc_store('anumber', 42);
echo apc_fetch('anumber'), PHP_EOL;
echo apc_dec('anumber'), PHP_EOL;
echo apc_dec('anumber', 10), PHP_EOL;
echo apc_dec('anumber', 10, $success), PHP_EOL;
var_dump($success);
echo "Now, let's fail", PHP_EOL, PHP_EOL;
apc_store('astring', 'foo');
$ret = apc_dec('astring', 1, $fail);
var_dump($ret);
var_dump($fail);
?>
O exemplo acima irá imprimir algo similar a:
Let's do something with success 42 41 31 21 bool(true) Now, let's fail bool(false) bool(false)
Veja Também
- apc_inc() - Increase a stored number
apc_define_constants
(PECL apc >= 3.0.0)
apc_define_constants — Define um conjunto de constantes para recuperação e definição em massa
Descrição
define() é notoriamente lento. Já que o benefício do APC é aumentar a performance de scripts/aplicações, esse mecanismo é disponibilizado para automatizar o processo de definição de constantes em massa. No entanto, essa função não se desempenha tão bem quanto antecipado.
Para uma solução com melhor performance, tente a extensão » hidef do PECL.
Nota: Para remover um conjunto de constantes guardadas (sem limpar o cache inteiro), um array vazio pode ser passado como parâmetro de constants, efetivamente limpando os valore(s) guardado(s).
Parâmetros
- key
-
A key serve de nome para a constante sendo guardada. Essa key é usada para recuperar as constantes guardadas com apc_load_constants().
- constants
-
Um array associativo de pares constant_name => value. O constant_name deve serguir as regras normais de nomenclatura de constantes. value deve ser um valor escalar (string ou número).
- case_sensitive
-
O comportamento padrão para constantes é ser declarado sensíveis ao caso; ex.: CONSTANT e Constant representam valores diferentes. Se esse parâmetro tem valor FALSE as constantes serão declaradas como símbolos insensíveis ao caso.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 Exemplo de apc_define_constants()
<?php
$constants = array(
'ONE' => 1,
'TWO' => 2,
'THREE' => 3,
);
apc_define_constants('numbers', $constants);
echo ONE, TWO, THREE;
?>
O exemplo acima irá imprimir:
123
Veja Também
- apc_load_constants() - Carrega um conjunto de constantes do cache
- define() - Define uma constante
- constant() - Retorna o valor de uma constante
- Ou a referência de constantes do PHP
apc_delete_file
(PECL apc >= 3.1.1)
apc_delete_file — Deletes files from the opcode cache
Parâmetros
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas. Or if keys is an array, then an empty array is returned on success, or an array of failed files is returned.
Exemplos
Exemplo #1 apc_delete_file() example
<?php
$filename = 'file.php';
if (apc_compile_file($filename)) {
if (apc_delete_file($filename)) {
echo "Successfully deleted file $filename from APC cache.", PHP_EOL;
}
}
if (apc_compile_file($filename)) {
if ($good = apc_delete_file(array($filename, 'donotexist.php'))) {
var_dump($good);
}
}
$bad = apc_delete_file('donotexist.php');
var_dump($bad);
?>
O exemplo acima irá imprimir algo similar a:
Successfully deleted file file.php from APC cache.
[Mon May 24 09:30:33 2010] [apc-warning] Could not stat file donotexist.php, unable to delete from cache. in /tmp/test.php on line 13.
array(1) {
[0]=>
string(14) "donotexist.php"
}
[Mon May 24 09:30:33 2010] [apc-warning] Could not stat file donotexist.php, unable to delete from cache. in /tmp/test.php on line 18.
bool(false)
Veja Também
- apc_clear_cache() - Limpa o cache do APC.
- apc_delete() - Remove uma variável guardado no cache.
- apc_exists() - Checks if APC key exists
apc_delete
(PECL apc >= 3.0.0)
apc_delete — Remove uma variável guardado no cache.
Descrição
Remove uma variável armazenada do cache.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 Um exemplo de apc_delete()
<?php
$bar = 'BAR';
apc_store('foo', $bar);
apc_delete('foo');
// Isso é obviamente inútil dessa forma
?>
Veja Também
- apc_store() - Guarda uma variável no cache
- apc_fetch() - Retorna uma variável guardado do cache
apc_exists
(PECL apc >= 3.1.4)
apc_exists — Checks if APC key exists
Valor Retornado
Returns TRUE if the key exists, otherwise FALSE Or if an array was passed to keys, then an array is returned that contains all existing keys, or an empty array if none exist.
Exemplos
Exemplo #1 apc_exists() example
<?php
$fruit = 'apple';
$veggie = 'carrot';
apc_store('foo', $fruit);
apc_store('bar', $veggie);
if (apc_exists('foo')) {
echo "Foo exists: ";
echo apc_fetch('foo');
} else {
echo "Foo does not exist";
}
echo PHP_EOL;
if (apc_exists('baz')) {
echo "Baz exists.";
} else {
echo "Baz does not exist";
}
echo PHP_EOL;
$ret = apc_exists(array('foo', 'donotexist', 'bar'));
var_dump($ret);
?>
O exemplo acima irá imprimir algo similar a:
Foo exists: apple
Baz does not exist
array(2) {
["foo"]=>
bool(true)
["bar"]=>
bool(true)
}
Veja Também
- apc_cache_info() - Retorna informação guardada (e meta-dados) de registros do APC
- apc_fetch() - Retorna uma variável guardado do cache
apc_fetch
(PECL apc >= 3.0.0)
apc_fetch — Retorna uma variável guardado do cache
Valor Retornado
A variável guardada se tiver sucesso; FALSE em caso de falha
Exemplos
Exemplo #1 Um exemplo de apc_fetch()
<?php
$bar = 'BAR';
apc_store('foo', $bar);
var_dump(apc_fetch('foo'));
?>
O exemplo acima irá imprimir:
string(3) "BAR"
Veja Também
- apc_store() - Guarda uma variável no cache
- apc_delete() - Remove uma variável guardado no cache.
apc_inc
(PECL apc >= 3.1.1)
apc_inc — Increase a stored number
Descrição
Increases a stored number.
Parâmetros
- key
-
The key of the value being increased.
- step
-
The step, or value to increase.
- success
-
Optionally pass the success or fail boolean value to this referenced variable.
Valor Retornado
Returns the current value of key's value on success, or FALSE on failure
Exemplos
Exemplo #1 apc_inc() example
<?php
echo "Let's do something with success", PHP_EOL;
apc_store('anumber', 42);
echo apc_fetch('anumber'), PHP_EOL;
echo apc_inc('anumber'), PHP_EOL;
echo apc_inc('anumber', 10), PHP_EOL;
echo apc_inc('anumber', 10, $success), PHP_EOL;
var_dump($success);
echo "Now, let's fail", PHP_EOL, PHP_EOL;
apc_store('astring', 'foo');
$ret = apc_inc('astring', 1, $fail);
var_dump($ret);
var_dump($fail);
?>
O exemplo acima irá imprimir algo similar a:
42 43 53 63 bool(true) Now, let's fail bool(false) bool(false)
Veja Também
- apc_dec() - Decrease a stored number
apc_load_constants
(PECL apc >= 3.0.0)
apc_load_constants — Carrega um conjunto de constantes do cache
Descrição
Carrega um conjunto de constantes do cache.
Parâmetros
- key
-
O nome do conjunto de constantes (que foi guardado com apc_define_constants()) para ser resgatado.
- case_sensitive
-
O comportamento padrão para constantes é serem declaradas sensíveis ao caso; ex.: CONSTANT e Constant representam valores diferentes. Se esse parâmetro tem valor FALSE as constantes serão declaradas como símbolos insensíveis ao caso.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 Exemplo de apc_load_constants()
<?php
$constants = array(
'ONE' => 1,
'TWO' => 2,
'THREE' => 3,
);
apc_define_constants('numbers', $constants);
apc_load_constants('numbers');
echo ONE, TWO, THREE;
?>
O exemplo acima irá imprimir:
123
Veja Também
- apc_define_constants() - Define um conjunto de constantes para recuperação e definição em massa
- define() - Define uma constante
- constant() - Retorna o valor de uma constante
- Ou a referência de constantes do PHP
apc_sma_info
(PECL apc >= 2.0.0)
apc_sma_info — Retorna informação sobre Alocação de Memória Compartilhada do APC.
Descrição
Recupera informação de alocação de memória compartilhada do APC.
Parâmetros
- limited
-
Quando definido para FALSE (padrão) apc_sma_info() retornará uma informação detalhada sobre cada segmento.
Valor Retornado
Array de dados sobre Alocação de Memória Compartilhada; FALSE em caso de falha.
Exemplos
Exemplo #1 Um exemplo de apc_sma_info()
<?php
print_r(apc_sma_info());
?>
O exemplo acima irá imprimir algo similar a:
Array
(
[num_seg] => 1
[seg_size] => 31457280
[avail_mem] => 31448408
[block_lists] => Array
(
[0] => Array
(
[0] => Array
(
[size] => 31448408
[offset] => 8864
)
)
)
)
apc_store
(PECL apc >= 3.0.0)
apc_store — Guarda uma variável no cache
Descrição
Armazena uma variável no cache.
Nota: Ao contrário de muitos outros mecanismos no PHP, variáveis guardadas usando apc_store() persistirão entre requisições (até que o valor seja removido do cache).
Parâmetros
- key
-
Guarda a variável usando esse nome. keys são únicas para cada cache, então, guardar um segundo valor com a mesma key sobrescreverá o valor original.
- var
-
A variável a ser guardada.
- ttl
-
Tempo de vida; guarda var no cache por ttl segundos. Após ttl ter passado, a variável guardada será removida do cache (na próxima requisição). Se ttl não for passado (ou se ttl for 0), o valor persistirá até ser removido manualmente do cache, ou caso deixe de existir no cache (clear, restart, etc.).
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 Um exemplo de apc_store()
<?php
$bar = 'BAR';
apc_store('foo', $bar);
var_dump(apc_fetch('foo'));
?>
O exemplo acima irá imprimir:
string(3) "BAR"
Veja Também
- apc_add() - Cache a variable in the data store
- apc_fetch() - Retorna uma variável guardado do cache
- apc_delete() - Remove uma variável guardado no cache.
Índice
- apc_add — Cache a variable in the data store
- apc_bin_dump — Get a binary dump of the given files and user variables
- apc_bin_dumpfile — Output a binary dump of cached files and user variables to a file
- apc_bin_load — Load a binary dump into the APC file/user cache
- apc_bin_loadfile — Load a binary dump from a file into the APC file/user cache
- apc_cache_info — Retorna informação guardada (e meta-dados) de registros do APC
- apc_cas — Updates an old value with a new value
- apc_clear_cache — Limpa o cache do APC.
- apc_compile_file — Stores a file in the bytecode cache, bypassing all filters.
- apc_dec — Decrease a stored number
- apc_define_constants — Define um conjunto de constantes para recuperação e definição em massa
- apc_delete_file — Deletes files from the opcode cache
- apc_delete — Remove uma variável guardado no cache.
- apc_exists — Checks if APC key exists
- apc_fetch — Retorna uma variável guardado do cache
- apc_inc — Increase a stored number
- apc_load_constants — Carrega um conjunto de constantes do cache
- apc_sma_info — Retorna informação sobre Alocação de Memória Compartilhada do APC.
- apc_store — Guarda uma variável no cache
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- APC Funções
- apc_add — Cache a variable in the data store
- apc_bin_dump — Get a binary dump of the given files and user variables
- apc_bin_dumpfile — Output a binary dump of cached files and user variables to a file
- apc_bin_load — Load a binary dump into the APC file/user cache
- apc_bin_loadfile — Load a binary dump from a file into the APC file/user cache
- apc_cache_info — Retorna informação guardada (e meta-dados) de registros do APC
- apc_cas — Updates an old value with a new value
- apc_clear_cache — Limpa o cache do APC.
- apc_compile_file — Stores a file in the bytecode cache, bypassing all filters.
- apc_dec — Decrease a stored number
- apc_define_constants — Define um conjunto de constantes para recuperação e definição em massa
- apc_delete_file — Deletes files from the opcode cache
- apc_delete — Remove uma variável guardado no cache.
- apc_exists — Checks if APC key exists
- apc_fetch — Retorna uma variável guardado do cache
- apc_inc — Increase a stored number
- apc_load_constants — Carrega um conjunto de constantes do cache
- apc_sma_info — Retorna informação sobre Alocação de Memória Compartilhada do APC.
- apc_store — Guarda uma variável no cache
Advanced PHP debugger
Introdução
APD is the Advanced PHP Debugger. It was written to provide profiling and debugging capabilities for PHP code, as well as to provide the ability to print out a full stack backtrace. APD supports interactive debugging, but by default it writes data to trace files. It also offers event based logging so that varying levels of information (including function calls, arguments passed, timings, etc.) can be turned on or off for individual scripts.
APD is a Zend Extension, modifying the way the internals of PHP handle function calls, and thus may or may not be compatible with other Zend Extensions (for example Zend Optimizer).
Instalação/Configuração
Índice
Dependências
Nenhuma biblioteca externa é necessária para compilar esta extensão.
Instalação
Informações para a instalação desta extensão PECL podem ser encontradas no manual no capitulo intitulado Instalação de extensões PECL. Informações adicionais como novas versões, downloads, arquivos fontes, manutenções, e um Changelog, podem ser obtidos aqui: » http://pecl.php.net/package/apd.
Uma DLL para esta extenção PECL esta atualmente indisponível. Veja também a seção compilando no Windows section.
In your INI file, add the following lines:
zend_extension = /absolute/path/to/apd.so apd.dumpdir = /absolute/path/to/trace/directory apd.statement_tracing = 0
Depending on your PHP build, the zend_extension directive can be one of the following:
zend_extension (non ZTS, non debug build) zend_extension_ts ( ZTS, non debug build) zend_extension_debug (non ZTS, debug build) zend_extension_debug_ts ( ZTS, debug build)
Building on Win32
To build APD under Windows you need a working PHP compilation environment as described on http://php.net/ -- basically, it requires you to have Microsoft Visual C++, win32build.zip, bison/flex, and some know how to get it to work. Also ensure that adp.dsp has DOS line endings; if it has unix line endings, Microsoft Visual C++ will complain about it.
Configurações em Execução
O comportamento dessas funções podem ser modificado pelas configurações do php.ini.
| Nome | Padrão | Modificável | Histórico |
|---|---|---|---|
| apd.dumpdir | NULL | PHP_INI_ALL | |
| apd.statement_tracing | "0" | PHP_INI_ALL | Available since apd 0.9. |
Breve descrição das diretivas de configuração.
- apd.dumpdir string
-
Sets the directory in which APD writes profile dump files. You can specify an absolute path or a relative path.
You can specify a different directory as an argument to apd_set_pprof_trace().
- apd.statement_tracing boolean
-
Specfies whether or not to do per-line tracings. Turning this on (1) will impact the performance of your application.
Tipos Resource
Esta extensão não possui nenhum tipo resource.
Constantes pré-definidas
As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.
| Constant | Value | Description |
|---|---|---|
| FUNCTION_TRACE (integer) | 1 | |
| ARGS_TRACE (integer) | 2 | |
| ASSIGNMENT_TRACE (integer) | 4 | |
| STATEMENT_TRACE (integer) | 8 | |
| MEMORY_TRACE (integer) | 16 | |
| TIMING_TRACE (integer) | 32 | |
| SUMMARY_TRACE (integer) | 64 | |
| ERROR_TRACE (integer) | 128 | |
| PROF_TRACE (integer) | 256 | |
| APD_VERSION (string) | example: 1.0.2-dev |
Exemplos
Índice
How to use PHP-APD in your scripts
-
As the first line of your PHP script, call the apd_set_pprof_trace() function to start the trace:
<?php
apd_set_pprof_trace();
?>You can insert the line anywhere in your script, but if you do not start tracing at the beginning of your script you discard profile data that might otherwise lead you to a performance bottleneck.
-
Now run your script. The dump output will be written to apd.dumpdir/pprof_pid.ext.
DicaIf you're running the CGI version of PHP, you will need to add the '-e' flag to enable extended information for apd to work properly. For example:
php -e -f script.php -
To display formatted profile data, issue the pprofp command with the sort and display options of your choice. The formatted output will look something like:
bash-2.05b$ pprofp -R /tmp/pprof.22141.0 Trace for /home/dan/testapd.php Total Elapsed Time = 0.00 Total System Time = 0.00 Total User Time = 0.00 Real User System secs/ cumm %Time (excl/cumm) (excl/cumm) (excl/cumm) Calls call s/call Memory Usage Name -------------------------------------------------------------------------------------- 100.0 0.00 0.00 0.00 0.00 0.00 0.00 1 0.0000 0.0009 0 main 56.9 0.00 0.00 0.00 0.00 0.00 0.00 1 0.0005 0.0005 0 apd_set_pprof_trace 28.0 0.00 0.00 0.00 0.00 0.00 0.00 10 0.0000 0.0000 0 preg_replace 14.3 0.00 0.00 0.00 0.00 0.00 0.00 10 0.0000 0.0000 0 str_replace
The -R option used in this example sorts the profile table by the amount of real time the script spent executing a given function. The "cumm call" column reveals how many times each function was called, and the "s/call" column reveals how many seconds each call to the function required, on average.
-
To generate a calltree file that you can import into the KCacheGrind profile analysis application, issue the pprof2calltree comand.
APD Funções
Contact information
If you have comments, bugfixes, enhancements or want to help developing this beast, you can send an mail to » apd@mail.communityconnect.com. Any help is very welcome.
apd_breakpoint
(PECL apd >= 0.2)
apd_breakpoint — Stops the interpreter and waits on a CR from the socket
Descrição
This can be used to stop the running of your script, and await responses on the connected socket. To step the program, just send enter (a blank line), or enter a php command to be executed.
Parâmetros
- debug_level
-
Um interiro que é formado pela adição em conjunto das constantes XXX_TRACE.
Não é recomendado usar MEMORY_TRACE. è muito lenta e não parece ser exata. ASSIGNMENT_TRACE ainda não esta implementada.
Para ativar todos os traços de funções (TIMING, FUNCTIONS, ARGS SUMMARY (como strace -c)) use o valor 99
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 Typical session using tcplisten
bash#tcplisten localhost 7777
APD - Advanced PHP Debugger Trace File
---------------------------------------------------------------------------
Process Pid (6118)
Trace Begun at Sun Mar 10 23:13:12 2002
---------------------------------------------------------------------------
( 0.000000): apd_set_session_trace called at /home/alan/Projects/project2/test.
php:5
( 0.074824): apd_set_session_trace_socket() at /home/alan/Projects/project2/tes
t.php:5 returned. Elapsed (0.074824)
( 0.074918): apd_breakpoint() /home/alan/Projects/project2/test.php:7
++ argv[0] $(??) = 9
apd_breakpoint() at /home/alan/Projects/project2/test.php:7 returned. Elapsed (
-2089521468.1073275368)
>\n
statement: /home/alan/Projects/project2/test.php:8
>\n
statement: /home/alan/Projects/project2/test.php:8
>\n
statement: /home/alan/Projects/project2/test.php:10
>apd_echo($i);
EXEC: apd_echo($i);
0
>apd_echo(serialize(apd_get_active_symbols()));
EXEC: apd_echo(serialize(apd_get_active_symbols()));
a:47:{i:0;s:4:"PWD";i:1;s:10:"COLORFGBG";i:2;s:11:"XAUTHORITY";i:3;s:14:"
COLORTERM_BCE";i:4;s:9:"WINDOWID";i:5;s:14:"ETERM_VERSION";i:6;s:16:"SE
SSION_MANAGER";i:7;s:4:"PS1";i:8;s:11:"GDMSESSION";i:9;s:5:"USER";i:10;s:5:"
MAIL";i:11;s:7:"OLDPWD";i:12;s:5:"LANG";i:13;s:10:"COLORTERM";i:14;s:8:"DISP
LAY";i:15;s:8:"LOGNAME";i:16;s:6:"
>apd_echo(system('ls /home/mydir'));
........
>apd_continue(0);
apd_callstack
(PECL apd 0.2-0.4)
apd_callstack — Returns the current call stack as an array
Descrição
Returns the current call stack as an array
Valor Retornado
An array containing the current call stack.
Exemplos
Exemplo #1 apd_callstack() example
<?php
print_r(apd_callstack());
?>
apd_clunk
(PECL apd 0.2-0.4)
apd_clunk — Throw a warning and a callstack
Descrição
Behaves like perl's Carp::cluck. Throw a warning and a callstack.
Parâmetros
- warning
-
The warning to throw.
- delimiter
-
The delimiter. Default to <BR />.
Valor Retornado
Não há valor retornado.
Exemplos
Exemplo #1 apd_clunk() example
<?php
apd_clunk("Some Warning", "<br/>");
?>
apd_continue
(PECL apd >= 0.2)
apd_continue — Restarts the interpreter
Descrição
Usually sent via the socket to restart the interpreter.
Parâmetros
- debug_level
-
Um interiro que é formado pela adição em conjunto das constantes XXX_TRACE.
Não é recomendado usar MEMORY_TRACE. è muito lenta e não parece ser exata. ASSIGNMENT_TRACE ainda não esta implementada.
Para ativar todos os traços de funções (TIMING, FUNCTIONS, ARGS SUMMARY (como strace -c)) use o valor 99
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 apd_continue() example
<?php
apd_continue(0);
?>
apd_croak
(PECL apd 0.2-0.4)
apd_croak — Throw an error, a callstack and then exit
Descrição
Behaves like perl's Carp::croak. Throw an error, a callstack and then exit.
Parâmetros
- warning
-
The warning to throw.
- delimiter
-
The delimiter. Default to <BR />.
Valor Retornado
Não há valor retornado.
Exemplos
Exemplo #1 apd_croak() example
<?php
apd_croak("Some Warning","<P>");
?>
apd_dump_function_table
(Unknown)
apd_dump_function_table — Outputs the current function table
Descrição
Outputs the current function table.
Valor Retornado
Não há valor retornado.
Exemplos
Exemplo #1 apd_dump_function_table() example
<?php
apd_dump_function_table();
?>
apd_dump_persistent_resources
(PECL apd 0.2-0.4)
apd_dump_persistent_resources — Return all persistent resources as an array
Descrição
Return all persistent resources as an array.
Valor Retornado
An array containing the current call stack.
Exemplos
Exemplo #1 apd_dump_persistent_resources() example
<?php
print_r(apd_dump_persistent_resources());
?>
apd_dump_regular_resources
(PECL apd 0.2-0.4)
apd_dump_regular_resources — Return all current regular resources as an array
Descrição
Return all current regular resources as an array.
Valor Retornado
An array containing the current regular resources.
Exemplos
Exemplo #1 apd_dump_regular_resources() example
<?php
print_r(apd_dump_regular_resources());
?>
apd_echo
(PECL apd >= 0.2)
apd_echo — Echo to the debugging socket
Descrição
Usually sent via the socket to request information about the running script.
Parâmetros
- output
-
The debugged variable.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 apd_echo() example
<?php
apd_echo($i);
?>
apd_get_active_symbols
(PECL apd 0.2)
apd_get_active_symbols — Get an array of the current variables names in the local scope
Descrição
Returns the names of all the variables defined in the active scope, (not their values).
Valor Retornado
A multidimensional array with all the variables.
Exemplos
Exemplo #1 apd_get_active_symbols() example
<?php
apd_echo(apd_get_active_symbols());
?>
apd_set_pprof_trace
(PECL apd >= 0.2)
apd_set_pprof_trace — Starts the session debugging
Descrição
Starts debugging to pprof_{process_id} in the dump directory.
Parâmetros
- dump_directory
-
The directory in which the profile dump file is written. If not set, the apd.dumpdir setting from the php.ini file is used.
- fragment
-
Valor Retornado
Returns path of the destination file.
Exemplos
Exemplo #1 apd_set_pprof_trace() example
<?php
apd_set_pprof_trace();
?>
apd_set_session_trace_socket
(PECL apd >= 0.2)
apd_set_session_trace_socket — Starts the remote session debugging
Descrição
Connects to the specified tcp_server (eg. tcplisten) and sends debugging data to the socket.
Parâmetros
- tcp_server
-
IP or Unix Domain socket (like a file) of the TCP server.
- socket_type
-
Can be AF_UNIX for file based sockets or APD_AF_INET for standard tcp/ip.
- port
-
You can use any port, but higher numbers are better as most of the lower numbers may be used by other system services.
- debug_level
-
Um interiro que é formado pela adição em conjunto das constantes XXX_TRACE.
Não é recomendado usar MEMORY_TRACE. è muito lenta e não parece ser exata. ASSIGNMENT_TRACE ainda não esta implementada.
Para ativar todos os traços de funções (TIMING, FUNCTIONS, ARGS SUMMARY (como strace -c)) use o valor 99
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 apd_set_session_trace_socket() example
<?php
apd_set_session_trace_socket("127.0.0.1",APD_AF_INET,7112,0);
?>
apd_set_session_trace
(PECL apd 0.2-0.4)
apd_set_session_trace — Starts the session debugging
Descrição
Starts debugging to apd_dump_{process_id} in the dump directory.
Parâmetros
- debug_level
-
Um interiro que é formado pela adição em conjunto das constantes XXX_TRACE.
Não é recomendado usar MEMORY_TRACE. è muito lenta e não parece ser exata. ASSIGNMENT_TRACE ainda não esta implementada.
Para ativar todos os traços de funções (TIMING, FUNCTIONS, ARGS SUMMARY (como strace -c)) use o valor 99
- dump_directory
-
The directory in which the profile dump file is written. If not set, the apd.dumpdir setting from the php.ini file is used.
Valor Retornado
Não há valor retornado.
Exemplos
Exemplo #1 apd_set_session_trace() example
<?php
apd_set_session_trace(99);
?>
apd_set_session
(PECL apd 0.2-0.4)
apd_set_session — Changes or sets the current debugging level
Descrição
This can be used to increase or decrease debugging in a different area of your application.
Parâmetros
- debug_level
-
Um interiro que é formado pela adição em conjunto das constantes XXX_TRACE.
Não é recomendado usar MEMORY_TRACE. è muito lenta e não parece ser exata. ASSIGNMENT_TRACE ainda não esta implementada.
Para ativar todos os traços de funções (TIMING, FUNCTIONS, ARGS SUMMARY (como strace -c)) use o valor 99
Valor Retornado
Não há valor retornado.
Exemplos
Exemplo #1 apd_set_session() example
<?php
apd_set_session(9);
?>
override_function
(PECL apd >= 0.2)
override_function — Overrides built-in functions
Descrição
Overrides built-in functions by replacing them in the symbol table.
Parâmetros
- function_name
-
The function to override.
- function_args
-
The function arguments, as a comma separated string.
Usually you will want to pass this parameter, as well as the function_code parameter, as a single quote delimited string. The reason for using single quoted strings, is to protect the variable names from parsing, otherwise, if you use double quotes there will be a need to escape the variable names, e.g. \$your_var.
- function_code
-
The new code for the function.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 override_function() example
<?php
override_function('test', '$a,$b', 'echo "DOING TEST"; return $a * $b;');
?>
rename_function
(PECL apd >= 0.2)
rename_function — Renames orig_name to new_name in the global function table
Descrição
Renames a orig_name to new_name in the global function table. Useful for temporarily overriding built-in functions.
Parâmetros
- original_name
-
The original function name.
- new_name
-
The new name for the original_name function.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 rename_function() example
<?php
rename_function('mysql_connect', 'debug_mysql_connect' );
?>
Índice
- apd_breakpoint — Stops the interpreter and waits on a CR from the socket
- apd_callstack — Returns the current call stack as an array
- apd_clunk — Throw a warning and a callstack
- apd_continue — Restarts the interpreter
- apd_croak — Throw an error, a callstack and then exit
- apd_dump_function_table — Outputs the current function table
- apd_dump_persistent_resources — Return all persistent resources as an array
- apd_dump_regular_resources — Return all current regular resources as an array
- apd_echo — Echo to the debugging socket
- apd_get_active_symbols — Get an array of the current variables names in the local scope
- apd_set_pprof_trace — Starts the session debugging
- apd_set_session_trace_socket — Starts the remote session debugging
- apd_set_session_trace — Starts the session debugging
- apd_set_session — Changes or sets the current debugging level
- override_function — Overrides built-in functions
- rename_function — Renames orig_name to new_name in the global function table
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Exemplos
- APD Funções
- apd_breakpoint — Stops the interpreter and waits on a CR from the socket
- apd_callstack — Returns the current call stack as an array
- apd_clunk — Throw a warning and a callstack
- apd_continue — Restarts the interpreter
- apd_croak — Throw an error, a callstack and then exit
- apd_dump_function_table — Outputs the current function table
- apd_dump_persistent_resources — Return all persistent resources as an array
- apd_dump_regular_resources — Return all current regular resources as an array
- apd_echo — Echo to the debugging socket
- apd_get_active_symbols — Get an array of the current variables names in the local scope
- apd_set_pprof_trace — Starts the session debugging
- apd_set_session_trace_socket — Starts the remote session debugging
- apd_set_session_trace — Starts the session debugging
- apd_set_session — Changes or sets the current debugging level
- override_function — Overrides built-in functions
- rename_function — Renames orig_name to new_name in the global function table
Compilador de PHP bytecode
Introdução
Este módulo é EXPERIMENTAL. O comportamento desta extensão — incluindo o nome de suas funções e qualquer outra documentação sobre esta extensão — poderá mudar sem aviso em futuras versões do PHP. Esta extensão deve ser usada por sua própria conta e risco.
Bcompiler foi escrito por várias razões:
- Para codificar script em uma aplicação PHP proprietária
- Para codificar algumas classes e/ou funções em uma aplicação PHP proprietária
- Para disponibilizar a produção de aplicações php-gtk que poderiam ser usadas em clientes desktops, sem precisa do php.exe.
- Para estudar a possibilidade de fazer um conversor de PHP para C
O segundo desses objetivos é alcançado usando as funções bcompiler_write_header(), bcompiler_write_class(), bcompiler_write_footer(), bcompiler_read(), e bcompiler_load(). Os arquivos bytecode podem ser escritos ou como não-compactados ou planos. O bcompiler_load() lê um arquivo compactador bzip que contém bytecodes, o que tende a ser 1/3 do tamanho original do arquivo.
Para criar arquivos do tipo EXE, bcompiler tem que ser usado com um arquivo de SAPI modificado ou uma versão do PHP que tenha sido compilada como uma biblioteca compartilhada. Nesse cenário, bcompiler ler o bytecode compactador do fim do arquivo executável.
bcompiler pode aumentar performance em volta de 30% quando usado com bytecodes não-compactados apenas. Mas lembre-se que bytecode não-compactado pode ser até 5 vezes maior que o código-fonte original. Usar compactação de bytecode pode evitar gasto de espaço, mas descompactar requer muito mais tempo do que avaliar um fonte. bcompiler também não faz nenhuma otimização de bytecode, isso pode ser acrescentado no futuro...
Em termos de proteção de código, é seguro dizer que é seria impossível recriar o código-fonte exato do qual ele foi criado, e sem os comentários acompanhando o código-font. Seria efetivamente inútil usar o bcompiler para recriar ou modificar uma classe. No entanto, é possível recuperar dados de um arquivo bytecode compactado - então não ponha suas senhas pessoais ou coisa do tipo nele.
Instalação/Configuração
Índice
Dependências
Nenhuma biblioteca externa é necessária para compilar esta extensão.
Instalação
Nota curta de instalação:
- Você precisa de pelo menos o PHP 4.3.0 para a compressão funcionar
- Para instalar no PHP 4.3.0 e superior no shell do unix digite pear install bcompiler
- Para instalar no Windows, até o mecanismo de distribuíção de pacotes binários estiver completo, favor procure os arquivos da lista de discussão pear-general pelos pacotes pré-compilados. (ou mande um e-mail para a lista de você não conseguir achar uma referência).
- Para instalar em versões mais antigas, você precisa fazer algumas pequenas alterações ao binário compilado.
- untar o arquivo bcompiler.tgz no diretório php4/ext.(Pegue o diretamente da PECL » http://pecl.php.net/get/bcompiler)
- Se o novo diretório for chamado algo como bcompiler-0.x, então você deve renomeá-lo para bcompiler (exceto se você só quiser compilá-lo como um módulo do php auto-contido).
- Se você estiver usando versões anteriores ao PHP 4.3.0, você terá que copiar os arquivos Makefile.in.old para Makefile.in e config.m4.old para config.m4.
- execute phpize no diretório ext/bcompiler
- execute ./buildconf no diretório php4
- execute o script configure com a opção --enable-bcompiler e as suas outras opções
- make; make install
- E por hoje é só pessoal.
Configurações em Execução
Esta extensão não define nenhum parâmetro de configuração no php.ini.
Tipos Resource
Esta extensão não possui nenhum tipo resource.
Constantes pré-definidas
Esta extensão não possui nenhuma constante.
bcompiler Funções
Informação para contato
Se você tiver comentários, resoluções de bugs, melhoramentos ou quer ajudar a desenvolver essa fera, você pode me enviar um e-mail para » alan_k@php.net. Qualquer ajuda é muito bem-vinda.
bcompiler_load_exe
(PECL bcompiler >= 0.4)
bcompiler_load_exe — Lê e cria classes a partir de um arquivo exe do bcompiler
Descrição
Lê os dados de um arquivo executável do bcompiler e cria classes a partir dos bytecodes
Parâmetros
- filename
-
String com o caminho do arquivo executável.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 Exemplo de bcompiler_load()
<?php
bcompiler_load_exe("/tmp/example.exe");
print_r(get_defined_classes());
?>
Notas
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
bcompiler_load
(PECL bcompiler >= 0.4)
bcompiler_load — Lê e cria classes a partir de um arquivo compactado pelo bzip
Descrição
Lê os dados de um arquivo compactado por bzip e cria classes a partir dos bytecodes.
Parâmetros
- filename
-
String com o caminho para o arquivo comprimido pelo bzip.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 Exemplo de chamada à bcompiler_load()
<?php
bcompiler_load("/tmp/example");
print_r(get_defined_classes());
?>
Notas
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Nota:
Favor usar as funções include e require para avaliar os bytecodes, é uma maneira mais portável e conveniente do que usar essa função.
Perceba que essa função não executa código no corpo do script contido no arquivo de bytecode.
bcompiler_parse_class
(PECL bcompiler >= 0.4)
bcompiler_parse_class — Lê o bytecode de uma classe e chama para uma função do usuário
Descrição
Lê os bytecodes de uma classe passa o resultado como parâmetro para uma função do usuário.
Parâmetros
- class
-
String com o nome da classe.
- callback
-
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 Exemplo de uso de bcompiler_parse_class()
<?php
function readByteCodes($data) {
print_r($data);
}
bcompiler_parse_class("DB","readByteCodes");
?>
Notas
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Nota:
Essa função foi removida do bcompiler e não está mais disponível a partir do bcompiler 0.5.
bcompiler_read
(PECL bcompiler >= 0.4)
bcompiler_read — Lê e cria uma classe a partir de um handle de arquivo
Descrição
Lê dados de um handle de arquivo aberto e cria classes a partir dos bytecodes.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 Exemplo de uso de bcompiler_read()
<?php
$fh = fopen("/tmp/example","r");
bcompiler_read($fh);
fclose($fh);
print_r(get_defined_classes());
?>
Notas
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Nota:
Favor usar chamadas de include ou require para avaliar os bytecodes, é uma maneira mais portável e conveniente do que usar essa função.
Favor notar que essa função não executará o código do corpo do script contido no arquivo bytecode.
bcompiler_write_class
(PECL bcompiler >= 0.4)
bcompiler_write_class — Escreve uma classe definida como bytecode
Descrição
Essa função lê os bytecodes do PHP de uma classe existente e escreve ela para um handle de arquivo aberto.
Parâmetros
- filehandle
-
Handle de arquivo, como o retornado por fopen().
- className
-
String com o nome da classe.
- extends
-
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 Exemplo de uso de bcompiler_write_class()
<?php
$fh = fopen("/tmp/example","w");
bcompiler_write_header($fh);
bcompiler_write_class($fh,"DB");
// you must write DB_common before DB_mysql, as DB_mysql extends DB_common.
bcompiler_write_class($fh,"DB_common");
bcompiler_write_class($fh,"DB_mysql");
bcompiler_write_footer($fh);
fclose($fh);
?>
Notas
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Nota:
Essa função não faz checagem de dependência, portanto, certifique-se de colocar as classes na ordem para que não resulte em um erro de classe não definida quando carregar o bytecode.
Veja Também
- bcompiler_write_header() - Escreve o cabeçalho do bcompiler
- bcompiler_write_footer() - Escreve o caracter \x00 para indicar o Fim dos dados compilados
bcompiler_write_constant
(PECL bcompiler >= 0.5)
bcompiler_write_constant — Escreve uma constante definida como bytecodes
Descrição
Lê os bytecodes do PHP de uma constante existente e escreve-os em um handle de arquivo aberto.
Parâmetros
- filehandle
-
Handle de arquivo, como o retornado por fopen().
- constantName
-
String com o nome da constante definida.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 Exemplo de uso de bcompiler_write_constant()
<?php
define("MODULE_MAX", 30);
$fh = fopen("/tmp/example","w");
bcompiler_write_header($fh);
bcompiler_write_constant($fh,"MODULE_MAX");
bcompiler_write_footer($fh);
fclose($fh);
?>
Notas
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Veja Também
- bcompiler_write_header() - Escreve o cabeçalho do bcompiler
- bcompiler_write_footer() - Escreve o caracter \x00 para indicar o Fim dos dados compilados
bcompile_write_file
(No version information available, might only be in SVN)
bcompile_write_file — Escreve um arquivo-fonte do PHP como bytecodes
Descrição
Essa função insere arquivos-fonte especificados no bytecode, e escreve-os para o handle de arquivo aberto.
Parâmetros
- filehandle
-
Handle de arquivo aberto, como retornado por fopen().
- filename
-
String com o caminho para o arquivo-fonte.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 Exemplo de uso de bcompiler_write_file()
<?php
$fh = fopen("example.phb", "w");
bcompiler_write_header($fh);
bcompiler_write_file($fh, "example.php");
bcompiler_write_footer($fh);
fclose($fh);
/* the following should be equivalent:
include "example.php";
and
include "example.phb";
*/
?>
Notas
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Veja Também
- bcompiler_write_header() - Escreve o cabeçalho do bcompiler
- bcompiler_write_footer() - Escreve o caracter \x00 para indicar o Fim dos dados compilados
bcompiler_write_function
(PECL bcompiler >= 0.5)
bcompiler_write_function — Escreve uma função definida como bytecodes
Descrição
Essa função lê o bytecode do PHP de uma função existente, e escreve o mesmo para um handle de arquivo aberto. Ordem não é importante, (ex.: se função b usa função a, e você compilar como no exemplo abaixo, funcionará perfeitamente).
Parâmetros
- filehandle
-
Handle de arquivo aberto, como retornado por fopen().
- functionName
-
String com o nome da função.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 Exemplo de uso de bcompiler_write_function()
<?php
$fh = fopen("/tmp/example","w");
bcompiler_write_header($fh);
bcompiler_write_function($fh,"my_function_a");
bcompiler_write_function($fh,"my_function_b");
bcompiler_write_footer($fh);
fclose($fh);
?>
Notas
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Veja Também
- bcompiler_write_header() - Escreve o cabeçalho do bcompiler
- bcompiler_write_footer() - Escreve o caracter \x00 para indicar o Fim dos dados compilados
bcompiler_write_functions_from_file
(PECL bcompiler >= 0.5)
bcompiler_write_functions_from_file — Escreve todas as funções definidas em um arquivo como bytecodes
Descrição
Essa função procura por todas as funções declaradas em um dado arquivo, e escreve o bytecode correspondente para um handle de arquivo aberto.
Parâmetros
- filehandle
-
Handle de arquivo aberto, como retornado por fopen().
- fileName
-
Caminho para o arquivo à ser compilado. Você deve sempre chamar include ou require no arquivo que deseja compilar.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 Exemplo de uso de bcompiler_write_functions_from_file()
<?php
require('module.php');
$fh = fopen("/tmp/example","w");
bcompiler_write_header($fh);
bcompiler_write_functions_from_file($fh,'module.php');
bcompiler_write_footer($fh);
fclose($fh);
?>
Notas
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Veja Também
- bcompiler_write_header() - Escreve o cabeçalho do bcompiler
- bcompiler_write_footer() - Escreve o caracter \x00 para indicar o Fim dos dados compilados
bcompiler_write_header
(PECL bcompiler >= 0.3)
bcompiler_write_header — Escreve o cabeçalho do bcompiler
Descrição
Escreve a parte do cabeçalho do arquivo bcompiler.
Parâmetros
- filehandle
-
Handle de arquivo aberto, como retornado por fopen().
- write_ver
-
Pode ser usado para escrever bytecode em um formato mais antigo, para que você possa usá-lo com versões mais velhas do bcompiler.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 bcompiler_write_header() example
<?php
$fh = fopen("/tmp/example","w");
bcompiler_write_header($fh);
bcompiler_write_class($fh,"DB");
bcompiler_write_footer($fh);
fclose($fh);
?>
Notas
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Veja Também
- bcompiler_write_footer() - Escreve o caracter \x00 para indicar o Fim dos dados compilados
bcompiler_write_included_filename
(PECL bcompiler >= 0.5)
bcompiler_write_included_filename — Escreve os bytecodes de um arquivo incluído (via include)
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Notas
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Índice
- bcompiler_load_exe — Lê e cria classes a partir de um arquivo exe do bcompiler
- bcompiler_load — Lê e cria classes a partir de um arquivo compactado pelo bzip
- bcompiler_parse_class — Lê o bytecode de uma classe e chama para uma função do usuário
- bcompiler_read — Lê e cria uma classe a partir de um handle de arquivo
- bcompiler_write_class — Escreve uma classe definida como bytecode
- bcompiler_write_constant — Escreve uma constante definida como bytecodes
- bcompiler_write_exe_footer — Escreve na posição de início e continua até o fim do arquivo de tipo EXE
- bcompile_write_file — Escreve um arquivo-fonte do PHP como bytecodes
- bcompiler_write_footer — Escreve o caracter \x00 para indicar o Fim dos dados compilados
- bcompiler_write_function — Escreve uma função definida como bytecodes
- bcompiler_write_functions_from_file — Escreve todas as funções definidas em um arquivo como bytecodes
- bcompiler_write_header — Escreve o cabeçalho do bcompiler
- bcompiler_write_included_filename — Escreve os bytecodes de um arquivo incluído (via include)
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- bcompiler Funções
- bcompiler_load_exe — Lê e cria classes a partir de um arquivo exe do bcompiler
- bcompiler_load — Lê e cria classes a partir de um arquivo compactado pelo bzip
- bcompiler_parse_class — Lê o bytecode de uma classe e chama para uma função do usuário
- bcompiler_read — Lê e cria uma classe a partir de um handle de arquivo
- bcompiler_write_class — Escreve uma classe definida como bytecode
- bcompiler_write_constant — Escreve uma constante definida como bytecodes
- bcompiler_write_exe_footer — Escreve na posição de início e continua até o fim do arquivo de tipo EXE
- bcompile_write_file — Escreve um arquivo-fonte do PHP como bytecodes
- bcompiler_write_footer — Escreve o caracter \x00 para indicar o Fim dos dados compilados
- bcompiler_write_function — Escreve uma função definida como bytecodes
- bcompiler_write_functions_from_file — Escreve todas as funções definidas em um arquivo como bytecodes
- bcompiler_write_header — Escreve o cabeçalho do bcompiler
- bcompiler_write_included_filename — Escreve os bytecodes de um arquivo incluído (via include)
Erros e Logs
Introdução
Estas são funções para lidar com erros e logs. Elas permitem a você definir a suas próprias regras para manusear erros, assim como para modificar a maneira com que é efetuado o log de erros. Isto permite a você melhorar e adaptar as suas necessidades os avisos de erro.
Com as funções de log, você pode mandar mensagens diretamente para outras máquinas, para um email (ou email para um pager), para os logs do sistema, etc, assim você pode seletivamente logar e monitorar as partes mais importantes das suas aplicações e websites.
As funções de erro permitem você configurar quais níveis de erro devem ser reportados e o tipo de resposta que será dado, indo desde simples avisos até as funções retornadas durante os erros.
Instalação/Configuração
Índice
Dependências
Nenhuma biblioteca externa é necessária para compilar esta extensão.
Instalação
Não há nenhuma instalação necessária para utilizar estas funções, elas fazem parte do núcleo do PHP.
Configurações em Execução
O comportamento dessas funções podem ser modificado pelas configurações do php.ini.
| Nome | Padrão | Modificável | Changelog |
|---|---|---|---|
| error_reporting | NULL | PHP_INI_ALL | |
| display_errors | "1" | PHP_INI_ALL | |
| display_startup_errors | "0" | PHP_INI_ALL | |
| log_errors | "0" | PHP_INI_ALL | |
| log_errors_max_len | "1024" | PHP_INI_ALL | Disponível desde PHP 4.3.0. |
| ignore_repeated_errors | "0" | PHP_INI_ALL | Disponível desde PHP 4.3.0. |
| ignore_repeated_source | "0" | PHP_INI_ALL | Disponível desde PHP 4.3.0. |
| report_memleaks | "1" | PHP_INI_ALL | Disponível desde PHP 4.3.0. |
| track_errors | "0" | PHP_INI_ALL | |
| html_errors | "1" | PHP_INI_ALL | |
| docref_root | "" | PHP_INI_ALL | Disponível desde PHP 4.3.0. |
| docref_ext | "" | PHP_INI_ALL | Disponível desde PHP 4.3.0. |
| error_prepend_string | NULL | PHP_INI_ALL | |
| error_append_string | NULL | PHP_INI_ALL | |
| error_log | NULL | PHP_INI_ALL |
Breve descrição das diretivas de configuração.
- error_reporting integer
-
Define o nível de erros para reportar. O parâmetro pode ser um inteiro ou uma constante. Os níveis de erros para reportar estão descritos em Constantes Pré-definidas, e no php.ini. Para definir em tempo de execução, use a função error_reporting(). Veja também a diretiva display_errors.
No PHP 4 e PHP 5 o valor padrão é E_ALL & ~E_NOTICE. Esta definição não mostra erros de nível E_NOTICE. Você deve querer mostra-los durante o desenvolvimento.
Nota:
Ativando E_NOTICE durante o desenvolvimento tem alguns beneficios. Para o proposito de eliminar erros: mensagens NOTICE irão avisar você sobre possiveis erros em seu código. Por exemplo, o uso de valores não definidos é avisado. É extremamente útil para encontrar erros de digitação e economisar tempo na correção de erros. As mensagens NOTICE irão avisar a você sobre mal estilo. Por exemplo, $arr[item] é melhor que seja escrito como $arr['item'] já que o PHP irá tratar "item" como uma constante. Se não for uma constante, o PHP irá considerar como uma string de índice para a matriz.
Nota:
No PHP 5 um novo nível de erro E_STRICT esta disponível. Já que E_STRICT não esta incluída em E_ALL você deve explicitamente ativar este nível de erro. Ativar E_STRICT durante o desenvolvimento tem alguns beneficios. Mensagem STRICT irão ajudar a você a utilizar o metodo mais recente de codificação, por exemplo, avisar você sobre funções obsoletas.
Nota: Constantes do PHP fora do PHP
Usar constantes PHP fora do PHP, como no httpd.conf, não terá sentido útiil assim nestes casos os valores integer são requeridos. E já que níveis de erros serão adicionados com o passar do tempo, o valor máximo (para E_ALL) irá provavelmente mudar. Assim no lugar de E_ALL considere usar um grande valor para cobrir todos os valores de agora assim como no futuro, um valor numérico como 2147483647.
- display_errors boolean
-
Isto determina quando os erros devem ser mostrados como parte da saída ou se devem ser escondidos do usuário.
O valor "stderr" é enviado para stderr ao invés de stdout. O valor é disponível no PHP 5.2.4. Em versões anteriores, esta diretiva era do tipo boolean.
Nota:
Isto serve para suportar o seu desenvolvimento e nunca deve ser usado em sistemas de produção (ex. sistemas conectados a internet).
Nota:
Mesmo podendo ser display_errors definido em tempo de execução (com ini_set()), ele não terá qualquer efeito se o script tiver erro fatal. Isto é porque a ação desejada em tempo de execução não é executada.
- display_startup_errors boolean
-
Mesmo quando display_errors esta em on, erros que aconteçam durante a inicialização do PHP não são mostrados. É fortemente recomendado manter display_startup_errors em off, exceto para procurar erros.
- log_errors boolean
-
Indica se as mensagens de erro do script devem ficar no log de erros do servidor ou em error_log. Esta opção depende do servidor.
Nota:
Você é fortemente avisado para usar o log de erros ao invés de mostra-los em web sites de produção.
- log_errors_max_len integer
-
Define o limite de tamanho da mensagem de erro para logar em bytes. Em error_log é adicionada informação sobre a fonte. O padrão é 1024 e 0 permite que não seja estabelecido nenhum limite. Este tamanho é aplicado aos erros logados, erros exibidos e também a $php_errormsg.
Quando um integer é utilizado, o valor é medido em bytes. A resumida notação, como descrito neste FAQ, pode também ser usada. - ignore_repeated_errors boolean
-
Não loga mensagens repetidas. Erros repetidos devem acontecer no mesmo arquivo na mesma linha enquanto ignore_repeated_source estiver em true.
- ignore_repeated_source boolean
-
Ignora a fonte da mensagem quando estiver ignorando mensagens repetidos. Quando esta definição ON não irá logar mensagens de erros repetidas de arquivos diferentes ou linhas diferentes.
- report_memleaks boolean
-
Se este parâmetro estiver em Off, quando acontecerem memory leaks não será mostrado (na saída ou no log). Isto só tem efeito numa compilação de debug, e se error_reporting incluir E_WARNING na lista de permitidos.
- track_errors boolean
-
Se ativado, a última mensagem de erro sempre estará disponível na variável $php_errormsg.
- html_errors boolean
-
Desativa as tags HTML nas mensagens de erro. O novo formato de mensagens de erro em HTML produz mensagens que podem ser clicadas e que direcionam o usuário para uma pagina descrevendo o erro ou a função que causou o erro. Estas referencias são afetadas por docref_root e docref_ext.
- docref_root string
-
O novo formato de mensagens de erro em HTML produz mensagens que podem ser clicadas e que direcionam o usuário para uma pagina descrevendo o erro ou a função que causou o erro. No caso de paginas de manual você pode baixar o manual na sua língua e definir esta diretiva para a sua cópia local. Se a sua cópia local do manual podur ser acessada por '/manual/' você pode simplesmente usar
docref_root=/manual/. Adicionalmente você deve definir docref_ext para ser igual a extensão da sua cópiadocref_ext=.html. É possível usar referencias externas. Por exemplo, você pode usardocref_root=http://manual/en/oudocref_root="http://landonize.it/?how=url&theme=classic&filter=Landon &url=http%3A%2F%2Fwww.php.net%2F"A maior parte do tempo você deve querer que o valor de docref_root termine com uma barra '/'. Mas veja o segundo exemplo acima o qual não tem ou não necessita isso.
Nota:
Isto é para suportar o seu desenvolvimento já que torna mais fácil encontrar a descrição de uma função. Entretando não deve ser usado em sistemas de produção (ex. sistemas conectados na internet).
- docref_ext string
-
Veja docref_root.
Nota:
O valor de docref_ext deve começar com um ponto '.'.
- error_prepend_string string
-
String para mostrar antes de uma mensagem de erro.
- error_append_string string
-
String para mostrar após uma mensagem de erro.
- error_log string
-
O nome do arquivo onde os erros do script serão logados. O arquivo deve poder ser escrito pelo usuário do servidor web. Se o valor especial syslog é usado, os erros são enviados para o log do sistema. No Unix, isto indica syslog(3) e no Windows NT isto indica o log do evento. O log de sistema não é suportado no Windows 95. Veja também: syslog(). Se esta diretiva não for definida, os erros são enviados para o log de erros do SAPI. Por exemplo, é para o log de erros do Apache ou stderr para o CLI.
Tipos Resource
Esta extensão não possui nenhum tipo resource.
Constantes pré-definidas
As constantes listadas abaixo estão sempre disponíveis como parte do núcleo do PHP.
Nota: Você pode usar estes nomes de constantes no php.ini mas não fora do PHP, como no httpd.conf, aonde você deve usar os valores.
| Valor | Constante | Descrição | Nota |
|---|---|---|---|
| 1 | E_ERROR (integer) | Erros fatais em tempo de execução. Estes indicam erros que não podem ser recuperados, como problemas de alocação de memória. A execução do script é interrompida. | |
| 2 | E_WARNING (integer) | Avisos em tempo de execução (erros não fatais). A execução do script não é interrompida. | |
| 4 | E_PARSE (integer) | Erro em tempo de compilação. Erros gerados pelo interpretador. | |
| 8 | E_NOTICE (integer) | Notícia em tempo de execução. Indica que o script encontrou alguma coisa que pode indicar um erro, mas que também possa acontecer durante a execução normal do script. | |
| 16 | E_CORE_ERROR (integer) | Erro fatal que acontece durante a inicialização do PHP. Este é parecido com E_ERROR, exceto que é gerado pelo núcleo do PHP. | desde o PHP 4 |
| 32 | E_CORE_WARNING (integer) | Avisos (erros não fatais) que aconteçam durante a inicialização do PHP. Este é parecido com E_WARNING, exceto que é gerado pelo núcleo do PHP. | desde o PHP 4 |
| 64 | E_COMPILE_ERROR (integer) | Erro fatal em tempo de compilação. Este é parecido com E_ERROR, exceto que é gerado pelo Zend Scripting Engine. | desde o PHP 4 |
| 128 | E_COMPILE_WARNING (integer) | Aviso em tempo de compilação. Este é parecido com E_WARNING, exceto que é geredo pelo Zend Scripting Engine. | desde o PHP 4 |
| 256 | E_USER_ERROR (integer) | Erro gerado pelo usuário. Este é parecido com E_ERROR, exceto que é gerado pelo código PHP usando a função trigger_error(). | desde o PHP 4 |
| 512 | E_USER_WARNING (integer) | Aviso gerado pelo usuário. Este é parecido com E_WARNING, exceto que é gerado pelo código PHP usando a função trigger_error(). | desde o PHP 4 |
| 1024 | E_USER_NOTICE (integer) | Notícia gerada pelo usuário. Este é parecido com E_NOTICE, exceto que é gerado pelo código PHP usando a função trigger_error(). | desde o PHP 4 |
| 2048 | E_STRICT (integer) | Notícias em tempo de execução. Permite ao PHP sugerir mudanças ao seu código as quais irão assegurar melhor interoperabilidade e compatibilidade futura do seu código. | desde o PHP 5 |
| 4096 | E_RECOVERABLE_ERROR (integer) | Erro fatal capturável. Indica que um erro provavelmente perigoso aconteceu, mas não deixou o Engine em um estado instável. Se o erro não for pego por uma manipulador definido pelo usuário (veja também set_error_handler()), a aplicação é abortada como se fosse um E_ERROR. | desde o PHP 5.2.0 |
| 8192 | E_DEPRECATED (integer) | Avisos em tempo de execução. Habilite-o para receber avisos sobre código que não funcionará em futuras versões. | desde o PHP 5.3.0 |
| 16384 | E_USER_DEPRECATED (integer) | Mensagem de aviso gerado pelo usuário. Este é como um E_DEPRECATED, exceto que é gerado em código PHP usando a função trigger_error(). | desde o PHP 5.3.0 |
| 30719 | E_ALL (integer) | Todos erros e avisos, como suportado, exceto de nível E_STRICT no PHP < 6. | 32767 no PHP 6, 30719 no PHP 5.3.x, 6143 no PHP 5.2.x, 2047 anteriormente |
Os valores acima (numéricos ou simbolicos) são usados para criar um bitmask que especifica quais erros reportar.Você pode usar os operadores Bit-a-bit para combinar estes valores ou mascarar certos tipos de erro. Note que somente '|', '~', '!', '^' and '&' serão ententidos dentro do php.ini.
Exemplos
Abaixo você poderá ver um exemplo de como usar as capacidades de gerenciamento de erros no PHP. Nós definimos uma função para gerenciamento de erros a qual guardas as informações dentro de um arquivo (usando um formato XML), e envia um e-mail para o desenvolvador caso um erro crítico na lógica aconteça.
Exemplo #1 Usando gerenciamento de erro em um script
<?php
// we will do our own error handling
error_reporting(0);
// user defined error handling function
function userErrorHandler($errno, $errmsg, $filename, $linenum, $vars)
{
// timestamp for the error entry
$dt = date("Y-m-d H:i:s (T)");
// define an assoc array of error string
// in reality the only entries we should
// consider are E_WARNING, E_NOTICE, E_USER_ERROR,
// E_USER_WARNING and E_USER_NOTICE
$errortype = array (
E_ERROR => 'Error',
E_WARNING => 'Warning',
E_PARSE => 'Parsing Error',
E_NOTICE => 'Notice',
E_CORE_ERROR => 'Core Error',
E_CORE_WARNING => 'Core Warning',
E_COMPILE_ERROR => 'Compile Error',
E_COMPILE_WARNING => 'Compile Warning',
E_USER_ERROR => 'User Error',
E_USER_WARNING => 'User Warning',
E_USER_NOTICE => 'User Notice',
E_STRICT => 'Runtime Notice',
E_RECOVERABLE_ERROR => 'Catchable Fatal Error'
);
// set of errors for which a var trace will be saved
$user_errors = array(E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE);
$err = "<errorentry>\n";
$err .= "\t<datetime>" . $dt . "</datetime>\n";
$err .= "\t<errornum>" . $errno . "</errornum>\n";
$err .= "\t<errortype>" . $errortype[$errno] . "</errortype>\n";
$err .= "\t<errormsg>" . $errmsg . "</errormsg>\n";
$err .= "\t<scriptname>" . $filename . "</scriptname>\n";
$err .= "\t<scriptlinenum>" . $linenum . "</scriptlinenum>\n";
if (in_array($errno, $user_errors)) {
$err .= "\t<vartrace>" . wddx_serialize_value($vars, "Variables") . "</vartrace>\n";
}
$err .= "</errorentry>\n\n";
// for testing
// echo $err;
// save to the error log, and e-mail me if there is a critical user error
error_log($err, 3, "/usr/local/php4/error.log");
if ($errno == E_USER_ERROR) {
mail("phpdev@example.com", "Critical User Error", $err);
}
}
function distance($vect1, $vect2)
{
if (!is_array($vect1) || !is_array($vect2)) {
trigger_error("Incorrect parameters, arrays expected", E_USER_ERROR);
return NULL;
}
if (count($vect1) != count($vect2)) {
trigger_error("Vectors need to be of the same size", E_USER_ERROR);
return NULL;
}
for ($i=0; $i<count($vect1); $i++) {
$c1 = $vect1[$i]; $c2 = $vect2[$i];
$d = 0.0;
if (!is_numeric($c1)) {
trigger_error("Coordinate $i in vector 1 is not a number, using zero",
E_USER_WARNING);
$c1 = 0.0;
}
if (!is_numeric($c2)) {
trigger_error("Coordinate $i in vector 2 is not a number, using zero",
E_USER_WARNING);
$c2 = 0.0;
}
$d += $c2*$c2 - $c1*$c1;
}
return sqrt($d);
}
$old_error_handler = set_error_handler("userErrorHandler");
// undefined constant, generates a warning
$t = I_AM_NOT_DEFINED;
// define some "vectors"
$a = array(2, 3, "foo");
$b = array(5.5, 4.3, -1.6);
$c = array(1, -3);
// generate a user error
$t1 = distance($c, $b) . "\n";
// generate another user error
$t2 = distance($b, "i am not an array") . "\n";
// generate a warning
$t3 = distance($a, $b) . "\n";
?>
Funções para Manuseamento de Erros
Veja Também
Veja também syslog().
debug_backtrace
(PHP 4 >= 4.3.0, PHP 5)
debug_backtrace — Generates a backtrace
Descrição
debug_backtrace() generates a PHP backtrace.
Parâmetros
- options
-
As of 5.3.6, this parameter is a bitmask for the following options:
Before 5.3.6, the only values recognized are TRUE or FALSE, which are the same as setting or not setting the DEBUG_BACKTRACE_PROVIDE_OBJECT option respectively.debug_backtrace() options DEBUG_BACKTRACE_PROVIDE_OBJECT Whether or not to populate the "object" index. DEBUG_BACKTRACE_IGNORE_ARGS Whether or not to omit the "args" index, and thus all the function/method arguments, to save memory. - limit
-
As of 5.4.0, this parameter can be used to limit the number of stack frames returned. By default (limit=0) it returns all stack frames.
Valor Retornado
Returns an array of associative arrays. The possible returned elements are as follows:
| Nome | Tipo | Descrição |
|---|---|---|
| function | string | The current function name. See also __FUNCTION__. |
| line | integer | The current line number. See also __LINE__. |
| file | string | The current file name. See also __FILE__. |
| class | string | The current class name. See also __CLASS__ |
| object | object | The current object. |
| type | string | The current call type. If a method call, "->" is returned. If a static method call, "::" is returned. If a function call, nothing is returned. |
| args | array | If inside a function, this lists the functions arguments. If inside an included file, this lists the included file name(s). |
Histórico
| Versão | Descrição |
|---|---|
| 5.4.0 | Added the optional parameter limit. |
| 5.3.6 | The parameter provide_object changed to options and additional option DEBUG_BACKTRACE_IGNORE_ARGS is added. |
| 5.2.5 | Added the optional parameter provide_object. |
| 5.1.1 | Added the current object as a possible return element. |
Exemplos
Exemplo #1 debug_backtrace() example
<?php
// filename: /tmp/a.php
function a_test($str)
{
echo "\nHi: $str";
var_dump(debug_backtrace());
}
a_test('friend');
?>
<?php
// filename: /tmp/b.php
include_once '/tmp/a.php';
?>
Results similar to the following when executing /tmp/b.php:
Hi: friend
array(2) {
[0]=>
array(4) {
["file"] => string(10) "/tmp/a.php"
["line"] => int(10)
["function"] => string(6) "a_test"
["args"]=>
array(1) {
[0] => &string(6) "friend"
}
}
[1]=>
array(4) {
["file"] => string(10) "/tmp/b.php"
["line"] => int(2)
["args"] =>
array(1) {
[0] => string(10) "/tmp/a.php"
}
["function"] => string(12) "include_once"
}
}
Veja Também
- trigger_error() - Gera uma mensagem a nível de usuário de erro/aviso/notícia
- debug_print_backtrace() - Mostra um backtrace
debug_print_backtrace
(PHP 5)
debug_print_backtrace — Mostra um backtrace
Descrição
debug_print_backtrace() prints a PHP backtrace. It prints the function calls, included/required files and eval()ed stuff.
Parâmetros
This function has no parameters.
Valor Retornado
Não há valor retornado.
Exemplos
Exemplo #1 debug_print_backtrace() example
<?php
// include.php file
function a() {
b();
}
function b() {
c();
}
function c(){
debug_print_backtrace();
}
a();
?>
<?php
// test.php file
// this is the file you should run
include 'include.php';
?>
O exemplo acima irá imprimir algo similar a:
#0 eval() called at [/tmp/include.php:5] #1 a() called at [/tmp/include.php:17] #2 include(/tmp/include.php) called at [/tmp/test.php:3] #0 c() called at [/tmp/include.php:10] #1 b() called at [/tmp/include.php:6] #2 a() called at [/tmp/include.php:17] #3 include(/tmp/include.php) called at [/tmp/test.php:3]
error_get_last
(PHP 5 >= 5.2.0)
error_get_last — Obtém o último erro ocorrido
Descrição
Obtém informação sobre o último erro que ocorreu.
Valor Retornado
Retorna um array associativo descrevendo o último erro com chaves "type", "message", "file" e "line". Retorna NULL se não tiver ocorrido um erro até a chamada da função.
Exemplos
Exemplo #1 Um exemplo da error_get_last()
<?php
echo $a;
print_r(error_get_last());
?>
O exemplo acima irá imprimir algo similar a:
Array
(
[type] => 8
[message] => Undefined variable: a
[file] => C:\WWW\index.php
[line] => 2
)
error_log
(PHP 4, PHP 5)
error_log — Envia uma mensagem de erro para algum lugar
Descrição
Envia uma mensagem de erro para o log de um servidor, para uma porta TCP ou para um arquivo.
Parâmetros
- message
-
The error message that should be logged.
- message_type
-
Says where the error should go. The possible message types are as follows:
Tipo de logs de error_log() 0 mensagem é enviada para o sistema de log do PHP, usando o sistema de log do sistema operacional ou para um arquivo, dependendo do que estiver definido na diretiva error_log. Esta é a opção padrão. 1 mensagem é enviado para o endereço de email em destination. Este é o unico tipo de mensagem onde o quarto parâmetro extra_headers é usado. 2 Não é mais uma opção. 3 mensagem é adicionada ao arquivo destination. Uma nova linha não é adicionada automaticamente ao final da string message. - destination
-
A destinação. Seu significado depende do parâmetro message_type como descrito acima.
- extra_headers
-
The extra headers. It's used when the message_type parameter is set to 1. This message type uses the same internal function as mail() does.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 Exemplos de error_log()
<?php
// Envia uma notificação para o log do servidor
// se não pudermos conectar ao banco de dados.
if (!Ora_Logon($username, $password)) {
error_log("Oracle database not available!", 0);
}
// Avisa o administrados se nós ficarmos sem FOO
if (!($foo = allocate_new_foo())) {
error_log("Big trouble, we're all out of FOOs!", 1,
"operator@example.com");
}
// outra forma de usar calling error_log():
error_log("You messed up!", 3, "/var/tmp/my-errors.log");
?>
error_reporting
(PHP 4, PHP 5)
error_reporting — Define quais erros serão reportados
Descrição
A função error_reporting() define a diretiva error_reporting em tempo de execução. O PHP tem vários níveis de erros, usando esta função você pode definir o nível durante a execução do seu script.
Parâmetros
- level
-
O novo nível error_reporting. Ele leva ou um bitmask, ou uma constante. Usar constantes é fortemente encorajado para assegurar compatibilidade com versões futuras. Quando níveis de erros forem adicionados, o intervalo dos inteiros aumenta, assim antigos níveis de erro baseados em inteiros não irão funcionar como esperado.
Os níveis de erro disponíveis estão listados a baixo. A descrição deles esta em constantes pré-definidas.
Constantes de nível e valores de bit de error_reporting(). Valor Constante 1 E_ERROR 2 E_WARNING 4 E_PARSE 8 E_NOTICE 16 E_CORE_ERROR 32 E_CORE_WARNING 64 E_COMPILE_ERROR 128 E_COMPILE_WARNING 256 E_USER_ERROR 512 E_USER_WARNING 1024 E_USER_NOTICE 6143 E_ALL 2048 E_STRICT 4096 E_RECOVERABLE_ERROR
Valor Retornado
Retorna o nível anterior de error_reporting.
Histórico
| Versão | Descrição |
|---|---|
| 5.0.0 | E_STRICT introduzido (não parte de E_ALL). |
| 5.2.0 | E_RECOVERABLE_ERROR introduzido. |
| 6 | E_STRICT tornou-se parte de E_ALL. |
Exemplos
Exemplo #1 Exemplos error_reporting()
<?php
// Turn off all error reporting
error_reporting(0);
// Report simple running errors
error_reporting(E_ERROR | E_WARNING | E_PARSE);
// Reporting E_NOTICE can be good too (to report uninitialized
// variables or catch variable name misspellings ...)
error_reporting(E_ERROR | E_WARNING | E_PARSE | E_NOTICE);
// Report all errors except E_NOTICE
// This is the default value set in php.ini
error_reporting(E_ALL ^ E_NOTICE);
// Report all PHP errors
error_reporting(E_ALL);
// Same as error_reporting(E_ALL);
ini_set('error_reporting', E_ALL);
?>
Notas
A maioria dos erros E_STRICT são avaliados em tempo de compilação assim esses erros não são reportados no arquivo aonde error_reporting é aumentado para incluir erros E_STRICT (e vice versa).
- A diretiva display_errors
- ini_set()
restore_error_handler
(PHP 4 >= 4.0.1, PHP 5)
restore_error_handler — Restaura a função anterior para gerenciamento de erro
Descrição
Usada após mudar a função que gerencia os erros usando set_error_handler(), para reverter para a função que gerencia os erros anterior (a qual pode ser uma função interna ou uma função definida pelo usuário).
Valor Retornado
Esta função sempre retorna TRUE.
Exemplos
Exemplo #1 Exemplo restore_error_handler()
Decide se unserialize() causou um erro, então restaura o manipulador de erro original.
<?php
function unserialize_handler($errno, $errstr)
{
echo "Invalid serialized value.\n";
}
$serialized = 'foo';
set_error_handler('unserialize_handler');
$original = unserialize($serialized);
restore_error_handler();
?>
O exemplo acima irá imprimir:
Invalid serialized value.
Notas
Nota:
Chamar restore_error_handler() da função error_handler é ignorada.
Veja Também
- error_reporting() - Define quais erros serão reportados
- set_error_handler() - Define uma função do usuário para manipular erros
- restore_exception_handler() - Restauda a função tratadora de exceções anterior.
- trigger_error() - Gera uma mensagem a nível de usuário de erro/aviso/notícia
restore_exception_handler
(PHP 5)
restore_exception_handler — Restauda a função tratadora de exceções anterior.
Descrição
Usada após mudar a função de tratamento de exceção com set_exception_handler(), para reverter para o tratador anterior (que pode ser integrado, ou uma função definida pelo usuário).
Valor Retornado
Essa função sempre retorna TRUE.
Veja Também
- set_exception_handler() - Define uma função definida pelo usuário para tratamento de exceções
- set_error_handler() - Define uma função do usuário para manipular erros
- restore_error_handler() - Restaura a função anterior para gerenciamento de erro
- error_reporting() - Define quais erros serão reportados
set_error_handler
(PHP 4 >= 4.0.1, PHP 5)
set_error_handler — Define uma função do usuário para manipular erros
Descrição
Define uma função do usuário (error_handler) para manipular erros no script.
Esta função pode ser usada para definir a sua própria maneira de manipular erros em tempo de execução, por exemplo, em aplicações nas quais você precisa fazer fazer uma limpeza de dados/arquivos quando um erro crítico acontece, ou quando você precisa que haja um erro sob certa circunstancia (usando trigger_error()).
è importante lembrar-se que o manipulador padrão de erros do PHP é completamente ignorado. As configurações de error_reporting() não terão efeito e o seu manipulador de erro será chamado - entretanto você ainda é capaz de ler o valor atual de error_reporting e agir apropriadamente. É importante notar que este valor será 0 se o comando que causou o erro foi precedido por @ operador de controle de erro .
também note que é sua responsabilidade die()(morrer) se necessário. Se a função manipuladora de erro retornar, a execução do script irá continuar com o próximo comando após o que causou o erro.
Os seguintes tipos de erros não podem ser manipulados com uma função definida pelo usuário: E_ERROR, E_PARSE, E_CORE_ERROR, E_CORE_WARNING, E_COMPILE_ERROR, E_COMPILE_WARNING, e a maioria de E_STRICT que ocorram no arquivo aonde set_error_handler() for chamada.
Se um erro acontecer antes que o script seja executado (exemplo em uploads de arquivos) a função personalizada de manipulação não pode ser chamada já que não estará registrada para isso neste momento.
Parâmetros
- error_handler
-
A função do usuário precisa aceitar dois parâmetros: o código de erro, e uma string descrevendo o erro. Então tem três parâmetros opcionais que podem ser dados: o nome do arquivo no qual o erro aconteceu, o número da linha na qual o erro aconteceu, e o contexto no qual o erro aconteceu (uma matriz que aponta para a tabela de símbolos ativos no ponto em que o erro aconteceu). A função pode ser mostrada como:
handler ( int $errno , string $errstr [, string $errfile [, int $errline [, array $errcontext ]]] )- errno
- O primeiro parâmetro, errno, contém o nível de erro que aconteceu, como um inteiro.
- errstr
- O segundo parâmetro, errstr, contém a mensagem de erro, como uma string.
- errfile
- O terceiro parãmetro é opcional, errfile, o qual contém o nome do arquivo no qual o erro ocorreu, como uma string.
- errline
- O quarto parâmetro é opcional, errline, o qual contém o número da linha na qual o erro ocorreu, como um inteiro.
- errcontext
- O quinto parâmetro é opcional, errcontext, o qual é uma matriz que aponta para a tabela de símbolos ativos no ponto aonde o erro ocorreu. Em outras palavras, errcontext irá conter uma matriz de cada váriavel que exista no escopo aonde o erro aconteceu. O manipulador de erro do usuário não deve modificar o contexto de erro.
Se a função retornar FALSE então o manipulador de erro normal continua.
- error_types
-
Pode ser usado para mascarar o uso da função error_handler da mesma maneira que a configuação error_reporting controla quais erros são exibidos. Sem esta mascara definida a função error_handler será chamada para cada erro sem se importar com a definição de error_reporting.
Valor Retornado
Retorna uma string contendo o manipulador de erro previamente definido (se houver um), ou NULL em caso de erro. Se o manipulador anterior for um metodo de classe, esta função irá retornar uma matriz indexada com a classe e o nome do metodo.
Histórico
| Versão | Descrição |
|---|---|
| 5.2.0 | O manipulador de erro deve retornar FALSE para povoar $php_errormsg. |
| 5.0.0 | O parâmetro error_types foi introzido. |
| 4.3.0 | Ao invés do nome da função, uma matriz contendo a referência a um objeto e um nome de metodo pode também ser dada como argumento para error_handler. |
| 4.0.2 | Três parâmetros opcionais foram adicionados para a função do usuário error_handler. Estes são o nome do arquivo, p número da linha e o contexto. |
Exemplos
Exemplo #1 Manipulação de erros com set_error_handler() e trigger_error()
O exemplo abaixo mostra a manipulação de exceções internas realizando erros e manipulando-os com uma função definida pelo usuário:
<?php
// error handler function
function myErrorHandler($errno, $errstr, $errfile, $errline)
{
switch ($errno) {
case E_USER_ERROR:
echo "<b>My ERROR</b> [$errno] $errstr<br />\n";
echo " Fatal error on line $errline in file $errfile";
echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n";
echo "Aborting...<br />\n";
exit(1);
break;
case E_USER_WARNING:
echo "<b>My WARNING</b> [$errno] $errstr<br />\n";
break;
case E_USER_NOTICE:
echo "<b>My NOTICE</b> [$errno] $errstr<br />\n";
break;
default:
echo "Unknown error type: [$errno] $errstr<br />\n";
break;
}
/* Don't execute PHP internal error handler */
return true;
}
// function to test the error handling
function scale_by_log($vect, $scale)
{
if (!is_numeric($scale) || $scale <= 0) {
trigger_error("log(x) for x <= 0 is undefined, you used: scale = $scale", E_USER_ERROR);
}
if (!is_array($vect)) {
trigger_error("Incorrect input vector, array of values expected", E_USER_WARNING);
return null;
}
$temp = array();
foreach($vect as $pos => $value) {
if (!is_numeric($value)) {
trigger_error("Value at position $pos is not a number, using 0 (zero)", E_USER_NOTICE);
$value = 0;
}
$temp[$pos] = log($scale) * $value;
}
return $temp;
}
// set to the user defined error handler
$old_error_handler = set_error_handler("myErrorHandler");
// trigger some errors, first define a mixed array with a non-numeric item
echo "vector a\n";
$a = array(2, 3, "foo", 5.5, 43.3, 21.11);
print_r($a);
// now generate second array
echo "----\nvector b - a notice (b = log(PI) * a)\n";
/* Value at position $pos is not a number, using 0 (zero) */
$b = scale_by_log($a, M_PI);
print_r($b);
// this is trouble, we pass a string instead of an array
echo "----\nvector c - a warning\n";
/* Incorrect input vector, array of values expected */
$c = scale_by_log("not array", 2.3);
var_dump($c); // NULL
// this is a critical error, log of zero or negative number is undefined
echo "----\nvector d - fatal error\n";
/* log(x) for x <= 0 is undefined, you used: scale = $scale" */
$d = scale_by_log($a, -2.5);
var_dump($d); // Never reached
?>
O exemplo acima irá imprimir algo similar a:
vector a
Array
(
[0] => 2
[1] => 3
[2] => foo
[3] => 5.5
[4] => 43.3
[5] => 21.11
)
----
vector b - a notice (b = log(PI) * a)
<b>My NOTICE</b> [1024] Value at position 2 is not a number, using 0 (zero)<br />
Array
(
[0] => 2.2894597716988
[1] => 3.4341896575482
[2] => 0
[3] => 6.2960143721717
[4] => 49.566804057279
[5] => 24.165247890281
)
----
vector c - a warning
<b>My WARNING</b> [512] Incorrect input vector, array of values expected<br />
NULL
----
vector d - fatal error
<b>My ERROR</b> [256] log(x) for x <= 0 is undefined, you used: scale = -2.5<br />
Fatal error on line 35 in file trigger_error.php, PHP 5.2.1 (FreeBSD)<br />
Aborting...<br />
Veja Também
- error_reporting() - Define quais erros serão reportados
- restore_error_handler() - Restaura a função anterior para gerenciamento de erro
- trigger_error() - Gera uma mensagem a nível de usuário de erro/aviso/notícia
- error level constants
- informações sobre o tipo callback
set_exception_handler
(PHP 5)
set_exception_handler — Define uma função definida pelo usuário para tratamento de exceções
Descrição
Define o tratador de exceção padrão se uma exceção não for pega em um bloco try/catch. A Execução não parará depois que exception_handler é chamada.
Parâmetros
- exception_handler
-
Nome da função à ser chamada quando uma exceção não pega ocorrer. Essa função deve ser definida antes de chamar set_exception_handler(). Essa função de tratamento precisa aceitar um parâmetro, que será o objeto da exceção que foi disparado.
Valor Retornado
Retorna o nome do tratador padrão de exceção anterior, ou NULL em caso de erro. Se nenhum tratador anterior foi definido, o retorno também será NULL.
Exemplos
Exemplo #1 Um exemplo de set_exception_handler()
<?php
function exception_handler($exception) {
echo "Uncaught exception: " , $exception->getMessage(), "\n";
}
set_exception_handler('exception_handler');
throw new Exception('Uncaught Exception');
echo "Not Executed\n";
?>
Veja Também
restore_exception_handler() - Restauda a função tratadora de exceções anterior., restore_error_handler() - Restaura a função anterior para gerenciamento de erro, error_reporting() - Define quais erros serão reportados, informações sobre o tipo callback, e Exceções do PHP 5.
trigger_error
(PHP 4 >= 4.0.1, PHP 5)
trigger_error — Gera uma mensagem a nível de usuário de erro/aviso/notícia
Descrição
Usado para realizar uma condição de erro, pode ser usado em conjunto com o manipulador de erro interno, ou com uma função definida pelo usuário que foi definida como novo manipulador de erro (set_error_handler()).
Esta função é útil se você precisa gerar uma resposta em particular para uma exceção em tempo de execução.
Parâmetros
- error_msg
-
A mensagem de erro definida para este erro. É limita a 1024 caracteres em tamanho. Quaisquer caracteres além de 1024 serão truncados.
- error_type
-
O tipo de erro definido para est erro. Funciona apenas com a família de constantes E_USER, e o padrão será E_USER_NOTICE.
Valor Retornado
Esta função retorna FALSE se for especificado error_type errado, TRUE se não.
Exemplos
Exemplo #1 Exemplo trigger_error()
Veja set_error_handler() para um exemplo mais extensivo.
<?php
if (assert($divisor == 0)) {
trigger_error("Cannot divide by zero", E_USER_ERROR);
}
?>
Veja Também
- error_reporting() - Define quais erros serão reportados
- set_error_handler() - Define uma função do usuário para manipular erros
- restore_error_handler() - Restaura a função anterior para gerenciamento de erro
- As constantes de nível de erro
Descrição
Esta função é um apelido para: trigger_error().
Índice
- debug_backtrace — Generates a backtrace
- debug_print_backtrace — Mostra um backtrace
- error_get_last — Obtém o último erro ocorrido
- error_log — Envia uma mensagem de erro para algum lugar
- error_reporting — Define quais erros serão reportados
- restore_error_handler — Restaura a função anterior para gerenciamento de erro
- restore_exception_handler — Restauda a função tratadora de exceções anterior.
- set_error_handler — Define uma função do usuário para manipular erros
- set_exception_handler — Define uma função definida pelo usuário para tratamento de exceções
- trigger_error — Gera uma mensagem a nível de usuário de erro/aviso/notícia
- user_error — Apelido para trigger_error
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Exemplos
- Funções para Manuseamento de Erros
- debug_backtrace — Generates a backtrace
- debug_print_backtrace — Mostra um backtrace
- error_get_last — Obtém o último erro ocorrido
- error_log — Envia uma mensagem de erro para algum lugar
- error_reporting — Define quais erros serão reportados
- restore_error_handler — Restaura a função anterior para gerenciamento de erro
- restore_exception_handler — Restauda a função tratadora de exceções anterior.
- set_error_handler — Define uma função do usuário para manipular erros
- set_exception_handler — Define uma função definida pelo usuário para tratamento de exceções
- trigger_error — Gera uma mensagem a nível de usuário de erro/aviso/notícia
- user_error — Apelido para trigger_error
htaccess-like support for all SAPIs
Introdução
The htscanner extension gives the possibility to use htaccess-like file to configure PHP per directory, just like apache's htaccess. It is especially useful with fastcgi (ISS5/6/7, lighttpd, etc.).
Instalação/Configuração
Índice
Dependências
PHP version 5.2.0 or greater.
Instalação
Informações para a instalação desta extensão PECL podem ser encontradas no manual no capitulo intitulado Instalação de extensões PECL. Informações adicionais como novas versões, downloads, arquivos fontes, manutenções, e um Changelog, podem ser obtidos aqui: » http://pecl.php.net/package/htscanner
Configurações em Execução
O comportamento dessas funções podem ser modificado pelas configurações do php.ini.
| Nome | Padrão | Modificável | Changelog |
|---|---|---|---|
| htscanner.config_file | ".htscanner" | PHP_INI_SYSTEM | |
| htscanner.default_docroot | "/" | PHP_INI_SYSTEM | |
| htscanner.default_ttl | "300" | PHP_INI_SYSTEM | |
| htscanner."stop_on_error" | "Off" | PHP_INI_SYSTEM |
Breve descrição das diretivas de configuração.
Tipos Resource
Esta extensão não possui nenhum tipo resource.
Inclusion hierarchy viewer
Introdução
Traces through and dumps the hierarchy of file inclusions and class inheritance at runtime.
The files may have been included using include(), include_once(), require(), or require_once().
Class inheritance dependencies are also reported.
Instalação/Configuração
Índice
Dependências
PHP version 5.1.0 or greater.
The included gengraph.php file utilizes the » graphviz library, however, this is not required.
Instalação
Informações para a instalação desta extensão PECL podem ser encontradas no manual no capitulo intitulado Instalação de extensões PECL. Informações adicionais como novas versões, downloads, arquivos fontes, manutenções, e um Changelog, podem ser obtidos aqui: » http://pecl.php.net/package/inclued
Configurações em Execução
O comportamento dessas funções podem ser modificado pelas configurações do php.ini.
| Nome | Padrão | Modificável | Histórico |
|---|---|---|---|
| inclued.enabled | Off | PHP_INI_SYSTEM | |
| inclued.dumpdir | NULL | PHP_INI_SYSTEM |
Breve descrição das diretivas de configuração.
- inclued.enabled bool
-
Whether or not to enable inclued.
- inclued.dumpdir string
-
Location (path) to the directory that stores inclued files. If set, each PHP request will create a file. These files are serialized versions of what inclued_get_data() would produce, so may be unserialized with unserialize().
CuidadoBecause every request creates a file, this directory may fill up fast!
Tipos Resource
Esta extensão não possui nenhum tipo resource.
Constantes pré-definidas
As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.
Esta extensão não possui nenhuma constante.
Exemplos
Índice
Example that implements inclued into an application
This example demonstrates the process of implementing inclued into an existing application, and viewing the results.
Exemplo #1 Getting the data within the PHP application itself (function)
<?php
// File to store the inclued information
$fp = fopen('/tmp/wp.ser', 'w');
if ($fp) {
$clue = inclued_get_data();
if ($clue) {
fwrite($fp, serialize($clue));
}
fclose($fp);
}
?>
Now that some data exists, it's time to make sense of it in the form of a graph. The inclued extension includes a PHP file named gengraph.php that creates a dot file that requires the » graphviz library. However, this form is not required.
Exemplo #2 Example use of gengraph.php
This example creates an image named inclued.png that shows the inclued data.
# First, create the dot file $ php graphviz.php -i /tmp/wp.ser -o wp.dot # Next, create the image $ dot -Tpng -o inclued.png wp.dot
Exemplo #3 Listing data via inclued dumps (configuration)
When using the inclued.dumpdir directive, files (include clues) are dumped with every request. Here's one way to list those files, and unserialize() them.
<?php
$path = ini_get('inclued.dumpdir');
if ($path && is_dir($path)) {
echo "Path: $path", PHP_EOL;
$inclues = new GlobIterator($path . DIRECTORY_SEPARATOR . 'inclued*');
if ($inclues->count() === 0) {
echo 'No clues today', PHP_EOL;
exit;
}
foreach ($inclues as $inclue) {
echo 'Inclued file: ', $inclue->getFilename(), PHP_EOL;
$data = file_get_contents($inclue->getPathname());
if ($data) {
$inc = unserialize($data);
echo ' -- filename: ', $inc['request']['SCRIPT_FILENAME'], PHP_EOL;
echo ' -- number of includes: ', count($inc['includes']), PHP_EOL;
}
echo PHP_EOL;
}
} else {
echo 'I am totally clueless today.', PHP_EOL;
}
?>
O exemplo acima irá imprimir algo similar a:
PATH: /tmp/inclued Inclued file: inclued.56521.1 -- filename: /Users/philip/test.php -- number of includes: 1 Inclued file: inclued.56563.1 -- filename: /tmp/none.php -- number of includes: 0 Inclued file: inclued.56636.1 -- filename: /tmp/three.php -- number of includes: 3
inclued Funções
inclued_get_data
(PECL inclued >= 0.1.0)
inclued_get_data — Get the inclued data
Descrição
Get the inclued data.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
The inclued data.
Exemplos
Exemplo #1 inclued_get_data() example
See the inclued examples section for ways to create graphs with this data.
<?php
include 'x.php';
$clue = inclued_get_data();
print_r($clue);
?>
O exemplo acima irá imprimir algo similar a:
Array
(
[includes] => Array
(
[0] => Array
(
[operation] => include
[op_type] => 2
[filename] => x.php
[opened_path] => /tmp/x.php
[fromfile] => /tmp/z.php
[fromline] => 2
)
)
)
Índice
- inclued_get_data — Get the inclued data
Memtrack
Introdução
The purpose of this extension is to detect the most memory hungry scripts and functions.
memtrack tracks memory consumption in PHP scripts and produces reports (warnings) when the consumption reaches certain levels set by the user. This is achieved by replacing default executor function by a special function which compares memory usage before and after running the original executor - this way we can tell how much the memory usage has changed during the execution of the current part of the code.
Zend Engine runs its executor for each opcode array (op_array), which usually means function, plain script and such, so memtrack doesn't have any noticeable effect on performance.
memtrack doesn't provide any functions, there are only INI directives which allow you to configure the way it should work.
Este módulo é EXPERIMENTAL. O comportamento desta extensão — incluindo o nome de suas funções e qualquer outra documentação sobre esta extensão — poderá mudar sem aviso em futuras versões do PHP. Esta extensão deve ser usada por sua própria conta e risco.
Instalação/Configuração
Índice
Dependências
Nenhuma biblioteca externa é necessária para compilar esta extensão.
Instalação
Informações para a instalação desta extensão PECL podem ser encontradas no manual no capitulo intitulado Instalação de extensões PECL. Informações adicionais como novas versões, downloads, arquivos fontes, manutenções, e um Changelog, podem ser obtidos aqui: » http://pecl.php.net/package/memtrack
Configurações em Execução
O comportamento dessas funções podem ser modificado pelas configurações do php.ini.
| Nome | Padrão | Modificável |
|---|---|---|
| memtrack.enabled | "0" | PHP_INI_SYSTEM |
| memtrack.soft_limit | "0" | PHP_INI_ALL |
| memtrack.hard_limit | "0" | PHP_INI_ALL |
| memtrack.vm_limit | "0" | PHP_INI_ALL |
| memtrack.ignore_functions | "" | PHP_INI_SYSTEM |
Breve descrição das diretivas de configuração.
- memtrack.enabled boolean
-
Disables or enables the extension. Default value is 0, i.e. disabled.
- memtrack.soft_limit int
-
Soft memory limit.
The extension checks memory consumption before and after executing an op_array and produces a warning is the difference between the two values is equal to or greater than the soft limit, but only if the function is not ignored.
Setting this option to 0 also disables both soft and hard limit warnings. Default value is 0, i.e. no warnings is produced.
- memtrack.hard_limit int
-
Hard memory limit.
The extension checks memory consumption before and after executing an op_array and produces a warning is the difference between the two values is equal to or greater than the hard limit, even if the function is ignored. Setting this option to 0 disables hard limit warnings completely. Default value is 0, i.e. no hard limit warnings is produced.
- memtrack.vm_limit int
-
Virtual memory limit (set on a process).
This limit is checked only on shutdown and a warning is produced if the value is greater than or equal to the limit.
This option is currently supported only on OSes where mallinfo() function is available (i.e. Linux).
- memtrack.ignore_functions string
-
A comma or whitespace-separated list of functions which are to be ignored by soft_limit. The values are case-insensitive, for class methods use class::method syntax.
Tipos Resource
Esta extensão não possui nenhum tipo resource.
Constantes pré-definidas
Esta extensão não possui nenhuma constante.
Exemplos
Índice
Basic usage
Basic example on using memtrack extension:
Exemplo #1 Creating large array in a function
<?php
/* /tmp/example1.php */
function foo() {
$a = array();
for ($i = 0; $i < 10000; $i++) $a[] = "test";
return $a;
}
$arr = foo();
?>
Run the example with the following command:
php -d memtrack.enabled=1 -d memtrack.soft_limit=1M -d memtrack.vm_limit=3M /tmp/example1.php
O exemplo acima irá imprimir algo similar a:
Warning: [memtrack] [pid 26177] user function foo() executed in /tmp/example1.php on line 10 allocated 4194304 bytes in /tmp/example1.php on line 0 Warning: [memtrack] [pid 26177] virtual memory usage on shutdown: 32911360 bytes in Unknown on line 0
Controle de Saída de Buffer
Introdução
As funções de Controle de Saída permitem a você controlar quando a saída é enviada do script. Isto pode ser util em várias situações diversas, especialmente se você precisa enviar cabeçalhos para o browser depois que seu script começou a enviar dados. As funções de controle de saída não afetam os cabeçalhos enviados usando header() ou setcookie(), somente funções como echo() e dados entre blocos de código PHP.
Nota:
Quando atualizando a partir do PHP 4.1 (e 4.2) para 4.3 note que devido a um bug nas versões anteriores, você deve ter certeza que implict_flush esta em OFF no seu php.ini, se não qualquer saída com ob_start() não será escondida da saída.
Instalação/Configuração
Índice
Dependências
Nenhuma biblioteca externa é necessária para compilar esta extensão.
Instalação
Não há nenhuma instalação necessária para utilizar estas funções, elas fazem parte do núcleo do PHP.
Configurações em Execução
O comportamento dessas funções podem ser modificado pelas configurações do php.ini.
| Nome | Padrão | Modificavel | Changelog |
|---|---|---|---|
| output_buffering | "0" | PHP_INI_PERDIR | |
| output_handler | NULL | PHP_INI_PERDIR | Disponível desde o PHP 4.0.4. |
| implicit_flush | "0" | PHP_INI_ALL | PHP_INI_PERDIR no PHP <= 4.2.3. |
Breve descrição das diretivas de configuração.
- output_buffering boolean/integer
-
Você pode ativar o buffer de saída para todos os arquivos definindo esta dretiva para 'On'. Se você quiser limitar o tamanho do buffer para um certo limite - você pode usar um número máximo de bytes ao invés de 'On', como valor para esta diretiva (ex., output_buffering=4096). No PHP 4.3.5, esta diretiva é sempre Off em PHP-CLI.
- output_handler string
-
Você pode redirecionar toda a saída do seu script para uma função. Por exemplo, se você definir set output_handler para mb_output_handler(), a codificação dos caracteres será transparentemente convertida para a codificação especificada. Definindo qualquer função para gerenciar a saída ativa o buffer de saída.
Nota:
Você não pode usar mb_output_handler() com ob_iconv_handler() e você não pode usar ob_gzhandler() e zlib.output_compression.
Nota:
Somente funções nativas podem ser usadas com esta diretiva. Para funções definidas pelo usuário, use ob_start().
- implicit_flush boolean
-
FALSE por padrão. Mudando isto para TRUE diz ao PHP para dizer para a camada de saída descarregar a si mesma automaticamente a cada bloco de saída. Isto é equivalente a utilizar a função do PHP flush() a cada print() ou echo() e a cada bloco de HTML.
Quando estiver usando o PHP em um ambiente web, ativando esta opção tem uma séria implicação na performance e geralmente é recomendada apenas para debug. O valor padrão é TRUE quando operando sobre CLI SAPI.
Veja também ob_implicit_flush().
Tipos Resource
Esta extensão não possui nenhum tipo resource.
Constantes pré-definidas
Esta extensão não possui nenhuma constante.
Exemplos
Índice
Exemplos
Exemplo #1 Exemplo de Controle de Saída
<?php
ob_start();
echo "Hello\n";
setcookie("cookiename", "cookiedata");
ob_end_flush();
?>
No exmplo acima, a saída de echo() será guardada no bffer de saída até que ob_end_flush() seja chamada. Em quanto isto, a chamada para setcookie() guadará o cookie sem causar um erro. (Normalmente você não pode enviar cabeçalhos para o browser depois que dados já foram enviados.)
Funções para Control de Saída
Veja Também
Veja também header() e setcookie().
flush
(PHP 4, PHP 5)
flush — Descarrega o buffer de saída
Descrição
Descarrega os buffers de saída do PHP e qualquer backend que o PHP esteja usando (CGI, um servidor web, etc). Isto efetivamente tenta empurrar toda a saída até aqui para o browser do usuário.
flush() não tem efeito no funcionamento de buffer do seu servidor ou do browser do cliente.
Vários servidores, especialmente no Win32, irão continuar colocando a saída do script em buffer até que ele termine antes de enviar os resultados para o browser.
Módulos de servidor para o Apache como o mod_gzip podem fazer buffer por si o que fará com que flush() não resulte em os dados serem enviados imediatamente para o cliente.
mesmo o browser pode fazer buffer antes de mostrar o conteúdo. Netscape, por exemplo, guarda o texto em buffer até que receba um end-of-line ou o inicio de uma tag, e não irá mostrar tabelas até que a tag </table> da tabela mais de fora seja vista.
Algumas versões do Microsoft Internet Explorer somente começaram a mostrar dados depois de terem recebido 256 bytes de saída, então você vai precisar enviar espaço em branco antes de descarregar para os browser para mostrar a página.
ob_clean
(PHP 4 >= 4.2.0, PHP 5)
ob_clean — Limpa (apaga) o buffer de saída
Descrição
Esta função descarta o conteúdo do buffer de saída.
Esta função não destroi o buffer de saída como a função ob_end_clean() faz.
Valor Retornado
Não há valor retornado.
Veja Também
- ob_flush() - Descarrega (envia) o conteúdo do buffer de saída
- ob_end_flush() - Descarrega (envia) o buffer de saída e desativa o buffer de saída
- ob_end_clean() - Limpa (apaga) o buffer de saída e desativa o buffer de saída
ob_end_clean
(PHP 4, PHP 5)
ob_end_clean — Limpa (apaga) o buffer de saída e desativa o buffer de saída
Descrição
Esta função descarta o conteúdo do buffer mais em cima e desativa o buffer de saída. Se você quiser processar o conteúdo do buffer, você deve utilizar a função ob_get_contents() antes de ob_end_clean() já que o conteúdo do buffer é descartado quando a função ob_end_flush() é chamada. A função retorna TRUE quando foi bem sucedida em discartar o buffer, FALSE se não. Razões para falhar é primeiro que você utilizou a função sem um buffer ativo ou por algum motivo o buffer não pode ser excluído (possivelmente por um buffer especial).
O exemplo a seguir mostra como eliminar todos os buffers de saída:
Exemplo #1 Exemplo ob_end_clean()
<?php
ob_start();
echo 'Texto que não será exibido.';
ob_end_clean();
?>
Nota: Se a função falhar gera um E_NOTICE. O valor booleano de rtorno foi adicionado no PHP 4.2.0.
Veja também ob_start(), ob_get_contents() e ob_flush().
ob_end_flush
(PHP 4, PHP 5)
ob_end_flush — Descarrega (envia) o buffer de saída e desativa o buffer de saída
Descrição
Esta função irá enviar o conteúdo do buffer mais em cima (se existir algum) e desativar o buffer de saída. Se você quiser processar o conteúdo do buffer você deverá utilizar ob_get_contents() antes de ob_end_flush() já que o conteúdo do buffer é discartado após ob_end_flush(). A função retorna TRUE quando é bem sucedida em discartar um buffer, FALSE se não. Razões para falhar é primeiro que você utilizou a função sem um buffer ativo ou por algum motivo o buffer não pode ser excluído (possivelmente por um buffer especial).
Nota: Esta função é que parecida com ob_get_flush(), exceto que ob_get_flush() retorna o buffer como uma string.
O exemplo a seguir mostra como descarregar e terminar com todos os buffers de saída:
Exemplo #1 Exemplo ob_end_flush()
<?php
while (@ob_end_flush());
?>
Nota: Se a função falhar gera um E_NOTICE. O valor booleano de rtorno foi adicionado no PHP 4.2.0.
Veja também ob_start(), ob_get_contents(), ob_get_flush(), ob_flush() e ob_end_clean().
ob_flush
(PHP 4 >= 4.2.0, PHP 5)
ob_flush — Descarrega (envia) o conteúdo do buffer de saída
Descrição
Esta função irá enviar o conteúdo do buffer de saída (se existir algum). Se você quiser processar o conteúdo do buffer você deverá utlizar ob_get_contents() antes de ob_flush() já que o conteúdo do buffer é descartado após ob_flush().
Esta função não destroi o buffer de saída como a função ob_end_flush() faz.
Valor Retornado
Não há valor retornado.
Veja Também
- ob_get_contents() - Retorna o conteúdo do buffer de saída
- ob_clean() - Limpa (apaga) o buffer de saída
- ob_end_flush() - Descarrega (envia) o buffer de saída e desativa o buffer de saída
- ob_end_clean() - Limpa (apaga) o buffer de saída e desativa o buffer de saída
ob_get_clean
(PHP 4 >= 4.3.0, PHP 5)
ob_get_clean — Obtém o conteudo do buffer e exclui o buffer de saída atual
Descrição
Esta função irá retornar o conteúdo do buffer de saída e terminar com o buffer de saída. Se o buffer de saída não estiver ativo então será retornado FALSE. ob_get_clean() essencialmente executa ambas ob_get_contents() e ob_end_clean().
Exemplo #1 Um exemplo simples de ob_get_clean()
<?php
ob_start();
print "Hello World";
$out = ob_get_clean();
$out = strtolower($out);
var_dump($out);
?>
Nosso exemplo irá mostrar:
string(11) "hello world"
Veja também ob_start() e ob_get_contents().
ob_get_contents
(PHP 4, PHP 5)
ob_get_contents — Retorna o conteúdo do buffer de saída
Descrição
Obtém o conteúdo do buffer de saída.
Valor Retornado
Isto irá retornar o conteúdo do buffer de saída ou FALSE, se não está fazendo buffer.
Exemplos
Exemplo #1 Um simples exemplo da ob_get_contents()
<?php
ob_start();
echo "Hello ";
$out1 = ob_get_contents();
echo "World";
$out2 = ob_get_contents();
ob_end_clean();
var_dump($out1, $out2);
?>
O exemplo acima irá imprimir:
string(6) "Hello " string(11) "Hello World"
Veja Também
- ob_start() - Ativa o buffer de saída
- ob_get_length() - Retorna o tamanho do buffer de saída
ob_get_flush
(PHP 4 >= 4.3.0, PHP 5)
ob_get_flush — Flush the output buffer, return it as a string and turn off output buffering
Descrição
ob_get_flush() flushes the output buffer, return it as a string and turns off output buffering.
Nota: This function is similar to ob_end_flush(), except that this function returns the buffer as a string.
Valor Retornado
Returns the output buffer or FALSE if no buffering is active.
Exemplos
Exemplo #1 ob_get_flush() example
<?php
//using output_buffering=On
print_r(ob_list_handlers());
//save buffer in a file
$buffer = ob_get_flush();
file_put_contents('buffer.txt', $buffer);
print_r(ob_list_handlers());
?>
O exemplo acima irá imprimir:
Array
(
[0] => default output handler
)
Array
(
)
Veja Também
- ob_end_clean() - Limpa (apaga) o buffer de saída e desativa o buffer de saída
- ob_end_flush() - Descarrega (envia) o buffer de saída e desativa o buffer de saída
- ob_list_handlers() - List all output handlers in use
ob_get_length
(PHP 4 >= 4.0.2, PHP 5)
ob_get_length — Retorna o tamanho do buffer de saída
Descrição
Este irá retonar o tamanho do conteúdo do buffer de saída.
Valor Retornado
Retorna o tamanho do conteúdo do buffer de saída ou FALSE se não está fazendo buffer.
Exemplos
Exemplo #1 Um simples exemplo da ob_get_length()
<?php
ob_start();
echo "Hello ";
$len1 = ob_get_length();
echo "World";
$len2 = ob_get_length();
ob_end_clean();
echo $len1 . ", ." . $len2;
?>
O exemplo acima irá imprimir:
6, 11
Veja Também
- ob_start() - Ativa o buffer de saída
- ob_get_contents() - Retorna o conteúdo do buffer de saída
ob_get_level
(PHP 4 >= 4.2.0, PHP 5)
ob_get_level — Retorna o nível do mecanismo de buffer de saída
Descrição
Isto irá retornar o nível de manipuladores de buffer aninhados ou zero se o mecanismo de buffer de saída não estiver ativado.
Veja também ob_start() e ob_get_contents().
ob_get_status
(PHP 4 >= 4.2.0, PHP 5)
ob_get_status — Obtém a situação dos buffers de saída
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função retorna o estado atual dos buffers de saída. Retorna uma matriz que contém o estado dos buffers ou FALSE em caso de erro.
Veja também ob_get_level().
ob_gzhandler
(PHP 4 >= 4.0.4, PHP 5)
ob_gzhandler — Função de callback para ob_start para compactar com gzip o buffer de saída
Descrição
ob_gzhandler() é intencionado para ser usado como uma função de callback para ob_start() para facilitar o envio de dados gz-encoded para browsers que suportam páginas comprimidas. Antes de ob_gzhandler() enviar dados comprimidos, ela determina qual o tipo de códificação de conteúdo que o browser irá aceitar ("gzip", "deflate" ou nenhum) e irá retornar a sua saída de acordo. Todos os browsers são suportados já que é dever do browser enviar o cabeçalho correto indicando que ele aceita paginas comprimidas.
Nota:
mode foi adicionado no PHP 4.0.5.
Exemplo #1 Exemplo ob_gzhandler()
<?php
ob_start("ob_gzhandler");
?>
<html>
<body>
<p>This should be a compressed page.</p>
</html>
<body>
Nota:
Você não pode usar ambas ob_gzhandler() e ini.zlib.output_compression. Também note que usar ini.zlib.output_compression é preferrível do que ob_gzhandler().
Veja também ob_start() e ob_end_flush().
ob_implicit_flush
(PHP 4, PHP 5)
ob_implicit_flush — Ativa ou desativa o descarregar implicito
Descrição
ob_implicit_flush() irá ativar ou desativar o descarregar implicito (se não for indicado flag, o padrão é on). O descarregar implicito fará com que o buffer seja descarregado a cada operação de saída, então não será mais necessário utilizar flush().
Ativando o descarregar automatico irá desabilitar o buffer de saída. Os buffers de saída atuais serão enviados como se ob_end_flush() fosse utilizada.
Veja também flush(), ob_start(), e ob_end_flush().
ob_list_handlers
(PHP 4 >= 4.3.0, PHP 5)
ob_list_handlers — List all output handlers in use
Descrição
Lists all output handlers in use.
Valor Retornado
This will return an array with the output handlers in use (if any). If output_buffering is enabled or an anonymous function was used with ob_start(), ob_list_handlers() will return "default output handler".
Exemplos
Exemplo #1 ob_list_handlers() example
<?php
//using output_buffering=On
print_r(ob_list_handlers());
ob_end_flush();
ob_start("ob_gzhandler");
print_r(ob_list_handlers());
ob_end_flush();
// anonymous functions
ob_start(create_function('$string', 'return $string;'));
print_r(ob_list_handlers());
ob_end_flush();
?>
O exemplo acima irá imprimir:
Array
(
[0] => default output handler
)
Array
(
[0] => ob_gzhandler
)
Array
(
[0] => default output handler
)
Veja Também
- ob_end_clean() - Limpa (apaga) o buffer de saída e desativa o buffer de saída
- ob_end_flush() - Descarrega (envia) o buffer de saída e desativa o buffer de saída
- ob_get_flush() - Flush the output buffer, return it as a string and turn off output buffering
- ob_start() - Ativa o buffer de saída
ob_start
(PHP 4, PHP 5)
ob_start — Ativa o buffer de saída
Descrição
Esta função irá ativar o buffer de saída. Enquanto o buffer de saída estiver ativo, não é enviada a saída do script (outros que não sejam cabeçalhos), ao invés a saída é guardada em um buffer interno.
O conteúdo deste buffer interno pode ser copiado em uma variável usando ob_get_contents(). Para enviar o que esta no buffer interno, use ob_end_flush(). Alternativamente, ob_end_clean() irá silenciosamente descartar o conteúdo do buffer.
Uma função de callback opcional output_callback também pode ser especificada. Esta função leva uma string coo parâmetro e deve retornar uma string. Esta função será chamada quando ob_end_flush() for chamada, ou quando o buffer de saída for descarregado ao final do script. Quando output_callback for chamada, ela irá receber o conteúdo do buffer como seu parâmetro e é esperado que ela retorne um novo buffer de saída como resultado, o qual será enviado para o browser. Se output_callback não é uma função que possa ser utilizada, esta função irá retornar FALSE.
Nota:
No PHP 4.0.4, ob_gzhandler() para facilitar o envio de dados gz-encoded para browsers que suportem paginas web comprimidas. ob_gzhandler() determina o tipo de codificação de conteúdo que o browser aceitará e enviará a sua saída de acordo.
Nota:
Antes do PHP 4.3.2 esta função não retornava FALSE caso output_callback não pudesse ser executada.
Buffers de saída são empilháveis, isro é, você pode utilizar ob_start() enquanto outro ob_start() estiver ativo. Apenas tenha certeza que você utiliza ob_end_flush() o número apropriado de vezes. Se multiplas funções de callback de saída estiverem ativas, a saída será filtrada sequencialmente atráves de cada uma delas na ordem de aninhamento.
ob_end_clean(), ob_end_flush(), ob_clean(), ob_flush() e ob_start() não devem ser utilizados dentro de uma função de callback. Se você utiliza-los dentro de uma função de callback, o funcionamento é indefinido. Se você quiser excluir o conteúdo de um buffer, retorne "" (uma string vazia) da função de callback.
Exemplo #1 Exemplo com uma função de callback definida pelo usuário
<?php
function callback($buffer)
{
// replace all the apples with oranges
return (str_replace("apples", "oranges", $buffer));
}
ob_start("callback");
?>
<html>
<body>
<p>It's like comparing apples to oranges.
</body>
</html>
<?php
ob_end_flush();
?>
Irá produzir:
<html> <body> <p>It's like comparing oranges to oranges. </body> </html>
Veja também ob_get_contents(), ob_end_flush(), ob_end_clean(), ob_implicit_flush() e ob_gzhandler().
output_add_rewrite_var
(PHP 4 >= 4.3.0, PHP 5)
output_add_rewrite_var — Add URL rewriter values
Descrição
This function adds another name/value pair to the URL rewrite mechanism. The name and value will be added to URLs (as GET parameter) and forms (as hidden input fields) the same way as the session ID when transparent URL rewriting is enabled with session.use_trans_sid. Please note that absolute URLs (http://example.com/..) aren't rewritten.
This function's behavior is controlled by the url_rewriter.tags php.ini parameter.
Nota: Calling this function will implicitly start output buffering if it is not active already.
Parâmetros
- name
-
The variable name.
- value
-
The variable value.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 output_add_rewrite_var() example
<?php
output_add_rewrite_var('var', 'value');
// some links
echo '<a href="file.php">link</a>
<a href="http://example.com">link2</a>';
// a form
echo '<form action="script.php" method="post">
<input type="text" name="var2" />
</form>';
print_r(ob_list_handlers());
?>
O exemplo acima irá imprimir:
<a href="file.php?var=value">link</a>
<a href="http://example.com">link2</a>
<form action="script.php" method="post">
<input type="hidden" name="var" value="value" />
<input type="text" name="var2" />
</form>
Array
(
[0] => URL-Rewriter
)
Veja Também
- output_reset_rewrite_vars() - Reset URL rewriter values
- ob_flush() - Descarrega (envia) o conteúdo do buffer de saída
- ob_list_handlers() - List all output handlers in use
output_reset_rewrite_vars
(PHP 4 >= 4.3.0, PHP 5)
output_reset_rewrite_vars — Reset URL rewriter values
Descrição
This function resets the URL rewriter and removes all rewrite variables previously set by the output_add_rewrite_var() function or the session mechanism (if session.use_trans_sid was set on session_start()).
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 output_reset_rewrite_vars() example
<?php
session_start();
output_add_rewrite_var('var', 'value');
echo '<a href="file.php">link</a>';
ob_flush();
output_reset_rewrite_vars();
echo '<a href="file.php">link</a>';
?>
O exemplo acima irá imprimir:
<a href="file.php?PHPSESSID=xxx&var=value">link</a> <a href="file.php">link</a>
Veja Também
- output_add_rewrite_var() - Add URL rewriter values
- ob_flush() - Descarrega (envia) o conteúdo do buffer de saída
- ob_list_handlers() - List all output handlers in use
- session_start() - Inicia dados de sessão
Índice
- flush — Descarrega o buffer de saída
- ob_clean — Limpa (apaga) o buffer de saída
- ob_end_clean — Limpa (apaga) o buffer de saída e desativa o buffer de saída
- ob_end_flush — Descarrega (envia) o buffer de saída e desativa o buffer de saída
- ob_flush — Descarrega (envia) o conteúdo do buffer de saída
- ob_get_clean — Obtém o conteudo do buffer e exclui o buffer de saída atual
- ob_get_contents — Retorna o conteúdo do buffer de saída
- ob_get_flush — Flush the output buffer, return it as a string and turn off output buffering
- ob_get_length — Retorna o tamanho do buffer de saída
- ob_get_level — Retorna o nível do mecanismo de buffer de saída
- ob_get_status — Obtém a situação dos buffers de saída
- ob_gzhandler — Função de callback para ob_start para compactar com gzip o buffer de saída
- ob_implicit_flush — Ativa ou desativa o descarregar implicito
- ob_list_handlers — List all output handlers in use
- ob_start — Ativa o buffer de saída
- output_add_rewrite_var — Add URL rewriter values
- output_reset_rewrite_vars — Reset URL rewriter values
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Exemplos
- Funções para Control de Saída
- flush — Descarrega o buffer de saída
- ob_clean — Limpa (apaga) o buffer de saída
- ob_end_clean — Limpa (apaga) o buffer de saída e desativa o buffer de saída
- ob_end_flush — Descarrega (envia) o buffer de saída e desativa o buffer de saída
- ob_flush — Descarrega (envia) o conteúdo do buffer de saída
- ob_get_clean — Obtém o conteudo do buffer e exclui o buffer de saída atual
- ob_get_contents — Retorna o conteúdo do buffer de saída
- ob_get_flush — Flush the output buffer, return it as a string and turn off output buffering
- ob_get_length — Retorna o tamanho do buffer de saída
- ob_get_level — Retorna o nível do mecanismo de buffer de saída
- ob_get_status — Obtém a situação dos buffers de saída
- ob_gzhandler — Função de callback para ob_start para compactar com gzip o buffer de saída
- ob_implicit_flush — Ativa ou desativa o descarregar implicito
- ob_list_handlers — List all output handlers in use
- ob_start — Ativa o buffer de saída
- output_add_rewrite_var — Add URL rewriter values
- output_reset_rewrite_vars — Reset URL rewriter values
Object property and method call overloading
Introdução
O propósito desta extensão é permitir a sobrecarga de propriedades de acesso e métodos de objetos. Somente uma função é definida nesta extensão, overload() que recebe o nome da classe que deve ter esta funcionalidade habilitada. A classe especificada tem que definir os métodos para ter esta funcionalidade: __get(), __set() e __call() respectivamente para leitura/escrita das propriedades, ou chamar um método. Desta forma a sobrecarga pode ser seletiva: Dentro destas funções a sobrecarga é desabilitada de forma que você possa acessar propriedades do objeto normalmente.
Este módulo é EXPERIMENTAL. O comportamento desta extensão — incluindo o nome de suas funções e qualquer outra documentação sobre esta extensão — poderá mudar sem aviso em futuras versões do PHP. Esta extensão deve ser usada por sua própria conta e risco.
Esta extensão não é parte do PHP 5. PHP 5 suporta __get(), __set() e __call() nativamente. Veja a página Sobrecarga no PHP 5 para mais informação.
Instalação/Configuração
Índice
Dependências
Nenhuma biblioteca externa é necessária para compilar esta extensão.
Instalação
Para usar estas funções, você precisa compilar o PHP com a opção --enable-overload . Começando com o PHP 4.3.0 esta extensão é habilitada por padrão. Você pode desabilitá-la com --disable--overload .
A versão para Windows do PHP tem suporte embutido para esta extensão. Você não precisa carregar nenhuma extensão adicional para utilizar essas funções.
Nota: Suporte nativo para overload está disponível com PHP 4.3.0.
Configurações em Execução
Esta extensão não define nenhum parâmetro de configuração no php.ini.
Tipos Resource
Esta extensão não possui nenhum tipo resource.
Constantes pré-definidas
Esta extensão não possui nenhuma constante.
Exemplos
Índice
Um exemplo simples da utilização da função overload():
Exemplo #1 Sobrecarga de uma classe no PHP
<?php
class OO {
var $a = 111;
var $elem = array('b' => 9, 'c' => 42);
// Callback method for getting a property
function __get($prop_name, &$prop_value)
{
if (isset($this->elem[$prop_name])) {
$prop_value = $this->elem[$prop_name];
return true;
} else {
return false;
}
}
// Callback method for setting a property
function __set($prop_name, $prop_value)
{
$this->elem[$prop_name] = $prop_value;
return true;
}
}
// Here we overload the OO object
overload('OO');
$o = new OO;
echo "\$o->a: $o->a\n"; // print: $o->a: 111
echo "\$o->b: $o->b\n"; // print: $o->b: 9
echo "\$o->c: $o->c\n"; // print: $o->c: 42
echo "\$o->d: $o->d\n"; // print: $o->d:
// add a new item to the $elem array in OO
$o->x = 56;
// instantiate stdclass (it is built-in in PHP 4)
// $val is not overloaded!
$val = new stdclass;
$val->prop = 555;
// Set "a" to be an array with the $val object in it
// But __set() will put this in the $elem array
$o->a = array($val);
var_dump($o->a[0]->prop);
?>
Funções para sobrecarga de Objeto
overload
(PHP 4 >= 4.3.0)
overload — Habilita sobrecarga de propriedade e método para uma classe
Descrição
A função overload() habilitará chamada sobrecarregando propriedade e método para uma classe identificada por class_name.
Parâmetros
- class_name
-
O nome da classe a ser sobrecarregada, como uma string
Valor Retornado
Não há valor retornado.
Exemplos
Veja um exemplo na seção introdutória.
Índice
- overload — Habilita sobrecarga de propriedade e método para uma classe
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Exemplos
- Funções para sobrecarga de Objeto
- overload — Habilita sobrecarga de propriedade e método para uma classe
Informações e Opções do PHP
Introdução
Estas funções permitem a você obter muitas informações sobre o PHP em si, ex. Configurações em tempo de execução, extensões carregadas, versão e muito mais. Você também encontrará funções para definir opções durante a execução. A provavelmente mais conhecida função do PHP - phpinfo() - pode ser encontrada aqui.
Instalação/Configuração
Índice
Dependências
Nenhuma biblioteca externa é necessária para compilar esta extensão.
Instalação
Não há nenhuma instalação necessária para utilizar estas funções, elas fazem parte do núcleo do PHP.
Configurações em Execução
O comportamento dessas funções podem ser modificado pelas configurações do php.ini.
| Nome | Padrão | Modificável | Lista de mudanças |
|---|---|---|---|
| assert.active | "1" | PHP_INI_ALL | |
| assert.bail | "0" | PHP_INI_ALL | |
| assert.warning | "1" | PHP_INI_ALL | |
| assert.callback | NULL | PHP_INI_ALL | |
| assert.quiet_eval | "0" | PHP_INI_ALL | |
| enable_dl | "1" | PHP_INI_SYSTEM | Removido no PHP 6.0.0. |
| max_execution_time | "30" | PHP_INI_ALL | |
| max_input_time | "-1" | PHP_INI_PERDIR | Disponível a partir do PHP 4.3.0. |
| max_input_nesting_level | "64" | PHP_INI_PERDIR | Disponível a partir do PHP 4.4.8. Removido no PHP 5.0.0. |
| magic_quotes_gpc | "1" | PHP_INI_PERDIR | PHP_INI_ALL in PHP <= 4.2.3. Remido no PHP 6.0.0. |
| magic_quotes_runtime | "0" | PHP_INI_ALL | Removido no PHP 6.0.0. |
| zend.enable_gc | "1" | PHP_INI_ALL | Disponível desde PHP 5.3.0. |
Breve descrição das diretivas de configuração.
- assert.active boolean
-
Ativa a comparação assert().
- assert.bail boolean
-
Termina a execução do script no caso de uma afirmação(assert) falhar.
- assert.warning boolean
-
Mostra um aviso PHP para cada afirmação(assert) que falhar.
- assert.callback string
-
Função do usuário a ser executado no caso de uma afirmação(assert) falhar.
- assert.quiet_eval boolean
-
Usa o que esta definido atualmente para a função error_reporting() durante a avaliação da afirmação. Se ativado, não são mostrados erros (error_reporting(0) implícito) durante a avaliação. Se desativado, os erros são mostrados de acordo com as definições de error_reporting()
- enable_dl boolean
-
Esta diretiva somente é realmente útil na versão do PHP como módulo do Apache. Você pode mudar o carregamento dinâmico de extensões do PHP com dl() on e off para cada servidor virtual ou por diretório.
A principal razão para mudar o carregamento dinâmico para off é segurança. Com o carregamento dinâmico é possível ignorar todas as restrições de open_basedir. O padrão é permitir o carregamento dinâmico exceto quando usando o safe mode. No safe mode, é sempre impossível usar dl().
- max_execution_time integer
-
Isto define o limite de tempo de execução de um script antes que seja terminado pelo interpretador. Isto ajuda a prevenir que scripts mal escritos serem executados indefinidamente pelo servidor. O padrão é 30. Ao executar o PHP a partir de linha de comando o valor padrão é 0.
O limite de tempo de execução não é afetado por chamadas do sistema, funções de streams, etc. Por favor veja a função set_time_limit() para maiores detalhes.
Você não pode mudar esta definição com a função ini_set() quando estiver executando em safe mode. O único meio de contornar é desativar o safe mode ou mudar o limite de tempo no php.ini.
Seu servidor web pode ter outras configurações de limite de tempo que também interrompar a execução do PHP. O apache tem uma diretiva Timeout e o IIS tem uma função de limite de tempo CGI. O padrão de ambas é 300 segundos. Veja a documentação do seu servidor web para os detalhes especificos.
- max_input_time integer
-
Isto define o tempo máximo em segundos que é permitido para analisar dados de entrada, como POST, GET e upload de arquivos.
- max_input_nesting_level integer
-
Define a profundidade máxima aninhada de variáveis de entrada (i.e. $_GET, $_POST..)
- magic_quotes_gpc boolean
-
Aviso
Este recurso tornou-se OBSOLETO a partir do PHP 5.3.0 REMOVIDO do PHP 6.0.0. Confiar neste recurso é extremamente não recomendado.
Define o estado para as aspas mágicas para operações GPC (Get/Post/Cookie). Quando as aspas mágicas estiverem em on, todas ' (aspas simples), " (aspas duplas), \ (barras invertidas) e NULL's são escapados com uma barra invertida automaticamente.
Nota:
No PHP 4 $_ENV também é escapada.
Nota:
Se a diretiva magic_quotes_sybase também estiver em ON ela irá sobrescrever completamente magic_quotes_gpc. Tendo ambas diretivas ativadas faz com que apenas as aspas simples sejam escapadas como ''. Aspas duplas, barras invertidas e NULL's irão permanecer intocados e não escapados.
Veja também get_magic_quotes_gpc().
- magic_quotes_runtime boolean
-
Aviso
Este recurso tornou-se OBSOLETO a partir do PHP 5.3.0 REMOVIDO do PHP 6.0.0. Confiar neste recurso é extremamente não recomendado.
Se magic_quotes_runtime estiver ativado, a maioria das funções que retornarem dados de qualquer fonte externa incluindo banco de dados e arquivos de texto terão as aspas escapadas com uma barra invertida. Se magic_quotes_sybase também estiver em on, uma aspa simples é escapada com uma aspa simples ao invés de uma barra invertida.
- zend.enable_gc boolean
-
Ativa ou desativa o coletor de referencia circular.
Tipos Resource
Esta extensão não possui nenhum tipo resource.
Constantes pré-definidas
As constantes listadas abaixo estão sempre disponíveis como parte do núcleo do PHP.
| Constante | Valor | Descrição |
|---|---|---|
| CREDITS_GROUP | 1 | Uma lista do núcleo de desenvolvedores |
| CREDITS_GENERAL | 2 | Créditos em geral: design e conceito da linguagem, autores do PHP e do módulo SAPI. |
| CREDITS_SAPI | 4 | Uma lista dos módulos API dos servidores para o PHP, e seus autores. |
| CREDITS_MODULES | 8 | Uma lista dos módulos de extensão para o PHP, e seus autores. |
| CREDITS_DOCS | 16 | Os créditos para a equipe de documentação. |
| CREDITS_FULLPAGE | 32 | Normalmente usada em combinação com as outras opções. Indica que uma pagina HTML completa precisa ser mostrada incluindo a informação indicada pelas outras opções. |
| CREDITS_QA | 64 | Os créditos para a equipe de controle de qualidade. |
| CREDITS_ALL | -1 | Todos os créditos, equivalente a usar: CREDITS_DOCS + CREDITS_GENERAL + CREDITS_GROUP + CREDITS_MODULES + CREDITS_QA CREDITS_FULLPAGE. Gera uma pagina HTML completa com as tags apropriadas. Este é o valor padrão. |
| Constante | Valor | Descrição |
|---|---|---|
| INFO_GENERAL | 1 | A linha da configuração, localização do php.ini, data de construção, servidor web, sistema e mais. |
| INFO_CREDITS | 2 | Créditos do PHP. Veja também phpcredits(). |
| INFO_CONFIGURATION | 4 | Valores atuais e principais para as diretivas de configuração do PHP. Veja também ini_get(). |
| INFO_MODULES | 8 | Módulos carregados e suas respectivas configurações. |
| INFO_ENVIRONMENT | 16 | Informações das variáveis de ambiente que também estão disponíveis em $_ENV. |
| INFO_VARIABLES | 32 | Mostra todas as variáveis pré-definidas a partir de EGPCS (Ambiente, GET, POST, Cookie, Server). |
| INFO_LICENSE | 64 | Informação sobre a licença do PHP. Veja também » a faq sobre licença. |
| INFO_ALL | -1 | Mostra tudo acima. Este é o valor padrão. |
Funções para Opções/Info do PHP
assert_options
(PHP 4, PHP 5)
assert_options — Define/Obtém várias opções do assert
Descrição
Define as várias opções de controle para assert() ou apenas consulta as definições atuais.
Parâmetros
- what
-
Opções Assert opção parâmetro do ini padrão descrição ASSERT_ACTIVE assert.active 1 ativa a avaliação de assert() ASSERT_WARNING assert.warning 1 mostra um aviso do PHP para cada afirmação que falhar ASSERT_BAIL assert.bail 0 termina a execução do script quando uma afirmação falhar ASSERT_QUIET_EVAL assert.quiet_eval 0 desativa error_reporting durante a avaliação da expressão ASSERT_CALLBACK assert.callback (NULL) função do usuário para chamar quando uma afirmação falhar - value
-
Um valor opcional novo para a opção.
Valor Retornado
Retorna a definição original de qualquer opção ou FALSE em caso de erro.
assert
(PHP 4, PHP 5)
assert — Confere se uma afirmação é FALSE
Descrição
assert() se a afirmação assertion é falsa e toma a ação apropriada.
Se o parâmetro assertion é dado como uma string ela será avaliada como código PHP pela função assert(). As vantagens da string assertion são menor sobrecarga quando conferir se a afirmação é verdadeira e mensagens contendo assertion quando a afirmação é falsa. Isto indica que se você passar uma condição booleana(verdadeiro ou falso) como assertion esta condição não será mostrado como parâmetro da função de afirmação, o qual você deve ter definido com a função assert_options(), a condição é convertida para uma string antes que a função gerenciadora seja chamada e o booleano FALSE é convertido para uma string vazia.
Afirmações devem ser usadas apenas com a intenção de eliminar erros. Você deve usa-las para testar condições que devam ser sempre TRUE e que indiquem algum erro de programação se não for ou para verificar a existência de certas coisas como a disponibilidade de funções de algum módulo ou limites e recursos do sistema.
Afirmações não devem ser usadas para operações em tempo de execução normais como para conferir certo valor de entrada. Como uma dica de uso, o seu código deve funcionar corretamente mesmo que o teste de afirmações não esteja ativado.
O funcionamento de assert() pode ser configurado por assert_options() ou pelas configurações descritas na pagina do manual para estas funções.
A função assert_options() e/ou a diretiva de configuração ASSERT_CALLBACK permitem configurar uma função para ser chamada no caso de falha da afirmação.
Funções chamadas a partir de falhas de assert() são particularmente úteis quando estiver criando sistemas automáticos para testes porque permitem que você capture facilmente o código passado para a afirmação em conjunto com informações sobre onde a afirmação foi feita. Enquanto esta informação pode ser capturada por outros métodos, usar afirmações torna muito mais fácil e rápido!
A função utilizada para processar as afirmações devem aceitar três argumentos. O primeiro irá conter o arquivo onde houve a falha na afirmação. O segundo argumento irá conter a linha onde a afirmação falhou e o terceiro argumento irá conter a expressão que falhou (se houver alguma - valores literais como 1 ou "dois" não serão passados por este argumento).
Parâmetros
- assertion
-
A afirmação.
Valor Retornado
FALSE se a afirmação for falsa, TRUE se não.
Exemplos
Exemplo #1 Gerenciando uma afirmação que falhou com uma função do usuário
<?php
// Ativa as afirmações e as deixa quietas
assert_options(ASSERT_ACTIVE, 1);
assert_options(ASSERT_WARNING, 0);
assert_options(ASSERT_QUIET_EVAL, 1);
// Cria a função do usuário que será chamada quando a afirmação falhar
function my_assert_handler($file, $line, $code)
{
echo "<hr>Afirmação falhou:
Arquivo '$file'<br />
Linha '$line'<br />
Código '$code'<br /><hr />";
}
// Define a função
assert_options(ASSERT_CALLBACK, 'my_assert_handler');
// Faz uma afirmação que irá falhar
assert('mysql_query ("")');
?>
dl
(PHP 4, PHP 5)
dl — Carrega uma extensão do PHP durante a execução
Descrição
Carrega a extensão do PHP indicada pelo parâmetro library.
Use extension_loaded() para testar se uma extensão esta disponível ou não. Isto funciona para extensões internas e para aquelas carregadas dinamicamente (através do php.ini ou da função dl()).
Parâmetros
- library
-
Este parâmetro é somente o nome do arquivo da exdtensão a carregar o qual também depende da sua plataforma. Por exemplo, a extensão sockets (se compilada como módulo compartilhado, não o padrão!) seria chamada sockets.so em plataformas Unix enquanto é chamada php_sockets.dll na plataforma Windows.
O diretório a partir do qual a extensão é carregada depende da sua plataforma:
Windows - Se for explicitamente definido no php.ini, a extensão é carregada a partir de c:\php4\extensions\ por padrão.
Unix - Se não for explicitamente definido no php.ini, o diretório padrão das extensões depende de
- se o PHP foi compilado com --enable-debug ou não
- se o PHP foi compilado com suporte (experimental) ZTS (Zend Thread Safety) ou não
- O ZEND_MODULE_API_NO (o número Zend internal module API, o que é basicamente a data onde houve uma mudança maior na API ex. 20010901)
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas. Se a funcionalidade de carregar os módulos não estiver disponível (veja a nota) ou foi desabilitada (ou por desativar enable_dl ou por ativar safe mode no php.ini) um E_ERROR é emitido e a execução é parada. Se dl() falhar porque a bliblioteca especificada mão puder ser carregada, em adição a FALSE uma mensagem E_WARNING é emitida.
Exemplos
Exemplo #1 Exemplosdl()
<?php
// Example loading an extension based on OS
if (!extension_loaded('sqlite')) {
if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
dl('php_sqlite.dll');
} else {
dl('sqlite.so');
}
}
// Or, the PHP_SHLIB_SUFFIX constant is available as of PHP 4.3.0
if (!extension_loaded('sqlite')) {
$prefix = (PHP_SHLIB_SUFFIX === 'dll') ? 'php_' : '';
dl($prefix . 'sqlite.' . PHP_SHLIB_SUFFIX);
}
?>
Notas
Nota:
dl() não e suportado em servidores multi-tarefa. Useextensions no seu php.ini quando estiver operando em um ambiente assim. Em todo o caso, as versões CGI e CLI não são afetadas!
Nota:
A partir do PHP 5, a função dl() esta obsoleta em todas as SAPI exceto CLI. Use o método de Diretivas para Carregar Extensões ao invés.
Nota:
Desde o PHP 6 esta função esta desabilitada em todas as SAPIs, exceto CLI, CGI e embutida.
Nota:
dl() diferencia maiúsculas e minúsculas em plataformas Unix.
Nota: Esta função é desabilitada quando o PHP é executado em safe-mode
Veja Também
- Diretivas para Carregar Extensões
- extension_loaded() - Indica quando uma extensão esta carregada
extension_loaded
(PHP 4, PHP 5)
extension_loaded — Indica quando uma extensão esta carregada
Descrição
Descobre se uma extensão esta carregada.
Parâmetros
- name
-
O nome da extensão.
Você poderá ver os nomes de várias extensões usando phpinfo() ou se estiver usando a versão CGI ou CLI do PHP você poderá usar a opção -m para listar todas as extensões disponíveis:
$ php -m [PHP Modules] xml tokenizer standard sockets session posix pcre overload mysql mbstring ctype [Zend Modules]
Valor Retornado
Retorna true TRUE se a extensão identificada por name esta carregada, FALSE se não.
Exemplos
Exemplo #1 Exemplo extension_loaded()
<?php
if (!extension_loaded('gd')) {
if (!dl('gd.so')) {
exit;
}
}
?>
Notas
Nota:
extension_loaded() usa o nome interno da extensão para testar se uma extensão esta disponível ou não. A maioria dos nomes internos esta escrita em minúsculas mas algumas extensões podem ter letras maiúsculas. Tenha cuidado que esta função diferencia maiúsculas e minúsculas!
Veja Também
- get_loaded_extensions() - Retorna uma matriz com os nomes de todos os módulos compilados e carregados
- get_extension_funcs() - Retorna uma matriz com os nomes de funções de um módulo
- phpinfo() - Mostra muitas informações sobre o PHP
- dl() - Carrega uma extensão do PHP durante a execução
gc_collect_cycles
(PHP 5 >= 5.3.0)
gc_collect_cycles — Forces collection of any existing garbage cycles
Descrição
Forces collection of any existing garbage cycles.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Returns number of collected cycles.
gc_disable
(PHP 5 >= 5.3.0)
gc_disable — Deactivates the circular reference collector
Descrição
Deactivates the circular reference collector, setting zend.enable_gc to 0.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Não há valor retornado.
gc_enable
(PHP 5 >= 5.3.0)
gc_enable — Activates the circular reference collector
Descrição
Activates the circular reference collector, setting zend.enable_gc to 1.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Não há valor retornado.
gc_enabled
(PHP 5 >= 5.3.0)
gc_enabled — Returns status of the circular reference collector
Descrição
Returns status of the circular reference collector.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Returns TRUE if the garbage collector is enabled, FALSE otherwise.
Exemplos
Exemplo #1 A gc_enabled() example
<?php
if(gc_enabled()) gc_collect_cycles();
?>
get_cfg_var
(PHP 4, PHP 5)
get_cfg_var — Obtém o valor de uma opção de configuração do PHP
Descrição
Retorna o valor atual da variável de configuração do PHP especificada por varname, ou FALSE se houver um erro.
Não irá retornar informação de configuração definidas quando o PHP foi compilado, ou lidas a partir de um arquivo de configuração do PHP (usando as diretivas php3).
Para saber se um sistema esta usando um arquivo de configuração, tente obter o valor da configuração cfg_file_path. Se estiver disponível então um arquivo de configuração esta sendo usado..
Veja também ini_get().
get_current_user
(PHP 4, PHP 5)
get_current_user — Obtém o nome do dono do script PHP atual
Descrição
Retorna o nome do dono do script PHP atual.
Valor Retornado
Retorna o username como uma string.
Veja Também
- getmyuid() - Obtém o UID do dono do script PHP
- getmygid() - Obtém o GID do dono do script PHP
- getmypid() - Obtém o ID do processo PHP
- getmyinode() - Obtém o inode do script atual
- getlastmod() - Obtém o tempo da última modificação na pagina
get_defined_constants
(PHP 4 >= 4.1.0, PHP 5)
get_defined_constants — Retorna uma matriz associativa com os nomes de todas as constantes e seus valores
Descrição
Retorna os nomes e os valores de todas as constantes definidas atualmente. Isto inclui aquelas criadas pelas extensões assim como as criadas com a função define().
Parâmetros
- categorize
-
Pode ser passado, modificando o retorno da função para um array multidimensional onde as categorias são as chaves da primeira dimensão e constantes e seus valores na segunda dimensão.
<?php
define("MY_CONSTANT", 1);
print_r(get_defined_constants(true));
?>O exemplo acima irá imprimir algo similar a:
Array ( [internal] => Array ( [E_ERROR] => 1 [E_WARNING] => 2 [E_PARSE] => 4 [E_NOTICE] => 8 [E_CORE_ERROR] => 16 [E_CORE_WARNING] => 32 [E_COMPILE_ERROR] => 64 [E_COMPILE_WARNING] => 128 [E_USER_ERROR] => 256 [E_USER_WARNING] => 512 [E_USER_NOTICE] => 1024 [E_ALL] => 2047 [TRUE] => 1 ) [pcre] => Array ( [PREG_PATTERN_ORDER] => 1 [PREG_SET_ORDER] => 2 [PREG_OFFSET_CAPTURE] => 256 [PREG_SPLIT_NO_EMPTY] => 1 [PREG_SPLIT_DELIM_CAPTURE] => 2 [PREG_SPLIT_OFFSET_CAPTURE] => 4 [PREG_GREP_INVERT] => 1 ) [user] => Array ( [MY_CONSTANT] => 1 ) )Nota:
O valor do parâmetro categorize é irrelevante, somente fornecê-lo é considerado.
Valor Retornado
Histórico
| Versão | Descrição |
|---|---|
| 5.0.0 | O parâmetro categorize foi adicionado. |
Exemplos
Exemplo #1 Exemplo da get_defined_constants()
<?php
print_r(get_defined_constants());
?>
O exemplo acima irá imprimir algo similar a:
Array
(
[E_ERROR] => 1
[E_WARNING] => 2
[E_PARSE] => 4
[E_NOTICE] => 8
[E_CORE_ERROR] => 16
[E_CORE_WARNING] => 32
[E_COMPILE_ERROR] => 64
[E_COMPILE_WARNING] => 128
[E_USER_ERROR] => 256
[E_USER_WARNING] => 512
[E_USER_NOTICE] => 1024
[E_ALL] => 2047
[TRUE] => 1
)
Veja Também
- defined() - Confere se uma constante existe
- get_loaded_extensions() - Retorna uma matriz com os nomes de todos os módulos compilados e carregados
- get_defined_functions() - Retorna um array de todas as funções definidas
- get_defined_vars() - Retorna o array com todas variáveis definidas
get_extension_funcs
(PHP 4, PHP 5)
get_extension_funcs — Retorna uma matriz com os nomes de funções de um módulo
Descrição
Esta função retorna o nome de todas as funções definidas no módulo indicado por module_name.
Parâmetros
- module_name
-
O nome do módulo.
Nota:
Este parâmetro precisa ser em minúsculo.
Valor Retornado
Retorna um array com todas as funções, ou FALSE se module_name não for uma extensão válida.
Exemplos
Exemplo #1 Imprime as funções de XML
<?php
print_r(get_extension_funcs("xml"));
?>
O exemplo acima irá imprimir algo similar a:
Array
(
[0] => xml_parser_create
[1] => xml_parser_create_ns
[2] => xml_set_object
[3] => xml_set_element_handler
[4] => xml_set_character_data_handler
[5] => xml_set_processing_instruction_handler
[6] => xml_set_default_handler
[7] => xml_set_unparsed_entity_decl_handler
[8] => xml_set_notation_decl_handler
[9] => xml_set_external_entity_ref_handler
[10] => xml_set_start_namespace_decl_handler
[11] => xml_set_end_namespace_decl_handler
[12] => xml_parse
[13] => xml_parse_into_struct
[14] => xml_get_error_code
[15] => xml_error_string
[16] => xml_get_current_line_number
[17] => xml_get_current_column_number
[18] => xml_get_current_byte_index
[19] => xml_parser_free
[20] => xml_parser_set_option
[21] => xml_parser_get_option
[22] => utf8_encode
[23] => utf8_decode
)
Veja Também
- get_loaded_extensions() - Retorna uma matriz com os nomes de todos os módulos compilados e carregados
get_include_path
(PHP 4 >= 4.3.0, PHP 5)
get_include_path — Obtém a opção de configuração include_path atual
Descrição
Obtém o valor atual da opção de configuração include_path.
Valor Retornado
Retorna o caminho, como uma string.
Exemplos
Exemplo #1 Exemplo get_include_path()
<?php
// Funciona a partir do PHP 4.3.0
echo get_include_path();
// Funciona em todas as versões do PHP
echo ini_get('include_path');
?>
Veja Também
- ini_get() - Obtém o valor de uma opção de configuração
- restore_include_path() - Restaura o valor da opção de configuração include_path
- set_include_path() - Define a opção de configuração include_path
- include()
get_included_files
(PHP 4, PHP 5)
get_included_files — Retorna uma matriz com os nomes dos arquivos incluídos ou requeridos
Descrição
Retorna uma matriz com os nomes de todos os arquivos que foram incluídos usando as funções include(), include_once(), require() ou require_once().
O script chamado originalmente é considerado um "arquivo incluído", assim será listado junto com os arquivos referenciados por include() e família.
Arquivos que forem incluídos ou requeridos varias vezes aparecem somente uma vez na matriz.
Nota:
Arquivos incluídos usando a diretiva de configuração auto_prepend_file não são incluídos na matriz retornada.
Exemplo #1 Exemplo get_included_files() (abc.php)
<?php
include 'test1.php';
include_once 'test2.php';
require 'test3.php';
require_once 'test4.php';
$included_files = get_included_files();
foreach ($included_files as $filename) {
echo "$filename\n";
}
?>
Irá gerar a seguinte saída:
abc.php test1.php test2.php test3.php test4.php
Nota:
No PHP 4.0.1pl2 e versões anteriores get_included_files() assume que os arquivos requeridos terminem com a extensão .php; outras extensões não serão retornadas. A matriz retornada por get_included_files() era uma matriz associativa e listava somente os arquivos incluídos pelas funções include() e include_once().
Veja também include(), include_once(), require(), require_once() e get_required_files().
get_loaded_extensions
(PHP 4, PHP 5)
get_loaded_extensions — Retorna uma matriz com os nomes de todos os módulos compilados e carregados
Descrição
Retorna uma matriz com os nomes de todos os módulos compilados e carregados no interpretador PHP.
Parâmetros
- zend_extensions
-
Retorna zend_extensions ou não, padrão é FALSE (não há lista de zend_extensions).
Valor Retornado
Retorna um array indexado de todos os nomes de módulos.
Histórico
| Versão | Descrição |
|---|---|
| 5.2.4 | O parâmetro opcional zend_extensions foi adicionado |
Exemplos
Exemplo #1 Exemplo da get_loaded_extensions()
<?php
print_r(get_loaded_extensions());
?>
O exemplo acima irá imprimir algo similar a:
Array ( [0] => xml [1] => wddx [2] => standard [3] => session [4] => posix [5] => pgsql [6] => pcre [7] => gd [8] => ftp [9] => db [10] => calendar [11] => bcmath )
Veja Também
- get_extension_funcs() - Retorna uma matriz com os nomes de funções de um módulo
- extension_loaded() - Indica quando uma extensão esta carregada
- dl() - Carrega uma extensão do PHP durante a execução
- phpinfo() - Mostra muitas informações sobre o PHP
get_magic_quotes_gpc
(PHP 4, PHP 5)
get_magic_quotes_gpc — Obtém a configuração atual de magic quotes gpc
Descrição
Retorna a configuração atual definida para magic_quotes_gpc
Lembre-se que a configuração magic_quotes_gpc não irá funcionar em runtime.
Para mais informação sobre magic_quotes, veja a seção de segurança.
Valor Retornado
Retorna 0 se magic quotes gpc está off, 1 caso contrário.
Exemplos
Exemplo #1 Exemplo get_magic_quotes_gpc()
<?php
echo get_magic_quotes_gpc(); // 1
echo $_POST['lastname']; // O\'reilly
echo addslashes($_POST['lastname']); // O\\\'reilly
if (!get_magic_quotes_gpc()) {
$lastname = addslashes($_POST['lastname']);
} else {
$lastname = $_POST['lastname'];
}
echo $lastname; // O\'reilly
$sql = "INSERT INTO lastnames (lastname) VALUES ('$lastname')";
?>
Notas
Nota:
Se a diretiva magic_quotes_sybase está ON irá completamente sobreescrever magic_quotes_gpc. Sendo assim quando get_magic_quotes_gpc() retorna TRUE nenhuma as dupla, barra invertida ou NUL's ganharão escape. Somente aspas simples ganharão escape. Neste caso teremos: ''
Veja Também
- addslashes() - Adiciona barras invertidas a uma string
- stripslashes() - Desfaz o efeito de addslashes
- get_magic_quotes_runtime() - Obtém a configuração ativa para magic_quotes_runtime
- ini_get() - Obtém o valor de uma opção de configuração
get_magic_quotes_runtime
(PHP 4, PHP 5)
get_magic_quotes_runtime — Obtém a configuração ativa para magic_quotes_runtime
Descrição
Retorna a configuração ativa para magic_quotes_runtime.
Valor Retornado
Retorna 0 se magic quotes runtime está off, 1 caso contrário.
Veja Também
- get_magic_quotes_gpc() - Obtém a configuração atual de magic quotes gpc
- set_magic_quotes_runtime() - Define a configuração atual para magic_quotes_runtime
Descrição
Esta função é um apelido para: get_included_files().
getenv
(PHP 4, PHP 5)
getenv — Obtém uma variável de ambiente
Descrição
Retorna o nome da variável de ambiente varname, ou FALSE em caso de erro.
<?php
$ip = getenv("REMOTE_ADDR"); // obtém o número ip do usuário
?>
Você poderá ver uma lista de todas as variáveis de ambiente usando phpinfo(). Você poderá encontram o que muitas delas indicam dando uma olhada em » CGI specification, especialmente em » page on environmental variables.
Nota:
Esta função não funciona no modo ISAPI.
Veja também putenv().
getlastmod
(PHP 4, PHP 5)
getlastmod — Obtém o tempo da última modificação na pagina
Descrição
Obtém a hora da última modificação da página atual.
Se você está interessado em obter a hora da última modificação de um arquivo diferente, considere usar filemtime().
Valor Retornado
Retorna o tempo da última modificação na pagina atual. O valor é retornado como um Unix timestamp, útil para usar com a função date(). Retorna FALSE em caso de erro.
Exemplos
Exemplo #1 Exemplo da getlastmod()
<?php
// mostra por exemplo 'Última Modificação: March 04 1998 20:43:59.'
echo "Última Modificação: " . date ("F d Y H:i:s.", getlastmod());
?>
Veja Também
- date() - Formata a data e a hora local
- getmyuid() - Obtém o UID do dono do script PHP
- getmygid() - Obtém o GID do dono do script PHP
- get_current_user() - Obtém o nome do dono do script PHP atual
- getmyinode() - Obtém o inode do script atual
- getmypid() - Obtém o ID do processo PHP
- filemtime() - Obtém o tempo de modificação do arquivo
getmygid
(PHP 4 >= 4.1.0, PHP 5)
getmygid — Obtém o GID do dono do script PHP
Descrição
Obtém o ID do grupo do atual script.
Valor Retornado
Retorna o ID do grupo do atual script, ou FALSE em erro.
Veja Também
- getmyuid() - Obtém o UID do dono do script PHP
- getmypid() - Obtém o ID do processo PHP
- get_current_user() - Obtém o nome do dono do script PHP atual
- getmyinode() - Obtém o inode do script atual
- getlastmod() - Obtém o tempo da última modificação na pagina
getmyinode
(PHP 4, PHP 5)
getmyinode — Obtém o inode do script atual
Descrição
Obtém o inode do script atual.
Valor Retornado
Retorna o inode do atual script como um inteiro, ou FALSE em erro.
Notas
Nota: esta função não é implementada na plataforma Windows
getmypid
(PHP 4, PHP 5)
getmypid — Obtém o ID do processo PHP
Descrição
Obtém o ID do atual processo do PHP.
Valor Retornado
Retorna o ID do processo PHP, ou FALSE em caso de erro.
Notas
ID de processo não é único, então são uma fonte de entropia fraca. Nós recomendamos não usas o pid em contextos dependentes de segurança.
Veja Também
- getmygid() - Obtém o GID do dono do script PHP
- getmyuid() - Obtém o UID do dono do script PHP
- get_current_user() - Obtém o nome do dono do script PHP atual
- getmyinode() - Obtém o inode do script atual
- getlastmod() - Obtém o tempo da última modificação na pagina
getmyuid
(PHP 4, PHP 5)
getmyuid — Obtém o UID do dono do script PHP
Descrição
Obtém o ID do usuário do atual script.
Valor Retornado
Retorna o ID do usuário do atual script, ou FALSE em erro.
Veja Também
- getmygid() - Obtém o GID do dono do script PHP
- getmypid() - Obtém o ID do processo PHP
- get_current_user() - Obtém o nome do dono do script PHP atual
- getmyinode() - Obtém o inode do script atual
- getlastmod() - Obtém o tempo da última modificação na pagina
getopt
(PHP 4 >= 4.3.0, PHP 5)
getopt — Obtém opções da lista de argumentos da linha de comando
Descrição
Retorna uma matriz associativa das opções/argumentos baseada no formato especificado no parâmetro options, ou FALSE em caso de erro.
Parâmetros
- options
-
O parâmetro options deve conter os seguintes elementos: caracteres individuais, e caracteres individuais seguidos por dois pontos para indicar uma opção com um argumento a seguir. Por exemplo, a string de opção x reconhece uma opção -x, e uma string de opção x: reconhece uma opção e um argumento -x argumento. Não importa se o argumento tem espaço no início.
- longopts
-
Valor Retornado
Esta função irá retornar uma matriz de opções/argumentos . Se uma opção não tiver argumento o valor definido será FALSE.
Histórico
| Versão | Descrição |
|---|---|
| 5.3.0 | Esta função não depende mais do sistema e funcionando também em Windows. |
Exemplos
Exemplo #1 Exemplo da getopt()
<?php
// parse the command line ($GLOBALS['argv'])
$options = getopt("f:hp:");
?>
getrusage
(PHP 4, PHP 5)
getrusage — Obtém a utilização de recursos
Descrição
Esta é uma interface para getrusage(2). Ela obtém informação retornada pela chamada do sistema.
Parâmetros
- who
-
Se who é 1, getrusage será chamada com RUSAGE_CHILDREN.
Valor Retornado
Retorna um array associativo contendo a informação retornado pela chamada do sistema. Todas entradas são acessíveis usando os seus documentados nomes de campos.
Exemplos
Exemplo #1 Exemplo da getrusage()
<?php
$dat = getrusage();
echo $dat["ru_nswap"]; // number of swaps
echo $dat["ru_majflt"]; // number of page faults
echo $dat["ru_utime.tv_sec"]; // user time used (seconds)
echo $dat["ru_utime.tv_usec"]; // user time used (microseconds)
?>
Notas
Nota: esta função não é implementada na plataforma Windows
Veja Também
- Man page do seu sistema em getrusage(2)
Descrição
Esta função é um apelido para: ini_set().
ini_get_all
(PHP 4 >= 4.2.0, PHP 5)
ini_get_all — Obtém todas as opções de configuração
Descrição
Retorna todas as opções de configuração como uma matriz associativa. Se o parâmetro opcional extension estiver definido, apenas as opções especificas para esta extensão serão retornadas.
A matriz retornada usa o nome da diretiva como chave da matriz sendo os os elementos global_value (definidos no php.ini), local_value (talvez definidos com ini_set() ou .htaccess), e access (o nível de acesso). Veja a seção do manual sobre mudanças de configuração para informações sobre o que são os níveis.
Nota:
É possível para uma diretiva ter múltiplos níveis de acesso, por isso access mostra os valores apropriados como um valor bitmask.
Exemplo #1 Exemplo ini_get_all()
<?php
$inis = ini_get_all();
print_r($inis);
?>
Parte da saída se parece com:
Array
(
[allow_call_time_pass_reference] => Array
(
[global_value] => 1
[local_value] => 1
[access] => 6
)
[allow_url_fopen] => Array
(
[global_value] => 1
[local_value] => 1
[access] => 7
)
...
)
Veja também: ini_get(), ini_restore(), ini_set(), get_loaded_extensions() e phpinfo().
ini_get
(PHP 4, PHP 5)
ini_get — Obtém o valor de uma opção de configuração
Descrição
Retorna o valor da opção em caso de sucesso. Em caso de falha, como tentar obter um valor que não exista, irá retornar uma string vazia.
Nota: Quando obtendo valores booleanos
Um valor booleano off será retornado como uma string vazia enquanto um valor booleano on será retornado como "1".
Nota: Quando obtendo valores de tamanho de memória
Vários valores de definição de tamanho de memória, como upload_max_filesize são guardados no arquivo php.ini em uma anotação curta. ini_get() irá retornar exatamente a string guardada no arquivo php.ini, NÃO o seu valor inteiro equivalente. Tentar funções matemáticas comuns com estes valores não trará o resultado esperado.
<?php
/*
Seu php.ini contém as seguintes definições:
display_errors = On
register_globals = Off
post_max_size = 8M
*/
echo 'display_errors = ' . ini_get('display_errors') . "\n";
echo 'register_globals = ' . ini_get('register_globals') . "\n";
echo 'post_max_size = ' . ini_get('post_max_size') . "\n";
echo 'post_max_size+1 = ' . (ini_get('post_max_size')+1) . "\n";
?>Este script irá produzir:
display_errors = 1 register_globals = 0 post_max_size = 8M post_max_size+1 = 9 */ ?>
Veja também get_cfg_var(), ini_get_all(), ini_restore() e ini_set().
ini_restore
(PHP 4, PHP 5)
ini_restore — Restaura o valor de uma opção de configuração
Descrição
Restaura o valor de uma opção de configuração para o seu valor original.
Parâmetros
- varname
-
O nome da opção de configuração.
Valor Retornado
Não há valor retornado.
Veja Também
- ini_get() - Obtém o valor de uma opção de configuração
- ini_get_all() - Obtém todas as opções de configuração
- ini_set() - Define o valor de uma opção de configuração
ini_set
(PHP 4, PHP 5)
ini_set — Define o valor de uma opção de configuração
Descrição
Define um novo valor para a opção de configuração indicada. A opção de configuração irá manter o novo valor durante a execução do script e será restaurado ao final da execução do script.
Parâmetros
- varname
-
Nem todas as opções disponíveis podem ser modificadas usando a função ini_set(). Há uma lista de todas as opções disponíveis no PHP apêndice.
- newvalue
-
O novo valor para a opção.
Valor Retornado
Retorna o valor anterior em sucesso, FALSE em falha.
Veja Também
- get_cfg_var() - Obtém o valor de uma opção de configuração do PHP
- ini_get() - Obtém o valor de uma opção de configuração
- ini_get_all() - Obtém todas as opções de configuração
- ini_restore() - Restaura o valor de uma opção de configuração
- Como modificar a configuração
Descrição
Esta função é um apelido para: set_magic_quotes_runtime()
main
(No version information available, might only be in SVN)
main — Marcador para main()
Descrição
Não existe função com o nome de main() com exceção no código fonte do PHP. No PHP 4.3.0, um novo tipo de gerenciamento de erro foi introduzido no fonte do PHP (php_error_docref). Uma das funções é prover links para as páginas de manual do PHP nas mensagens de erros quando a diretiva de configuração html_errors (on por padrão) e docref_root (on por padrão até o PHP 4.3.2) estiverem definidas.
Algumas vezes as mensagens de erro se referem a uma página de manual para a função main(), é por isso que esta pagina existe. Por favor adicione um comentário do usuário abaixo que mencione qual função do PHP causou um erro que foi ligado a função main() e será corrigido e propriamente documentado.
| Nome da função | Não aponta para aqui a partir do |
|---|---|
| include() | 5.1.0 |
| include_once() | 5.1.0 |
| require() | 5.1.0 |
| require_once() | 5.1.0 |
memory_get_peak_usage
(PHP 5 >= 5.2.0)
memory_get_peak_usage — Returns the peak of memory allocated by PHP
Descrição
Returns the peak of memory, in bytes, that's been allocated to your PHP script.
Parâmetros
- real_usage
-
Set this to TRUE to get the real size of memory allocated from system. If not set or FALSE only the memory used by emalloc() is reported.
Valor Retornado
Returns the memory peak in bytes.
Histórico
| Versão | Descrição |
|---|---|
| 5.2.1 | Compiling with --enable-memory-limit is no longer required for this function to exist. |
| 5.2.0 | real_usage was added. |
memory_get_usage
(PHP 4 >= 4.3.2, PHP 5)
memory_get_usage — Retorna a quantidade de memória alocada para PHP
Descrição
Retorna a quantidade de memória, em bytes, que esta atualmente alocada para o seu script PHP.
Parâmetros
- real_usage
-
Defina isto para TRUE para obter a quantidade geral de memória alocada pelo sistema. Se não definida ou FALSE somente a memória usada por emalloc() é reportada.
Valor Retornado
Retorna a quantidade de memória em bytes.
Histórico
| Versão | Descrição |
|---|---|
| 5.2.1 | Compilar com --enable-memory-limit não é mais requerido para esta função existir. |
| 5.2.0 | real_usage foi adicionado. |
Exemplos
Exemplo #1 Exemplo da memory_get_usage()
<?php
// Este é apenas um exemplo, os números abaixo
// serão diferentes dependendo do seu sistema
echo memory_get_usage() . "\n"; // 36640
$a = str_repeat("Hello", 4242);
echo memory_get_usage() . "\n"; // 57960
unset($a);
echo memory_get_usage() . "\n"; // 36744
?>
php_ini_loaded_file
(PHP 5 >= 5.2.4)
php_ini_loaded_file — Retrieve a path to the loaded php.ini file
Descrição
Check if a php.ini file is loaded, and retrieve its path.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
The loaded php.ini path, or FALSE if one is not loaded.
Exemplos
Exemplo #1 php_ini_loaded_file() example
<?php
$inipath = php_ini_loaded_file();
if ($inipath) {
echo 'Loaded php.ini: ' . $inipath;
} else {
echo 'A php.ini file is not loaded';
}
?>
O exemplo acima irá imprimir algo similar a:
Loaded php.ini: /usr/local/php/php.ini
Veja Também
- php_ini_scanned_files() - Retorna uma lista dos arquivos ini interpretados a partir do diretório ini adicional
- phpinfo() - Mostra muitas informações sobre o PHP
- The configuration file
php_ini_scanned_files
(PHP 4 >= 4.3.0, PHP 5)
php_ini_scanned_files — Retorna uma lista dos arquivos ini interpretados a partir do diretório ini adicional
Descrição
php_ini_scanned_files() retorna uma lista separada por vírgula dos arquivos interpretados depois do php.ini. Estes arquivos são encontrados no diretório definido pela opção --with-config-file-scan-dir definida durante a compilação.
Retorna uma lista de arquivos ini separados por vírgula em caso de sucesso. Se a diretiva --with-config-files-scan-dir não foi definida é retornado FALSE. Se foi definida e o diretório estiver vazio, uma string vazia é retornada. Se um arquivo estiver irreconhecível, o arquivo ainda fará parte da string retornada, mas também será retornado um erro do PHP. Este erro do PHP será visto em tempo de compilação e quando usar a função php_ini_scanned_files().
Os arquivos de configuração incluem também o caminho incluído em --with-config-file-scan-dir. Também cada vírgula e seguida por uma nova linha.
Exemplo #1 Um exemplo simples para a lista de arquivos ini retornados
<?php
if ($filelist = php_ini_scanned_files()) {
if (strlen($filelist) > 0) {
$files = explode(',', $filelist);
foreach ($files as $file) {
echo "<li>" . trim($file) . "</li>\n";
}
}
}
?>
php_logo_guid
(PHP 4, PHP 5)
php_logo_guid — Obtém o guid do logo
Descrição
Esta função retorna um ID que pode ser utilizado para mostrar o logo do PHP usando uma imagem embutida. O logo é mostrado somente se expose_php está On.
Valor Retornado
Retorna PHPE9568F34-D428-11d2-A769-00AA001ACF42.
Exemplos
Exemplo #1 Exemplo php_logo_uid()
<?php
echo '<img src="' . $_SERVER['PHP_SELF'] .
'?=' . php_logo_guid() . '" alt="PHP Logo !" />';
?>
Veja Também
- phpinfo() - Mostra muitas informações sobre o PHP
- phpversion() - Obtém a versão atual do PHP
- phpcredits() - Mostra os créditos pelo PHP
- zend_logo_guid() - Retorna o guid Zend
php_sapi_name
(PHP 4 >= 4.0.1, PHP 5)
php_sapi_name — Retorna o tipo de interface entre o servidor web e o PHP
Descrição
Retorna uma string minúscula que descreve o tipo de interface entre o servidor web e o PHP (Server API, SAPI). Em CGI PHP, esta string é "cgi", em mod_php para o Apache, esta string é "apache" e assim por diante.
Valor Retornado
Retorna o tipo da interface, como uma string em minúsculo.
Exemplos
Exemplo #1 Exemplo da php_sapi_name()
<?php
$sapi_type = php_sapi_name();
if (substr($sapi_type, 0, 3) == 'cgi') {
echo "You are using CGI PHP\n";
} else {
echo "You are not using CGI PHP\n";
}
?>
php_uname
(PHP 4 >= 4.0.2, PHP 5)
php_uname — Retorna informação sobre o sistema operacional que o PHP foi construído
Descrição
php_uname() retorna uma string com a descrição do sistema operacional que o PHP foi construído. Se você quer apenas o nome do sistema operacional, considere usar a constante PHP_OS.
Exemplo #1 Alguns exemplos de php_uname()
<?php
echo php_uname();
echo PHP_OS;
/* Algumas saídas possíveis:
Linux localhost 2.4.21-0.13mdk #1 Fri Mar 14 15:08:06 EST 2003 i686
Linux
FreeBSD localhost 3.2-RELEASE #15: Mon Dec 17 08:46:02 GMT 2001
FreeBSD
Windows NT XN1 5.1 build 2600
WINNT
*/
if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
echo 'Este é um servidor usando!';
} else {
echo 'Este é um servidor que não usa Windows!';
}
?>
Existem também algumas Constantes pré-definidas que podem ser úteis, por exemplo:
Exemplo #2 Algumas constantes relacionadas com o sistema operacional
<?php
// *nix
echo DIRECTORY_SEPARATOR; // /
echo PHP_SHLIB_SUFFIX; // so
echo PATH_SEPARATOR; // :
// Win*
echo DIRECTORY_SEPARATOR; // \
echo PHP_SHLIB_SUFFIX; // dll
echo PATH_SEPARATOR; // ;
?>
Veja também phpversion(), php_sapi_name() e phpinfo().
phpcredits
(PHP 4, PHP 5)
phpcredits — Mostra os créditos pelo PHP
Descrição
Esta função mostra os créditos devidos aos desenvolvedores do PHP, módulos, etc. É gerado os códigos HTML apropriados para inserir a informação em uma página.
Parâmetros
- flag
-
Para gerar uma página de créditos customizada, você terá que usar o parâmetro flag. flag é opcional, e o padrão é CREDITS_ALL.
Flags pré-definidas da phpcredits() Nome Descrição CREDITS_ALL Todos os créditos, equivalente ao usar: CREDITS_DOCS + CREDITS_GENERAL + CREDITS_GROUP + CREDITS_MODULES + CREDITS_FULLPAGE. Gera uma completa página HTML com as apropriadas tags. CREDITS_DOCS Os créditos para o time da documentação CREDITS_FULLPAGE Normalmente usado na combinação com outras flags. Indica que a completa página HTML precisa ser imprimida incluindo a informação indicada por outras flags. CREDITS_GENERAL Créditos gerais: design da linguagem e conceitos, autores do PHP 4.0 e módulos SAPI. CREDITS_GROUP Uma lista de desenvolvedores do core CREDITS_MODULES Uma lista de módulos para o PHP, e seus autores CREDITS_SAPI Uma lista de módulos server API para o PHP, e seus autores
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 Imprimindo os créditos gerais
<?php
phpcredits(CREDITS_GENERAL);
?>
Exemplo #2 Imprime os desenvolvedores do core e o grupo da documentação
<?php
phpcredits(CREDITS_GROUP + CREDITS_DOCS + CREDITS_FULLPAGE);
?>
Exemplo #3 Imprimindo todos os créditos
<html>
<head>
<title>My credits page</title>
</head>
<body>
<?php
// some code of your own
phpcredits(CREDITS_ALL - CREDITS_FULLPAGE);
// some more code
?>
</body>
</html>
Veja Também
- phpversion() - Obtém a versão atual do PHP
- php_logo_guid() - Obtém o guid do logo
- phpinfo() - Mostra muitas informações sobre o PHP
phpinfo
(PHP 4, PHP 5)
phpinfo — Mostra muitas informações sobre o PHP
Descrição
Mostra uma grande quantidade de informações sobre o estado atual do PHP. Isto inclui informações sobre as opções de compilação do PHP e extensões, a versão do PHP, informações do servidor e ambiente (se compilado como um módulo), o ambiente PHP, informação da versão do SO, caminhos, valores principais e locais das opções de configuração, cabeçalhos HTTP e a licença do PHP.
Devido a configuração em cada sistema ser diferente, a função phpinfo() e normalmente utilizada para conhecer as definições de configuração e as variáveis pré-definidas que estejam disponíveis no sistema. phpinfo() é também é uma ferramenta valiosa para eliminação de erros já que contém todos os dados de EGPCS (Environment, GET, POST, Cookie, Server).
A saída pode ser configurada passando-se uma ou mais das seguintes constants que serão somadas junto com o parâmetro opcional what. Pode combinar as respectivas constantes ou seus valores bit a bit juntos com o operador or.
| Nome (constant) | Valor | Descrição |
|---|---|---|
| INFO_GENERAL | 1 | A linha de configuração, localização do php.ini data de construção, Servidor Web, Sistema e mais. |
| INFO_CREDITS | 2 | Créditos do PHP 4. Veja também phpcredits(). |
| INFO_CONFIGURATION | 4 | Valores locais e principais para as diretivas de configuração do PHP. Veja também ini_get(). |
| INFO_MODULES | 8 | Módulos carregados e suas respectivas configurações. Veja também get_loaded_modules(). |
| INFO_ENVIRONMENT | 16 | Informação das variáveis de ambiente que também esta disponível em $_ENV. |
| INFO_VARIABLES | 32 | Mostra todas as variáveis pré-definidas de EGPCS (Environment, GET, POST, Cookie, Server). |
| INFO_LICENSE | 64 | Informação sobre a Licença do PHP. Veja também o » faq sobre a licença. |
| INFO_ALL | -1 | Mostra tudo acima. Este é o valor padrão. |
Exemplo #1 Exemplos phpinfo()
<?php
// Mostra todas as informações, usa o padrão INFO_ALL
phpinfo();
// Mostra apenas informações dos módulos.
// phpinfo(8) mostra um resultado identico.
phpinfo(INFO_MODULES);
?>
Nota:
Partes da informação mostrada é desabilitada quando a diretiva de configuração expose_php for definida para off. Isto inclui os logos do PHP e Zend, e os créditos.
Nota:
phpinfo() envia texto simples ao invés de HTML quando esta usando o modo CLI.
Veja também phpversion(), phpcredits(), php_logo_guid(), ini_get(), ini_set(), get_loaded_modules(), e a seção sobre Variáveis Pré-definidas.
phpversion
(PHP 4, PHP 5)
phpversion — Obtém a versão atual do PHP
Descrição
Retorna uma string contendo a versão atual do interpretador PHP ou extensão.
Parâmetros
- extension
-
Um opcional nome de extensão.
Valor Retornado
Se o parâmetro opcional extension é especificado, phpversion() retorna a versão desta extensão, ou FALSE se não há informação da versão ou a extensão não está habilitada.
Exemplos
Exemplo #1 Exemplo phpversion()
<?php
// mostra por exemplo 'Versão Atual do PHP: 4.1.1'
echo 'Versão Atual do PHP: ' . phpversion();
// mostra e.g. '2.0' ou nada se a extensão não está habilitada
echo phpversion('tidy');
?>
Notas
Nota:
Esta informação está também disponível na constante pré-definida PHP_VERSION.
Veja Também
- version_compare() - Compares two "PHP-standardized" version number strings
- phpinfo() - Mostra muitas informações sobre o PHP
- phpcredits() - Mostra os créditos pelo PHP
- php_logo_guid() - Obtém o guid do logo
- zend_version() - Obtém a versão da Zend engine que esta sendo executada
putenv
(PHP 4, PHP 5)
putenv — Define o valor de uma variável de ambiente
Descrição
Adiciona setting no ambiente do servidor. A variável de ambiente irá existir somente durante a requisição atual. Ao final da requisição o ambiente é retornado ao seu estado natural.
Definir certas variáveis de ambiente pode ser potencialmente uma brecha de segurança.. A diretiva safe_mode_allowed_env_vars contém uma lista separada por vírgula de prefixos. No modo seguro, o usuário poderá alterar variáveis de ambiente cujo o nome comece por um dos prefixos indicados nesta diretiva. Por padrão os usuários só poderão definir varáveis que comecem com PHP_ (ex.. PHP_FOO=BAR). Nota: se esta diretiva estiver vazia, o PHP permitirá ao usuário modificar QUALQUER variável de ambiente!
A diretiva safe_mode_protected_env_vars contém uma lista separada por vírgula de variáveis de ambiente que o usuário não possa mudar usando putenv(). Estas variáveis serão protegidas mesmo que safe_mode_allowed_env_vars esta definida para permitir muda-las
Parâmetros
- setting
-
A definição, como "FOO=BAR"
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 Definindo uma variável de ambiente
<?php
putenv("UNIQID=$uniqid");
?>
Notas
Esta diretiva tem efeito somente quando safe-mode está ativada!
restore_include_path
(PHP 4 >= 4.3.0, PHP 5)
restore_include_path — Restaura o valor da opção de configuração include_path
Descrição
Restaura a opção de configuração include_path de volta para o seu valor principal definido no php.ini
Valor Retornado
Não há valor retornado.
Exemplos
Exemplo #1 Exemplo restore_include_path()
<?php
echo get_include_path(); // .:/usr/local/lib/php
set_include_path('/inc');
echo get_include_path(); // /inc
// Funciona a partir do PHP 4.3.0
restore_include_path();
// Funciona em todas as versões do PHP
ini_restore('include_path');
echo get_include_path(); // .:/usr/local/lib/phpp
?>
Veja Também
- ini_restore() - Restaura o valor de uma opção de configuração
- get_include_path() - Obtém a opção de configuração include_path atual
- set_include_path() - Define a opção de configuração include_path
- include()
set_include_path
(PHP 4 >= 4.3.0, PHP 5)
set_include_path — Define a opção de configuração include_path
Descrição
Define a opção de configuração include_path pela duração do script. Retorna o valor anterior de include_path em caso de sucesso ou FALSE em caso de falha.
Exemplo #1 Exemplo set_include_path()
<?php
// Funciona a partir do PHP 4.3.0
set_include_path('/inc');
// Funciona em todas as versões
ini_set('include_path', '/inc');
?>
Exemplo #2 Adicionando mais entradas ao include path
Através do uso da constante PATH_SEPARATOR, é possível extender o include path sem levar em consideração o sistema operacional.
Neste exemplo, nós adicionamos /usr/lib/pear ao final do include_path existente.
<?php
$path = '/usr/lib/pear';
set_include_path(get_include_path() . PATH_SEPARATOR . $path);
?>
Veja também ini_set(), get_include_path(), restore_include_path() e include().
set_magic_quotes_runtime
(PHP 4, PHP 5)
set_magic_quotes_runtime — Define a configuração atual para magic_quotes_runtime
Descrição
Define a configuração atual pata magic_quotes_runtime.
Parâmetros
- new_setting
-
0 para off, 1 para on.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Veja Também
- get_magic_quotes_gpc() - Obtém a configuração atual de magic quotes gpc
- get_magic_quotes_runtime() - Obtém a configuração ativa para magic_quotes_runtime
set_time_limit
(PHP 4, PHP 5)
set_time_limit — Limita o tempo de execução do script
Descrição
Define o número de segundos durante os quais é permitido a execução do script. Se este limite é atingido, o script retorna um erro fatal. O limite padrão é de 30 segundos, ou se existir o valor definido o valor max_execution_time definido no php.ini. Se seconds for definido como zero, não é imposto nenhum limite.
Quando utilizada, set_time_limit() reinicia o contador do limite do tempo a partir de zero. Em outras palavras, se o limite for 30 segundos, e 25 segundos depois do inicio da execução do script for utilizada a função com por exemplo, set_time_limit(20), o script será executado por 45 segundos até acabar o tempo.
set_time_limit() não tem efeito quando o PHP esta sendo executado em safe mode. Não existe como contornar sem desabilitar o safe mode ou mudar o limite de tempo no php.ini.
Nota:
A função set_time_limit() e a diretiva de configuração max_execution_time somente afetam a execução do script em si mesmo. Qualquer tempo gasto com atividades que aconteçam fora da execução do script como chamadas de sistema usando system(), operações de streams, consultas em banco de dados, etc. não é incluso ao determinar o limite de tempo que o script esta sendo executado.
Veja também: max_execution_time e max_input_time.
sys_get_temp_dir
(PHP 5 >= 5.2.1)
sys_get_temp_dir — Returns directory path used for temporary files
Descrição
Returns the path of the directory PHP stores temporary files in by default.
Valor Retornado
Returns the path of the temporary directory.
Exemplos
Exemplo #1 sys_get_temp_dir() example
<?php
// Create a temporary file in the temporary
// files directory using sys_get_temp_dir()
$temp_file = tempnam(sys_get_temp_dir(), 'Tux');
echo $temp_file;
?>
O exemplo acima irá imprimir algo similar a:
C:\Windows\Temp\TuxA318.tmp
version_compare
(PHP 4 >= 4.1.0, PHP 5)
version_compare — Compares two "PHP-standardized" version number strings
Descrição
version_compare() compares two "PHP-standardized" version number strings. This is useful if you would like to write programs working only on some versions of PHP.
The function first replaces _, - and + with a dot . in the version strings and also inserts dots . before and after any non number so that for example '4.3.2RC1' becomes '4.3.2.RC.1'. Then it splits the results like if you were using explode('.', $ver). Then it compares the parts starting from left to right. If a part contains special version strings these are handled in the following order: any string not found in this list < dev < alpha = a < beta = b < RC = rc < # < pl = p. This way not only versions with different levels like '4.1' and '4.1.2' can be compared but also any PHP specific version containing development state.
Parâmetros
- version1
-
First version number.
- version2
-
Second version number.
- operator
-
If you specify the third optional operator argument, you can test for a particular relationship. The possible operators are: <, lt, <=, le, >, gt, >=, ge, ==, =, eq, !=, <>, ne respectively.
This parameter is case-sensitive, so values should be lowercase.
Valor Retornado
By default, version_compare() returns -1 if the first version is lower than the second, 0 if they are equal, and 1 if the second is lower.
When using the optional operator argument, the function will return TRUE if the relationship is the one specified by the operator, FALSE otherwise.
Exemplos
The examples below use the PHP_VERSION constant, because it contains the value of the PHP version that is executing the code.
Exemplo #1 version_compare() examples
<?php
if (version_compare(PHP_VERSION, '6.0.0') >= 0) {
echo 'I am at least PHP version 6.0.0, my version: ' . PHP_VERSION . "\n";
}
if (version_compare(PHP_VERSION, '5.3.0') >= 0) {
echo 'I am at least PHP version 5.3.0, my version: ' . PHP_VERSION . "\n";
}
if (version_compare(PHP_VERSION, '5.0.0', '>=')) {
echo 'I am using PHP 5, my version: ' . PHP_VERSION . "\n";
}
if (version_compare(PHP_VERSION, '5.0.0', '<')) {
echo 'I am using PHP 4, my version: ' . PHP_VERSION . "\n";
}
?>
Notas
Nota:
The PHP_VERSION constant holds current PHP version.
Nota:
Note that pre-release versions, such as 5.3.0-dev, are considered lower than their final release counterparts (like 5.3.0).
Veja Também
- phpversion() - Obtém a versão atual do PHP
- php_uname() - Retorna informação sobre o sistema operacional que o PHP foi construído
- function_exists() - Retorna TRUE se a função dada está definida
zend_logo_guid
(PHP 4, PHP 5)
zend_logo_guid — Retorna o guid Zend
Descrição
Esta função retorna um ID que pode ser usado para mostrar o logo da Zend usando uma imagem embutida.
Valor Retornado
Retorna PHPE9568F35-D428-11d2-A769-00AA001ACF42.
Exemplos
Exemplo #1 Exemplo da zend_logo_guid()
<?php
echo '<img src="' . $_SERVER['PHP_SELF'] .
'?=' . zend_logo_guid() . '" alt="Zend Logo !" />';
?>
zend_thread_id
(PHP 5)
zend_thread_id — Returns a unique identifier for the current thread
Descrição
This function returns a unique identifier for the current thread.
Valor Retornado
Returns the thread id as an integer.
Exemplos
Exemplo #1 zend_thread_id() example
<?php
$thread_id = zend_thread_id();
echo 'Current thread id is: ' . $thread_id;
?>
O exemplo acima irá imprimir algo similar a:
Current thread id is: 7864
Notas
Nota:
This function is only available if PHP has been built with ZTS (Zend Thread Safety) support and debug mode (--enable-debug).
zend_version
(PHP 4, PHP 5)
zend_version — Obtém a versão da Zend engine que esta sendo executada
Descrição
Retorna uma string contendo a versão atual da Zend Engine que esta sendo executada.
Valor Retornado
Retorna o número da versão da Zend Engine, como uma string.
Exemplos
Exemplo #1 Exemplo zend_version()
<?php
echo "Zend engine version: " . zend_version();
?>
O exemplo acima irá imprimir algo similar a:
Zend engine version: 2.2.0
Veja Também
- phpinfo() - Mostra muitas informações sobre o PHP
- phpcredits() - Mostra os créditos pelo PHP
- php_logo_guid() - Obtém o guid do logo
- phpversion() - Obtém a versão atual do PHP
Índice
- assert_options — Define/Obtém várias opções do assert
- assert — Confere se uma afirmação é FALSE
- dl — Carrega uma extensão do PHP durante a execução
- extension_loaded — Indica quando uma extensão esta carregada
- gc_collect_cycles — Forces collection of any existing garbage cycles
- gc_disable — Deactivates the circular reference collector
- gc_enable — Activates the circular reference collector
- gc_enabled — Returns status of the circular reference collector
- get_cfg_var — Obtém o valor de uma opção de configuração do PHP
- get_current_user — Obtém o nome do dono do script PHP atual
- get_defined_constants — Retorna uma matriz associativa com os nomes de todas as constantes e seus valores
- get_extension_funcs — Retorna uma matriz com os nomes de funções de um módulo
- get_include_path — Obtém a opção de configuração include_path atual
- get_included_files — Retorna uma matriz com os nomes dos arquivos incluídos ou requeridos
- get_loaded_extensions — Retorna uma matriz com os nomes de todos os módulos compilados e carregados
- get_magic_quotes_gpc — Obtém a configuração atual de magic quotes gpc
- get_magic_quotes_runtime — Obtém a configuração ativa para magic_quotes_runtime
- get_required_files — Sinônimo de get_included_files
- getenv — Obtém uma variável de ambiente
- getlastmod — Obtém o tempo da última modificação na pagina
- getmygid — Obtém o GID do dono do script PHP
- getmyinode — Obtém o inode do script atual
- getmypid — Obtém o ID do processo PHP
- getmyuid — Obtém o UID do dono do script PHP
- getopt — Obtém opções da lista de argumentos da linha de comando
- getrusage — Obtém a utilização de recursos
- ini_alter — Sinônimo de ini_set
- ini_get_all — Obtém todas as opções de configuração
- ini_get — Obtém o valor de uma opção de configuração
- ini_restore — Restaura o valor de uma opção de configuração
- ini_set — Define o valor de uma opção de configuração
- magic_quotes_runtime — Sinônimo de set_magic_quotes_runtime
- main — Marcador para main
- memory_get_peak_usage — Returns the peak of memory allocated by PHP
- memory_get_usage — Retorna a quantidade de memória alocada para PHP
- php_ini_loaded_file — Retrieve a path to the loaded php.ini file
- php_ini_scanned_files — Retorna uma lista dos arquivos ini interpretados a partir do diretório ini adicional
- php_logo_guid — Obtém o guid do logo
- php_sapi_name — Retorna o tipo de interface entre o servidor web e o PHP
- php_uname — Retorna informação sobre o sistema operacional que o PHP foi construído
- phpcredits — Mostra os créditos pelo PHP
- phpinfo — Mostra muitas informações sobre o PHP
- phpversion — Obtém a versão atual do PHP
- putenv — Define o valor de uma variável de ambiente
- restore_include_path — Restaura o valor da opção de configuração include_path
- set_include_path — Define a opção de configuração include_path
- set_magic_quotes_runtime — Define a configuração atual para magic_quotes_runtime
- set_time_limit — Limita o tempo de execução do script
- sys_get_temp_dir — Returns directory path used for temporary files
- version_compare — Compares two "PHP-standardized" version number strings
- zend_logo_guid — Retorna o guid Zend
- zend_thread_id — Returns a unique identifier for the current thread
- zend_version — Obtém a versão da Zend engine que esta sendo executada
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Funções para Opções/Info do PHP
- assert_options — Define/Obtém várias opções do assert
- assert — Confere se uma afirmação é FALSE
- dl — Carrega uma extensão do PHP durante a execução
- extension_loaded — Indica quando uma extensão esta carregada
- gc_collect_cycles — Forces collection of any existing garbage cycles
- gc_disable — Deactivates the circular reference collector
- gc_enable — Activates the circular reference collector
- gc_enabled — Returns status of the circular reference collector
- get_cfg_var — Obtém o valor de uma opção de configuração do PHP
- get_current_user — Obtém o nome do dono do script PHP atual
- get_defined_constants — Retorna uma matriz associativa com os nomes de todas as constantes e seus valores
- get_extension_funcs — Retorna uma matriz com os nomes de funções de um módulo
- get_include_path — Obtém a opção de configuração include_path atual
- get_included_files — Retorna uma matriz com os nomes dos arquivos incluídos ou requeridos
- get_loaded_extensions — Retorna uma matriz com os nomes de todos os módulos compilados e carregados
- get_magic_quotes_gpc — Obtém a configuração atual de magic quotes gpc
- get_magic_quotes_runtime — Obtém a configuração ativa para magic_quotes_runtime
- get_required_files — Sinônimo de get_included_files
- getenv — Obtém uma variável de ambiente
- getlastmod — Obtém o tempo da última modificação na pagina
- getmygid — Obtém o GID do dono do script PHP
- getmyinode — Obtém o inode do script atual
- getmypid — Obtém o ID do processo PHP
- getmyuid — Obtém o UID do dono do script PHP
- getopt — Obtém opções da lista de argumentos da linha de comando
- getrusage — Obtém a utilização de recursos
- ini_alter — Sinônimo de ini_set
- ini_get_all — Obtém todas as opções de configuração
- ini_get — Obtém o valor de uma opção de configuração
- ini_restore — Restaura o valor de uma opção de configuração
- ini_set — Define o valor de uma opção de configuração
- magic_quotes_runtime — Sinônimo de set_magic_quotes_runtime
- main — Marcador para main
- memory_get_peak_usage — Returns the peak of memory allocated by PHP
- memory_get_usage — Retorna a quantidade de memória alocada para PHP
- php_ini_loaded_file — Retrieve a path to the loaded php.ini file
- php_ini_scanned_files — Retorna uma lista dos arquivos ini interpretados a partir do diretório ini adicional
- php_logo_guid — Obtém o guid do logo
- php_sapi_name — Retorna o tipo de interface entre o servidor web e o PHP
- php_uname — Retorna informação sobre o sistema operacional que o PHP foi construído
- phpcredits — Mostra os créditos pelo PHP
- phpinfo — Mostra muitas informações sobre o PHP
- phpversion — Obtém a versão atual do PHP
- putenv — Define o valor de uma variável de ambiente
- restore_include_path — Restaura o valor da opção de configuração include_path
- set_include_path — Define a opção de configuração include_path
- set_magic_quotes_runtime — Define a configuração atual para magic_quotes_runtime
- set_time_limit — Limita o tempo de execução do script
- sys_get_temp_dir — Returns directory path used for temporary files
- version_compare — Compares two "PHP-standardized" version number strings
- zend_logo_guid — Retorna o guid Zend
- zend_thread_id — Returns a unique identifier for the current thread
- zend_version — Obtém a versão da Zend engine que esta sendo executada
runkit
Introdução
The runkit extension provides means to modify constants, user-defined functions, and user-defined classes. It also provides for custom superglobal variables and embeddable sub-interpreters via sandboxing.
This package is meant as a feature added replacement for the » classkit package. When compiled with the --enable-runkit=classkit option to ./configure, it will export classkit compatible function definitions and constants.
Constantes pré-definidas
As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.
- RUNKIT_IMPORT_FUNCTIONS (integer)
- runkit_import() flag indicating that normal functions should be imported from the specified file.
- RUNKIT_IMPORT_CLASS_METHODS (integer)
- runkit_import() flag indicating that class methods should be imported from the specified file.
- RUNKIT_IMPORT_CLASS_CONSTS (integer)
- runkit_import() flag indicating that class constants should be imported from the specified file. Note that this flag is only meaningful in PHP versions 5.1.0 and above.
- RUNKIT_IMPORT_CLASS_PROPS (integer)
- runkit_import() flag indicating that class standard properties should be imported from the specified file.
- RUNKIT_IMPORT_CLASSES (integer)
- runkit_import() flag representing a bitwise OR of the RUNKIT_IMPORT_CLASS_* constants.
- RUNKIT_IMPORT_OVERRIDE (integer)
- runkit_import() flag indicating that if any of the imported functions, methods, constants, or properties already exist, they should be replaced with the new definitions. If this flag is not set, then any imported definitions which already exist will be discarded.
- RUNKIT_ACC_PUBLIC (integer)
- PHP 5 specific flag to runkit_method_add()
- RUNKIT_ACC_PROTECTED (integer)
- PHP 5 specific flag to runkit_method_add()
- RUNKIT_ACC_PRIVATE (integer)
- PHP 5 specific flag to runkit_method_add()
- CLASSKIT_ACC_PUBLIC (integer)
- PHP 5 specific flag to classkit_method_add() Only defined when classkit compatibility is enabled.
- CLASSKIT_ACC_PROTECTED (integer)
- PHP 5 specific flag to classkit_method_add() Only defined when classkit compatibility is enabled.
- CLASSKIT_ACC_PRIVATE (integer)
- PHP 5 specific flag to classkit_method_add() Only defined when classkit compatibility is enabled.
- CLASSKIT_AGGREGATE_OVERRIDE (integer)
- PHP 5 specific flag to classkit_import() Only defined when classkit compatibility is enabled.
- RUNKIT_VERSION (string)
- Defined to the current version of the runkit package.
- CLASSKIT_VERSION (string)
- Defined to the current version of the runkit package. Only defined when classkit compatibility is enabled.
Instalação/Configuração
Índice
Dependências
Modifying Constants, Functions, Classes, and Methods works with all releases of PHP 4 and PHP 5. No special requirements are necessary.
Custom Superglobals are only available in PHP 4.2.0 or later.
Sandboxing requires PHP 5.1.0 or later, or PHP 5.0.0 with a special TSRM patch applied. Regardless of which version of PHP is in use it must be compiled with the --enable-maintainer-zts option. See the README file in the runkit package for additional information.
Instalação
Esta extensão » PECL não vem compilada com o PHP.
Informações para a instalação desta extensão PECL podem ser encontradas no manual no capitulo intitulado Instalação de extensões PECL. Informações adicionais como novas versões, downloads, arquivos fontes, manutenções, e um Changelog, podem ser obtidos aqui: » http://pecl.php.net/package/runkit.
Uma DLL para esta extenção PECL esta atualmente indisponível. Veja também a seção compilando no Windows section.
Configurações em Execução
O comportamento dessas funções podem ser modificado pelas configurações do php.ini.
| Nome | Padrão | Modificável | Histórico |
|---|---|---|---|
| runkit.superglobal | "" | PHP_INI_PERDIR | |
| runkit.internal_override | "0" | PHP_INI_SYSTEM |
Breve descrição das diretivas de configuração.
- runkit.superglobal string
-
Comma-separated list of variable names to be treated as superglobals.
This value should be set in the systemwide php.ini file, but may work
in perdir configuration contexts depending on your SAPI.
Exemplo #1 Custom Superglobals with runkit.superglobal=_FOO,_BAR in php.ini
<?php
function show_values() {
echo "Foo is $_FOO\n";
echo "Bar is $_BAR\n";
echo "Baz is $_BAZ\n";
}
$_FOO = 'foo';
$_BAR = 'bar';
$_BAZ = 'baz';
/* Displays foo and bar, but not baz */
show_values();
?> - runkit.internal_override boolean
- Enables ability to modify/rename/remove internal functions.
Tipos Resource
Esta extensão não possui nenhum tipo resource.
runkit Funções
Runkit_Sandbox
(PECL runkit >= 0.7.0)
Runkit_Sandbox — Runkit Sandbox Class -- PHP Virtual Machine
Descrição
Instantiating the Runkit_Sandbox class creates a new thread with its own scope and program stack. Using a set of options passed to the constructor, this environment may be restricted to a subset of what the primary interpreter can do and provide a safer environment for executing user supplied code.
Nota: Suporte para Sandbox (necessário para runkit_lint(), runkit_lint_file(), e a classe Runkit_Sandbox) esta disponível apenas com o PHP 5.1 com versões do PHP 5.0 com patch especial e precisam que seja uma versão segura para thread. Veja o arquivo README incluído no pacote runkit para maiores informações.
Constructor
options is an associative array containing any combination of the special ini options listed below.
- safe_mode
-
If the outer script which is instantiating the Runkit_Sandbox class is configured with safe_mode = off, then safe_mode may be turned on for the sandbox environment. This setting can not be used to disable safe_mode when it's already enabled in the outer script.
- safe_mode_gid
-
If the outer script which is instantiating the Runkit_Sandbox class is configured with safe_mode_gid = on, then safe_mode_gid may be turned off for the sandbox environment. This setting can not be used to enable safe_mode_gid when it's already disabled in the outer script.
- safe_mode_include_dir
-
If the outer script which is instantiating the Runkit_Sandbox class is configured with a safe_mode_include_dir, then a new safe_mode_include_dir may be set for sandbox environments below the currently defined value. safe_mode_include_dir may also be cleared to indicate that the bypass feature is disabled. If safe_mode_include_dir was blank in the outer script, but safe_mode was not enabled, then any arbitrary safe_mode_include_dir may be set while turning safe_mode on.
- open_basedir
-
open_basedir may be set to any path below the current setting of open_basedir. If open_basedir is not set within the global scope, then it is assumed to be the root directory and may be set to any location.
- allow_url_fopen
-
Like safe_mode, this setting can only be made more restrictive, in this case by setting it to FALSE when it is previously set to TRUE
- disable_functions
-
Comma separated list of functions to disable within the sandbox sub-interpreter. This list need not contain the names of the currently disabled functions, they will remain disabled whether listed here or not.
- disable_classes
-
Comma separated list of classes to disable within the sandbox sub-interpreter. This list need not contain the names of the currently disabled classes, they will remain disabled whether listed here or not.
- runkit.superglobal
-
Comma separated list of variables to be treated as superglobals within the sandbox sub-interpreter. These variables will be used in addition to any variables defined internally or through the global runkit.superglobal setting.
- runkit.internal_override
-
Ini option runkit.internal_override may be disabled (but not re-enabled) within sandboxes.
Exemplo #1 Instantiating a restricted sandbox
<?php
$options = array(
'safe_mode'=>true,
'open_basedir'=>'/var/www/users/jdoe/',
'allow_url_fopen'=>'false',
'disable_functions'=>'exec,shell_exec,passthru,system',
'disable_classes'=>'myAppClass');
$sandbox = new Runkit_Sandbox($options);
/* Non-protected ini settings may set normally */
$sandbox->ini_set('html_errors',true);
?>
Accessing Variables
All variables in the global scope of the sandbox environment are accessible as properties of the sandbox object. The first thing to note is that because of the way memory between these two threads is managed, object and resource variables can not currently be exchanged between interpreters. Additionally, all arrays are deep copied and any references will be lost. This also means that references between interpreters are not possible.
Exemplo #2 Working with variables in a sandbox
<?php
$sandbox = new Runkit_Sandbox();
$sandbox->foo = 'bar';
$sandbox->eval('echo "$foo\n"; $bar = $foo . "baz";');
echo "{$sandbox->bar}\n";
if (isset($sandbox->foo)) unset($sandbox->foo);
$sandbox->eval('var_dump(isset($foo));');
?>
O exemplo acima irá imprimir:
bar barbaz bool(false)
Calling PHP Functions
Any function defined within the sandbox may be called as a method on the sandbox object. This also includes a few pseudo-function language constructs: eval(), include(), include_once(), require(), require_once(), echo(), print(), die(), and exit().
Exemplo #3 Calling sandbox functions
<?php
$sandbox = new Runkit_Sandbox();
echo $sandbox->str_replace('a','f','abc');
?>
O exemplo acima irá imprimir:
fbc
When passing arguments to a sandbox function, the arguments are taken from the outer instance of PHP. If you wish to pass arguments from the sandbox's scope, be sure to access them as properties of the sandbox object as illustrated above.
Exemplo #4 Passing arguments to sandbox functions
<?php
$sandbox = new Runkit_Sandbox();
$foo = 'bar';
$sandbox->foo = 'baz';
echo $sandbox->str_replace('a',$foo,'a');
echo $sandbox->str_replace('a',$sandbox->foo,'a');
?>
O exemplo acima irá imprimir:
bar baz
Changing Sandbox Settings
As of runkit version 0.5, certain Sandbox settings may be modified on the fly using ArrayAccess syntax. Some settings, such as active are read-only and meant to provide status information. Other settings, such as output_handler may be set and read much like a normal array offset. Future settings may be write-only, however no such settings currently exist.
| Setting | Type | Purpose | Default |
|---|---|---|---|
| active | Boolean (Read Only) | TRUE if the Sandbox is still in a usable state, FALSE if the request is in bailout due to a call to die(), exit(), or because of a fatal error condition. | TRUE (Initial) |
| output_handler | Callback | When set to a valid callback, all output generated by the Sandbox instance will be processed through the named function. Sandbox output handlers follow the same calling conventions as the system-wide output handler. | None |
| parent_access | Boolean | May the sandbox use instances of the Runkit_Sandbox_Parent class? Must be enabled for other Runkit_Sandbox_Parent related settings to work. | FALSE |
| parent_read | Boolean | May the sandbox read variables in its parent's context? | FALSE |
| parent_write | Boolean | May the sandbox modify variables in its parent's context? | FALSE |
| parent_eval | Boolean | May the sandbox evaluate arbitrary code in its parent's context? DANGEROUS | FALSE |
| parent_include | Boolean | May the sandbox include php code files in its parent's context? DANGEROUS | FALSE |
| parent_echo | Boolean | May the sandbox echo data in its parent's context effectively bypassing its own output_handler? | FALSE |
| parent_call | Boolean | May the sandbox call functions in its parent's context? | FALSE |
| parent_die | Boolean | May the sandbox kill its own parent? (And thus itself) | FALSE |
| parent_scope | Integer | What scope will parental property access look at? 0 == Global scope, 1 == Calling scope, 2 == Scope preceeding calling scope, 3 == The scope before that, etc..., etc... | 0 (Global) |
| parent_scope | String | When parent_scope is set to a string value, it refers to a named array variable in the global scope. If the named variable does not exist at the time of access it will be created as an empty array. If the variable exists but it not an array, a dummy array will be created containing a reference to the named global variable. |
Runkit_Sandbox_Parent
(PECL runkit >= 0.7.0)
Runkit_Sandbox_Parent — Runkit Anti-Sandbox Class
Descrição
Instantiating the Runkit_Sandbox_Parent class from within a sandbox environment created from the Runkit_Sandbox class provides some (controlled) means for a sandbox child to access its parent.
Nota: Suporte para Sandbox (necessário para runkit_lint(), runkit_lint_file(), e a classe Runkit_Sandbox) esta disponível apenas com o PHP 5.1 com versões do PHP 5.0 com patch especial e precisam que seja uma versão segura para thread. Veja o arquivo README incluído no pacote runkit para maiores informações.
In order for any of the Runkit_Sandbox_Parent features to function. Support must be enabled on a per-sandbox basis by enabling the parent_access flag from the parent's context.
Exemplo #1 Working with variables in a sandbox
<?php
$sandbox = new Runkit_Sandbox();
$sandbox['parent_access'] = true;
?>
Accessing the Parent's Variables
Just as with sandbox variable access, a sandbox parent's variables may be read from and written to as properties of the Runkit_Sandbox_Parent class. Read access to parental variables may be enabled with the parent_read setting (in addition to the base parent_access setting). Write access, in turn, is enabled through the parent_write setting.
Unlike sandbox child variable access, the variable scope is not limited to globals only. By setting the parent_scope setting to an appropriate integer value, other scopes in the active call stack may be inspected instead. A value of 0 (Default) will direct variable access at the global scope. 1 will point variable access at whatever variable scope was active at the time the current block of sandbox code was executed. Higher values progress back through the functions that called the functions that led to the sandbox executing code that tried to access its own parent's variables.
Exemplo #2 Accessing parental variables
<?php
$php = new Runkit_Sandbox();
$php['parent_access'] = true;
$php['parent_read'] = true;
$test = "Global";
$php->eval('$PARENT = new Runkit_Sandbox_Parent;');
$php['parent_scope'] = 0;
one();
$php['parent_scope'] = 1;
one();
$php['parent_scope'] = 2;
one();
$php['parent_scope'] = 3;
one();
$php['parent_scope'] = 4;
one();
$php['parent_scope'] = 5;
one();
function one() {
$test = "one()";
two();
}
function two() {
$test = "two()";
three();
}
function three() {
$test = "three()";
$GLOBALS['php']->eval('var_dump($PARENT->test);');
}
?>
O exemplo acima irá imprimir:
string(6) "Global" string(7) "three()" string(5) "two()" string(5) "one()" string(6) "Global" string(6) "Global"
Calling the Parent's Functions
Just as with sandbox access, a sandbox may access its parents functions providing that the proper settings have been enabled. Enabling parent_call will allow the sandbox to call all functions available to the parent scope. Language constructs are each controlled by their own setting: print() and echo() are enabled with parent_echo. die() and exit() are enabled with parent_die. eval() is enabled with parent_eval while include(), include_once(), require(), and require_once() are enabled through parent_include.
runkit_class_adopt
(PECL runkit >= 0.7.0)
runkit_class_adopt — Convert a base class to an inherited class, add ancestral methods when appropriate
Descrição
Parâmetros
- classname
-
Name of class to be adopted
- parentname
-
Parent class which child class is extending
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 A runkit_class_adopt() example
<?php
class myParent {
function parentFunc() {
echo "Parent Function Output\n";
}
}
class myChild {
}
runkit_class_adopt('myChild','myParent');
myChild::parentFunc();
?>
O exemplo acima irá imprimir:
Parent Function Output
Veja Também
- runkit_class_emancipate() - Convert an inherited class to a base class, removes any method whose scope is ancestral
runkit_class_emancipate
(PECL runkit >= 0.7.0)
runkit_class_emancipate — Convert an inherited class to a base class, removes any method whose scope is ancestral
Descrição
Parâmetros
- classname
-
Name of class to emancipate
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 A runkit_class_emancipate() example
<?php
class myParent {
function parentFunc () {
echo "Parent Function Output\n";
}
}
class myChild extends myParent {
}
myChild::parentFunc();
runkit_class_emancipate('myChild');
myChild::parentFunc();
?>
O exemplo acima irá imprimir:
Parent Function Output Fatal error: Call to undefined function: parentFunc() in example.php on line 12
Veja Também
- runkit_class_adopt() - Convert a base class to an inherited class, add ancestral methods when appropriate
runkit_constant_add
(PECL runkit >= 0.7.0)
runkit_constant_add — Similar to define(), but allows defining in class definitions as well
Descrição
Parâmetros
- constname
-
Name of constant to declare. Either a string to indicate a global constant, or classname::constname to indicate a class constant.
- value
-
NULL, Bool, Long, Double, String, or Resource value to store in the new constant.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Veja Também
- define() - Define uma constante
- runkit_constant_redefine() - Redefine an already defined constant
- runkit_constant_remove() - Remove/Delete an already defined constant
runkit_constant_redefine
(PECL runkit >= 0.7.0)
runkit_constant_redefine — Redefine an already defined constant
Descrição
Parâmetros
- constname
-
Constant to redefine. Either string indicating global constant, or classname::constname indicating class constant.
- newvalue
-
New value to assign to constant.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Veja Também
- runkit_constant_add() - Similar to define(), but allows defining in class definitions as well
- runkit_constant_remove() - Remove/Delete an already defined constant
runkit_constant_remove
(PECL runkit >= 0.7.0)
runkit_constant_remove — Remove/Delete an already defined constant
Descrição
Parâmetros
- constname
-
Name of constant to remove. Either a string indicating a global constant, or classname::constname indicating a class constant.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Veja Também
- define() - Define uma constante
- runkit_constant_add() - Similar to define(), but allows defining in class definitions as well
- runkit_constant_redefine() - Redefine an already defined constant
runkit_function_add
(PECL runkit >= 0.7.0)
runkit_function_add — Add a new function, similar to create_function()
Descrição
Parâmetros
- funcname
-
Name of function to be created
- arglist
-
Comma separated argument list
- code
-
Code making up the function
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 A runkit_function_add() example
<?php
runkit_function_add('testme','$a,$b','echo "The value of a is $a\n"; echo "The value of b is $b\n";');
testme(1,2);
?>
O exemplo acima irá imprimir:
The value of a is 1 The value of b is 2
Veja Também
- create_function() - Cria uma função anônima (lambda-style)
- runkit_function_redefine() - Replace a function definition with a new implementation
- runkit_function_copy() - Copy a function to a new function name
- runkit_function_rename() - Change a function's name
- runkit_function_remove() - Remove a function definition
- runkit_method_add() - Dynamically adds a new method to a given class
runkit_function_copy
(PECL runkit >= 0.7.0)
runkit_function_copy — Copy a function to a new function name
Descrição
Parâmetros
- funcname
-
Name of existing function
- targetname
-
Name of new function to copy definition to
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 A runkit_function_copy() example
<?php
function original() {
echo "In a function\n";
}
runkit_function_copy('original','duplicate');
original();
duplicate();
?>
O exemplo acima irá imprimir:
In a function In a function
Veja Também
- runkit_function_add() - Add a new function, similar to create_function
- runkit_function_redefine() - Replace a function definition with a new implementation
- runkit_function_rename() - Change a function's name
- runkit_function_remove() - Remove a function definition
runkit_function_redefine
(PECL runkit >= 0.7.0)
runkit_function_redefine — Replace a function definition with a new implementation
Descrição
Nota: Por padrão, apenas funções do usuário podem ser removidas, renomeadas ou modificadas. Para poder modificar funções internas, você deve ativar a definição runkit.internal_override no php.ini.
Parâmetros
- funcname
-
Name of function to redefine
- arglist
-
New list of arguments to be accepted by function
- code
-
New code implementation
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 A runkit_function_redefine() example
<?php
function testme() {
echo "Original Testme Implementation\n";
}
testme();
runkit_function_redefine('testme','','echo "New Testme Implementation\n";');
testme();
?>
O exemplo acima irá imprimir:
Original Testme Implementation New Testme Implementation
Veja Também
- runkit_function_add() - Add a new function, similar to create_function
- runkit_function_copy() - Copy a function to a new function name
- runkit_function_rename() - Change a function's name
- runkit_function_remove() - Remove a function definition
runkit_function_remove
(PECL runkit >= 0.7.0)
runkit_function_remove — Remove a function definition
Descrição
Nota: Por padrão, apenas funções do usuário podem ser removidas, renomeadas ou modificadas. Para poder modificar funções internas, você deve ativar a definição runkit.internal_override no php.ini.
Parâmetros
- funcname
-
Name of function to be deleted
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Veja Também
- runkit_function_add() - Add a new function, similar to create_function
- runkit_function_copy() - Copy a function to a new function name
- runkit_function_redefine() - Replace a function definition with a new implementation
- runkit_function_rename() - Change a function's name
runkit_function_rename
(PECL runkit >= 0.7.0)
runkit_function_rename — Change a function's name
Descrição
Nota: Por padrão, apenas funções do usuário podem ser removidas, renomeadas ou modificadas. Para poder modificar funções internas, você deve ativar a definição runkit.internal_override no php.ini.
Parâmetros
- funcname
-
Current function name
- newname
-
New function name
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Veja Também
- runkit_function_add() - Add a new function, similar to create_function
- runkit_function_copy() - Copy a function to a new function name
- runkit_function_redefine() - Replace a function definition with a new implementation
- runkit_function_remove() - Remove a function definition
runkit_import
(PECL runkit >= 0.7.0)
runkit_import — Process a PHP file importing function and class definitions, overwriting where appropriate
Descrição
Similar to include() however any code residing outside of a function or class is simply ignored. Additionally, depending on the value of flags, any functions or classes which already exist in the currently running environment will be automatically overwritten by their new definitions.
Parâmetros
- filename
-
Filename to import function and class definitions from
- flags
-
Bitwise OR of the RUNKIT_IMPORT_* family of constants.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
runkit_lint_file
(PECL runkit >= 0.7.0)
runkit_lint_file — Check the PHP syntax of the specified file
Descrição
The runkit_lint_file() function performs a syntax (lint) check on the specified filename testing for scripting errors. This is similar to using php -l from the commandline.
Nota: Suporte para Sandbox (necessário para runkit_lint(), runkit_lint_file(), e a classe Runkit_Sandbox) esta disponível apenas com o PHP 5.1 com versões do PHP 5.0 com patch especial e precisam que seja uma versão segura para thread. Veja o arquivo README incluído no pacote runkit para maiores informações.
Parâmetros
- filename
-
File containing PHP Code to be lint checked
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
runkit_lint
(PECL runkit >= 0.7.0)
runkit_lint — Check the PHP syntax of the specified php code
Descrição
The runkit_lint() function performs a syntax (lint) check on the specified php code testing for scripting errors. This is similar to using php -l from the command line except runkit_lint() accepts actual code rather than a filename.
Nota: Suporte para Sandbox (necessário para runkit_lint(), runkit_lint_file(), e a classe Runkit_Sandbox) esta disponível apenas com o PHP 5.1 com versões do PHP 5.0 com patch especial e precisam que seja uma versão segura para thread. Veja o arquivo README incluído no pacote runkit para maiores informações.
Parâmetros
- code
-
PHP Code to be lint checked
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
runkit_method_add
(PECL runkit >= 0.7.0)
runkit_method_add — Dynamically adds a new method to a given class
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Parâmetros
- classname
-
The class to which this method will be added
- methodname
-
The name of the method to add
- args
-
Comma-delimited list of arguments for the newly-created method
- code
-
The code to be evaluated when methodname is called
- flags
-
The type of method to create, can be RUNKIT_ACC_PUBLIC, RUNKIT_ACC_PROTECTED or RUNKIT_ACC_PRIVATE
Nota:
This parameter is only used as of PHP 5, because, prior to this, all methods were public.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 runkit_method_add() example
<?php
class Example {
function foo() {
echo "foo!\n";
}
}
// create an Example object
$e = new Example();
// Add a new public method
runkit_method_add(
'Example',
'add',
'$num1, $num2',
'return $num1 + $num2;',
RUNKIT_ACC_PUBLIC
);
// add 12 + 4
echo $e->add(12, 4);
?>
O exemplo acima irá imprimir:
16
Veja Também
- runkit_method_copy() - Copies a method from class to another
- runkit_method_redefine() - Dynamically changes the code of the given method
- runkit_method_remove() - Dynamically removes the given method
- runkit_method_rename() - Dynamically changes the name of the given method
- runkit_function_add() - Add a new function, similar to create_function
runkit_method_copy
(PECL runkit >= 0.7.0)
runkit_method_copy — Copies a method from class to another
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Parâmetros
- dClass
-
Destination class for copied method
- dMethod
-
Destination method name
- sClass
-
Source class of the method to copy
- sMethod
-
Name of the method to copy from the source class. If this parameter is omitted, the value of dMethod is assumed.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 runkit_method_copy() example
<?php
class Foo {
function example() {
return "foo!\n";
}
}
class Bar {
// initially, no methods
}
// copy the example() method from the Foo class to the Bar class, as baz()
runkit_method_copy('Bar', 'baz', 'Foo', 'example');
// output copied function
echo Bar::baz();
?>
O exemplo acima irá imprimir:
foo!
Veja Também
- runkit_method_add() - Dynamically adds a new method to a given class
- runkit_method_redefine() - Dynamically changes the code of the given method
- runkit_method_remove() - Dynamically removes the given method
- runkit_method_rename() - Dynamically changes the name of the given method
- runkit_function_copy() - Copy a function to a new function name
runkit_method_redefine
(PECL runkit >= 0.7.0)
runkit_method_redefine — Dynamically changes the code of the given method
Descrição
Nota: Esta função não pode ser usada para manipular o método atualmente em execução (ou emcadeado).
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Parâmetros
- classname
-
The class in which to redefine the method
- methodname
-
The name of the method to redefine
- args
-
Comma-delimited list of arguments for the redefined method
- code
-
The new code to be evaluated when methodname is called
- flags
-
The redefined method can be RUNKIT_ACC_PUBLIC, RUNKIT_ACC_PROTECTED or RUNKIT_ACC_PRIVATE
Nota:
This parameter is only used as of PHP 5, because, prior to this, all methods were public.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 runkit_method_redefine() example
<?php
class Example {
function foo() {
return "foo!\n";
}
}
// create an Example object
$e = new Example();
// output Example::foo() (before redefine)
echo "Before: " . $e->foo();
// Redefine the 'foo' method
runkit_method_redefine(
'Example',
'foo',
'',
'return "bar!\n";',
RUNKIT_ACC_PUBLIC
);
// output Example::foo() (after redefine)
echo "After: " . $e->foo();
?>
O exemplo acima irá imprimir:
Before: foo! After: bar!
Veja Também
- runkit_method_add() - Dynamically adds a new method to a given class
- runkit_method_copy() - Copies a method from class to another
- runkit_method_remove() - Dynamically removes the given method
- runkit_method_rename() - Dynamically changes the name of the given method
- runkit_function_redefine() - Replace a function definition with a new implementation
runkit_method_remove
(PECL runkit >= 0.7.0)
runkit_method_remove — Dynamically removes the given method
Descrição
Nota: Esta função não pode ser usada para manipular o método atualmente em execução (ou emcadeado).
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Parâmetros
- classname
-
The class in which to remove the method
- methodname
-
The name of the method to remove
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 runkit_method_remove() example
<?php
class Example {
function foo() {
return "foo!\n";
}
function bar() {
return "bar!\n";
}
}
// Remove the 'foo' method
runkit_method_remove(
'Example',
'foo'
);
echo implode(' ', get_class_methods('Example'));
?>
O exemplo acima irá imprimir:
bar
Veja Também
- runkit_method_add() - Dynamically adds a new method to a given class
- runkit_method_copy() - Copies a method from class to another
- runkit_method_redefine() - Dynamically changes the code of the given method
- runkit_method_rename() - Dynamically changes the name of the given method
- runkit_function_remove() - Remove a function definition
runkit_method_rename
(PECL runkit >= 0.7.0)
runkit_method_rename — Dynamically changes the name of the given method
Descrição
Nota: Esta função não pode ser usada para manipular o método atualmente em execução (ou emcadeado).
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Parâmetros
- classname
-
The class in which to rename the method
- methodname
-
The name of the method to rename
- newname
-
The new name to give to the renamed method
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 runkit_method_rename() example
<?php
class Example {
function foo() {
return "foo!\n";
}
}
// Rename the 'foo' method to 'bar'
runkit_method_rename(
'Example',
'foo',
'bar'
);
// output renamed function
echo Example::bar();
?>
O exemplo acima irá imprimir:
foo!
Veja Também
- runkit_method_add() - Dynamically adds a new method to a given class
- runkit_method_copy() - Copies a method from class to another
- runkit_method_redefine() - Dynamically changes the code of the given method
- runkit_method_remove() - Dynamically removes the given method
- runkit_function_rename() - Change a function's name
runkit_return_value_used
(PECL runkit >= 0.8.0)
runkit_return_value_used — Determines if the current functions return value will be used
Descrição
Valor Retornado
Returns TRUE if the function's return value is used by the calling scope, otherwise FALSE
Exemplos
Exemplo #1 runkit_return_value_used() example
<?php
function foo() {
var_dump(runkit_return_value_used());
}
foo();
$f = foo();
?>
O exemplo acima irá imprimir:
bool(false) bool(true)
runkit_sandbox_output_handler
(PECL runkit >= 0.7.0)
runkit_sandbox_output_handler — Specify a function to capture and/or process output from a runkit sandbox
Descrição
Ordinarily, anything output (such as with echo() or print()) will be output as though it were printed from the parent's scope. Using runkit_sandbox_output_handler() however, output generated by the sandbox (including errors), can be captured by a function outside of the sandbox.
Nota: Suporte para Sandbox (necessário para runkit_lint(), runkit_lint_file(), e a classe Runkit_Sandbox) esta disponível apenas com o PHP 5.1 com versões do PHP 5.0 com patch especial e precisam que seja uma versão segura para thread. Veja o arquivo README incluído no pacote runkit para maiores informações.
Nota: Deprecated
As of runkit version 0.5, this function is deprecated and is scheduled to be removed from the package prior to a 1.0 release. The output handler for a given Runkit_Sandbox instance may be read/set using the array offset syntax shown on the Runkit_Sandbox class definition page.
Parâmetros
- sandbox
-
Object instance of Runkit_Sandbox class on which to set output handling.
- callback
-
Name of a function which expects one parameter. Output generated by sandbox will be passed to this callback. Anything returned by the callback will be displayed normally. If this parameter is not passed then output handling will not be changed. If a non-truth value is passed, output handling will be disabled and will revert to direct display.
Valor Retornado
Returns the name of the previously defined output handler callback, or FALSE if no handler was previously defined.
Exemplos
Exemplo #1 Feeding output to a variable
<?php
function capture_output($str) {
$GLOBALS['sandbox_output'] .= $str;
return '';
}
$sandbox_output = '';
$php = new Runkit_Sandbox();
runkit_sandbox_output_handler($php, 'capture_output');
$php->echo("Hello\n");
$php->eval('var_dump("Excuse me");');
$php->die("I lost myself.");
unset($php);
echo "Sandbox Complete\n\n";
echo $sandbox_output;
?>
O exemplo acima irá imprimir:
Sandbox Complete Hello string(9) "Excuse me" I lost myself.
runkit_superglobals
(PECL runkit >= 0.7.0)
runkit_superglobals — Return numerically indexed array of registered superglobals
Descrição
Valor Retornado
Returns a numerically indexed array of the currently registered superglobals. i.e. _GET, _POST, _REQUEST, _COOKIE, _SESSION, _SERVER, _ENV, _FILES
Índice
- Runkit_Sandbox — Runkit Sandbox Class -- PHP Virtual Machine
- Runkit_Sandbox_Parent — Runkit Anti-Sandbox Class
- runkit_class_adopt — Convert a base class to an inherited class, add ancestral methods when appropriate
- runkit_class_emancipate — Convert an inherited class to a base class, removes any method whose scope is ancestral
- runkit_constant_add — Similar to define(), but allows defining in class definitions as well
- runkit_constant_redefine — Redefine an already defined constant
- runkit_constant_remove — Remove/Delete an already defined constant
- runkit_function_add — Add a new function, similar to create_function
- runkit_function_copy — Copy a function to a new function name
- runkit_function_redefine — Replace a function definition with a new implementation
- runkit_function_remove — Remove a function definition
- runkit_function_rename — Change a function's name
- runkit_import — Process a PHP file importing function and class definitions, overwriting where appropriate
- runkit_lint_file — Check the PHP syntax of the specified file
- runkit_lint — Check the PHP syntax of the specified php code
- runkit_method_add — Dynamically adds a new method to a given class
- runkit_method_copy — Copies a method from class to another
- runkit_method_redefine — Dynamically changes the code of the given method
- runkit_method_remove — Dynamically removes the given method
- runkit_method_rename — Dynamically changes the name of the given method
- runkit_return_value_used — Determines if the current functions return value will be used
- runkit_sandbox_output_handler — Specify a function to capture and/or process output from a runkit sandbox
- runkit_superglobals — Return numerically indexed array of registered superglobals
- Introdução
- Constantes pré-definidas
- Instalação/Configuração
- runkit Funções
- Runkit_Sandbox — Runkit Sandbox Class -- PHP Virtual Machine
- Runkit_Sandbox_Parent — Runkit Anti-Sandbox Class
- runkit_class_adopt — Convert a base class to an inherited class, add ancestral methods when appropriate
- runkit_class_emancipate — Convert an inherited class to a base class, removes any method whose scope is ancestral
- runkit_constant_add — Similar to define(), but allows defining in class definitions as well
- runkit_constant_redefine — Redefine an already defined constant
- runkit_constant_remove — Remove/Delete an already defined constant
- runkit_function_add — Add a new function, similar to create_function
- runkit_function_copy — Copy a function to a new function name
- runkit_function_redefine — Replace a function definition with a new implementation
- runkit_function_remove — Remove a function definition
- runkit_function_rename — Change a function's name
- runkit_import — Process a PHP file importing function and class definitions, overwriting where appropriate
- runkit_lint_file — Check the PHP syntax of the specified file
- runkit_lint — Check the PHP syntax of the specified php code
- runkit_method_add — Dynamically adds a new method to a given class
- runkit_method_copy — Copies a method from class to another
- runkit_method_redefine — Dynamically changes the code of the given method
- runkit_method_remove — Dynamically removes the given method
- runkit_method_rename — Dynamically changes the name of the given method
- runkit_return_value_used — Determines if the current functions return value will be used
- runkit_sandbox_output_handler — Specify a function to capture and/or process output from a runkit sandbox
- runkit_superglobals — Return numerically indexed array of registered superglobals
Break the silence operator
Introdução
The scream extension gives the possibility to disable the silencing error control operator so all errors are being reported. This feature is controlled by an ini setting.
Instalação/Configuração
Índice
Dependências
PHP version 5.2.0 or greater.
Instalação
Informações para a instalação desta extensão PECL podem ser encontradas no manual no capitulo intitulado Instalação de extensões PECL. Informações adicionais como novas versões, downloads, arquivos fontes, manutenções, e um Changelog, podem ser obtidos aqui: » http://pecl.php.net/package/scream
Configurações em Execução
O comportamento dessas funções podem ser modificado pelas configurações do php.ini.
| Nome | Padrão | Modificável | Changelog |
|---|---|---|---|
| scream.enabled | Off | PHP_INI_ALL |
Breve descrição das diretivas de configuração.
- scream.enabled int
-
Whether or not to enable scream.
Tipos Resource
Esta extensão não possui nenhum tipo resource.
Exemplos
Índice
Example that shows the effect of scream
This example demonstrates how scream affects the behaviour of PHP's error handler.
Exemplo #1 Enabling and disabling scream at runtime
<?php
// Make sure errors will be shown
ini_set('display_errors', true);
error_reporting(E_ALL);
// Disable scream - this is the default and produce an error
ini_set('scream.enabled', false);
echo "Opening http://example.com/not-existing-file\n";
@fopen('http://example.com/not-existing-file', 'r');
// Now enable scream and try again
ini_set('scream.enabled', true);
echo "Opening http://example.com/not-existing-file\n";
@fopen('http://example.com/another-not-existing-file', 'r');
?>
O exemplo acima irá imprimir algo similar a:
Opening http://example.com/not-existing-file Opening http://example.com/not-existing-file Warning: fopen(http://example.com/another-not-existing-file): failed to open stream: HTTP request failed! HTTP/1.1 404 Not Found in example.php on line 14
Nota: Usually one would set this in the php.ini configuration file instead of changing the code.
Weak References
Introdução
Weak references provide a non-intrusive gateway to ephemeral objects. Unlike normal (strong) references, weak references do not prevent the garbage collector from freeing that object. For this reason, an object may be destroyed even though a weak reference to that object still exists. In such conditions, the weak reference seamlessly becomes invalid.
Exemplo #1 Weakref usage example
<?php
class MyClass {
public function __destruct() {
echo "Destroying object!\n";
}
}
$o1 = new MyClass;
$r1 = new Weakref($o1);
if ($r1->valid()) {
echo "Object still exists!\n";
var_dump($r1->get());
} else {
echo "Object is dead!\n";
}
unset($o1);
if ($r1->valid()) {
echo "Object still exists!\n";
var_dump($r1->get());
} else {
echo "Object is dead!\n";
}
?>
O exemplo acima irá imprimir:
Object still exists!
object(MyClass)#1 (0) {
}
Destroying object!
Object is dead!
Instalação/Configuração
Índice
Dependências
Nenhuma biblioteca externa é necessária para compilar esta extensão.
Instalação
Esta extensão » PECL não vem compilada com o PHP.
Informações para a instalação desta extensão PECL podem ser encontradas no manual no capitulo intitulado Instalação de extensões PECL. Informações adicionais como novas versões, downloads, arquivos fontes, manutenções, e um Changelog, podem ser obtidos aqui: » http://pecl.php.net/package/weakref.
Uma DLL para esta extenção PECL esta atualmente indisponível. Veja também a seção compilando no Windows section.
Tipos Resource
Esta extensão não possui nenhum tipo resource.
The Weakref class
(No version information available, might only be in SVN)
Introdução
The Weakref class provides a gateway to objects without preventing the garbage collector from freeing those objects. It also provides a way to turn a weak reference into a strong one.
Sinopse da classe
Exemplos
Exemplo #1 Weakref usage example
<?php
class MyClass {
public function __destruct() {
echo "Destroying object!\n";
}
}
$o1 = new MyClass;
$r1 = new Weakref($o1);
if ($r1->valid()) {
echo "Object still exists!\n";
var_dump($r1->get());
} else {
echo "Object is dead!\n";
}
unset($o1);
if ($r1->valid()) {
echo "Object still exists!\n";
var_dump($r1->get());
} else {
echo "Object is dead!\n";
}
?>
O exemplo acima irá imprimir:
Object still exists!
object(MyClass)#1 (0) {
}
Destroying object!
Object is dead!
Weakref::acquire
(No version information available, might only be in SVN)
Weakref::acquire — Acquires a strong reference on that object
Descrição
Acquires a strong reference on that object, virtually turning the weak reference into a strong one.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Returns TRUE if the reference was valid and could be turned into a strong reference, FALSE otherwise.
Exemplos
Exemplo #1 Weakref::acquire() example
<?php
class MyClass {
public function __destruct() {
echo "Destroying object!\n";
}
}
$o1 = new MyClass;
$r1 = new Weakref($o1);
$r1->acquire();
echo "Unsetting o1...\n";
unset($o1);
$o2 = $r1->get();
$r1->release();
echo "Unsetting o2...\n";
unset($o2);
?>
O exemplo acima irá imprimir:
Unsetting o1... Unsetting o2... Destroying object!
Exemplo #2 Nested acquire/release example
<?php
class MyClass {
public function __destruct() {
echo "Destroying object!\n";
}
}
$o1 = new MyClass;
$r1 = new Weakref($o1);
echo "Acquiring...\n";
$r1->acquire();
echo " Unsetting...\n";
unset($o1);
echo " Acquiring...\n";
$r1->acquire();
echo " Acquiring...\n";
$r1->acquire();
echo " Releasing...\n";
$r1->release();
echo " Releasing...\n";
$r1->release();
echo "Releasing...\n";
$r1->release();
?>
O exemplo acima irá imprimir:
Acquiring...
Unsetting...
Acquiring...
Acquiring...
Releasing...
Releasing...
Releasing...
Destroying object!
Weakref::__construct
(No version information available, might only be in SVN)
Weakref::__construct — Constructs a new weak reference
Descrição
Constructs a new weak reference.
Parâmetros
- object
-
The object to reference.
Valor Retornado
Não há valor retornado.
Exemplos
Exemplo #1 Weakref::__construct() example
<?php
class MyClass {
public function __destruct() {
echo "Destroying object!\n";
}
}
$o1 = new MyClass;
$r1 = new Weakref($o1);
if ($r1->valid()) {
echo "Object still exists!\n";
var_dump($r1->get());
} else {
echo "Object is dead!\n";
}
unset($o1);
if ($r1->valid()) {
echo "Object still exists!\n";
var_dump($r1->get());
} else {
echo "Object is dead!\n";
}
?>
O exemplo acima irá imprimir:
Object still exists!
object(MyClass)#1 (0) {
}
Destroying object!
Object is dead!
Weakref::get
(No version information available, might only be in SVN)
Weakref::get — Returns the object pointed to by the weak reference
Descrição
Returns the object pointed to by the weak reference.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Returns the object if the reference is still valid, NULL otherwise.
Weakref::release
(No version information available, might only be in SVN)
Weakref::release — Releases a previously acquired reference
Descrição
Releases a previously acquired reference. Potentially turning a strong reference back into a weak reference.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Returns TRUE if the reference was previously acquired and thus could be released, FALSE otherwise.
Exemplos
Exemplo #1 Weakref::release() example
<?php
class MyClass {
public function __destruct() {
echo "Destroying object!\n";
}
}
$o1 = new MyClass;
$r1 = new Weakref($o1);
$r1->acquire();
echo "Unsetting o1...\n";
unset($o1);
$o2 = $r1->get();
$r1->release();
echo "Unsetting o2...\n";
unset($o2);
?>
O exemplo acima irá imprimir:
Unsetting o1... Unsetting o2... Destroying object!
Weakref::valid
(No version information available, might only be in SVN)
Weakref::valid — Checks whether the object referenced still exists
Descrição
Checks whether the object referenced still exists.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Returns TRUE if the object still exists and is thus still accessible via Weakref::get(), FALSE otherwise.
Índice
- Weakref::acquire — Acquires a strong reference on that object
- Weakref::__construct — Constructs a new weak reference
- Weakref::get — Returns the object pointed to by the weak reference
- Weakref::release — Releases a previously acquired reference
- Weakref::valid — Checks whether the object referenced still exists
- Introdução
- Instalação/Configuração
- Weakref — The Weakref class
- Weakref::acquire — Acquires a strong reference on that object
- Weakref::__construct — Constructs a new weak reference
- Weakref::get — Returns the object pointed to by the weak reference
- Weakref::release — Releases a previously acquired reference
- Weakref::valid — Checks whether the object referenced still exists
Windows Cache for PHP
Introdução
Windows Cache Extension for PHP is a PHP accelerator that is used to increase the speed of PHP applications running on Windows and Windows Server. Once the Windows Cache Extension for PHP is enabled and loaded by the PHP engine, PHP applications can take advantage of the functionality without any code modifications.
The Windows Cache Extension includes 5 different types of caches. The following describes the purpose of each cache type and the benefits it provides.
-
PHP Opcode Cache - PHP is a script processing engine, which reads an input stream of data that contains text and/or PHP instructions and produces another stream of data, most commonly in the HTML format. This means that on a web server the PHP engine reads, parses, compiles and executes a PHP script each time that it is requested by a Web client. The reading, parsing and compilation operations put additional load on the web server's CPU and file system and thus affect the overall performance of a PHP web application. The PHP bytecode (opcode) cache is used to store the compiled script bytecode in shared memory so that it can be re-used by PHP engine for subsequent executions of the same script.
-
File Cache - Even with the PHP opcode cache enabled, the PHP engine has to accesses the script files on a file system. When PHP scripts are stored on a remote UNC file share, the file operations introduce a significant performance overhead. The Windows Cache Extension for PHP includes a file cache that is used to store the content of the PHP script files in shared memory, which reduces the amount of file system operations performed by PHP engine.
-
Resolve File Path Cache - PHP scripts very often include or operate with files by using relative file paths. Every file path has to be normalized to an absolute file path by the PHP engine. When a PHP application uses many PHP files and accesses them by relative paths, the operation of resolving the paths may negatively impact the application's performance. The Windows Cache Extension for PHP provides a Resolve File Path cache, which is used to store the mappings between relative and absolute file paths, thereby reducing the number of path resolutions that the PHP engine has to perform.
-
User Cache (available since version 1.1.0) - PHP scripts can take advantage of the shared memory cache by using the user cache API's. PHP objects and variables can be stored in the user cache and then re-used on subsequent requests. This can be used to improve performance of PHP scripts and to share the data across multiple PHP processes.
-
Session Handler (available since version 1.1.0) - The WinCache session handler can be used to store the PHP session data in the shared memory cache. This avoids file system operations for reading and writing session data, which improves performance when large amount of data is stored in PHP session.
Instalação/Configuração
Índice
- Dependências
- Instalação
- Configurações em Execução
- WinCache Statistics Script
- WinCache Session Handler
- WinCache Functions Reroutes
- Tipos Resource
Dependências
The extension is currently supported only on the following configurations:
Windows OS:
- Windows XP SP3 with IIS 5.1 and » FastCGI Extension
- Windows Server 2003 with IIS 6.0 and » FastCGI Extension
- Windows Vista SP1 with IIS 7.0 and FastCGI Module
- Windows Server 2008 with IIS 7.0 and FastCGI Module
- Windows 7 with IIS 7.5 and FastCGI Module
- Windows Server 2008 R2 with IIS 7.5 and FastCGI Module
PHP:
- PHP 5.2.X, Non-thread-safe build
- PHP 5.3 X86, Non-thread-safe VC9 build
Nota: The WinCache Extension can only be used when IIS is configured to run PHP via FastCGI.
Instalação
Esta extensão » PECL não vem compilada com o PHP.
Informações para a instalação desta extensão PECL podem ser encontradas no manual no capitulo intitulado Instalação de extensões PECL. Informações adicionais como novas versões, downloads, arquivos fontes, manutenções, e um Changelog, podem ser obtidos aqui: » http://pecl.php.net/package/wincache.
There are two packages for this extension: one package is for PHP versions 5.2.X, and the other package is for PHP 5.3.X. Select the package that is appropriate for the PHP version being used.
To install and enable the extension, follow these steps:
-
Unpack the package into some temporary location.
-
Copy the php_wincache.dll file into the PHP extensions folder. Typically this folder is called "ext" and it is located in the same folder with all PHP binary files. For example: C:\Program Files\PHP\ext.
-
Using a text editor, open the php.ini file, which is usually located in the same folder where all PHP binary files are. For example: C:\Program Files\PHP\php.ini.
-
Add the following line at the end of the php.ini file: extension = php_wincache.dll.
-
Save and close the php.ini file.
-
Recycle the IIS Application Pools for PHP to pick up the configuration changes. To check that the extension has been enabled, create a file called phpinfo.php with a PHP code that calls phpinfo function.
-
Save the phpinfo.php file in the root folder of a IIS web site that uses PHP, then open a browser and make a request to http://localhost/phpinfo.php. Search within the returned web page for a section called wincache. If the extension is enabled, then the phpinfo output will list the configuration settings provided by the WinCache.
Nota: Do not forget to remove phpinfo.php file from the web site's root folder after verifying that extension has been enabled.
Configurações em Execução
O comportamento dessas funções podem ser modificado pelas configurações do php.ini.
The following table lists and explains the configuration settings provided by the WinCache extension:
| Nome | Padrão | Minimum | Maximum | Modificável | Histórico |
|---|---|---|---|---|---|
| wincache.fcenabled | "1" | "0" | "1" | PHP_INI_ALL | Available since WinCache 1.0.0 |
| wincache.fcenabledfilter | "NULL" | "NULL" | "NULL" | PHP_INI_SYSTEM | Available since WinCache 1.0.0 |
| wincache.fcachesize | "24" | "5" | "255" | PHP_INI_SYSTEM | Available since WinCache 1.0.0 |
| wincache.fcndetect | "1" | "0" | "1" | PHP_INI_SYSTEM | Available since WinCache 1.1.0 |
| wincache.maxfilesize | "256" | "10" | "2048" | PHP_INI_SYSTEM | Available since WinCache 1.0.0 |
| wincache.ocenabled | "1" | "0" | "1" | PHP_INI_ALL | Available since WinCache 1.0.0 |
| wincache.ocenabledfilter | "NULL" | "NULL" | "NULL" | PHP_INI_SYSTEM | Available since WinCache 1.0.0 |
| wincache.ocachesize | "96" | "15" | "255" | PHP_INI_SYSTEM | Available since WinCache 1.0.0 |
| wincache.filecount | "4096" | "1024" | "16384" | PHP_INI_SYSTEM | Available since WinCache 1.0.0 |
| wincache.chkinterval | "30" | "0" | "300" | PHP_INI_SYSTEM | Available since WinCache 1.0.0 |
| wincache.ttlmax | "1200" | "0" | "7200" | PHP_INI_SYSTEM | Available since WinCache 1.0.0 |
| wincache.enablecli | 0 | 0 | 1 | PHP_INI_SYSTEM | Available since WinCache 1.0.0 |
| wincache.ignorelist | NULL | NULL | NULL | PHP_INI_ALL | Available since WinCache 1.0.0 |
| wincache.namesalt | NULL | NULL | NULL | PHP_INI_SYSTEM | Available since WinCache 1.0.0 |
| wincache.ucenabled | 1 | 0 | 1 | PHP_INI_SYSTEM | Available since WinCache 1.1.0 |
| wincache.ucachesize | 8 | 5 | 85 | PHP_INI_SYSTEM | Available since WinCache 1.1.0 |
| wincache.scachesize | 8 | 5 | 85 | PHP_INI_SYSTEM | Available since WinCache 1.1.0 |
| wincache.rerouteini | NULL | NULL | NULL | PHP_INI_SYSTEM | Available since WinCache 1.2.0 |
Breve descrição das diretivas de configuração.
- wincache.fcenabled boolean
- Enables or disables the file cache functionality.
- wincache.fcenabledfilter string
- Defines a comma-separated list of IIS web site identifiers where file cache should be enabled or disabled. This setting works in conjunction with wincache.fcenabled: if wincache.fcenabled is set to 1, then the sites listed in the wincache.fcenabledfilter will have the file cache turned off; if wincache.fcenabled is set to 0, then the sites listed in the wincache.fcenabledfilter will have the file cache turned on.
- wincache.fcachesize integer
- Defines the maximum memory size (in megabytes) that is allocated for the file cache. If the total size of all the cached files exceeds the value specified in this setting, then most stale files will be removed from the file cache.
- wincache.fcndetect boolean
- Enables or disables the file change notification detection functionality. If file change notification is supported then it will be used to refresh the opcode and file cache entries as soon as the corresponding files are modified on a file system. If file change notification is not supported, for example when using network file shares, then wincache will poll for file changes at regular time intervals specified by wincache.chkinterval.
- wincache.maxfilesize integer
- Defines the maximum allowed size (in kilobytes) for a single file to be cached. If a file size exceeds the specified value, the file will not be cached. This setting applies to the file cache only.
- wincache.ocenabled boolean
- Enables or disables the opcode cache functionality
- wincache.ocenabledfilter string
- Defines a comma-separated list of IIS web site identifiers where opcode cache should be enabled or disabled. This setting works in conjunction with wincache.ocenabled: if wincache.ocenabled is set to 1, then the sites listed in the wincache.ocenabledfilter will have the opcode cache turned off; if wincache.ocenabled is set to 0, then the sites listed in the wincache.ocenabledfilter will have the opcode cache turned on.
- wincache.ocachesize integer
- Defines the maximum memory size (in megabytes) that is allocated for the opcode cache. If the cached opcode size exceeds the specified value, then most stale opcode will be removed from the cache. Note that the opcode cache size must be at least 3 times bigger than file cache size. If that is not the case the opcode cache size will be automatically increased.
- wincache.filecount integer
- Defines how many files are expected to be cached by the extension, so that appropriate memory size is allocated at the startup time. If the number of files exceeds the specified value, the WinCache will re-allocate more memory as needed.
- wincache.chkinterval integer
- Defines how often (in seconds) the extension checks for file changes in order to refresh the cache. Setting it to 0 will disable the refreshing of the cache. The file changes will not be reflected in the cache unless the cache entry for that file is removed by scavenger or IIS application pool is recycled or wincache_refresh_if_changed function is called.
- wincache.ttlmax integer
- Defines the maximum time to live (in seconds) for a cached entry without being used. Setting it to 0 will disable the cache scavenger, so the cached entries will never be removed from the cache during the lifetime of the IIS worker process.
- wincache.enablecli boolean
- Defines if caching is enabled when PHP is running in command line (CLI) mode.
- wincache.ignorelist string
-
Defines a list of files that should not be cached by the extension. The files list is specified by using file names only, separated by the pipe symbol - "|".
Exemplo #1 wincache.ignorelist example
wincache.ignorelist = "index.php|misc.php|admin.php"
- wincache.namesalt string
- Defines a string that will be used when naming the extension specific objects that are stored in shared memory. This is used to avoid conflicts that may be caused if other applications within an IIS worker process tries to access shared memory. The length of the namesalt string cannot exceed 8 characters.
- wincache.ucenabled boolean
- Enables or disables the user cache functionality.
- wincache.ucachesize integer
- Defines the maximum memory size in megabytes that is allocated for the user cache. If the total size of variables stored in the user cache exceeds the specified value, then the most stale variables will be removed from the cache.
- wincache.scachesize integer
- Defines the maximum memory size in megabytes that is allocated for the session cache. If the total size of data stored in the session cache exceeds the specified value, then the most stale data will be removed from the cache.
- wincache.rerouteini string
- Specifies an absolute or a relateve path to the reroute.ini file that contains the list of PHP functions whose implementation should be replaced with the WinCache function equivalents. If a relative path is specified then it is assumed to be relative to the location of php-cgi.exe file.
WinCache Statistics Script
The installation package for WinCache includes a PHP script, wincache.php, that can be used to obtain cache information and statistics.
If the WinCache extension was installed via the Microsoft Web Platform Installer, then this script is located in %SystemDrive%\Program Files\IIS\Windows Cache for PHP\. On a 64-bit version of the Windows Server operating system, the script is located in %SystemDrive%\Program Files (x86)\IIS\Windows Cache for PHP. If the extension was installed manually, then the wincache.php will be located in the same folder from which the content of the installation package was extracted.
To use wincache.php, copy it into a root folder of a Web site or into any subfolder. To protect the script, open it in any text editor and replace the values for USERNAME and PASSWORD constants. If any other IIS authentication is enabled on the server, then follow the instructions in the comments:
Exemplo #1 Authentication configuration for wincache.php
<?php
/**
* ======================== CONFIGURATION SETTINGS ==============================
* If you do not want to use authentication for this page, set USE_AUTHENTICATION to 0.
* If you use authentication then replace the default password.
*/
define('USE_AUTHENTICATION', 1);
define('USERNAME', 'wincache');
define('PASSWORD', 'wincache');
/**
* The Basic PHP authentication will work only when IIS is configured to support
* Anonymous Authentication' and nothing else. If IIS is configured to support/use
* any other kind of authentication like Basic/Negotiate/Digest etc, this will not work.
* In that case use the array below to define the names of users in your
* domain/network/workgroup which you want to grant access to.
*/
$user_allowed = array('DOMAIN\user1', 'DOMAIN\user2', 'DOMAIN\user3');
/**
* If the array contains string 'all', then all the users authenticated by IIS
* will have access to the page. Uncomment the below line and comment above line
* to grant access to all users who gets authenticated by IIS.
*/
/* $user_allowed = array('all'); */
/** ===================== END OF CONFIGURATION SETTINGS ========================== */
?>
Nota: Always protect the wincache.php script by using either the built-in authentication or the server's authentication mechanism. Leaving this script unprotected may compromise the security of your web application and web server.
WinCache Session Handler
The WinCache session handler (available since WinCache 1.1.0) can be used to configure PHP to store the session data in shared memory session cache. Using shared memory instead of the default file session storage helps improve performance of PHP applications that store large amount of data in session objects. Wincache session cache uses file-backed shared memory, which ensures that the session data is not lost during recycling of IIS application pools.
To configure PHP to use WinCache session handler set the php.ini setting session.save_handler to wincache. By default the Windows temporary file location is used for storing the session data. To change the location of the session file use session.save_path directive.
Exemplo #1 Enabling WinCache session handler
session.save_handler = wincache session.save_path = C:\inetpub\temp\session\
WinCache Functions Reroutes
The WinCache functions reroutes (available since WinCache 1.2.0) can be used to replace built-in PHP functions with their equivalents that are optimized for a particular purpose. WinCache extension includes Windows-optimized implementation of PHP file functions that may improve performance of PHP applications in cases when PHP has to access files on network shares. The optimized implementation is provided for the following functions:
To configure WinCache to use the functions reroutes use the file reroute.ini that is included in WinCache installation package. Copy this file into the same directory where php.ini file is located. After that add the wincache.rerouteini setting in php.ini and specify an absolute or relative path to the reroute.ini file.
Exemplo #1 Enabling WinCache functions reroutes
wincache.rerouteini = C:\PHP\reroute.ini
Nota: If WinCache functions reroutes are enabled it is recommended to increase the WinCache file cache size. This can be done by using wincache.fcachesize setting.
The reroute.ini file contains the mappings between the native PHP functions and their equivalents in WinCache. Each line in the file defines a mapping by using the following syntax:
<PHP function name>:[<number of function parameters>]=<wincache function name>
The example of the file is shown below. In this example the calls to PHP function file_get_contents() will be replaced with calls to wincache_file_get_contents() only if the number of parameters passed to the function is less than or equals to 2. Specifying the number of parameters is useful when replacement function does not handle all the function's parameters.
Exemplo #2 Reroute.ini file content
[FunctionRerouteList] file_exists=wincache_file_exists file_get_contents:2=wincache_file_get_contents readfile:2=wincache_readfile is_readable=wincache_is_readable is_writable=wincache_is_writable is_writeable=wincache_is_writable is_file=wincache_is_file is_dir=wincache_is_dir realpath=wincache_realpath filesize=wincache_filesize
Tipos Resource
Esta extensão não possui nenhum tipo resource.
Constantes pré-definidas
Esta extensão não possui nenhuma constante.
WinCache Funções
wincache_fcache_fileinfo
(PECL wincache >= 1.0.0)
wincache_fcache_fileinfo — Retrieves information about files cached in the file cache
Descrição
Retrieves information about file cache content and its usage.
Parâmetros
- summaryonly
-
Controls whether the returned array will contain information about individual cache entries along with the file cache summary.
Valor Retornado
Array of meta data about file cache or FALSE on failure
The array returned by this function contains the following elements:
- total_cache_uptime - total time in seconds that the file cache has been active
- total_file_count - total number of files that are currently in the file cache
- total_hit_count - number of times the files have been served from the file cache
- total_miss_count - number of times the files have not been found in the file cache
-
file_entries - an array that contains the information about all the cached files:
- file_name - absolute file name of the cached file
- add_time - time in seconds since the file has been added to the file cache
- use_time - time in seconds since the file has been accessed in the file cache
- last_check - time in seconds since the file has been checked for modifications
- hit_count - number of times the file has been served from the cache
- file_size - size of the cached file in bytes
Exemplos
Exemplo #1 A wincache_fcache_fileinfo() example
<pre>
<?php
print_r(wincache_fcache_fileinfo());
?>
</pre>
O exemplo acima irá imprimir:
Array
( [total_cache_uptime] => 3234
[total_file_count] => 5
[total_hit_count] => 0
[total_miss_count] => 1
[file_entries] => Array
(
[1] => Array
(
[file_name] => c:\inetpub\wwwroot\checkcache.php
[add_time] => 1
[use_time] => 0
[last_check] => 1
[hit_count] => 1
[file_size] => 2435
)
[2] => Array (...iterates for each cached file)
)
)
Veja Também
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_ocache_meminfo() - Retrieves information about opcode cache memory usage
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage
wincache_fcache_meminfo
(PECL wincache >= 1.0.0)
wincache_fcache_meminfo — Retrieves information about file cache memory usage
Descrição
Retrieves information about memory usage by file cache.
Valor Retornado
Array of meta data about file cache memory usage or FALSE on failure
The array returned by this function contains the following elements:
- memory_total - amount of memory in bytes allocated for the file cache
- memory_free - amount of free memory in bytes available for the file cache
- num_used_blks - number of memory blocks used by the file cache
- num_free_blks - number of free memory blocks available for the file cache
- memory_overhead - amount of memory in bytes used for the file cache internal structures
Exemplos
Exemplo #1 A wincache_fcache_meminfo() example
<pre>
<?php
print_r(wincache_fcache_meminfo());
?>
</pre>
O exemplo acima irá imprimir:
Array
(
[memory_total] => 134217728
[memory_free] => 131339120
[num_used_blks] => 361
[num_free_blks] => 3
[memory_overhead] => 5856
)
Veja Também
- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_ocache_meminfo() - Retrieves information about opcode cache memory usage
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage
wincache_lock
(PECL wincache >= 1.1.0)
wincache_lock — Acquires an exclusive lock on a given key
Descrição
Obtains an exclusive lock on a given key. The execution of the current script will be blocked until the lock can be obtained. Once the lock is obtained, the other scripts that try to request the lock by using the same key will be blocked, until the current script releases the lock by using wincache_unlock().
Using of the wincache_lock() and wincache_unlock() can cause deadlocks when executing PHP scripts in a multi-process environment like FastCGI. Do not use these functions unless you are absolutely sure you need to use them. For the majority of the operations on the user cache it is not necessary to use these functions.
Parâmetros
- key
-
Name of the key in the cache to get the lock on.
- isglobal
-
Controls whether the scope of the lock is system-wide or local. Local locks are scoped to the application pool in IIS FastCGI case or to all php processes that have the same parent process identifier.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 Using wincache_lock()
<?php
$fp = fopen("/tmp/lock.txt", "r+");
if (wincache_lock(“lock_txt_lock”)) { // do an exclusive lock
ftruncate($fp, 0); // truncate file
fwrite($fp, "Write something here\n");
wincache_unlock(“lock_txt_lock”); // release the lock
} else {
echo "Couldn't get the lock!";
}
fclose($fp);
?>
Veja Também
- wincache_unlock() - Releases an exclusive lock on a given key
- wincache_ucache_set() - Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_ucache_get() - Gets a variable stored in the user cache
- wincache_ucache_delete() - Deletes variables from the user cache
- wincache_ucache_clear() - Deletes entire content of the user cache
- wincache_ucache_exists() - Checks if a variable exists in the user cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
wincache_ocache_fileinfo
(PECL wincache >= 1.0.0)
wincache_ocache_fileinfo — Retrieves information about files cached in the opcode cache
Descrição
Retrieves information about opcode cache content and its usage.
Parâmetros
- summaryonly
-
Controls whether the returned array will contain information about individual cache entries along with the opcode cache summary.
Valor Retornado
Array of meta data about opcode cache or FALSE on failure
The array returned by this function contains the following elements:
- total_cache_uptime - total time in seconds that the opcode cache has been active
- total_file_count - total number of files that are currently in the opcode cache
- total_hit_count - number of times the compiled opcode have been served from the cache
- total_miss_count - number of times the compiled opcode have not been found in the cache
- is_local_cache - true is the cache metadata is for a local cache instance, false if the metadata is for the global cache
-
file_entries - an array that contains the information about all the cached files:
- file_name - absolute file name of the cached file
- add_time - time in seconds since the file has been added to the opcode cache
- use_time - time in seconds since the file has been accessed in the opcode cache
- last_check - time in seconds since the file has been checked for modifications
- hit_count - number of times the file has been served from the cache
- function_count - number of functions in the cached file
- class_count - number of classes in the cached file
Exemplos
Exemplo #1 A wincache_ocache_fileinfo() example
<pre>
<?php
print_r(wincache_ocache_fileinfo());
?>
</pre>
O exemplo acima irá imprimir:
Array
(
[total_cache_uptime] => 17357
[total_file_count] => 121
[total_hit_count] => 36562
[total_miss_count] => 201
[file_entries] => Array
(
[1] => Array
(
[file_name] => c:\inetpub\wwwroot\checkcache.php
[add_time] => 17356
[use_time] => 7
[last_check] => 10
[hit_count] => 454
[function_count] => 0
[class_count] => 1
)
[2] => Array (...iterates for each cached file)
)
)
Veja Também
- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_meminfo() - Retrieves information about opcode cache memory usage
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage
wincache_ocache_meminfo
(PECL wincache >= 1.0.0)
wincache_ocache_meminfo — Retrieves information about opcode cache memory usage
Descrição
Retrieves information about memory usage by opcode cache.
Valor Retornado
Array of meta data about opcode cache memory usage or FALSE on failure
The array returned by this function contains the following elements:
- memory_total - amount of memory in bytes allocated for the opcode cache
- memory_free - amount of free memory in bytes available for the opcode cache
- num_used_blks - number of memory blocks used by the opcode cache
- num_free_blks - number of free memory blocks available for the opcode cache
- memory_overhead - amount of memory in bytes used for the opcode cache internal structures
Exemplos
Exemplo #1 A wincache_ocache_meminfo() example
<pre>
<?php
print_r(wincache_ocache_meminfo());
?>
</pre>
O exemplo acima irá imprimir:
Array
(
[memory_total] => 134217728
[memory_free] => 112106972
[num_used_blks] => 15469
[num_free_blks] => 4
[memory_overhead] => 247600
)
Veja Também
- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage
wincache_refresh_if_changed
(PECL wincache >= 1.0.0)
wincache_refresh_if_changed — Refreshes the cache entries for the cached files
Descrição
Refreshes the cache entries for the files, whose names were passed in the input argument. If no argument is specified then refreshes all the entries in the cache.
Parâmetros
- files
-
An array of file names for files that need to be refreshed. An absolute or relative file paths can be used.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
WinCache performs regular checks on the cached files to ensure that if any file has changed then the corresponding entry in the cache is updated. By default this check is performed every 30 seconds. If, for example, a PHP script updates another PHP script where the application's configuration settings are stored, then it may happen that after the configuration settings have been saved to a file, the application is still using old settings for some time until the cache is refreshed. In those cases it may be preferrable to refresh the cache right after the file has been changed. The following example shows how this can be done.
Exemplo #1 A wincache_refresh_if_changed() example
<?php
$filename = 'C:\inetpub\wwwroot\config.php';
$handle = fopen($filename, 'w+');
if ($handle === FALSE) die('Failed to open file '.$filename.' for writing');
fwrite($handle, '<?php $setting=something; ?>');
fclose($handle);
wincache_refresh_if_changed(array($filename));
?>
Veja Também
- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_ocache_meminfo() - Retrieves information about opcode cache memory usage
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
wincache_rplist_fileinfo
(PECL wincache >= 1.0.0)
wincache_rplist_fileinfo — Retrieves information about resolve file path cache
Descrição
Retrieves information about cached mappings between relative file paths and corresponding absolute file paths.
Valor Retornado
Array of meta data about the resolve file path cache or FALSE on failure
The array returned by this function contains the following elements:
- total_file_count - total number of file path mappings stored in the cache
-
rplist_entries - an array that contains the information about all the cached file paths:
- resolve_path - path to a file
- subkey_data - corresponding absolute path to a file
Exemplos
Exemplo #1 A wincache_rplist_fileinfo() example
<pre>
<?php
print_r(wincache_rplist_fileinfo());
?>
</pre>
O exemplo acima irá imprimir:
Array
(
[total_file_count] => 5
[rplist_entries] => Array
(
[1] => Array
(
[resolve_path] => checkcache.php
[subkey_data] => c:\inetpub\wwwroot|c:\inetpub\wwwroot\checkcache.php
)
[2] => Array (...iterates for each cached file)
)
)
Veja Também
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_ocache_meminfo() - Retrieves information about opcode cache memory usage
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage
wincache_rplist_meminfo
(PECL wincache >= 1.0.0)
wincache_rplist_meminfo — Retrieves information about memory usage by the resolve file path cache
Descrição
Retrieves information about memory usage by resolve file path cache.
Valor Retornado
Array of meta data that describes memory usage by resolve file path cache. or FALSE on failure
The array returned by this function contains the following elements:
- memory_total - amount of memory in bytes allocated for the resolve file path cache
- memory_free - amount of free memory in bytes available for the resolve file path cache
- num_used_blks - number of memory blocks used by the resolve file path cache
- num_free_blks - number of free memory blocks available for the resolve file path cache
- memory_overhead - amount of memory in bytes used for the internal structures of resolve file path cache
Exemplos
Exemplo #1 A wincache_rplist_meminfo() example
<pre>
<?php
print_r(wincache_rplist_meminfo());
?>
</pre>
O exemplo acima irá imprimir:
Array
(
[memory_total] => 9437184
[memory_free] => 9416744
[num_used_blks] => 23
[num_free_blks] => 1
[memory_overhead] => 416
)
Veja Também
- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_ocache_meminfo() - Retrieves information about opcode cache memory usage
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage
wincache_scache_info
(PECL wincache >= 1.1.0)
wincache_scache_info — Retrieves information about files cached in the session cache
Descrição
Retrieves information about session cache content and its usage.
Parâmetros
- summaryonly
-
Controls whether the returned array will contain information about individual cache entries along with the session cache summary.
Valor Retornado
Array of meta data about session cache or FALSE on failure
The array returned by this function contains the following elements:
- total_cache_uptime - total time in seconds that the session cache has been active
- total_item_count - total number of elements that are currently in the session cache
- is_local_cache - true is the cache metadata is for a local cache instance, false if the metadata is for the global cache
- total_hit_count - number of times the data has been served from the cache
- total_miss_count - number of times the data has not been found in the cache
-
scache_entries - an array that contains the information about all the cached items:
- key_name - name of the key which is used to store the data
- value_type - type of value stored by the key
- use_time - time in seconds since the file has been accessed in the opcode cache
- last_check - time in seconds since the file has been checked for modifications
- ttl_seconds - time remaining for the data to live in the cache, 0 meaning infinite
- age_seconds - time elapsed from the time data has been added in the cache
- hitcount - number of times data has been served from the cache
Exemplos
Exemplo #1 A wincache_scache_info() example
<pre>
<?php
print_r(wincache_scache_info());
?>
</pre>
O exemplo acima irá imprimir:
Array
(
[total_cache_uptime] => 17357
[total_file_count] => 121
[total_hit_count] => 36562
[total_miss_count] => 201
[scache_entries] => Array
(
[1] => Array
(
[file_name] => c:\inetpub\wwwroot\checkcache.php
[add_time] => 17356
[use_time] => 7
[last_check] => 10
[hit_count] => 454
[function_count] => 0
[class_count] => 1
)
[2] => Array (...iterates for each cached file)
)
)
Veja Também
- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_meminfo() - Retrieves information about opcode cache memory usage
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage
wincache_scache_meminfo
(PECL wincache >= 1.1.0)
wincache_scache_meminfo — Retrieves information about session cache memory usage
Descrição
Retrieves information about memory usage by session cache.
Valor Retornado
Array of meta data about session cache memory usage or FALSE on failure
The array returned by this function contains the following elements:
- memory_total - amount of memory in bytes allocated for the session cache
- memory_free - amount of free memory in bytes available for the session cache
- num_used_blks - number of memory blocks used by the session cache
- num_free_blks - number of free memory blocks available for the session cache
- memory_overhead - amount of memory in bytes used for the session cache internal structures
Exemplos
Exemplo #1 A wincache_scache_meminfo() example
<pre>
<?php
print_r(wincache_scache_meminfo());
?>
</pre>
O exemplo acima irá imprimir:
Array
(
[memory_total] => 5242880
[memory_free] => 5215056
[num_used_blks] => 6
[num_free_blks] => 3
[memory_overhead] => 176
)
Veja Também
- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
wincache_ucache_add
(PECL wincache >= 1.1.0)
wincache_ucache_add — Adds a variable in user cache only if variable does not already exist in the cache
Descrição
Adds a variable in user cache, only if this variable doesn't already exist in the cache. The added variable remains in the user cache unless its time to live expires or it is deleted by using wincache_ucache_delete() or wincache_ucache_clear() functions.
Parâmetros
- key
-
Store the variable using this key name. If a variable with same key is already present the function will fail and return FALSE. key is case sensitive. To override the value even if key is present use wincache_ucache_set() function instad. key can also take array of name => value pairs where names will be used as keys. This can be used to add multiple values in the cache in one operation, thus avoiding race condition.
- value
-
Value of a variable to store. Value supports all data types except resources, such as file handles. This paramter is ignored if first argument is an array. A general guidance is to pass NULL as value while using array as key. If value is an object, or an array containing objects, then the objects will be serialized. See __sleep() for details on serializing objects.
- values
-
Associative array of keys and values.
- ttl
-
Time for the variable to live in the cache in seconds. After the value specified in ttl has passed the stored variable will be deleted from the cache. This parameter takes a default value of 0 which means the variable will stay in the cache unless explicitly deleted by using wincache_ucache_delete() or wincache_ucache_clear() functions.
Valor Retornado
If key is string, the function returns TRUE on success and FALSE on failure.
If key is an array, the function returns:
- If all the name => value pairs in the array can be set, function returns an empty array;
- If all the name => value pairs in the array cannot be set, function returns FALSE;
- If some can be set while others cannot, function returns an array with name=>value pair for which the addition failed in the user cache.
Exemplos
Exemplo #1 wincache_ucache_add() with key as a string
<?php
$bar = 'BAR';
var_dump(wincache_ucache_add('foo', $bar));
var_dump(wincache_ucache_add('foo', $bar));
var_dump(wincache_ucache_get('foo'));
?>
O exemplo acima irá imprimir:
bool(true) bool(false) string(3) "BAR"
Exemplo #2 wincache_ucache_add() with key as an array
<?php
$colors_array = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
var_dump(wincache_ucache_add($colors_array));
var_dump(wincache_ucache_add($colors_array));
var_dump(wincache_ucache_get('Blue'));
?>
O exemplo acima irá imprimir:
array(0) { }
array(4) {
["green"]=> int(-1)
["Blue"]=> int(-1)
["yellow"]=> int(-1)
["cyan"]=> int(-1)
}
string(1) "6"
Veja Também
- wincache_ucache_set() - Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_ucache_get() - Gets a variable stored in the user cache
- wincache_ucache_delete() - Deletes variables from the user cache
- wincache_ucache_clear() - Deletes entire content of the user cache
- wincache_ucache_exists() - Checks if a variable exists in the user cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- __sleep()
wincache_ucache_cas
(PECL wincache >= 1.1.0)
wincache_ucache_cas — Compares the variable with old value and assigns new value to it
Descrição
Compares the variable associated with the key with old_value and if it matches then assigns the new_value to it.
Parâmetros
- key
-
The key that is used to store the variable in the cache. key is case sensitive.
- old_value
-
Old value of the variable pointed by key in the user cache. The value should be of type long, otherwise the function returns FALSE.
- new_value
-
New value which will get assigned to variable pointer by key if a match is found. The value should be of type long, otherwise the function returns FALSE.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 Using wincache_ucache_cas()
<?php
wincache_ucache_set('counter', 2922);
var_dump(wincache_ucache_cas('counter', 2922, 1));
var_dump(wincache_ucache_get('counter'));
?>
O exemplo acima irá imprimir:
bool(true) int(1)
Veja Também
- wincache_ucache_inc() - Increments the value associated with the key
- wincache_ucache_dec() - Decrements the value associated with the key
wincache_ucache_clear
(PECL wincache >= 1.1.0)
wincache_ucache_clear — Deletes entire content of the user cache
Descrição
Clears/deletes all the values stored in the user cache.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 using wincache_ucache_clear()
<?php
wincache_ucache_set('green', 1);
wincache_ucache_set('red', 2);
wincache_ucache_set('orange', 4);
wincache_ucache_set('blue', 8);
wincache_ucache_set('cyan', 16);
$array1 = array('green', 'red', 'orange', 'blue', 'cyan');
var_dump(wincache_ucache_get($array1));
var_dump(wincache_ucache_clear());
var_dump(wincache_ucache_get($array1));
?>
O exemplo acima irá imprimir:
array(5) { ["green"]=> int(1)
["red"]=> int(2)
["orange"]=> int(4)
["blue"]=> int(8)
["cyan"]=> int(16) }
bool(true)
bool(false)
Veja Também
- wincache_ucache_set() - Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_ucache_add() - Adds a variable in user cache only if variable does not already exist in the cache
- wincache_ucache_delete() - Deletes variables from the user cache
- wincache_ucache_get() - Gets a variable stored in the user cache
- wincache_ucache_exists() - Checks if a variable exists in the user cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
wincache_ucache_dec
(PECL wincache >= 1.1.0)
wincache_ucache_dec — Decrements the value associated with the key
Descrição
Decrements the value associated with the key by 1 or as specified by dec_by.
Parâmetros
- key
-
The key that was used to store the variable in the cache. key is case sensitive.
- dec_by
-
The value by which the variable associated with the key will get decremented. If the argument is a floating point number it will be truncated to nearest integer. The variable associated with the key should be of type long, otherwise the function fails and returns FALSE.
- success
-
Will be set to TRUE on success and FALSE on failure.
Valor Retornado
Returns the decremented value on success and FALSE on failure.
Exemplos
Exemplo #1 Using wincache_ucache_dec()
<?php
wincache_ucache_set('counter', 1);
var_dump(wincache_ucache_dec('counter', 2923, $success));
var_dump($success);
?>
O exemplo acima irá imprimir:
int(2922) bool(true)
Veja Também
- wincache_ucache_inc() - Increments the value associated with the key
- wincache_ucache_cas() - Compares the variable with old value and assigns new value to it
wincache_ucache_delete
(PECL wincache >= 1.1.0)
wincache_ucache_delete — Deletes variables from the user cache
Descrição
Deletes the elements in the user cache pointed by key.
Parâmetros
- key
-
The key that was used to store the variable in the cache. key is case sensitive. key can be an array of keys.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
If key is an array then the function returns FALSE if every element of the array fails to get deleted from the user cache, otherwise returns an array which consists of all the keys that are deleted.
Exemplos
Exemplo #1 Using wincache_ucache_delete() with key as a string
<?php
wincache_ucache_set('foo', 'bar');
var_dump(wincache_ucache_delete('foo'));
var_dump(wincache_ucache_exists('foo'));
?>
O exemplo acima irá imprimir:
bool(true) bool(false)
Exemplo #2 Usingwincache_ucache_delete() with key as an array
<?php
$array1 = array('green' => '5', 'blue' => '6', 'yellow' => '7', 'cyan' => '8');
wincache_ucache_set($array1);
$array2 = array('green', 'blue', 'yellow', 'cyan');
var_dump(wincache_ucache_delete($array2));
?>
O exemplo acima irá imprimir:
array(4) { [0]=> string(5) "green"
[1]=> string(4) "Blue"
[2]=> string(6) "yellow"
[3]=> string(4) "cyan" }
Exemplo #3 Using wincache_ucache_delete() with key as an array where some elements cannot be deleted
<?php
$array1 = array('green' => '5', 'blue' => '6', 'yellow' => '7', 'cyan' => '8');
wincache_ucache_set($array1);
$array2 = array('orange', 'red', 'yellow', 'cyan');
var_dump(wincache_ucache_delete($array2));
?>
O exemplo acima irá imprimir:
array(2) { [0]=> string(6) "yellow"
[1]=> string(4) "cyan" }
Veja Também
- wincache_ucache_set() - Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_ucache_add() - Adds a variable in user cache only if variable does not already exist in the cache
- wincache_ucache_get() - Gets a variable stored in the user cache
- wincache_ucache_clear() - Deletes entire content of the user cache
- wincache_ucache_exists() - Checks if a variable exists in the user cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
wincache_ucache_exists
(PECL wincache >= 1.1.0)
wincache_ucache_exists — Checks if a variable exists in the user cache
Descrição
Checks if a variable with the key exists in the user cache or not.
Parâmetros
- key
-
The key that was used to store the variable in the cache. key is case sensitive.
Valor Retornado
Returns TRUE if variable with the key exitsts, otherwise returns FALSE.
Exemplos
Exemplo #1 Using wincache_ucache_exists()
<?php
if (!wincache_ucache_exists('green'))
wincache_ucache_set('green', 1);
var_dump(wincache_ucache_exists('green'));
?>
O exemplo acima irá imprimir:
bool(true)
Veja Também
- wincache_ucache_set() - Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_ucache_add() - Adds a variable in user cache only if variable does not already exist in the cache
- wincache_ucache_get() - Gets a variable stored in the user cache
- wincache_ucache_clear() - Deletes entire content of the user cache
- wincache_ucache_delete() - Deletes variables from the user cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
wincache_ucache_get
(PECL wincache >= 1.1.0)
wincache_ucache_get — Gets a variable stored in the user cache
Descrição
Gets a variable stored in the user cache.
Parâmetros
- key
-
The key that was used to store the variable in the cache. key is case sensitive. key can be an array of keys. In this case the return value will be an array of values of each element in the key array. If an object, or an array containing objects, is returned, then the objects will be unserialized. See __wakeup() for details on unserializing objects.
- success
-
Will be set to TRUE on success and FALSE on failure.
Valor Retornado
If key is a string, the function returns the value of the variable stored with that key. The success is set to TRUE on success and to FALSE on failure.
The key is an array, the parameter success is always set to TRUE. The returned array (name => value pairs) will contain only those name => value pairs for which the get operation in user cache was successful. If none of the keys in the key array finds a match in the user cache an empty array will be returned.
Exemplos
Exemplo #1 wincache_ucache_get() with key as a string
<?php
wincache_ucache_add('color', 'blue');
var_dump(wincache_ucache_get('color', $success));
var_dump($success);
?>
O exemplo acima irá imprimir:
string(4) "blue" bool(true)
Exemplo #2 wincache_ucache_get() with key as an array
<?php
$array1 = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
wincache_ucache_set($array1);
$array2 = array('green', 'Blue', 'yellow', 'cyan');
var_dump(wincache_ucache_get($array2, $success));
var_dump($success);
?>
O exemplo acima irá imprimir:
array(4) { ["green"]=> string(1) "5"
["Blue"]=> string(1) "6"
["yellow"]=> string(1) "7"
["cyan"]=> string(1) "8" }
bool(true)
Veja Também
- wincache_ucache_add() - Adds a variable in user cache only if variable does not already exist in the cache
- wincache_ucache_set() - Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_ucache_delete() - Deletes variables from the user cache
- wincache_ucache_clear() - Deletes entire content of the user cache
- wincache_ucache_exists() - Checks if a variable exists in the user cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- __wakeup()
wincache_ucache_inc
(PECL wincache >= 1.1.0)
wincache_ucache_inc — Increments the value associated with the key
Descrição
Increments the value associated with the key by 1 or as specified by inc_by.
Parâmetros
- key
-
The key that was used to store the variable in the cache. key is case sensitive.
- inc_by
-
The value by which the variable associated with the key will get incremented. If the argument is a floating point number it will be truncated to nearest integer. The variable associated with the key should be of type long, otherwise the function fails and returns FALSE.
- success
-
Will be set to TRUE on success and FALSE on failure.
Valor Retornado
Returns the incremented value on success and FALSE on failure.
Exemplos
Exemplo #1 Using wincache_ucache_inc()
<?php
wincache_ucache_set('counter', 1);
var_dump(wincache_ucache_inc('counter', 2921, $success));
var_dump($success);
?>
O exemplo acima irá imprimir:
int(2922) bool(true)
Veja Também
- wincache_ucache_dec() - Decrements the value associated with the key
- wincache_ucache_cas() - Compares the variable with old value and assigns new value to it
wincache_ucache_info
(PECL wincache >= 1.1.0)
wincache_ucache_info — Retrieves information about data stored in the user cache
Descrição
Retrieves information about data stored in the user cache.
Parâmetros
- summaryonly
-
Controls whether the returned array will contain information about individual cache entries along with the user cache summary.
- key
-
The key of an entry in the user cache. If specified then the returned array will contain information only about that cache entry. If not specified and summaryonly is set to FALSE then the returned array will contain information about all entries in the cache.
Valor Retornado
Array of meta data about user cache or FALSE on failure
The array returned by this function contains the following elements:
- total_cache_uptime - total time in seconds that the user cache has been active
- total_item_count - total number of elements that are currently in the user cache
- is_local_cache - true is the cache metadata is for a local cache instance, false if the metadata is for the global cache
- total_hit_count - number of times the data has been served from the cache
- total_miss_count - number of times the data has not been found in the cache
-
ucache_entries - an array that contains the information about all the cached items:
- key_name - name of the key which is used to store the data
- value_type - type of value stored by the key
- use_time - time in seconds since the file has been accessed in the opcode cache
- last_check - time in seconds since the file has been checked for modifications
- is_session - indicates if the data is a session variable
- ttl_seconds - time remaining for the data to live in the cache, 0 meaning infinite
- age_seconds - time elapsed from the time data has been added in the cache
- hitcount - number of times data has been served from the cache
Exemplos
Exemplo #1 Using wincache_ucache_info()
<?php
wincache_ucache_get('green');
wincache_ucache_set('green', 2922);
wincache_ucache_get('green');
wincache_ucache_get('green');
wincache_ucache_get('green');
print_r(wincache_ucache_info());
?>
O exemplo acima irá imprimir:
Array
( ["total_cache_uptime"] => int(0)
["is_local_cache"] => bool(false)
["total_item_count"] => int(1)
["total_hit_count"] => int(3)
["total_miss_count"] => int(1)
["ucache_entries"] => Array(1)
( [1] => Array(6)
(
["key_name"] => string(5) "green"
["value_type"] => string(4) "long"
["is_session"] => int(0)
["ttl_seconds"] => int(0)
["age_seconds"] => int(0)
["hitcount"] => int(3)
)
)
)
Veja Também
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_ocache_meminfo() - Retrieves information about opcode cache memory usage
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_scache_info() - Retrieves information about files cached in the session cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage
wincache_ucache_meminfo
(PECL wincache >= 1.1.0)
wincache_ucache_meminfo — Retrieves information about user cache memory usage
Descrição
Retrieves information about memory usage by user cache.
Valor Retornado
Array of meta data about user cache memory usage or FALSE on failure
The array returned by this function contains the following elements:
- memory_total - amount of memory in bytes allocated for the user cache
- memory_free - amount of free memory in bytes available for the user cache
- num_used_blks - number of memory blocks used by the user cache
- num_free_blks - number of free memory blocks available for the user cache
- memory_overhead - amount of memory in bytes used for the user cache internal structures
Exemplos
Exemplo #1 A wincache_ucache_meminfo() example
<pre>
<?php
print_r(wincache_ucache_meminfo());
?>
</pre>
O exemplo acima irá imprimir:
Array
(
[memory_total] => 5242880
[memory_free] => 5215056
[num_used_blks] => 6
[num_free_blks] => 3
[memory_overhead] => 176
)
Veja Também
- wincache_fcache_fileinfo() - Retrieves information about files cached in the file cache
- wincache_fcache_meminfo() - Retrieves information about file cache memory usage
- wincache_ocache_fileinfo() - Retrieves information about files cached in the opcode cache
- wincache_rplist_fileinfo() - Retrieves information about resolve file path cache
- wincache_rplist_meminfo() - Retrieves information about memory usage by the resolve file path cache
- wincache_refresh_if_changed() - Refreshes the cache entries for the cached files
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
- wincache_scache_meminfo() - Retrieves information about session cache memory usage
wincache_ucache_set
(PECL wincache >= 1.1.0)
wincache_ucache_set — Adds a variable in user cache and overwrites a variable if it already exists in the cache
Descrição
Adds a variable in user cache. Overwrites a variable if it already exists in the cache. The added or updated variable remains in the user cache unless its time to live expires or it is deleted by using wincache_ucache_delete() or wincache_ucache_clear() functions.
Parâmetros
- key
-
Store the variable using this key name. If a variable with same key is already present the function will overwrite the previous value with the new one. key is case sensitive. key can also take array of name => value pairs where names will be used as keys. This can be used to add multiple values in the cache in one operation, thus avoiding race condition.
- value
-
Value of a variable to store. Value supports all data types except resources, such as file handles. This paramter is ignored if first argument is an array. A general guidance is to pass NULL as value while using array as key. If value is an object, or an array containing objects, then the objects will be serialized. See __sleep() for details on serializing objects.
- values
-
Associative array of keys and values.
- ttl
-
Time for the variable to live in the cache in seconds. After the value specified in ttl has passed the stored variable will be deleted from the cache. This parameter takes a default value of 0 which means the variable will stay in the cache unless explicitly deleted by using wincache_ucache_delete() or wincache_ucache_clear() functions.
Valor Retornado
If key is string, the function returns TRUE on success and FALSE on failure.
If key is an array, the function returns:
- If all the name => value pairs in the array can be set, function returns an empty array;
- If all the name => value pairs in the array cannot be set, function returns FALSE;
- If some can be set while others cannot, function returns an array with name=>value pair for which the addition failed in the user cache.
Exemplos
Exemplo #1 wincache_ucache_set() with key as a string
<?php
$bar = 'BAR';
var_dump(wincache_ucache_set('foo', $bar));
var_dump(wincache_ucache_get('foo'));
$bar1 = 'BAR1';
var_dump(wincache_ucache_set('foo', $bar1));
var_dump(wincache_ucache_get('foo'));
?>
O exemplo acima irá imprimir:
bool(true) string(3) "BAR" bool(true) string(3) "BAR1"
Exemplo #2 wincache_ucache_set() with key as an array
<?php
$colors_array = array('green' => '5', 'Blue' => '6', 'yellow' => '7', 'cyan' => '8');
var_dump(wincache_ucache_set($colors_array));
var_dump(wincache_ucache_set($colors_array));
var_dump(wincache_ucache_get('Blue'));
?>
O exemplo acima irá imprimir:
array(0) {}
array(0) {}
string(1) "6"
Veja Também
- wincache_ucache_add() - Adds a variable in user cache only if variable does not already exist in the cache
- wincache_ucache_get() - Gets a variable stored in the user cache
- wincache_ucache_delete() - Deletes variables from the user cache
- wincache_ucache_clear() - Deletes entire content of the user cache
- wincache_ucache_exists() - Checks if a variable exists in the user cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- __sleep()
wincache_unlock
(PECL wincache >= 1.1.0)
wincache_unlock — Releases an exclusive lock on a given key
Descrição
Releases an exclusive lock that was obtained on a given key by using wincache_lock(). If any other process was blocked waiting for the lock on this key, that process will be able to obtain the lock.
Using of the wincache_lock() and wincache_unlock() can cause deadlocks when executing PHP scripts in a multi-process environment like FastCGI. Do not use these functions unless you are absolutely sure you need to use them. For the majority of the operations on the user cache it is not necessary to use these functions.
Parâmetros
- key
-
Name of the key in the cache to release the lock on.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 Using wincache_unlock()
<?php
$fp = fopen("/tmp/lock.txt", "r+");
if (wincache_lock(“lock_txt_lock”)) { // do an exclusive lock
ftruncate($fp, 0); // truncate file
fwrite($fp, "Write something here\n");
wincache_unlock(“lock_txt_lock”); // release the lock
} else {
echo "Couldn't get the lock!";
}
fclose($fp);
?>
Veja Também
- wincache_lock() - Acquires an exclusive lock on a given key
- wincache_ucache_set() - Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_ucache_get() - Gets a variable stored in the user cache
- wincache_ucache_delete() - Deletes variables from the user cache
- wincache_ucache_clear() - Deletes entire content of the user cache
- wincache_ucache_exists() - Checks if a variable exists in the user cache
- wincache_ucache_meminfo() - Retrieves information about user cache memory usage
- wincache_ucache_info() - Retrieves information about data stored in the user cache
- wincache_scache_info() - Retrieves information about files cached in the session cache
Índice
- wincache_fcache_fileinfo — Retrieves information about files cached in the file cache
- wincache_fcache_meminfo — Retrieves information about file cache memory usage
- wincache_lock — Acquires an exclusive lock on a given key
- wincache_ocache_fileinfo — Retrieves information about files cached in the opcode cache
- wincache_ocache_meminfo — Retrieves information about opcode cache memory usage
- wincache_refresh_if_changed — Refreshes the cache entries for the cached files
- wincache_rplist_fileinfo — Retrieves information about resolve file path cache
- wincache_rplist_meminfo — Retrieves information about memory usage by the resolve file path cache
- wincache_scache_info — Retrieves information about files cached in the session cache
- wincache_scache_meminfo — Retrieves information about session cache memory usage
- wincache_ucache_add — Adds a variable in user cache only if variable does not already exist in the cache
- wincache_ucache_cas — Compares the variable with old value and assigns new value to it
- wincache_ucache_clear — Deletes entire content of the user cache
- wincache_ucache_dec — Decrements the value associated with the key
- wincache_ucache_delete — Deletes variables from the user cache
- wincache_ucache_exists — Checks if a variable exists in the user cache
- wincache_ucache_get — Gets a variable stored in the user cache
- wincache_ucache_inc — Increments the value associated with the key
- wincache_ucache_info — Retrieves information about data stored in the user cache
- wincache_ucache_meminfo — Retrieves information about user cache memory usage
- wincache_ucache_set — Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_unlock — Releases an exclusive lock on a given key
Building for Windows
Índice
Prerequisites
Building WinCache extension will require:
- PHP source code
- PHP build environment
- WinCache source code
For completing first two steps, follow the step-by-step guide for how to » build PHP on Windows.
For getting the WinCache source code follow the instructions described in Downloading PECL extensions.
Compiling and building
The following steps describe how to compile and build WinCache on Windows OS:
-
Open a command prompt which is used to build PHP
-
Go to the root folder where PHP sources are present
-
Run the command:
cscript.exe win32\build\buildconf.js
-
Run the command:
The output will contain a new flag --enable-wincache.configure.bat --help
-
Run the command:
--enable-wincache is the only extra option which is required to ensure that WinCache extension gets built properly. This option will build WinCache and will statically link it with PHP dll. To build WinCache extension as a stand-alone DLL use the option --enable-wincache=shared.configure.js [all options used to build PHP] --enable-wincache
-
Run the command:
nmake
Verifying the build
The following steps describe how to verify that WinCache has been built correctly:
-
Go to the folder where the PHP binaries are built
-
Run the command:
If WinCache has been built properly, the output of this command will list the INI directives and functions supported by WinCache.php.exe -n -d extension=php_wincache.dll -re wincache
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- WinCache Funções
- wincache_fcache_fileinfo — Retrieves information about files cached in the file cache
- wincache_fcache_meminfo — Retrieves information about file cache memory usage
- wincache_lock — Acquires an exclusive lock on a given key
- wincache_ocache_fileinfo — Retrieves information about files cached in the opcode cache
- wincache_ocache_meminfo — Retrieves information about opcode cache memory usage
- wincache_refresh_if_changed — Refreshes the cache entries for the cached files
- wincache_rplist_fileinfo — Retrieves information about resolve file path cache
- wincache_rplist_meminfo — Retrieves information about memory usage by the resolve file path cache
- wincache_scache_info — Retrieves information about files cached in the session cache
- wincache_scache_meminfo — Retrieves information about session cache memory usage
- wincache_ucache_add — Adds a variable in user cache only if variable does not already exist in the cache
- wincache_ucache_cas — Compares the variable with old value and assigns new value to it
- wincache_ucache_clear — Deletes entire content of the user cache
- wincache_ucache_dec — Decrements the value associated with the key
- wincache_ucache_delete — Deletes variables from the user cache
- wincache_ucache_exists — Checks if a variable exists in the user cache
- wincache_ucache_get — Gets a variable stored in the user cache
- wincache_ucache_inc — Increments the value associated with the key
- wincache_ucache_info — Retrieves information about data stored in the user cache
- wincache_ucache_meminfo — Retrieves information about user cache memory usage
- wincache_ucache_set — Adds a variable in user cache and overwrites a variable if it already exists in the cache
- wincache_unlock — Releases an exclusive lock on a given key
- Building for Windows
Hierarchical Profiler
Introdução
XHProf is a light-weight hierarchical and instrumentation based profiler. During the data collection phase, it keeps track of call counts and inclusive metrics for arcs in the dynamic callgraph of a program. It computes exclusive metrics in the reporting/post processing phase, such as wall (elapsed) time, CPU time and memory usage. A functions profile can be broken down by callers or callees. XHProf handles recursive functions by detecting cycles in the callgraph at data collection time itself and avoiding the cycles by giving unique depth qualified names for the recursive invocations.
XHProf includes a simple HTML based user interface (written in PHP). The browser based UI for viewing profiler results makes it easy to view results or to share results with peers. A callgraph image view is also supported.
XHProf reports can often be helpful in understanding the structure of the code being executed. The hierarchical nature of the reports can be used to determine, for example, what chain of calls led to a particular function getting called.
XHProf supports ability to compare two runs (a.k.a. "diff" reports) or aggregate data from multiple runs. Diff and aggregate reports, much like single run reports, offer "flat" as well as "hierarchical" views of the profile.
Additional documentation can be found via the » facebook xhprof website.
Instalação/Configuração
Índice
Dependências
Although not required, xhprof includes an interface that's written in PHP. It's used to save and display the profiled data in a usable way, where viewing is done via a web browser. So, a PHP enabled web server will likely make the xhprof experience more useful.
There's also a fork of the GUI interface at » http://github.com/preinheimer/xhprof
Instalação
Informações para a instalação desta extensão PECL podem ser encontradas no manual no capitulo intitulado Instalação de extensões PECL. Informações adicionais como novas versões, downloads, arquivos fontes, manutenções, e um Changelog, podem ser obtidos aqui: » http://pecl.php.net/package/xhprof
Configurações em Execução
O comportamento dessas funções podem ser modificado pelas configurações do php.ini.
| Nome | Padrão | Modificável | Histórico |
|---|---|---|---|
| xhprof.output_dir | "" | PHP_INI_ALL |
Breve descrição das diretivas de configuração.
- xhprof.output_dir string
-
Directory used by the default implementation of the iXHProfRuns interface (namely, the XHProfRuns_Default class) for storing XHProf runs.
Tipos Resource
Esta extensão não possui nenhum tipo resource.
Constantes pré-definidas
As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.
Exemplos
Exemplo #1 Xhprof example with the optional GUI
This example starts and stops the profiler, then uses the bundled GUI interface to save and parse the results. In other words, the code from the extension itself ends at the call to xhprof_disable().
<?php
xhprof_enable(XHPROF_FLAGS_CPU + XHPROF_FLAGS_MEMORY);
for ($i = 0; $i <= 1000; $i++) {
$a = $i * $i;
}
$xhprof_data = xhprof_disable();
$XHPROF_ROOT = "/tools/xhprof/";
include_once $XHPROF_ROOT . "/xhprof_lib/utils/xhprof_lib.php";
include_once $XHPROF_ROOT . "/xhprof_lib/utils/xhprof_runs.php";
$xhprof_runs = new XHProfRuns_Default();
$run_id = $xhprof_runs->save_run($xhprof_data, "xhprof_testing");
echo "http://localhost/xhprof/xhprof_html/index.php?run={$run_id}&source=xhprof_testing\n";
?>
O exemplo acima irá imprimir algo similar a:
http://localhost/xhprof/xhprof_html/index.php?run=t11_4bdf44d21121f&source=xhprof_testing
Xhprof Funções
xhprof_disable
(PECL xhprof >= 0.9.0)
xhprof_disable — Stops xhprof profiler
Descrição
Stops the profiler, and returns xhprof data from the run.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
An array of xhprof data, from the run.
Exemplos
Exemplo #1 xhprof_disable() example
<?php
xhprof_enable();
$foo = strlen("foo bar");
$xhprof_data = xhprof_disable();
print_r($xhprof_data);
?>
O exemplo acima irá imprimir algo similar a:
Array
(
[main()==>strlen] => Array
(
[ct] => 1
[wt] => 279
)
[main()==>xhprof_disable] => Array
(
[ct] => 1
[wt] => 9
)
[main()] => Array
(
[ct] => 1
[wt] => 610
)
)
xhprof_enable
(PECL xhprof >= 0.9.0)
xhprof_enable — Start xhprof profiler
Descrição
Start xhprof profiling.
Parâmetros
- flags
-
Optional flags to add additional information to the profiling. See the XHprof constants for further information about these flags, e.g., XHPROF_FLAGS_MEMORY to enable memory profiling.
- options
-
An array of optional options, namely, the 'ignored_functions' option to pass in functions to be ignored during profiling.
Valor Retornado
NULL
Histórico
| Versão | Descrição |
|---|---|
| 0.9.2 | The optional options parameter was added. |
Exemplos
Exemplo #1 xhprof_enable() examples
<?php
// 1. elapsed time + memory + CPU profiling; and ignore built-in (internal) functions
xhprof_enable(XHPROF_FLAGS_NO_BUILTINS | XHPROF_FLAGS_CPU | XHPROF_FLAGS_MEMORY);
// 2. elapsed time profiling; ignore call_user_func* during profiling
xhprof_enable(
0,
array('ignored_functions' => array('call_user_func',
'call_user_func_array')));
// 3. elapsed time + memory profiling; ignore call_user_func* during profiling
xhprof_enable(
XHPROF_FLAGS_MEMORY,
array('ignored_functions' => array('call_user_func',
'call_user_func_array')));
?>
Veja Também
- xhprof_disable() - Stops xhprof profiler
- xhprof_sample_enable() - Description
- memory_get_usage() - Retorna a quantidade de memória alocada para PHP
- getrusage() - Obtém a utilização de recursos
xhprof_sample_disable
(PECL xhprof >= 0.9.0)
xhprof_sample_disable — Stops xhprof sample profiler
Descrição
Stops the sample mode xhprof profiler, and
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
An array of xhprof sample data, from the run.
Exemplos
Exemplo #1 xhprof_sample_disable() example
<?php
xhprof_sample_enable();
for ($i = 0; $i <= 10000; $i++) {
$a = strlen($i);
$b = $i * $a;
$c = rand();
}
$xhprof_data = xhprof_sample_disable();
print_r($xhprof_data);
?>
O exemplo acima irá imprimir algo similar a:
Array
(
[1272935300.800000] => main()
[1272935300.900000] => main()
)
xhprof_sample_enable
(PECL xhprof >= 0.9.0)
xhprof_sample_enable — Description
Descrição
Starts profiling in sample mode, which is a lighter weight version of xhprof_enable(). The sampling interval is 0.1 seconds, and samples record the full function call stack. The main use case is when lower overhead is required when doing performance monitoring and diagnostics.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
NULL
Veja Também
- xhprof_sample_disable() - Stops xhprof sample profiler
- xhprof_enable() - Start xhprof profiler
- memory_get_usage() - Retorna a quantidade de memória alocada para PHP
- getrusage() - Obtém a utilização de recursos
Índice
- xhprof_disable — Stops xhprof profiler
- xhprof_enable — Start xhprof profiler
- xhprof_sample_disable — Stops xhprof sample profiler
- xhprof_sample_enable — Description
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Exemplos
- Xhprof Funções
- xhprof_disable — Stops xhprof profiler
- xhprof_enable — Start xhprof profiler
- xhprof_sample_disable — Stops xhprof sample profiler
- xhprof_sample_enable — Description
- APC — Alternative PHP Cache
- APD — Advanced PHP debugger
- bcompiler — Compilador de PHP bytecode
- Manuseamento de Erro — Erros e Logs
- htscanner — htaccess-like support for all SAPIs
- inclued — Inclusion hierarchy viewer
- Memtrack
- Controle de Saída — Controle de Saída de Buffer
- Object overloading — Object property and method call overloading
- Opções/Info do PHP — Informações e Opções do PHP
- runkit
- scream — Break the silence operator
- Weakref — Weak References
- Introdução
- Instalação/Configuração
- Weakref — The Weakref class
- WinCache — Windows Cache for PHP
- Xhprof — Hierarchical Profiler
Manipulação de Formatos de Audio
ID3 Tags
Introdução
These functions let you read and manipulate ID3 tags. ID3 tags are used in MP3 files to store title of the song, as well as information about the artist, album, genre, year and track number.
Since version 0.2 it is also possible to extract text frames from ID3 v2.2+ tags.
Instalação/Configuração
Índice
Dependências
Nenhuma biblioteca externa é necessária para compilar esta extensão.
Instalação
Informações para a instalação desta extensão PECL podem ser encontradas no manual no capitulo intitulado Instalação de extensões PECL. Informações adicionais como novas versões, downloads, arquivos fontes, manutenções, e um Changelog, podem ser obtidos aqui: » http://pecl.php.net/package/id3.
Uma DLL para esta extenção PECL esta atualmente indisponível. Veja também a seção compilando no Windows section.
Configurações em Execução
Esta extensão não define nenhum parâmetro de configuração no php.ini.
Tipos Resource
Esta extensão não possui nenhum tipo resource.
Predefined Constants
Most of the id3 functions either let you specify or return a tag version. In order to specify the version please use on of these constants.
- ID3_V1_0 (integer)
- ID3_V1_0 is used if you are working with ID3 V1.0 tags. These tags may contain the fields title, artist, album, genre, year and comment.
- ID3_V1_1 (integer)
- ID3_V1_1 is used if you are working with ID3 V1.1 tags. These tags may all information contained in v1.0 tags plus the track number.
- ID3_V2_1 (integer)
- ID3_V2_1 is used if you are working with ID3 V2.1 tags.
- ID3_V2_2 (integer)
- ID3_V2_2 is used if you are working with ID3 V2.2 tags.
- ID3_V2_3 (integer)
- ID3_V2_3 is used if you are working with ID3 V2.3 tags.
- ID3_V2_4 (integer)
- ID3_V2_4 is used if you are working with ID3 V2.4 tags.
- ID3_BEST (integer)
- ID3_BEST is used if would like to let the id3 functions determine which tag version should be used.
ID3 Funções
id3_get_frame_long_name
(PECL id3 >= 0.2)
id3_get_frame_long_name — Get the long name of an ID3v2 frame
Descrição
id3_get_frame_long_name() returns the long name for an ID3v2 frame.
Parâmetros
- frameId
-
An ID3v2 frame
Valor Retornado
Returns the frame long name or FALSE on errors.
Exemplos
Exemplo #1 id3_get_frame_long_name() example
<?php
$longName = id3_get_frame_long_name("TOLY");
echo $longName;
?>
O exemplo acima irá imprimir:
Original lyricist(s)/text writer(s)
id3_get_frame_short_name
(PECL id3 >= 0.2)
id3_get_frame_short_name — Get the short name of an ID3v2 frame
Descrição
id3_get_frame_short_name() returns the short name for an ID3v2 frame.
Parâmetros
- frameId
-
An ID3v2 frame
Valor Retornado
Returns the frame short name or FALSE on errors.
The values returned by id3_get_frame_short_name() are used in the array returned by id3_get_tag().
Exemplos
Exemplo #1 id3_get_frame_short_name() example
<?php
$shortName = id3_get_frame_short_name("TOLY");
echo $shortName;
?>
O exemplo acima irá imprimir:
originalLyricist
id3_get_genre_id
(PECL id3 >= 0.1)
id3_get_genre_id — Get the id for a genre
Descrição
id3_get_genre_id() returns the id for a genre.
Parâmetros
- genre
-
Genre name as string.
Valor Retornado
The genre id or FALSE on errors.
Exemplos
Exemplo #1 id3_get_genre_id() example
<?php
$id = id3_get_genre_id("Alternative");
echo $id;
?>
O exemplo acima irá imprimir:
20
Veja Também
- id3_get_genre_name() - Get the name for a genre id
- id3_get_genre_list() - Get all possible genre values
id3_get_genre_list
(PECL id3 >= 0.1)
id3_get_genre_list — Get all possible genre values
Descrição
id3_get_genre_list() returns an array containing all possible genres that may be stored in an ID3 tag. This list has been created by Eric Kemp and later extended by WinAmp.
This function is useful to provide you users a list of genres from which they may choose one. When updating the ID3 tag you will always have to specify the genre as an integer ranging from 0 to 147.
Valor Retornado
Returns an array containing all possible genres that may be stored in an ID3 tag.
Exemplos
Exemplo #1 id3_get_genre_list() example
<?php
$genres = id3_get_genre_list();
print_r($genres);
?>
O exemplo acima irá imprimir:
Array
(
[0] => Blues
[1] => Classic Rock
[2] => Country
[3] => Dance
[4] => Disco
[5] => Funk
[6] => Grunge
[7] => Hip-Hop
[8] => Jazz
[9] => Metal
[10] => New Age
[11] => Oldies
[12] => Other
[13] => Pop
[14] => R&B
[15] => Rap
[16] => Reggae
[17] => Rock
[18] => Techno
[19] => Industrial
[20] => Alternative
[21] => Ska
[22] => Death Metal
[23] => Pranks
[24] => Soundtrack
[25] => Euro-Techno
[26] => Ambient
[27] => Trip-Hop
[28] => Vocal
[29] => Jazz+Funk
[30] => Fusion
[31] => Trance
[32] => Classical
[33] => Instrumental
[34] => Acid
[35] => House
[36] => Game
[37] => Sound Clip
[38] => Gospel
[39] => Noise
[40] => Alternative Rock
[41] => Bass
[42] => Soul
[43] => Punk
[44] => Space
[45] => Meditative
[46] => Instrumental Pop
[47] => Instrumental Rock
[48] => Ethnic
[49] => Gothic
[50] => Darkwave
[51] => Techno-Industrial
[52] => Electronic
[53] => Pop-Folk
[54] => Eurodance
[55] => Dream
[56] => Southern Rock
[57] => Comedy
[58] => Cult
[59] => Gangsta
[60] => Top 40
[61] => Christian Rap
[62] => Pop/Funk
[63] => Jungle
[64] => Native US
[65] => Cabaret
[66] => New Wave
[67] => Psychadelic
[68] => Rave
[69] => Showtunes
[70] => Trailer
[71] => Lo-Fi
[72] => Tribal
[73] => Acid Punk
[74] => Acid Jazz
[75] => Polka
[76] => Retro
[77] => Musical
[78] => Rock & Roll
[79] => Hard Rock
[80] => Folk
[81] => Folk-Rock
[82] => National Folk
[83] => Swing
[84] => Fast Fusion
[85] => Bebob
[86] => Latin
[87] => Revival
[88] => Celtic
[89] => Bluegrass
[90] => Avantgarde
[91] => Gothic Rock
[92] => Progressive Rock
[93] => Psychedelic Rock
[94] => Symphonic Rock
[95] => Slow Rock
[96] => Big Band
[97] => Chorus
[98] => Easy Listening
[99] => Acoustic
[100] => Humour
[101] => Speech
[102] => Chanson
[103] => Opera
[104] => Chamber Music
[105] => Sonata
[106] => Symphony
[107] => Booty Bass
[108] => Primus
[109] => Porn Groove
[110] => Satire
[111] => Slow Jam
[112] => Club
[113] => Tango
[114] => Samba
[115] => Folklore
[116] => Ballad
[117] => Power Ballad
[118] => Rhytmic Soul
[119] => Freestyle
[120] => Duet
[121] => Punk Rock
[122] => Drum Solo
[123] => Acapella
[124] => Euro-House
[125] => Dance Hall
[126] => Goa
[127] => Drum & Bass
[128] => Club-House
[129] => Hardcore
[130] => Terror
[131] => Indie
[132] => BritPop
[133] => Negerpunk
[134] => Polsk Punk
[135] => Beat
[136] => Christian Gangsta
[137] => Heavy Metal
[138] => Black Metal
[139] => Crossover
[140] => Contemporary C
[141] => Christian Rock
[142] => Merengue
[143] => Salsa
[144] => Thrash Metal
[145] => Anime
[146] => JPop
[147] => SynthPop
)
Veja Também
- id3_get_genre_name() - Get the name for a genre id
- id3_get_genre_id() - Get the id for a genre
id3_get_genre_name
(PECL id3 >= 0.1)
id3_get_genre_name — Get the name for a genre id
Descrição
id3_get_genre_name() returns the name for a genre id.
Parâmetros
- genre_id
-
An integer ranging from 0 to 147
Valor Retornado
Returns the name as a string.
Exemplos
Exemplo #1 id3_get_genre_name() example
<?php
$genre = id3_get_genre_name(20);
echo $genre;
?>
O exemplo acima irá imprimir:
Alternative
Veja Também
- id3_get_genre_list() - Get all possible genre values
- id3_get_genre_id() - Get the id for a genre
id3_get_tag
(PECL id3 >= 0.1)
id3_get_tag — Get all information stored in an ID3 tag
Descrição
id3_get_tag() is used to get all information stored in the id3 tag of the specified file.
Parâmetros
- filename
-
The path to the MP3 file
Instead of a filename you may also pass a valid stream resource
- version
-
Allows you to specify the version of the tag as MP3 files may contain both, version 1.x and version 2.x tags
Since version 0.2 id3_get_tag() also supports ID3 tags of version 2.2, 2.3 and 2.4. To extract information from these tags, pass one of the constants ID3_V2_2, ID3_V2_3 or ID3_V2_4 as the second parameter. ID3 v2.x tags can contain a lot more information about the MP3 file than ID3 v1.x tags.
Valor Retornado
Returns an associative array with various keys like: title, artist, ..
The key genre will contain an integer between 0 and 147. You may use id3_get_genre_name() to convert it to a human readable string.
Exemplos
Exemplo #1 id3_get_tag() example
<?php
$tag = id3_get_tag( "path/to/example.mp3" );
print_r($tag);
?>
O exemplo acima irá imprimir algo similar a:
Array
(
[title] => DN-38416
[artist] => Re:\Legion
[album] => Reflections
[year] => 2004
[genre] => 19
)
Exemplo #2 id3_get_tag() example
<?php
$tag = id3_get_tag( "path/to/example2.mp3", ID3_V2_3 );
print_r($tag);
?>
O exemplo acima irá imprimir algo similar a:
Array
(
[copyright] => Dirty Mac
[originalArtist] => Dirty Mac
[composer] => Marcus Götze
[artist] => Dirty Mac
[title] => Little Big Man
[album] => Demo-Tape
[track] => 5/12
[genre] => (17)Rock
[year] => 2001
)
Veja Também
- id3_set_tag() - Update information stored in an ID3 tag
- id3_remove_tag() - Remove an existing ID3 tag
- id3_get_version() - Get version of an ID3 tag
id3_get_version
(PECL id3 >= 0.1)
id3_get_version — Get version of an ID3 tag
Descrição
id3_get_version() retrieves the version(s) of the ID3 tag(s) in the MP3 file.
If a file contains an ID3 v1.1 tag, it always contains a 1.0 tag, as version 1.1 is just an extension of 1.0.
Parâmetros
- filename
-
The path to the MP3 file
Instead of a filename you may also pass a valid stream resource
Valor Retornado
Returns the version number of the ID3 tag of the file. As a tag can contain ID3 v1.x and v2.x tags, the return value of this function should be bitwise compared with the predefined constants ID3_V1_0, ID3_V1_1 and ID3_V2.
Exemplos
Exemplo #1 id3_get_version() example
<?php
$version = id3_get_version( "path/to/example.mp3" );
if ($version & ID3_V1_0) {
echo "Contains a 1.x tag\n";
}
if ($version & ID3_V1_1) {
echo "Contains a 1.1 tag\n";
}
if ($version & ID3_V2) {
echo "Contains a 2.x tag\n";
}
?>
O exemplo acima irá imprimir algo similar a:
Contains a 1.x tag Contains a 1.1 tag
Veja Também
- id3_set_tag() - Update information stored in an ID3 tag
- id3_get_tag() - Get all information stored in an ID3 tag
- id3_remove_tag() - Remove an existing ID3 tag
id3_remove_tag
(PECL id3 >= 0.1)
id3_remove_tag — Remove an existing ID3 tag
Descrição
id3_remove_tag() is used to remove the information stored of an ID3 tag.
Parâmetros
- filename
-
The path to the MP3 file
Instead of a filename you may also pass a valid stream resource
- version
-
Allows you to specify the version of the tag as MP3 files may contain both, version 1.x and version 2.x tags.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 id3_remove_tag() example
<?php
$result = id3_remove_tag( "path/to/example.mp3", ID3_V1_0 );
if ($result === true) {
echo "Tag succesfully removed\n";
}
?>
If the file is writable and contained a 1.0 tag, this will output:
Tag succesfully removed
Notas
Nota: Currently id3_remove_tag() only supports version 1.0 and 1.1. If you choose to remove a 1.0 tag and the file contains a 1.1 tag, this tag will be removed, as v1.1 is only an extension of 1.0.
Veja Também
- id3_set_tag() - Update information stored in an ID3 tag
- id3_get_tag() - Get all information stored in an ID3 tag
- id3_get_version() - Get version of an ID3 tag
id3_set_tag
(PECL id3 >= 0.1)
id3_set_tag — Update information stored in an ID3 tag
Descrição
id3_set_tag() is used to change the information stored of an ID3 tag. If no tag has been present, it will be added to the file.
Parâmetros
- filename
-
The path to the MP3 file
Instead of a filename you may also pass a valid stream resource
- tag
-
An associative array of tag keys and values
The following keys may be used in the associative array:
Keys in the associative array key possible value available in version title string with maximum of 30 characters v1.0, v1.1 artist string with maximum of 30 characters v1.0, v1.1 album string with maximum of 30 characters v1.0, v1.1 year 4 digits v1.0, v1.1 genre integer value between 0 and 147 v1.0, v1.1 comment string with maximum of 30 characters (28 in v1.1) v1.0, v1.1 track integer between 0 and 255 v1.1 - version
-
Allows you to specify the version of the tag as MP3 files may contain both, version 1.x and version 2.x tags
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 id3_set_tag() example
<?php
$data = array(
"title" => "Re:Start",
"artist" => "Re:\Legion",
"comment" => "A nice track"
);
$result = id3_set_tag( "path/to/example.mp3", $data, ID3_V1_0 );
if ($result === true) {
echo "Tag succesfully updated\n";
}
?>
If the file is writable, this will output:
Tag succesfully updated
Notas
Nota: Currently id3_set_tag() only supports version 1.0 and 1.1.
Veja Também
- id3_remove_tag() - Remove an existing ID3 tag
- id3_get_tag() - Get all information stored in an ID3 tag
- id3_get_version() - Get version of an ID3 tag
Índice
- id3_get_frame_long_name — Get the long name of an ID3v2 frame
- id3_get_frame_short_name — Get the short name of an ID3v2 frame
- id3_get_genre_id — Get the id for a genre
- id3_get_genre_list — Get all possible genre values
- id3_get_genre_name — Get the name for a genre id
- id3_get_tag — Get all information stored in an ID3 tag
- id3_get_version — Get version of an ID3 tag
- id3_remove_tag — Remove an existing ID3 tag
- id3_set_tag — Update information stored in an ID3 tag
- Introdução
- Instalação/Configuração
- Predefined Constants
- ID3 Funções
- id3_get_frame_long_name — Get the long name of an ID3v2 frame
- id3_get_frame_short_name — Get the short name of an ID3v2 frame
- id3_get_genre_id — Get the id for a genre
- id3_get_genre_list — Get all possible genre values
- id3_get_genre_name — Get the name for a genre id
- id3_get_tag — Get all information stored in an ID3 tag
- id3_get_version — Get version of an ID3 tag
- id3_remove_tag — Remove an existing ID3 tag
- id3_set_tag — Update information stored in an ID3 tag
KTaglib
Introdução
KTaglib is an object oriented binding to the taglib library from the KDE project used in projects like Amarok to read and write ID3 and Ogg tags. The library also provides access to audio information. The bindings are designed usually follow the underlying C++ API, but were changed whenever there is a more PHP-like way.
Nota:
At the moment ktaglib is able to read and write ID3v1 and ID3v2 tags.
Instalação/Configuração
Índice
Dependências
If you want to build ktaglib you need at least taglib 1.5 installed. To obtain the taglib see the » taglib project page. Windows DLL's are build static against taglib, therefore there is no need to have taglib installed.
Instalação
Informações para a instalação desta extensão PECL podem ser encontradas no manual no capitulo intitulado Instalação de extensões PECL. Informações adicionais como novas versões, downloads, arquivos fontes, manutenções, e um Changelog, podem ser obtidos aqui: » http://pecl.php.net/package/ktaglib.
Uma DLL para esta extenção PECL esta atualmente indisponível. Veja também a seção compilando no Windows section.
Constantes pré-definidas
As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.
KTaglib uses class constants. Most of the constants are mappings to the according Taglib enums and constants.
- KTaglib_MPEG_Header::Version1 (integer)
- ID3 version is 1.0
- KTaglib_MPEG_Header::Version2 (integer)
- ID3 version is 2.0
- KTaglib_MPEG_Header::Version2_5 (integer)
- ID3 version is 2.5
- KTaglib_ID3v2_AttachedPictureFrame::Other (integer)
- Picture type Other
- KTaglib_ID3v2_AttachedPictureFrame::FileIcon (integer)
- Picture type FileIcon
- KTaglib_ID3v2_AttachedPictureFrame::OtherFileIcon (integer)
- Picture type OtherFileIcon
- KTaglib_ID3v2_AttachedPictureFrame::FrontCover (integer)
- Picture type FrontCover
- KTaglib_ID3v2_AttachedPictureFrame::BackCover (integer)
- Picture type BackCover
- KTaglib_ID3v2_AttachedPictureFrame::LeafletPage (integer)
- Picture type LeafletPage
- KTaglib_ID3v2_AttachedPictureFrame::Media (integer)
- Picture type Media
- KTaglib_ID3v2_AttachedPictureFrame::LeadArtist (integer)
- Picture type LeadArtist
- KTaglib_ID3v2_AttachedPictureFrame::Artist (integer)
- Picture type Artist
- KTaglib_ID3v2_AttachedPictureFrame::Conductor (integer)
- Picture type Condutor
- KTaglib_ID3v2_AttachedPictureFrame::Band (integer)
- Picture type Band
- KTaglib_ID3v2_AttachedPictureFrame::Composer (integer)
- Picture type Composer
- KTaglib_ID3v2_AttachedPictureFrame::Lyricist (integer)
- Picture type Lyricist
- KTaglib_ID3v2_AttachedPictureFrame::RecordingLocation (integer)
- Picture type RecordingLocation
- KTaglib_ID3v2_AttachedPictureFrame::DuringRecording (integer)
- Picture type DuringRecording
- KTaglib_ID3v2_AttachedPictureFrame::DuringPerformance (integer)
- Picture type DuringPerformance
- KTaglib_ID3v2_AttachedPictureFrame::MovieScreenCapture (integer)
- Picture type MovieScreenCapture
- KTaglib_ID3v2_AttachedPictureFrame::ColouredFish (integer)
- Picture type ColouredFish
- KTaglib_ID3v2_AttachedPictureFrame::Illustration (integer)
- Picture type Illustration
- KTaglib_ID3v2_AttachedPictureFrame::BandLogo (integer)
- Picture type BandLogo
The KTaglib_MPEG_File class
(No version information available, might only be in SVN)
Introdução
Represents an MPEG file. MPEG files can have ID3v1, ID3v2 tags and audio properties.
Class synopsis
KTaglib_MPEG_File::__construct
(0.0.1)
KTaglib_MPEG_File::__construct — Opens a new file
Descrição
Opens a new MPEG file.
Parâmetros
- filename
-
The file to read
Exemplos
Exemplo #1 Opens a new MP3 file and read the title
<?php
$mpeg = new KTaglib_MPEG_File('example.mp3');
echo $mpeg->getID3v1Tag()->getTitle();
?>
KTaglib_MPEG_File::getAudioProperties
(0.0.1)
KTaglib_MPEG_File::getAudioProperties — Returns an object that provides access to the audio properties
Descrição
Returns an object that provides access to the audio properties of the mpeg file.
Valor Retornado
Returns an KTaglib_MPEG_AudioProperties object or false.
KTaglib_MPEG_File::getID3v1Tag
(0.0.1)
KTaglib_MPEG_File::getID3v1Tag — Returns an object representing an ID3v1 tag
Descrição
Returns an object that represents an ID3v1 tag, which can be used to get information about the ID3v1 tag.
Valor Retornado
Returns an KTaglib_MPEG_ID3v1Tag object or false if there is no ID3v1 tag.
KTaglib_MPEG_File::getID3v2Tag
(0.0.1)
KTaglib_MPEG_File::getID3v2Tag — Returns a ID3v2 object
Descrição
Returns a ID3v2 object for the mpeg file. If no ID3v2 Tag is present, an KTaglib_TagNotFoundException is thrown.
Valor Retornado
Returns the KTaglib_ID3v2_Tag object of the MPEG file or false if there is no ID3v2 tag
Índice
- KTaglib_MPEG_File::__construct — Opens a new file
- KTaglib_MPEG_File::getAudioProperties — Returns an object that provides access to the audio properties
- KTaglib_MPEG_File::getID3v1Tag — Returns an object representing an ID3v1 tag
- KTaglib_MPEG_File::getID3v2Tag — Returns a ID3v2 object
The KTaglib_MPEG_AudioProperties class
(No version information available, might only be in SVN)
Introdução
Represents the audio properties of a MPEG file, like length, bitrate or samplerate.
Class synopsis
KTaglib_MPEG_AudioProperties::getBitrate
(0.0.1)
KTaglib_MPEG_AudioProperties::getBitrate — Returns the bitrate of the MPEG file
Descrição
Returns the bitrate of the MPEG file
Valor Retornado
Returns the bitrate as an integer
KTaglib_MPEG_AudioProperties::getChannels
(0.0.1)
KTaglib_MPEG_AudioProperties::getChannels — Returns the amount of channels of a MPEG file
Descrição
Returns the amount of channels of the MPEG file
Valor Retornado
Returns the channel count as an integer
KTaglib_MPEG_AudioProperties::getLayer
(0.0.1)
KTaglib_MPEG_AudioProperties::getLayer — Returns the layer of a MPEG file
Descrição
Returns the layer of the MPEG file (usually 3 for MP3).
Valor Retornado
Returns the layer as an integer
KTaglib_MPEG_AudioProperties::getLength
(0.0.1)
KTaglib_MPEG_AudioProperties::getLength — Returns the length of a MPEG file
Descrição
Returns the length of the MPEG file
Valor Retornado
Returns the length as an integer
KTaglib_MPEG_AudioProperties::getSampleBitrate
(0.0.1)
KTaglib_MPEG_AudioProperties::getSampleBitrate — Returns the sample bitrate of a MPEG file
Descrição
Returns the sample bitrate of the MPEG file
Valor Retornado
Returns the sample bitrate as an integer
KTaglib_MPEG_AudioProperties::getVersion
(0.0.1)
KTaglib_MPEG_AudioProperties::getVersion — Returns the version of a MPEG file
Descrição
Returns the version of the MPEG file header. The possible versions are defined in Tag_MPEG_Header (Version1, Version2, Version2.5).
Valor Retornado
Returns the version
KTaglib_MPEG_AudioProperties::isCopyrighted
(0.0.1)
KTaglib_MPEG_AudioProperties::isCopyrighted — Returns the length of a MPEG file
Descrição
Returns true if the MPEG file is copyrighted
Valor Retornado
Returns true if the MPEG file is copyrighted
KTaglib_MPEG_AudioProperties::isOriginal
(0.0.1)
KTaglib_MPEG_AudioProperties::isOriginal — Returns the length of a MPEG file
Descrição
Returns true if the file is marked as the original file
Valor Retornado
Returns true if the file is marked as the original file
KTaglib_MPEG_AudioProperties::isProtectionEnabled
(0.0.1)
KTaglib_MPEG_AudioProperties::isProtectionEnabled — Returns the length of a MPEG file
Descrição
Returns true if protection mechanism (like DRM) are enabled for this file
Valor Retornado
Returns true if protection mechanism (like DRM) are enabled for this file
Índice
- KTaglib_MPEG_AudioProperties::getBitrate — Returns the bitrate of the MPEG file
- KTaglib_MPEG_AudioProperties::getChannels — Returns the amount of channels of a MPEG file
- KTaglib_MPEG_AudioProperties::getLayer — Returns the layer of a MPEG file
- KTaglib_MPEG_AudioProperties::getLength — Returns the length of a MPEG file
- KTaglib_MPEG_AudioProperties::getSampleBitrate — Returns the sample bitrate of a MPEG file
- KTaglib_MPEG_AudioProperties::getVersion — Returns the version of a MPEG file
- KTaglib_MPEG_AudioProperties::isCopyrighted — Returns the length of a MPEG file
- KTaglib_MPEG_AudioProperties::isOriginal — Returns the length of a MPEG file
- KTaglib_MPEG_AudioProperties::isProtectionEnabled — Returns the length of a MPEG file
The KTaglib_Tag class
(No version information available, might only be in SVN)
Introdução
Base class for ID3v1 or ID3v2 tags
KTaglib_Tag::getAlbum
(0.0.1)
KTaglib_Tag::getAlbum — Returns the title string from a ID3 tag
Descrição
Returns the album string of an ID3 tag. This method is implemented in ID3v1 and ID3v2 tags.
Valor Retornado
Returns the album string
KTaglib_Tag::getArtist
(0.0.1)
KTaglib_Tag::getArtist — Returns the artist string from a ID3 tag
Descrição
Returns the artist string of an ID3 tag. This method is implemented in ID3v1 and ID3v2 tags.
Valor Retornado
Returns the artist string
KTaglib_Tag::getComment
(0.0.1)
KTaglib_Tag::getComment — Returns the comment from a ID3 tag
Descrição
Returns the comment of an ID3 tag. This method is implemented in ID3v1 and ID3v2 tags.
Valor Retornado
Returns the comment string
KTaglib_Tag::getGenre
(0.0.1)
KTaglib_Tag::getGenre — Returns the genre from a ID3 tag
Descrição
Returns the genre of an ID3 tag. This method is implemented in ID3v1 and ID3v2 tags.
Valor Retornado
Returns the genre string
KTaglib_Tag::getTitle
(0.0.1)
KTaglib_Tag::getTitle — Returns the title string from a ID3 tag
Descrição
Returns the title string of an ID3 tag. This method is implemented in ID3v1 and ID3v2 tags.
Valor Retornado
Returns the title string
KTaglib_Tag::getTrack
(0.0.1)
KTaglib_Tag::getTrack — Returns the track number from a ID3 tag
Descrição
Returns the track number of an ID3 tag. This method is implemented in ID3v1 and ID3v2 tags.
Valor Retornado
Returns the track number as an integer
KTaglib_Tag::getYear
(0.0.1)
KTaglib_Tag::getYear — Returns the year from a ID3 tag
Descrição
Returns the year of an ID3 tag. This method is implemented in ID3v1 and ID3v2 tags.
Valor Retornado
Returns the year as an integer
KTaglib_Tag::isEmpty
(0.0.1)
KTaglib_Tag::isEmpty — Returns true if the tag is empty
Descrição
Returns true if the tag exists, but is empty. This method is implemented in ID3v1 and ID3v2 tags.
Valor Retornado
Returns true if the tag is empty, otherwise false.
Índice
- KTaglib_Tag::getAlbum — Returns the title string from a ID3 tag
- KTaglib_Tag::getArtist — Returns the artist string from a ID3 tag
- KTaglib_Tag::getComment — Returns the comment from a ID3 tag
- KTaglib_Tag::getGenre — Returns the genre from a ID3 tag
- KTaglib_Tag::getTitle — Returns the title string from a ID3 tag
- KTaglib_Tag::getTrack — Returns the track number from a ID3 tag
- KTaglib_Tag::getYear — Returns the year from a ID3 tag
- KTaglib_Tag::isEmpty — Returns true if the tag is empty
The KTaglib_ID3v2_Tag class
(No version information available, might only be in SVN)
Introdução
Represents and ID3v2 tag. It provides a list of ID3v2 frames and can be used to add and remove additional frames.
Class synopsis
KTaglib_ID3v2_Tag::addFrame
(0.0.1)
KTaglib_ID3v2_Tag::addFrame — Add a frame to the ID3v2 tag
Descrição
Adds a frame to the ID3v2 tag. The frame must be a valid KTaglib_ID3v2_Frame object. To save the tag, the save function needs to be invoked.
Valor Retornado
Returns true on success, otherwise false.
KTaglib_ID3v2_Tag::getFrameList
(0.0.1)
KTaglib_ID3v2_Tag::getFrameList — Returns an array of ID3v2 frames, associated with the ID3v2 tag
Descrição
Returns an array of ID3v2 frames, associated with the ID3v2 tag.
Valor Retornado
Return an array of KTaglib_ID3v2_Frame objects
Índice
- KTaglib_ID3v2_Tag::addFrame — Add a frame to the ID3v2 tag
- KTaglib_ID3v2_Tag::getFrameList — Returns an array of ID3v2 frames, associated with the ID3v2 tag
The KTaglib_ID3v2_Frame class
(No version information available, might only be in SVN)
Introdução
The base class for ID3v2 frames. ID3v2 tags are separated in various specialized frames. Some frames can exists multiple times.
Class synopsis
KTaglib_ID3v2_Frame::getSize
(0.0.1)
KTaglib_ID3v2_Frame::getSize — Returns the size of the frame in bytes
Descrição
Returns the size of the frame in bytes. Please refer to id3.org to see what ID3v2 frames are and how they are defined.
Valor Retornado
Returns the size of the frame in bytes
KTaglib_ID3v2_Frame::__toString
(0.0.1)
KTaglib_ID3v2_Frame::__toString — Returns a string representation of the frame
Descrição
Returns a string representation of the frame. This might be just the frame id, but might contain more information. Please see the ktaglib documentation for more information
Valor Retornado
Returns a string representation of the frame.
Índice
- KTaglib_ID3v2_Frame::getSize — Returns the size of the frame in bytes
- KTaglib_ID3v2_Frame::__toString — Returns a string representation of the frame
The KTaglib_ID3v2_AttachedPictureFrame class
(No version information available, might only be in SVN)
Introdução
Represents an ID3v2 frame that can hold a picture.
Class synopsis
KTaglib_ID3v2_AttachedPictureFrame::getDescription
(0.0.1)
KTaglib_ID3v2_AttachedPictureFrame::getDescription — Returns a description for the picture in a picture frame
Descrição
Returns the attached description for a picture frame in an ID3v2.x frame.
Valor Retornado
Returns a description for the picture in a picture frame
KTaglib_ID3v2_AttachedPictureFrame::getMimeType
(0.2.0)
KTaglib_ID3v2_AttachedPictureFrame::getMimeType — Returns the mime type of the picture
Descrição
Returns the mime type of the image represented by the attached picture frame.
Please notice that this method might return different types. While ID3v2.2 have a mime type that doesn't start with "image/", ID3v2.3 and v2.4 usually start with "image/". Therefore the method might return "image/png" for IDv2.3 frames and just "PNG" for ID3v2.2 frames.
Notice that even the frame is an attached picture, the mime type might not be set and therefore an empty string might be returned.
Valor Retornado
Returns the mime type of the image represented by the attached picture frame.
KTaglib_ID3v2_AttachedPictureFrame::getType
(0.2.0)
KTaglib_ID3v2_AttachedPictureFrame::getType — Returns the type of the image
Descrição
Returns the type of the image.
The ID3v2 specification allows an AttachedPictureFrame to set the type of an image. This can be e.g. FrontCover or FileIcon. Please refer to the KTaglib_ID3v2_AttachedPictureFrame class description for a list of available types.
Valor Retornado
Returns the integer representation of the type.
KTaglib_ID3v2_AttachedPictureFrame::savePicture
(0.0.1)
KTaglib_ID3v2_AttachedPictureFrame::savePicture — Saves the picture to a file
Descrição
Saves the attached picture to the given filename.
Valor Retornado
Returns true on success, otherwise false
KTaglib_ID3v2_AttachedPictureFrame::setMimeType
(0.2.0)
KTaglib_ID3v2_AttachedPictureFrame::setMimeType — Set's the mime type of the picture
Descrição
Sets the mime type of the image. This should in most cases be "image/png" or "image/jpeg".
KTaglib_ID3v2_AttachedPictureFrame::setPicture
(0.0.1)
KTaglib_ID3v2_AttachedPictureFrame::setPicture — Sets the frame picture to the given image
Descrição
Sets the picture to the give image. The image is loaded from the given filename. Please note that the picture is not saved unless you call the save method of the corresponding file object.
Valor Retornado
Returns true on success, otherwise false
KTaglib_ID3v2_AttachedPictureFrame::setType
(0.2.0)
KTaglib_ID3v2_AttachedPictureFrame::setType — Set the type of the image
Descrição
Sets the type of the image. This can be e.g. FrontCover or FileIcon. Please refer to the KTaglib_ID3v2_AttachedPictureFrame class description for a list of available types and their constant mappings.
Índice
- KTaglib_ID3v2_AttachedPictureFrame::getDescription — Returns a description for the picture in a picture frame
- KTaglib_ID3v2_AttachedPictureFrame::getMimeType — Returns the mime type of the picture
- KTaglib_ID3v2_AttachedPictureFrame::getType — Returns the type of the image
- KTaglib_ID3v2_AttachedPictureFrame::savePicture — Saves the picture to a file
- KTaglib_ID3v2_AttachedPictureFrame::setMimeType — Set's the mime type of the picture
- KTaglib_ID3v2_AttachedPictureFrame::setPicture — Sets the frame picture to the given image
- KTaglib_ID3v2_AttachedPictureFrame::setType — Set the type of the image
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- KTaglib_MPEG_File — The KTaglib_MPEG_File class
- KTaglib_MPEG_File::__construct — Opens a new file
- KTaglib_MPEG_File::getAudioProperties — Returns an object that provides access to the audio properties
- KTaglib_MPEG_File::getID3v1Tag — Returns an object representing an ID3v1 tag
- KTaglib_MPEG_File::getID3v2Tag — Returns a ID3v2 object
- KTaglib_MPEG_AudioProperties — The KTaglib_MPEG_AudioProperties class
- KTaglib_MPEG_AudioProperties::getBitrate — Returns the bitrate of the MPEG file
- KTaglib_MPEG_AudioProperties::getChannels — Returns the amount of channels of a MPEG file
- KTaglib_MPEG_AudioProperties::getLayer — Returns the layer of a MPEG file
- KTaglib_MPEG_AudioProperties::getLength — Returns the length of a MPEG file
- KTaglib_MPEG_AudioProperties::getSampleBitrate — Returns the sample bitrate of a MPEG file
- KTaglib_MPEG_AudioProperties::getVersion — Returns the version of a MPEG file
- KTaglib_MPEG_AudioProperties::isCopyrighted — Returns the length of a MPEG file
- KTaglib_MPEG_AudioProperties::isOriginal — Returns the length of a MPEG file
- KTaglib_MPEG_AudioProperties::isProtectionEnabled — Returns the length of a MPEG file
- KTaglib_Tag — The KTaglib_Tag class
- KTaglib_Tag::getAlbum — Returns the title string from a ID3 tag
- KTaglib_Tag::getArtist — Returns the artist string from a ID3 tag
- KTaglib_Tag::getComment — Returns the comment from a ID3 tag
- KTaglib_Tag::getGenre — Returns the genre from a ID3 tag
- KTaglib_Tag::getTitle — Returns the title string from a ID3 tag
- KTaglib_Tag::getTrack — Returns the track number from a ID3 tag
- KTaglib_Tag::getYear — Returns the year from a ID3 tag
- KTaglib_Tag::isEmpty — Returns true if the tag is empty
- KTaglib_ID3v2_Tag — The KTaglib_ID3v2_Tag class
- KTaglib_ID3v2_Tag::addFrame — Add a frame to the ID3v2 tag
- KTaglib_ID3v2_Tag::getFrameList — Returns an array of ID3v2 frames, associated with the ID3v2 tag
- KTaglib_ID3v2_Frame — The KTaglib_ID3v2_Frame class
- KTaglib_ID3v2_Frame::getSize — Returns the size of the frame in bytes
- KTaglib_ID3v2_Frame::__toString — Returns a string representation of the frame
- KTaglib_ID3v2_AttachedPictureFrame — The KTaglib_ID3v2_AttachedPictureFrame class
- KTaglib_ID3v2_AttachedPictureFrame::getDescription — Returns a description for the picture in a picture frame
- KTaglib_ID3v2_AttachedPictureFrame::getMimeType — Returns the mime type of the picture
- KTaglib_ID3v2_AttachedPictureFrame::getType — Returns the type of the image
- KTaglib_ID3v2_AttachedPictureFrame::savePicture — Saves the picture to a file
- KTaglib_ID3v2_AttachedPictureFrame::setMimeType — Set's the mime type of the picture
- KTaglib_ID3v2_AttachedPictureFrame::setPicture — Sets the frame picture to the given image
- KTaglib_ID3v2_AttachedPictureFrame::setType — Set the type of the image
OGG/Vorbis
Introdução
The OGG/Vorbis file format, as defined by » http://www.vorbis.com/, is a scheme for compressing audio streams by multiple factors with a minimum of quality loss. This extension adds Ogg Vorbis support to PHP's URL Wrappers. When used in read mode, compressed OGG/Vorbis data is expanded to raw PCM audio in one of six PCM encoding formats listed below.
Instalação/Configuração
Índice
Instalação
Informações para a instalação desta extensão PECL podem ser encontradas no manual no capitulo intitulado Instalação de extensões PECL. Informações adicionais como novas versões, downloads, arquivos fontes, manutenções, e um Changelog, podem ser obtidos aqui: » http://pecl.php.net/package/oggvorbis
Configurações em Execução
Esta extensão não define nenhum parâmetro de configuração no php.ini.
Tipos Resource
Esta extensão não possui nenhum tipo resource.
Constantes pré-definidas
As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.
| Constant | Definition |
|---|---|
| OGGVORBIS_PCM_U8 | Unsigned 8-bit PCM. |
| OGGVORBIS_PCM_S8 | Signed 8-bit PCM. |
| OGGVORBIS_PCM_U16_LE | Unsigned 16-bit PCM. Little Endian byte order. |
| OGGVORBIS_PCM_U16_BE | Unsigned 16-bit PCM. Big Endian byte order. |
| OGGVORBIS_PCM_S16_LE | Signed 16-bit PCM. Little Endian byte order. |
| OGGVORBIS_PCM_S16_BE | Signed 16-bit PCM. Big Endian byte order. |
Context options
| Option | Definition | Relevance | Default |
|---|---|---|---|
| pcm_mode | PCM byte encoding used. See constants below. | Read / Write | OGGVORBIS_PCM_S16_LE |
| rate | PCM Sampling rate. Measured in Hz. | Write only | 44100 |
| bitrate | Vorbis Average Bitrate Encoding / Variable Bitrate Encoding. Measured in bps (ABR) or Quality level (VBR: 0.0 to 1.0). 128000 ABR is rough equal to 0.4 VBR. | Write only | 128000 |
| channels | Number of PCM channels. 1 == Mono, 2 == Stereo. | Write only | 2 |
| serialno | Serial Number of stream within file. Must be unique within file. Because of the potential to select a duplicate serial number within a chained file, make efforts to manually assign unique numbers when encoding. | Write only | Random |
| comments | Associative array of file comments. Will be translated to strtoupper($name) . "=$value". Note: This context option is not available in oggvorbis-0.1 | Write only | array('ENCODER' => 'PHP/OggVorbis, http://pear.php.net/oggvorbis') |
Exemplos
Índice
Examples on using the ogg:// wrapper.
Exemplo #1 Reading an OGG/Vorbis file
<?php
dl("oggvorbis.so");
/* By default, ogg:// will decode to Signed 16-bit Little Endian */
$fp = fopen('ogg://myaudio.ogg', 'r');
/* Collect some information about the file. */
$metadata = stream_get_meta_data($fp);
/* Inspect the first song (usually the only song,
but OGG/Vorbis files may be chained) */
$songdata = $metadata['wrapper_data'][0];
echo "OGG/Vorbis file encoded by: {$songdata['vendor']}\n.";
echo " {$songdata['channels']} channels of {$songdata['rate']}Hz sampling encoded at {$songdata['bitrate_nominal']}bps.\n";
foreach($songdata['comments'] as $comment) {
echo " $comment\n";
}
while ($audio_data = fread($fp, 8192)) {
/* Do something with the PCM audio we're extracting from the OGG.
Copying to /dev/dsp is a good target on linux systems,
just remember to setup the device for your sampling mode first. */
}
fclose($fp);
?>
Exemplo #2 Encode an audio file to OGG/Vorbis
<?php
dl('oggvorbis.so');
$context = stream_context_create(array('ogg'=>array(
'pcm_mode' => OGGVORBIS_PCM_S8, /* Signed 8bit audio */
'rate' => 44100, /* 44kHz CD quality */
'bitrate' => 0.5, /* Midquality VBR */
'channels' => 1, /* Mono */
'serialno' => 12345))); /* Unique within our stream */
/* Open file for appending. This will "chain" a second OGG stream at the end of the first. */
$ogg = fopen('ogg://mysong.ogg', 'a', false, $context);
$pcm = fopen('mysample.pcm', 'r');
/* Compress the raw PCM audio from mysample.pcm into mysong.ogg */
stream_copy_to_stream($pcm, $ogg);
fclose($pcm);
fclose($ogg);
?>
OpenAL Audio Bindings
Instalação/Configuração
Índice
Dependências
Nenhuma biblioteca externa é necessária para compilar esta extensão.
Instalação
Esta extensão » PECL não vem compilada com o PHP.
Informações para a instalação desta extensão PECL podem ser encontradas no manual no capitulo intitulado Instalação de extensões PECL. Informações adicionais como novas versões, downloads, arquivos fontes, manutenções, e um Changelog, podem ser obtidos aqui: » http://pecl.php.net/package/openal.
Uma DLL para esta extenção PECL esta atualmente indisponível. Veja também a seção compilando no Windows section.
Configurações em Execução
Esta extensão não define nenhum parâmetro de configuração no php.ini.
Tipos Resource
This extension defines four resource types: Open AL(Device) - Returned by openal_device_open(), Open AL(Context) - Returned by openal_context_create(), Open AL(Buffer) - Returned by openal_buffer_create(), and Open AL(Source) - Returned by openal_source_create().
Constantes pré-definidas
As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.
- ALC_FREQUENCY (integer)
- Context Attribute
- ALC_REFRESH (integer)
- Context Attribute
- ALC_SYNC (integer)
- Context Attribute
- AL_FREQUENCY (integer)
- Buffer Setting
- AL_BITS (integer)
- Buffer Setting
- AL_CHANNELS (integer)
- Buffer Setting
- AL_SIZE (integer)
- Buffer Setting
- AL_BUFFER (integer)
- Source/Listener Setting (Integer)
- AL_SOURCE_RELATIVE (integer)
- Source/Listener Setting (Integer)
- AL_SOURCE_STATE (integer)
- Source/Listener Setting (Integer)
- AL_PITCH (integer)
- Source/Listener Setting (Float)
- AL_GAIN (integer)
- Source/Listener Setting (Float)
- AL_MIN_GAIN (integer)
- Source/Listener Setting (Float)
- AL_MAX_GAIN (integer)
- Source/Listener Setting (Float)
- AL_MAX_DISTANCE (integer)
- Source/Listener Setting (Float)
- AL_ROLLOFF_FACTOR (integer)
- Source/Listener Setting (Float)
- AL_CONE_OUTER_GAIN (integer)
- Source/Listener Setting (Float)
- AL_CONE_INNER_ANGLE (integer)
- Source/Listener Setting (Float)
- AL_CONE_OUTER_ANGLE (integer)
- Source/Listener Setting (Float)
- AL_REFERENCE_DISTANCE (integer)
- Source/Listener Setting (Float)
- AL_POSITION (integer)
- Source/Listener Setting (Float Vector)
- AL_VELOCITY (integer)
- Source/Listener Setting (Float Vector)
- AL_DIRECTION (integer)
- Source/Listener Setting (Float Vector)
- AL_ORIENTATION (integer)
- Source/Listener Setting (Float Vector)
- AL_FORMAT_MONO8 (integer)
- PCM Format
- AL_FORMAT_MONO16 (integer)
- PCM Format
- AL_FORMAT_STEREO8 (integer)
- PCM Format
- AL_FORMAT_STEREO16 (integer)
- PCM Format
- AL_INITIAL (integer)
- Source State
- AL_PLAYING (integer)
- Source State
- AL_PAUSED (integer)
- Source State
- AL_STOPPED (integer)
- Source State
- AL_LOOPING (integer)
- Source State
- AL_TRUE (integer)
- Boolean value recognized by OpenAL
- AL_FALSE (integer)
- Boolean value recognized by OpenAL
OpenAL Funções
openal_buffer_create
(PECL openal >= 0.1.0)
openal_buffer_create — Generate OpenAL buffer
Descrição
Valor Retornado
Returns an Open AL(Buffer) resource on success or FALSE on failure.
Veja Também
- openal_buffer_loadwav() - Load a .wav file into a buffer
- openal_buffer_data() - Load a buffer with data
openal_buffer_data
(PECL openal >= 0.1.0)
openal_buffer_data — Load a buffer with data
Descrição
Parâmetros
- buffer
-
An Open AL(Buffer) resource (previously created by openal_buffer_create()).
- format
-
Format of data, one of: AL_FORMAT_MONO8, AL_FORMAT_MONO16, AL_FORMAT_STEREO8 e AL_FORMAT_STEREO16
- data
-
Block of binary audio data in the format and freq specified.
- freq
-
Frequency of data given in Hz.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Veja Também
- openal_buffer_loadwav() - Load a .wav file into a buffer
- openal_stream() - Begin streaming on a source
openal_buffer_destroy
(PECL openal >= 0.1.0)
openal_buffer_destroy — Destroys an OpenAL buffer
Descrição
Parâmetros
- buffer
-
An Open AL(Buffer) resource (previously created by openal_buffer_create()).
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
openal_buffer_get
(PECL openal >= 0.1.0)
openal_buffer_get — Retrieve an OpenAL buffer property
Descrição
Parâmetros
- buffer
-
An Open AL(Buffer) resource (previously created by openal_buffer_create()).
- property
-
Specific property, one of: AL_FREQUENCY, AL_BITS, AL_CHANNELS e AL_SIZE.
Valor Retornado
Returns an integer value appropriate to the property requested or FALSE on failure.
openal_buffer_loadwav
(PECL openal >= 0.1.0)
openal_buffer_loadwav — Load a .wav file into a buffer
Descrição
Parâmetros
- buffer
-
An Open AL(Buffer) resource (previously created by openal_buffer_create()).
- wavfile
-
Path to .wav file on local file system.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Veja Também
- openal_buffer_data() - Load a buffer with data
- openal_stream() - Begin streaming on a source
openal_context_create
(PECL openal >= 0.1.0)
openal_context_create — Create an audio processing context
Descrição
Parâmetros
- device
-
An Open AL(Device) resource (previously created by openal_device_open()).
Valor Retornado
Returns an Open AL(Context) resource on success or FALSE on failure.
Veja Também
- openal_device_open() - Initialize the OpenAL audio layer
- openal_context_destroy() - Destroys a context
openal_context_current
(PECL openal >= 0.1.0)
openal_context_current — Make the specified context current
Descrição
Parâmetros
- context
-
An Open AL(Context) resource (previously created by openal_context_create()).
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
openal_context_destroy
(PECL openal >= 0.1.0)
openal_context_destroy — Destroys a context
Descrição
Parâmetros
- context
-
An Open AL(Context) resource (previously created by openal_context_create()).
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
openal_context_process
(PECL openal >= 0.1.0)
openal_context_process — Process the specified context
Descrição
Parâmetros
- context
-
An Open AL(Context) resource (previously created by openal_context_create()).
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Veja Também
- openal_context_create() - Create an audio processing context
- openal_context_current() - Make the specified context current
- openal_context_suspend() - Suspend the specified context
openal_context_suspend
(PECL openal >= 0.1.0)
openal_context_suspend — Suspend the specified context
Descrição
Parâmetros
- context
-
An Open AL(Context) resource (previously created by openal_context_create()).
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Veja Também
- openal_context_create() - Create an audio processing context
- openal_context_current() - Make the specified context current
- openal_context_process() - Process the specified context
openal_device_close
(PECL openal >= 0.1.0)
openal_device_close — Close an OpenAL device
Descrição
Parâmetros
- device
-
An Open AL(Device) resource (previously created by openal_device_open()) to be closed.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
openal_device_open
(PECL openal >= 0.1.0)
openal_device_open — Initialize the OpenAL audio layer
Descrição
Parâmetros
- device_desc
-
Open an audio device optionally specified by device_desc. If device_desc is not specified the first available audio device will be used.
Valor Retornado
Returns an Open AL(Device) resource on success or FALSE on failure.
Veja Também
- openal_device_close() - Close an OpenAL device
- openal_context_create() - Create an audio processing context
openal_listener_get
(PECL openal >= 0.1.0)
openal_listener_get — Retrieve a listener property
Descrição
Parâmetros
- property
-
Property to retrieve, one of: AL_GAIN (float), AL_POSITION (array(float,float,float)), AL_VELOCITY (array(float,float,float)) e AL_ORIENTATION (array(float,float,float)).
Valor Retornado
Returns a float or array of floats (as appropriate) or FALSE on failure.
openal_listener_set
(PECL openal >= 0.1.0)
openal_listener_set — Set a listener property
Descrição
Parâmetros
- property
-
Property to set, one of: AL_GAIN (float), AL_POSITION (array(float,float,float)), AL_VELOCITY (array(float,float,float)) e AL_ORIENTATION (array(float,float,float)).
- setting
-
Value to set, either float, or an array of floats as appropriate.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
openal_source_create
(PECL openal >= 0.1.0)
openal_source_create — Generate a source resource
Descrição
Valor Retornado
Returns an Open AL(Source) resource on success or FALSE on failure.
Veja Também
- openal_source_set() - Set source property
- openal_source_play() - Start playing the source
- openal_source_destroy() - Destroy a source resource
openal_source_destroy
(PECL openal >= 0.1.0)
openal_source_destroy — Destroy a source resource
Descrição
Parâmetros
- source
-
An Open AL(Source) resource (previously created by openal_source_create()).
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
openal_source_get
(PECL openal >= 0.1.0)
openal_source_get — Retrieve an OpenAL source property
Descrição
Parâmetros
- source
-
An Open AL(Source) resource (previously created by openal_source_create()).
- property
-
Property to get, one of: AL_SOURCE_RELATIVE (int), AL_SOURCE_STATE (int), AL_PITCH (float), AL_GAIN (float), AL_MIN_GAIN (float), AL_MAX_GAIN (float), AL_MAX_DISTANCE (float), AL_ROLLOFF_FACTOR (float), AL_CONE_OUTER_GAIN (float), AL_CONE_INNER_ANGLE (float), AL_CONE_OUTER_ANGLE (float), AL_REFERENCE_DISTANCE (float), AL_POSITION (array(float,float,float)), AL_VELOCITY (array(float,float,float)), AL_DIRECTION (array(float,float,float)).
Valor Retornado
Returns the type associated with the property being retrieved or FALSE on failure.
Veja Também
- openal_source_create() - Generate a source resource
- openal_source_set() - Set source property
- openal_source_play() - Start playing the source
openal_source_pause
(PECL openal >= 0.1.0)
openal_source_pause — Pause the source
Descrição
Parâmetros
- source
-
An Open AL(Source) resource (previously created by openal_source_create()).
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Veja Também
- openal_source_stop() - Stop playing the source
- openal_source_play() - Start playing the source
- openal_source_rewind() - Rewind the source
openal_source_play
(PECL openal >= 0.1.0)
openal_source_play — Start playing the source
Descrição
Parâmetros
- source
-
An Open AL(Source) resource (previously created by openal_source_create()).
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Veja Também
- openal_source_stop() - Stop playing the source
- openal_source_pause() - Pause the source
- openal_source_rewind() - Rewind the source
openal_source_rewind
(PECL openal >= 0.1.0)
openal_source_rewind — Rewind the source
Descrição
Parâmetros
- source
-
An Open AL(Source) resource (previously created by openal_source_create()).
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Veja Também
- openal_source_stop() - Stop playing the source
- openal_source_pause() - Pause the source
- openal_source_play() - Start playing the source
openal_source_set
(PECL openal >= 0.1.0)
openal_source_set — Set source property
Descrição
Parâmetros
- source
-
An Open AL(Source) resource (previously created by openal_source_create()).
- property
-
Property to set, one of: AL_BUFFER (OpenAL(Source)), AL_LOOPING (bool), AL_SOURCE_RELATIVE (int), AL_SOURCE_STATE (int), AL_PITCH (float), AL_GAIN (float), AL_MIN_GAIN (float), AL_MAX_GAIN (float), AL_MAX_DISTANCE (float), AL_ROLLOFF_FACTOR (float), AL_CONE_OUTER_GAIN (float), AL_CONE_INNER_ANGLE (float), AL_CONE_OUTER_ANGLE (float), AL_REFERENCE_DISTANCE (float), AL_POSITION (array(float,float,float)), AL_VELOCITY (array(float,float,float)), AL_DIRECTION (array(float,float,float)).
- setting
-
Value to assign to specified property. Refer to the description of property for a description of the value(s) expected.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Veja Também
- openal_source_create() - Generate a source resource
- openal_source_get() - Retrieve an OpenAL source property
- openal_source_play() - Start playing the source
openal_source_stop
(PECL openal >= 0.1.0)
openal_source_stop — Stop playing the source
Descrição
Parâmetros
- source
-
An Open AL(Source) resource (previously created by openal_source_create()).
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Veja Também
- openal_source_play() - Start playing the source
- openal_source_pause() - Pause the source
- openal_source_rewind() - Rewind the source
openal_stream
(PECL openal >= 0.1.0)
openal_stream — Begin streaming on a source
Descrição
Parâmetros
- source
-
An Open AL(Source) resource (previously created by openal_source_create()).
- format
-
Format of data, one of: AL_FORMAT_MONO8, AL_FORMAT_MONO16, AL_FORMAT_STEREO8 e AL_FORMAT_STEREO16
- rate
-
Frequency of data to stream given in Hz.
Valor Retornado
Returns a stream resource on success or FALSE on failure.
Veja Também
- openal_source_create() - Generate a source resource
- fwrite() - Escrita binary-safe em arquivos
Índice
- openal_buffer_create — Generate OpenAL buffer
- openal_buffer_data — Load a buffer with data
- openal_buffer_destroy — Destroys an OpenAL buffer
- openal_buffer_get — Retrieve an OpenAL buffer property
- openal_buffer_loadwav — Load a .wav file into a buffer
- openal_context_create — Create an audio processing context
- openal_context_current — Make the specified context current
- openal_context_destroy — Destroys a context
- openal_context_process — Process the specified context
- openal_context_suspend — Suspend the specified context
- openal_device_close — Close an OpenAL device
- openal_device_open — Initialize the OpenAL audio layer
- openal_listener_get — Retrieve a listener property
- openal_listener_set — Set a listener property
- openal_source_create — Generate a source resource
- openal_source_destroy — Destroy a source resource
- openal_source_get — Retrieve an OpenAL source property
- openal_source_pause — Pause the source
- openal_source_play — Start playing the source
- openal_source_rewind — Rewind the source
- openal_source_set — Set source property
- openal_source_stop — Stop playing the source
- openal_stream — Begin streaming on a source
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- OpenAL Funções
- openal_buffer_create — Generate OpenAL buffer
- openal_buffer_data — Load a buffer with data
- openal_buffer_destroy — Destroys an OpenAL buffer
- openal_buffer_get — Retrieve an OpenAL buffer property
- openal_buffer_loadwav — Load a .wav file into a buffer
- openal_context_create — Create an audio processing context
- openal_context_current — Make the specified context current
- openal_context_destroy — Destroys a context
- openal_context_process — Process the specified context
- openal_context_suspend — Suspend the specified context
- openal_device_close — Close an OpenAL device
- openal_device_open — Initialize the OpenAL audio layer
- openal_listener_get — Retrieve a listener property
- openal_listener_set — Set a listener property
- openal_source_create — Generate a source resource
- openal_source_destroy — Destroy a source resource
- openal_source_get — Retrieve an OpenAL source property
- openal_source_pause — Pause the source
- openal_source_play — Start playing the source
- openal_source_rewind — Rewind the source
- openal_source_set — Set source property
- openal_source_stop — Stop playing the source
- openal_stream — Begin streaming on a source
- ID3 — ID3 Tags
- KTaglib
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- KTaglib_MPEG_File — The KTaglib_MPEG_File class
- KTaglib_MPEG_AudioProperties — The KTaglib_MPEG_AudioProperties class
- KTaglib_Tag — The KTaglib_Tag class
- KTaglib_ID3v2_Tag — The KTaglib_ID3v2_Tag class
- KTaglib_ID3v2_Frame — The KTaglib_ID3v2_Frame class
- KTaglib_ID3v2_AttachedPictureFrame — The KTaglib_ID3v2_AttachedPictureFrame class
- oggvorbis — OGG/Vorbis
- OpenAL — OpenAL Audio Bindings
Serviços de Autenticação
Kerberos V
Introdução
These package allows you to access Kerberos V administration servers. You can create, modify, and delete Kerberos V principals and policies.
More information about Kerberos can be found at » http://web.mit.edu/kerberos/www/.
Documentation for Kerberos and KADM5 can be found at » http://web.mit.edu/kerberos/www/krb5-1.2/krb5-1.2.8/doc/admin_toc.html.
Instalação/Configuração
Índice
Dependências
Nenhuma biblioteca externa é necessária para compilar esta extensão.
Instalação
Informações para a instalação desta extensão PECL podem ser encontradas no manual no capitulo intitulado Instalação de extensões PECL. Informações adicionais como novas versões, downloads, arquivos fontes, manutenções, e um Changelog, podem ser obtidos aqui: » http://pecl.php.net/package/kadm5.
Nota:
If this option is used without specifying the path to KADM5, PHP will use the built-in KADM5 client libraries. Users who run other applications that use KADM5 (for example, running PHP 4 and PHP 5 as concurrent apache modules, or auth-kadm5) should always specify the path to KADM5: --with-kadm5=/path/to/kadm5. This will force PHP to use the client libraries installed by KADM5, avoiding any conflicts.
Uma DLL para esta extenção PECL esta atualmente indisponível. Veja também a seção compilando no Windows section.
Configurações em Execução
Esta extensão não define nenhum parâmetro de configuração no php.ini.
Constantes pré-definidas
Índice
As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.
Constants for Attribute Flags
The functions kadm5_create_principal(), kadm5_modify_principal(), and kadm5_modify_principal() allow to specify special attributes using a bitfield. The symbols are defined below:
| constant |
|---|
| KRB5_KDB_DISALLOW_POSTDATED |
| KRB5_KDB_DISALLOW_FORWARDABLE |
| KRB5_KDB_DISALLOW_TGT_BASED |
| KRB5_KDB_DISALLOW_RENEWABLE |
| KRB5_KDB_DISALLOW_PROXIABLE |
| KRB5_KDB_DISALLOW_DUP_SKEY |
| KRB5_KDB_DISALLOW_ALL_TIX |
| KRB5_KDB_REQUIRES_PRE_AUTH |
| KRB5_KDB_REQUIRES_HW_AUTH |
| KRB5_KDB_REQUIRES_PWCHANGE |
| KRB5_KDB_DISALLOW_SVR |
| KRB5_KDB_PWCHANGE_SERVER |
| KRB5_KDB_SUPPORT_DESMD5 |
| KRB5_KDB_NEW_PRINC |
Constants for Options
The functions kadm5_create_principal(), kadm5_modify_principal(), and kadm5_get_principal() allow to specify or return principal's options as an associative array. The keys for the associative array are defined as string constants below:
| constant | funcdef | description |
|---|---|---|
| KADM5_PRINCIPAL | long | The expire time of the princial as a Kerberos timestamp. |
| KADM5_PRINC_EXPIRE_TIME | long | The expire time of the princial as a Kerberos timestamp. |
| KADM5_LAST_PW_CHANGE | long | The time this principal's password was last changed. |
| KADM5_PW_EXPIRATION | long | The expire time of the principal's current password, as a Kerberos timestamp. |
| KADM5_MAX_LIFE | long | The maximum lifetime of any Kerberos ticket issued to this principal. |
| KADM5_MAX_RLIFE | long | The maximum renewable lifetime of any Kerberos ticket issued to or for this principal. |
| KADM5_MOD_NAME | string | The name of the Kerberos principal that most recently modified this principal. |
| KADM5_MOD_TIME | long | The time this principal was last modified, as a Kerberos timestamp. |
| KADM5_KVNO | long | The version of the principal's current key. |
| KADM5_POLICY | string | The name of the policy controlling this principal. |
| KADM5_CLEARPOLICY | long | Standard procedure is to assign the 'default' policy to new principals. KADM5_CLEARPOLICY suppresses this behaviour. |
| KADM5_LAST_SUCCESS | long | The KDC time of the last successfull AS_REQ. |
| KADM5_LAST_FAILED | long | The KDC time of the last failed AS_REQ. |
| KADM5_FAIL_AUTH_COUNT | long | The number of consecutive failed AS_REQs. |
| KADM5_RANDKEY | long | Generates a random password for the principal. The parameter password will be ignored. |
| KADM5_ATTRIBUTES | long | A bitfield of attributes for use by the KDC. |
Exemplos
Índice
Basic usage
This simple example shows how to connect, query, print resulting principals and disconnect from a KADM5 database.
Exemplo #1 KADM5 extension overview example
<?php
$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");
print "<h1>get_principals</h1>\n";
$principals = kadm5_get_principals($handle);
for( $i=0; $i<count($principals); $i++)
print "$principals[$i]<br>\n";
print "<h1>get_policies</h1>\n";
$policies = kadm5_get_policies($handle);
for( $i=0; $i<count($policies); $i++)
print "$policies[$i]<br>\n";
print "<h1>get_principal burbach@GONICUS.LOCAL</h1>\n";
$options = kadm5_get_principal($handle, "burbach@GONICUS.LOCAL" );
$keys = array_keys($options);
for( $i=0; $i<count($keys); $i++) {
$value = $options[$keys[$i]];
print "$keys[$i]: $value<br>\n";
}
$options = array(KADM5_PRINC_EXPIRE_TIME => 0);
kadm5_modify_principal($handle, "burbach@GONICUS.LOCAL", $options);
kadm5_destroy($handle);
?>
KADM5 Funções
kadm5_chpass_principal
(PECL kadm5 >= 0.2.3)
kadm5_chpass_principal — Changes the principal's password
Descrição
kadm5_chpass_principal() sets the new password password for the principal.
Parâmetros
- handle
-
A KADM5 handle.
- principal
-
The principal.
- password
-
The new password.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 Example of changing principal's password
<?php
$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");
kadm5_chpass_principal($handle, "burbach@GONICUS.LOCAL", "newpassword");
kadm5_destroy($handle);
?>
kadm5_create_principal
(PECL kadm5 >= 0.2.3)
kadm5_create_principal — Creates a kerberos principal with the given parameters
Descrição
Creates a principal with the given password.
Parâmetros
- handle
-
A KADM5 handle.
- principal
-
The principal.
- password
-
If password is omitted or is NULL, a random key will be generated.
- options
-
It is possible to specify several optional parameters within the array options. Allowed are the following options: KADM5_PRINC_EXPIRE_TIME, KADM5_PW_EXPIRATION, KADM5_ATTRIBUTES, KADM5_MAX_LIFE, KADM5_KVNO, KADM5_POLICY, KADM5_CLEARPOLICY, KADM5_MAX_RLIFE.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 Example of principal's creation
<?php
$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");
$attributes = KRB5_KDB_REQUIRES_PRE_AUTH | KRB5_KDB_DISALLOW_PROXIABLE;
$options = array(KADM5_PRINC_EXPIRE_TIME => 0,
KADM5_POLICY => "default",
KADM5_ATTRIBUTES => $attributes);
kadm5_create_principal($handle, "burbach@GONICUS.LOCAL", "password", $options);
kadm5_destroy($handle);
?>
Veja Também
- kadm5_modify_principal() - Modifies a kerberos principal with the given parameters
- kadm5_delete_principal() - Deletes a kerberos principal
kadm5_delete_principal
(PECL kadm5 >= 0.2.3)
kadm5_delete_principal — Deletes a kerberos principal
Descrição
Removes the principal from the Kerberos database.
Parâmetros
- handle
-
A KADM5 handle.
- principal
-
The removed principal.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 kadm5_delete_principal() example
<?php
$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");
kadm5_delete_principal($handle, "burbach@GONICUS.LOCAL");
kadm5_destroy($handle);
?>
Veja Também
- kadm5_modify_principal() - Modifies a kerberos principal with the given parameters
- kadm5_create_principal() - Creates a kerberos principal with the given parameters
kadm5_destroy
(PECL kadm5 >= 0.2.3)
kadm5_destroy — Closes the connection to the admin server and releases all related resources
Descrição
Closes the connection to the admin server and releases all related resources.
Parâmetros
- handle
-
A KADM5 handle.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
kadm5_flush
(PECL kadm5 >= 0.2.3)
kadm5_flush — Flush all changes to the Kerberos database
Descrição
Flush all changes to the Kerberos database, leaving the connection to the Kerberos admin server open.
Parâmetros
- handle
-
A KADM5 handle.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
kadm5_get_policies
(PECL kadm5 >= 0.2.3)
kadm5_get_policies — Gets all policies from the Kerberos database
Descrição
Gets an array containing the policies's names.
Parâmetros
- handle
-
A KADM5 handle.
Valor Retornado
Returns array of policies on success or FALSE on failure.
Exemplos
Exemplo #1 kadm5_get_policies() example
<?php
$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");
print "<h1>get_policies</h1>\n";
foreach (kadm5_get_policies($handle) as $policy) {
echo "$policy<br />\n";
}
kadm5_destroy($handle);
?>
kadm5_get_principal
(PECL kadm5 >= 0.2.3)
kadm5_get_principal — Gets the principal's entries from the Kerberos database
Descrição
Gets the principal's entries from the Kerberos database.
Parâmetros
- handle
-
A KADM5 handle.
- principal
-
The principal.
Valor Retornado
Returns array of options containing the following keys: KADM5_PRINCIPAL, KADM5_PRINC_EXPIRE_TIME, KADM5_PW_EXPIRATION, KADM5_ATTRIBUTES, KADM5_MAX_LIFE, KADM5_MOD_NAME, KADM5_MOD_TIME, KADM5_KVNO, KADM5_POLICY, KADM5_MAX_RLIFE, KADM5_LAST_SUCCESS, KADM5_LAST_FAILED, KADM5_FAIL_AUTH_COUNT on success or FALSE on failure.
Exemplos
Exemplo #1 kadm5_get_principal() example
<?php
$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");
print "<h1>get_principal burbach@GONICUS.LOCAL</h1>\n";
$options = kadm5_get_principal($handle, "burbach@GONICUS.LOCAL" );
foreach ($options as $key => $value) {
echo "$key: $value<br />\n";
}
kadm5_destroy($handle);
?>
kadm5_get_principals
(PECL kadm5 >= 0.2.3)
kadm5_get_principals — Gets all principals from the Kerberos database
Descrição
kadm5_get_principals() returns an array containing the principals's names.
Parâmetros
- handle
-
A KADM5 handle.
Valor Retornado
Returns array of principals on success or FALSE on failure.
Exemplos
Exemplo #1 kadm5_get_principals() example
<?php
$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");
print "<h1>get_principals</h1>\n";
foreach (kadm5_get_principals($handle) as $principal) {
echo "$principal<br />\n";
}
kadm5_destroy($handle);
?>
kadm5_init_with_password
(PECL kadm5 >= 0.2.3)
kadm5_init_with_password — Opens a connection to the KADM5 library
Descrição
Opens a connection with the KADM5 library using the principal and the given password to obtain initial credentials from the admin_server.
Parâmetros
- admin_server
-
The server.
- realm
-
Defines the authentication domain for the connection.
- principal
-
The principal.
- password
-
If password is omitted or is NULL, a random key will be generated.
Valor Retornado
Returns a KADM5 handle on success or FALSE on failure.
Exemplos
Exemplo #1 KADM5 initialization example
<?php
$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");
$attributes = KRB5_KDB_REQUIRES_PRE_AUTH | KRB5_KDB_DISALLOW_PROXIABLE;
$options = array(KADM5_PRINC_EXPIRE_TIME => 0,
KADM5_POLICY => "default",
KADM5_ATTRIBUTES => $attributes);
kadm5_create_principal($handle, "burbach@GONICUS.LOCAL", "password", $options);
kadm5_destroy($handle);
?>
Notas
Nota:
Connection should be closed after use with kadm5_destroy().
Veja Também
- kadm5_destroy() - Closes the connection to the admin server and releases all related resources
kadm5_modify_principal
(PECL kadm5 >= 0.2.3)
kadm5_modify_principal — Modifies a kerberos principal with the given parameters
Descrição
Modifies a principal according to the given options.
Parâmetros
- handle
-
A KADM5 handle.
- principal
-
The principal.
- options
-
It is possible to specify several optional parameters within the array options. Allowed are the following options: KADM5_PRINC_EXPIRE_TIME, KADM5_PW_EXPIRATION, KADM5_ATTRIBUTES, KADM5_MAX_LIFE, KADM5_KVNO, KADM5_POLICY, KADM5_CLEARPOLICY, KADM5_MAX_RLIFE. KADM5_FAIL_AUTH_COUNT.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 Example of modifying principal
<?php
$handle = kadm5_init_with_password("afs-1", "GONICUS.LOCAL", "admin/admin", "password");
$attributes = KRB5_KDB_REQUIRES_PRE_AUTH;
$options = array(KADM5_PRINC_EXPIRE_TIME => 3451234,
KADM5_POLICY => "gonicus",
KADM5_ATTRIBUTES => $attributes);
kadm5_modify_principal($handle, "burbach@GONICUS.LOCAL", $options);
kadm5_destroy($handle);
?>
Veja Também
- kadm5_create_principal() - Creates a kerberos principal with the given parameters
- kadm5_delete_principal() - Deletes a kerberos principal
Índice
- kadm5_chpass_principal — Changes the principal's password
- kadm5_create_principal — Creates a kerberos principal with the given parameters
- kadm5_delete_principal — Deletes a kerberos principal
- kadm5_destroy — Closes the connection to the admin server and releases all related resources
- kadm5_flush — Flush all changes to the Kerberos database
- kadm5_get_policies — Gets all policies from the Kerberos database
- kadm5_get_principal — Gets the principal's entries from the Kerberos database
- kadm5_get_principals — Gets all principals from the Kerberos database
- kadm5_init_with_password — Opens a connection to the KADM5 library
- kadm5_modify_principal — Modifies a kerberos principal with the given parameters
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Exemplos
- KADM5 Funções
- kadm5_chpass_principal — Changes the principal's password
- kadm5_create_principal — Creates a kerberos principal with the given parameters
- kadm5_delete_principal — Deletes a kerberos principal
- kadm5_destroy — Closes the connection to the admin server and releases all related resources
- kadm5_flush — Flush all changes to the Kerberos database
- kadm5_get_policies — Gets all policies from the Kerberos database
- kadm5_get_principal — Gets the principal's entries from the Kerberos database
- kadm5_get_principals — Gets all principals from the Kerberos database
- kadm5_init_with_password — Opens a connection to the KADM5 library
- kadm5_modify_principal — Modifies a kerberos principal with the given parameters
Radius
Introdução
This package is based on the libradius (Remote Authentication Dial In User Service) of FreeBSD. It allows clients to perform authentication and accounting by means of network requests to remote servers.
This PECL extension adds full support for Radius Authentication (» RFC 2865) and Radius Accounting (» RFC 2866). This package is available for Unix (tested on FreeBSD and Linux) and for Windows.
Nota:
An exact description for libradius can be found » here. A detailed description of the configuration file can be found » here.
Instalação/Configuração
Índice
Dependências
Nenhuma biblioteca externa é necessária para compilar esta extensão.
Instalação
Esta extensão » PECL não vem compilada com o PHP.
Informações para a instalação desta extensão PECL podem ser encontradas no manual no capitulo intitulado Instalação de extensões PECL. Informações adicionais como novas versões, downloads, arquivos fontes, manutenções, e um Changelog, podem ser obtidos aqui: » http://pecl.php.net/package/radius.
Uma DLL para esta extenção PECL esta atualmente indisponível. Veja também a seção compilando no Windows section.
Configurações em Execução
Esta extensão não define nenhum parâmetro de configuração no php.ini.
Tipos Resource
Esta extensão não possui nenhum tipo resource.
Constantes pré-definidas
As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.
- RADIUS_ACCESS_REQUEST ()
- Authentication Request
- RADIUS_ACCESS_ACCEPT ()
- Access accepted
- RADIUS_ACCESS_REJECT ()
- Access rejected
- RADIUS_ACCOUNTING_REQUEST ()
- Accounting request
- RADIUS_ACCOUNTING_RESPONSE ()
- Accounting response
- RADIUS_ACCESS_CHALLENGE ()
- Accsess challenge
- RADIUS_USER_NAME (string)
- Username
- RADIUS_USER_PASSWORD (string)
- Password
- RADIUS_CHAP_PASSWORD (string)
- Chap Password: chappass = md5(ident + plaintextpass + challenge)
- RADIUS_NAS_IP_ADDRESS (string)
- NAS IP-Adress
- RADIUS_NAS_PORT (int)
- NAS Port
- RADIUS_SERVICE_TYPE (int)
-
Type of Service, one of:
- RADIUS_LOGIN
- RADIUS_FRAMED
- RADIUS_CALLBACK_LOGIN
- RADIUS_CALLBACK_FRAMED
- RADIUS_OUTBOUND
- RADIUS_ADMINISTRATIVE
- RADIUS_NAS_PROMPT
- RADIUS_AUTHENTICATE_ONLY
- RADIUS_CALLBACK_NAS_PROMPT
- RADIUS_FRAMED_PROTOCOL (int)
-
Framed Protocol, one of:
- RADIUS_PPP
- RADIUS_SLIP
- RADIUS_ARAP
- RADIUS_GANDALF
- RADIUS_XYLOGICS
- RADIUS_FRAMED_IP_ADDRESS (int)
- IPv4 Internet network address
- RADIUS_FRAMED_IP_NETMASK (string)
- Netmask
- RADIUS_FRAMED_ROUTING (int)
- Routing
- RADIUS_FILTER_ID (string)
- Filter ID
- RADIUS_FRAMED_MTU (int)
- MTU
- RADIUS_FRAMED_COMPRESSION (int)
-
Compression, one of:
- RADIUS_COMP_NONE
- RADIUS_COMP_VJ
- RADIUS_COMP_IPXHDR
- RADIUS_LOGIN_IP_HOST (string)
- Login IP Host
- RADIUS_LOGIN_SERVICE (int)
- Login Service
- RADIUS_LOGIN_TCP_PORT (int)
- Login TCP Port
- RADIUS_REPLY_MESSAGE (string)
- Reply Message
- RADIUS_CALLBACK_NUMBER (string)
- Callback Number
- RADIUS_CALLBACK_ID (string)
- Callback ID
- RADIUS_FRAMED_ROUTE (string)
- Framed Route
- RADIUS_FRAMED_IPX_NETWORK (string)
- Framed IPX Network
- RADIUS_STATE (string)
- State
- RADIUS_CLASS (int)
- Class
- RADIUS_VENDOR_SPECIFIC (int)
- Vendor specific attribute
- RADIUS_SESSION_TIMEOUT (int)
- Session timeout
- RADIUS_IDLE_TIMEOUT (int)
- Idle timeout
- RADIUS_TERMINATION_ACTION (int)
- Termination action
- RADIUS_CALLED_STATION_ID (int)
- Called Station Id
- RADIUS_CALLING_STATION_ID (string)
- Calling Station Id
- RADIUS_NAS_IDENTIFIER (int)
- NAS ID
- RADIUS_PROXY_STATE (int)
- Proxy State
- RADIUS_LOGIN_LAT_SERVICE (int)
- Login LAT Service
- RADIUS_LOGIN_LAT_NODE (int)
- Login LAT Node
- RADIUS_LOGIN_LAT_GROUP (int)
- Login LAT Group
- RADIUS_FRAMED_APPLETALK_LINK (int)
- Framed Appletalk Link
- RADIUS_FRAMED_APPLETALK_NETWORK (int)
- Framed Appletalk Network
- RADIUS_FRAMED_APPLETALK_ZONE (int)
- Framed Appletalk Zone
- RADIUS_CHAP_CHALLENGE (string)
- Challenge
- RADIUS_NAS_PORT_TYPE (int)
-
NAS port type, one of:
- RADIUS_ASYNC
- RADIUS_SYNC
- RADIUS_ISDN_SYNC
- RADIUS_ISDN_ASYNC_V120
- RADIUS_ISDN_ASYNC_V110
- RADIUS_VIRTUAL
- RADIUS_PIAFS
- RADIUS_HDLC_CLEAR_CHANNEL
- RADIUS_X_25
- RADIUS_X_75
- RADIUS_G_3_FAX
- RADIUS_SDSL
- RADIUS_ADSL_CAP
- RADIUS_ADSL_DMT
- RADIUS_IDSL
- RADIUS_ETHERNET
- RADIUS_XDSL
- RADIUS_CABLE
- RADIUS_WIRELESS_OTHER
- RADIUS_WIRELESS_IEEE_802_11
- RADIUS_PORT_LIMIT (int)
- Port Limit
- RADIUS_LOGIN_LAT_PORT (int)
- Login LAT Port
- RADIUS_CONNECT_INFO (string)
- Connect info
- RADIUS_ACCT_STATUS_TYPE (int)
-
Accounting status type, one of:
- RADIUS_START
- RADIUS_STOP
- RADIUS_ACCOUNTING_ON
- RADIUS_ACCOUNTING_OFF
- RADIUS_ACCT_DELAY_TIME (int)
- Accounting delay time
- RADIUS_ACCT_INPUT_OCTETS (int)
- Accounting input bytes
- RADIUS_ACCT_OUTPUT_OCTETS (int)
- Accounting output bytes
- RADIUS_ACCT_SESSION_ID (int)
- Accounting session ID
- RADIUS_ACCT_AUTHENTIC (int)
-
Accounting authentic, one of:
- RADIUS_AUTH_RADIUS
- RADIUS_AUTH_LOCAL
- RADIUS_AUTH_REMOTE
- RADIUS_ACCT_SESSION_TIME (int)
- Accounting session time
- RADIUS_ACCT_INPUT_PACKETS (int)
- Accounting input packets
- RADIUS_ACCT_OUTPUT_PACKETS (int)
- Accounting output packets
- RADIUS_ACCT_TERMINATE_CAUSE (int)
-
Accounting terminate cause, one of:
- RADIUS_TERM_USER_REQUEST
- RADIUS_TERM_LOST_CARRIER
- RADIUS_TERM_LOST_SERVICE
- RADIUS_TERM_IDLE_TIMEOUT
- RADIUS_TERM_SESSION_TIMEOUT
- RADIUS_TERM_ADMIN_RESET
- RADIUS_TERM_ADMIN_REBOOT
- RADIUS_TERM_PORT_ERROR
- RADIUS_TERM_NAS_ERROR
- RADIUS_TERM_NAS_REQUEST
- RADIUS_TERM_NAS_REBOOT
- RADIUS_TERM_PORT_UNNEEDED
- RADIUS_TERM_PORT_PREEMPTED
- RADIUS_TERM_PORT_SUSPENDED
- RADIUS_TERM_SERVICE_UNAVAILABLE
- RADIUS_TERM_CALLBACK
- RADIUS_TERM_USER_ERROR
- RADIUS_TERM_HOST_REQUEST
- RADIUS_ACCT_MULTI_SESSION_ID (string)
- Accounting multi session ID
- RADIUS_ACCT_LINK_COUNT (int)
- Accounting link count
- RADIUS_VENDOR_MICROSOFT (int)
-
Microsoft specific vendor attributes (» RFC 2548), one of:
- RADIUS_MICROSOFT_MS_CHAP_RESPONSE
- RADIUS_MICROSOFT_MS_CHAP_ERROR
- RADIUS_MICROSOFT_MS_CHAP_PW_1
- RADIUS_MICROSOFT_MS_CHAP_PW_2
- RADIUS_MICROSOFT_MS_CHAP_LM_ENC_PW
- RADIUS_MICROSOFT_MS_CHAP_NT_ENC_PW
- RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY
- RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES
- RADIUS_MICROSOFT_MS_RAS_VENDOR
- RADIUS_MICROSOFT_MS_CHAP_DOMAIN
- RADIUS_MICROSOFT_MS_CHAP_CHALLENGE
- RADIUS_MICROSOFT_MS_CHAP_MPPE_KEYS
- RADIUS_MICROSOFT_MS_BAP_USAGE
- RADIUS_MICROSOFT_MS_LINK_UTILIZATION_THRESHOLD
- RADIUS_MICROSOFT_MS_LINK_DROP_TIME_LIMIT
- RADIUS_MICROSOFT_MS_MPPE_SEND_KEY
- RADIUS_MICROSOFT_MS_MPPE_RECV_KEY
- RADIUS_MICROSOFT_MS_RAS_VERSION
- RADIUS_MICROSOFT_MS_OLD_ARAP_PASSWORD
- RADIUS_MICROSOFT_MS_NEW_ARAP_PASSWORD
- RADIUS_MICROSOFT_MS_ARAP_PASSWORD_CHANGE_REASON
- RADIUS_MICROSOFT_MS_FILTER
- RADIUS_MICROSOFT_MS_ACCT_AUTH_TYPE
- RADIUS_MICROSOFT_MS_ACCT_EAP_TYPE
- RADIUS_MICROSOFT_MS_CHAP2_RESPONSE
- RADIUS_MICROSOFT_MS_CHAP2_SUCCESS
- RADIUS_MICROSOFT_MS_CHAP2_PW
- RADIUS_MICROSOFT_MS_PRIMARY_DNS_SERVER
- RADIUS_MICROSOFT_MS_SECONDARY_DNS_SERVER
- RADIUS_MICROSOFT_MS_PRIMARY_NBNS_SERVER
- RADIUS_MICROSOFT_MS_SECONDARY_NBNS_SERVER
- RADIUS_MICROSOFT_MS_ARAP_CHALLENGE
Exemplos
Howto start?
- get a radius resource
- configure the library
- create the request
- put attributes
- send the request
- receive attributes
- close the radius resource (optional)
The package contains an example php script. This script demonstrates howto authenticate with radius using PAP or CHAP (md5). If you authenticate with Microsoft Radius servers then its not possible to use CHAP (md5). If you would like to authenticate with Microsoft Servers you have to use MS-CHAPv1 or MS-CHAPv2, but its more complicated, because you need md4, sha1 and des to generate the right data. The enclosed examples demonstrate all authentication-methods, including MS-CHAPv1 and MS-CHAPv2. To get the MS-CHAP to work you need the mcrypt and the mhash extension, starting with version 1.2 of the package, the mcrypt extension is no longer needed.
Radius Funções
Contact Information
If you have comments, bugfixes, enhancements or want to help to develop this you can send me a mail at » mbretter@php.net.
radius_acct_open
(PECL radius >= 1.1.0)
radius_acct_open — Creates a Radius handle for accounting
Descrição
Valor Retornado
Returns a handle on success, FALSE on error. This function only fails if insufficient memory is available.
Exemplos
Exemplo #1 radius_acct_open() example
<?php
$res = radius_acct_open ()
or die ("Could not create handle");
print("Handle successfully created");
?>
radius_add_server
(PECL radius >= 1.1.0)
radius_add_server — Adds a server
Descrição
radius_add_server() may be called multiple times, and it may be used together with radius_config(). At most 10 servers may be specified. When multiple servers are given, they are tried in round-robin fashion until a valid response is received, or until each server's max_tries limit has been reached.
Parâmetros
- radius_handle
-
- hostname
-
The hostname parameter specifies the server host, either as a fully qualified domain name or as a dotted-quad IP address in text form.
- port
-
The port specifies the UDP port to contact on the server. If port is given as 0, the library looks up the
radius/udporradacct/udpservice in the network services database, and uses the port found there. If no entry is found, the library uses the standard Radius ports, 1812 for authentication and 1813 for accounting. - secret
-
The shared secret for the server host is passed to the secret parameter. The Radius protocol ignores all but the leading 128 bytes of the shared secret.
- timeout
-
The timeout for receiving replies from the server is passed to the timeout parameter, in units of seconds.
- max_tries
-
The maximum number of repeated requests to make before giving up is passed into the max_tries.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 radius_add_server() example
<?php
if (!radius_add_server($res, 'radius.example.com', 1812, 'testing123', 3, 3)) {
echo 'RadiusError:' . radius_strerror($res). "\n<br>";
exit;
}
?>
radius_auth_open
(PECL radius >= 1.1.0)
radius_auth_open — Creates a Radius handle for authentication
Descrição
Valor Retornado
Returns a handle on success, FALSE on error. This function only fails if insufficient memory is available.
Exemplos
Exemplo #1 radius_auth_open() example
<?php
$radh = radius_auth_open()
or die ("Could not create handle");
echo "Handle successfully created";
?>
radius_close
(PECL radius >= 1.1.0)
radius_close — Frees all ressources
Descrição
It is not needed to call this function because php frees all resources at the end of each request.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
radius_config
(PECL radius >= 1.1.0)
radius_config — Causes the library to read the given configuration file
Descrição
Before issuing any Radius requests, the library must be made aware of the servers it can contact. The easiest way to configure the library is to call radius_config(). radius_config() causes the library to read a configuration file whose format is described in » radius.conf.
Parâmetros
- radius_handle
-
- file
-
The pathname of the configuration file is passed as the file argument to radius_config(). The library can also be configured programmatically by calls to radius_add_server().
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
radius_create_request
(PECL radius >= 1.1.0)
radius_create_request — Create accounting or authentication request
Descrição
A Radius request consists of a code specifying the kind of request, and zero or more attributes which provide additional information. To begin constructing a new request, call radius_create_request().
Nota: Attention: You must call this function, before you can put any attribute!
Parâmetros
- radius_handle
-
- type
-
Type is RADIUS_ACCESS_REQUEST or RADIUS_ACCOUNTING_REQUEST.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 radius_create_request() example
<?php
if (!radius_create_request($res, RADIUS_ACCESS_REQUEST)) {
echo 'RadiusError:' . radius_strerror($res). "\n<br />";
exit;
}
?>
radius_cvt_addr
(PECL radius >= 1.1.0)
radius_cvt_addr — Converts raw data to IP-Address
Descrição
Exemplos
Exemplo #1 radius_cvt_addr() example
<?php
while ($resa = radius_get_attr($res)) {
if (!is_array($resa)) {
printf ("Error getting attribute: %s\n", radius_strerror($res));
exit;
}
$attr = $resa['attr'];
$data = $resa['data'];
switch ($attr) {
case RADIUS_FRAMED_IP_ADDRESS:
$ip = radius_cvt_addr($data);
echo "IP: $ip<br>\n";
break;
case RADIUS_FRAMED_IP_NETMASK:
$mask = radius_cvt_addr($data);
echo "MASK: $mask<br>\n";
break;
}
}
?>
Veja Também
- radius_cvt_int() - Converts raw data to integer
- radius_cvt_string() - Converts raw data to string
radius_cvt_int
(PECL radius >= 1.1.0)
radius_cvt_int — Converts raw data to integer
Descrição
Exemplos
Exemplo #1 radius_cvt_int() example
<?php
while ($resa = radius_get_attr($res)) {
if (!is_array($resa)) {
printf ("Error getting attribute: %s\n", radius_strerror($res));
exit;
}
$attr = $resa['attr'];
$data = $resa['data'];
switch ($attr) {
case RADIUS_FRAMED_MTU:
$mtu = radius_cvt_int($data);
echo "MTU: $mtu<br>\n";
break;
}
}
?>
Veja Também
- radius_cvt_addr() - Converts raw data to IP-Address
- radius_cvt_string() - Converts raw data to string
radius_cvt_string
(PECL radius >= 1.1.0)
radius_cvt_string — Converts raw data to string
Descrição
Exemplos
Exemplo #1 radius_cvt_string() example
<?php
while ($resa = radius_get_attr($res)) {
if (!is_array($resa)) {
printf ("Error getting attribute: %s\n", radius_strerror($res));
exit;
}
$attr = $resa['attr'];
$data = $resa['data'];
switch ($attr) {
case RADIUS_FILTER_ID:
$id = radius_cvt_string($data);
echo "Filter ID: $id<br>\n";
break;
}
}
?>
Veja Também
- radius_cvt_addr() - Converts raw data to IP-Address
- radius_cvt_int() - Converts raw data to integer
radius_demangle_mppe_key
(PECL radius >= 1.2.0)
radius_demangle_mppe_key — Derives mppe-keys from mangled data
Descrição
When using MPPE with MS-CHAPv2, the send- and recv-keys are mangled (see » RFC 2548), however this function is useless, because I don't think that there is or will be a PPTP-MPPE implementation in PHP.
Valor Retornado
Returns the demangled string, or FALSE on error.
radius_demangle
(PECL radius >= 1.2.0)
radius_demangle — Demangles data
Descrição
Some data (Passwords, MS-CHAPv1 MPPE-Keys) is mangled for security reasons, and must be demangled before you can use them.
Valor Retornado
Returns the demangled string, or FALSE on error.
radius_get_attr
(PECL radius >= 1.1.0)
radius_get_attr — Extracts an attribute
Descrição
Like Radius requests, each response may contain zero or more attributes. After a response has been received successfully by radius_send_request(), its attributes can be extracted one by one using radius_get_attr(). Each time radius_get_attr() is called, it gets the next attribute from the current response.
Valor Retornado
Returns an associative array containing the attribute-type and the data, or error number <= 0.
Exemplos
Exemplo #1 radius_get_attr() example
<?php
while ($resa = radius_get_attr($res)) {
if (!is_array($resa)) {
printf("Error getting attribute: %s\n", radius_strerror($res));
exit;
}
$attr = $resa['attr'];
$data = $resa['data'];
printf("Got Attr:%d %d Bytes %s\n", $attr, strlen($data), bin2hex($data));
}
?>
Veja Também
- radius_put_attr() - Attaches a binary attribute
- radius_get_vendor_attr() - Extracts a vendor specific attribute
- radius_put_vendor_attr() - Attaches a vendor specific binary attribute
- radius_send_request() - Sends the request and waites for a reply
radius_get_vendor_attr
(PECL radius >= 1.1.0)
radius_get_vendor_attr — Extracts a vendor specific attribute
Descrição
If radius_get_attr() returns RADIUS_VENDOR_SPECIFIC, radius_get_vendor_attr() may be called to determine the vendor.
Valor Retornado
Returns an associative array containing the attribute-type, vendor and the data, or FALSE on error.
Exemplos
Exemplo #1 radius_get_vendor_attr() example
<?php
while ($resa = radius_get_attr($res)) {
if (!is_array($resa)) {
printf ("Error getting attribute: %s\n", radius_strerror($res));
exit;
}
$attr = $resa['attr'];
$data = $resa['data'];
printf("Got Attr:%d %d Bytes %s\n", $attr, strlen($data), bin2hex($data));
if ($attr == RADIUS_VENDOR_SPECIFIC) {
$resv = radius_get_vendor_attr($data);
if (is_array($resv)) {
$vendor = $resv['vendor'];
$attrv = $resv['attr'];
$datav = $resv['data'];
printf("Got Vendor Attr:%d %d Bytes %s\n", $attrv, strlen($datav), bin2hex($datav));
}
}
}
?>
Veja Também
- radius_get_attr() - Extracts an attribute
- radius_put_vendor_attr() - Attaches a vendor specific binary attribute
radius_put_addr
(PECL radius >= 1.1.0)
radius_put_addr — Attaches an IP-Address attribute
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
radius_put_attr
(PECL radius >= 1.1.0)
radius_put_attr — Attaches a binary attribute
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 radius_put_attr() example
<?php
mt_srand(time());
$chall = mt_rand();
$chapval = md5(pack('Ca*',1 , 'sepp' . $chall));
$pass = pack('CH*', 1, $chapval);
if (!radius_put_attr($res, RADIUS_CHAP_PASSWORD, $pass)) {
echo 'RadiusError:' . radius_strerror($res). "\n<br />";
exit;
}
?>
Veja Também
- radius_get_attr() - Extracts an attribute
- radius_get_vendor_attr() - Extracts a vendor specific attribute
- radius_put_vendor_attr() - Attaches a vendor specific binary attribute
radius_put_int
(PECL radius >= 1.1.0)
radius_put_int — Attaches an integer attribute
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 radius_put_int() example
<?php
if (!radius_put_int($res, RAD_FRAMED_PROTOCOL, RAD_PPP)) {
echo 'RadiusError:' . radius_strerror($res). "\n<br />";
exit;
}
?>
Veja Também
- radius_put_string() - Attaches a string attribute
- radius_put_vendor_int() - Attaches a vendor specific integer attribute
- radius_put_vendor_string() - Attaches a vendor specific string attribute
radius_put_string
(PECL radius >= 1.1.0)
radius_put_string — Attaches a string attribute
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 radius_put_string() example
<?php
if (!radius_put_string($res, RADIUS_USER_NAME, 'billy')) {
echo 'RadiusError:' . radius_strerror($res). "\n<br />";
exit;
}
?>
Veja Também
- radius_put_int() - Attaches an integer attribute
- radius_put_vendor_int() - Attaches a vendor specific integer attribute
- radius_put_vendor_string() - Attaches a vendor specific string attribute
radius_put_vendor_addr
(PECL radius >= 1.1.0)
radius_put_vendor_addr — Attaches a vendor specific IP-Address attribute
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
radius_put_vendor_attr
(PECL radius >= 1.1.0)
radius_put_vendor_attr — Attaches a vendor specific binary attribute
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 radius_put_vendor_attr() example
<?php
if (!radius_put_vendor_attr($res, RADIUS_VENDOR_MICROSOFT, RAD_MICROSOFT_MS_CHAP_CHALLENGE, $challenge)) {
echo 'RadiusError:' . radius_strerror($res). "\n<br />";
exit;
}
?>
radius_put_vendor_int
(PECL radius >= 1.1.0)
radius_put_vendor_int — Attaches a vendor specific integer attribute
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
radius_put_vendor_string
(PECL radius >= 1.1.0)
radius_put_vendor_string — Attaches a vendor specific string attribute
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
radius_request_authenticator
(PECL radius >= 1.1.0)
radius_request_authenticator — Returns the request authenticator
Descrição
The request authenticator is needed for demangling mangled data like passwords and encryption-keys.
Valor Retornado
Returns the request authenticator as string, or FALSE on error.
radius_send_request
(PECL radius >= 1.1.0)
radius_send_request — Sends the request and waites for a reply
Descrição
After the Radius request has been constructed, it is sent by radius_send_request().
The radius_send_request() function sends the request and waits for a valid reply, retrying the defined servers in round-robin fashion as necessary.
Valor Retornado
If a valid response is received, radius_send_request() returns the Radius code which specifies the type of the response. This will typically be RADIUS_ACCESS_ACCEPT, RADIUS_ACCESS_REJECT, or RADIUS_ACCESS_CHALLENGE. If no valid response is received, radius_send_request() returns FALSE.
radius_server_secret
(PECL radius >= 1.1.0)
radius_server_secret — Returns the shared secret
Descrição
The shared secret is needed as salt for demangling mangled data like passwords and encryption-keys.
Valor Retornado
Returns the server's shared secret as string, or FALSE on error.
radius_strerror
(PECL radius >= 1.1.0)
radius_strerror — Returns an error message
Descrição
If Radius-functions fail then they record an error message. This error message can be retrieved with this function.
Valor Retornado
Returns error messages as string from failed radius functions.
Índice
- radius_acct_open — Creates a Radius handle for accounting
- radius_add_server — Adds a server
- radius_auth_open — Creates a Radius handle for authentication
- radius_close — Frees all ressources
- radius_config — Causes the library to read the given configuration file
- radius_create_request — Create accounting or authentication request
- radius_cvt_addr — Converts raw data to IP-Address
- radius_cvt_int — Converts raw data to integer
- radius_cvt_string — Converts raw data to string
- radius_demangle_mppe_key — Derives mppe-keys from mangled data
- radius_demangle — Demangles data
- radius_get_attr — Extracts an attribute
- radius_get_vendor_attr — Extracts a vendor specific attribute
- radius_put_addr — Attaches an IP-Address attribute
- radius_put_attr — Attaches a binary attribute
- radius_put_int — Attaches an integer attribute
- radius_put_string — Attaches a string attribute
- radius_put_vendor_addr — Attaches a vendor specific IP-Address attribute
- radius_put_vendor_attr — Attaches a vendor specific binary attribute
- radius_put_vendor_int — Attaches a vendor specific integer attribute
- radius_put_vendor_string — Attaches a vendor specific string attribute
- radius_request_authenticator — Returns the request authenticator
- radius_send_request — Sends the request and waites for a reply
- radius_server_secret — Returns the shared secret
- radius_strerror — Returns an error message
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Exemplos
- Radius Funções
- radius_acct_open — Creates a Radius handle for accounting
- radius_add_server — Adds a server
- radius_auth_open — Creates a Radius handle for authentication
- radius_close — Frees all ressources
- radius_config — Causes the library to read the given configuration file
- radius_create_request — Create accounting or authentication request
- radius_cvt_addr — Converts raw data to IP-Address
- radius_cvt_int — Converts raw data to integer
- radius_cvt_string — Converts raw data to string
- radius_demangle_mppe_key — Derives mppe-keys from mangled data
- radius_demangle — Demangles data
- radius_get_attr — Extracts an attribute
- radius_get_vendor_attr — Extracts a vendor specific attribute
- radius_put_addr — Attaches an IP-Address attribute
- radius_put_attr — Attaches a binary attribute
- radius_put_int — Attaches an integer attribute
- radius_put_string — Attaches a string attribute
- radius_put_vendor_addr — Attaches a vendor specific IP-Address attribute
- radius_put_vendor_attr — Attaches a vendor specific binary attribute
- radius_put_vendor_int — Attaches a vendor specific integer attribute
- radius_put_vendor_string — Attaches a vendor specific string attribute
- radius_request_authenticator — Returns the request authenticator
- radius_send_request — Sends the request and waites for a reply
- radius_server_secret — Returns the shared secret
- radius_strerror — Returns an error message
Extensões Relacionadas a Data e Hora
Calendário
Introdução
A extensão de calendário contém uma série de funções para simplificar a conversão de diferentes formatos de calendários. O calendário padrão é baseado no formato "Julian Day Count". A contagem de dias do calendário "Julian Day Count" começa em 1º de Janeiro de 4713 B.C. Para converter um calendário para algum formato, você deve primeiro convertê-lo para o formato "Julian Day Count", então converter para o sistema de calendário de sua escolha. O formato de calendário "Julian Day Count" é muito diferente do "Julian Calendar"! Para mais informações sobre o calendário "Julian Day Count", visite » http://www.hermetic.ch/cal_stud/jdn.htm. Para mais informações sobre sistemas de calendários, visite: » http://www.fourmilab.ch/documents/calendar/. "Excerpts from this page are included in these instructions, and are in quotes".
Instalação/Configuração
Índice
Dependências
Nenhuma biblioteca externa é necessária para compilar esta extensão.
Instalação
Para estas funções funcionarem, você precisa compilar o PHP com --enable-calendar .
A versão para Windows do PHP tem suporte embutido para esta extensão. Você não precisa carregar nenhuma extensão adicional para utilizar essas funções.
Configurações em Execução
Esta extensão não define nenhum parâmetro de configuração no php.ini.
Tipos Resource
Esta extensão não possui nenhum tipo resource.
Constantes pré-definidas
As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.
- CAL_GREGORIAN (integer)
- CAL_JULIAN (integer)
- CAL_JEWISH (integer)
- CAL_FRENCH (integer)
- CAL_NUM_CALS (integer)
- CAL_DOW_DAYNO (integer)
- CAL_DOW_SHORT (integer)
- CAL_DOW_LONG (integer)
- CAL_MONTH_GREGORIAN_SHORT (integer)
- CAL_MONTH_GREGORIAN_LONG (integer)
- CAL_MONTH_JULIAN_SHORT (integer)
- CAL_MONTH_JULIAN_LONG (integer)
- CAL_MONTH_JEWISH (integer)
- CAL_MONTH_FRENCH (integer)
As constantes abaixo estão disponíveis à partir do PHP 4.3.0:
- CAL_EASTER_DEFAULT (integer)
- CAL_EASTER_ROMAN (integer)
- CAL_EASTER_ALWAYS_GREGORIAN (integer)
- CAL_EASTER_ALWAYS_JULIAN (integer)
As constantes abaixo estão disponíveis à partir do PHP 5.0.0:
Calendário Funções
cal_days_in_month
(PHP 4 >= 4.1.0, PHP 5)
cal_days_in_month — Retorna o número de dias em um mês de um calendário e ano requisitado
Descrição
Esta função irá retornar o número de dias em um month do year para o calendar especificado.
Parâmetros
- calendar
-
Calendário para usar no cálculo
- month
-
Mês a ser selecionado no calendário
- year
-
Ano no selecionado calendário
Valor Retornado
A quantidade de dias do selecionado mês no dado calendário
Exemplos
Exemplo #1 Exemplo da cal_days_in_month()
<?php
$num = cal_days_in_month(CAL_GREGORIAN, 8, 2003); // 31
echo "Houve $num dias em Agosto de 2003";
?>
cal_from_jd
(PHP 4 >= 4.1.0, PHP 5)
cal_from_jd — Converte à partir do "Julian Day Count" para um outro calendário suportado
Descrição
cal_from_jd() converte do "Julian Day Count" ( jd) para uma data de um calendário especificado. Os valores dos calendários suportados são CAL_GREGORIAN, CAL_JULIAN, CAL_JEWISH e CAL_FRENCH.
Exemplo #1 cal_from_jd() exemplo
<?php
$hoje = unixtojd(mktime(0, 0, 0, 8, 16, 2003));
print_r(cal_from_jd($hoje, CAL_GREGORIAN));
?>
Este código retorna:
Array
(
[date] => 8/16/2003
[month] => 8
[day] => 16
[year] => 2003
[dow] => 6
[abbrevdayname] => Sat
[dayname] => Saturday
[abbrevmonth] => Aug
[monthname] => August
)
Veja também cal_to_jd().
cal_info
(PHP 4 >= 4.1.0, PHP 5)
cal_info — Retorna informações sobre um calendário em particular
Descrição
cal_info() retorna as informações de um calendar. Os nomes de diferentes calendários que podem ser usados como calendar são os seguintes:
- 0 ou CAL_GREGORIAN - Gregorian Calendar
- 1 ou CAL_JULIAN - Julian Calendar
- 2 ou CAL_JEWISH - Jewish Calendar
- 3 ou CAL_FRENCH - French Revolutionary Calendar
A informação do calendário especificado é retornada em um array contendo os elementos calname, calsymbol, month, abbrevmonth e maxdaysinmonth.
Se nenhum calendário foi especificado as informações de todos os calendários suportados são retornadas em um array.
Parâmetros
- calendar
-
Calendário a ser retornado informação. Se nenhuma informação de calendário é especificada, todos calendários são retornados.
Valor Retornado
Histórico
| Versão | Descrição |
|---|---|
| Desde o 5.0 | O parâmetro calendar é opcional e o padrão é "todos calendários" se omitido. |
Exemplos
Exemplo #1 Exemplo de cal_info()
<?php
$info = cal_info(0);
print_r($info);
?>
O exemplo acima irá imprimir:
Array
(
[months] => Array
(
[1] => January
[2] => February
[3] => March
[4] => April
[5] => May
[6] => June
[7] => July
[8] => August
[9] => September
[10] => October
[11] => November
[12] => December
)
[abbrevmonths] => Array
(
[1] => Jan
[2] => Feb
[3] => Mar
[4] => Apr
[5] => May
[6] => Jun
[7] => Jul
[8] => Aug
[9] => Sep
[10] => Oct
[11] => Nov
[12] => Dec
)
[maxdaysinmonth] => 31
[calname] => Gregorian
[calsymbol] => CAL_GREGORIAN
)
cal_to_jd
(PHP 4 >= 4.1.0, PHP 5)
cal_to_jd — Converte um calendário (suportado) para o calendário "Julian Day Count"
Descrição
cal_to_jd() calcula uma data em formato "Julian Day Count" à partir de um calendar suportado especificado. Os calendar suportados são: CAL_GREGORIAN, CAL_JULIAN, CAL_JEWISH e CAL_FRENCH.
Parâmetros
- calendar
-
Calendário para converter, um dos CAL_GREGORIAN, CAL_JULIAN, CAL_JEWISH ou CAL_FRENCH.
- month
-
O mês como um número, o intervalo válido depende do calendar
- day
-
O dia como um número, o intervalo válido depende do calendar
- year
-
O ano como um número, o intervalo válido depende do calendar
Valor Retornado
Um número de data juliana.
Veja Também
- cal_from_jd() - Converte à partir do "Julian Day Count" para um outro calendário suportado
- frenchtojd() - Converte uma data do calendário Republicano da França para o calendário "Julian Day Count".
- gregoriantojd() - Converte uma data gregoriana para o "Julian Day Count"
- jewishtojd() - Converte uma data do calendário Judaico para o calendário "Julian Day Count"
- juliantojd() - Converte datas no formato "Julian" para o formato "Julian Day Count"
- unixtojd() - Converte datas do sistema Unix para data Juliana
easter_date
(PHP 4, PHP 5)
easter_date — Retorna a data do sistema UNIX correspondente à meia-noite da Páscoa do ano especificado. Se nenhum ano tiver sido especificado, será assumido o ano atual.
Descrição
Retorna a data do sistema UNIX correspondente à meia-noite da Páscoa do ano especificado. Se nenhum ano tiver sido especificado, será assumido o ano atual.
À partir da versão 4.3.0 PHP, e se omitido o parâmetro ano, o padrão assumido é o ano atual de acordo com a hora local.
Aviso Esta função irá gerar um aviso se o ano está fora do padrão de datas do sistema UNIX (i.e. antes de 1970 ou após 2037).
Exemplo #1 easter_date() exemplo
<?php
echo date ("M-d-Y", easter_date(1999)); // Apr-04-1999
echo date ("M-d-Y", easter_date(2000)); // Apr-23-2000
echo date ("M-d-Y", easter_date(2001)); // Apr-15-2001
?>
A data da Páscoa foi definida pelo Conselho de Nicaea em DC325 como sendo o primeiro domingo após a primeira lua cheia que cai no equinócio da primavera ou depois dele. O equinócio geralmente cai perto do 21º de Março, logo, o cálculo resume-se à determinar a data da lua cheia e a data do seguinte domingo. O algoritmo usado aqui foi feito no ano 532 por Dionysius Exiguus. De acordo com o calendário "Julian" (para anos anterioris à 1753) um simples ciclo de 19-anos é usado para seguir as fases da lua. De acordo com o Calendário Gregoriano (para antes após 1753 - planejado por Clavius e por Lilius, e feito por Pope Gregory XIII em Outubro de 1582, e na Grã Bretanha e suas colônias em Setembro de 1752), duas correções fatoriais foram adicionadas para fazer o ciclo mais exato.
(O código é baseado em um programa feito em C por Simon Kershaw, <webmaster@ely.anglican.org>)
Veja easter_days() para calcular a Páscoa antes de 1970 ou após 2037.
easter_days
(PHP 4, PHP 5)
easter_days — Obtém o número de dias entre 21 de Março e o dia da Páscoa em determinado ano.
Description
Retorna o número de dias entre 21 de Março e o dia da Páscoa em determinado ano. Se nenhum ano tiver sido especificado, será assumido o ano atual.
À partir da versão 4.3.0 do PHP, o parâmetro ano é opcional e se for omitido o padrão assumido é o ano atual de acrodo com o hora local.
O parâmetro método está disponível à partir da versão 4.3.0 do PHP e perimite calcular as datas da Páscoa baseadas no calendário Gregoriano durante os anos 1582 - 1752 quando a constante CAL_EASTER_ROMAN está ligada. Veja as constantes de calendário para obter outras constantes válidas.
Ao invés de usar a função easter_date(), você pode usar esta função para calcular a Páscoa em anos que estão fora da escala de datas do sistema UNIX (i.e. antes de 1970 ou após 2037).
Exemplo #1 easter_days() exemplo
<?php
echo easter_days (1999); // 14, i.e. April 4
echo easter_days (1492); // 32, i.e. April 22
echo easter_days (1913); // 2, i.e. March 23
?>
A data da Páscoa foi definida pelo Conselho de Nicaea em DC325 como sendo o primeiro domingo após a primeira lua cheia que cai no equinócio da primavera ou depois dele. O equinócio geralmente cai perto do 21º de Março, logo, o cálculo resume-se à determinar a data da lua cheia e a data do seguinte domingo. O algoritmo usado aqui foi feito no ano 532 por Dionysius Exiguus. De acordo com o calendário "Julian" (para anos anterioris à 1753) um simples ciclo de 19-anos é usado para seguir as fases da lua. De acordo com o Calendário Gregoriano (para antes após 1753 - planejado por Clavius e por Lilius, e feito por Pope Gregory XIII em Outubro de 1582, e na Grã Bretanha e suas colônias em Setembro de 1752), duas correções fatoriais foram adicionadas para fazer o ciclo mais exato.
(O código é baseado em um programa feito em C por Simon Kershaw, <webmaster@ely.anglican.org>)
Veja também easter_date().
FrenchToJD
(PHP 4, PHP 5)
FrenchToJD — Converte uma data do calendário Republicano da França para o calendário "Julian Day Count".
Descrição
Converte uma data do calendário Republicano da França para o calendário "Julian Day Count".
Estas rotinas somente converte datas entre os anos de 1 até 14 (datas Gregorianas de 22 de Setembro de 1792 até 22 de Setembro de 1806). "This more than covers the period when the calendar was in use."
GregorianToJD
(PHP 4, PHP 5)
GregorianToJD — Converte uma data gregoriana para o "Julian Day Count"
Descrição
Escala válida para o Calendário Gregoriano: 4714 A.C. to 9999 D.C.
Entretanto esta função pode trabalhar com todas datas anteriores à, porém usá-la desta maneira não tem muito sentido. O Calendário Gregoriano não foi instituído até 15 de Outubro de 1582 (ou 5 de Outubro de 1582, no calendário JDC ("Julian Day Count")). Alguns países aceitaram este calendário um pouco mais tarde. Por exemplo, a Grã Bretanha converteu-se em 1752, a URSS em 1918 e a Grécia em 1923. A maioria dos países Europeus usaram o calendário "Julian" (JDC) antes do calendário Gregoriano.
Parâmetros
- month
-
O mês como um número entre 1 (para janeiro) e 12 (para dezembro)
- day
-
O dia como um número entre 1 e 31
- year
-
O ano como um número entre -4714 e 9999
Valor Retornado
A data juliana para a dada data gregoriana como um inteiro.
Exemplos
Exemplo #1 Funções de Calendário
<?php
$jd = GregorianToJD (10,11,1970);
echo "$jd\n";
$gregorian = JDToGregorian ($jd);
echo "$gregorian\n";
?>
Veja Também
- jdtogregorian() - Converte uma data no formato "Julian Day Count" para o formato Gregoriano
- cal_to_jd() - Converte um calendário (suportado) para o calendário "Julian Day Count"
JDDayOfWeek
(PHP 4, PHP 5)
JDDayOfWeek — Retorna o dia da semana
Descrição
Retorna o dia da semana. Pode retornar uma "string" ou um inteiro dependendo do modo utilizado.
Parâmetros
- julianday
-
Um número de data juliana como inteiro
- mode
-
Calendários da semana (modos) Modo Significado 0 (Padrão) Retorna o dia da semana como sendo um número inteiro (0=domingo, 1=segunda, etc.) 1 Retorna uma string contendo o dia da semana (Inglês-gregoriano) 2 Retorna uma "string" contendo a abreviação do dia da semana (Inglês-gregoriano)
Valor Retornado
Um dia da semana gregoriano com um inteiro ou string.
JDMonthName
(PHP 4, PHP 5)
JDMonthName — Retorna o nome de um mês
Descrição
Retorna uma "string" contendo o nome do mês. O parâmetro mode diz à função qual calendário será convertido para o formato "Julian Day Count", e o tipo do nome do mês.
| Modo | Significado | Valores |
|---|---|---|
| 0 | Gregoriano - abreviado | Jan, Fev, Mar, Abr, Mai, Jun, Jul, Ago, Set, Out, Nov, Dez |
| 1 | Gregoriano | Janeiro, Fevereiro, Março, Abril, Maio, Junho, Julho, Agosto, Setembro, Outubro, Novembro, Dezembro |
| 2 | "Julian" - abreviado | Jan, Fev, Mar, Abr, Mai, Jun, Jul, Ago, Set, Out, Nov, Dez |
| 3 | "Julian" | Janeiro, Fevereiro, Março, Abril, Maio, Junho, Julho, Agosto, Setembro, Outubro, Novembro, Dezembro |
| 4 | Judeu | Tishri, Heshvan, Kislev, Tevet, Shevat, AdarI, AdarII, Nisan, Iyyar, Sivan, Tammuz, Av, Elul |
| 5 | Republicano Francês | Vendemiaire, Brumaire, Frimaire, Nivose, Pluviose, Ventose, Germinal, Floreal, Prairial, Messidor, Thermidor, Fructidor, Extra |
Parâmetros
- jday
-
A data juliana
- calendar
-
O calendário para obter o nome do mês
Valor Retornado
O nome do mês para a dada data juliana e calendar.
JDToFrench
(PHP 4, PHP 5)
JDToFrench — Converte do calendário "Julian Day Count" para o calendário Republicano Francês
Descrição
Converte do calendário "Julian Day Count" para o calendário Republicano Francês
Parâmetros
- julianday
-
Um número de data Juliana como inteiro
Valor Retornado
A data republicana francesa como uma string no formato "mês/dia/ano"
Veja Também
- frenchtojd() - Converte uma data do calendário Republicano da França para o calendário "Julian Day Count".
- cal_from_jd() - Converte à partir do "Julian Day Count" para um outro calendário suportado
JDToGregorian
(PHP 4, PHP 5)
JDToGregorian — Converte uma data no formato "Julian Day Count" para o formato Gregoriano
Descrição
Converte "Julian Day Count" para uma "string" contendo a data em formato Gregoriano "mês/dia/ano".
Parâmetros
- julianday
-
O número de uma data Juliana como inteiro
Valor Retornado
A data gregoriana no formato "mês/dia/ano"
Veja Também
- gregoriantojd() - Converte uma data gregoriana para o "Julian Day Count"
- cal_from_jd() - Converte à partir do "Julian Day Count" para um outro calendário suportado
jdtojewish
(PHP 4, PHP 5)
jdtojewish — Convete uma data do calendário "Julian Day Count" para o calendário Judaico
Descrição
Convete uma data do calendário "Julian Day Count" para o calendário Judaico
Os parâmetros hebrew e fl são opcionais e estarão disponíveis na versão do PHP 5.0.0
Se o parâmetro hebrew for TRUE, o parâmetro fl a "string" de saída de dados é baseada no formato "hebrew". Os formatos disponíveis são: CAL_JEWISH_ADD_ALAFIM_GERESH, CAL_JEWISH_ADD_ALAFIM, CAL_JEWISH_ADD_GERESHAYIM.
Exemplo #1 jdtojewish() Exemplo
<?php
echo jdtojewish(gregoriantojd(10,8,2002), true,
CAL_JEWISH_ADD_GERESHAYIM + CAL_JEWISH_ADD_ALAFIM + CAL_JEWISH_ADD_ALAFIM_GERESH);
?>
JDToJulian
(PHP 4, PHP 5)
JDToJulian — Converte uma data do calendário "Julian Day Count" para o calendário "Julian"
Descrição
Converte "Julian Day Count" para uma "string" contendo a data do calendário "Julian" no formato "mês/dia/ano".
Parâmetros
- julianday
-
O número de uma data Juliana como inteiro
Valor Retornado
A data Juliana como uma string no formato "mês/dia/ano"
Veja Também
- juliantojd() - Converte datas no formato "Julian" para o formato "Julian Day Count"
- cal_from_jd() - Converte à partir do "Julian Day Count" para um outro calendário suportado
jdtounix
(PHP 4, PHP 5)
jdtounix — Converte do formato de dada Juliana para Unix timestamp
Descrição
Esta função irá retorna a data do sistema Unix correspondente ao "Julian Day" especificado no parâmetro jday ou FALSE se jday não está dentre a escala de datas Unix (Anos Gregorianos entre 1970 e 2037 ou 2440588 <= jday <= 2465342). A hora retornada é a hora local (e não a GMT).
Parâmetros
- jday
-
O número de um data juliana entre 2440588 e 2465342.
Valor Retornado
O unix timestamp para o ínicio da dada data juliana.
JewishToJD
(PHP 4, PHP 5)
JewishToJD — Converte uma data do calendário Judaico para o calendário "Julian Day Count"
Descrição
Entretanto esta função suporta datas anteriores ao ano 1 (3761 A.C.), porém tal uso não faz sentido. O calendário Judaico vem sendo usado por centenas de anos, porém os primeiros dias não tem uma fórmula que determina qual é o começo do mês. Um novo mês começa quando uma lua nova é vista.
Parâmetros
- month
-
O mês como um número entre 1 e 13
- day
-
O dia como um número entre 1 e 30
- year
-
O ano como um número entre 1 e 9999
Valor Retornado
A data juliana para a dada data judaica como um inteiro.
Veja Também
- jdtojewish() - Convete uma data do calendário "Julian Day Count" para o calendário Judaico
- cal_to_jd() - Converte um calendário (suportado) para o calendário "Julian Day Count"
JulianToJD
(PHP 4, PHP 5)
JulianToJD — Converte datas no formato "Julian" para o formato "Julian Day Count"
Descrição
O Calendário "Julian" vai de 4713 A.C. até 9999 D.C.
Entretanto esta função trabalha com datas anteriores à 4713 A.C, porém tal uso não faz muito sentido. O calendário foi criado em 46 A.C., mas os detalhes não foram padronizados até o ano 8 D.C., e talvez mais tarde no 4º século. Além disso, o começo do ano variou de uma cultura para outra - nem todas aceitaram o Janeiro como sendo o primeiro mês.
Lembre-se, o sistema atual de calendário que é usado mundialmente é o Gregoriano. A função gregoriantojd() pode ser usada para converter datas no formato Gregoriano para o formato "Julian Day Count".
Parâmetros
- month
-
O mês como um número entre 1 (para janeiro) a 12 (para dezembro)
- day
-
O dia como um número entre 1 a 31
- year
-
O ano como um número entre -4713 a 9999
Valor Retornado
A data Juliana para a dada data Juliana como um inteiro.
Veja Também
- jdtojulian() - Converte uma data do calendário "Julian Day Count" para o calendário "Julian"
- cal_to_jd() - Converte um calendário (suportado) para o calendário "Julian Day Count"
unixtojd
(PHP 4, PHP 5)
unixtojd — Converte datas do sistema Unix para data Juliana
Descrição
Retorna a data Juliana para um Unix timestamp (segundos desde 1.1.1970), ou para o dia atual se nenhum timestamp for especificado.
Parâmetros
- timestamp
-
Um timestamp para converter.
Valor Retornado
Um número de data Juliana como inteiro.
Índice
- cal_days_in_month — Retorna o número de dias em um mês de um calendário e ano requisitado
- cal_from_jd — Converte à partir do "Julian Day Count" para um outro calendário suportado
- cal_info — Retorna informações sobre um calendário em particular
- cal_to_jd — Converte um calendário (suportado) para o calendário "Julian Day Count"
- easter_date — Retorna a data do sistema UNIX correspondente à meia-noite da Páscoa do ano especificado. Se nenhum ano tiver sido especificado, será assumido o ano atual.
- easter_days — Obtém o número de dias entre 21 de Março e o dia da Páscoa em determinado ano.
- FrenchToJD — Converte uma data do calendário Republicano da França para o calendário "Julian Day Count".
- GregorianToJD — Converte uma data gregoriana para o "Julian Day Count"
- JDDayOfWeek — Retorna o dia da semana
- JDMonthName — Retorna o nome de um mês
- JDToFrench — Converte do calendário "Julian Day Count" para o calendário Republicano Francês
- JDToGregorian — Converte uma data no formato "Julian Day Count" para o formato Gregoriano
- jdtojewish — Convete uma data do calendário "Julian Day Count" para o calendário Judaico
- JDToJulian — Converte uma data do calendário "Julian Day Count" para o calendário "Julian"
- jdtounix — Converte do formato de dada Juliana para Unix timestamp
- JewishToJD — Converte uma data do calendário Judaico para o calendário "Julian Day Count"
- JulianToJD — Converte datas no formato "Julian" para o formato "Julian Day Count"
- unixtojd — Converte datas do sistema Unix para data Juliana
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Calendário Funções
- cal_days_in_month — Retorna o número de dias em um mês de um calendário e ano requisitado
- cal_from_jd — Converte à partir do "Julian Day Count" para um outro calendário suportado
- cal_info — Retorna informações sobre um calendário em particular
- cal_to_jd — Converte um calendário (suportado) para o calendário "Julian Day Count"
- easter_date — Retorna a data do sistema UNIX correspondente à meia-noite da Páscoa do ano especificado. Se nenhum ano tiver sido especificado, será assumido o ano atual.
- easter_days — Obtém o número de dias entre 21 de Março e o dia da Páscoa em determinado ano.
- FrenchToJD — Converte uma data do calendário Republicano da França para o calendário "Julian Day Count".
- GregorianToJD — Converte uma data gregoriana para o "Julian Day Count"
- JDDayOfWeek — Retorna o dia da semana
- JDMonthName — Retorna o nome de um mês
- JDToFrench — Converte do calendário "Julian Day Count" para o calendário Republicano Francês
- JDToGregorian — Converte uma data no formato "Julian Day Count" para o formato Gregoriano
- jdtojewish — Convete uma data do calendário "Julian Day Count" para o calendário Judaico
- JDToJulian — Converte uma data do calendário "Julian Day Count" para o calendário "Julian"
- jdtounix — Converte do formato de dada Juliana para Unix timestamp
- JewishToJD — Converte uma data do calendário Judaico para o calendário "Julian Day Count"
- JulianToJD — Converte datas no formato "Julian" para o formato "Julian Day Count"
- unixtojd — Converte datas do sistema Unix para data Juliana
Data e Hora
Introdução
Estas funções te permitem conseguir a data e a hora do servidor onde o PHP está rodando. Você pode usar estas funções para formatar a saída de data e hora de muitas maneiras diferentes.
Nota: Por favor mantenha em mente que estas funções dependem das configurações locais do servidor. Considerar especialmente horário-de-verão (use e.g. $date = strtotime('+7 days', $date) e não $date += 7*24*60*60) e anos bissextos quando trabalhar com estas funções.
Nota: Os timezones referenciados nesta seção podem ser encontrados em Lista de Timezones Suportados.
Instalação/Configuração
Índice
Dependências
Nenhuma biblioteca externa é necessária para compilar esta extensão.
Instalação
Não há nenhuma instalação necessária para utilizar estas funções, elas fazem parte do núcleo do PHP.
Nota: Getting the latest timezone database
The latest version of the timezone database can be installed via PECL's » timezonedb.
Nota: Experimental DateTime support in PHP 5.1.x
Although the DateTime class (and related functions) are enabled by default since PHP 5.2.0, it is possible to add experimental support into PHP 5.1.x by using the following flag before configure/compile: CFLAGS=-DEXPERIMENTAL_DATE_SUPPORT=1
Configurações em Execução
O comportamento dessas funções podem ser modificado pelas configurações do php.ini.
| Nome | Valor Padrão | Alterável | Changelog |
|---|---|---|---|
| date.default_latitude | "31.7667" | PHP_INI_ALL | Disponível desde o PHP 5.0.0. |
| date.default_longitude | "35.2333" | PHP_INI_ALL | Disponível desde o PHP 5.0.0. |
| date.sunrise_zenith | "90.583333" | PHP_INI_ALL | Disponível desde o PHP 5.0.0. |
| date.sunset_zenith | "90.583333" | PHP_INI_ALL | Disponível desde o PHP 5.0.0. |
| date.timezone | "" | PHP_INI_ALL | Disponível desde o PHP 5.1.0. |
Breve descrição das diretivas de configuração.
- date.default_latitude float
-
A latitude padrão.
- date.default_longitude float
-
A longitude padrão.
- date.sunrise_zenith float
-
O zenith do nascer do sol padrão.
- date.sunset_zenith float
-
O zenith do pôr-do-sol padrão.
- date.timezone string
-
A zona horária padrão usada por todas as funções de data/hora se a variável de ambiente TZ não existir. A ordem de precedência é descrita na página da função date_default_timezone_get(). Veja Lista de Timezones Suportados para uma lista de zonas horárias suportadas.
Nota: As primeiras quatro opções de configuração são usadas atualmente por date_sunrise() e date_sunset().
Tipos Resource
Esta extensão não possui nenhum tipo resource.
Constantes pré-definidas
As seguintes constantes são definidas desde o PHP 5.1.1 e oferecem representações padrão de datas, que podem ser usadas com funções de formatação de datas (como date()).
- DATE_ATOM (string)
- Atom (exemplo: 2005-08-15T15:52:01+00:00)
- DATE_COOKIE (string)
- HTTP Cookies (exemplo: Monday, 15-Aug-05 15:52:01 UTC)
- DATE_ISO8601 (string)
- ISO-8601 (exemplo: 2005-08-15T15:52:01+0000)
- DATE_RFC822 (string)
- RFC 822 (exemplo: Mon, 15 Aug 05 15:52:01 +0000)
- DATE_RFC850 (string)
- RFC 850 (exemplo: Monday, 15-Aug-05 15:52:01 UTC)
- DATE_RFC1036 (string)
- RFC 1036 (exemplo: Mon, 15 Aug 05 15:52:01 +0000)
- DATE_RFC1123 (string)
- RFC 1123 (exemplo: Mon, 15 Aug 2005 15:52:01 +0000)
- DATE_RFC2822 (string)
- RFC 2822 (Mon, 15 Aug 2005 15:52:01 +0000)
- DATE_RFC3339 (string)
- O mesmo que DATE_ATOM (desde o PHP 5.1.3)
- DATE_RSS (string)
- RSS (Mon, 15 Aug 2005 15:52:01 +0000)
- DATE_W3C (string)
- World Wide Web Consortium (exemplo: 2005-08-15T15:52:01+00:00)
As seguintes constantes existem desde o PHP 5.1.2 e especificam o formato retornado pelas funções date_sunrise() e date_sunset().
Lista de Timezones Suportados
Índice
Aqui você encontrará a lista completa de timezones suportados pelo PHP, os quais podem ser usados com e.g. date_default_timezone_set().
Nota: A mais recente versão do banco de dados de timezone pode ser instalada via » timezonedb do PECL.
Nota: This list is based upon the timezone database version 2011.14.
Africa
| Africa/Abidjan | Africa/Accra | Africa/Addis_Ababa | Africa/Algiers | Africa/Asmara |
| Africa/Asmera | Africa/Bamako | Africa/Bangui | Africa/Banjul | Africa/Bissau |
| Africa/Blantyre | Africa/Brazzaville | Africa/Bujumbura | Africa/Cairo | Africa/Casablanca |
| Africa/Ceuta | Africa/Conakry | Africa/Dakar | Africa/Dar_es_Salaam | Africa/Djibouti |
| Africa/Douala | Africa/El_Aaiun | Africa/Freetown | Africa/Gaborone | Africa/Harare |
| Africa/Johannesburg | Africa/Juba | Africa/Kampala | Africa/Khartoum | Africa/Kigali |
| Africa/Kinshasa | Africa/Lagos | Africa/Libreville | Africa/Lome | Africa/Luanda |
| Africa/Lubumbashi | Africa/Lusaka | Africa/Malabo | Africa/Maputo | Africa/Maseru |
| Africa/Mbabane | Africa/Mogadishu | Africa/Monrovia | Africa/Nairobi | Africa/Ndjamena |
| Africa/Niamey | Africa/Nouakchott | Africa/Ouagadougou | Africa/Porto-Novo | Africa/Sao_Tome |
| Africa/Timbuktu | Africa/Tripoli | Africa/Tunis | Africa/Windhoek |
America
| America/Adak | America/Anchorage | America/Anguilla | America/Antigua | America/Araguaina |
| America/Argentina/Buenos_Aires | America/Argentina/Catamarca | America/Argentina/ComodRivadavia | America/Argentina/Cordoba | America/Argentina/Jujuy |
| America/Argentina/La_Rioja | America/Argentina/Mendoza | America/Argentina/Rio_Gallegos | America/Argentina/Salta | America/Argentina/San_Juan |
| America/Argentina/San_Luis | America/Argentina/Tucuman | America/Argentina/Ushuaia | America/Aruba | America/Asuncion |
| America/Atikokan | America/Atka | America/Bahia | America/Bahia_Banderas | America/Barbados |
| America/Belem | America/Belize | America/Blanc-Sablon | America/Boa_Vista | America/Bogota |
| America/Boise | America/Buenos_Aires | America/Cambridge_Bay | America/Campo_Grande | America/Cancun |
| America/Caracas | America/Catamarca | America/Cayenne | America/Cayman | America/Chicago |
| America/Chihuahua | America/Coral_Harbour | America/Cordoba | America/Costa_Rica | America/Cuiaba |
| America/Curacao | America/Danmarkshavn | America/Dawson | America/Dawson_Creek | America/Denver |
| America/Detroit | America/Dominica | America/Edmonton | America/Eirunepe | America/El_Salvador |
| America/Ensenada | America/Fort_Wayne | America/Fortaleza | America/Glace_Bay | America/Godthab |
| America/Goose_Bay | America/Grand_Turk | America/Grenada | America/Guadeloupe | America/Guatemala |
| America/Guayaquil | America/Guyana | America/Halifax | America/Havana | America/Hermosillo |
| America/Indiana/Indianapolis | America/Indiana/Knox | America/Indiana/Marengo | America/Indiana/Petersburg | America/Indiana/Tell_City |
| America/Indiana/Vevay | America/Indiana/Vincennes | America/Indiana/Winamac | America/Indianapolis | America/Inuvik |
| America/Iqaluit | America/Jamaica | America/Jujuy | America/Juneau | America/Kentucky/Louisville |
| America/Kentucky/Monticello | America/Knox_IN | America/Kralendijk | America/La_Paz | America/Lima |
| America/Los_Angeles | America/Louisville | America/Lower_Princes | America/Maceio | America/Managua |
| America/Manaus | America/Marigot | America/Martinique | America/Matamoros | America/Mazatlan |
| America/Mendoza | America/Menominee | America/Merida | America/Metlakatla | America/Mexico_City |
| America/Miquelon | America/Moncton | America/Monterrey | America/Montevideo | America/Montreal |
| America/Montserrat | America/Nassau | America/New_York | America/Nipigon | America/Nome |
| America/Noronha | America/North_Dakota/Beulah | America/North_Dakota/Center | America/North_Dakota/New_Salem | America/Ojinaga |
| America/Panama | America/Pangnirtung | America/Paramaribo | America/Phoenix | America/Port-au-Prince |
| America/Port_of_Spain | America/Porto_Acre | America/Porto_Velho | America/Puerto_Rico | America/Rainy_River |
| America/Rankin_Inlet | America/Recife | America/Regina | America/Resolute | America/Rio_Branco |
| America/Rosario | America/Santa_Isabel | America/Santarem | America/Santiago | America/Santo_Domingo |
| America/Sao_Paulo | America/Scoresbysund | America/Shiprock | America/Sitka | America/St_Barthelemy |
| America/St_Johns | America/St_Kitts | America/St_Lucia | America/St_Thomas | America/St_Vincent |
| America/Swift_Current | America/Tegucigalpa | America/Thule | America/Thunder_Bay | America/Tijuana |
| America/Toronto | America/Tortola | America/Vancouver | America/Virgin | America/Whitehorse |
| America/Winnipeg | America/Yakutat | America/Yellowknife |
Antarctica
| Antarctica/Casey | Antarctica/Davis | Antarctica/DumontDUrville | Antarctica/Macquarie | Antarctica/Mawson |
| Antarctica/McMurdo | Antarctica/Palmer | Antarctica/Rothera | Antarctica/South_Pole | Antarctica/Syowa |
| Antarctica/Vostok |
Arctic
| Arctic/Longyearbyen |
Asia
| Asia/Aden | Asia/Almaty | Asia/Amman | Asia/Anadyr | Asia/Aqtau |
| Asia/Aqtobe | Asia/Ashgabat | Asia/Ashkhabad | Asia/Baghdad | Asia/Bahrain |
| Asia/Baku | Asia/Bangkok | Asia/Beirut | Asia/Bishkek | Asia/Brunei |
| Asia/Calcutta | Asia/Choibalsan | Asia/Chongqing | Asia/Chungking | Asia/Colombo |
| Asia/Dacca | Asia/Damascus | Asia/Dhaka | Asia/Dili | Asia/Dubai |
| Asia/Dushanbe | Asia/Gaza | Asia/Harbin | Asia/Hebron | Asia/Ho_Chi_Minh |
| Asia/Hong_Kong | Asia/Hovd | Asia/Irkutsk | Asia/Istanbul | Asia/Jakarta |
| Asia/Jayapura | Asia/Jerusalem | Asia/Kabul | Asia/Kamchatka | Asia/Karachi |
| Asia/Kashgar | Asia/Kathmandu | Asia/Katmandu | Asia/Kolkata | Asia/Krasnoyarsk |
| Asia/Kuala_Lumpur | Asia/Kuching | Asia/Kuwait | Asia/Macao | Asia/Macau |
| Asia/Magadan | Asia/Makassar | Asia/Manila | Asia/Muscat | Asia/Nicosia |
| Asia/Novokuznetsk | Asia/Novosibirsk | Asia/Omsk | Asia/Oral | Asia/Phnom_Penh |
| Asia/Pontianak | Asia/Pyongyang | Asia/Qatar | Asia/Qyzylorda | Asia/Rangoon |
| Asia/Riyadh | Asia/Saigon | Asia/Sakhalin | Asia/Samarkand | Asia/Seoul |
| Asia/Shanghai | Asia/Singapore | Asia/Taipei | Asia/Tashkent | Asia/Tbilisi |
| Asia/Tehran | Asia/Tel_Aviv | Asia/Thimbu | Asia/Thimphu | Asia/Tokyo |
| Asia/Ujung_Pandang | Asia/Ulaanbaatar | Asia/Ulan_Bator | Asia/Urumqi | Asia/Vientiane |
| Asia/Vladivostok | Asia/Yakutsk | Asia/Yekaterinburg | Asia/Yerevan |
Atlantic
| Atlantic/Azores | Atlantic/Bermuda | Atlantic/Canary | Atlantic/Cape_Verde | Atlantic/Faeroe |
| Atlantic/Faroe | Atlantic/Jan_Mayen | Atlantic/Madeira | Atlantic/Reykjavik | Atlantic/South_Georgia |
| Atlantic/St_Helena | Atlantic/Stanley |
Australia
| Australia/ACT | Australia/Adelaide | Australia/Brisbane | Australia/Broken_Hill | Australia/Canberra |
| Australia/Currie | Australia/Darwin | Australia/Eucla | Australia/Hobart | Australia/LHI |
| Australia/Lindeman | Australia/Lord_Howe | Australia/Melbourne | Australia/North | Australia/NSW |
| Australia/Perth | Australia/Queensland | Australia/South | Australia/Sydney | Australia/Tasmania |
| Australia/Victoria | Australia/West | Australia/Yancowinna |
Europe
| Europe/Amsterdam | Europe/Andorra | Europe/Athens | Europe/Belfast | Europe/Belgrade |
| Europe/Berlin | Europe/Bratislava | Europe/Brussels | Europe/Bucharest | Europe/Budapest |
| Europe/Chisinau | Europe/Copenhagen | Europe/Dublin | Europe/Gibraltar | Europe/Guernsey |
| Europe/Helsinki | Europe/Isle_of_Man | Europe/Istanbul | Europe/Jersey | Europe/Kaliningrad |
| Europe/Kiev | Europe/Lisbon | Europe/Ljubljana | Europe/London | Europe/Luxembourg |
| Europe/Madrid | Europe/Malta | Europe/Mariehamn | Europe/Minsk | Europe/Monaco |
| Europe/Moscow | Europe/Nicosia | Europe/Oslo | Europe/Paris | Europe/Podgorica |
| Europe/Prague | Europe/Riga | Europe/Rome | Europe/Samara | Europe/San_Marino |
| Europe/Sarajevo | Europe/Simferopol | Europe/Skopje | Europe/Sofia | Europe/Stockholm |
| Europe/Tallinn | Europe/Tirane | Europe/Tiraspol | Europe/Uzhgorod | Europe/Vaduz |
| Europe/Vatican | Europe/Vienna | Europe/Vilnius | Europe/Volgograd | Europe/Warsaw |
| Europe/Zagreb | Europe/Zaporozhye | Europe/Zurich |
Indian
| Indian/Antananarivo | Indian/Chagos | Indian/Christmas | Indian/Cocos | Indian/Comoro |
| Indian/Kerguelen | Indian/Mahe | Indian/Maldives | Indian/Mauritius | Indian/Mayotte |
| Indian/Reunion |
Pacific
| Pacific/Apia | Pacific/Auckland | Pacific/Chatham | Pacific/Chuuk | Pacific/Easter |
| Pacific/Efate | Pacific/Enderbury | Pacific/Fakaofo | Pacific/Fiji | Pacific/Funafuti |
| Pacific/Galapagos | Pacific/Gambier | Pacific/Guadalcanal | Pacific/Guam | Pacific/Honolulu |
| Pacific/Johnston | Pacific/Kiritimati | Pacific/Kosrae | Pacific/Kwajalein | Pacific/Majuro |
| Pacific/Marquesas | Pacific/Midway | Pacific/Nauru | Pacific/Niue | Pacific/Norfolk |
| Pacific/Noumea | Pacific/Pago_Pago | Pacific/Palau | Pacific/Pitcairn | Pacific/Pohnpei |
| Pacific/Ponape | Pacific/Port_Moresby | Pacific/Rarotonga | Pacific/Saipan | Pacific/Samoa |
| Pacific/Tahiti | Pacific/Tarawa | Pacific/Tongatapu | Pacific/Truk | Pacific/Wake |
| Pacific/Wallis | Pacific/Yap |
Others
| Brazil/Acre | Brazil/DeNoronha | Brazil/East | Brazil/West | Canada/Atlantic |
| Canada/Central | Canada/East-Saskatchewan | Canada/Eastern | Canada/Mountain | Canada/Newfoundland |
| Canada/Pacific | Canada/Saskatchewan | Canada/Yukon | CET | Chile/Continental |
| Chile/EasterIsland | CST6CDT | Cuba | EET | Egypt |
| Eire | EST | EST5EDT | Etc/GMT | Etc/GMT+0 |
| Etc/GMT+1 | Etc/GMT+10 | Etc/GMT+11 | Etc/GMT+12 | Etc/GMT+2 |
| Etc/GMT+3 | Etc/GMT+4 | Etc/GMT+5 | Etc/GMT+6 | Etc/GMT+7 |
| Etc/GMT+8 | Etc/GMT+9 | Etc/GMT-0 | Etc/GMT-1 | Etc/GMT-10 |
| Etc/GMT-11 | Etc/GMT-12 | Etc/GMT-13 | Etc/GMT-14 | Etc/GMT-2 |
| Etc/GMT-3 | Etc/GMT-4 | Etc/GMT-5 | Etc/GMT-6 | Etc/GMT-7 |
| Etc/GMT-8 | Etc/GMT-9 | Etc/GMT0 | Etc/Greenwich | Etc/UCT |
| Etc/Universal | Etc/UTC | Etc/Zulu | Factory | GB |
| GB-Eire | GMT | GMT+0 | GMT-0 | GMT0 |
| Greenwich | Hongkong | HST | Iceland | Iran |
| Israel | Jamaica | Japan | Kwajalein | Libya |
| MET | Mexico/BajaNorte | Mexico/BajaSur | Mexico/General | MST |
| MST7MDT | Navajo | NZ | NZ-CHAT | Poland |
| Portugal | PRC | PST8PDT | ROC | ROK |
| Singapore | Turkey | UCT | Universal | US/Alaska |
| US/Aleutian | US/Arizona | US/Central | US/East-Indiana | US/Eastern |
| US/Hawaii | US/Indiana-Starke | US/Michigan | US/Mountain | US/Pacific |
| US/Pacific-New | US/Samoa | UTC | W-SU | WET |
| Zulu |
Por favor não use nenhuma das zonas de horario listadas aqui (alem de UTC), elas só existem por motivo de compatibilidade com versões anteriores.
Funções de Data/Hora
checkdate
(PHP 4, PHP 5)
checkdate — Valida uma data Gregoriana
Descrição
Checa a validade da data formada pelos argumentos. Uma data é considerada válida se cada parâmetro é adequadamente definida.
Parâmetros
- month
-
O mês entre 1 e 12.
- day
-
O dia está dentro do número permitido de dias para um month. Anos bissexto são levados em consideração.
- year
-
The year is between 1 and 32767 inclusive.
Valor Retornado
Retorna TRUE se a dada data é valida; caso contrário retorna FALSE.
Exemplos
Exemplo #1 Exemplo da checkdate()
<?php
var_dump(checkdate(12, 31, 2000));
var_dump(checkdate(2, 29, 2001));
?>
O exemplo acima irá imprimir:
bool(true) bool(false)
Veja Também
- mktime() - Obtém um timestamp Unix para uma data
- strtotime() - Analisa qualquer descrição em texto em inglês de data hora em timestamp Unix
date_add
(PHP 5 >= 5.3.0)
date_add — Sinônimo de DateTime::add()
Descrição
Esta função é um apelido para: DateTime::add()
date_create_from_format
(PHP 5 >= 5.3.0)
date_create_from_format — Sinônimo de DateTime::createFromFormat()
Descrição
Esta função é um apelido para: DateTime::createFromFormat()
date_create
(PHP 5 >= 5.2.0)
date_create — Retorna um novo objeto DateTime
Descrição
Parâmetros
- time
-
String no formato aceito pela strtotime(), o padrão é "now".
- timezone
-
Time zone do tempo.
Valor Retornado
Retorna um objeto DateTime em sucesso ou FALSE em falha.
date_date_set
(PHP 5 >= 5.2.0)
date_date_set — Define a data
Descrição
Parâmetros
- object
-
Objeto DateTime.
- year
-
Ano da data.
- month
-
Mês da data.
- day
-
Dia da data.
Valor Retornado
Retorna NULL em caso de sucesso ou FALSE em falha.
date_default_timezone_get
(PHP 5 >= 5.1.0)
date_default_timezone_get — Retorna a timezone (zona de tempo) padrão usada por todas as funções de data e tempo em um script
Descrição
Em ordem de preferência, essa função retorna a timezone padrão por:
-
Lendo a timezone configurada utilizando a função date_default_timezone_set() (se existir)
-
Até o PHP 5.4.0 somente: Lendo a variável de ambiente TZ (se não estiver vazia)
-
Lendo o valor de date.timezone do ini (se configurada)
-
Até o PHP 5.4.0 somente: Perguntando ao sistema operacional (se suportado e permitido pelo SO). Isso usa um algoritmo que tenta adivinhar a timezone. De jeito nenhum isso funcionará corretamente em toda situação. Um aviso é mostrado quando esse estágio é alcançado. Não confie que ele será adivinhado corretamente, e configure date.timezone para a zona correta.
Se nenhuma das opções acima tiverem sucesso, a função date_default_timezone_get() retornará a timezone padrão UTC
Valor Retornado
Retorna uma string.
Histórico
| Versão | Descrição |
|---|---|
| 5.4.0 | A variável de ambiente TZ não é mais utilizada para adivinhar a timezone. |
| 5.4.0 | A timezone não é mais adivinhada de informações disponíveis através do sistema operacional já que a timezone adivinhada não é confiável. |
Exemplos
Exemplo #1 Lendo a timezone padrão
<?php
date_default_timezone_set('Europe/London');
if (date_default_timezone_get()) {
echo 'date_default_timezone_set: ' . date_default_timezone_get() . '<br />';
}
if (ini_get('date.timezone')) {
echo 'date.timezone: ' . ini_get('date.timezone');
}
?>
O exemplo acima irá imprimir algo similar a:
date_default_timezone_set: Europe/London date.timezone: Europe/London
Exemplo #2 Lendo a abreviação de uma timezone
<?php
date_default_timezone_set('America/Los_Angeles');
echo date_default_timezone_get() . ' => ' . date('e') . ' => ' . date('T');
?>
O exemplo acima irá imprimir:
America/Los_Angeles => America/Los_Angeles => PST
Veja Também
- date_default_timezone_set() - Configura a timezone padrão a ser utilizada por todas as funções de data e hora em um script
- Lista de Timezones Suportados
date_default_timezone_set
(PHP 5 >= 5.1.0)
date_default_timezone_set — Configura a timezone padrão a ser utilizada por todas as funções de data e hora em um script
Descrição
date_default_timezone_set() configura a timezone padrão a ser utilizada por todas as funções de data e hora em um script
Nota:
Desde o PHP5.1.0 (quando as funções de data e tempo foram reescritas), toda chamada a esse tipo de função irá gerar um E_NOTICE se a timezone não é válida, e/ou uma mensagem E_WARNING se estiver utilizando as configurações do sistema ou a variável de ambiente TZ.
Ao invés de utilizar essa função para setar a timezone padrão no seu script, você pode também utilizar a configuração INI date.timezone para configurar a timezone padrão.
Parâmetros
- timezone_identifier
-
O identificador da timezone, como UTC ou Europe/Lisbon. A lista de identificadores válidos está disponível em Lista de Timezones Suportados.
Valor Retornado
A função retorna FALSE se o timezone_identifier não é válido, ou TRUE caso contrário.
Exemplos
Exemplo #1 Lendo a timezone padrão
<?php
date_default_timezone_set('America/Los_Angeles');
$script_tz = date_default_timezone_get();
if (strcmp($script_tz, ini_get('date.timezone'))){
echo 'Script timezone differs from ini-set timezone.';
} else {
echo 'Script timezone and ini-set timezone match.';
}
?>
Histórico
| Versão | Descrição |
|---|---|
| 5.3.0 | Agora retorna E_WARNING ao invés de E_STRICT. |
| 5.1.2 | A função passou a validar o parâmetro timezone_identifier. |
Veja Também
- date_default_timezone_get() - Retorna a timezone (zona de tempo) padrão usada por todas as funções de data e tempo em um script
- Lista de Timezones Suportados
date_diff
(PHP 5 >= 5.3.0)
date_diff — Sinônimo de DateTime::diff()
Descrição
Esta função é um apelido para: DateTime::diff()
date_format
(PHP 5 >= 5.2.0)
date_format — Retorna a data formatada de acordo com o formato dado
Descrição
Valor Retornado
Retorna a data formatada em caso de sucesso ou FALSE em falha.
date_get_last_errors
(PHP 5 >= 5.3.0)
date_get_last_errors — Sinônimo de DateTime::getLastErrors()
Descrição
Esta função é um apelido para: DateTime::getLastErrors()
date_interval_create_from_date_string
(PHP 5 >= 5.3.0)
date_interval_create_from_date_string — Sinônimo de DateInterval::createFromDateString()
Descrição
Esta função é um apelido para: DateInterval::createFromDateString()
date_interval_format
(PHP 5 >= 5.3.0)
date_interval_format — Sinônimo de DateInterval::format()
Descrição
Esta função é um apelido para: DateInterval::format()
date_isodate_set
(PHP 5 >= 5.2.0)
date_isodate_set — Define a data ISO
Descrição
Parâmetros
- object
-
Objeto DateTime.
- year
-
Ano da data.
- week
-
Semana da data.
- day
-
Dia da data.
Valor Retornado
Retorna NULL em caso de sucesso ou FALSE em falha.
date_modify
(PHP 5 >= 5.2.0)
date_modify — Altera o timestamp
Descrição
Valor Retornado
Retorna NULL em caso de sucesso ou FALSE em falha.
Exemplos
Exemplo #1 Um exemplo da date_modify()
<?php
$date = new DateTime("2006-12-12");
$date->modify("+1 day");
echo $date->format("Y-m-d");
?>
O exemplo acima irá imprimir:
2006-12-13
Veja Também
- strtotime() - Analisa qualquer descrição em texto em inglês de data hora em timestamp Unix
date_offset_get
(PHP 5 >= 5.2.0)
date_offset_get — Sinônimo de DateTime::getOffset()
Descrição
Esta função é um apelido para: DateTime::getOffset()
date_parse_from_format
(PHP 5 >= 5.3.0)
date_parse_from_format — Get info about given date formatted according to the specified format
Descrição
Returns associative array with detailed info about given date.
Parâmetros
- format
-
Format accepted by DateTime::createFromFormat().
- date
-
String representing the date.
Valor Retornado
Returns associative array with detailed info about given date.
Exemplos
Exemplo #1 date_parse_from_format() example
<?php
$date = "6.1.2009 13:00+01:00";
print_r(date_parse_from_format("j.n.Y H:iP", $date));
?>
O exemplo acima irá imprimir:
Array
(
[year] => 2009
[month] => 1
[day] => 6
[hour] => 13
[minute] => 0
[second] => 0
[fraction] =>
[warning_count] => 0
[warnings] => Array
(
)
[error_count] => 0
[errors] => Array
(
)
[is_localtime] => 1
[zone_type] => 1
[zone] => -60
[is_dst] =>
)
date_parse
(PHP 5 >= 5.2.0)
date_parse — Retorna um array associativo com detalhes sobre uma dada data
Descrição
Valor Retornado
Retorna um array com informação sobre a data analisada em sucesso, ou FALSE em falha.
Erros
No caso do formato da data conter erro, o elemento 'erros' conterá as mensagens de erro.
Exemplos
Exemplo #1 Um exemplo da date_parse()
<?php
print_r(date_parse("2006-12-12 10:00:00.5"));
?>
O exemplo acima irá imprimir:
Array
(
[year] => 2006
[month] => 12
[day] => 12
[hour] => 10
[minute] => 0
[second] => 0
[fraction] => 0.5
[warning_count] => 0
[warnings] => Array()
[error_count] => 0
[errors] => Array()
[is_localtime] =>
)
date_sub
(PHP 5 >= 5.3.0)
date_sub — Sinônimo de DateTime::sub()
Descrição
Esta função é um apelido para: DateTime::sub()
date_sun_info
(PHP 5 >= 5.1.2)
date_sun_info — Retorna um array com informações sobre pôr-do-sol/nascer-do-sol e o início/fim do dia
Descrição
Parâmetros
- time
-
Carimbo de data (timestamp).
- latitude
-
Latitude em graus.
- longitude
-
Longitude em graus.
Valor Retornado
Retorna um array em caso de sucesso or FALSE on failure.
Exemplos
Exemplo #1 Um exemplo de date_sun_info()
<?php
$sun_info = date_sun_info(strtotime("2006-12-12"), 31.7667, 35.2333);
foreach ($sun_info as $key => $val) {
echo "$key: " . date("H:i:s", $val) . "\n";
}
?>
O exemplo acima irá imprimir:
sunrise: 05:52:11 sunset: 15:41:21 transit: 10:46:46 civil_twilight_begin: 05:24:08 civil_twilight_end: 16:09:24 nautical_twilight_begin: 04:52:25 nautical_twilight_end: 16:41:06 astronomical_twilight_begin: 04:21:32 astronomical_twilight_end: 17:12:00
Veja Também
- date_sunrise() - Returns time of sunrise for a given day and location
- date_sunset() - Returns time of sunset for a given day and location
date_sunrise
(PHP 5)
date_sunrise — Returns time of sunrise for a given day and location
Descrição
date_sunrise() returns the sunrise time for a given day (specified as a timestamp) and location.
Parâmetros
- timestamp
-
The timestamp of the day from which the sunrise time is taken.
- format
-
format constants constant description example SUNFUNCS_RET_STRING returns the result as string 16:46 SUNFUNCS_RET_DOUBLE returns the result as float 16.78243132 SUNFUNCS_RET_TIMESTAMP returns the result as integer (timestamp) 1095034606 - latitude
-
Defaults to North, pass in a negative value for South. See also: date.default_latitude
- longitude
-
Defaults to East, pass in a negative value for West. See also: date.default_longitude
- zenith
-
Default: date.sunrise_zenith
- gmtoffset
-
Specified in hours.
Valor Retornado
Returns the sunrise time in a specified format on success or FALSE on failure.
Erros
Toda a chamada a uma função de data/hora irá gerar um se a zona da hora não for valida, e/ou uma mensagem E_STRICT ou E_WARNING se estiver usando a definição do sistema ou a variável de ambiente TZ. Veja também date_default_timezone_set()
Histórico
| Versão | Descrição |
|---|---|
| 5.1.0 | Agora emite E_STRICT e E_NOTICE em erros da zona de horário. |
Exemplos
Exemplo #1 date_sunrise() example
<?php
/* calculate the sunrise time for Lisbon, Portugal
Latitude: 38.4 North
Longitude: 9 West
Zenith ~= 90
offset: +1 GMT
*/
echo date("D M d Y"). ', sunrise time : ' .date_sunrise(time(), SUNFUNCS_RET_STRING, 38.4, -9, 90, 1);
?>
O exemplo acima irá imprimir algo similar a:
Mon Dec 20 2004, sunrise time : 08:54
date_sunset
(PHP 5)
date_sunset — Returns time of sunset for a given day and location
Descrição
date_sunset() returns the sunset time for a given day (specified as a timestamp) and location.
Parâmetros
- timestamp
-
The timestamp of the day from which the sunset time is taken.
- format
-
format constants constant description example SUNFUNCS_RET_STRING returns the result as string 16:46 SUNFUNCS_RET_DOUBLE returns the result as float 16.78243132 SUNFUNCS_RET_TIMESTAMP returns the result as integer (timestamp) 1095034606 - latitude
-
Defaults to North, pass in a negative value for South. See also: date.default_latitude
- longitude
-
Defaults to East, pass in a negative value for West. See also: date.default_longitude
- zenith
-
Default: date.sunset_zenith
- gmtoffset
-
Specified in hours.
Erros
Toda a chamada a uma função de data/hora irá gerar um se a zona da hora não for valida, e/ou uma mensagem E_STRICT ou E_WARNING se estiver usando a definição do sistema ou a variável de ambiente TZ. Veja também date_default_timezone_set()
Histórico
| Versão | Descrição |
|---|---|
| 5.1.0 | Agora emite E_STRICT e E_NOTICE em erros da zona de horário. |
Valor Retornado
Returns the sunset time in a specified format on success or FALSE on failure.
Exemplos
Exemplo #1 date_sunset() example
<?php
/* calculate the sunset time for Lisbon, Portugal
Latitude: 38.4 North
Longitude: 9 West
Zenith ~= 90
offset: +1 GMT
*/
echo date("D M d Y"). ', sunset time : ' .date_sunset(time(), SUNFUNCS_RET_STRING, 38.4, -9, 90, 1);
?>
O exemplo acima irá imprimir algo similar a:
Mon Dec 20 2004, sunset time : 18:13
date_time_set
(PHP 5 >= 5.2.0)
date_time_set — Define o tempo
Descrição
Parâmetros
- object
-
Objeto DateTime.
- hour
-
Hora do tempo.
- minute
-
Minuto do tempo.
- second
-
Segundo do tempo.
Valor Retornado
Retorna NULL em caso de sucesso ou FALSE em falha.
date_timestamp_get
(PHP 5 >= 5.3.0)
date_timestamp_get — Sinônimo de DateTime::getTimestamp()
Descrição
Esta função é um apelido para: DateTime::getTimestamp()
date_timestamp_set
(PHP 5 >= 5.3.0)
date_timestamp_set — Sinônimo de DateTime::setTimestamp()
Descrição
Esta função é um apelido para: DateTime::setTimestamp()
date_timezone_get
(PHP 5 >= 5.2.0)
date_timezone_get — Sinônimo de DateTime::getTimezone()
Descrição
Esta função é um apelido para: DateTime::getTimezone()
date_timezone_set
(PHP 5 >= 5.2.0)
date_timezone_set — Sinônimo de DateTime::setTimezone()
Descrição
Esta função é um apelido para: DateTime::setTimezone()
date
(PHP 4, PHP 5)
date — Formata a data e a hora local
Descrição
Retorna uma string de acordo com a string format dada usando o inteiro timestamp dado ou a hora atual local se nenhum timestamp é dado. Em outras palavras, timestamp é opcional e o padrão para o valor de time().
Parâmetros
- format
-
A string de formato da data a ser mostrada. Veja as opções de formatação abaixo.
Os seguintes caracteres são reconhecidos na string do parâmetro format Caractere de format Descrição Exemplo de valores retornados Day --- --- d Dia do mês, 2 digitos com preenchimento de zero 01 até 31 D Uma representação textual de um dia, três letras Mon até Sun j Dia do mês sem preenchimento de zero 1 até 31 l ('L' minúsculo) A representação textual completa do dia da semana Sunday até Saturday N Representação numérica ISO-8601 do dia da semana (adicionado no PHP 5.1.0) 1 (para Segunda) até 7 (para Domingo) S Sufixo ordinal inglês para o dia do mês, 2 caracteres st, nd, rd ou th. Funciona bem com j w Representação numérica do dia da semana 0 (para domingo) até 6 (para sábado) z O dia do ano (começando do 0) 0 through 365 Semana --- --- W Número do ano da semana ISO-8601, semanas começam na Segunda (adicionado no PHP 4.1.0) Exemplo: 42 (the 42nd week in the year) Mês --- --- F Um representação completa de um mês, como January ou March January até December m Representação numérica de um mês, com leading zeros 01 a 12 M Uma representação textual curta de um mês, três letras Jan a Dec n Representação numérica de um mês, sem leading zeros 1 a 12 t Número de dias de um dado mês 28 through 31 Year --- --- L Se está em um ano bissexto 1 se está em ano bissexto, 0 caso contrário. o Número do ano ISO-8601. Este tem o mesmo valor como Y, exceto que se o número da semana ISO (W) pertence ao anterior ou próximo ano, o ano é usado ao invés. (adicionado no PHP 5.1.0) Exemplos: 1999 ou 2003 Y Uma representação de ano completa, 4 dígitos Exemplos: 1999 ou 2003 y Uma representação do ano com dois dígitos Exemplos: 99 ou 03 Tempo --- --- a Antes/Depois de meio-dia em minúsculo am or pm A Antes/Depois de meio-dia em maiúsculo AM or PM B Swatch Internet time 000 até 999 g Formato 12-horas de uma hora sem preenchimento de zero 1 até 12 G Formato 24-horas de uma hora sem preenchimento de zero 0 até 23 h Formato 12-horas de uma hora com zero preenchendo à esquerda 01 até 12 H Formato 24-horas de uma hora com zero preenchendo à esquerda 00 até 23 i Minutos com zero preenchendo à esquerda 00 até 59 s Segundos, com zero preenchendo à esquerda 00 até 59 u Milisegundos (adicionado no PHP 5.2.2) Exemplo: 54321 Timezone --- --- e Identificador de Timezone (adicionado no PHP 5.1.0) Exemplos: UTC, GMT, Atlantic/Azores I (capital i) Se a data está ou não no horário de verão 1 se horário de verão, 0 caso contrário. O Diferença para Greenwich time (GMT) em horas Exemplo: +0200 P Diferença para Greenwich time (GMT) com dois pontos entre horas e minutos (adicionado no PHP 5.1.3) Exemplo: +02:00 T Abreviação de Timezone Exemplos: EST, MDT ... Z Timezone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive. -43200 até 50400 Full Date/Time --- --- c ISO 8601 date (adicionado no PHP 5) 2004-02-12T15:19:21+00:00 r » RFC 2822 formatted date Exemplo: Thu, 21 Dec 2000 16:01:07 +0200 U Segundos desde a Época Unix (January 1 1970 00:00:00 GMT) Veja também time() Caracteres não reconhecidos no formato de serão impressos como são. O formato Z será sempre retornado 0 quando usar gmdate().
Nota:
Desde que esta função aceita somente integer timestamps o caractere de formato u é somente útil quando usando a função date_format() com um timestamp baseado pelo usuário criado com date_create().
- timestamp
-
O parâmetro opcional timestamp é um integer Unix timestamp cujo padrão é a hora local se timestamp não for dado. Em outras palavras, o padrão é o valor de time().
Valor Retornado
Retorna um string da data formatada. Se um valor não-numérico é usado para timestamp, FALSE é retornado e um erro de nível E_WARNING é emitido.
Erros
Toda a chamada a uma função de data/hora irá gerar um se a zona da hora não for valida, e/ou uma mensagem E_STRICT ou E_WARNING se estiver usando a definição do sistema ou a variável de ambiente TZ. Veja também date_default_timezone_set()
Histórico
| Versão | Descrição |
|---|---|
| 5.1.0 | O intervalo válido de um timestamp é tipicamente de Sex, 13 Dez 1901 20:45:54 GMT to Ter, 19 Jan 2038 03:14:07 GMT. (Estas são as datas que correspondem ao valor mínimo e máximo para um inteiro com sinal de 32-bit). Contudo, antes do PHP 5.1.0 este intervalo foi limitado de 01-01-1970 para 19-01-2038 em alguns sistemas (e.g. Windows). |
| 5.1.0 | Agora emite E_STRICT e E_NOTICE em erros da zona de horário. |
| 5.1.1 | Há constantes útils do padrão de formato de data/hora que podem ser usados para especificar o parâmetro format. |
Exemplos
Exemplo #1 Exemplos da date()
<?php
// Modifica a zona de tempo a ser utilizada. Disnovível desde o PHP 5.1
date_default_timezone_set('UTC');
// Exibe alguma coisa como: Monday
echo date("l");
// Exibe alguma coisa como: Monday 8th of August 2005 03:12:46 PM
echo date('l jS \of F Y h:i:s A');
// Exibe: July 1, 2000 is on a Saturday
echo "July 1, 2000 is on a " . date("l", mktime(0, 0, 0, 7, 1, 2000));
/* utiliza as constantes do parâmetro de formato */
// Exibe alguma coisa como: Mon, 15 Aug 2005 15:12:46 UTC
echo date(DATE_RFC822);
// Exibe alguma coisa como: 2000-07-01T00:00:00+00:00
echo date(DATE_ATOM, mktime(0, 0, 0, 7, 1, 2000));
?>
Você pode prevenir um caracter conhecido no formato de string de um existente escapando-o com uma barra invertida antes dele. Se o caracter com a barra invertida já é uma sequência especial, você pode precisar também escapar a barra invertida.
Exemplo #2 Caracteres de escape em date()
<?php
// exibe algo como: Wednesday the 15th
echo date("l \\t\h\e jS");
?>
É possível utilizar date() e mktime() juntos para encontrar datas no futuro ou no passado.
Exemplo #3 Exemplo da date() e mktime()
<?php
$tomorrow = mktime (0, 0, 0, date("m") , date("d")+1, date("Y"));
$lastmonth = mktime (0, 0, 0, date("m")-1, date("d"), date("Y"));
$nextyear = mktime (0, 0, 0, date("m"), date("d"), date("Y")+1);
?>
Nota:
Esta pode ser mais confiável do que simplesmente adicionar ou subtrair o número de segundos em um dia ou mês para um timestamp devido ao horário de verão.
Alguns exemplos de formatação de date(). Note que você poderia escapar qualquer outro caracter, como algum que atualmente tenha um significado especial produzirá resultados indesejáveis, e outros caracteres poderiam assumir significados em futuras versões do PHP. Quando usar escape, certifique o uso de aspas simples para evitar caracteres como \n próprio para novas linhas.
Exemplo #4 Formatação de date()
<?php
// Assumindo que hoje é: March 10th, 2001, 5:16:18 pm
$today = date("F j, Y, g:i a"); // March 10, 2001, 5:16 pm
$today = date("m.d.y"); // 03.10.01
$today = date("j, n, Y"); // 10, 3, 2001
$today = date("Ymd"); // 20010310
$today = date('h-i-s, j-m-y, it is w Day z '); // 05-16-17, 10-03-01, 1631 1618 6 Fripm01
$today = date('\i\t \i\s \t\h\e jS \d\a\y.'); // It is the 10th day.
$today = date("D M j G:i:s T Y"); // Sat Mar 10 15:16:08 MST 2001
$today = date('H:m:s \m \i\s\ \m\o\n\t\h'); // 17:03:17 m is month
$today = date("H:i:s"); // 17:16:17
?>
Para formatar datas em outras línguas, você usaria as funções setlocale() e strftime() ao invés de date().
Notas
Nota:
Para gerar um timestamp de uma string da representação da data, você pode usar strtotime(). Adicionalmente, alguns banco de dados tem funções para converter os formatos de data para timestamps (como a função » UNIX_TIMESTAMP do MySQL).
Timestamp do início da requisição está disponível na $_SERVER['REQUEST_TIME'] desde o PHP 5.1.
Veja Também
- getlastmod() - Obtém o tempo da última modificação na pagina
- gmdate() - Formata uma data/hora GMT/CUT
- mktime() - Obtém um timestamp Unix para uma data
- strftime() - Formata uma hora/data de acordo com as configurações locais
- time() - Retorna o timestamp Unix atual
getdate
(PHP 4, PHP 5)
getdate — Consegue informações data/hora
Descrição
Retorna um array associativo contendo a informação da data do timestamp, ou a hora corrente local se nenhum timestamp é dado.
Parâmetros
Valor Retornado
Retorna um array associativo de informação sobre o timestamp. Elementos do array associativo são os seguintes:
| Chave | Descrição | Exemplo dos valores retornados |
|---|---|---|
| "seconds" | Representação numérica dos segundos | 0 a 59 |
| "minutes" | Representação numérica dos minutos | 0 a 59 |
| "hours" | Representação numérica das horas | 0 a 23 |
| "mday" | Representação numérica do dia do mês | 1 a 31 |
| "wday" | Representação numérica do dia da semana | 0 (para Sunday) a 6 (para Saturday) |
| "mon" | Representação numérica de um mês | 1 a 12 |
| "year" | Representação numérica completa do ano, 4 digitos | Exemples: 1999 ou 2003 |
| "yday" | Numeric representation of the day of the year | 0 a 366 |
| "weekday" | Representação textual completa do dia da semana | Sunday a Saturday |
| "month" | Representação textual completa de um mês, tal como January ou March | January a December |
| 0 | Segundos desde a época UNIX, similar aos valores retornados pela time() e usados por date(). | Dependente do sistema, tipicamente -2147483648 à 2147483647. |
Exemplos
Exemplo #1 Exemplo da getdate()
<?php
$today = getdate();
print_r($today);
?>
O exemplo acima irá imprimir algo similar a:
Array
(
[seconds] => 40
[minutes] => 58
[hours] => 21
[mday] => 17
[wday] => 2
[mon] => 6
[year] => 2003
[yday] => 167
[weekday] => Tuesday
[month] => June
[0] => 1055901520
)
Veja Também
- date() - Formata a data e a hora local
- time() - Retorna o timestamp Unix atual
- setlocale() - Define informações locais
gettimeofday
(PHP 4, PHP 5)
gettimeofday — Obtém a hora local
Descrição
Esta é uma interface para gettimeofday(2). Esta retorna um array contendo o dado retornado da comunicação com o sistema.
Parâmetros
- return_float
-
Quando definido para TRUE, um float ao invés de array é retornado.
Valor Retornado
Por padrão um array é retornado. Se return_float é definido, então um float é retornado.
Array keys:
- "sec" - segundos desde a época Unix
- "usec" - microsegundos
- "minuteswest" - minutos a oeste de Greenwich
- "dsttime" - tipo de correção dst
Histórico
| Versão | Descrição |
|---|---|
| 5.1.0 | O parâmetro return_float foi adicionado. |
Exemplos
Exemplo #1 Exemplo da gettimeofday()
<?php
print_r(gettimeofday());
echo gettimeofday(true);
?>
O exemplo acima irá imprimir algo similar a:
Array
(
[sec] => 1073504408
[usec] => 238215
[minuteswest] => 0
[dsttime] => 1
)
1073504408.23910
gmdate
(PHP 4, PHP 5)
gmdate — Formata uma data/hora GMT/CUT
Descrição
Idêntica a função date() exceto que o tempo está em Greenwich Mean Time (GMT).
Parâmetros
Valor Retornado
Retorna uma string da data formatada. Se um valor não-numérico é usado para timestamp, FALSE é retornado e um erro de nível E_WARNING é emitido.
Histórico
| Versão | Descrição |
|---|---|
| 5.1.0 | O intervalo válido de um timestamp é normalmente de Fri, 13 Dec 1901 20:45:54 GMT a Tue, 19 Jan 2038 03:14:07 GMT. (Estas são as datas que correspondem aos valores máximo e mínimo para um inteiro 32-bit com sinal). Contudo, antes do PHP 5.1.0 este intervalo foi limitado para 01-01-1970 a 19-01-2038 em alguns sistemas (e.g. Windows). |
| 5.1.1 | Há constantes úteis do padrão de formato data/hora que podem ser usadas para especificar o parâmetro format. |
Exemplos
Exemplo #1 Exemplo da gmdate()
Quando executado na Finlândia (GMT +0200), a primeira linha abaixo imprime "Jan 01 1998 00:00:00", enquando a segunda imprime "Dec 31 1997 22:00:00".
<?php
echo date("M d Y H:i:s", mktime(0, 0, 0, 1, 1, 1998));
echo gmdate("M d Y H:i:s", mktime(0, 0, 0, 1, 1, 1998));
?>
Veja Também
- date() - Formata a data e a hora local
- mktime() - Obtém um timestamp Unix para uma data
- gmmktime() - Obtém um timestamp Unix para uma data GMT
- strftime() - Formata uma hora/data de acordo com as configurações locais
gmmktime
(PHP 4, PHP 5)
gmmktime — Obtém um timestamp Unix para uma data GMT
Descrição
Idêntico ao mktime() exceto que os parâmetros representam uma data GMT. gmmktime() internamente usa mktime() então somente tempo válido no derivado tempo local pode ser usado.
Como em mktime(), os argumentos podem ser omitidos da direita para esquerda, com qualquer argumento omitido sendo definido para o valor GMT correspondente.
Parâmetros
- hour
-
A hora
- minute
-
O minuto
- second
-
O segundo
- month
-
O mês
- day
-
O dia
- year
-
O ano
- is_dst
-
Parâmetros sempre representam uma data GMT em is_dst sendo assim, não influencia o resultado.
Valor Retornado
Retorna um integer Unix timestamp.
Histórico
| Versão | Descrição |
|---|---|
| 5.1.0 | As of PHP 5.1.0, the is_dst parameter became deprecated. As a result, the new timezone handling features should be used instead. |
Exemplos
Exemplo #1 gmmktime() no Windows
<?php
gmmktime(0, 0, 0, 1, 1, 1970); // valid in GMT and west, invalid in east
?>
gmstrftime
(PHP 4, PHP 5)
gmstrftime — Formata uma hora/data GMT/CUT de acordo com as configurações locais
Descrição
Mesmo comportamento que strftime() exceto que o tempo retornado é Greenwich Mean Time (GMT). Por exemplo, quando roda no Padrão de tempo Oriental (GMT -0500), a primeira linha abaixo imprime "Dec 31 1998 20:00:00", enquanto a segunda linha imprime "Jan 01 1999 01:00:00".
Parâmetros
- format
-
See description in strftime().
- timestamp
-
O parâmetro opcional timestamp é um integer Unix timestamp cujo padrão é a hora local se timestamp não for dado. Em outras palavras, o padrão é o valor de time().
Valor Retornado
Retorna uma string formatada de acordo com a dada string de formato usando o dado timestamp ou o atual tempo local se nenhum timestamp é dado. Nomes de mês e dias da semana e outras strings dependem do atual locale definido com setlocale().
Exemplos
Exemplo #1 Exemplo da gmstrftime()
<?php
setlocale(LC_TIME, 'en_US');
echo strftime("%b %d %Y %H:%M:%S", mktime(20, 0, 0, 12, 31, 98)) . "\n";
echo gmstrftime("%b %d %Y %H:%M:%S", mktime(20, 0, 0, 12, 31, 98)) . "\n";
?>
idate
(PHP 5)
idate — Format a local time/date as integer
Descrição
Returns a number formatted according to the given format string using the given integer timestamp or the current local time if no timestamp is given. In other words, timestamp is optional and defaults to the value of time().
Unlike the function date(), idate() accepts just one char in the format parameter.
Parâmetros
- format
-
The following characters are recognized in the format parameter string format character Description B Swatch Beat/Internet Time d Day of the month h Hour (12 hour format) H Hour (24 hour format) i Minutes I (uppercase i) returns 1 if DST is activated, 0 otherwise L (uppercase l) returns 1 for leap year, 0 otherwise m Month number s Seconds t Days in current month U Seconds since the Unix Epoch - January 1 1970 00:00:00 UTC - this is the same as time() w Day of the week (0 on Sunday) W ISO-8601 week number of year, weeks starting on Monday y Year (1 or 2 digits - check note below) Y Year (4 digits) z Day of the year Z Timezone offset in seconds - timestamp
-
O parâmetro opcional timestamp é um integer Unix timestamp cujo padrão é a hora local se timestamp não for dado. Em outras palavras, o padrão é o valor de time().
Valor Retornado
Returns an integer.
As idate() always returns an integer and as they can't start with a "0", idate() may return fewer digits than you would expect. See the example below.
Erros
Toda a chamada a uma função de data/hora irá gerar um se a zona da hora não for valida, e/ou uma mensagem E_STRICT ou E_WARNING se estiver usando a definição do sistema ou a variável de ambiente TZ. Veja também date_default_timezone_set()
Histórico
| Versão | Descrição |
|---|---|
| 5.1.0 | Agora emite E_STRICT e E_NOTICE em erros da zona de horário. |
Exemplos
Exemplo #1 idate() example
<?php
$timestamp = strtotime('1st January 2004'); //1072915200
// this prints the year in a two digit format
// however, as this would start with a "0", it
// only prints "4"
echo idate('y', $timestamp);
?>
localtime
(PHP 4, PHP 5)
localtime — Obtém a hora local
Descrição
A função localtime() retorna uma matriz idêntica àquela da estrutura retornada pela chamada de uma função em C.
Parâmetros
- timestamp
-
O parâmetro opcional timestamp é um integer Unix timestamp cujo padrão é a hora local se timestamp não for dado. Em outras palavras, o padrão é o valor de time().
- is_associative
-
Se definido para FALSE ou não fornecido, então um array é retornado, com índices numéricos. Se o argumento é definido para TRUE então localtime() é um array associativo contendo todos os diferentes elementos da estrutura retornados pela chamada da função C para o localtime. Os nomes das diferentes chaves do array associativo são as seguintes:
- "tm_sec" - Segundos
- "tm_min" - Minutos
- "tm_hour" - Hora
- "tm_mday" - Dia do mês Meses são de 0 (Jan) à 11 (Dez) e dias da semana são de 0 (Dom) à 6 (Sáb).
- "tm_mon" - Mês do ano, começa com 0 para Janeiro
- "tm_year" - Anos desde 1900
- "tm_wday" - Dia da semana
- "tm_yday" - Dia do ano
- "tm_isdst" - Se está em horário de verão
Erros
Toda a chamada a uma função de data/hora irá gerar um se a zona da hora não for valida, e/ou uma mensagem E_STRICT ou E_WARNING se estiver usando a definição do sistema ou a variável de ambiente TZ. Veja também date_default_timezone_set()
Histórico
| Versão | Descrição |
|---|---|
| 5.1.0 | Agora emite E_STRICT e E_NOTICE em erros da zona de horário. |
Exemplos
Exemplo #1 Exemplo da localtime()
<?php
$localtime = localtime();
$localtime_assoc = localtime(time(), true);
print_r($localtime);
print_r($localtime_assoc);
?>
O exemplo acima irá imprimir algo similar a:
Array
(
[0] => 24
[1] => 3
[2] => 19
[3] => 3
[4] => 3
[5] => 105
[6] => 0
[7] => 92
[8] => 1
)
Array
(
[tm_sec] => 24
[tm_min] => 3
[tm_hour] => 19
[tm_mday] => 3
[tm_mon] => 3
[tm_year] => 105
[tm_wday] => 0
[tm_yday] => 92
[tm_isdst] => 1
)
microtime
(PHP 4, PHP 5)
microtime — Retorna um timestamp Unix com microsegundos
Descrição
A microtime() retorna o timestamp atual com microsegundos. Esta função está apenas disponível em sistemas operacionais que suportam o chamda do sistema gettimeofday().
Parâmetros
- get_as_float
-
Quando chamada sem o argumento opcional, esta função retorna a string "msec sec" onde sec é o a hora atual medida em segundos desde a era UNIX (0:00:00 January 1, 1970 GMT), e msec é a parte em microsegundos. Ambas porções de string são retornadas em segundos.
Se o opcional get_as_float é definido para TRUE então um float (em segundos) é retornado.
Histórico
| Versão | Descrição |
|---|---|
| 5.0.0 | O parâmetro get_as_float foi adicionado. |
Exemplos
Exemplo #1 Cronometrando a execução do script com microtime()
<?php
/**
* Simple function to replicate PHP 5 behaviour
*/
function microtime_float()
{
list($usec, $sec) = explode(" ", microtime());
return ((float)$usec + (float)$sec);
}
$time_start = microtime_float();
// Sleep for a while
usleep(100);
$time_end = microtime_float();
$time = $time_end - $time_start;
echo "Did nothing in $time seconds\n";
?>
Exemplo #2 Timing script execution in PHP 5
<?php
$time_start = microtime(true);
// Sleep for a while
usleep(100);
$time_end = microtime(true);
$time = $time_end - $time_start;
echo "Did nothing in $time seconds\n";
?>
mktime
(PHP 4, PHP 5)
mktime — Obtém um timestamp Unix para uma data
Descrição
Retorna o timestamp Unix correspondente para os argumentos dados. Este timestamp é um longo inteiro contendo o número de segundos entre a Era Unix (January 1 1970 00:00:00 GMT) e o tempo especificado.
Argumentos podem ser omitidos da direita para esquerda; quaisquer argumentos assim omitidos serão definidos para o valor atual de acordo com a data e a hora local.
Parâmetros
- hour
-
O número da hora.
- minute
-
O número do minuto.
- second
-
O número de segundos passados do minuto.
- month
-
O número do mês.
- day
-
O número do dia.
- year
-
O número do ano. Pode conter dois ou quatro dígitos, com os valores entre 0-69 significando 2000-2069 e 70-100 para 1970-2000. Em sistemas aonde o time_t é um inteiro assinado de 32 bit, como é mais comum, o alcance do ano é algo entre 1901 e 2038. Entretanto, antes do PHP 5.1.0 esse range era limitado para 1970 até 2038 em alguns sistemas (ex. Windows).
- is_dst
-
Este parâmetro pode ser definido para 1 se está durante o horário de verão (DST), 0 se não está, ou -1 (o padrão) se é desconhecido se o tempo está dentro do horário de verão ou não. Se é desconhecido, o PHP tenta compreender por si mesmo. Isto pode causar inesperado (mas não incorreto) resultados. As vezes é inválido se DST é habilitado no sistema em que o PHP está executando ou is_dst é definido para 1. Se DST é habilitado em e.g. 2:00, todo tempo entre 2:00 e 3:00 são inválidos e mktime() retorna um indefinido (normalmente negativo) valor. Alguns sistemas (e.g. Solaris 8) habilita DST na meia-noite então tempo 0:30 do dia quando DST está habilitado é avaliado como 23:30 do dia anterior.
Nota:
No PHP 5.1.0, este parâmetro tornou-se obsoleto. Como resultado, o o novo recurso de manuseamento de timezone deve ser usado ao invés dele.
Valor Retornado
mktime() retorna o Unix timestamp dos argumentos dado. Se os argumentos são inválidos, a função retorna FALSE (antes do PHP 5.1 retornava -1).
Erros
Toda a chamada a uma função de data/hora irá gerar um se a zona da hora não for valida, e/ou uma mensagem E_STRICT ou E_WARNING se estiver usando a definição do sistema ou a variável de ambiente TZ. Veja também date_default_timezone_set()
Histórico
| Versão | Descrição |
|---|---|
| 3.0.10 | Adicionado o parâmetrois_dst |
| 5.1.0 | O parâmetro is_dst tornou-se obsoleto. Fazendo a função retornar FALSE em erro, ao invés de -1. Reparada a função para aceitar o ano, mês e dia para ser todos passados como zero. |
| 5.1.0 | Agora emite E_STRICT e E_NOTICE em erros da zona de horário. |
Exemplos
Exemplo #1 Exemplo da mktime()
mktime() é útil durante a aritmética e validação de data, enquanto ela calculará automaticamente o valor correto para a entrada fora do intervalo. Por exemplo, cada uma das seguintes linhas produzirá a string "Jan-01-1998".
<?php
echo date("M-d-Y", mktime(0, 0, 0, 12, 32, 1997));
echo date("M-d-Y", mktime(0, 0, 0, 13, 1, 1997));
echo date("M-d-Y", mktime(0, 0, 0, 1, 1, 1998));
echo date("M-d-Y", mktime(0, 0, 0, 1, 1, 98));
?>
Exemplo #2 Último dia do próximo mês
O último dia de um mês dado pode ser expressado como o dia "0" do mês seguinte, não o dia -1. Os dois exemplos seguintes produzirão a string "The last day in Feb 2000 is: 29".
<?php
$lastday = mktime (0,0,0,3,0,2000);
echo strftime ("Last day in Feb 2000 is: %d", $lastday);
$lastday = mktime (0,0,0,4,-31,2000);
echo strftime ("Last day in Feb 2000 is: %d", $lastday);
?>
Notas
Antes do PHP 5.1.0, timestamp negativos não eram suportados em nenhuma versão conhecida do Windows e em alguns outros sistemas também. Portanto o intervalo válido de anos foi limitado para 1970 até 2038.
Veja Também
- gmmktime() - Obtém um timestamp Unix para uma data GMT
- date() - Formata a data e a hora local
- time() - Retorna o timestamp Unix atual
strftime
(PHP 4, PHP 5)
strftime — Formata uma hora/data de acordo com as configurações locais
Descrição
Formata uma hora/data local de acordo com o configuração de locale. Nome do mês e dia da semana e outras strings dependem do atual local definido com setlocale().
Note que todas as conversões especificadas podem ser suportadas pela sua biblioteca C, em alguns casos elas não serão suportadas pelo PHP strftime(). Além disso, nem todas as plataformas suportam timestamps negativos, então sua faixa de datas não pode ser limitada mais cedo do que a época Unix. Isto significa e.g. %e, %T, %R e %D (e outras mais) e datas anteriores a Jan 1, 1970 não funcionarão em Windows, algumas distribuições Linux, e alguns outros sistemas operacionais. Para sistemas Windows um resumo completo dos especificadores de conversão suportados podem ser encontrados neste website » MSDN .
Parâmetros
- format
-
As seguintes conversões especificadoras são conhecidas no formato de string:
- %a - dia da semana abreviado de acordo com a localidade
- %A - nome da semana completo de acordo com a localidade
- %b - nome do mês abreviado de acordo com a localidade
- %B - nome do mês completo de acordo com a localidade
- %c - representação da data e hora preferida pela a localidade
- %C - número do século (o ano dividido por 100 e truncado para um inteiro, de 00 até 99)
- %d - dia do mês como um número decimal (de 01 até 31)
- %D - mesmo que %m/%d/%y
- %e - dia do mês como um número decimal, um simples dígito é precedido por espaço (de ' 1' até '31')
- %g - como %G, mas sem o século.
- %G - o 4-dígito do ano correspodendo as ISO week number (see %V). Este tem o mesmo formato e valor que %Y, exceto que se o ISO week number pertence ao prévio ou próximo ano, aquele ano é usado ao invés deste.
- %h - mesmo que %b
- %H - hora como um número decimal usando um relógio de 24-horas (de 00 até 23)
- %I - hora como um número decimal usando um relógio de 12-hoas (de 01 até 12)
- %j - dia do ano como número decimal (de 001 até 366)
- %m - mês como número decimal (de 01 até 12)
- %M - minuto como número decimal
- %n - caracter novalinha
- %p - um dos dois `am' ou `pm' de acordo com o valor da hora dada, ou as strings correspondentes para a localidade
- %r - hora em a.m. e p.m. notação
- %R - hora em notação de 24 horas
- %S - segundo como um número decimal
- %t - caracter tab
- %T - hora corrente, igual a %H:%M:%S
-
%u - dia da semana como número decimal [1,7], com 1 representando
Segunda-feira
Aviso
Sun Solaris parece iniciar o Domingo como 1 embora ISO 9889:1999 (o padrão C corrente) claramente especificados que ele poderia ser segunda-feira.
- %U - dia da semana do ano corrente como número decimal, começando com o primeiro domingo como o primeiro dia da primeira semana
- %V - O número da semana corrente ISO 8601:1988 do ano corrente como um número decimal, de 01 até 53, onde semana 1 é a primeira semana que tem pelo menos 4 dias no ano corrente, e com segunda-feira como o primeiro dia da semana. (Use %G ou %g para o componente anual que corresponde ao dia da semana para o para o timestamp especificado.)
- %W - dia da semana do ano corrente como número decimal, começando com o a segunda-feira como o primeiro dia da primera semana
- %w - dia da semana como número decimal, domingo sendo 0
- %x - representação preferida para a data para a localidade corrente sem a hora
- %X - representação preferida para a hora para a localidade corrente sem a data
- %y - ano como número decimal sem o século (de 00 até 99)
- %Y - ano como número decimal incluindo o século
- %Z ou %z - time zone, nome ou abreviação (dependendo do sistema operacional)
- %% - a literal `%' character
Tamanho máximo deste parâmetro é 1023 caracteres.
- timestamp
-
O parâmetro opcional timestamp é um integer Unix timestamp cujo padrão é a hora local se timestamp não for dado. Em outras palavras, o padrão é o valor de time().
Valor Retornado
Retorna uma string formatada de acordo com o formato dado em timestamp ou o horário corrente se nenhum timestamp é dado. Nomes de mês e dia da semana e outras strings dependentes de linguagens respeitam o atual locale definido com setlocale().
Erros
Toda a chamada a uma função de data/hora irá gerar um se a zona da hora não for valida, e/ou uma mensagem E_STRICT ou E_WARNING se estiver usando a definição do sistema ou a variável de ambiente TZ. Veja também date_default_timezone_set()
Histórico
| Versão | Descrição |
|---|---|
| 5.1.0 | Agora emite E_STRICT e E_NOTICE em erros da zona de horário. |
Exemplos
Este exemplo funciona se você tem os respectivos locales instalados em seu sistema.
Exemplo #1 strftime() exemplos locais
<?php
setlocale(LC_TIME, "C");
echo strftime("%A");
setlocale(LC_TIME, "fi_FI");
echo strftime(" in Finnish is %A,");
setlocale(LC_TIME, "fr_FR");
echo strftime(" in French %A and");
setlocale(LC_TIME, "de_DE");
echo strftime(" in German %A.\n");
?>
Exemplo #2 Exemplo de número de semana ISO 8601:1988
<?php
/* December 2002 / January 2003
ISOWk M Tu W Thu F Sa Su
----- ----------------------------
51 16 17 18 19 20 21 22
52 23 24 25 26 27 28 29
1 30 31 1 2 3 4 5
2 6 7 8 9 10 11 12
3 13 14 15 16 17 18 19 */
// Outputs: 12/28/2002 - %V,%G,%Y = 52,2002,2002
echo "12/28/2002 - %V,%G,%Y = " . strftime("%V,%G,%Y", strtotime("12/28/2002")) . "\n";
// Outputs: 12/30/2002 - %V,%G,%Y = 1,2003,2002
echo "12/30/2002 - %V,%G,%Y = " . strftime("%V,%G,%Y", strtotime("12/30/2002")) . "\n";
// Outputs: 1/3/2003 - %V,%G,%Y = 1,2003,2003
echo "1/3/2003 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/3/2003")) . "\n";
// Outputs: 1/10/2003 - %V,%G,%Y = 2,2003,2003
echo "1/10/2003 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/10/2003")) . "\n";
/* December 2004 / January 2005
ISOWk M Tu W Thu F Sa Su
----- ----------------------------
51 13 14 15 16 17 18 19
52 20 21 22 23 24 25 26
53 27 28 29 30 31 1 2
1 3 4 5 6 7 8 9
2 10 11 12 13 14 15 16 */
// Outputs: 12/23/2004 - %V,%G,%Y = 52,2004,2004
echo "12/23/2004 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("12/23/2004")) . "\n";
// Outputs: 12/31/2004 - %V,%G,%Y = 53,2004,2004
echo "12/31/2004 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("12/31/2004")) . "\n";
// Outputs: 1/2/2005 - %V,%G,%Y = 53,2004,2005
echo "1/2/2005 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/2/2005")) . "\n";
// Outputs: 1/3/2005 - %V,%G,%Y = 1,2005,2005
echo "1/3/2005 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/3/2005")) . "\n";
?>
Notas
Nota: %G e %V, que são baseadas nos números de semana no ISO 8601:1988 pode ser dado resultados inesperados (embora corretos) se o sistema numérico não é perfeitamente entendido. Veja exemplos da %V nesta página do manual.
Veja Também
- setlocale() - Define informações locais
- mktime() - Obtém um timestamp Unix para uma data
- strptime() - Parse a time/date generated with strftime
- gmstrftime() - Formata uma hora/data GMT/CUT de acordo com as configurações locais
- » Especificação Open Group da strftime()
Descrição
strptime() returns an array with the date parsed, or FALSE on error.
Month and weekday names and other language dependent strings respect the current locale set with setlocale() (LC_TIME).
Parâmetros
- date (string)
-
The string to parse (e.g. returned from strftime()).
- format (string)
-
The format used in date (e.g. the same as used in strftime()). Note that some of the format options available to strftime() may not have any effect within strptime(); the exact subset that are supported will vary based on the operating system and C library in use.
For more information about the format options, read the strftime() page.
Valor Retornado
Returns an array or FALSE on failure.
| parameters | Description |
|---|---|
| "tm_sec" | Seconds after the minute (0-61) |
| "tm_min" | Minutes after the hour (0-59) |
| "tm_hour" | Hour since midnight (0-23) |
| "tm_mday" | Day of the month (1-31) |
| "tm_mon" | Months since January (0-11) |
| "tm_year" | Years since 1900 |
| "tm_wday" | Days since Sunday (0-6) |
| "tm_yday" | Days since January 1 (0-365) |
| "unparsed" | the date part which was not recognized using the specified format |
Exemplos
Exemplo #1 strptime() example
<?php
$format = '%d/%m/%Y %H:%M:%S';
$strf = strftime($format);
echo "$strf\n";
print_r(strptime($strf, $format));
?>
O exemplo acima irá imprimir algo similar a:
03/10/2004 15:54:19
Array
(
[tm_sec] => 19
[tm_min] => 54
[tm_hour] => 15
[tm_mday] => 3
[tm_mon] => 9
[tm_year] => 104
[tm_wday] => 0
[tm_yday] => 276
[unparsed] =>
)
Notas
Nota: esta função não é implementada na plataforma Windows
Nota:
Internally, this function calls the strptime() function provided by the system's C library. This function can exhibit noticeably different behaviour across different operating systems. The use of date_parse_from_format(), which does not suffer from these issues, is recommended on PHP 5.3.0 and later.
Nota:
"tm_sec" includes any leap seconds (currently upto 2 a year). For more information on leap seconds, see the » Wikipedia article on leap seconds.
Nota:
Prior to PHP 5.2.0, this function could return undefined behaviour. Notably, the "tm_sec", "tm_min" and "tm_hour" entries would return undefined values.
Veja Também
- checkdate() - Valida uma data Gregoriana
- strftime() - Formata uma hora/data de acordo com as configurações locais
- date_parse_from_format() - Get info about given date formatted according to the specified format
- DateTime::createFromFormat()
strtotime
(PHP 4, PHP 5)
strtotime — Analisa qualquer descrição em texto em inglês de data hora em timestamp Unix
Descrição
A função espera que seja dado uma string contendo um formato de data em inglês US e tentará analisar esse formato dentro de um timestamp Unix (o número de segundos desde January 1 1970 00:00:00 GMT), relativo ao timestamp dado em now, ou a hora atual se now não é fornecido.
Esta função usará a variável de ambiente TZ (se disponível) para calcular o timestamp. Desde o PHP 5.1.0 há forma fácil para definir o timezone que é usada em todas as funções de data/hora. Este processo é explicado na página da função date_default_timezone_get().
Nota:
Se o número do ano é especificado no formato de dois dígitos, o valor entre 00-69 é mapeado para 2000-2069 e 70-99 para 1970-1999.
Parâmetros
- time
-
A string para analisar, de acordo com a sintaxe GNU de » Formato de Entrada de Data. Antes do PHP 5.0.0, microsegundos não eram permitidos na hora, desde o PHP 5.0.0 eles são permitidos mas ignorados.
- now
-
O timestamp usado para calcular o valor retornado.
Valor Retornado
Retorna um timestamp em sucesso, FALSE caso contrário. Antes do PHP 5.1.0, esta função podia retornar -1 em falha.
Erros
Toda a chamada a uma função de data/hora irá gerar um se a zona da hora não for valida, e/ou uma mensagem E_STRICT ou E_WARNING se estiver usando a definição do sistema ou a variável de ambiente TZ. Veja também date_default_timezone_set()
Histórico
| Versão | Descrição |
|---|---|
| 5.1.0 | Ela agora retorna FALSE em falha, ao invés de -1. |
| 5.1.0 | Agora emite E_STRICT e E_NOTICE em erros da zona de horário. |
Exemplos
Exemplo #1 Exemplo da strtotime()
<?php
echo strtotime("now"), "\n";
echo strtotime("10 September 2000"), "\n";
echo strtotime("+1 day"), "\n";
echo strtotime("+1 week"), "\n";
echo strtotime("+1 week 2 days 4 hours 2 seconds"), "\n";
echo strtotime("next Thursday"), "\n";
echo strtotime("last Monday"), "\n";
?>
Exemplo #2 Checando por falha
<?php
$str = 'Not Good';
// em versões antes do PHP 5.1.0 você compararia com -1, ao invés de false
if (($timestamp = strtotime($str)) === false) {
echo "The string ($str) is bogus";
} else {
echo "$str == " . date('l dS \o\f F Y h:i:s A', $timestamp);
}
?>
Notas
Em PHP 5 superior a 5.0.2, "now" e outros tempo relativos são erradamente computados para meia-noite do dia. Diferente de outras versões onde ele é corretamente computado da hora atual.
Nas versões do PHP menor que 4.4.0, "next" é incorretamente computado como +2. Uma solução típica para isso é usar "+1".
Nota:
O intervalo válido de um timestamp é tipicamente de Fri, 13 Dec 1901 20:45:54 GMT até Tue, 19 Jan 2038 03:14:07 GMT. (Estas são datas que correspondem aos valores máximos e mínimos para um inteiro assinado de 32-bit.) Adicionalmente, nem todas as plataformas suportam timestamps negativos, então a faixa de sua data pode ser limitada antes de chegar na Era Unix. Isto significa que ex. datas antes de Jan 1, 1970 não trabalharão no Windows, nem em algumas distribuições do Linux, e num grupo de outros sistemas operacionais. PHP 5.1.0 e mais recentes versões superaram esta limitação, no entanto.
time
(PHP 4, PHP 5)
time — Retorna o timestamp Unix atual
Descrição
Retorna a hora atual medida no número de segundos desde a Era Unix (January 1 1970 00:00:00 GMT).
Exemplos
Exemplo #1 time() example
<?php
$nextWeek = time() + (7 * 24 * 60 * 60);
// 7 days; 24 hours; 60 mins; 60secs
echo 'Now: '. date('Y-m-d') ."\n";
echo 'Next Week: '. date('Y-m-d', $nextWeek) ."\n";
// or using strtotime():
echo 'Next Week: '. date('Y-m-d', strtotime('+1 week')) ."\n";
?>
O exemplo acima irá imprimir algo similar a:
Now: 2005-03-30 Next Week: 2005-04-06 Next Week: 2005-04-06
Notas
Timestamp do início da requisição está disponível na $_SERVER['REQUEST_TIME'] desde o PHP 5.1.
Veja Também
- date() - Formata a data e a hora local
- microtime() - Retorna um timestamp Unix com microsegundos
timezone_abbreviations_list
(PHP 5 >= 5.2.0)
timezone_abbreviations_list — Sinônimo de DateTimeZone::listAbbreviations()
Descrição
Esta função é um apelido para: DateTimeZone::listAbbreviations()
timezone_identifiers_list
(PHP 5 >= 5.2.0)
timezone_identifiers_list — Sinônimo de DateTimeZone::listIdentifiers()
Descrição
Esta função é um apelido para: DateTimeZone::listIdentifiers()
timezone_location_get
(PHP 5 >= 5.3.0)
timezone_location_get — Sinônimo de DateTimeZone::getLocation()
Descrição
Esta função é um apelido para: DateTimeZone::getLocation()
timezone_name_from_abbr
(PHP 5 >= 5.1.3)
timezone_name_from_abbr — Returns the timezone name from abbreviation
Descrição
Parâmetros
- abbr
-
Time zone abbreviation.
- gmtOffset
-
Offset from GMT in seconds. Defaults to -1 which means that first found time zone corresponding to abbr is returned. Otherwise exact offset is searched and only if not found then the first time zone with any offset is returned.
- isdst
-
Daylight saving time indicator. Defaults to -1, which means that whether the time zone has daylight saving or not is not taken into consideration when searching. If this is set to 1, then the gmtOffset is assumed to be an offset with daylight saving in effect; if 0, then gmtOffset is assumed to be an offset without daylight saving in effect. If abbr doesn't exist then the time zone is searched solely by the gmtOffset and isdst.
Valor Retornado
Returns time zone name on success or FALSE on failure.
Exemplos
Exemplo #1 A timezone_name_from_abbr() example
<?php
echo timezone_name_from_abbr("CET") . "\n";
echo timezone_name_from_abbr("", 3600, 0) . "\n";
?>
O exemplo acima irá imprimir algo similar a:
Europe/Berlin Europe/Paris
timezone_name_get
(PHP 5 >= 5.2.0)
timezone_name_get — Sinônimo de DateTimeZone::getName()
Descrição
Esta função é um apelido para: DateTimeZone::getName()
timezone_offset_get
(PHP 5 >= 5.2.0)
timezone_offset_get — Sinônimo de DateTimeZone::getOffset()
Descrição
Esta função é um apelido para: DateTimeZone::getOffset()
timezone_open
(PHP 5 >= 5.2.0)
timezone_open — Retorna um novo objeto DateTimeZone
Descrição
Esta função é um apelido para: DateTimeZone::__construct()
timezone_transitions_get
(PHP 5 >= 5.2.0)
timezone_transitions_get — Sinônimo de DateTimeZone::getTransitions()
Descrição
Esta função é um apelido para: DateTimeZone::getTransitions()
timezone_version_get
(PHP 5 >= 5.3.0)
timezone_version_get — Gets the version of the timezonedb
Descrição
Returns the current version of the timezonedb.
Valor Retornado
Returns a string.
Exemplos
Exemplo #1 Getting the timezonedb version
<?php
echo timezone_version_get();
?>
O exemplo acima irá imprimir algo similar a:
2009.7
Índice
- checkdate — Valida uma data Gregoriana
- date_add — Sinônimo de DateTime::add
- date_create_from_format — Sinônimo de DateTime::createFromFormat
- date_create — Retorna um novo objeto DateTime
- date_date_set — Define a data
- date_default_timezone_get — Retorna a timezone (zona de tempo) padrão usada por todas as funções de data e tempo em um script
- date_default_timezone_set — Configura a timezone padrão a ser utilizada por todas as funções de data e hora em um script
- date_diff — Sinônimo de DateTime::diff
- date_format — Retorna a data formatada de acordo com o formato dado
- date_get_last_errors — Sinônimo de DateTime::getLastErrors
- date_interval_create_from_date_string — Sinônimo de DateInterval::createFromDateString
- date_interval_format — Sinônimo de DateInterval::format
- date_isodate_set — Define a data ISO
- date_modify — Altera o timestamp
- date_offset_get — Sinônimo de DateTime::getOffset
- date_parse_from_format — Get info about given date formatted according to the specified format
- date_parse — Retorna um array associativo com detalhes sobre uma dada data
- date_sub — Sinônimo de DateTime::sub
- date_sun_info — Retorna um array com informações sobre pôr-do-sol/nascer-do-sol e o início/fim do dia
- date_sunrise — Returns time of sunrise for a given day and location
- date_sunset — Returns time of sunset for a given day and location
- date_time_set — Define o tempo
- date_timestamp_get — Sinônimo de DateTime::getTimestamp
- date_timestamp_set — Sinônimo de DateTime::setTimestamp
- date_timezone_get — Sinônimo de DateTime::getTimezone
- date_timezone_set — Sinônimo de DateTime::setTimezone
- date — Formata a data e a hora local
- getdate — Consegue informações data/hora
- gettimeofday — Obtém a hora local
- gmdate — Formata uma data/hora GMT/CUT
- gmmktime — Obtém um timestamp Unix para uma data GMT
- gmstrftime — Formata uma hora/data GMT/CUT de acordo com as configurações locais
- idate — Format a local time/date as integer
- localtime — Obtém a hora local
- microtime — Retorna um timestamp Unix com microsegundos
- mktime — Obtém um timestamp Unix para uma data
- strftime — Formata uma hora/data de acordo com as configurações locais
- strptime — Parse a time/date generated with strftime
- strtotime — Analisa qualquer descrição em texto em inglês de data hora em timestamp Unix
- time — Retorna o timestamp Unix atual
- timezone_abbreviations_list — Sinônimo de DateTimeZone::listAbbreviations
- timezone_identifiers_list — Sinônimo de DateTimeZone::listIdentifiers
- timezone_location_get — Sinônimo de DateTimeZone::getLocation
- timezone_name_from_abbr — Returns the timezone name from abbreviation
- timezone_name_get — Sinônimo de DateTimeZone::getName
- timezone_offset_get — Sinônimo de DateTimeZone::getOffset
- timezone_open — Retorna um novo objeto DateTimeZone
- timezone_transitions_get — Sinônimo de DateTimeZone::getTransitions
- timezone_version_get — Gets the version of the timezonedb
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Lista de Timezones Suportados
- Funções de Data/Hora
- checkdate — Valida uma data Gregoriana
- date_add — Sinônimo de DateTime::add
- date_create_from_format — Sinônimo de DateTime::createFromFormat
- date_create — Retorna um novo objeto DateTime
- date_date_set — Define a data
- date_default_timezone_get — Retorna a timezone (zona de tempo) padrão usada por todas as funções de data e tempo em um script
- date_default_timezone_set — Configura a timezone padrão a ser utilizada por todas as funções de data e hora em um script
- date_diff — Sinônimo de DateTime::diff
- date_format — Retorna a data formatada de acordo com o formato dado
- date_get_last_errors — Sinônimo de DateTime::getLastErrors
- date_interval_create_from_date_string — Sinônimo de DateInterval::createFromDateString
- date_interval_format — Sinônimo de DateInterval::format
- date_isodate_set — Define a data ISO
- date_modify — Altera o timestamp
- date_offset_get — Sinônimo de DateTime::getOffset
- date_parse_from_format — Get info about given date formatted according to the specified format
- date_parse — Retorna um array associativo com detalhes sobre uma dada data
- date_sub — Sinônimo de DateTime::sub
- date_sun_info — Retorna um array com informações sobre pôr-do-sol/nascer-do-sol e o início/fim do dia
- date_sunrise — Returns time of sunrise for a given day and location
- date_sunset — Returns time of sunset for a given day and location
- date_time_set — Define o tempo
- date_timestamp_get — Sinônimo de DateTime::getTimestamp
- date_timestamp_set — Sinônimo de DateTime::setTimestamp
- date_timezone_get — Sinônimo de DateTime::getTimezone
- date_timezone_set — Sinônimo de DateTime::setTimezone
- date — Formata a data e a hora local
- getdate — Consegue informações data/hora
- gettimeofday — Obtém a hora local
- gmdate — Formata uma data/hora GMT/CUT
- gmmktime — Obtém um timestamp Unix para uma data GMT
- gmstrftime — Formata uma hora/data GMT/CUT de acordo com as configurações locais
- idate — Format a local time/date as integer
- localtime — Obtém a hora local
- microtime — Retorna um timestamp Unix com microsegundos
- mktime — Obtém um timestamp Unix para uma data
- strftime — Formata uma hora/data de acordo com as configurações locais
- strptime — Parse a time/date generated with strftime
- strtotime — Analisa qualquer descrição em texto em inglês de data hora em timestamp Unix
- time — Retorna o timestamp Unix atual
- timezone_abbreviations_list — Sinônimo de DateTimeZone::listAbbreviations
- timezone_identifiers_list — Sinônimo de DateTimeZone::listIdentifiers
- timezone_location_get — Sinônimo de DateTimeZone::getLocation
- timezone_name_from_abbr — Returns the timezone name from abbreviation
- timezone_name_get — Sinônimo de DateTimeZone::getName
- timezone_offset_get — Sinônimo de DateTimeZone::getOffset
- timezone_open — Retorna um novo objeto DateTimeZone
- timezone_transitions_get — Sinônimo de DateTimeZone::getTransitions
- timezone_version_get — Gets the version of the timezonedb
Extensões Específica para Linha de Comando
Ncurses Terminal Screen Control
Introdução
ncurses (new curses) is a free software emulation of curses in System V Rel 4.0 (and above). It uses terminfo format, supports pads, colors, multiple highlights, form characters and function key mapping. Because of the interactive nature of this library, it will be of little use for writing Web applications, but may be useful when writing scripts meant using PHP from the command line.
The features available, such as colors, depend on the terminal that you are using. Use functions such as ncurses_has_colors(), ncurses_can_change_color(), and ncurses_has_ic() to check for individual capabilities.
Nota:
Esta extensão foi movida para o repositório » PECL e não é mais distribuida em conjunto com o PHP a partir do PHP 5.3.0.
ncurses is available for the following platforms:
- AIX
- BeOS
- BSD variants (FreeBSD, NetBSD, OpenBSD)
- Cygwin
- Digital Unix (aka OSF1)
- GNU/Linux
- HPUX
- IRIX64
- Mac OS X
- OS/2
- QNX
- SCO OpenServer
- Solaris
- Tru64
Instalação/Configuração
Índice
Dependências
You need the ncurses libraries and headerfiles. Download the latest version from the » ftp://ftp.gnu.org/pub/gnu/ncurses/ or from an other GNU-Mirror.
Instalação
Informações para a instalação desta extensão PECL podem ser encontradas no manual no capitulo intitulado Instalação de extensões PECL. Informações adicionais como novas versões, downloads, arquivos fontes, manutenções, e um Changelog, podem ser obtidos aqui: » http://pecl.php.net/package/ncurses.
Wide character CRT screen handling (ncursesw) support was added in version 1.0.1 of this PECL extension.
Configurações em Execução
Esta extensão não define nenhum parâmetro de configuração no php.ini.
Tipos Resource
This extension defines window, panel and pad resources.
Constantes pré-definidas
Índice
As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.
Error codes
On error ncurses functions return -1. Some functions return 0 on success. See the relevant pages in the documentation for actual return values.
Colors
| constant | meaning |
|---|---|
| NCURSES_COLOR_BLACK | no color (black) |
| NCURSES_COLOR_WHITE | white |
| NCURSES_COLOR_RED | red - supported when terminal is in color mode |
| NCURSES_COLOR_GREEN | green - supported when terminal is in color mode |
| NCURSES_COLOR_YELLOW | yellow - supported when terminal is in color mode |
| NCURSES_COLOR_BLUE | blue - supported when terminal is in color mode |
| NCURSES_COLOR_CYAN | cyan - supported when terminal is in color mode |
| NCURSES_COLOR_MAGENTA | magenta - supported when terminal is in color mode |
Keys
| constant | meaning |
|---|---|
| NCURSES_KEY_F0 - NCURSES_KEY_F64 | function keys F1 - F64 |
| NCURSES_KEY_DOWN | down arrow |
| NCURSES_KEY_UP | up arrow |
| NCURSES_KEY_LEFT | left arrow |
| NCURSES_KEY_RIGHT | right arrow |
| NCURSES_KEY_HOME | home key (upward+left arrow) |
| NCURSES_KEY_BACKSPACE | backspace |
| NCURSES_KEY_DL | delete line |
| NCURSES_KEY_IL | insert line |
| NCURSES_KEY_DC | delete character |
| NCURSES_KEY_IC | insert char or enter insert mode |
| NCURSES_KEY_EIC | exit insert char mode |
| NCURSES_KEY_CLEAR | clear screen |
| NCURSES_KEY_EOS | clear to end of screen |
| NCURSES_KEY_EOL | clear to end of line |
| NCURSES_KEY_SF | scroll one line forward |
| NCURSES_KEY_SR | scroll one line backward |
| NCURSES_KEY_NPAGE | next page |
| NCURSES_KEY_PPAGE | previous page |
| NCURSES_KEY_STAB | set tab |
| NCURSES_KEY_CTAB | clear tab |
| NCURSES_KEY_CATAB | clear all tabs |
| NCURSES_KEY_SRESET | soft (partial) reset |
| NCURSES_KEY_RESET | reset or hard reset |
| NCURSES_KEY_PRINT | |
| NCURSES_KEY_LL | lower left |
| NCURSES_KEY_A1 | upper left of keypad |
| NCURSES_KEY_A3 | upper right of keypad |
| NCURSES_KEY_B2 | center of keypad |
| NCURSES_KEY_C1 | lower left of keypad |
| NCURSES_KEY_C3 | lower right of keypad |
| NCURSES_KEY_BTAB | back tab |
| NCURSES_KEY_BEG | beginning |
| NCURSES_KEY_CANCEL | cancel |
| NCURSES_KEY_CLOSE | close |
| NCURSES_KEY_COMMAND | cmd (command) |
| NCURSES_KEY_COPY | copy |
| NCURSES_KEY_CREATE | create |
| NCURSES_KEY_END | end |
| NCURSES_KEY_EXIT | exit |
| NCURSES_KEY_FIND | find |
| NCURSES_KEY_HELP | help |
| NCURSES_KEY_MARK | mark |
| NCURSES_KEY_MESSAGE | message |
| NCURSES_KEY_MOVE | move |
| NCURSES_KEY_NEXT | next |
| NCURSES_KEY_OPEN | open |
| NCURSES_KEY_OPTIONS | options |
| NCURSES_KEY_PREVIOUS | previous |
| NCURSES_KEY_REDO | redo |
| NCURSES_KEY_REFERENCE | ref (reference) |
| NCURSES_KEY_REFRESH | refresh |
| NCURSES_KEY_REPLACE | replace |
| NCURSES_KEY_RESTART | restart |
| NCURSES_KEY_RESUME | resume |
| NCURSES_KEY_SAVE | save |
| NCURSES_KEY_SBEG | shiftet beg (beginning) |
| NCURSES_KEY_SCANCEL | shifted cancel |
| NCURSES_KEY_SCOMMAND | shifted command |
| NCURSES_KEY_SCOPY | shifted copy |
| NCURSES_KEY_SCREATE | shifted create |
| NCURSES_KEY_SDC | shifted delete char |
| NCURSES_KEY_SDL | shifted delete line |
| NCURSES_KEY_SELECT | select |
| NCURSES_KEY_SEND | shifted end |
| NCURSES_KEY_SEOL | shifted end of line |
| NCURSES_KEY_SEXIT | shifted exit |
| NCURSES_KEY_SFIND | shifted find |
| NCURSES_KEY_SHELP | shifted help |
| NCURSES_KEY_SHOME | shifted home |
| NCURSES_KEY_SIC | shifted input |
| NCURSES_KEY_SLEFT | shifted left arrow |
| NCURSES_KEY_SMESSAGE | shifted message |
| NCURSES_KEY_SMOVE | shifted move |
| NCURSES_KEY_SNEXT | shifted next |
| NCURSES_KEY_SOPTIONS | shifted options |
| NCURSES_KEY_SPREVIOUS | shifted previous |
| NCURSES_KEY_SPRINT | shifted print |
| NCURSES_KEY_SREDO | shifted redo |
| NCURSES_KEY_SREPLACE | shifted replace |
| NCURSES_KEY_SRIGHT | shifted right arrow |
| NCURSES_KEY_SRSUME | shifted resume |
| NCURSES_KEY_SSAVE | shifted save |
| NCURSES_KEY_SSUSPEND | shifted suspend |
| NCURSES_KEY_UNDO | undo |
| NCURSES_KEY_MOUSE | mouse event has occurred |
| NCURSES_KEY_MAX | maximum key value |
Mouse
| Constant | meaning |
|---|---|
| NCURSES_BUTTON1_RELEASED - NCURSES_BUTTON4_RELEASED | button (1-4) released |
| NCURSES_BUTTON1_PRESSED - NCURSES_BUTTON4_PRESSED | button (1-4) pressed |
| NCURSES_BUTTON1_CLICKED - NCURSES_BUTTON4_CLICKED | button (1-4) clicked |
| NCURSES_BUTTON1_DOUBLE_CLICKED - NCURSES_BUTTON4_DOUBLE_CLICKED | button (1-4) double clicked |
| NCURSES_BUTTON1_TRIPLE_CLICKED - NCURSES_BUTTON4_TRIPLE_CLICKED | button (1-4) triple clicked |
| NCURSES_BUTTON_CTRL | ctrl pressed during click |
| NCURSES_BUTTON_SHIFT | shift pressed during click |
| NCURSES_BUTTON_ALT | alt pressed during click |
| NCURSES_ALL_MOUSE_EVENTS | report all mouse events |
| NCURSES_REPORT_MOUSE_POSITION | report mouse position |
Ncurses Funções
ncurses_addch
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_addch — Add character at current position and advance cursor
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- ch
-
ncurses_addchnstr
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_addchnstr — Add attributed string with specified length at current position
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- s
-
- n
-
ncurses_addchstr
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_addchstr — Add attributed string at current position
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- s
-
ncurses_addnstr
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_addnstr — Add string with specified length at current position
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- s
-
- n
-
ncurses_addstr
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_addstr — Output text at current position
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- text
-
ncurses_assume_default_colors
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_assume_default_colors — Define default colors for color 0
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- fg
-
- bg
-
ncurses_attroff
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_attroff — Turn off the given attributes
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- attributes
-
ncurses_attron
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_attron — Turn on the given attributes
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- attributes
-
ncurses_attrset
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_attrset — Set given attributes
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- attributes
-
ncurses_baudrate
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_baudrate — Returns baudrate of terminal
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
ncurses_beep
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_beep — Let the terminal beep
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
ncurses_beep() sends an audible alert (bell) and if its not possible flashes the screen.
ncurses_bkgd
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_bkgd — Set background property for terminal screen
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- attrchar
-
ncurses_bkgdset
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_bkgdset — Control screen background
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- attrchar
-
ncurses_border
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_border — Draw a border around the screen using attributed characters
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Draws the specified lines and corners around the main window.
Use ncurses_wborder() for borders around subwindows!
Parâmetros
Every parameter expects 0 to draw a line or 1 to skip it.
- left
-
- right
-
- top
-
- bottom
-
- tl_corner
-
Top left corner
- tr_corner
-
Top right corner
- bl_corner
-
Bottom left corner
- br_corner
-
Bottom right corner
ncurses_bottom_panel
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_bottom_panel — Moves a visible panel to the bottom of the stack
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- panel
-
ncurses_can_change_color
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_can_change_color — Checks if terminal color definitions can be changed
Descrição
Checks whether the terminal has color capabilities and whether the programmer can change color definitions using ncurses_init_color(). ncurses must be initialized using ncurses_init() before calling this function.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Return TRUE if the programmer can change color definitions, FALSE otherwise.
Veja Também
- ncurses_has_colors() - Checks if terminal has color capabilities
- ncurses_init_color() - Define a terminal color
- ncurses_start_color() - Initializes color functionality
ncurses_cbreak
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_cbreak — Switch of input buffering
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Disables line buffering and character processing (interrupt and flow control characters are unaffected), making characters typed by the user immediately available to the program.
Valor Retornado
Returns TRUE or NCURSES_ERR if any error occurred.
ncurses_clear
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_clear — Clear screen
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Clears the screen completely without setting blanks.
Note: ncurses_clear() clears the screen without setting blanks, which have the current background rendition. To clear screen with blanks, use ncurses_erase().
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
ncurses_clrtobot
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_clrtobot — Clear screen from current position to bottom
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Erases all lines from cursor to end of screen and creates blanks. Blanks created by ncurses_clrtobot() have the current background rendition.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Veja Também
- ncurses_clear() - Clear screen
- ncurses_clrtoeol() - Clear screen from current position to end of line
ncurses_clrtoeol
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_clrtoeol — Clear screen from current position to end of line
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Erases the current line from cursor position to the end. Blanks created by ncurses_clrtoeol() have the current background rendition.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Veja Também
- ncurses_clear() - Clear screen
- ncurses_clrtobot() - Clear screen from current position to bottom
ncurses_color_content
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_color_content — Retrieves RGB components of a color
Descrição
Retrieves the red, green, and blue components for the given color definition. Terminal color capabilities must be initialized with ncurses_start_color() prior to calling this function.
Parâmetros
- color
-
The number of the color to retrieve information for. May be one of the pre-defined color constants.
- r
-
A reference to which to return the red component of the color. The value returned to the reference will be between 0 and 1000.
- g
-
A reference to which to return the green component of the color. The value returned to the reference will be between 0 and 1000.
- b
-
A reference to which to return the blue component of the color. The value returned to the reference will be between 0 and 1000.
Valor Retornado
Returns -1 if the function was successful, and 0 if ncurses or terminal color capabilities have not been initialized.
Veja Também
- ncurses_init_color() - Define a terminal color
- ncurses_start_color() - Initializes color functionality
ncurses_color_set
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_color_set — Set active foreground and background colors
Descrição
Sets the active foreground and background colors. Any characters written after this function is invoked will have these colors. This function requires terminal colors to be supported and initialized using ncurses_start_color() beforehand.
ncurses uses color pairs to specify both foreground and background colors. Use ncurses_init_pair() to define a color pair.
Parâmetros
- pair
-
The color pair from which to get the foreground and background colors to set as the active colors.
Valor Retornado
Returns -1 on success, and 0 on failure.
Exemplos
Exemplo #1 Writing a string with a specified color to the screen
<?php
ncurses_init();
// If the terminal supports colors, initialize and set active color
if (ncurses_has_colors()) {
ncurses_start_color();
ncurses_init_pair(1, NCURSES_COLOR_YELLOW, NCURSES_COLOR_BLUE);
ncurses_color_set(1);
}
// Write a string at specified location
ncurses_mvaddstr(10, 10, "Hello world! Yellow on blue text!");
// Flush output to screen
ncurses_refresh();
ncurses_end();
?>
Veja Também
- ncurses_init_pair() - Define a color pair
- ncurses_start_color() - Initializes color functionality
ncurses_curs_set
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_curs_set — Set cursor state
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- visibility
-
ncurses_def_prog_mode
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_def_prog_mode — Saves terminals (program) mode
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Saves the current terminal modes for program (in curses) for use by ncurses_reset_prog_mode().
Valor Retornado
Returns FALSE on success, otherwise TRUE.
ncurses_def_shell_mode
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_def_shell_mode — Saves terminals (shell) mode
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Saves the current terminal modes for shell (not in curses) for use by ncurses_reset_shell_mode().
Valor Retornado
Returns FALSE on success, TRUE otherwise.
ncurses_define_key
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_define_key — Define a keycode
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- definition
-
- keycode
-
ncurses_del_panel
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_del_panel — Remove panel from the stack and delete it (but not the associated window)
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- panel
-
ncurses_delay_output
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_delay_output — Delay output on terminal using padding characters
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- milliseconds
-
ncurses_delch
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_delch — Delete character at current position, move rest of line left
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Deletes the character under the cursor. All characters to the right of the cursor on the same line are moved to the left one position and the last character on the line is filled with a blank. The cursor position does not change.
Valor Retornado
Returns FALSE on success, TRUE otherwise.
ncurses_deleteln
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_deleteln — Delete line at current position, move rest of screen up
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Deletes the current line under cursorposition. All lines below the current line are moved up one line. The bottom line of window is cleared. Cursor position does not change.
Valor Retornado
Returns FALSE on success, otherwise TRUE.
ncurses_delwin
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_delwin — Delete a ncurses window
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- window
-
ncurses_doupdate
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_doupdate — Write all prepared refreshes to terminal
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Compares the virtual screen to the physical screen and updates the physical screen. This way is more effective than using multiple refresh calls.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
ncurses_echo
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_echo — Activate keyboard input echo
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Enables echo mode. All characters typed by user are echoed by ncurses_getch().
Valor Retornado
Returns FALSE on success, TRUE if any error occurred.
ncurses_echochar
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_echochar — Single character output including refresh
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- character
-
ncurses_end
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_end — Stop using ncurses, clean up the screen
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
ncurses_erase
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_erase — Erase terminal screen
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Fills the terminal screen with blanks.
Created blanks have the current background rendition, set by ncurses_bkgd().
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Veja Também
- ncurses_bkgd() - Set background property for terminal screen
- ncurses_clear() - Clear screen
ncurses_erasechar
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_erasechar — Returns current erase character
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Returns the current erase character.
Valor Retornado
The current erase char, as a string.
ncurses_filter
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_filter — Set LINES for iniscr() and newterm() to 1
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
ncurses_flash
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_flash — Flash terminal screen (visual bell)
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Flashes the screen, and if its not possible, sends an audible alert (bell).
Valor Retornado
Returns FALSE on success, otherwise TRUE.
ncurses_flushinp
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_flushinp — Flush keyboard input buffer
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Throws away any typeahead that has been typed and has not yet been read by your program.
Valor Retornado
Returns FALSE on success, otherwise TRUE.
ncurses_getch
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_getch — Read a character from keyboard
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
ncurses_getmaxyx
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_getmaxyx — Returns the size of a window
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Gets the horizontal and vertical size of the given window into the given variables.
Variables must be passed as reference, so they are updated when the user changes the terminal size.
Parâmetros
- window
-
The measured window
- y
-
This will be set to the window height
- x
-
This will be set to the window width
Valor Retornado
Não há valor retornado.
ncurses_getmouse
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_getmouse — Reads mouse event
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
ncurses_getmouse() reads mouse event out of queue.
Parâmetros
- mevent
-
Event options will be delivered in this parameter which has to be an array, passed by reference (see example below).
On success an associative array with following keys will be delivered:
-
"id" : Id to distinguish multiple devices
-
"x" : screen relative x-position in character cells
-
"y" : screen relative y-position in character cells
-
"z" : currently not supported
-
"mmask" : Mouse action
-
Valor Retornado
Returns FALSE if a mouse event is actually visible in the given window, otherwise returns TRUE.
Exemplos
Exemplo #1 ncurses_getmouse() example
<?php
switch (ncurses_getch()){
case NCURSES_KEY_MOUSE:
if (!ncurses_getmouse($mevent)){
if ($mevent["mmask"] & NCURSES_MOUSE_BUTTON1_PRESSED){
$mouse_x = $mevent["x"]; // Save mouse position
$mouse_y = $mevent["y"];
}
}
break;
default:
/* .... */
}
?>
ncurses_getyx
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_getyx — Returns the current cursor position for a window
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- window
-
- y
-
- x
-
ncurses_halfdelay
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_halfdelay — Put terminal into halfdelay mode
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- tenth
-
ncurses_has_colors
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_has_colors — Checks if terminal has color capabilities
Descrição
Checks whether the terminal has color capabilities. This function can be used to write terminal-independent programs. ncurses must be initialized using ncurses_init() before calling this function.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Return TRUE if the terminal has color capabilities, FALSE otherwise.
Exemplos
Exemplo #1 Writing a string with a specified color to the screen
<?php
ncurses_init();
// If the terminal supports colors, initialize and set active color
if (ncurses_has_colors()) {
ncurses_start_color();
ncurses_init_pair(1, NCURSES_COLOR_YELLOW, NCURSES_COLOR_BLUE);
ncurses_color_set(1);
}
// Write a string at specified location
ncurses_mvaddstr(10, 10, "Hello world! Yellow on blue text!");
// Flush output to screen
ncurses_refresh();
ncurses_end();
?>
Veja Também
- ncurses_can_change_color() - Checks if terminal color definitions can be changed
- ncurses_start_color() - Initializes color functionality
ncurses_has_ic
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_has_ic — Check for insert- and delete-capabilities
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Checks whether the terminal has insert and delete capabilities.
Valor Retornado
Returns TRUE if the terminal has insert/delete-capabilities, FALSE otherwise.
ncurses_has_il
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_has_il — Check for line insert- and delete-capabilities
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Checks whether the terminal has insert- and delete-line-capabilities.
Valor Retornado
Returns TRUE if the terminal has insert/delete-line capabilities, FALSE otherwise.
ncurses_has_key
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_has_key — Check for presence of a function key on terminal keyboard
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- keycode
-
ncurses_hide_panel
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_hide_panel — Remove panel from the stack, making it invisible
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- panel
-
ncurses_hline
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_hline — Draw a horizontal line at current position using an attributed character and max. n characters long
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- charattr
-
- n
-
ncurses_inch
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_inch — Get character and attribute at current position
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Returns the character from the current position.
Valor Retornado
Returns the character, as a string.
ncurses_init_color
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_init_color — Define a terminal color
Descrição
Defines or redefines the given color. When this function is called, all occurrences of the given color on the screen, if any, immediately change to the new definition.
Color capabilities must be supported by the terminal and initialized using ncurses_start_color() prior to calling this function. In addition, the terminal must have color changing capabilities; use ncurses_can_change_color() to check for this.
Parâmetros
- color
-
The identification number of the color to redefine. It may be one of the default color constants.
- r
-
A color value, between 0 and 1000, for the red component.
- g
-
A color value, between 0 and 1000, for the green component.
- b
-
A color value, between 0 and 1000, for the blue component.
Valor Retornado
Returns -1 if the function was successful, and 0 if ncurses or terminal color capabilities have not been initialized or the terminal does not have color changing capabilities.
Veja Também
- ncurses_color_content() - Retrieves RGB components of a color
- ncurses_start_color() - Initializes color functionality
ncurses_init_pair
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_init_pair — Define a color pair
Descrição
Defines or redefines the given color pair to have the given foreground and background colors. If the color pair was previously initialized, the screen is refreshed and all occurrences of it are changed to reflect the new definition.
Color capabilities must be initialized using ncurses_start_color() before calling this function. The first color pair (color pair 0) is assumed to be white on black by default, but can be changed using ncurses_assume_default_colors().
Parâmetros
- pair
-
The number of the color pair to define.
- fg
-
The foreground color for the color pair. May be one of the pre-defined colors or one defined by ncurses_init_color() if the terminal has color changing capabilities.
- bg
-
The background color for the color pair. May be one of the pre-defined colors or one defined by ncurses_init_color() if the terminal has color changing capabilities.
Valor Retornado
Returns -1 if the function was successful, and 0 if ncurses or color support were not initialized.
Notas
Note that color changing capabilities are not required for defining color pairs of pre-existing colors, but only for changing definitions (red, green, and blue components) of colors themselves per ncurses_init_color().
Exemplos
Exemplo #1 Writing a string with a specified color to the screen
<?php
ncurses_init();
// If the terminal supports colors, initialize and set active color
if (ncurses_has_colors()) {
ncurses_start_color();
ncurses_init_pair(1, NCURSES_COLOR_YELLOW, NCURSES_COLOR_BLUE);
ncurses_color_set(1);
}
// Write a string at specified location
ncurses_mvaddstr(10, 10, "Hello world! Yellow on blue text!");
// Flush output to screen
ncurses_refresh();
ncurses_end();
?>
Veja Também
- ncurses_pair_content() - Retrieves foreground and background colors of a color pair
- ncurses_start_color() - Initializes color functionality
ncurses_init
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_init — Initialize ncurses
Descrição
Initializes the ncurses interface. This function must be used before any other ncurses function call.
Note that ncurses_end() must be called before exiting from the program, or the terminal will not be restored to its proper non-visual mode.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Não há valor retornado.
ncurses_insch
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_insch — Insert character moving rest of line including character at current position
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- character
-
ncurses_insdelln
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_insdelln — Insert lines before current line scrolling down (negative numbers delete and scroll up)
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- count
-
ncurses_insertln
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_insertln — Insert a line, move rest of screen down
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Inserts a new line above the current line. The bottom line will be lost.
ncurses_insstr
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_insstr — Insert string at current position, moving rest of line right
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- text
-
ncurses_instr
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_instr — Reads string from terminal screen
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Reads a string from the terminal screen and returns the number of characters read from the current character position until end of line.
Parâmetros
- buffer
-
The characters. Attributes will be stripped.
Valor Retornado
Returns the number of characters.
ncurses_isendwin
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_isendwin — Ncurses is in endwin mode, normal screen output may be performed
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Checks if ncurses is in endwin mode.
Valor Retornado
Returns TRUE, if ncurses_end() has been called without any subsequent calls to ncurses_wrefresh(), FALSE otherwise.
Veja Também
- ncurses_end() - Stop using ncurses, clean up the screen
- ncurses_wrefresh() - Refresh window on terminal screen
ncurses_keyok
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_keyok — Enable or disable a keycode
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- keycode
-
- enable
-
ncurses_keypad
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_keypad — Turns keypad on or off
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- window
-
- bf
-
ncurses_killchar
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_killchar — Returns current line kill character
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Returns the current line kill character.
Valor Retornado
Returns the kill character, as a string.
ncurses_longname
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_longname — Returns terminals description
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Returns a verbose description of the terminal.
Valor Retornado
Returns the description, as a string truncated to 128 characters. On errors, returns NULL.
ncurses_meta
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_meta — Enables/Disable 8-bit meta key information
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- window
-
- 8bit
-
ncurses_mouse_trafo
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mouse_trafo — Transforms coordinates
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- y
-
- x
-
- toscreen
-
ncurses_mouseinterval
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mouseinterval — Set timeout for mouse button clicks
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- milliseconds
-
ncurses_mousemask
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mousemask — Sets mouse options
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Sets mouse events to be reported. By default no mouse events will be reported.
Mouse events are represented by NCURSES_KEY_MOUSE in the ncurses_wgetch() input stream. To read the event data and pop the event of queue, call ncurses_getmouse().
Parâmetros
- newmask
-
Mouse mask options can be set with the following predefined constants:
NCURSES_BUTTON1_PRESSED
NCURSES_BUTTON1_RELEASED
NCURSES_BUTTON1_CLICKED
NCURSES_BUTTON1_DOUBLE_CLICKED
NCURSES_BUTTON1_TRIPLE_CLICKED
NCURSES_BUTTON2_PRESSED
NCURSES_BUTTON2_RELEASED
NCURSES_BUTTON2_CLICKED
NCURSES_BUTTON2_DOUBLE_CLICKED
NCURSES_BUTTON2_TRIPLE_CLICKED
NCURSES_BUTTON3_PRESSED
NCURSES_BUTTON3_RELEASED
NCURSES_BUTTON3_CLICKED
NCURSES_BUTTON3_DOUBLE_CLICKED
NCURSES_BUTTON3_TRIPLE_CLICKED
NCURSES_BUTTON4_PRESSED
NCURSES_BUTTON4_RELEASED
NCURSES_BUTTON4_CLICKED
NCURSES_BUTTON4_DOUBLE_CLICKED
NCURSES_BUTTON4_TRIPLE_CLICKED
NCURSES_BUTTON_SHIFT>
NCURSES_BUTTON_CTRL
NCURSES_BUTTON_ALT
NCURSES_ALL_MOUSE_EVENTS
NCURSES_REPORT_MOUSE_POSITION
As a side effect, setting a zero mousemask in newmask turns off the mouse pointer. Setting a non zero value turns mouse pointer on.
- oldmask
-
This will be set to the previous value of the mouse event mask.
Valor Retornado
Returns a mask to indicated which of the in parameter newmask specified mouse events can be reported. On complete failure, it returns 0.
Exemplos
Exemplo #1 ncurses_mousemask() example
<?php
$newmask = NCURSES_BUTTON1_CLICKED + NCURSES_BUTTON1_RELEASED;
$mask = ncurses_mousemask($newmask, $oldmask);
if ($mask & $newmask){
printf("All specified mouse options will be supported\n");
}
?>
Veja Também
- ncurses_getch() - Read a character from keyboard
- ncurses_getmouse() - Reads mouse event
- ncurses_ungetmouse() - Pushes mouse event to queue
ncurses_move_panel
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_move_panel — Moves a panel so that its upper-left corner is at [startx, starty]
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- panel
-
- startx
-
- starty
-
ncurses_move
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_move — Move output position
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- y
-
- x
-
ncurses_mvaddch
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mvaddch — Move current position and add character
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- y
-
- x
-
- c
-
ncurses_mvaddchnstr
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mvaddchnstr — Move position and add attributed string with specified length
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- y
-
- x
-
- s
-
- n
-
ncurses_mvaddchstr
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mvaddchstr — Move position and add attributed string
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- y
-
- x
-
- s
-
ncurses_mvaddnstr
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mvaddnstr — Move position and add string with specified length
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- y
-
- x
-
- s
-
- n
-
ncurses_mvaddstr
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mvaddstr — Move position and add string
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- y
-
- x
-
- s
-
ncurses_mvcur
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mvcur — Move cursor immediately
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- old_y
-
- old_x
-
- new_y
-
- new_x
-
ncurses_mvdelch
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mvdelch — Move position and delete character, shift rest of line left
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- y
-
- x
-
ncurses_mvgetch
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mvgetch — Move position and get character at new position
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- y
-
- x
-
ncurses_mvhline
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mvhline — Set new position and draw a horizontal line using an attributed character and max. n characters long
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- y
-
- x
-
- attrchar
-
- n
-
ncurses_mvinch
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mvinch — Move position and get attributed character at new position
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- y
-
- x
-
ncurses_mvvline
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mvvline — Set new position and draw a vertical line using an attributed character and max. n characters long
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- y
-
- x
-
- attrchar
-
- n
-
ncurses_mvwaddstr
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_mvwaddstr — Add string at new position in window
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- window
-
- y
-
- x
-
- text
-
ncurses_napms
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_napms — Sleep
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- milliseconds
-
ncurses_new_panel
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_new_panel — Create a new panel and associate it with window
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- window
-
ncurses_newpad
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_newpad — Creates a new pad (window)
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- rows
-
- cols
-
ncurses_newwin
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_newwin — Create a new window
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Creates a new window to draw elements in.
When creating additional windows, remember to use ncurses_getmaxyx() to check for available space, as terminal size is individual and may vary.
Parâmetros
- rows
-
Number of rows
- cols
-
Number of columns
- y
-
y-coordinate of the origin
- x
-
x-coordinate of the origin
Valor Retornado
Returns a resource ID for the new window.
ncurses_nl
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_nl — Translate newline and carriage return / line feed
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
ncurses_nocbreak
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_nocbreak — Switch terminal to cooked mode
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Returns terminal to normal (cooked) mode. Initially the terminal may or may not in cbreak mode as the mode is inherited. Therefore a program should call ncurses_cbreak() and ncurses_nocbreak() explicitly.
Valor Retornado
Returns TRUE if any error occurred, otherwise FALSE.
ncurses_noecho
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_noecho — Switch off keyboard input echo
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Prevents echoing of user typed characters.
Valor Retornado
Returns TRUE if any error occurred, FALSE otherwise.
Veja Também
- ncurses_echo() - Activate keyboard input echo
- ncurses_getch() - Read a character from keyboard
ncurses_nonl
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_nonl — Do not translate newline and carriage return / line feed
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
ncurses_noqiflush
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_noqiflush — Do not flush on signal characters
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
ncurses_noraw
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_noraw — Switch terminal out of raw mode
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Switches the terminal out of raw mode. Raw mode is similar to cbreak mode, in that characters typed are immediately passed through to the user program. The differences that are that in raw mode, the interrupt, quit, suspend and flow control characters are all passed through uninterpreted, instead of generating a signal.
Valor Retornado
Returns TRUE if any error occurred, otherwise FALSE.
Veja Também
- ncurses_raw() - Switch terminal into raw mode
- ncurses_cbreak() - Switch of input buffering
- ncurses_nocbreak() - Switch terminal to cooked mode
ncurses_pair_content
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_pair_content — Retrieves foreground and background colors of a color pair
Descrição
Retrieves the foreground and background colors that constitute the given color pair. Terminal color capabilities must be initialized with ncurses_start_color() prior to calling this function.
Parâmetros
- pair
-
The number of the color pair to retrieve information for.
- f
-
A reference to which to return the foreground color of the color pair. The information returned will be a color number referring to one of the pre-defined colors or a color defined previously by ncurses_init_color() if the terminal supports color changing.
- b
-
A reference to which to return the background color of the color pair. The information returned will be a color number referring to one of the pre-defined colors or a color defined previously by ncurses_init_color() if the terminal supports color changing.
Valor Retornado
Returns -1 if the function was successful, and 0 if ncurses or terminal color capabilities have not been initialized.
Veja Também
- ncurses_init_pair() - Define a color pair
- ncurses_start_color() - Initializes color functionality
ncurses_panel_above
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_panel_above — Returns the panel above panel
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- panel
-
Valor Retornado
If panel is null, returns the bottom panel in the stack.
ncurses_panel_below
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_panel_below — Returns the panel below panel
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- panel
-
Parâmetros
If panel is null, returns the top panel in the stack.
ncurses_panel_window
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_panel_window — Returns the window associated with panel
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- panel
-
ncurses_pnoutrefresh
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_pnoutrefresh — Copies a region from a pad into the virtual screen
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- pad
-
- pminrow
-
- pmincol
-
- sminrow
-
- smincol
-
- smaxrow
-
- smaxcol
-
ncurses_prefresh
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_prefresh — Copies a region from a pad into the virtual screen
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- pad
-
- pminrow
-
- pmincol
-
- sminrow
-
- smincol
-
- smaxrow
-
- smaxcol
-
ncurses_putp
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_putp — Apply padding information to the string and output it
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- text
-
ncurses_qiflush
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_qiflush — Flush on signal characters
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
ncurses_raw
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_raw — Switch terminal into raw mode
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Places the terminal in raw mode. Raw mode is similar to cbreak mode, in that characters typed are immediately passed through to the user program. The differences that are that in raw mode, the interrupt, quit, suspend and flow control characters are all passed through uninterpreted, instead of generating a signal.
Valor Retornado
Returns TRUE if any error occurred, otherwise FALSE.
Veja Também
- ncurses_noraw() - Switch terminal out of raw mode
- ncurses_cbreak() - Switch of input buffering
- ncurses_nocbreak() - Switch terminal to cooked mode
ncurses_refresh
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_refresh — Refresh screen
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- ch
-
ncurses_replace_panel
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_replace_panel — Replaces the window associated with panel
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- panel
-
- window
-
ncurses_reset_prog_mode
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_reset_prog_mode — Resets the prog mode saved by def_prog_mode
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
ncurses_reset_shell_mode
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_reset_shell_mode — Resets the shell mode saved by def_shell_mode
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
ncurses_resetty
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_resetty — Restores saved terminal state
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Restores the terminal state, which was previously saved by calling ncurses_savetty().
Valor Retornado
Always returns FALSE.
ncurses_savetty
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_savetty — Saves terminal state
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Saves the current terminal state. The saved terminal state can be restored with ncurses_resetty().
Valor Retornado
Always returns FALSE.
ncurses_scr_dump
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_scr_dump — Dump screen content to file
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- filename
-
ncurses_scr_init
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_scr_init — Initialize screen from file dump
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- filename
-
ncurses_scr_restore
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_scr_restore — Restore screen from file dump
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- filename
-
ncurses_scr_set
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_scr_set — Inherit screen from file dump
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- filename
-
ncurses_scrl
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_scrl — Scroll window content up or down without changing current position
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- count
-
ncurses_show_panel
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_show_panel — Places an invisible panel on top of the stack, making it visible
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- panel
-
ncurses_slk_attr
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_slk_attr — Returns current soft label key attribute
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Returns the current soft label key attribute.
Valor Retornado
The attribute, as an integer.
ncurses_slk_attroff
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_slk_attroff — Turn off the given attributes for soft function-key labels
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- intarg
-
ncurses_slk_attron
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_slk_attron — Turn on the given attributes for soft function-key labels
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- intarg
-
ncurses_slk_attrset
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_slk_attrset — Set given attributes for soft function-key labels
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- intarg
-
ncurses_slk_clear
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_slk_clear — Clears soft labels from screen
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
The function ncurses_slk_clear() clears soft label keys from screen.
Valor Retornado
Returns TRUE on errors, FALSE otherwise.
ncurses_slk_color
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_slk_color — Sets color for soft label keys
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- intarg
-
ncurses_slk_init
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_slk_init — Initializes soft label key functions
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Initializes soft label key functions
This function must be called before ncurses_init() or ncurses_newwin() is called.
Parâmetros
- format
-
If ncurses_init() eventually uses a line from stdscr to emulate the soft labels, then this parameter determines how the labels are arranged of the screen.
0 indicates a 3-2-3 arrangement of the labels, 1 indicates a 4-4 arrangement and 2 indicates the PC like 4-4-4 mode, but in addition an index line will be created.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
ncurses_slk_noutrefresh
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_slk_noutrefresh — Copies soft label keys to virtual screen
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
ncurses_slk_refresh
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_slk_refresh — Copies soft label keys to screen
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Copies soft label keys from virtual screen to physical screen.
ncurses_slk_restore
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_slk_restore — Restores soft label keys
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Restores the soft label keys after ncurses_slk_clear() has been performed.
ncurses_slk_set
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_slk_set — Sets function key labels
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- labelnr
-
- label
-
- format
-
ncurses_slk_touch
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_slk_touch — Forces output when ncurses_slk_noutrefresh is performed
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Forces all the soft labels to be output the next time a ncurses_slk_noutrefresh() is performed.
ncurses_standend
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_standend — Stop using 'standout' attribute
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
ncurses_standout
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_standout — Start using 'standout' attribute
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
ncurses_start_color
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_start_color — Initializes color functionality
Descrição
Initializes color functionality in ncurses. This function must be called before any color manipulation functions are called and after ncurses_init() is called. It is good practice to call this function right after ncurses_init().
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Returns 0 on success, or -1 if the color table could not be allocated or ncurses was not initialized.
Exemplos
Exemplo #1 Writing a string with a specified color to the screen
<?php
ncurses_init();
// If the terminal supports colors, initialize and set active color
if (ncurses_has_colors()) {
ncurses_start_color();
ncurses_init_pair(1, NCURSES_COLOR_YELLOW, NCURSES_COLOR_BLUE);
ncurses_color_set(1);
}
// Write a string at specified location
ncurses_mvaddstr(10, 10, "Hello world! Yellow on blue text!");
// Flush output to screen
ncurses_refresh();
ncurses_end();
?>
Veja Também
- ncurses_can_change_color() - Checks if terminal color definitions can be changed
- ncurses_has_colors() - Checks if terminal has color capabilities
ncurses_termattrs
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_termattrs — Returns a logical OR of all attribute flags supported by terminal
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
ncurses_termname
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_termname — Returns terminals (short)-name
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Returns terminals shortname.
Valor Retornado
Returns the shortname of the terminal, truncated to 14 characters. On errors, returns NULL.
ncurses_timeout
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_timeout — Set timeout for special key sequences
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- millisec
-
ncurses_top_panel
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_top_panel — Moves a visible panel to the top of the stack
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- panel
-
ncurses_typeahead
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_typeahead — Specify different filedescriptor for typeahead checking
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- fd
-
ncurses_ungetch
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_ungetch — Put a character back into the input stream
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- keycode
-
ncurses_ungetmouse
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_ungetmouse — Pushes mouse event to queue
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Pushes a KEY_MOUSE event onto the unput queue and associates with this event the given state sata and screen-relative character cell coordinates, specified in mevent.
Parâmetros
- mevent
-
An associative array specifying the event options:
-
"id" : Id to distinguish multiple devices
-
"x" : screen relative x-position in character cells
-
"y" : screen relative y-position in character cells
-
"z" : currently not supported
-
"mmask" : Mouse action
-
Valor Retornado
Returns FALSE on success, TRUE otherwise.
ncurses_update_panels
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_update_panels — Refreshes the virtual screen to reflect the relations between panels in the stack
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
ncurses_use_default_colors
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_use_default_colors — Assign terminal default colors to color id -1
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
ncurses_use_env
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_use_env — Control use of environment information about terminal size
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- flag
-
ncurses_use_extended_names
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_use_extended_names — Control use of extended names in terminfo descriptions
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- flag
-
ncurses_vidattr
(PHP 4 >= 4.0.7, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_vidattr — Display the string on the terminal in the video attribute mode
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- intarg
-
ncurses_vline
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_vline — Draw a vertical line at current position using an attributed character and max. n characters long
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- charattr
-
- n
-
ncurses_waddch
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_waddch — Adds character at current position in a window and advance cursor
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- window
-
- ch
-
ncurses_waddstr
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_waddstr — Outputs text at current postion in window
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- window
-
- str
-
- n
-
ncurses_wattroff
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wattroff — Turns off attributes for a window
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- window
-
- attrs
-
ncurses_wattron
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wattron — Turns on attributes for a window
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- window
-
- attrs
-
ncurses_wattrset
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wattrset — Set the attributes for a window
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- window
-
- attrs
-
ncurses_wborder
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wborder — Draws a border around the window using attributed characters
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Draws the specified lines and corners around the passed window.
Use ncurses_border() for borders around the main window.
Parâmetros
Each parameter expects 0 to draw a line and 1 to skip it.
- window
-
The window on which we operate
- left
-
- right
-
- top
-
- bottom
-
- tl_corner
-
Top left corner
- tr_corner
-
Top right corner
- bl_corner
-
Bottom left corner
- br_corner
-
Bottom right corner
ncurses_wclear
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wclear — Clears window
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- window
-
ncurses_wcolor_set
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wcolor_set — Sets windows color pairings
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- window
-
- color_pair
-
ncurses_werase
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_werase — Erase window contents
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- window
-
ncurses_wgetch
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wgetch — Reads a character from keyboard (window)
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- window
-
ncurses_whline
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_whline — Draws a horizontal line in a window at current position using an attributed character and max. n characters long
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- window
-
- charattr
-
- n
-
ncurses_wmouse_trafo
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wmouse_trafo — Transforms window/stdscr coordinates
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- window
-
- x
-
- y
-
- toscreen
-
ncurses_wmove
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wmove — Moves windows output position
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- window
-
- y
-
- x
-
ncurses_wnoutrefresh
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wnoutrefresh — Copies window to virtual screen
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- window
-
ncurses_wrefresh
(PHP 4 >= 4.2.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wrefresh — Refresh window on terminal screen
Descrição
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- window
-
ncurses_wstandend
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wstandend — End standout mode for a window
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- window
-
ncurses_wstandout
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wstandout — Enter standout mode for a window
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- window
-
ncurses_wvline
(PHP 4 >= 4.3.0, PHP 5 < 5.3.0, PECL ncurses >= 1.0.0)
ncurses_wvline — Draws a vertical line in a window at current position using an attributed character and max. n characters long
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- window
-
- charattr
-
- n
-
Índice
- ncurses_addch — Add character at current position and advance cursor
- ncurses_addchnstr — Add attributed string with specified length at current position
- ncurses_addchstr — Add attributed string at current position
- ncurses_addnstr — Add string with specified length at current position
- ncurses_addstr — Output text at current position
- ncurses_assume_default_colors — Define default colors for color 0
- ncurses_attroff — Turn off the given attributes
- ncurses_attron — Turn on the given attributes
- ncurses_attrset — Set given attributes
- ncurses_baudrate — Returns baudrate of terminal
- ncurses_beep — Let the terminal beep
- ncurses_bkgd — Set background property for terminal screen
- ncurses_bkgdset — Control screen background
- ncurses_border — Draw a border around the screen using attributed characters
- ncurses_bottom_panel — Moves a visible panel to the bottom of the stack
- ncurses_can_change_color — Checks if terminal color definitions can be changed
- ncurses_cbreak — Switch of input buffering
- ncurses_clear — Clear screen
- ncurses_clrtobot — Clear screen from current position to bottom
- ncurses_clrtoeol — Clear screen from current position to end of line
- ncurses_color_content — Retrieves RGB components of a color
- ncurses_color_set — Set active foreground and background colors
- ncurses_curs_set — Set cursor state
- ncurses_def_prog_mode — Saves terminals (program) mode
- ncurses_def_shell_mode — Saves terminals (shell) mode
- ncurses_define_key — Define a keycode
- ncurses_del_panel — Remove panel from the stack and delete it (but not the associated window)
- ncurses_delay_output — Delay output on terminal using padding characters
- ncurses_delch — Delete character at current position, move rest of line left
- ncurses_deleteln — Delete line at current position, move rest of screen up
- ncurses_delwin — Delete a ncurses window
- ncurses_doupdate — Write all prepared refreshes to terminal
- ncurses_echo — Activate keyboard input echo
- ncurses_echochar — Single character output including refresh
- ncurses_end — Stop using ncurses, clean up the screen
- ncurses_erase — Erase terminal screen
- ncurses_erasechar — Returns current erase character
- ncurses_filter — Set LINES for iniscr() and newterm() to 1
- ncurses_flash — Flash terminal screen (visual bell)
- ncurses_flushinp — Flush keyboard input buffer
- ncurses_getch — Read a character from keyboard
- ncurses_getmaxyx — Returns the size of a window
- ncurses_getmouse — Reads mouse event
- ncurses_getyx — Returns the current cursor position for a window
- ncurses_halfdelay — Put terminal into halfdelay mode
- ncurses_has_colors — Checks if terminal has color capabilities
- ncurses_has_ic — Check for insert- and delete-capabilities
- ncurses_has_il — Check for line insert- and delete-capabilities
- ncurses_has_key — Check for presence of a function key on terminal keyboard
- ncurses_hide_panel — Remove panel from the stack, making it invisible
- ncurses_hline — Draw a horizontal line at current position using an attributed character and max. n characters long
- ncurses_inch — Get character and attribute at current position
- ncurses_init_color — Define a terminal color
- ncurses_init_pair — Define a color pair
- ncurses_init — Initialize ncurses
- ncurses_insch — Insert character moving rest of line including character at current position
- ncurses_insdelln — Insert lines before current line scrolling down (negative numbers delete and scroll up)
- ncurses_insertln — Insert a line, move rest of screen down
- ncurses_insstr — Insert string at current position, moving rest of line right
- ncurses_instr — Reads string from terminal screen
- ncurses_isendwin — Ncurses is in endwin mode, normal screen output may be performed
- ncurses_keyok — Enable or disable a keycode
- ncurses_keypad — Turns keypad on or off
- ncurses_killchar — Returns current line kill character
- ncurses_longname — Returns terminals description
- ncurses_meta — Enables/Disable 8-bit meta key information
- ncurses_mouse_trafo — Transforms coordinates
- ncurses_mouseinterval — Set timeout for mouse button clicks
- ncurses_mousemask — Sets mouse options
- ncurses_move_panel — Moves a panel so that its upper-left corner is at [startx, starty]
- ncurses_move — Move output position
- ncurses_mvaddch — Move current position and add character
- ncurses_mvaddchnstr — Move position and add attributed string with specified length
- ncurses_mvaddchstr — Move position and add attributed string
- ncurses_mvaddnstr — Move position and add string with specified length
- ncurses_mvaddstr — Move position and add string
- ncurses_mvcur — Move cursor immediately
- ncurses_mvdelch — Move position and delete character, shift rest of line left
- ncurses_mvgetch — Move position and get character at new position
- ncurses_mvhline — Set new position and draw a horizontal line using an attributed character and max. n characters long
- ncurses_mvinch — Move position and get attributed character at new position
- ncurses_mvvline — Set new position and draw a vertical line using an attributed character and max. n characters long
- ncurses_mvwaddstr — Add string at new position in window
- ncurses_napms — Sleep
- ncurses_new_panel — Create a new panel and associate it with window
- ncurses_newpad — Creates a new pad (window)
- ncurses_newwin — Create a new window
- ncurses_nl — Translate newline and carriage return / line feed
- ncurses_nocbreak — Switch terminal to cooked mode
- ncurses_noecho — Switch off keyboard input echo
- ncurses_nonl — Do not translate newline and carriage return / line feed
- ncurses_noqiflush — Do not flush on signal characters
- ncurses_noraw — Switch terminal out of raw mode
- ncurses_pair_content — Retrieves foreground and background colors of a color pair
- ncurses_panel_above — Returns the panel above panel
- ncurses_panel_below — Returns the panel below panel
- ncurses_panel_window — Returns the window associated with panel
- ncurses_pnoutrefresh — Copies a region from a pad into the virtual screen
- ncurses_prefresh — Copies a region from a pad into the virtual screen
- ncurses_putp — Apply padding information to the string and output it
- ncurses_qiflush — Flush on signal characters
- ncurses_raw — Switch terminal into raw mode
- ncurses_refresh — Refresh screen
- ncurses_replace_panel — Replaces the window associated with panel
- ncurses_reset_prog_mode — Resets the prog mode saved by def_prog_mode
- ncurses_reset_shell_mode — Resets the shell mode saved by def_shell_mode
- ncurses_resetty — Restores saved terminal state
- ncurses_savetty — Saves terminal state
- ncurses_scr_dump — Dump screen content to file
- ncurses_scr_init — Initialize screen from file dump
- ncurses_scr_restore — Restore screen from file dump
- ncurses_scr_set — Inherit screen from file dump
- ncurses_scrl — Scroll window content up or down without changing current position
- ncurses_show_panel — Places an invisible panel on top of the stack, making it visible
- ncurses_slk_attr — Returns current soft label key attribute
- ncurses_slk_attroff — Turn off the given attributes for soft function-key labels
- ncurses_slk_attron — Turn on the given attributes for soft function-key labels
- ncurses_slk_attrset — Set given attributes for soft function-key labels
- ncurses_slk_clear — Clears soft labels from screen
- ncurses_slk_color — Sets color for soft label keys
- ncurses_slk_init — Initializes soft label key functions
- ncurses_slk_noutrefresh — Copies soft label keys to virtual screen
- ncurses_slk_refresh — Copies soft label keys to screen
- ncurses_slk_restore — Restores soft label keys
- ncurses_slk_set — Sets function key labels
- ncurses_slk_touch — Forces output when ncurses_slk_noutrefresh is performed
- ncurses_standend — Stop using 'standout' attribute
- ncurses_standout — Start using 'standout' attribute
- ncurses_start_color — Initializes color functionality
- ncurses_termattrs — Returns a logical OR of all attribute flags supported by terminal
- ncurses_termname — Returns terminals (short)-name
- ncurses_timeout — Set timeout for special key sequences
- ncurses_top_panel — Moves a visible panel to the top of the stack
- ncurses_typeahead — Specify different filedescriptor for typeahead checking
- ncurses_ungetch — Put a character back into the input stream
- ncurses_ungetmouse — Pushes mouse event to queue
- ncurses_update_panels — Refreshes the virtual screen to reflect the relations between panels in the stack
- ncurses_use_default_colors — Assign terminal default colors to color id -1
- ncurses_use_env — Control use of environment information about terminal size
- ncurses_use_extended_names — Control use of extended names in terminfo descriptions
- ncurses_vidattr — Display the string on the terminal in the video attribute mode
- ncurses_vline — Draw a vertical line at current position using an attributed character and max. n characters long
- ncurses_waddch — Adds character at current position in a window and advance cursor
- ncurses_waddstr — Outputs text at current postion in window
- ncurses_wattroff — Turns off attributes for a window
- ncurses_wattron — Turns on attributes for a window
- ncurses_wattrset — Set the attributes for a window
- ncurses_wborder — Draws a border around the window using attributed characters
- ncurses_wclear — Clears window
- ncurses_wcolor_set — Sets windows color pairings
- ncurses_werase — Erase window contents
- ncurses_wgetch — Reads a character from keyboard (window)
- ncurses_whline — Draws a horizontal line in a window at current position using an attributed character and max. n characters long
- ncurses_wmouse_trafo — Transforms window/stdscr coordinates
- ncurses_wmove — Moves windows output position
- ncurses_wnoutrefresh — Copies window to virtual screen
- ncurses_wrefresh — Refresh window on terminal screen
- ncurses_wstandend — End standout mode for a window
- ncurses_wstandout — Enter standout mode for a window
- ncurses_wvline — Draws a vertical line in a window at current position using an attributed character and max. n characters long
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Ncurses Funções
- ncurses_addch — Add character at current position and advance cursor
- ncurses_addchnstr — Add attributed string with specified length at current position
- ncurses_addchstr — Add attributed string at current position
- ncurses_addnstr — Add string with specified length at current position
- ncurses_addstr — Output text at current position
- ncurses_assume_default_colors — Define default colors for color 0
- ncurses_attroff — Turn off the given attributes
- ncurses_attron — Turn on the given attributes
- ncurses_attrset — Set given attributes
- ncurses_baudrate — Returns baudrate of terminal
- ncurses_beep — Let the terminal beep
- ncurses_bkgd — Set background property for terminal screen
- ncurses_bkgdset — Control screen background
- ncurses_border — Draw a border around the screen using attributed characters
- ncurses_bottom_panel — Moves a visible panel to the bottom of the stack
- ncurses_can_change_color — Checks if terminal color definitions can be changed
- ncurses_cbreak — Switch of input buffering
- ncurses_clear — Clear screen
- ncurses_clrtobot — Clear screen from current position to bottom
- ncurses_clrtoeol — Clear screen from current position to end of line
- ncurses_color_content — Retrieves RGB components of a color
- ncurses_color_set — Set active foreground and background colors
- ncurses_curs_set — Set cursor state
- ncurses_def_prog_mode — Saves terminals (program) mode
- ncurses_def_shell_mode — Saves terminals (shell) mode
- ncurses_define_key — Define a keycode
- ncurses_del_panel — Remove panel from the stack and delete it (but not the associated window)
- ncurses_delay_output — Delay output on terminal using padding characters
- ncurses_delch — Delete character at current position, move rest of line left
- ncurses_deleteln — Delete line at current position, move rest of screen up
- ncurses_delwin — Delete a ncurses window
- ncurses_doupdate — Write all prepared refreshes to terminal
- ncurses_echo — Activate keyboard input echo
- ncurses_echochar — Single character output including refresh
- ncurses_end — Stop using ncurses, clean up the screen
- ncurses_erase — Erase terminal screen
- ncurses_erasechar — Returns current erase character
- ncurses_filter — Set LINES for iniscr() and newterm() to 1
- ncurses_flash — Flash terminal screen (visual bell)
- ncurses_flushinp — Flush keyboard input buffer
- ncurses_getch — Read a character from keyboard
- ncurses_getmaxyx — Returns the size of a window
- ncurses_getmouse — Reads mouse event
- ncurses_getyx — Returns the current cursor position for a window
- ncurses_halfdelay — Put terminal into halfdelay mode
- ncurses_has_colors — Checks if terminal has color capabilities
- ncurses_has_ic — Check for insert- and delete-capabilities
- ncurses_has_il — Check for line insert- and delete-capabilities
- ncurses_has_key — Check for presence of a function key on terminal keyboard
- ncurses_hide_panel — Remove panel from the stack, making it invisible
- ncurses_hline — Draw a horizontal line at current position using an attributed character and max. n characters long
- ncurses_inch — Get character and attribute at current position
- ncurses_init_color — Define a terminal color
- ncurses_init_pair — Define a color pair
- ncurses_init — Initialize ncurses
- ncurses_insch — Insert character moving rest of line including character at current position
- ncurses_insdelln — Insert lines before current line scrolling down (negative numbers delete and scroll up)
- ncurses_insertln — Insert a line, move rest of screen down
- ncurses_insstr — Insert string at current position, moving rest of line right
- ncurses_instr — Reads string from terminal screen
- ncurses_isendwin — Ncurses is in endwin mode, normal screen output may be performed
- ncurses_keyok — Enable or disable a keycode
- ncurses_keypad — Turns keypad on or off
- ncurses_killchar — Returns current line kill character
- ncurses_longname — Returns terminals description
- ncurses_meta — Enables/Disable 8-bit meta key information
- ncurses_mouse_trafo — Transforms coordinates
- ncurses_mouseinterval — Set timeout for mouse button clicks
- ncurses_mousemask — Sets mouse options
- ncurses_move_panel — Moves a panel so that its upper-left corner is at [startx, starty]
- ncurses_move — Move output position
- ncurses_mvaddch — Move current position and add character
- ncurses_mvaddchnstr — Move position and add attributed string with specified length
- ncurses_mvaddchstr — Move position and add attributed string
- ncurses_mvaddnstr — Move position and add string with specified length
- ncurses_mvaddstr — Move position and add string
- ncurses_mvcur — Move cursor immediately
- ncurses_mvdelch — Move position and delete character, shift rest of line left
- ncurses_mvgetch — Move position and get character at new position
- ncurses_mvhline — Set new position and draw a horizontal line using an attributed character and max. n characters long
- ncurses_mvinch — Move position and get attributed character at new position
- ncurses_mvvline — Set new position and draw a vertical line using an attributed character and max. n characters long
- ncurses_mvwaddstr — Add string at new position in window
- ncurses_napms — Sleep
- ncurses_new_panel — Create a new panel and associate it with window
- ncurses_newpad — Creates a new pad (window)
- ncurses_newwin — Create a new window
- ncurses_nl — Translate newline and carriage return / line feed
- ncurses_nocbreak — Switch terminal to cooked mode
- ncurses_noecho — Switch off keyboard input echo
- ncurses_nonl — Do not translate newline and carriage return / line feed
- ncurses_noqiflush — Do not flush on signal characters
- ncurses_noraw — Switch terminal out of raw mode
- ncurses_pair_content — Retrieves foreground and background colors of a color pair
- ncurses_panel_above — Returns the panel above panel
- ncurses_panel_below — Returns the panel below panel
- ncurses_panel_window — Returns the window associated with panel
- ncurses_pnoutrefresh — Copies a region from a pad into the virtual screen
- ncurses_prefresh — Copies a region from a pad into the virtual screen
- ncurses_putp — Apply padding information to the string and output it
- ncurses_qiflush — Flush on signal characters
- ncurses_raw — Switch terminal into raw mode
- ncurses_refresh — Refresh screen
- ncurses_replace_panel — Replaces the window associated with panel
- ncurses_reset_prog_mode — Resets the prog mode saved by def_prog_mode
- ncurses_reset_shell_mode — Resets the shell mode saved by def_shell_mode
- ncurses_resetty — Restores saved terminal state
- ncurses_savetty — Saves terminal state
- ncurses_scr_dump — Dump screen content to file
- ncurses_scr_init — Initialize screen from file dump
- ncurses_scr_restore — Restore screen from file dump
- ncurses_scr_set — Inherit screen from file dump
- ncurses_scrl — Scroll window content up or down without changing current position
- ncurses_show_panel — Places an invisible panel on top of the stack, making it visible
- ncurses_slk_attr — Returns current soft label key attribute
- ncurses_slk_attroff — Turn off the given attributes for soft function-key labels
- ncurses_slk_attron — Turn on the given attributes for soft function-key labels
- ncurses_slk_attrset — Set given attributes for soft function-key labels
- ncurses_slk_clear — Clears soft labels from screen
- ncurses_slk_color — Sets color for soft label keys
- ncurses_slk_init — Initializes soft label key functions
- ncurses_slk_noutrefresh — Copies soft label keys to virtual screen
- ncurses_slk_refresh — Copies soft label keys to screen
- ncurses_slk_restore — Restores soft label keys
- ncurses_slk_set — Sets function key labels
- ncurses_slk_touch — Forces output when ncurses_slk_noutrefresh is performed
- ncurses_standend — Stop using 'standout' attribute
- ncurses_standout — Start using 'standout' attribute
- ncurses_start_color — Initializes color functionality
- ncurses_termattrs — Returns a logical OR of all attribute flags supported by terminal
- ncurses_termname — Returns terminals (short)-name
- ncurses_timeout — Set timeout for special key sequences
- ncurses_top_panel — Moves a visible panel to the top of the stack
- ncurses_typeahead — Specify different filedescriptor for typeahead checking
- ncurses_ungetch — Put a character back into the input stream
- ncurses_ungetmouse — Pushes mouse event to queue
- ncurses_update_panels — Refreshes the virtual screen to reflect the relations between panels in the stack
- ncurses_use_default_colors — Assign terminal default colors to color id -1
- ncurses_use_env — Control use of environment information about terminal size
- ncurses_use_extended_names — Control use of extended names in terminfo descriptions
- ncurses_vidattr — Display the string on the terminal in the video attribute mode
- ncurses_vline — Draw a vertical line at current position using an attributed character and max. n characters long
- ncurses_waddch — Adds character at current position in a window and advance cursor
- ncurses_waddstr — Outputs text at current postion in window
- ncurses_wattroff — Turns off attributes for a window
- ncurses_wattron — Turns on attributes for a window
- ncurses_wattrset — Set the attributes for a window
- ncurses_wborder — Draws a border around the window using attributed characters
- ncurses_wclear — Clears window
- ncurses_wcolor_set — Sets windows color pairings
- ncurses_werase — Erase window contents
- ncurses_wgetch — Reads a character from keyboard (window)
- ncurses_whline — Draws a horizontal line in a window at current position using an attributed character and max. n characters long
- ncurses_wmouse_trafo — Transforms window/stdscr coordinates
- ncurses_wmove — Moves windows output position
- ncurses_wnoutrefresh — Copies window to virtual screen
- ncurses_wrefresh — Refresh window on terminal screen
- ncurses_wstandend — End standout mode for a window
- ncurses_wstandout — Enter standout mode for a window
- ncurses_wvline — Draws a vertical line in a window at current position using an attributed character and max. n characters long
Newt
Introdução
This is a PHP language extension for RedHat Newt library, a terminal-based window and widget library for writing applications with user friendly interface. Once this extension is enabled in PHP it will provide the use of Newt widgets, such as windows, buttons, checkboxes, radiobuttons, labels, editboxes, scrolls, textareas, scales, etc. Use of this extension if very similar to the original Newt API of C programming language.
Instalação/Configuração
Índice
Dependências
This module uses the functions of the RedHat Newt library. You need libnewt version >= 0.51.0.
Instalação
Esta extensão » PECL não vem compilada com o PHP. Informações para a instalação desta extensão PECL podem ser encontradas no manual no capitulo intitulado Instalação de extensões PECL. Informações adicionais como novas versões, downloads, arquivos fontes, manutenções, e um Changelog, podem ser obtidos aqui: » http://pecl.php.net/package/newt.
No PHP 4, os fontes desta estensão PECL podem ser encontrados no diretório ext/ ou dentro dos fontes do PHP ou no link PECL acima. In order to use these functions you must compile CGI or CLI PHP with newt support by using the --with-newt[=DIR] configure option.
Nota:
This extension is not available for Windows platform.
You may need also curses and slang libraries, in order to compile this extension. To specify locations of these libraries, use the following configuration options: --with-curses-dir=/path/to/libcurses --with-slang-dir=/path/to/libslang
Configurações em Execução
Esta extensão não define nenhum parâmetro de configuração no php.ini.
Tipos Resource
This extension uses two resource types: "newt component" and "newt grid".
Resource type "newt component" is returned by functions, which create common newt widgets (for example: newt_button())
Resource type "newt grid" is a special link identifier for components, returned by newt grid factory functions (for example: newt_create_grid())
Constantes pré-definidas
Índice
- Newt form exit reasons
- Newt colorsets
- Newt argument flags
- Newt Flags Sense
- Newt Components Flags
- File Descriptor Flags
- Checkbox Tree Flags
- Entry Flags
- Listbox Flags
- Textbox Flags
- Form Flags
- Newt Keys
- Newt Anchors
- Grid Flags
As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.
Newt form exit reasons
| constant | meaning |
|---|---|
| NEWT_EXIT_HOTKEY | hotkey defined by newt_form_add_hot_key() was pressed |
| NEWT_EXIT_COMPONENT | some component has caused form to exit |
| NEWT_EXIT_FDREADY | file descriptor specified in newt_form_watch_fd() is ready to be read or written to |
| NEWT_EXIT_TIMER | time specified in newt_form_set_timer() has elapsed |
Newt colorsets
| constant | meaning |
|---|---|
| NEWT_COLORSET_ROOT | |
| NEWT_COLORSET_BORDER | |
| NEWT_COLORSET_WINDOW | |
| NEWT_COLORSET_SHADOW | |
| NEWT_COLORSET_TITLE | |
| NEWT_COLORSET_BUTTON | |
| NEWT_COLORSET_ACTBUTTON | |
| NEWT_COLORSET_CHECKBOX | |
| NEWT_COLORSET_ACTCHECKBOX | |
| NEWT_COLORSET_ENTRY | |
| NEWT_COLORSET_LABEL | |
| NEWT_COLORSET_LISTBOX | |
| NEWT_COLORSET_ACTLISTBOX | |
| NEWT_COLORSET_TEXTBOX | |
| NEWT_COLORSET_ACTTEXTBOX | |
| NEWT_COLORSET_HELPLINE | |
| NEWT_COLORSET_ROOTTEXT | |
| NEWT_COLORSET_ROOTTEXT | |
| NEWT_COLORSET_EMPTYSCALE | |
| NEWT_COLORSET_FULLSCALE | |
| NEWT_COLORSET_DISENTRY | |
| NEWT_COLORSET_COMPACTBUTTON | |
| NEWT_COLORSET_ACTSELLISTBOX | |
| NEWT_COLORSET_SELLISTBOX |
Newt argument flags
| constant | meaning |
|---|---|
| NEWT_ARG_LAST | |
| NEWT_ARG_APPEND |
Newt Flags Sense
| constant | meaning |
|---|---|
| NEWT_FLAGS_SET | |
| NEWT_FLAGS_RESET | |
| NEWT_FLAGS_TOGGLE |
Newt Components Flags
| constant | meaning |
|---|---|
| NEWT_FLAG_RETURNEXIT | Exit form, when component is activated |
| NEWT_FLAG_HIDDEN | Component is hidden |
| NEWT_FLAG_SCROLL | Component is scrollable |
| NEWT_FLAG_DISABLED | Component is disabled |
| NEWT_FLAG_BORDER | |
| NEWT_FLAG_WRAP | Wrap text |
| NEWT_FLAG_NOF12 | Don't exit form on pressing F12 |
| NEWT_FLAG_MULTIPLE | |
| NEWT_FLAG_SELECTED | Component is selected |
| NEWT_FLAG_CHECKBOX | Component is checkbox |
| NEWT_FLAG_PASSWORD | Entry component is password entry |
| NEWT_FLAG_SHOWCURSOR | Show cursor |
File Descriptor Flags
| constant | meaning |
|---|---|
| NEWT_FD_READ | |
| NEWT_FD_WRITE | |
| NEWT_FD_EXCEPT |
Checkbox Tree Flags
| constant | meaning |
|---|---|
| NEWT_CHECKBOXTREE_UNSELECTABLE | |
| NEWT_CHECKBOXTREE_HIDE_BOX | |
| NEWT_CHECKBOXTREE_COLLAPSED | |
| NEWT_CHECKBOXTREE_EXPANDED | |
| NEWT_CHECKBOXTREE_UNSELECTED | |
| NEWT_CHECKBOXTREE_SELECTED |
Entry Flags
| constant | meaning |
|---|---|
| NEWT_ENTRY_SCROLL | |
| NEWT_ENTRY_HIDDEN | |
| NEWT_ENTRY_RETURNEXIT | |
| NEWT_ENTRY_DISABLED |
Listbox Flags
| constant | meaning |
|---|---|
| NEWT_LISTBOX_RETURNEXIT |
Textbox Flags
| constant | meaning |
|---|---|
| NEWT_TEXTBOX_WRAP | Wrap text in the textbox |
| NEWT_TEXTBOX_SCROLL | Scroll text in the textbox |
Form Flags
| constant | meaning |
|---|---|
| NEWT_FORM_NOF12 | Don't exit form on F12 press |
Newt Keys
| constant | meaning |
|---|---|
| NEWT_KEY_TAB | |
| NEWT_KEY_ENTER | |
| NEWT_KEY_SUSPEND | |
| NEWT_KEY_ESCAPE | |
| NEWT_KEY_RETURN | |
| NEWT_KEY_EXTRA_BASE | |
| NEWT_KEY_UP | |
| NEWT_KEY_DOWN | |
| NEWT_KEY_LEFT | |
| NEWT_KEY_RIGHT | |
| NEWT_KEY_BKSPC | |
| NEWT_KEY_DELETE | |
| NEWT_KEY_HOME | |
| NEWT_KEY_END | |
| NEWT_KEY_UNTAB | |
| NEWT_KEY_PGUP | |
| NEWT_KEY_PGDN | |
| NEWT_KEY_INSERT | |
| NEWT_KEY_F1 | |
| NEWT_KEY_F2 | |
| NEWT_KEY_F3 | |
| NEWT_KEY_F4 | |
| NEWT_KEY_F5 | |
| NEWT_KEY_F6 | |
| NEWT_KEY_F7 | |
| NEWT_KEY_F8 | |
| NEWT_KEY_F9 | |
| NEWT_KEY_F10 | |
| NEWT_KEY_F11 | |
| NEWT_KEY_F12 | |
| NEWT_KEY_RESIZE |
Newt Anchors
| constant | meaning |
|---|---|
| NEWT_ANCHOR_LEFT | |
| NEWT_ANCHOR_RIGHT | |
| NEWT_ANCHOR_TOP | |
| NEWT_ANCHOR_BOTTOM |
Grid Flags
| constant | meaning |
|---|---|
| NEWT_GRID_FLAG_GROWX | |
| NEWT_GRID_FLAG_GROWY | |
| NEWT_GRID_EMPTY | |
| NEWT_GRID_COMPONENT | |
| NEWT_GRID_SUBGRID |
Exemplos
Índice
Basic usage
This example is a PHP port of RedHat 'setup' utility dialog, executed in text mode.
Exemplo #1 Newt Usage Example
<?php
newt_init ();
newt_cls ();
newt_draw_root_text (0, 0, "Test Mode Setup Utility 1.12");
newt_push_help_line (null);
newt_draw_root_text (-30, 0, "(c) 1999-2002 RedHat, Inc");
newt_get_screen_size ($rows, $cols);
newt_open_window ($rows/2-17, $cols/2-10, 34, 17, "Choose a Tool");
$form = newt_form ();
$list = newt_listbox (3, 2, 10);
foreach (array (
"Authentication configuration",
"Firewall configuration",
"Mouse configuration",
"Network configuration",
"Printer configuration",
"System services") as $l_item)
{
newt_listbox_add_entry ($list, $l_item, $l_item);
}
$b1 = newt_button (5, 12, "Run Tool");
$b2 = newt_button (21, 12, "Quit");
newt_form_add_component ($form, $list);
newt_form_add_components ($form, array($b1, $b2));
newt_refresh ();
newt_run_form ($form);
newt_pop_window ();
newt_pop_help_line ();
newt_finished ();
newt_form_destroy ($form);
?>
Newt Funções
newt_bell
(PECL newt >= 0.1)
newt_bell — Send a beep to the terminal
Descrição
This function sends a beep to the terminal.
Nota:
Depending on the terminal's settings, this beep may or may not be audible.
Valor Retornado
Não há valor retornado.
newt_centered_window
(PECL newt >= 0.1)
newt_centered_window — Open a centered window of the specified size
Descrição
Open a centered window of the specified size.
Parâmetros
- width
-
Window width
- height
-
Window height
- title
-
Window title
Valor Retornado
Undefined value.
Veja Também
- newt_pop_window() - Removes the top window from the display
- newt_open_window() - Open a window of the specified size and position
newt_checkbox_get_value
(PECL newt >= 0.1)
newt_checkbox_get_value — Retreives value of checkox resource
Descrição
This function returns the character in the sequence which indicates the current value of the checkbox.
Parâmetros
- checkbox
-
Valor Retornado
Returns character indicating the value of the checkbox.
newt_checkbox_set_flags
(PECL newt >= 0.1)
newt_checkbox_set_flags — Configures checkbox resource
Descrição
This function allows to set various flags on checkbox resource.
Parâmetros
- checkbox
-
- flags
-
- sense
-
Valor Retornado
Não há valor retornado.
newt_checkbox_set_value
(PECL newt >= 0.1)
newt_checkbox_set_value — Sets the value of the checkbox
Descrição
This function allows to set the current value of the checkbox resource.
Parâmetros
- checkbox
-
- value
-
Valor Retornado
Não há valor retornado.
newt_checkbox_tree_add_item
(PECL newt >= 0.1)
newt_checkbox_tree_add_item — Adds new item to the checkbox tree
Descrição
This function allows to add new item to the checkbox tree.
Parâmetros
- checkboxtree
-
- text
-
- data
-
- flags
-
- index
-
Valor Retornado
Não há valor retornado.
newt_checkbox_tree_find_item
(PECL newt >= 0.1)
newt_checkbox_tree_find_item — Finds an item in the checkbox tree
Descrição
Finds an item in the checkbox tree by item's data.
Parâmetros
- checkboxtree
-
- data
-
Valor Retornado
Returns checkbox tree item resource, or NULL if it wasn't found.
newt_checkbox_tree_get_current
(PECL newt >= 0.1)
newt_checkbox_tree_get_current — Returns checkbox tree selected item
Descrição
This method returns checkbox tree selected tem.
Parâmetros
- checkboxtree
-
Valor Retornado
Returns current (selected) checkbox tree item.
newt_checkbox_tree_get_entry_value
(PECL newt >= 0.1)
newt_checkbox_tree_get_entry_value —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- checkboxtree
-
- data
-
Valor Retornado
newt_checkbox_tree_get_multi_selection
(PECL newt >= 0.1)
newt_checkbox_tree_get_multi_selection —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- checkboxtree
-
- seqnum
-
Valor Retornado
newt_checkbox_tree_get_selection
(PECL newt >= 0.1)
newt_checkbox_tree_get_selection —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- checkboxtree
-
Valor Retornado
newt_checkbox_tree_multi
(PECL newt >= 0.1)
newt_checkbox_tree_multi —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- left
-
- top
-
- height
-
- seq
-
- flags
-
Valor Retornado
newt_checkbox_tree_set_current
(PECL newt >= 0.1)
newt_checkbox_tree_set_current —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- checkboxtree
-
- data
-
Valor Retornado
Não há valor retornado.
newt_checkbox_tree_set_entry_value
(PECL newt >= 0.1)
newt_checkbox_tree_set_entry_value —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- checkboxtree
-
- data
-
- value
-
Valor Retornado
Não há valor retornado.
newt_checkbox_tree_set_entry
(PECL newt >= 0.1)
newt_checkbox_tree_set_entry —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- checkboxtree
-
- data
-
- text
-
Valor Retornado
Não há valor retornado.
newt_checkbox_tree_set_width
(PECL newt >= 0.1)
newt_checkbox_tree_set_width —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- checkbox_tree
-
- width
-
Valor Retornado
Não há valor retornado.
newt_checkbox_tree
(PECL newt >= 0.1)
newt_checkbox_tree —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- left
-
- top
-
- height
-
- flags
-
Valor Retornado
newt_checkbox
(PECL newt >= 0.1)
newt_checkbox —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- left
-
- top
-
- text
-
- def_value
-
- seq
-
Valor Retornado
newt_clear_key_buffer
(PECL newt >= 0.1)
newt_clear_key_buffer — Discards the contents of the terminal's input buffer without waiting for additional input
Descrição
Discards the contents of the terminal's input buffer without waiting for additional input.
Valor Retornado
Não há valor retornado.
newt_cls
(PECL newt >= 0.1)
newt_cls —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
Valor Retornado
Não há valor retornado.
newt_component_add_callback
(PECL newt >= 0.1)
newt_component_add_callback —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- component
-
- func_name
-
- data
-
Valor Retornado
Não há valor retornado.
newt_component_takes_focus
(PECL newt >= 0.1)
newt_component_takes_focus —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- component
-
- takes_focus
-
Valor Retornado
Não há valor retornado.
newt_create_grid
(PECL newt >= 0.1)
newt_create_grid —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- cols
-
- rows
-
Valor Retornado
newt_cursor_off
(PECL newt >= 0.1)
newt_cursor_off —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
Valor Retornado
Não há valor retornado.
newt_cursor_on
(PECL newt >= 0.1)
newt_cursor_on —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
Não há valor retornado.
newt_delay
(PECL newt >= 0.1)
newt_delay —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- microseconds
-
Valor Retornado
Não há valor retornado.
newt_draw_form
(PECL newt >= 0.1)
newt_draw_form —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- form
-
Valor Retornado
Não há valor retornado.
newt_draw_root_text
(PECL newt >= 0.1)
newt_draw_root_text — Displays the string text at the position indicated
Descrição
Displays the string text at the position indicated.
Parâmetros
- left
-
Column number
Nota:
If left is negative, the position is measured from the opposite side of the screen.
- top
-
Line number
Nota:
If top is negative, the position is measured from the opposite side of the screen.
- text
-
Text to display.
Valor Retornado
Não há valor retornado.
Exemplos
Exemplo #1 A newt_draw_root_text() example
This code demonstrates drawing of titles in the both corners of the screen.
<?php
newt_init();
newt_cls();
newt_draw_root_text (2, 0, "Some root text");
newt_refresh();
sleep(1);
newt_draw_root_text (-30, 0, "Root text in the other corner");
newt_refresh();
sleep(1);
newt_finished();
?>
Veja Também
- newt_push_help_line() - Saves the current help line on a stack, and displays the new line
- newt_pop_help_line() - Replaces the current help line with the one from the stack
newt_entry_get_value
(PECL newt >= 0.1)
newt_entry_get_value —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- entry
-
Valor Retornado
newt_entry_set_filter
(PECL newt >= 0.1)
newt_entry_set_filter —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- entry
-
- filter
-
- data
-
Valor Retornado
Não há valor retornado.
newt_entry_set_flags
(PECL newt >= 0.1)
newt_entry_set_flags —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- entry
-
- flags
-
- sense
-
Valor Retornado
Não há valor retornado.
newt_entry_set
(PECL newt >= 0.1)
newt_entry_set —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- entry
-
- value
-
- cursor_at_end
-
Valor Retornado
Não há valor retornado.
newt_entry
(PECL newt >= 0.1)
newt_entry —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- left
-
- top
-
- width
-
- init_value
-
- flags
-
Valor Retornado
newt_finished
(PECL newt >= 0.1)
newt_finished — Uninitializes newt interface
Descrição
Uninitializes newt interface. This function be called, when program is ready to exit.
Valor Retornado
Returns 1 on success, 0 on failure.
newt_form_add_component
(PECL newt >= 0.1)
newt_form_add_component — Adds a single component to the form
Descrição
Adds a single component to the form.
Parâmetros
- form
-
Form to which component will be added
- component
-
Component to add to the form
Valor Retornado
Não há valor retornado.
Exemplos
Exemplo #1 A newt_form_add_component() example
<?php
$form = newt_form();
$options = array("Authentication configuration", "Firewall configuration",
"Mouse configuration", "Network configuration", "Printer configuration",
"System services");
$list = newt_listbox(3, 2, 10);
foreach ($options as $l_item) {
newt_listbox_add_entry($list, $l_item, $l_item);
}
newt_form_add_component($form, $list);
?>
newt_form_add_components
(PECL newt >= 0.1)
newt_form_add_components — Add several components to the form
Descrição
Adds several components to the form.
Parâmetros
- form
-
Form to which components will be added
- components
-
Array of components to add to the form
Valor Retornado
Não há valor retornado.
Exemplos
Exemplo #1 A newt_form_add_components() example
<?php
$form = newt_form();
$b1 = newt_button(5, 12, "Run Tool");
$b2 = newt_button(21, 12, "Quit");
newt_form_add_components($form, array($b1, $b2));
?>
newt_form_add_hot_key
(PECL newt >= 0.1)
newt_form_add_hot_key —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- form
-
- key
-
Valor Retornado
Não há valor retornado.
newt_form_destroy
(PECL newt >= 0.1)
newt_form_destroy — Destroys a form
Descrição
This function frees the memory resources used by the form and all of the components which have been added to the form (including those components which are on subforms). Once a form has been destroyed, none of the form's components can be used.
Parâmetros
- form
-
Form component, which is going to be destroyed
Valor Retornado
Não há valor retornado.
newt_form_get_current
(PECL newt >= 0.1)
newt_form_get_current —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- form
-
Valor Retornado
newt_form_run
(PECL newt >= 0.1)
newt_form_run — Runs a form
Descrição
This function runs the form passed to it.
Parâmetros
- form
-
Form component
- exit_struct
-
Array, used for returning information after running the form component. Keys and values are described in the following table:
Form Exit Structure Index Key Value Type Description reason integer The reason, why the form has been exited. Possible values are defined here. watch resource Resource link, specified in newt_form_watch_fd() key integer Hotkey component resource Component, which caused the form to exit
Valor Retornado
Não há valor retornado.
newt_form_set_background
(PECL newt >= 0.1)
newt_form_set_background —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- from
-
- background
-
Valor Retornado
Não há valor retornado.
newt_form_set_height
(PECL newt >= 0.1)
newt_form_set_height —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- form
-
- height
-
Valor Retornado
Não há valor retornado.
newt_form_set_size
(PECL newt >= 0.1)
newt_form_set_size —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- form
-
Valor Retornado
Não há valor retornado.
newt_form_set_timer
(PECL newt >= 0.1)
newt_form_set_timer —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- form
-
- milliseconds
-
Valor Retornado
Não há valor retornado.
newt_form_set_width
(PECL newt >= 0.1)
newt_form_set_width —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- form
-
- width
-
Valor Retornado
Não há valor retornado.
newt_form_watch_fd
(PECL newt >= 0.1)
newt_form_watch_fd —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- form
-
- stream
-
- flags
-
Valor Retornado
Não há valor retornado.
newt_form
(PECL newt >= 0.1)
newt_form — Create a form
Descrição
Create a new form.
Parâmetros
- vert_bar
-
Vertical scrollbar which should be associated with the form
- help
-
Help text string
- flags
-
Various flags
Valor Retornado
Returns a resource link to the created form component, or FALSE on error.
Exemplos
Exemplo #1 A newt_form() example
Displays a single button "Quit", which closes the application once it's pressed.
<?php
newt_init();
newt_cls();
$myform = newt_form();
$button = newt_button (5, 12, "Quit");
newt_form_add_component ($myform, $button);
newt_refresh ();
newt_run_form ($myform);
newt_finished ();
newt_form_destroy ($myform);
?>
Veja Também
- newt_form_run() - Runs a form
- newt_run_form() - Runs a form
- newt_form_add_component() - Adds a single component to the form
- newt_form_add_components() - Add several components to the form
- newt_form_destroy() - Destroys a form
newt_get_screen_size
(PECL newt >= 0.1)
newt_get_screen_size — Fills in the passed references with the current size of the terminal
Descrição
Fills in the passed references with the current size of the terminal.
Parâmetros
- cols
-
Number of columns in the terminal
- rows
-
Number of rows in the terminal
Valor Retornado
Não há valor retornado.
Exemplos
Exemplo #1 A newt_get_screen_size() example
This code prints out the screen size of your terminal.
<?php
newt_init();
newt_get_screen_size (&$cols, &$rows);
newt_finished();
print "Your terminal size is: {$cols}x{$rows}\n";
?>
O exemplo acima irá imprimir:
Your terminal size is: 138x47
newt_grid_add_components_to_form
(PECL newt >= 0.1)
newt_grid_add_components_to_form —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- grid
-
- form
-
- recurse
-
Valor Retornado
Não há valor retornado.
newt_grid_basic_window
(PECL newt >= 0.1)
newt_grid_basic_window —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- text
-
- middle
-
- buttons
-
Valor Retornado
newt_grid_free
(PECL newt >= 0.1)
newt_grid_free —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- grid
-
- recurse
-
Valor Retornado
Não há valor retornado.
newt_grid_get_size
(PECL newt >= 0.1)
newt_grid_get_size —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- grid
-
- width
-
- height
-
Valor Retornado
Não há valor retornado.
newt_grid_h_close_stacked
(PECL newt >= 0.1)
newt_grid_h_close_stacked —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- element1_type
-
- element1
-
Valor Retornado
newt_grid_h_stacked
(PECL newt >= 0.1)
newt_grid_h_stacked —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- element1_type
-
- element1
-
Valor Retornado
newt_grid_place
(PECL newt >= 0.1)
newt_grid_place —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- grid
-
- left
-
- top
-
Valor Retornado
Não há valor retornado.
newt_grid_set_field
(PECL newt >= 0.1)
newt_grid_set_field —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- grid
-
- col
-
- row
-
- type
-
- val
-
- pad_left
-
- pad_top
-
- pad_right
-
- pad_bottom
-
- anchor
-
- flags
-
Valor Retornado
Não há valor retornado.
newt_grid_simple_window
(PECL newt >= 0.1)
newt_grid_simple_window —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- text
-
- middle
-
- buttons
-
Valor Retornado
newt_grid_v_close_stacked
(PECL newt >= 0.1)
newt_grid_v_close_stacked —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- element1_type
-
- element1
-
Valor Retornado
newt_grid_v_stacked
(PECL newt >= 0.1)
newt_grid_v_stacked —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- element1_type
-
- element1
-
Valor Retornado
newt_grid_wrapped_window_at
(PECL newt >= 0.1)
newt_grid_wrapped_window_at —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- grid
-
- title
-
- left
-
- top
-
Valor Retornado
Não há valor retornado.
newt_grid_wrapped_window
(PECL newt >= 0.1)
newt_grid_wrapped_window —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- grid
-
- title
-
Valor Retornado
Não há valor retornado.
newt_init
(PECL newt >= 0.1)
newt_init — Initialize newt
Descrição
Initializes the newt interface. This function must be called before any other newt function.
Valor Retornado
Returns 1 on success, 0 on failure.
newt_label_set_text
(PECL newt >= 0.1)
newt_label_set_text —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- label
-
- text
-
Valor Retornado
Não há valor retornado.
newt_label
(PECL newt >= 0.1)
newt_label —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- left
-
- top
-
- text
-
Valor Retornado
newt_listbox_append_entry
(PECL newt >= 0.1)
newt_listbox_append_entry —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- listbox
-
- text
-
- data
-
Valor Retornado
Não há valor retornado.
newt_listbox_clear_selection
(PECL newt >= 0.1)
newt_listbox_clear_selection —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- listbox
-
Valor Retornado
Não há valor retornado.
newt_listbox_clear
(PECL newt >= 0.1)
newt_listbox_clear —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- listobx
-
Valor Retornado
Não há valor retornado.
newt_listbox_delete_entry
(PECL newt >= 0.1)
newt_listbox_delete_entry —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- listbox
-
- key
-
Valor Retornado
Não há valor retornado.
newt_listbox_get_current
(PECL newt >= 0.1)
newt_listbox_get_current —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- listbox
-
Valor Retornado
newt_listbox_get_selection
(PECL newt >= 0.1)
newt_listbox_get_selection —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- listbox
-
Valor Retornado
newt_listbox_insert_entry
(PECL newt >= 0.1)
newt_listbox_insert_entry —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- listbox
-
- text
-
- data
-
- key
-
Valor Retornado
Não há valor retornado.
newt_listbox_item_count
(PECL newt >= 0.1)
newt_listbox_item_count —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- listbox
-
Valor Retornado
newt_listbox_select_item
(PECL newt >= 0.1)
newt_listbox_select_item —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- listbox
-
- key
-
- sense
-
Valor Retornado
Não há valor retornado.
newt_listbox_set_current_by_key
(PECL newt >= 0.1)
newt_listbox_set_current_by_key —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- listbox
-
- key
-
Valor Retornado
Não há valor retornado.
newt_listbox_set_current
(PECL newt >= 0.1)
newt_listbox_set_current —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- listbox
-
- num
-
Valor Retornado
Não há valor retornado.
newt_listbox_set_data
(PECL newt >= 0.1)
newt_listbox_set_data —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- listbox
-
- num
-
- data
-
Valor Retornado
Não há valor retornado.
newt_listbox_set_entry
(PECL newt >= 0.1)
newt_listbox_set_entry —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- listbox
-
- num
-
- text
-
Valor Retornado
Não há valor retornado.
newt_listbox_set_width
(PECL newt >= 0.1)
newt_listbox_set_width —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- listbox
-
- width
-
Valor Retornado
Não há valor retornado.
newt_listbox
(PECL newt >= 0.1)
newt_listbox —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- left
-
- top
-
- height
-
- flags
-
Valor Retornado
newt_listitem_get_data
(PECL newt >= 0.1)
newt_listitem_get_data —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- item
-
Valor Retornado
newt_listitem_set
(PECL newt >= 0.1)
newt_listitem_set —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- item
-
- text
-
Valor Retornado
Não há valor retornado.
newt_listitem
(PECL newt >= 0.1)
newt_listitem —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- left
-
- top
-
- text
-
- is_default
-
- prev_item
-
- data
-
- flags
-
Valor Retornado
newt_open_window
(PECL newt >= 0.1)
newt_open_window — Open a window of the specified size and position
Descrição
Open a window of the specified size and position.
Parâmetros
- left
-
Location of the upper left-hand corner of the window (column number)
- top
-
Location of the upper left-hand corner of the window (row number)
- width
-
Window width
- height
-
Window height
- title
-
Window title
Valor Retornado
Returns 1 on success, 0 on failure.
Veja Também
- newt_pop_window() - Removes the top window from the display
- newt_centered_window() - Open a centered window of the specified size
newt_pop_help_line
(PECL newt >= 0.1)
newt_pop_help_line — Replaces the current help line with the one from the stack
Descrição
Replaces the current help line with the one from the stack.
Nota:
It's important not to call to newt_pop_help_line() more than newt_push_help_line().
Valor Retornado
Não há valor retornado.
Veja Também
- newt_push_help_line() - Saves the current help line on a stack, and displays the new line
newt_pop_window
(PECL newt >= 0.1)
newt_pop_window — Removes the top window from the display
Descrição
Removes the top window from the display, and redraws the display areas which the window overwrote.
Valor Retornado
Não há valor retornado.
Veja Também
- newt_open_window() - Open a window of the specified size and position
- newt_centered_window() - Open a centered window of the specified size
newt_push_help_line
(PECL newt >= 0.1)
newt_push_help_line — Saves the current help line on a stack, and displays the new line
Descrição
Saves the current help line on a stack, and displays the new line.
Parâmetros
- text
-
New help text message
Nota:
If not specified, the help line is cleared.
Valor Retornado
Não há valor retornado.
newt_radio_get_current
(PECL newt >= 0.1)
newt_radio_get_current —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- set_member
-
Valor Retornado
newt_redraw_help_line
(PECL newt >= 0.1)
newt_redraw_help_line —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
Valor Retornado
Não há valor retornado.
newt_reflow_text
(PECL newt >= 0.1)
newt_reflow_text —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- text
-
- width
-
- flex_down
-
- flex_up
-
- actual_width
-
- actual_height
-
Valor Retornado
newt_refresh
(PECL newt >= 0.1)
newt_refresh — Updates modified portions of the screen
Descrição
To increase performance, newt only updates the display when it needs to, not when the program tells it to write to the terminal. Applications can force newt to immediately update modified portions of the screen by calling this function.
Valor Retornado
Não há valor retornado.
newt_resize_screen
(PECL newt >= 0.1)
newt_resize_screen —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- redraw
-
Valor Retornado
Não há valor retornado.
newt_resume
(PECL newt >= 0.1)
newt_resume — Resume using the newt interface after calling newt_suspend()
Valor Retornado
Não há valor retornado.
newt_run_form
(PECL newt >= 0.1)
newt_run_form — Runs a form
Descrição
This function runs the form passed to it.
Parâmetros
- form
-
Form component
Valor Retornado
The component which caused the form to stop running.
Nota:
Notice that this function doesn't fit in with newt's normal naming convention. It is an older interface which will not work for all forms. It was left in newt only for legacy applications. It is a simpler interface than the new newt_form_run() though, and is still used quite often as a result. When an application is done with a form, it destroys the form and all of the components the form contains.
newt_scale_set
(PECL newt >= 0.1)
newt_scale_set —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- scale
-
- amount
-
Valor Retornado
Não há valor retornado.
newt_scale
(PECL newt >= 0.1)
newt_scale —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- left
-
- top
-
- width
-
- full_value
-
Valor Retornado
newt_scrollbar_set
(PECL newt >= 0.1)
newt_scrollbar_set —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- scrollbar
-
- where
-
- total
-
Valor Retornado
Não há valor retornado.
newt_set_help_callback
(PECL newt >= 0.1)
newt_set_help_callback —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- function
-
Valor Retornado
Não há valor retornado.
newt_set_suspend_callback
(PECL newt >= 0.1)
newt_set_suspend_callback — Set a callback function which gets invoked when user presses the suspend key
Descrição
Set a callback function which gets invoked when user presses the suspend key (normally ^Z). If no suspend callback is registered, the suspend keystroke is ignored.
Parâmetros
- function
-
A callback function, which accepts one argument: data
- data
-
This data is been passed to the callback function
Valor Retornado
Não há valor retornado.
Veja Também
- newt_suspend() - Tells newt to return the terminal to its initial state
- newt_resume() - Resume using the newt interface after calling newt_suspend
newt_suspend
(PECL newt >= 0.1)
newt_suspend — Tells newt to return the terminal to its initial state
Descrição
Tells newt to return the terminal to its initial state. Once this is done, the application can suspend itself (by sending itself a SIGTSTP, fork a child program, or do whatever else it likes).
Valor Retornado
Não há valor retornado.
newt_textbox_get_num_lines
(PECL newt >= 0.1)
newt_textbox_get_num_lines —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- textbox
-
Valor Retornado
newt_textbox_reflowed
(PECL newt >= 0.1)
newt_textbox_reflowed —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- left
-
- top
-
- *text
-
- width
-
- flex_down
-
- flex_up
-
- flags
-
Valor Retornado
newt_textbox_set_height
(PECL newt >= 0.1)
newt_textbox_set_height —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- textbox
-
- height
-
Valor Retornado
Não há valor retornado.
newt_textbox_set_text
(PECL newt >= 0.1)
newt_textbox_set_text —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- textbox
-
- text
-
Valor Retornado
Não há valor retornado.
newt_textbox
(PECL newt >= 0.1)
newt_textbox —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- left
-
- top
-
- width
-
- height
-
- flags
-
Valor Retornado
newt_vertical_scrollbar
(PECL newt >= 0.1)
newt_vertical_scrollbar —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- left
-
- top
-
- height
-
- normal_colorset
-
- thumb_colorset
-
Valor Retornado
newt_wait_for_key
(PECL newt >= 0.1)
newt_wait_for_key — Doesn't return until a key has been pressed
Descrição
This function doesn't return until a key has been pressed. The keystroke is then ignored. If a key is already in the terminal's buffer, this function discards a keystroke and returns immediately.
Valor Retornado
Não há valor retornado.
Veja Também
- newt_clear_key_buffer() - Discards the contents of the terminal's input buffer without waiting for additional input
newt_win_choice
(PECL newt >= 0.1)
newt_win_choice —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- title
-
- button1_text
-
- button2_text
-
- format
-
- args
-
Valor Retornado
newt_win_entries
(PECL newt >= 0.1)
newt_win_entries —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- title
-
- text
-
- suggested_width
-
- flex_down
-
- flex_up
-
- data_width
-
- items
-
- button1
-
- button2
-
Valor Retornado
Exemplos
Exemplo #1 A newt_win_entries() example
<?php
newt_init();
newt_cls();
$entries[] = array('text' => 'First name:', 'value' => &$f_name);
$entries[] = array('text' => 'Last name:', 'value' => &$l_name);
$rc = newt_win_entries("User information", "Please enter your credentials:", 50, 7, 7, 30, $entries, "Ok", "Back");
newt_finished ();
if ($rc != 2) {
echo "Your name is: $f_name $l_name\n";
}
?>
newt_win_message
(PECL newt >= 0.1)
newt_win_message —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- title
-
- button_text
-
- format
-
- args
-
Valor Retornado
Não há valor retornado.
newt_win_messagev
(PECL newt >= 0.1)
newt_win_messagev —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- title
-
- button_text
-
- format
-
- args
-
Valor Retornado
Não há valor retornado.
newt_win_ternary
(PECL newt >= 0.1)
newt_win_ternary —
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- title
-
Its description
- button1_text
-
Its description
- button2_text
-
Its description
- button3_text
-
Its description
- format
-
Its description
- args
-
Its description
Valor Retornado
What the function returns, first on success, then on failure. See also the &return.success; entity
Índice
- newt_bell — Send a beep to the terminal
- newt_button_bar — This function returns a grid containing the buttons created.
- newt_button — Create a new button
- newt_centered_window — Open a centered window of the specified size
- newt_checkbox_get_value — Retreives value of checkox resource
- newt_checkbox_set_flags — Configures checkbox resource
- newt_checkbox_set_value — Sets the value of the checkbox
- newt_checkbox_tree_add_item — Adds new item to the checkbox tree
- newt_checkbox_tree_find_item — Finds an item in the checkbox tree
- newt_checkbox_tree_get_current — Returns checkbox tree selected item
- newt_checkbox_tree_get_entry_value — Descrição
- newt_checkbox_tree_get_multi_selection — Descrição
- newt_checkbox_tree_get_selection — Descrição
- newt_checkbox_tree_multi — Descrição
- newt_checkbox_tree_set_current — Descrição
- newt_checkbox_tree_set_entry_value — Descrição
- newt_checkbox_tree_set_entry — Descrição
- newt_checkbox_tree_set_width — Descrição
- newt_checkbox_tree — Descrição
- newt_checkbox — Descrição
- newt_clear_key_buffer — Discards the contents of the terminal's input buffer without waiting for additional input
- newt_cls — Descrição
- newt_compact_button — Descrição
- newt_component_add_callback — Descrição
- newt_component_takes_focus — Descrição
- newt_create_grid — Descrição
- newt_cursor_off — Descrição
- newt_cursor_on — Descrição
- newt_delay — Descrição
- newt_draw_form — Descrição
- newt_draw_root_text — Displays the string text at the position indicated
- newt_entry_get_value — Descrição
- newt_entry_set_filter — Descrição
- newt_entry_set_flags — Descrição
- newt_entry_set — Descrição
- newt_entry — Descrição
- newt_finished — Uninitializes newt interface
- newt_form_add_component — Adds a single component to the form
- newt_form_add_components — Add several components to the form
- newt_form_add_hot_key — Descrição
- newt_form_destroy — Destroys a form
- newt_form_get_current — Descrição
- newt_form_run — Runs a form
- newt_form_set_background — Descrição
- newt_form_set_height — Descrição
- newt_form_set_size — Descrição
- newt_form_set_timer — Descrição
- newt_form_set_width — Descrição
- newt_form_watch_fd — Descrição
- newt_form — Create a form
- newt_get_screen_size — Fills in the passed references with the current size of the terminal
- newt_grid_add_components_to_form — Descrição
- newt_grid_basic_window — Descrição
- newt_grid_free — Descrição
- newt_grid_get_size — Descrição
- newt_grid_h_close_stacked — Descrição
- newt_grid_h_stacked — Descrição
- newt_grid_place — Descrição
- newt_grid_set_field — Descrição
- newt_grid_simple_window — Descrição
- newt_grid_v_close_stacked — Descrição
- newt_grid_v_stacked — Descrição
- newt_grid_wrapped_window_at — Descrição
- newt_grid_wrapped_window — Descrição
- newt_init — Initialize newt
- newt_label_set_text — Descrição
- newt_label — Descrição
- newt_listbox_append_entry — Descrição
- newt_listbox_clear_selection — Descrição
- newt_listbox_clear — Descrição
- newt_listbox_delete_entry — Descrição
- newt_listbox_get_current — Descrição
- newt_listbox_get_selection — Descrição
- newt_listbox_insert_entry — Descrição
- newt_listbox_item_count — Descrição
- newt_listbox_select_item — Descrição
- newt_listbox_set_current_by_key — Descrição
- newt_listbox_set_current — Descrição
- newt_listbox_set_data — Descrição
- newt_listbox_set_entry — Descrição
- newt_listbox_set_width — Descrição
- newt_listbox — Descrição
- newt_listitem_get_data — Descrição
- newt_listitem_set — Descrição
- newt_listitem — Descrição
- newt_open_window — Open a window of the specified size and position
- newt_pop_help_line — Replaces the current help line with the one from the stack
- newt_pop_window — Removes the top window from the display
- newt_push_help_line — Saves the current help line on a stack, and displays the new line
- newt_radio_get_current — Descrição
- newt_radiobutton — Descrição
- newt_redraw_help_line — Descrição
- newt_reflow_text — Descrição
- newt_refresh — Updates modified portions of the screen
- newt_resize_screen — Descrição
- newt_resume — Resume using the newt interface after calling newt_suspend
- newt_run_form — Runs a form
- newt_scale_set — Descrição
- newt_scale — Descrição
- newt_scrollbar_set — Descrição
- newt_set_help_callback — Descrição
- newt_set_suspend_callback — Set a callback function which gets invoked when user presses the suspend key
- newt_suspend — Tells newt to return the terminal to its initial state
- newt_textbox_get_num_lines — Descrição
- newt_textbox_reflowed — Descrição
- newt_textbox_set_height — Descrição
- newt_textbox_set_text — Descrição
- newt_textbox — Descrição
- newt_vertical_scrollbar — Descrição
- newt_wait_for_key — Doesn't return until a key has been pressed
- newt_win_choice — Descrição
- newt_win_entries — Descrição
- newt_win_menu — Descrição
- newt_win_message — Descrição
- newt_win_messagev — Descrição
- newt_win_ternary — Descrição
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Exemplos
- Newt Funções
- newt_bell — Send a beep to the terminal
- newt_button_bar — This function returns a grid containing the buttons created.
- newt_button — Create a new button
- newt_centered_window — Open a centered window of the specified size
- newt_checkbox_get_value — Retreives value of checkox resource
- newt_checkbox_set_flags — Configures checkbox resource
- newt_checkbox_set_value — Sets the value of the checkbox
- newt_checkbox_tree_add_item — Adds new item to the checkbox tree
- newt_checkbox_tree_find_item — Finds an item in the checkbox tree
- newt_checkbox_tree_get_current — Returns checkbox tree selected item
- newt_checkbox_tree_get_entry_value — Descrição
- newt_checkbox_tree_get_multi_selection — Descrição
- newt_checkbox_tree_get_selection — Descrição
- newt_checkbox_tree_multi — Descrição
- newt_checkbox_tree_set_current — Descrição
- newt_checkbox_tree_set_entry_value — Descrição
- newt_checkbox_tree_set_entry — Descrição
- newt_checkbox_tree_set_width — Descrição
- newt_checkbox_tree — Descrição
- newt_checkbox — Descrição
- newt_clear_key_buffer — Discards the contents of the terminal's input buffer without waiting for additional input
- newt_cls — Descrição
- newt_compact_button — Descrição
- newt_component_add_callback — Descrição
- newt_component_takes_focus — Descrição
- newt_create_grid — Descrição
- newt_cursor_off — Descrição
- newt_cursor_on — Descrição
- newt_delay — Descrição
- newt_draw_form — Descrição
- newt_draw_root_text — Displays the string text at the position indicated
- newt_entry_get_value — Descrição
- newt_entry_set_filter — Descrição
- newt_entry_set_flags — Descrição
- newt_entry_set — Descrição
- newt_entry — Descrição
- newt_finished — Uninitializes newt interface
- newt_form_add_component — Adds a single component to the form
- newt_form_add_components — Add several components to the form
- newt_form_add_hot_key — Descrição
- newt_form_destroy — Destroys a form
- newt_form_get_current — Descrição
- newt_form_run — Runs a form
- newt_form_set_background — Descrição
- newt_form_set_height — Descrição
- newt_form_set_size — Descrição
- newt_form_set_timer — Descrição
- newt_form_set_width — Descrição
- newt_form_watch_fd — Descrição
- newt_form — Create a form
- newt_get_screen_size — Fills in the passed references with the current size of the terminal
- newt_grid_add_components_to_form — Descrição
- newt_grid_basic_window — Descrição
- newt_grid_free — Descrição
- newt_grid_get_size — Descrição
- newt_grid_h_close_stacked — Descrição
- newt_grid_h_stacked — Descrição
- newt_grid_place — Descrição
- newt_grid_set_field — Descrição
- newt_grid_simple_window — Descrição
- newt_grid_v_close_stacked — Descrição
- newt_grid_v_stacked — Descrição
- newt_grid_wrapped_window_at — Descrição
- newt_grid_wrapped_window — Descrição
- newt_init — Initialize newt
- newt_label_set_text — Descrição
- newt_label — Descrição
- newt_listbox_append_entry — Descrição
- newt_listbox_clear_selection — Descrição
- newt_listbox_clear — Descrição
- newt_listbox_delete_entry — Descrição
- newt_listbox_get_current — Descrição
- newt_listbox_get_selection — Descrição
- newt_listbox_insert_entry — Descrição
- newt_listbox_item_count — Descrição
- newt_listbox_select_item — Descrição
- newt_listbox_set_current_by_key — Descrição
- newt_listbox_set_current — Descrição
- newt_listbox_set_data — Descrição
- newt_listbox_set_entry — Descrição
- newt_listbox_set_width — Descrição
- newt_listbox — Descrição
- newt_listitem_get_data — Descrição
- newt_listitem_set — Descrição
- newt_listitem — Descrição
- newt_open_window — Open a window of the specified size and position
- newt_pop_help_line — Replaces the current help line with the one from the stack
- newt_pop_window — Removes the top window from the display
- newt_push_help_line — Saves the current help line on a stack, and displays the new line
- newt_radio_get_current — Descrição
- newt_radiobutton — Descrição
- newt_redraw_help_line — Descrição
- newt_reflow_text — Descrição
- newt_refresh — Updates modified portions of the screen
- newt_resize_screen — Descrição
- newt_resume — Resume using the newt interface after calling newt_suspend
- newt_run_form — Runs a form
- newt_scale_set — Descrição
- newt_scale — Descrição
- newt_scrollbar_set — Descrição
- newt_set_help_callback — Descrição
- newt_set_suspend_callback — Set a callback function which gets invoked when user presses the suspend key
- newt_suspend — Tells newt to return the terminal to its initial state
- newt_textbox_get_num_lines — Descrição
- newt_textbox_reflowed — Descrição
- newt_textbox_set_height — Descrição
- newt_textbox_set_text — Descrição
- newt_textbox — Descrição
- newt_vertical_scrollbar — Descrição
- newt_wait_for_key — Doesn't return until a key has been pressed
- newt_win_choice — Descrição
- newt_win_entries — Descrição
- newt_win_menu — Descrição
- newt_win_message — Descrição
- newt_win_messagev — Descrição
- newt_win_ternary — Descrição
GNU Readline
Introdução
As funções readline() implementam uma interface para a biblioteca GNU Readline. Estas são funções que provem uma linha de comando editável. Um exeplo é o bash que permite a você usar as setas para inserir caracteres ou navegas no historico dos comandos. Por causa da naturesa interativa desta biblioteca, ela será de pouco uso para escrever aplicações web, mas será util quando você estiver escrevendo scripts que usem o PHP a partir da linha de comando.
Nota: Esta extensão não está disponível na plataforma Windows.
Instalação/Configuração
Índice
Dependências
Para usar as funções readline, você precisa instalar a libreadline. Você pode encontrar a libreadline na página do projeto GNU Readline, em » http://cnswww.cns.cwru.edu/~chet/readline/rltop.html. É mantida por Chet Ramey, que também é o autor do Bash.
Você também pode utilizar estas funções com a biblioteca libedit, uma substituição não-GLP para a biblioteca readline. A biblioteca libedit esta sobre a licença BSD e esta disponível para download a partir de » http://www.thrysoee.dk/editline/.
Instalação
Para usar estas funções você deverá compilar as versões CGI ou CLI version do PHP com suporte readline. Você precisa configurar o PHP com --with-readline[=DIR] . Para usar a substituiçao libedit readline, configure o PHP com --with-libedit[=DIR] .
Configurações em Execução
Esta extensão não define nenhum parâmetro de configuração no php.ini.
Tipos Resource
Esta extensão não possui nenhum tipo resource.
Constantes pré-definidas
Esta extensão não possui nenhuma constante.
Funções da Readline
readline_add_history
(PHP 4, PHP 5)
readline_add_history — Adiciona uma linha ao histórico
Descrição
Esta função adiciona uma linha ao histórico da linha de comando.
Parâmetros
- line
-
A linha para ser adicionada no histórico.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
readline_callback_handler_install
(PHP 5 >= 5.1.0)
readline_callback_handler_install — Initializes the readline callback interface and terminal, prints the prompt and returns immediately
Descrição
Sets up a readline callback interface then prints prompt and immediately returns. Calling this function twice without removing the previous callback interface will automatically and conveniently overwrite the old interface.
The callback feature is useful when combined with stream_select() as it allows interleaving of IO and user input, unlike readline().
Parâmetros
- prompt
-
The prompt message.
- callback
-
The callback function takes one parameter; the user input returned.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 Readline Callback Interface Example
<?php
function rl_callback($ret)
{
global $c, $prompting;
echo "You entered: $ret\n";
$c++;
if ($c > 10) {
$prompting = false;
readline_callback_handler_remove();
} else {
readline_callback_handler_install("[$c] Enter something: ", 'rl_callback');
}
}
$c = 1;
$prompting = true;
readline_callback_handler_install("[$c] Enter something: ", 'rl_callback');
while ($prompting) {
$w = NULL;
$e = NULL;
$n = stream_select($r = array(STDIN), $w, $e, null);
if ($n && in_array(STDIN, $r)) {
// read a character, will call the callback when a newline is entered
readline_callback_read_char();
}
}
echo "Prompting disabled. All done.\n";
?>
Veja Também
- readline_callback_handler_remove() - Removes a previously installed callback handler and restores terminal settings
- readline_callback_read_char() - Reads a character and informs the readline callback interface when a line is received
- stream_select() - Runs the equivalent of the select() system call on the given arrays of streams with a timeout specified by tv_sec and tv_usec
readline_callback_handler_remove
(PHP 5 >= 5.1.0)
readline_callback_handler_remove — Removes a previously installed callback handler and restores terminal settings
Descrição
Removes a previously installed callback handler and restores terminal settings.
Valor Retornado
Returns TRUE if a previously installed callback handler was removed, or FALSE if one could not be found.
Exemplos
See readline_callback_handler_install() for an example of how to use the readline callback interface.
Veja Também
- readline_callback_handler_install() - Initializes the readline callback interface and terminal, prints the prompt and returns immediately
- readline_callback_read_char() - Reads a character and informs the readline callback interface when a line is received
readline_callback_read_char
(PHP 5 >= 5.1.0)
readline_callback_read_char — Reads a character and informs the readline callback interface when a line is received
Descrição
Reads a character of user input. When a line is received, this function informs the readline callback interface installed using readline_callback_handler_install() that a line is ready for input.
Valor Retornado
Não há valor retornado.
Exemplos
See readline_callback_handler_install() for an example of how to use the readline callback interface.
Veja Também
- readline_callback_handler_install() - Initializes the readline callback interface and terminal, prints the prompt and returns immediately
- readline_callback_handler_remove() - Removes a previously installed callback handler and restores terminal settings
readline_clear_history
(PHP 4, PHP 5)
readline_clear_history — Limpa a história
Descrição
Esta função limpa todo o histórico da linha de comando.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
readline_completion_function
(PHP 4, PHP 5)
readline_completion_function — Registra uma função de completar
Descrição
Esta função registra uma função de completar. Este é o mesmo tipo de funcionamento que você tem se você pressionar a tecla tab enquanto estiver usando o Bash.
Parâmetros
- function
-
Você deve usar o nome de uma função existente a qual aceita uma linha de comando parcial e retorna uma matriz de possíveis combinações.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
readline_info
(PHP 4, PHP 5)
readline_info — Obtém/Define várias variáveis internas do readline
Descrição
Obtém ou define várias variáveis internas da readline.
Parâmetros
- varname
-
Um nome de variável.
- newvalue
-
Se fornecido, este será o novo valor.
Valor Retornado
Se for utilizada sem parâmetros, esta função retorna uma matriz de valores para as configurações que a readline usa. Os elementos serão indexados pelos seguintes valores: done, end, erase_empty_line, library_version, line_buffer, mark, pending_input, point, prompt, readline_name, e terminal_name.
Se for utilizada com um ou dois parâmetros, o antigo valor é retornado.
readline_list_history
(PHP 4, PHP 5)
readline_list_history — Lista a história
Descrição
Obtém o histório de linha de comando inteiro.
Valor Retornado
Retorna um array do histórico de linha de comando inteiro. Os elementos são indexados por inteiros iniciando de zero.
readline_on_new_line
(PHP 5 >= 5.1.0)
readline_on_new_line — Inform readline that the cursor has moved to a new line
Descrição
Tells readline that the cursor has moved to a new line.
Valor Retornado
Não há valor retornado.
readline_read_history
(PHP 4, PHP 5)
readline_read_history — Lê a história
Descrição
Esta função lê a história dos comandos de um arquivo.
Parâmetros
- filename
-
Caminho para o nome do arquivo contendo o histórico de comando.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
readline_redisplay
(PHP 5 >= 5.1.0)
readline_redisplay — Redraws the display
Descrição
Redraws readline to redraw the display.
Valor Retornado
Não há valor retornado.
readline_write_history
(PHP 4, PHP 5)
readline_write_history — Grava a história
Descrição
Esta função escreve a história dos comandos em um arquivo.
Parâmetros
- filename
-
Caminho para salvar o arquivo.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
readline
(PHP 4, PHP 5)
readline — Lê uma linha
Descrição
Lê uma única linha do usuário. Você precisa adicionar esta linha para armazenar no histórico usando readline_add_history().
Parâmetros
- prompt
-
Você pode especificar uma string a qual é o prompt do usuário.
Valor Retornado
Retorna uma simples string do usuário. A linha retornada tem o caractere de newline do removido.
Exemplos
Exemplo #1 readline()
<?php
// Obtém três comandos do usuário
for ($i=0; $i < 3; $i++) {
$line = readline("Command: ");
readline_add_history($line);
}
// Mostra o historíco
print_r(readline_list_history());
// Mostra as variáveis
print_r(readline_info());
?>
Índice
- readline_add_history — Adiciona uma linha ao histórico
- readline_callback_handler_install — Initializes the readline callback interface and terminal, prints the prompt and returns immediately
- readline_callback_handler_remove — Removes a previously installed callback handler and restores terminal settings
- readline_callback_read_char — Reads a character and informs the readline callback interface when a line is received
- readline_clear_history — Limpa a história
- readline_completion_function — Registra uma função de completar
- readline_info — Obtém/Define várias variáveis internas do readline
- readline_list_history — Lista a história
- readline_on_new_line — Inform readline that the cursor has moved to a new line
- readline_read_history — Lê a história
- readline_redisplay — Redraws the display
- readline_write_history — Grava a história
- readline — Lê uma linha
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Funções da Readline
- readline_add_history — Adiciona uma linha ao histórico
- readline_callback_handler_install — Initializes the readline callback interface and terminal, prints the prompt and returns immediately
- readline_callback_handler_remove — Removes a previously installed callback handler and restores terminal settings
- readline_callback_read_char — Reads a character and informs the readline callback interface when a line is received
- readline_clear_history — Limpa a história
- readline_completion_function — Registra uma função de completar
- readline_info — Obtém/Define várias variáveis internas do readline
- readline_list_history — Lista a história
- readline_on_new_line — Inform readline that the cursor has moved to a new line
- readline_read_history — Lê a história
- readline_redisplay — Redraws the display
- readline_write_history — Grava a história
- readline — Lê uma linha
Extensões de Arquivo e Compressão
Bzip2
Introdução
As funções para bzip2 são usadas para ler e escrever, de forma transparente, arquivos compactados do tipo bzip2 (.bz2).
Instalação/Configuração
Índice
Dependências
Este módulo utiliza as funções da biblioteca » bzip2 desenvolvida por Julian Seward. Este módulo requer bzip2/libbzip2 versão >= 1.0.x.
Instalação
Suporte ao Bzip2 no PHP não está disponível por padrão. Você precisará usar a opção de configuração --with-bz2[=DIR] quando compilar o PHP para habilitar o suporte à bzip2.
Configurações em Execução
Esta extensão não define nenhum parâmetro de configuração no php.ini.
Tipos Resource
Esta extensão define um tipo de recurso (resource): um ponteiro para arquivo que identifica o arquivo bzip2 que está sendo usado.
Constantes pré-definidas
Esta extensão não possui nenhuma constante.
Exemplos
Este exemplo abre um arquivo temporário e escreve uma string de test nele, e então mostra o conteúdo do arquivo.
Exemplo #1 Um exemplo simples de bzip2
<?php
$filename = "/tmp/testfile.bz2";
$str = "This is a test string.\n";
// open file for writing
$bz = bzopen($filename, "w");
// write string to file
bzwrite($bz, $str);
// close file
bzclose($bz);
// open file for reading
$bz = bzopen($filename, "r");
// read 10 characters
echo bzread($bz, 10);
// output until end of the file (or the next 1024 char) and close it.
echo bzread($bz);
bzclose($bz);
?>
Bzip2 Funções
bzclose
(PHP 4 >= 4.0.4, PHP 5)
bzclose — Fecha um ponteiro de arquivo bzip2
Descrição
Fecha o dado ponteiro de arquivo bzip2.
Parâmetros
- bz
-
O ponteiro de arquivo. Ele precisa ser válido e precisa apontar para um arquivo devidamente aberto com sucesso por bzopen().
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
bzcompress
(PHP 4 >= 4.0.4, PHP 5)
bzcompress — Comprime uma string em dados no formato bzip2
Descrição
bzcompress() comprime a string source e a retorna no formato de dados codificados com bzip2.
O parâmetro opcional blocksize especifica o tamanho do bloco utilizado no momento de compressão e deve ser um número de 1 a 9, com 9 sendo a melhor taxa de compressão, mas usando mais recursos para fazê-lo. O valor padrão de blocksize é 4.
O parâmetro opcional workfactor controla como a fase de compressão irá se comportar quando ocorrer o pior caso: a entrada de dados muito repetitivos. O seu valor pode ser de 0 até 250, com 0 sendo um caso especial, e 30 o valor padrão. Independente do valor de workfactor, a saída gerada será a mesma.
Exemplo #1 Exemplo de bzcompress()
<?php
$str = "demonstracao de dados comprimidos";
$bzstr = bzcompress($str, 9);
echo $bzstr;
?>
Veja também bzdecompress().
bzdecompress
(PHP 4 >= 4.0.4, PHP 5)
bzdecompress — Descomprime dados no formato bzip2
Descrição
bzdecompress() descomprime a string source string contendo dados no formato bzip2 e retorna o seu valor. Se o parâmetro opcional small for TRUE, um algoritmo alternativo de descompressão, com a utilização de menos memória (a máxima quantidade de memória requerida é em torno de 2300K), será usado mas funciona com a metade da velocidade. Veja a documentação do » bzip2 para mais informações sobre essa característica.
Exemplo #1 bzdecompress()
<?php
$start_str = "Esse cara é legal?";
$bzstr = bzcompress($start_str);
echo "String Comprimida: ";
echo $bzstr;
echo "\n<br />\n";
$str = bzdecompress($bzstr);
echo "String Descomprimida: ";
echo $str;
echo "\n<br />\n";
?>
Veja também bzcompress().
bzerrno
(PHP 4 >= 4.0.4, PHP 5)
bzerrno — Retorna um número de erro do bzip2
Descrição
Retorna o número do erro de qualquer erro do bzip2 retornado pelo ponteiro de arquivo bz.
Veja também bzerror() e bzerrstr().
bzerror
(PHP 4 >= 4.0.4, PHP 5)
bzerror — Retorna o número e string de erro do bzip2 em um array
Descrição
Retorna o número e string do erro de um erro da bzip2 retornado pelo dado ponteiro de arquivo. bz.
Parâmetros
- bz
-
O ponteiro do arquivo - Ele precisa ser válido e precisa apontar para um arquivo aberto com sucesso pela bzopen().
Valor Retornado
Retorna um array associativo, com o código de erro na entrada errno, e a mensagem de erro na entrada errstr.
Exemplos
Exemplo #1 Exemplo da bzerror()
<?php
$error = bzerror($bz);
echo $error["errno"];
echo $error["errstr"];
?>
Veja Também
- bzerrno() - Retorna um número de erro do bzip2
- bzerrstr() - Retorna a string de erro do bzip2
bzerrstr
(PHP 4 >= 4.0.4, PHP 5)
bzerrstr — Retorna a string de erro do bzip2
Descrição
Obtém a string de erro de um erro da bzip2 retornado para um dado ponteiro de arquivo.
Parâmetros
- bz
-
O ponteiro do arquivo. Ele precisa ser válido e precisa apontar para um arquivo aberto com sucesso pela bzopen().
Valor Retornado
Retorna uma string contendo a mensagem de erro.
bzflush
(PHP 4 >= 4.0.4, PHP 5)
bzflush — Força a escrita de todos os dados que estão no buffer
Descrição
Força a escrita de todos os dados do bzip2 que estão em buffer para o ponteiro de arquivo bz.
Parâmetros
- bz
-
O ponteiro do arquivo. Ele precisa ser válido e precisa apontar para um arquivo aberto com sucesso por bzopen().
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
bzopen
(PHP 4 >= 4.0.4, PHP 5)
bzopen — Abre um arquivo comprimido com bzip2
Descrição
Abre um arquivo bzip2 (.bz2) para leitura ou escrita. O parâmetro filename é o nome do arquivo a ser aberto. mode é similar ao da função fopen() (`r' para leitura, `w' para escrita, etc.).
Se esta função falhar, retorna FALSE, do contrário retorna um ponteiro de arquivo aberto.
Exemplo #1 Exemplo de bzopen()
<?php
$bz = bzopen("/tmp/foo.bz2", "r");
$arquivo_descomprimido = '';
while (!feof($bz)) {
$arquivo_descomprimido .= bzread($bz, 4096);
}
bzclose($bz);
print( "O conteúdo de /tmp/foo.bz2 é: " );
print( "\n<br>\n" );
print( $arquivo_descomprimido );
?>
Veja também bzclose().
bzread
(PHP 4 >= 4.0.4, PHP 5)
bzread — Leitura binary-safe de um arquivo bzip2
Descrição
bzread() lê o número de bytes equivalente a length do ponteiro de arquivo bzip2 referenciado por bz. A leitura pára quando a a quantidade de bytes referenciados por length (descomprimidos) foram lidos ou EOF foi alcançado, o que acontecer primeiro. Se o parâmetro opcional length não for especificado, bzread() irá ler 1024 bytes (descomprimidos) de cada vez.
Exemplo #1 Exemplo de bzread()
<?php
$file = "/tmp/foo.bz2";
$bz = bzopen($file", "r") or die("Couldn't open $file");
$decompressed_file = '';
while (!feof($bz)) {
$decompressed_file .= bzread($bz, 4096);
}
bzclose($bz);
echo "The contents of /tmp/foo.bz2 are: <br />\n";
echo $decompressed_file;
?>
bzwrite
(PHP 4 >= 4.0.4, PHP 5)
bzwrite — Escrita binary-safe em um arquivo bzip2
Descrição
bzwrite() escreve o conteúdo da string data no arquivo referenciado pelo ponteiro de arquivo bzip2 bz. Se o parâmetro opcional length for passado, a escrita irá parar depois deste número de bytes (descomprimidos) foram escritos ou se o final da string foi alcançado, o que acontecer primeiro.
Exemplo #1 Exemplo de bzwrite()
<?php
$str = "dados descomprimidos";
$bz = bzopen("/tmp/foo.bz2", "w");
bzwrite($bz, $str, strlen($str));
bzclose($bz);
?>
Índice
- bzclose — Fecha um ponteiro de arquivo bzip2
- bzcompress — Comprime uma string em dados no formato bzip2
- bzdecompress — Descomprime dados no formato bzip2
- bzerrno — Retorna um número de erro do bzip2
- bzerror — Retorna o número e string de erro do bzip2 em um array
- bzerrstr — Retorna a string de erro do bzip2
- bzflush — Força a escrita de todos os dados que estão no buffer
- bzopen — Abre um arquivo comprimido com bzip2
- bzread — Leitura binary-safe de um arquivo bzip2
- bzwrite — Escrita binary-safe em um arquivo bzip2
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Exemplos
- Bzip2 Funções
- bzclose — Fecha um ponteiro de arquivo bzip2
- bzcompress — Comprime uma string em dados no formato bzip2
- bzdecompress — Descomprime dados no formato bzip2
- bzerrno — Retorna um número de erro do bzip2
- bzerror — Retorna o número e string de erro do bzip2 em um array
- bzerrstr — Retorna a string de erro do bzip2
- bzflush — Força a escrita de todos os dados que estão no buffer
- bzopen — Abre um arquivo comprimido com bzip2
- bzread — Leitura binary-safe de um arquivo bzip2
- bzwrite — Escrita binary-safe em um arquivo bzip2
LZF
Introdução
LZF é um algoritmo de compressão muito rápido, ideal para economizar espaço com um pequeno custo de velocidade. Ele pode ser otimizado para velocidade ou espaço em tempo de compilação. Esta extensão está usando para suas operações a biblioteca » liblzf de Marc Lehmann.
Instalação/Configuração
Índice
Dependências
Nenhuma biblioteca externa é necessária para compilar esta extensão.
Instalação
Esta extensão » PECL não vem compilada com o PHP. Informações para a instalação desta extensão PECL podem ser encontradas no manual no capitulo intitulado Instalação de extensões PECL. Informações adicionais como novas versões, downloads, arquivos fontes, manutenções, e um Changelog, podem ser obtidos aqui: » http://pecl.php.net/package/lzf.
Para usar estas funções você precisa compilar PHP com suporte a lzf usando a opção de configuração --with-lzf[=DIR] . Você pode também passar --enable-lzf-better-compression para otimizar o LZF mais para espaço do que velocidade.
Usuários Windows podem habilitar php_lzf.dll no php.ini para usar estas funções. Uma DLL para esta extenção PECL esta atualmente indisponível. Veja também a seção compilando no Windows section.
Configurações em Execução
Esta extensão não define nenhum parâmetro de configuração no php.ini.
Tipos Resource
Esta extensão não possui nenhum tipo resource.
Constantes pré-definidas
Esta extensão não possui nenhuma constante.
Funções da LZF
lzf_compress
(PECL lzf >= 0.1.0)
lzf_compress — Compressão LZF
Descrição
lzf_compress() comprime a string data usando a codificação LZF.
Parâmetros
- data
-
Retorna a string comprimida.
Valor Retornado
Retorna a informação comprimida ou FALSE se um erro ocorreu.
lzf_decompress
(PECL lzf >= 0.1.0)
lzf_decompress — Descompressão LZF
Descrição
lzf_compress() decomprime a string data contendo dados com codificação lzf.
Parâmetros
- data
-
A string comprimida.
Valor Retornado
Retorna a informação decompressa ou FALSE se um erro ocorreu.
lzf_optimized_for
(PECL lzf >= 1.0.0)
lzf_optimized_for — Determina para que a extensão LZF foi otimizada
Descrição
Determina para que a extensão LZF foi otimizada durante a compilação.
Valor Retornado
Retorna 1 se LZF foi otimizada para velocidade, 0 para compressão.
Índice
- lzf_compress — Compressão LZF
- lzf_decompress — Descompressão LZF
- lzf_optimized_for — Determina para que a extensão LZF foi otimizada
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Funções da LZF
- lzf_compress — Compressão LZF
- lzf_decompress — Descompressão LZF
- lzf_optimized_for — Determina para que a extensão LZF foi otimizada
Phar
Introdução
The phar extension provides a way to put entire PHP applications into a single file called a "phar" (PHP Archive) for easy distribution and installation. In addition to providing this service, the phar extension also provides a file-format abstraction method for creating and manipulating tar and zip files through the PharData class, much as PDO provides a unified interface for accessing different databases. Unlike PDO, which cannot convert between different databases, Phar also can convert between tar, zip and phar file formats with a single line of code. see Phar::convertToExecutable() for one example.
What is phar? Phar archives are best characterized as a convenient way to group several files into a single file. As such, a phar archive provides a way to distribute a complete PHP application in a single file and run it from that file without the need to extract it to disk. Additionally, phar archives can be executed by PHP as easily as any other file, both on the commandline and from a web server. Phar is kind of like a thumb drive for PHP applications.
Phar implements this functionality through a Stream Wrapper. Normally, to use an external file within a PHP script, you would use include()
Exemplo #1 Using an external file
<?php
include '/path/to/external/file.php';
?>
PHP can be thought of as actually translating /path/to/external/file.php into a stream wrapper as file:///path/to/external/file.php, and under the hood it does in fact use the plain file stream wrapper stream functions to access all local files.
To use a file named file.php contained with a phar archive /path/to/myphar.phar, the syntax is very similar to the file:// syntax above.
Exemplo #2 Using a file within a phar archive
<?php
include 'phar:///path/to/myphar.phar/file.php';
?>
In fact, one can treat a phar archive exactly as if it were an external disk, using any of fopen()-related functions, opendir() and mkdir()-related functions to read, change, or create new files and directories within the phar archive. This allows complete PHP applications to be distributed in a single file and run directly from that file.
The most common usage for a phar archive is to distribute a complete application in a single file. For instance, the PEAR Installer that is bundled with PHP versions is distributed as a phar archive. To use a phar archive distributed in this way, the archive can be executed on the command-line or via a web server.
Phar archives can be distributed as tar archives, zip archives, or as the custom phar file format designed specifically for the phar extension. Each file format has advantages and disadvantages. The tar and zip file formats can be read or extracted by any third-party tool that can read the format, but require the phar extension in order to run with PHP. The phar file format is customized and unique to the phar extension, and can only be created by the phar extension or the PEAR package » PHP_Archive, but has the advantage that applications created in this format will run even if the phar extension is not enabled.
In other words, even with the phar extension disabled, one can execute or include a phar-based archive. Accessing individual files within a phar archive is only possible with the phar extension unless the phar archive was created by PHP_Archive.
The phar extension is also capable of converting a phar archive from tar to zip or to phar file format in a single command:
Exemplo #3 Converting a phar archive from phar to tar file format
<?php
$phar = new Phar('myphar.phar');
$pgz = $phar->convertToExecutable(Phar::TAR, Phar::GZ); // makes myphar.phar.tar.gz
?>
Phar can compress individual files or an entire archive using gzip compression or bzip2 compression, and can verify archive integrity automatically through the use of md5(), sha1(), sha256(), or sha512() signatures.
Lastly, the Phar extension is security-conscious, and disables write access to executable phar archives by default, and requires system-level disabling of the phar.readonly php.ini setting in order to create or modify phar archives. Normal tar and zip archives without an executable stub can always be created or modified using the PharData class.
If you are creating applications for distribution, you will want to read How to create Phar Archives. If you want more information on the differences between the three file formats that phar supports, you should read Phar, Tar and Zip.
If you are using phar applications, there are helpful tips in How to use Phar Archives
The word phar is a contraction of PHP and Archive and is based loosely on the jar (Java Archive) familiar to Java developers.
The implementation for Phar archives is based on the PEAR package » PHP_Archive, and the implementation details are similar, although the Phar extension is much more powerful. In addition, the Phar extension allows most PHP applications to be run unmodified while PHP_Archive-based phar archives often require extensive modification in order to work.
Instalação/Configuração
Índice
Dependências
Phar requires PHP 5.2.0 or newer. Additional features require the SPL extension in order to take advantage of iteration and array access to a Phar's file contents. The phar stream does not require any additional extensions to function.
You may optionally wish to enable the zlib and bzip2 extensions to take advantage of compressed phar support. In addition, to take advantage of OpenSSL signing, the OpenSSL extension must be enabled.
Note that a bug in the zlib.deflate stream filter fixed in PHP version 5.2.6 and newer may cause truncation of gzip and bzip2-compressed phar archives.
Instalação
The Phar extension is built into PHP as of PHP version 5.3.0. Phar may be installed via the PECL extension with previous PHP versions, and the » Phar PECL page contains further information and history.
Windows users must include the php_phar.dll file within php.ini to use this extension.
Configurações em Execução
O comportamento dessas funções podem ser modificado pelas configurações do php.ini.
| Nome | Padrão | Modificável | Histórico |
|---|---|---|---|
| phar.readonly | "1" | PHP_INI_ALL | |
| phar.require_hash | "1" | PHP_INI_ALL | |
| phar.extract_list | "" | PHP_INI_ALL | Available from phar 1.1.0 to 1.2.3, removed in 2.0.0. |
| phar.cache_list | "" | PHP_INI_SYSTEM | Available from phar 2.0.0. |
Breve descrição das diretivas de configuração.
- phar.readonly boolean
-
This option disables creation or modification of Phar archives using the phar stream or Phar object's write support. This setting should always be enabled on production machines, as the phar extension's convenient write support could allow straightforward creation of a php-based virus when coupled with other common security vulnerabilities.
Nota:
This setting can only be unset in php.ini due to security reasons. If phar.readonly is disabled in php.ini, the user may enable phar.readonly in a script or disable it later. If phar.readonly is enabled in php.ini, a script may harmlessly "re-enable" the INI variable, but may not disable it.
- phar.require_hash boolean
-
This option will force all opened Phar archives to contain some kind of signature (currently MD5, SHA1, SHA256 and SHA512 are supported), and will refuse to process any Phar archive that does not contain a signature.
Nota:
This setting can only be unset in php.ini due to security reasons. If phar.require_hash is disabled in php.ini, the user may enable phar.require_hash in a script or disable it later. If phar.require_hash is enabled in php.ini, a script may harmlessly "re-enable" the INI variable, but may not disable it.
This setting does not affect reading plain tar files with the PharData class.
- phar.extract_list string
-
This INI setting has been removed as of phar 2.0.0
Allows mappings from a full path to a phar archive or its alias to the location of its extracted files. The format of the parameter is name=archive,name2=archive2. This allows extraction of phar files to disk, and allows phar to act as a kind of mapper to extracted disk files. This is often done for performance reasons, or to assist with debugging a phar.
Exemplo #1 phar.extract_list usage example
in php.ini:
phar.extract_list = archive=/full/path/to/archive/,arch2=/full/path/to/arch2
<?php
include "phar://archive/content.php";
include "phar://arch2/foo.php";
?> - phar.cache_list string
-
This INI setting was added in phar 2.0.0
Allows mapping phar archives to be pre-parsed at web server startup, providing a performance improvement that brings running files out of a phar archive very close to the speed of running those files from a traditional disk-based installation.
Exemplo #2 phar.cache_list usage example
in php.ini (windows): phar.cache_list =C:\path\to\phar1.phar;C:\path\to\phar2.phar in php.ini (unix): phar.cache_list =/path/to/phar1.phar:/path/to/phar2.phar
Tipos Resource
The Phar extension provides the phar stream, which allows accessing files contained within a phar transparently. See also the description of the Phar file format.
Constantes pré-definidas
As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.
| Constant | Value | Description |
|---|---|---|
| Phar::NONE (integer) | 0x00000000 | no compression |
| Phar::COMPRESSED (integer) | 0x0000F000 | bitmask that can be used with file flags to determine if any compression is present |
| Phar::GZ (integer) | 0x00001000 | zlib (gzip) compression |
| Phar::BZ2 (integer) | 0x00002000 | bzip2 compression |
| Constant | Value | Description |
|---|---|---|
| Phar::SAME (integer) | 0 | retain the same file format |
| Phar::PHAR (integer) | 1 | phar file format |
| Phar::TAR (integer) | 2 | tar file format |
| Phar::ZIP (integer) | 3 | zip file format |
| Constant | Value | Description |
|---|---|---|
| Phar::MD5 (integer) | 0x0001 | signature with md5 hash algorithm |
| Phar::SHA1 (integer) | 0x0002 | signature with sha1 hash algorithm |
| Phar::SHA256 (integer) | 0x0003 | signature with sha256 hash algorithm (requires hash extension) |
| Phar::SHA512 (integer) | 0x0004 | signature with sha512 hash algorithm (requires hash extension) |
| Phar::OPENSSL (integer) | 0x0010 | signature with OpenSSL public/private key pair. This is a true, asymmetric key signature. |
| Constant | Value | Description |
|---|---|---|
| Phar::PHP (integer) | 1 | used to instruct the mimeoverrides parameter of Phar::webPhar() that the extension should be parsed as a PHP file |
| Phar::PHPS (integer) | 2 | used to instruct the mimeoverrides parameter of Phar::webPhar() that the extension should be parsed as a PHP source file through highlight_file() |
Using Phar Archives
Índice
- Using Phar Archives: Introduction
- Using Phar Archives: the phar stream wrapper
- Using Phar Archives: the Phar and PharData class
Using Phar Archives: Introduction
Phar archives are similar in concept to Java JAR archives, but are tailored to the needs and to the flexibility of PHP applications. A Phar archive is used to distribute a complete PHP application or library in a single file. A Phar archive application is used exactly like any other PHP application:
php coolapplication.phar
Using a Phar archive library is identical to using any other PHP library:
<?php
include 'coollibrary.phar';
?>
The phar stream wrapper provides the core of the phar extension, and is explained in detail here. The phar stream wrapper allows accessing the files within a phar archive using PHP's standard file functions fopen(), opendir(), and others that work on regular files. The phar stream wrapper supports all read/write operations on both files and directories.
<?php
include 'phar://coollibrary.phar/internal/file.php';
header('Content-type: image/jpeg');
// phars can be accessed by full path or by alias
echo file_get_contents('phar:///fullpath/to/coollibrary.phar/images/wow.jpg');
?>
The Phar class implements advanced functionality for accessing files and for creating phar archives. The Phar class is explained in detail here.
<?php
try {
// open an existing phar
$p = new Phar('coollibrary.phar', 0);
// Phar extends SPL's DirectoryIterator class
foreach (new RecursiveIteratorIterator($p) as $file) {
// $file is a PharFileInfo class, and inherits from SplFileInfo
echo $file->getFileName() . "\n";
echo file_get_contents($file->getPathName()) . "\n"; // display contents;
}
if (isset($p['internal/file.php'])) {
var_dump($p['internal/file.php']->getMetadata());
}
// create a new phar - phar.readonly must be 0 in php.ini
// phar.readonly is enabled by default for security reasons.
// On production servers, Phars need never be created,
// only executed.
if (Phar::canWrite()) {
$p = new Phar('newphar.tar.phar', 0, 'newphar.tar.phar');
// make this a tar-based phar archive, compressed with gzip compression (.tar.gz)
$p = $p->convertToExecutable(Phar::TAR, Phar::GZ);
// create transaction - nothing is written to newphar.phar
// until stopBuffering() is called, although temporary storage is needed
$p->startBuffering();
// add all files in /path/to/project, saving in the phar with the prefix "project"
$p->buildFromIterator(new RecursiveIteratorIterator(new DirectoryIterator('/path/to/project')), '/path/to/');
// add a new file via the array access API
$p['file1.txt'] = 'Information';
$fp = fopen('hugefile.dat', 'rb');
// copy all data from the stream
$p['data/hugefile.dat'] = $fp;
if (Phar::canCompress(Phar::GZ)) {
$p['data/hugefile.dat']->compress(Phar::GZ);
}
$p['images/wow.jpg'] = file_get_contents('images/wow.jpg');
// any value can be saved as file-specific meta-data
$p['images/wow.jpg']->setMetadata(array('mime-type' => 'image/jpeg'));
$p['index.php'] = file_get_contents('index.php');
$p->setMetadata(array('bootstrap' => 'index.php'));
// save the phar archive to disk
$p->stopBuffering();
}
} catch (Exception $e) {
echo 'Could not open Phar: ', $e;
}
?>
In addition, verification of phar file contents can be done using any of the supported symmetric hash algorithms (MD5, SHA1, SHA256 and SHA512 if ext/hash is enabled) and using asymmetric public/private key signing using OpenSSL (new in Phar 2.0.0). To take advantage of OpenSSL signing, you need to generate a public/private key pair, and use the private key to set the signature using Phar::setSignatureAlgorithm(). In addition, the public key as extracted using this code:
<?php
$public = openssl_get_publickey(file_get_contents('private.pem'));
$pkey = '';
openssl_pkey_export($public, $pkey);
?>
As of version 2.0.0, The Phar class also provides 3 static methods, Phar::webPhar(), Phar::mungServer() and Phar::interceptFileFuncs() that are crucial to packaging up PHP applications designed for usage on regular filesystems and for web-based applications. Phar::webPhar() implements a front controller that routes HTTP calls to the correct location within the phar archive. Phar::mungServer() is used to modify the values of the $_SERVER array to trick applications that process these values. Phar::interceptFileFuncs() instructs Phar to intercept calls to fopen(), file_get_contents(), opendir(), and all of the stat-based functions (file_exists(), is_readable() and so on) and route all relative paths to locations within the phar archive.
As an example, packaging up a release of the popular phpMyAdmin application for use as a phar archive requires only this simple script and then phpMyAdmin.phar.tar.php can be accessed as a regular file from your web server after modifying the user/password:
<?php
@unlink('phpMyAdmin.phar.tar.php');
copy('phpMyAdmin-2.11.3-english.tar.gz', 'phpMyAdmin.phar.tar.php');
$a = new Phar('phpMyAdmin.phar.tar.php');
$a->startBuffering();
$a["phpMyAdmin-2.11.3-english/config.inc.php"] = '<?php
/* Servers configuration */
$i = 0;
/* Server localhost (config:root) [1] */
$i++;
$cfg[\'Servers\'][$i][\'host\'] = \'localhost\';
$cfg[\'Servers\'][$i][\'extension\'] = \'mysqli\';
$cfg[\'Servers\'][$i][\'connect_type\'] = \'tcp\';
$cfg[\'Servers\'][$i][\'compress\'] = false;
$cfg[\'Servers\'][$i][\'auth_type\'] = \'config\';
$cfg[\'Servers\'][$i][\'user\'] = \'root\';
$cfg[\'Servers\'][$i][\'password\'] = \'\';
/* End of servers configuration */
if (strpos(PHP_OS, \'WIN\') !== false) {
$cfg[\'UploadDir\'] = getcwd();
} else {
$cfg[\'UploadDir\'] = \'/tmp/pharphpmyadmin\';
@mkdir(\'/tmp/pharphpmyadmin\');
@chmod(\'/tmp/pharphpmyadmin\', 0777);
}';
$a->setStub('<?php
Phar::interceptFileFuncs();
Phar::webPhar("phpMyAdmin.phar", "phpMyAdmin-2.11.3-english/index.php");
echo "phpMyAdmin is intended to be executed from a web browser\n";
exit -1;
__HALT_COMPILER();
');
$a->stopBuffering();
?>
Using Phar Archives: the phar stream wrapper
The Phar stream wrapper fully supports fopen() for read and write (not append), unlink(), stat(), fstat(), fseek(), rename() and directory stream operations opendir() and as of version 2.0.0, rmdir() and mkdir().
Individual file compression and per-file metadata can also be manipulated in a Phar archive using stream contexts:
<?php
$context = stream_context_create(array('phar' =>
array('compress' => Phar::GZ)),
array('metadata' => array('user' => 'cellog')));
file_put_contents('phar://my.phar/somefile.php', 0, $context);
?>
The phar stream wrapper does not operate on remote files, and cannot operate on remote files, and so is allowed even when the allow_url_fopen and allow_url_include INI options are disabled.
Although it is possible to create phar archives from scratch just using stream operations, it is best to use the functionality built into the Phar class. The stream wrapper is best used for read-only operations.
Using Phar Archives: the Phar and PharData class
The Phar class supports reading and manipulation of Phar archives, as well as iteration through inherited functionality of the RecursiveDirectoryIterator class. With support for the ArrayAccess interface, files inside a Phar archive can be accessed as if they were part of an associative array.
The PharData class extends the Phar, and allows creating and modifying non-executable (data) tar and zip archives even if phar.readonly=1 in php.ini. As such, PharData::setAlias() and PharData::setStub() are both disabled as the concept of alias and stub are unique to executable phar archives.
It is important to note that when creating a Phar archive, the full path should be passed to the Phar object constructor. Relative paths will fail to initialize.
Assuming that $p is a Phar object initialized as follows:
<?php
$p = new Phar('/path/to/myphar.phar', 0, 'myphar.phar');
?>
An empty Phar archive will be created at /path/to/myphar.phar, or if /path/to/myphar.phar already exists, it will be opened again. The literal myphar.phar demonstrates the concept of an alias that can be used to reference /path/to/myphar.phar in URLs as in:
<?php
// these two calls to file_get_contents() are equivalent if
// /path/to/myphar.phar has an explicit alias of "myphar.phar"
// in its manifest, or if the phar was initialized with the
// previous example's Phar object setup
$f = file_get_contents('phar:///path/to/myphar.phar/whatever.txt');
$f = file_get_contents('phar://myphar.phar/whatever.txt');
?>
With the newly created $p Phar object, the following is possible:
- $a = $p['file.php'] creates a PharFileInfo class that refers to the contents of phar://myphar.phar/file.php
- $p['file.php'] = $v creates a new file (phar://myphar.phar/file.php), or overwrites an existing file within myphar.phar. $v can be either a string or an open file pointer, in which case the entire contents of the file will be used to create the new file. Note that $p->addFromString('file.php', $v) is functionally equivalent to the above. Also possible is to add the contents of a file with $p->addFile('/path/to/file.php', 'file.php'). Lastly, an empty directory can be created with $p->addEmptyDir('empty').
- isset($p['file.php']) can be used to determine whether phar://myphar.phar/file.php exists within myphar.phar.
- unset($p['file.php']) erases phar://myphar.phar/file.php from myphar.phar.
In addition, the Phar object is the only way to access Phar-specific metadata, through Phar::getMetadata(), and the only way to set or retrieve a Phar archive's PHP loader stub through Phar::getStub() and Phar::setStub(). Additionally, compression for the entire Phar archive at once can only be manipulated using the Phar class.
The full list of Phar object functionality is documented below.
The PharFileInfo class extends the SplFileInfo class, and adds several methods for manipulating Phar-specific details of a file contained within a Phar, such as manipulating compression and metadata.
Creating Phar Archives
Índice
Creating Phar Archives: Introduction
To be written fully in the near future. Before reading this, be sure to read How to use Phar Archives.
A great place to start is by reading about Phar::buildFromIterator(), and the specifics of the file format choices available for archives. A healthy understanding of what a stub is and does is crucial to phar archive creation, and so Phar::setStub() and Phar::createDefaultStub() are good places to start as well. If you are distributing a web-based application, it is crucial to know about Phar::webPhar() and related method Phar::mungServer(). Any application that accesses its own files should also consider using Phar::interceptFileFuncs().
What makes a phar a phar and not a tar or a zip?
Índice
- Ingredients of all Phar archives, independent of file format
- Phar file stub
- Head-to-head comparison of Phar, Tar and Zip
- Tar-based phars
- Zip-based phars
- Phar File Format
- Global Phar bitmapped flags
- Phar manifest file entry definition
- Phar Signature format
Ingredients of all Phar archives, independent of file format
All Phar archives contain three to four sections:
-
a stub
-
a manifest describing the contents
-
the file contents
-
[optional] a signature for verifying Phar integrity (phar file format only)
Phar file stub
A Phar's stub is a simple PHP file. The smallest possible stub follows:
<?php __HALT_COMPILER();
A stub must contain as a minimum, the __HALT_COMPILER(); token at its conclusion. Typically, a stub will contain loader functionality like so:
<?php
Phar::mapPhar();
include 'phar://myphar.phar/index.php';
__HALT_COMPILER();
There are no restrictions on the contents of a Phar stub, except for the requirement
that it conclude with __HALT_COMPILER();. The closing PHP tag
?>
?>
In a tar or zip-based phar archive, the stub is stored in the .phar/stub.php file. The default stub for phar-based Phar archives contains approximately 7k of code to extract the contents of the phar and execute them. See Phar::createDefaultStub() for more detail.
The phar alias is stored in a tar or zip-based phar archive in the .phar/alias.txt file as plain text.
Head-to-head comparison of Phar, Tar and Zip
What are the good and the bad things about the three supported file formats in the phar extension? This table attempts to address that question.
| Feature | Phar | Tar | Zip |
|---|---|---|---|
| Standard File Format | No | Yes | Yes |
| Can be executed without the Phar Extension [1] | Yes | No | No |
| Per-file compression | Yes | No | Yes |
| Whole-archive compression | Yes | Yes | No |
| Whole-archive signature validation | Yes | Yes | Yes (PHP 5.3.1+) |
| Web-specific application support | Yes | Yes | Yes |
| Per-file Meta-data | Yes | Yes | Yes |
| Whole-Archive Meta-data | Yes | Yes | Yes |
| Archive creation/modification [2] | Yes | Yes | Yes |
| Full support for all stream wrapper functions | Yes | Yes | Yes |
| Can be created/modified even if phar.readonly=1 [3] | No | Yes | Yes |
[1] PHP can only directly access the contents of a Phar archive without the Phar extension if it is using a stub that extracts the contents of the phar archive. The stub created by Phar::createDefaultStub() extracts the phar archive and runs its contents from a temporary directory if no phar extension is found.
[2] All write access requires phar.readonly to be disabled in php.ini or on the command-line directly.
[3] Only tar and zip archives without .phar in their filename and without an executable stub .phar/stub.php can be created if phar.readonly=1.
Tar-based phars
Archives based on the tar file format follow the more modern USTAR file format. The design of the tar file header makes them more efficient to access than the zip file format, and almost as efficient as the phar file format. File names are limited to 255 bytes, including full path within the phar archive. There is no limit on the number of files within a tar-based phar archive. These archives can fully compressed in gzip or bzip2 format and still be executed by the Phar extension.
To compress an entire archive, use Phar::compress(). To decompress an entire archive, use Phar::decompress().
Zip-based phars
Archives based on the zip file format support several features built into the zip file format. Per-file and whole-archive metadata is stored in the zip file comment and zip archive comment as a serialized string. Pre-existing zip comments will be successfully read as a string. Per-file compression read/write is supported with zlib compression, and read access is supported with bzip2 compression. There is no limit on the number of files within a zip-based phar archive. Empty directories are stored in the zip archive as files with a trailing slash like my/directory/
Phar File Format
The phar file format is literally laid out as stub/manifest/contents/signature, and stores the crucial information of what is included in the phar archive in its manifest.
The Phar manifest is a highly optimized format that allows per-file specification of file compression, file permissions, and even user-defined meta-data such as file user or group. All values greater than 1 byte are stored in little-endian byte order, with the exception of the API version, which for historical reasons is stored as 3 nibbles in big-endian order.
All unused flags are reserved for future use, and must not be used to store custom information. Use the per-file meta-data facility to store customized information about particular files.
The basic file format of a Phar archive manifest is as follows:
| Size in bytes | Description |
|---|---|
| 4 bytes | Length of manifest in bytes (1 MB limit) |
| 4 bytes | Number of files in the Phar |
| 2 bytes | API version of the Phar manifest (currently 1.0.0) |
| 4 bytes | Global Phar bitmapped flags |
| 4 bytes | Length of Phar alias |
| ?? | Phar alias (length based on previous) |
| 4 bytes | Length of Phar metadata (0 for none) |
| ?? | Serialized Phar Meta-data, stored in serialize() format |
| at least 24 * number of entries bytes | entries for each file |
Global Phar bitmapped flags
Here are the bitmapped flags currently recognized by the Phar extension for the global Phar flat bitmap:
| Value | Description |
|---|---|
| 0x00010000 | If set, this Phar contains a verification signature |
| 0x00001000 | If set, this Phar contains at least 1 file that is compressed with zlib compression |
| 0x00002000 | If set, this Phar contains at least 1 file that is compressed with bzip compression |
Phar manifest file entry definition
Each file in the manifest contains the following information:
| Size in bytes | Description |
|---|---|
| 4 bytes | Filename length in bytes |
| ?? | Filename (length specified in previous) |
| 4 bytes | Un-compressed file size in bytes |
| 4 bytes | Unix timestamp of file |
| 4 bytes | Compressed file size in bytes |
| 4 bytes | CRC32 checksum of un-compressed file contents |
| 4 bytes | Bit-mapped File-specific flags |
| 4 bytes | Serialized File Meta-data length (0 for none) |
| ?? | Serialized File Meta-data, stored in serialize() format |
Note that as of API version 1.1.1, empty directories are stored as filenames with a trailing slash like my/directory/
The File-specific bitmap values recognized are:
| Value | Description |
|---|---|
| 0x000001FF | These bits are reserved for defining specific file permissions of a file. Permissions are used for fstat() and can be used to recreate desired permissions upon extraction. |
| 0x00001000 | If set, this file is compressed with zlib compression |
| 0x00002000 | If set, this file is compressed with bzip compression |
Phar Signature format
Phars containing a signature always have the signature appended to the end of the Phar archive after the loader, manifest, and file contents. The two signature formats supported at this time are MD5 and SHA1.
| Length in bytes | Description |
|---|---|
| 16 or 20 bytes | The actual signature, 20 bytes for an SHA1 signature, 16 bytes for an MD5 signature, 32 bytes for an SHA256 signature, and 64 bytes for an SHA512 signature. |
| 4 bytes | Signature flags. 0x0001 is used to define an MD5 signature, 0x0002 is used to define an SHA1 signature, 0x0004 is used to define an SHA256 signature, and 0x0008 is used to define an SHA512 signature. The SHA256 and SHA512 signature support was introduced with API version 1.1.0. |
| 4 bytes | Magic GBMB used to define the presence of a signature. |
The Phar class
(No version information available, might only be in SVN)
Introdução
The Phar class provides a high-level interface to accessing and creating phar archives.
Sinopse da classe
Phar::addEmptyDir
(Unknown)
Phar::addEmptyDir — Add an empty directory to the phar archive
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
With this method, an empty directory is created with path dirname. This method is similar to ZipArchive::addEmptyDir().
Parâmetros
- dirname
-
The name of the empty directory to create in the phar archive
Valor Retornado
no return value, exception is thrown on failure.
Exemplos
Exemplo #1 A Phar::addEmptyDir() example
<?php
try {
$a = new Phar('/path/to/phar.phar');
$a->addEmptyDir('/full/path/to/file');
// demonstrates how this file is stored
$b = $a['full/path/to/file']->isDir();
} catch (Exception $e) {
// handle errors here
}
?>
Veja Também
- PharData::addEmptyDir() - Add an empty directory to the tar/zip archive
- Phar::addFile() - Add a file from the filesystem to the phar archive
- Phar::addFromString() - Add a file from the filesystem to the phar archive
Phar::addFile
(Unknown)
Phar::addFile — Add a file from the filesystem to the phar archive
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
With this method, any file or URL can be added to the phar archive. If the optional second parameter localname is specified, the file will be stored in the archive with that name, otherwise the file parameter is used as the path to store within the archive. URLs must have a localname or an exception is thrown. This method is similar to ZipArchive::addFile().
Parâmetros
- file
-
Full or relative path to a file on disk to be added to the phar archive.
- localname
-
Path that the file will be stored in the archive.
Valor Retornado
no return value, exception is thrown on failure.
Exemplos
Exemplo #1 A Phar::addFile() example
<?php
try {
$a = new Phar('/path/to/phar.phar');
$a->addFile('/full/path/to/file');
// demonstrates how this file is stored
$b = $a['full/path/to/file']->getContent();
$a->addFile('/full/path/to/file', 'my/file.txt');
$c = $a['my/file.txt']->getContent();
// demonstrate URL usage
$a->addFile('http://www.example.com', 'example.html');
} catch (Exception $e) {
// handle errors here
}
?>
Veja Também
- Phar::offsetSet() - set the contents of an internal file to those of an external file
- PharData::addFile() - Add a file from the filesystem to the tar/zip archive
- Phar::addFromString() - Add a file from the filesystem to the phar archive
- Phar::addEmptyDir() - Add an empty directory to the phar archive
Phar::addFromString
(Unknown)
Phar::addFromString — Add a file from the filesystem to the phar archive
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
With this method, any string can be added to the phar archive. The file will be stored in the archive with localname as its path. This method is similar to ZipArchive::addFromString().
Parâmetros
- localname
-
Path that the file will be stored in the archive.
- contents
-
The file contents to store
Valor Retornado
no return value, exception is thrown on failure.
Exemplos
Exemplo #1 A Phar::addFromString() example
<?php
try {
$a = new Phar('/path/to/phar.phar');
$a->addFromString('path/to/file.txt', 'my simple file');
$b = $a['path/to/file.txt']->getContent();
// to add contents from a stream handle for large files, use offsetSet()
$c = fopen('/path/to/hugefile.bin');
$a['largefile.bin'] = $c;
fclose($c);
} catch (Exception $e) {
// handle errors here
}
?>
Veja Também
- Phar::offsetSet() - set the contents of an internal file to those of an external file
- PharData::addFromString() - Add a file from the filesystem to the tar/zip archive
- Phar::addFile() - Add a file from the filesystem to the phar archive
- Phar::addEmptyDir() - Add an empty directory to the phar archive
Phar::apiVersion
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::apiVersion — Returns the api version
Descrição
Return the API version of the phar file format that will be used when creating phars. The Phar extension supports reading API version 1.0.0 or newer. API version 1.1.0 is required for SHA-256 and SHA-512 hash, and API version 1.1.1 is required to store empty directories.
Parâmetros
Valor Retornado
The API version string as in "1.0.0".
Exemplos
Exemplo #1 A Phar::apiVersion() example
<?php
echo Phar::apiVersion();
?>
O exemplo acima irá imprimir:
1.1.1
Phar::buildFromDirectory
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::buildFromDirectory — Construct a phar archive from the files within a directory.
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
Populate a phar archive from directory contents. The optional second parameter is a regular expression (pcre) that is used to exclude files. Any filename that matches the regular expression will be included, all others will be excluded. For more fine-grained control, use Phar::buildFromIterator().
Parâmetros
- base_dir
-
The full or relative path to the directory that contains all files to add to the archive.
- regex
-
An optional pcre regular expression that is used to filter the list of files. Only file paths matching the regular expression will be included in the archive.
Valor Retornado
Phar::buildFromDirectory() returns an associative array mapping internal path of file to the full path of the file on the filesystem.
Erros
This method throws BadMethodCallException when unable to instantiate the internal directory iterators, or a PharException if there were errors saving the phar archive.
Exemplos
Exemplo #1 A Phar::buildFromDirectory() example
<?php
// create with alias "project.phar"
$phar = new Phar('project.phar', 0, 'project.phar');
// add all files in the project
$phar->buildFromDirectory(dirname(__FILE__) . '/project');
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
$phar2 = new Phar('project2.phar', 0, 'project2.phar');
// add all files in the project, only include php files
$phar2->buildFromDirectory(dirname(__FILE__) . '/project', '/\.php$/');
$phar2->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>
Phar::buildFromIterator
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::buildFromIterator — Construct a phar archive from an iterator.
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
Populate a phar archive from an iterator. Two styles of iterators are supported, iterators that map the filename within the phar to the name of a file on disk, and iterators like DirectoryIterator that return SplFileInfo objects. For iterators that return SplFileInfo objects, the second parameter is required.
Parâmetros
- iter
-
Any iterator that either associatively maps phar file to location or returns SplFileInfo objects
- base_directory
-
For iterators that return SplFileInfo objects, the portion of each file's full path to remove when adding to the phar archive
Valor Retornado
Phar::buildFromIterator() returns an associative array mapping internal path of file to the full path of the file on the filesystem.
Exemplos
Exemplo #1 A Phar::buildFromIterator() with SplFileInfo
For most phar archives, the archive will reflect an actual directory layout, and the second style is the most useful. For instance, to create a phar archive containing the files in this sample directory layout:
/path/to/project/
config/
dist.xml
debug.xml
lib/
file1.php
file2.php
src/
processthing.php
www/
index.php
cli/
index.php
This code could be used to add these files to the "project.phar" phar archive:
<?php
// create with alias "project.phar"
$phar = new Phar('project.phar', 0, 'project.phar');
$phar->buildFromIterator(
new RecursiveIteratorIterator(
new RecursiveDirectoryIterator('/path/to/project')),
'/path/to/project');
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>
The file project.phar can then be used immediately. Phar::buildFromIterator() does not set values such as compression, metadata, and this can be done after creating the phar archive.
As an interesting note, Phar::buildFromIterator() can also be used to copy the contents of an existing phar archive, as the Phar object descends from DirectoryIterator:
<?php
// create with alias "project.phar"
$phar = new Phar('project.phar', 0, 'project.phar');
$phar->buildFromIterator(
new RecursiveIteratorIterator(
new Phar('/path/to/anotherphar.phar')),
'phar:///path/to/anotherphar.phar/path/to/project');
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>
Exemplo #2 A Phar::buildFromIterator() with other iterators
The second form of the iterator can be used with any iterator that returns a key => value mapping, such as an ArrayIterator:
<?php
// create with alias "project.phar"
$phar = new Phar('project.phar', 0, 'project.phar');
$phar->buildFromIterator(
new ArrayIterator(
array(
'internal/file.php' => dirname(__FILE__) . '/somefile.php',
'another/file.jpg' => fopen('/path/to/bigfile.jpg', 'rb'),
)));
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>
Erros
This method returns UnexpectedValueException when the iterator returns incorrect values, such as an integer key instead of a string, a BadMethodCallException when an SplFileInfo-based iterator is passed without a base_directory parameter, or a PharException if there were errors saving the phar archive.
Veja Também
- Phar::buildFromDirectory() - Construct a phar archive from the files within a directory.
Phar::canCompress
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::canCompress — Returns whether phar extension supports compression using either zlib or bzip2
Descrição
This should be used to test whether compression is possible prior to loading a phar archive containing compressed files.
Parâmetros
- type
-
Either Phar::GZ or Phar::BZ2 can be used to test whether compression is possible with a specific compression algorithm (zlib or bzip2).
Valor Retornado
TRUE if compression/decompression is available, FALSE if not.
Exemplos
Exemplo #1 A Phar::canCompress() example
<?php
if (Phar::canCompress()) {
echo file_get_contents('phar://compressedphar.phar/internal/file.txt');
} else {
echo 'no compression available';
}
?>
Veja Também
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressFiles() - Compresses all files in the current Phar archive
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::convertToExecutable() - Convert a phar archive to another executable phar archive file format
- Phar::convertToData() - Convert a phar archive to a non-executable tar or zip file
Phar::canWrite
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::canWrite — Returns whether phar extension supports writing and creating phars
Descrição
This static method determines whether write access has been disabled in the system php.ini via the phar.readonly ini variable.
Parâmetros
Valor Retornado
TRUE if write access is enabled, FALSE if it is disabled.
Exemplos
Exemplo #1 A Phar::canWrite() example
<?php
if (Phar::canWrite()) {
file_put_contents('phar://myphar.phar/file.txt', 'hi there');
}
?>
Phar::compress
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::compress — Compresses the entire Phar archive using Gzip or Bzip2 compression
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
For tar-based and phar-based phar archives, this method compresses the entire archive using gzip compression or bzip2 compression. The resulting file can be processed with the gunzip command/bunzip command, or accessed directly and transparently with the Phar extension.
For Zip-based phar archives, this method fails with an exception. The zlib extension must be enabled to compress with gzip compression, the bzip2 extension must be enabled in order to compress with bzip2 compression. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed.
In addition, this method automatically renames the archive, appending .gz, .bz2 or removing the extension if passed Phar::NONE to remove compression. Alternatively, a file extension may be specified with the second parameter.
Parâmetros
- compression
-
Compression must be one of Phar::GZ, Phar::BZ2 to add compression, or Phar::NONE to remove compression.
- extension
-
By default, the extension is .phar.gz or .phar.bz2 for compressing phar archives, and .phar.tar.gz or .phar.tar.bz2 for compressing tar archives. For decompressing, the default file extensions are .phar and .phar.tar.
Valor Retornado
Returns a Phar object.
Erros
Throws BadMethodCallException if the phar.readonly INI variable is on, the zlib extension is not available, or the bzip2 extension is not enabled.
Exemplos
Exemplo #1 A Phar::compress() example
<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p1 = $p->compress(Phar::GZ); // copies to /path/to/my.phar.gz
$p2 = $p->compress(Phar::BZ2); // copies to /path/to/my.phar.bz2
$p3 = $p2->compress(Phar::NONE); // exception: /path/to/my.phar already exists
?>
Veja Também
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- PharData::compress() - Compresses the entire tar/zip archive using Gzip or Bzip2 compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::decompress() - Decompresses the entire Phar archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::compressFiles() - Compresses all files in the current Phar archive
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
Phar::compressAllFilesBZIP2
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::compressAllFilesBZIP2 — Compresses all files in the current Phar archive using Bzip2 compression
Descrição
Nota:
Este método tem sido removido da extensão phar a partir da versão 2.0.0. Implementações alternativas são possíveis usando Phar::compress(), Phar::decompress(), Phar::compressFiles() e Phar::decompressFiles().
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
This method compresses all files in the Phar archive using bzip2 compression. The bzip2 extension must be enabled to take advantage of this feature. In addition, if any files are already compressed using gzip compression, the zlib extension must be enabled in order to decompress the files prior to re-compressing with bzip2 compression. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Erros
Throws BadMethodCallException if the phar.readonly INI variable is on, the bzip2 extension is not available, or if any files are compressed using gzip compression and the zlib extension is not enabled.
Exemplos
Exemplo #1 A Phar::compressAllFilesBZIP2() example
<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressedBZIP2());
var_dump($file->isCompressedGZ());
}
$p->compressAllFilesBZIP2();
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressedBZIP2());
var_dump($file->isCompressedGZ());
}
?>
O exemplo acima irá imprimir:
string(10) "myfile.txt" bool(false) bool(false) bool(false) string(11) "myfile2.txt" bool(false) bool(false) bool(false) string(10) "myfile.txt" bool(true) bool(true) bool(false) string(11) "myfile2.txt" bool(true) bool(true) bool(false)
Veja Também
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressedBZIP2() - Returns whether the entry is compressed using bzip2
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::isCompressedGZ() - Returns whether the entry is compressed using gz
- PharFileInfo::setCompressedBZIP2() - Compresses the current Phar entry within the phar using Bzip2 compression
- PharFileInfo::setUncompressed() - Uncompresses the current Phar entry within the phar, if it is compressed
- PharFileInfo::setCompressedGZ() - Compresses the current Phar entry within the phar using gz compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressAllFilesGZ() - Compresses all files in the current Phar archive using Gzip compression
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::uncompressAllFiles() - Uncompresses all files in the current Phar archive
Phar::compressAllFilesGZ
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::compressAllFilesGZ — Compresses all files in the current Phar archive using Gzip compression
Descrição
Nota:
Este método tem sido removido da extensão phar a partir da versão 2.0.0. Implementações alternativas são possíveis usando Phar::compress(), Phar::decompress(), Phar::compressFiles() e Phar::decompressFiles().
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
For tar-based phar archives, this method compresses the entire archive using gzip compression. The resulting file can be processed with the gunzip command, or accessed directly and transparently with the Phar extension.
For Zip-based and phar-based phar archives, this method compresses all files in the Phar archive using gzip compression. The zlib extension must be enabled to take advantage of this feature. In addition, if any files are already compressed using bzip2 compression, the bzip2 extension must be enabled in order to decompress the files prior to re-compressing with gzip compression. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Erros
Throws BadMethodCallException if the phar.readonly INI variable is on, the zlib extension is not available, or if any files are compressed using bzip2 compression and the bzip2 extension is not enabled.
Exemplos
Exemplo #1 A Phar::compressAllFilesGZ() example
<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressedBZIP2());
var_dump($file->isCompressedGZ());
}
$p->compressAllFilesGZ();
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressedBZIP2());
var_dump($file->isCompressedGZ());
}
?>
O exemplo acima irá imprimir:
string(10) "myfile.txt" bool(false) bool(false) bool(false) string(11) "myfile2.txt" bool(false) bool(false) bool(false) string(10) "myfile.txt" bool(true) bool(false) bool(true) string(11) "myfile2.txt" bool(true) bool(false) bool(true)
Veja Também
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressedBZIP2() - Returns whether the entry is compressed using bzip2
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::isCompressedGZ() - Returns whether the entry is compressed using gz
- PharFileInfo::setCompressedBZIP2() - Compresses the current Phar entry within the phar using Bzip2 compression
- PharFileInfo::setUncompressed() - Uncompresses the current Phar entry within the phar, if it is compressed
- PharFileInfo::setCompressedGZ() - Compresses the current Phar entry within the phar using gz compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressAllFilesBZIP2() - Compresses all files in the current Phar archive using Bzip2 compression
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::uncompressAllFiles() - Uncompresses all files in the current Phar archive
Phar::compressFiles
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::compressFiles — Compresses all files in the current Phar archive
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
For tar-based phar archives, this method throws a BadMethodCallException, as compression of individual files within a tar archive is not supported by the file format. Use Phar::compress() to compress an entire tar-based phar archive.
For Zip-based and phar-based phar archives, this method compresses all files in the Phar archive using the specified compression. The zlib or bzip2 extensions must be enabled to take advantage of this feature. In addition, if any files are already compressed using bzip2/zlib compression, the respective extension must be enabled in order to decompress the files prior to re-compressing. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed.
Parâmetros
- compression
-
Compression must be one of Phar::GZ, Phar::BZ2 to add compression, or Phar::NONE to remove compression.
Valor Retornado
Não há valor retornado.
Erros
Throws BadMethodCallException if the phar.readonly INI variable is on, the zlib extension is not available, or if any files are compressed using bzip2 compression and the bzip2 extension is not enabled.
Exemplos
Exemplo #1 A Phar::compressFiles() example
<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressed(Phar::BZ2));
var_dump($file->isCompressed(Phar::GZ));
}
$p->compressFiles(Phar::GZ);
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressed(Phar::BZ2));
var_dump($file->isCompressed(Phar::GZ));
}
?>
O exemplo acima irá imprimir:
string(10) "myfile.txt" bool(false) bool(false) bool(false) string(11) "myfile2.txt" bool(false) bool(false) bool(false) string(10) "myfile.txt" int(4096) bool(false) bool(true) string(11) "myfile2.txt" int(4096) bool(false) bool(true)
Veja Também
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::decompress() - Decompresses the entire Phar archive
Phar::__construct
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::__construct — Construct a Phar archive object
Descrição
Parâmetros
- fname
-
Path to an existing Phar archive or to-be-created archive
- flags
-
Flags to pass to parent class RecursiveDirectoryIterator.
- alias
-
Alias with which this Phar archive should be referred to in calls to stream functionality.
Erros
Throws BadMethodCallException if called twice, UnexpectedValueException if the phar archive can't be opened.
Exemplos
Exemplo #1 A Phar::__construct() example
<?php
try {
$p = new Phar('/path/to/my.phar', CURRENT_AS_FILEINFO | KEY_AS_FILENAME,
'my.phar');
} catch (UnexpectedValueException $e) {
die('Could not open my.phar');
} catch (BadMethodCallException $e) {
echo 'technically, this cannot happen';
}
// this works now
echo file_get_contents('phar://my.phar/example.txt');
// and works as if we had typed
echo file_get_contents('phar:///path/to/my.phar/example.txt');
?>
Phar::convertToData
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::convertToData — Convert a phar archive to a non-executable tar or zip file
Descrição
This method is used to convert an executable phar archive to either a tar or zip file. To make the tar or zip non-executable, the phar stub and phar alias files are removed from the newly created archive.
If no changes are specified, this method throws a BadMethodCallException if the archive is in phar file format. For archives in tar or zip file format, this method converts the archive to a non-executable archive.
If successful, the method creates a new archive on disk and returns a PharData object. The old archive is not removed from disk, and should be done manually after the process has finished.
Parâmetros
- format
-
This should be one of Phar::TAR or Phar::ZIP. If set to NULL, the existing file format will be preserved.
- compression
-
This should be one of Phar::NONE for no whole-archive compression, Phar::GZ for zlib-based compression, and Phar::BZ2 for bzip-based compression.
- extension
-
This parameter is used to override the default file extension for a converted archive. Note that .phar cannot be used anywhere in the filename for a non-executable tar or zip archive.
If converting to a tar-based phar archive, the default extensions are .tar, .tar.gz, and .tar.bz2 depending on specified compression. For zip-based archives, the default extension is .zip.
Valor Retornado
The method returns a PharData object on success and throws an exception on failure.
Erros
This method throws BadMethodCallException when unable to compress, an unknown compression method has been specified, the requested archive is buffering with Phar::startBuffering() and has not concluded with Phar::stopBuffering(), and a PharException if any problems are encountered during the phar creation process.
Exemplos
Exemplo #1 A Phar::convertToData() example
Using Phar::convertToData():
<?php
try {
$tarphar = new Phar('myphar.phar.tar');
// note that myphar.phar.tar is *not* unlinked
// convert it to the non-executable tar file format
// creates myphar.tar
$tar = $tarphar->convertToData();
// convert to non-executable zip format, creates myphar.zip
$zip = $tarphar->convertToData(Phar::ZIP);
// create myphar.tbz
$tgz = $tarphar->convertToData(Phar::TAR, Phar::BZ2, '.tbz');
// creates myphar.phar.tgz
$phar = $tarphar->convertToData(Phar::PHAR); // throws exception
} catch (Exception $e) {
// handle the error here
}
?>
Veja Também
- Phar::convertToExecutable() - Convert a phar archive to another executable phar archive file format
- PharData::convertToExecutable() - Convert a non-executable tar/zip archive to an executable phar archive
- PharData::convertToData() - Convert a phar archive to a non-executable tar or zip file
Phar::convertToExecutable
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::convertToExecutable — Convert a phar archive to another executable phar archive file format
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
This method is used to convert a phar archive to another file format. For instance, it can be used to create a tar-based executable phar archive from a zip-based executable phar archive, or from an executable phar archive in the phar file format. In addition, it can be used to apply whole-archive compression to a tar or phar-based archive.
If no changes are specified, this method throws a BadMethodCallException.
If successful, the method creates a new archive on disk and returns a Phar object. The old archive is not removed from disk, and should be done manually after the process has finished.
Parâmetros
- format
-
This should be one of Phar::PHAR, Phar::TAR, or Phar::ZIP. If set to NULL, the existing file format will be preserved.
- compression
-
This should be one of Phar::NONE for no whole-archive compression, Phar::GZ for zlib-based compression, and Phar::BZ2 for bzip-based compression.
- extension
-
This parameter is used to override the default file extension for a converted archive. Note that all zip- and tar-based phar archives must contain .phar in their file extension in order to be processed as a phar archive.
If converting to a phar-based archive, the default extensions are .phar, .phar.gz, or .phar.bz2 depending on the specified compression. For tar-based phar archives, the default extensions are .phar.tar, .phar.tar.gz, and .phar.tar.bz2. For zip-based phar archives, the default extension is .phar.zip.
Valor Retornado
The method returns a Phar object on success and throws an exception on failure.
Erros
This method throws BadMethodCallException when unable to compress, an unknown compression method has been specified, the requested archive is buffering with Phar::startBuffering() and has not concluded with Phar::stopBuffering(), an UnexpectedValueException if write support is disabled, and a PharException if any problems are encountered during the phar creation process.
Exemplos
Exemplo #1 A Phar::convertToExecutable() example
Using Phar::convertToExecutable():
<?php
try {
$tarphar = new Phar('myphar.phar.tar');
// convert it to the phar file format
// note that myphar.phar.tar is *not* unlinked
$phar = $tarphar->convertToExecutable(Phar::PHAR); // creates myphar.phar
$phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
// creates myphar.phar.tgz
$compressed = $phar->convertToExecutable(Phar::TAR, Phar::GZ, '.phar.tgz');
} catch (Exception $e) {
// handle the error here
}
?>
Veja Também
- Phar::convertToData() - Convert a phar archive to a non-executable tar or zip file
- PharData::convertToExecutable() - Convert a non-executable tar/zip archive to an executable phar archive
- PharData::convertToData() - Convert a phar archive to a non-executable tar or zip file
Phar::copy
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::copy — Copy a file internal to the phar archive to another new file within the phar
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
Copy a file internal to the phar archive to another new file within the phar. This is an object-oriented alternative to using copy() with the phar stream wrapper.
Parâmetros
- oldfile
-
- newfile
-
Valor Retornado
returns TRUE on success, but it is safer to encase method call in a try/catch block and assume success if no exception is thrown.
Erros
throws UnexpectedValueException if the source file does not exist, the destination file already exists, write access is disabled, opening either file fails, reading the source file fails, or a PharException if writing the changes to the phar fails.
Exemplos
Exemplo #1 A Phar::copy() example
This example shows using Phar::copy() and the equivalent stream wrapper performance of the same thing. The primary difference between the two approaches is error handling. All Phar methods throw exceptions, whereas the stream wrapper uses trigger_error().
<?php
try {
$phar = new Phar('myphar.phar');
$phar['a'] = 'hi';
$phar->copy('a', 'b');
echo $phar['b']; // outputs "hi"
} catch (Exception $e) {
// handle error
}
// the stream wrapper equivalent of the above code.
// E_WARNINGS are triggered on error rather than exceptions.
copy('phar://myphar.phar/a', 'phar//myphar.phar/c');
echo file_get_contents('phar://myphar.phar/c'); // outputs "hi"
?>
Phar::count
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::count — Returns the number of entries (files) in the Phar archive
Descrição
Parâmetros
Valor Retornado
The number of files contained within this phar, or 0 (the number zero) if none.
Exemplos
Exemplo #1 A Phar::count() example
<?php
// make sure it doesn't exist
@unlink('brandnewphar.phar');
try {
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
} catch (Exception $e) {
echo 'Could not create phar:', $e;
}
echo 'The new phar has ' . $p->count() . " entries\n";
$p['file.txt'] = 'hi';
echo 'The new phar has ' . $p->count() . " entries\n";
?>
O exemplo acima irá imprimir:
The new phar has 0 entries The new phar has 1 entries
Phar::createDefaultStub
(Unknown)
Phar::createDefaultStub — Create a phar-file format specific stub
Descrição
This method is intended for creation of phar-file format-specific stubs, and is not intended for use with tar- or zip-based phar archives.
Phar archives contain a bootstrap loader, or stub written in PHP that is executed when the archive is executed in PHP either via include:
<?php
include 'myphar.phar';
?>
php myphar.phar
This method provides a simple and easy method to create a stub that will run a startup file from the phar archive. In addition, different files can be specified for running the phar archive from the command line versus through a web server. The loader stub also calls Phar::interceptFileFuncs() to allow easy bundling of a PHP application that accesses the file system. If the phar extension is not present, the loader stub will extract the phar archive to a temporary directory and then operate on the files. A shutdown function erases the temporary files on exit.
Valor Retornado
Returns a string containing the contents of a customized bootstrap loader (stub) that allows the created Phar archive to work with or without the Phar extension enabled.
Erros
Throws UnexpectedValueException if either parameter is longer than 400 bytes.
Exemplos
Exemplo #1 A Phar::createDefaultStub() example
<?php
try {
$phar = new Phar('myphar.phar');
$phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
} catch (Exception $e) {
// handle errors
}
?>
Veja Também
- Phar::setStub() - Used to set the PHP loader or bootstrap stub of a Phar archive
- Phar::getStub() - Return the PHP loader or bootstrap stub of a Phar archive
Phar::decompress
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::decompress — Decompresses the entire Phar archive
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
For tar-based and phar-based phar archives, this method decompresses the entire archive.
For Zip-based phar archives, this method fails with an exception. The zlib extension must be enabled to decompress an archive compressed with gzip compression, and the bzip2 extension must be enabled in order to decompress an archive compressed with bzip2 compression. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed.
In addition, this method automatically changes the file extension of the archive, .phar by default for phar archives, or .phar.tar for tar-based phar archives. Alternatively, a file extension may be specified with the second parameter.
Parâmetros
- extension
-
For decompressing, the default file extensions are .phar and .phar.tar. Use this parameter to specify another file extension. Be aware that all executable phar archives must contain .phar in their filename.
Valor Retornado
A Phar object is returned.
Erros
Throws BadMethodCallException if the phar.readonly INI variable is on, the zlib extension is not available, or the bzip2 extension is not enabled.
Exemplos
Exemplo #1 A Phar::decompress() example
<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar.gz');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p3 = $p2->decompress(); // creates /path/to/my.phar
?>
Veja Também
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- PharData::compress() - Compresses the entire tar/zip archive using Gzip or Bzip2 compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::compressFiles() - Compresses all files in the current Phar archive
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
Phar::decompressFiles
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::decompressFiles — Decompresses all files in the current Phar archive
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
For tar-based phar archives, this method throws a BadMethodCallException, as compression of individual files within a tar archive is not supported by the file format. Use Phar::compress() to compress an entire tar-based phar archive.
For Zip-based and phar-based phar archives, this method decompresses all files in the Phar archive. The zlib or bzip2 extensions must be enabled to take advantage of this feature if any files are compressed using bzip2/zlib compression. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Erros
Throws BadMethodCallException if the phar.readonly INI variable is on, the zlib extension is not available, or if any files are compressed using bzip2 compression and the bzip2 extension is not enabled.
Exemplos
Exemplo #1 A Phar::decompressFiles() example
<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p->compressFiles(Phar::GZ);
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressed(Phar::BZ2));
var_dump($file->isCompressed(Phar::GZ));
}
$p->decompressFiles();
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressed(Phar::BZ2));
var_dump($file->isCompressed(Phar::GZ));
}
?>
O exemplo acima irá imprimir:
string(10) "myfile.txt" int(4096) bool(false) bool(true) string(11) "myfile2.txt" int(4096) bool(false) bool(true) string(10) "myfile.txt" bool(false) bool(false) bool(false) string(11) "myfile2.txt" bool(false) bool(false) bool(false)
Veja Também
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressFiles() - Compresses all files in the current Phar archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::decompress() - Decompresses the entire Phar archive
Phar::delMetadata
(PHP >= 5.3.0, PECL phar >= 1.2.0)
Phar::delMetadata — Deletes the global metadata of the phar
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
Deletes the global metadata of the phar
Parâmetros
Valor Retornado
returns TRUE on success, but it is better to check for thrown exception, and assume success if none is thrown.
Erros
Throws PharException if errors occur while flushing changes to disk.
Exemplos
Exemplo #1 A Phar::delMetaData() example
<?php
try {
$phar = new Phar('myphar.phar');
var_dump($phar->getMetadata());
$phar->setMetadata("hi there");
var_dump($phar->getMetadata());
$phar->delMetadata();
var_dump($phar->getMetadata());
} catch (Exception $e) {
// handle errors
}
?>
O exemplo acima irá imprimir:
NULL string(8) "hi there" NULL
Veja Também
- Phar::getMetadata() - Returns phar archive meta-data
- Phar::setMetadata() - Sets phar archive meta-data
- Phar::hasMetadata() - Returns whether phar has global meta-data
Phar::delete
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::delete — Delete a file within a phar archive
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
Delete a file within an archive. This is the functional equivalent of calling unlink() on the stream wrapper equivalent, as shown in the example below.
Parâmetros
- entry
-
Path within an archive to the file to delete.
Valor Retornado
returns TRUE on success, but it is better to check for thrown exception, and assume success if none is thrown.
Erros
Throws PharException if errors occur while flushing changes to disk.
Exemplos
Exemplo #1 A Phar::delete() example
<?php
try {
$phar = new Phar('myphar.phar');
$phar->delete('unlink/me.php');
// this is equivalent to:
unlink('phar://myphar.phar/unlink/me.php');
} catch (Exception $e) {
// handle errors
}
?>
Veja Também
- PharData::delete() - Delete a file within a tar/zip archive
- Phar::unlinkArchive() - Completely remove a phar archive from disk and from memory
Phar::extractTo
(Unknown)
Phar::extractTo — Extract the contents of a phar archive to a directory
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
Extract all files within a phar archive to disk. Extracted files and directories preserve permissions as stored in the archive. The optional parameters allow optional control over which files are extracted, and whether existing files on disk can be overwritten. The second parameter files can be either the name of a file or directory to extract, or an array of names of files and directories to extract. By default, this method will not overwrite existing files, the third parameter can be set to true to enable overwriting of files. This method is similar to ZipArchive::extractTo().
Parâmetros
- pathto
-
Path within an archive to the file to delete.
- files
-
The name of a file or directory to extract, or an array of files/directories to extract
- overwrite
-
Set to TRUE to enable overwriting existing files
Valor Retornado
returns TRUE on success, but it is better to check for thrown exception, and assume success if none is thrown.
Erros
Throws PharException if errors occur while flushing changes to disk.
Exemplos
Exemplo #1 A Phar::extractTo() example
<?php
try {
$phar = new Phar('myphar.phar');
$phar->extractTo('/full/path'); // extract all files
$phar->extractTo('/another/path', 'file.txt'); // extract only file.txt
$phar->extractTo('/this/path',
array('file1.txt', 'file2.txt')); // extract 2 files only
$phar->extractTo('/third/path', null, true); // extract all files, and overwrite
} catch (Exception $e) {
// handle errors
}
?>
Phar::getMetadata
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::getMetadata — Returns phar archive meta-data
Descrição
Retrieve archive meta-data. Meta-data can be any PHP variable that can be serialized.
Parâmetros
No parameters.
Valor Retornado
any PHP variable that can be serialized and is stored as meta-data for the Phar archive, or NULL if no meta-data is stored.
Exemplos
Exemplo #1 A Phar::getMetadata() example
<?php
// make sure it doesn't exist
@unlink('brandnewphar.phar');
try {
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
$p['file.php'] = '<?php echo "hello";';
$p->setMetadata(array('bootstrap' => 'file.php'));
var_dump($p->getMetadata());
} catch (Exception $e) {
echo 'Could not modify phar:', $e;
}
?>
O exemplo acima irá imprimir:
array(1) {
["bootstrap"]=>
string(8) "file.php"
}
Veja Também
- Phar::setMetadata() - Sets phar archive meta-data
- Phar::delMetadata() - Deletes the global metadata of the phar
- Phar::hasMetadata() - Returns whether phar has global meta-data
Phar::getModified
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::getModified — Return whether phar was modified
Descrição
This method can be used to determine whether a phar has either had an internal file deleted, or contents of a file changed in some way.
Parâmetros
No parameters.
Valor Retornado
TRUE if the phar has been modified since opened, FALSE if not.
Phar::getSignature
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::getSignature — Return MD5/SHA1/SHA256/SHA512/OpenSSL signature of a Phar archive
Descrição
Returns the verification signature of a phar archive in a hexadecimal string.
Parâmetros
Valor Retornado
Array with the opened archive's signature in hash key and MD5, SHA-1, SHA-256, SHA-512, or OpenSSL in hash_type. This signature is a hash calculated on the entire phar's contents, and may be used to verify the integrity of the archive. A valid signature is absolutely required of all executable phar archives if the phar.require_hash INI variable is set to true.
Phar::getStub
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::getStub — Return the PHP loader or bootstrap stub of a Phar archive
Descrição
Phar archives contain a bootstrap loader, or stub written in PHP that is executed when the archive is executed in PHP either via include:
<?php
include 'myphar.phar';
?>
php myphar.phar
Valor Retornado
Returns a string containing the contents of the bootstrap loader (stub) of the current Phar archive.
Erros
Throws RuntimeException if it is not possible to read the stub from the Phar archive.
Exemplos
Exemplo #1 A Phar::getStub() example
<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
echo $p->getStub();
echo "==NEXT==\n";
$p->setStub("<?php
function __autoload($class)
{
include 'phar://' . str_replace('_', '/', $class);
}
Phar::mapPhar('myphar.phar');
include 'phar://myphar.phar/startup.php';
__HALT_COMPILER(); ?>");
echo $p->getStub();
?>
O exemplo acima irá imprimir:
<?php __HALT_COMPILER(); ?>
==NEXT==
<?php
function __autoload($class)
{
include 'phar://' . str_replace('_', '/', $class);
}
Phar::mapPhar('myphar.phar');
include 'phar://myphar.phar/startup.php';
__HALT_COMPILER(); ?>
Veja Também
- Phar::setStub() - Used to set the PHP loader or bootstrap stub of a Phar archive
- Phar::createDefaultStub() - Create a phar-file format specific stub
Phar::getSupportedCompression
(PHP >= 5.3.0, PECL phar >= 1.2.0)
Phar::getSupportedCompression — Return array of supported compression algorithms
Descrição
Parâmetros
No parameters.
Valor Retornado
Returns an array containing any of Phar::GZ or Phar::BZ2, depending on the availability of the zlib extension or the bz2 extension.
Veja Também
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::decompress() - Decompresses the entire Phar archive
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressFiles() - Compresses all files in the current Phar archive
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
Phar::getSupportedSignatures
(PHP >= 5.3.0, PECL phar >= 1.1.0)
Phar::getSupportedSignatures — Return array of supported signature types
Descrição
Return array of supported signature types
Parâmetros
No parameters.
Valor Retornado
Returns an array containing any of MD5, SHA-1, SHA-256, SHA-512, or OpenSSL.
Veja Também
- Phar::getSignature() - Return MD5/SHA1/SHA256/SHA512/OpenSSL signature of a Phar archive
- Phar::setSignatureAlgorithm() - set the signature algorithm for a phar and apply it. The
Phar::getVersion
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::getVersion — Return version info of Phar archive
Descrição
Returns the API version of an opened Phar archive.
Parâmetros
Valor Retornado
The opened archive's API version. This is not to be confused with the API version that the loaded phar extension will use to create new phars. Each Phar archive has the API version hard-coded into its manifest. See Phar file format documentation for more information.
Phar::hasMetadata
(PHP >= 5.3.0, PECL phar >= 1.2.0)
Phar::hasMetadata — Returns whether phar has global meta-data
Descrição
Returns whether phar has global meta-data set.
Parâmetros
No parameters.
Valor Retornado
Returns TRUE if meta-data has been set, and FALSE if not.
Exemplos
Exemplo #1 A Phar::hasMetadata() example
<?php
try {
$phar = new Phar('myphar.phar');
var_dump($phar->hasMetadata());
$phar->setMetadata(array('thing' => 'hi'));
var_dump($phar->hasMetadata());
$phar->delMetadata();
var_dump($phar->hasMetadata());
} catch (Exception $e) {
// handle error
}
?>
O exemplo acima irá imprimir:
bool(false) bool(true) bool(false)
Veja Também
- Phar::getMetadata() - Returns phar archive meta-data
- Phar::setMetadata() - Sets phar archive meta-data
- Phar::delMetadata() - Deletes the global metadata of the phar
Phar::interceptFileFuncs
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::interceptFileFuncs — instructs phar to intercept fopen, file_get_contents, opendir, and all of the stat-related functions
Descrição
instructs phar to intercept fopen(), readfile(), file_get_contents(), opendir(), and all of the stat-related functions. If any of these functions is called from within a phar archive with a relative path, the call is modified to access a file within the phar archive. Absolute paths are assumed to be attempts to load external files from the filesystem.
This function makes it possible to run PHP applications designed to run off of a hard disk as a phar application.
Parâmetros
No parameters.
Valor Retornado
Exemplos
Exemplo #1 A Phar::interceptFileFuncs() example
<?php
Phar::interceptFileFuncs();
include 'phar://' . __FILE__ . '/file.php';
?>
Assuming that this phar is at /path/to/myphar.phar and it contains file.php and file2.txt, if file.php contains this code:
Exemplo #2 A Phar::interceptFileFuncs() example
<?php
echo file_get_contents('file2.txt');
?>
Normally PHP would search the current directory for file2.txt, which would translate as the directory of file.php, or the current directory of a command-line user. Phar::interceptFileFuncs() instructs PHP to consider the current directory to be phar:///path/to/myphar.phar/ and so opens phar:///path/to/myphar.phar/file2.txt in the above example code.
Phar::isBuffering
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::isBuffering — Used to determine whether Phar write operations are being buffered, or are flushing directly to disk
Descrição
This method can be used to determine whether a Phar will save changes to disk immediately, or whether a call to Phar::stopBuffering() is needed to enable saving changes.
Phar write buffering is per-archive, buffering active for the foo.phar Phar archive does not affect changes to the bar.phar Phar archive.
Valor Retornado
Returns TRUE if the write operations are being buffer, FALSE otherwise.
Exemplos
Exemplo #1 A Phar::isBuffering() example
<?php
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
$p2 = new Phar('existingphar.phar');
$p['file1.txt'] = 'hi';
var_dump($p->isBuffering());
var_dump($p2->isBuffering());
?>
=2=
<?php
$p->startBuffering();
var_dump($p->isBuffering());
var_dump($p2->isBuffering());
$p->stopBuffering();
?>
=3=
<?php
var_dump($p->isBuffering());
var_dump($p2->isBuffering());
?>
O exemplo acima irá imprimir:
bool(false) bool(false) =2= bool(true) bool(false) =3= bool(false) bool(false)
Veja Também
- Phar::startBuffering() - Start buffering Phar write operations, do not modify the Phar object on disk
- Phar::stopBuffering() - Stop buffering write requests to the Phar archive, and save changes to disk
Phar::isCompressed
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::isCompressed — Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on). Zip-based phar archives cannot be compressed as a file, and so this method will always return FALSE if a zip-based phar archive is queried.
Parâmetros
No parameters.
Valor Retornado
Phar::GZ, Phar::BZ2 or FALSE
Exemplos
Exemplo #1 A Phar::isCompressed() example
<?php
try {
$phar1 = new Phar('myphar.zip.phar');
var_dump($phar1->isCompressed());
$phar2 = new Phar('myuncompressed.tar.phar');
var_dump($phar2->isCompressed());
$phar2->compressAllFilesGZ();
var_dump($phar2->isCompressed() == Phar::GZ);
} catch (Exception $e) {
}
?>
O exemplo acima irá imprimir:
bool(false) bool(false) bool(true)
Veja Também
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- Phar::decompress() - Decompresses the entire Phar archive
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::compressFiles() - Compresses all files in the current Phar archive
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
Phar::isFileFormat
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::isFileFormat — Returns true if the phar archive is based on the tar/phar/zip file format depending on the parameter
Descrição
Parâmetros
- format
-
Either Phar::PHAR, Phar::TAR, or Phar::ZIP to test for the format of the archive.
Valor Retornado
Returns TRUE if the phar archive matches the file format requested by the parameter
Erros
PharException is thrown if the parameter is an unknown file format specifier.
Veja Também
- Phar::convertToExecutable() - Convert a phar archive to another executable phar archive file format
- Phar::convertToData() - Convert a phar archive to a non-executable tar or zip file
Phar::isValidPharFilename
(PHP >= 5.3.0, PECL phar >= 1.2.0)
Phar::isValidPharFilename — Returns whether the given filename is a valid phar filename
Descrição
Returns whether the given filename is a valid phar filename that will be recognized as a phar archive by the phar extension. This can be used to test a name without having to instantiate a phar archive and catch the inevitable Exception that will be thrown if an invalid name is specified.
Parâmetros
- filename
-
The name or full path to a phar archive not yet created
- executable
-
This parameter determines whether the filename should be treated as a phar executable archive, or a data non-executable archive
Valor Retornado
Returns TRUE if the filename is valid, FALSE if not.
Phar::isWritable
(Unknown)
Phar::isWritable — Returns true if the phar archive can be modified
Descrição
This method returns TRUE if phar.readonly is 0, and the actual phar archive on disk is not read-only.
Parâmetros
No parameters.
Valor Retornado
Returns TRUE if the phar archive can be modified
Veja Também
- Phar::canWrite() - Returns whether phar extension supports writing and creating phars
- PharData::isWritable() - Returns true if the tar/zip archive can be modified
Phar::loadPhar
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::loadPhar — Loads any phar archive with an alias
Descrição
This can be used to read the contents of an external Phar archive. This is most useful for assigning an alias to a phar so that subsequent references to the phar can use the shorter alias, or for loading Phar archives that only contain data and are not intended for execution/inclusion in PHP scripts.
Parâmetros
- filename
-
the full or relative path to the phar archive to open
- alias
-
The alias that may be used to refer to the phar archive. Note that many phar archives specify an explicit alias inside the phar archive, and a PharException will be thrown if a new alias is specified in this case.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Erros
PharException is thrown if an alias is passed in and the phar archive already has an explicit alias
Exemplos
Exemplo #1 A Phar::loadPhar() example
Phar::loadPhar can be used anywhere to load an external Phar archive, whereas Phar::mapPhar should be used in a loader stub for a Phar.
<?php
try {
Phar::loadPhar('/path/to/phar.phar', 'my.phar');
echo file_get_contents('phar://my.phar/file.txt');
} catch (PharException $e) {
echo $e;
}
?>
Phar::mapPhar
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::mapPhar — Reads the currently executed file (a phar) and registers its manifest
Descrição
This static method can only be used inside a Phar archive's loader stub in order to initialize the phar when it is directly executed, or when it is included in another script.
Parâmetros
- alias
-
The alias that can be used in phar:// URLs to refer to this archive, rather than its full path.
- dataoffset
-
Unused variable, here for compatibility with PEAR's PHP_Archive.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Erros
PharException is thrown if not called directly within PHP execution, if no __HALT_COMPILER(); token is found in the current source file, or if the file cannot be opened for reading.
Exemplos
Exemplo #1 A Phar::mapPhar() example
mapPhar should be used only inside a phar's loader stub. Use loadPhar to load an external phar into memory.
Here is a sample Phar loader stub that uses mapPhar.
<?php
function __autoload($class)
{
include 'phar://me.phar/' . str_replace('_', '/', $class) . '.php';
}
try {
Phar::mapPhar('me.phar');
include 'phar://me.phar/startup.php';
} catch (PharException $e) {
echo $e->getMessage();
die('Cannot initialize Phar');
}
__HALT_COMPILER();
Phar::mount
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::mount — Mount an external path or file to a virtual location within the phar archive
Descrição
Much like the unix file system concept of mounting external devices to paths within the directory tree, Phar::mount() allows referring to external files and directories as if they were inside of an archive. This allows powerful abstraction such as referring to external configuration files as if they were inside the archive.
Parâmetros
- pharpath
-
The internal path within the phar archive to use as the mounted path location. This must be a relative path within the phar archive, and must not already exist.
- externalpath
-
A path or URL to an external file or directory to mount within the phar archive
Valor Retornado
No return. PharException is thrown on failure.
Erros
Throws PharException if any problems occur mounting the path.
Exemplos
Exemplo #1 A Phar::mount() example
The following example shows accessing an external configuration file as if it were a path within a phar archive.
First, the code inside of a phar archive:
<?php
$configuration = simplexml_load_string(file_get_contents(
Phar::running(false) . '/config.xml'));
?>
Next the external code used to mount the configuration file:
<?php
// first set up the association between the abstract config.xml
// and the actual one on disk
Phar::mount('phar://config.xml', '/home/example/config.xml');
// now run the application
include '/path/to/archive.phar';
?>
Another method is to put the mounting code inside the stub of the phar archive. Here is an example of setting up a default configuration file if no user configuration is specified:
<?php
// first set up the association between the abstract config.xml
// and the actual one on disk
if (defined('EXTERNAL_CONFIG')) {
Phar::mount('config.xml', EXTERNAL_CONFIG);
if (file_exists(__DIR__ . '/extra_config.xml')) {
Phar::mount('extra.xml', __DIR__ . '/extra_config.xml');
}
} else {
Phar::mount('config.xml', 'phar://' . __FILE__ . '/default_config.xml');
Phar::mount('extra.xml', 'phar://' . __FILE__ . '/default_extra.xml');
}
// now run the application
include 'phar://' . __FILE__ . '/index.php';
__HALT_COMPILER();
?>
...and the code externally to load this phar archive:
<?php
define('EXTERNAL_CONFIG', '/home/example/config.xml');
// now run the application
include '/path/to/archive.phar';
?>
Phar::mungServer
(Unknown)
Phar::mungServer — Defines a list of up to 4 $_SERVER variables that should be modified for execution
Descrição
Phar::mungServer() should only be called within the stub of a phar archive.
Defines a list of up to 4 $_SERVER variables that should be modified for execution. Variables that can be modified to remove traces of phar execution are REQUEST_URI, PHP_SELF, SCRIPT_NAME and SCRIPT_FILENAME.
On its own, this method does nothing. Only when combined with Phar::webPhar() does it take effect, and only when the requested file is a PHP file to be parsed. Note that the PATH_INFO and PATH_TRANSLATED variables are always modified.
The original values of variables that are modified are stored in the SERVER array with PHAR_ prepended, so for instance SCRIPT_NAME would be saved as PHAR_SCRIPT_NAME.
Parâmetros
- munglist
-
an array containing as string indices any of REQUEST_URI, PHP_SELF, SCRIPT_NAME and SCRIPT_FILENAME. Other values trigger an exception, and Phar::mungServer() is case-sensitive.
Valor Retornado
No return.
Erros
Throws UnexpectedValueException if any problems are found with the passed in data.
Exemplos
Exemplo #1 A Phar::mungServer() example
<?php
// example stub
Phar::mungServer(array('REQUEST_URI'));
Phar::webPhar();
__HALT_COMPILER();
?>
Veja Também
- Phar::webPhar() - mapPhar for web-based phars. front controller for web applications
- Phar::setStub() - Used to set the PHP loader or bootstrap stub of a Phar archive
Phar::offsetExists
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::offsetExists — determines whether a file exists in the phar
Descrição
This is an implementation of the ArrayAccess interface allowing direct manipulation of the contents of a Phar archive using array access brackets.
offsetExists() is called whenever isset() is called.
Parâmetros
- offset
-
The filename (relative path) to look for in a Phar.
Valor Retornado
Returns TRUE if the file exists within the phar, or FALSE if not.
Exemplos
Exemplo #1 A Phar::offsetExists() example
<?php
$p = new Phar(dirname(__FILE__) . '/my.phar', 0, 'my.phar');
$p['firstfile.txt'] = 'first file';
$p['secondfile.txt'] = 'second file';
// the next set of lines call offsetExists() indirectly
var_dump(isset($p['firstfile.txt']));
var_dump(isset($p['nothere.txt']));
?>
O exemplo acima irá imprimir:
bool(true) bool(false)
Veja Também
- Phar::offsetGet() - Gets a PharFileInfo object for a specific file
- Phar::offsetSet() - set the contents of an internal file to those of an external file
- Phar::offsetUnset() - remove a file from a phar
Phar::offsetGet
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::offsetGet — Gets a PharFileInfo object for a specific file
Descrição
This is an implementation of the ArrayAccess interface allowing direct manipulation of the contents of a Phar archive using array access brackets. Phar::offsetGet() is used for retrieving files from a Phar archive.
Parâmetros
- offset
-
The filename (relative path) to look for in a Phar.
Valor Retornado
A PharFileInfo object is returned that can be used to iterate over a file's contents or to retrieve information about the current file.
Erros
This method throws BadMethodCallException if the file does not exist in the Phar archive.
Exemplos
Exemplo #1 Phar::offsetGet() example
As with all classes that implement the ArrayAccess interface, Phar::offsetGet() is automatically called when using the [] angle bracket operator.
<?php
$p = new Phar(dirname(__FILE__) . '/myphar.phar', 0, 'myphar.phar');
$p['exists.txt'] = "file exists\n";
try {
// automatically calls offsetGet()
echo $p['exists.txt'];
echo $p['doesnotexist.txt'];
} catch (BadMethodCallException $e) {
echo $e;
}
?>
O exemplo acima irá imprimir:
file exists Entry doesnotexist.txt does not exist
Veja Também
- Phar::offsetExists() - determines whether a file exists in the phar
- Phar::offsetSet() - set the contents of an internal file to those of an external file
- Phar::offsetUnset() - remove a file from a phar
Phar::offsetSet
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::offsetSet — set the contents of an internal file to those of an external file
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
This is an implementation of the ArrayAccess interface allowing direct manipulation of the contents of a Phar archive using array access brackets. offsetSet is used for modifying an existing file, or adding a new file to a Phar archive.
Parâmetros
- offset
-
The filename (relative path) to modify in a Phar.
- value
-
Content of the file.
Valor Retornado
No return values.
Erros
if phar.readonly is 1, BadMethodCallException is thrown, as modifying a Phar is only allowed when phar.readonly is set to 0. Throws PharException if there are any problems flushing changes made to the Phar archive to disk.
Exemplos
Exemplo #1 A Phar::offsetSet() example
offsetSet should not be accessed directly, but instead used via array access with the [] operator.
<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
try {
// calls offsetSet
$p['file.txt'] = 'Hi there';
} catch (Exception $e) {
echo 'Could not modify file.txt:', $e;
}
?>
Veja Também
- Phar::offsetExists() - determines whether a file exists in the phar
- Phar::offsetGet() - Gets a PharFileInfo object for a specific file
- Phar::offsetUnset() - remove a file from a phar
Phar::offsetUnset
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::offsetUnset — remove a file from a phar
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
This is an implementation of the ArrayAccess interface allowing direct manipulation of the contents of a Phar archive using array access brackets. offsetUnset is used for deleting an existing file, and is called by the unset() language construct.
Parâmetros
- offset
-
The filename (relative path) to modify in a Phar.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Erros
if phar.readonly is 1, BadMethodCallException is thrown, as modifying a Phar is only allowed when phar.readonly is set to 0. Throws PharException if there are any problems flushing changes made to the Phar archive to disk.
Exemplos
Exemplo #1 A Phar::offsetUnset() example
<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
try {
// deletes file.txt from my.phar by calling offsetUnset
unset($p['file.txt']);
} catch (Exception $e) {
echo 'Could not delete file.txt: ', $e;
}
?>
Veja Também
- Phar::offsetExists() - determines whether a file exists in the phar
- Phar::offsetGet() - Gets a PharFileInfo object for a specific file
- Phar::offsetSet() - set the contents of an internal file to those of an external file
- Phar::unlinkArchive() - Completely remove a phar archive from disk and from memory
- Phar::delete() - Delete a file within a phar archive
Phar::running
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::running — Returns the full path on disk or full phar URL to the currently executing Phar archive
Descrição
Returns the full path to the running phar archive. This is intended for use much like the __FILE__ magic constant, and only has effect inside an executing phar archive.
Inside the stub of an archive, Phar::running() returns "". Simply use __FILE__ to access the current running phar inside a stub.
Parâmetros
- retphar
-
If FALSE, the full path on disk to the phar archive is returned. If TRUE, a full phar URL is returned.
Valor Retornado
Returns the filename if valid, empty string otherwise.
Exemplos
Exemplo #1 A Phar::running() example
For the following example, assume the phar archive is located at /path/to/phar/my.phar.
<?php
$a = Phar::running(); // $a is "phar:///path/to/my.phar"
$b = Phar::running(false); // $b is "/path/to/my.phar"
?>
Phar::setAlias
(PHP >= 5.3.0, PECL phar >= 1.2.1)
Phar::setAlias — Set the alias for the Phar archive
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
Set the alias for the Phar archive, and write it as the permanent alias for this phar archive. An alias can be used internally to a phar archive to ensure that use of the phar stream wrapper to access internal files always works regardless of the location of the phar archive on the filesystem. Another alternative is to rely upon Phar's interception of include() or to use Phar::interceptFileFuncs() and use relative paths.
Parâmetros
- alias
-
A shorthand string that this archive can be referred to in phar stream wrapper access.
Valor Retornado
Erros
Throws UnexpectedValueException when write access is disabled, and PharException if the alias is already in use or any problems were encountered flushing changes to disk.
Exemplos
Exemplo #1 A Phar::setAlias() example
<?php
try {
$phar = new Phar('myphar.phar');
$phar->setAlias('myp.phar');
} catch (Exception $e) {
// handle error
}
?>
Veja Também
- Phar::__construct() - Construct a Phar archive object
- Phar::interceptFileFuncs() - instructs phar to intercept fopen, file_get_contents, opendir, and all of the stat-related functions
Phar::setDefaultStub
(Unknown)
Phar::setDefaultStub — Used to set the PHP loader or bootstrap stub of a Phar archive to the default loader
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
This method is a convenience method that combines the functionality of Phar::createDefaultStub() and Phar::setStub().
Parâmetros
- index
-
Relative path within the phar archive to run if accessed on the command-line
- webindex
-
Relative path within the phar archive to run if accessed through a web browser
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Erros
UnexpectedValueException is thrown if phar.readonly is enabled in php.ini. PharException is thrown if any problems are encountered flushing changes to disk.
Exemplos
Exemplo #1 A Phar::setDefaultStub() example
<?php
try {
$phar = new Phar('myphar.phar');
$phar->setDefaultStub('cli.php', 'web/index.php');
// this is the same as:
// $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
} catch (Exception $e) {
// handle errors
}
?>
Veja Também
- Phar::setStub() - Used to set the PHP loader or bootstrap stub of a Phar archive
- Phar::createDefaultStub() - Create a phar-file format specific stub
Phar::setMetadata
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::setMetadata — Sets phar archive meta-data
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
Phar::setMetadata() should be used to store customized data that describes something about the phar archive as a complete entity. PharFileInfo::setMetadata() should be used for file-specific meta-data. Meta-data can slow down the performance of loading a phar archive if the data is large.
Some possible uses for meta-data include specifying which file within the archive should be used to bootstrap the archive, or the location of a file manifest like » PEAR's package.xml file. However, any useful data that describes the phar archive may be stored.
Parâmetros
- metadata
-
Any PHP variable containing information to store that describes the phar archive
Valor Retornado
Não há valor retornado.
Exemplos
Exemplo #1 A Phar::setMetadata() example
<?php
// make sure it doesn't exist
@unlink('brandnewphar.phar');
try {
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
$p['file.php'] = '<?php echo "hello"';
$p->setMetadata(array('bootstrap' => 'file.php'));
var_dump($p->getMetadata());
} catch (Exception $e) {
echo 'Could not create and/or modify phar:', $e;
}
?>
O exemplo acima irá imprimir:
array(1) {
["bootstrap"]=>
string(8) "file.php"
}
Veja Também
- Phar::getMetadata() - Returns phar archive meta-data
- Phar::delMetadata() - Deletes the global metadata of the phar
- Phar::hasMetadata() - Returns whether phar has global meta-data
Phar::setSignatureAlgorithm
(PHP >= 5.3.0, PECL phar >= 1.1.0)
Phar::setSignatureAlgorithm — set the signature algorithm for a phar and apply it.
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
set the signature algorithm for a phar and apply it. The signature algorithm must be one of Phar::MD5, Phar::SHA1, Phar::SHA256, Phar::SHA512, or Phar::OPENSSL.
Note that all executable phar archives have a signature created automatically, SHA1 by default. data tar- or zip-based archives (archives created with the PharData class) must have their signature created and set explicitly via Phar::setSignatureAlgorithm().
Parâmetros
- sigtype
-
One of Phar::MD5, Phar::SHA1, Phar::SHA256, Phar::SHA512, or Phar::OPENSSL
- privatekey
-
The contents of an OpenSSL private key, as extracted from a certificate or OpenSSL key file:
See phar introduction for instructions on naming and placement of the public key file.<?php
$private = openssl_get_privatekey(file_get_contents('private.pem'));
$pkey = '';
openssl_pkey_export($private, $pkey);
$p->setSignatureAlgorithm(Phar::OPENSSL, $pkey);
?>
Valor Retornado
Não há valor retornado.
Erros
Throws UnexpectedValueException for many errors, and a PharException if any problems occur flushing changes to disk.
Veja Também
- Phar::getSupportedSignatures() - Return array of supported signature types
- Phar::getSignature() - Return MD5/SHA1/SHA256/SHA512/OpenSSL signature of a Phar archive
Phar::setStub
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::setStub — Used to set the PHP loader or bootstrap stub of a Phar archive
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
This method is used to add a PHP bootstrap loader stub to a new Phar archive, or to replace the loader stub in an existing Phar archive.
The loader stub for a Phar archive is used whenever an archive is included directly as in this example:
<?php
include 'myphar.phar';
?>
The loader is not accessed when including a file through the phar stream wrapper like so:
<?php
include 'phar://myphar.phar/somefile.php';
?>
Parâmetros
- stub
-
A string or an open stream handle to use as the executable stub for this phar archive.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Erros
UnexpectedValueException is thrown if phar.readonly is enabled in php.ini. PharException is thrown if any problems are encountered flushing changes to disk.
Exemplos
Exemplo #1 A Phar::setStub() example
<?php
try {
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
$p['a.php'] = '<?php var_dump("Hello");';
$p->setStub('<?php var_dump("First"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>');
include 'phar://brandnewphar.phar/a.php';
var_dump($p->getStub());
$p['b.php'] = '<?php var_dump("World");';
$p->setStub('<?php var_dump("Second"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>');
include 'phar://brandnewphar.phar/b.php';
var_dump($p->getStub());
} catch (Exception $e) {
echo 'Write operations failed on brandnewphar.phar: ', $e;
}
?>
O exemplo acima irá imprimir:
string(5) "Hello"
string(82) "<?php var_dump("First"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>"
string(5) "World"
string(83) "<?php var_dump("Second"); Phar::mapPhar("brandnewphar.phar"); __HALT_COMPILER(); ?>"
Veja Também
- Phar::getStub() - Return the PHP loader or bootstrap stub of a Phar archive
- Phar::createDefaultStub() - Create a phar-file format specific stub
Phar::startBuffering
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::startBuffering — Start buffering Phar write operations, do not modify the Phar object on disk
Descrição
Although technically unnecessary, the Phar::startBuffering() method can provide a significant performance boost when creating or modifying a Phar archive with a large number of files. Ordinarily, every time a file within a Phar archive is created or modified in any way, the entire Phar archive will be recreated with the changes. In this way, the archive will be up-to-date with the activity performed on it.
However, this can be unnecessary when simply creating a new Phar archive, when it would make more sense to write the entire archive out at once. Similarly, it is often necessary to make a series of changes and to ensure that they all are possible before making any changes on disk, similar to the relational database concept of transactions. the Phar::startBuffering()/Phar::stopBuffering() pair of methods is provided for this purpose.
Phar write buffering is per-archive, buffering active for the foo.phar Phar archive does not affect changes to the bar.phar Phar archive.
Valor Retornado
Não há valor retornado.
Exemplos
Exemplo #1 A Phar::startBuffering() example
<?php
// make sure it doesn't exist
@unlink('brandnewphar.phar');
try {
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
} catch (Exception $e) {
echo 'Could not create phar:', $e;
}
echo 'The new phar has ' . $p->count() . " entries\n";
$p->startBuffering();
$p['file.txt'] = 'hi';
$p['file2.txt'] = 'there';
$p['file2.txt']->setCompressedGZ();
$p['file3.txt'] = 'babyface';
$p['file3.txt']->setMetadata(42);
$p->setStub("<?php
function __autoload($class)
{
include 'phar://myphar.phar/' . str_replace('_', '/', $class) . '.php';
}
Phar::mapPhar('myphar.phar');
include 'phar://myphar.phar/startup.php';
__HALT_COMPILER();");
$p->stopBuffering();
?>
Veja Também
- Phar::stopBuffering() - Stop buffering write requests to the Phar archive, and save changes to disk
- Phar::isBuffering() - Used to determine whether Phar write operations are being buffered, or are flushing directly to disk
Phar::stopBuffering
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::stopBuffering — Stop buffering write requests to the Phar archive, and save changes to disk
Descrição
Phar::stopBuffering() is used in conjunction with the Phar::startBuffering() method. Phar::startBuffering() can provide a significant performance boost when creating or modifying a Phar archive with a large number of files. Ordinarily, every time a file within a Phar archive is created or modified in any way, the entire Phar archive will be recreated with the changes. In this way, the archive will be up-to-date with the activity performed on it.
However, this can be unnecessary when simply creating a new Phar archive, when it would make more sense to write the entire archive out at once. Similarly, it is often necessary to make a series of changes and to ensure that they all are possible before making any changes on disk, similar to the relational database concept of transactions. The Phar::startBuffering()/Phar::stopBuffering() pair of methods is provided for this purpose.
Phar write buffering is per-archive, buffering active for the foo.phar Phar archive does not affect changes to the bar.phar Phar archive.
Valor Retornado
Não há valor retornado.
Erros
PharException is thrown if any problems are encountered flushing changes to disk.
Exemplos
Exemplo #1 A Phar::stopBuffering() example
<?php
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
$p['file1.txt'] = 'hi';
$p->startBuffering();
var_dump($p->getStub());
$p->setStub("<?php
function __autoload(\$class)
{
include 'phar://brandnewphar.phar/' . str_replace('_', '/', \$class) . '.php';
}
Phar::mapPhar('brandnewphar.phar');
include 'phar://brandnewphar.phar/startup.php';
__HALT_COMPILER();");
$p->stopBuffering();
var_dump($p->getStub());
?>
O exemplo acima irá imprimir:
string(24) "<?php __HALT_COMPILER();"
string(195) "<?php
function __autoload($class)
{
include 'phar://' . str_replace('_', '/', $class);
}
Phar::mapPhar('brandnewphar.phar');
include 'phar://brandnewphar.phar/startup.php';
__HALT_COMPILER();"
Veja Também
- Phar::startBuffering() - Start buffering Phar write operations, do not modify the Phar object on disk
- Phar::isBuffering() - Used to determine whether Phar write operations are being buffered, or are flushing directly to disk
Phar::uncompressAllFiles
(PECL phar < 2.0.0)
Phar::uncompressAllFiles — Uncompresses all files in the current Phar archive
Descrição
Nota:
Este método tem sido removido da extensão phar a partir da versão 2.0.0. Implementações alternativas são possíveis usando Phar::compress(), Phar::decompress(), Phar::compressFiles() e Phar::decompressFiles().
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
This method decompresses all files in the Phar archive. If any files are already compressed using gzip compression, the zlib extension must be enabled in order to decompress the files, and any files compressed using bzip2 compression require the bzip2 extension to decompress the files. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Erros
Throws BadMethodCallException if the phar.readonly INI variable is on, the bzip2 extension is not enabled and any files are compressed using bzip2 compression, or if any files are compressed using gzip compression and the zlib extension is not enabled.
Exemplos
Exemplo #1 A Phar::uncompressAllFiles() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p->compressAllFilesGZ();
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressedBZIP2());
var_dump($file->isCompressedGZ());
}
$p->uncompressAllFiles();
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressedBZIP2());
var_dump($file->isCompressedGZ());
}
} catch (Exception $e) {
echo 'Write operations failed on my.phar: ', $e;
}
?>
O exemplo acima irá imprimir:
string(10) "myfile.txt" bool(true) bool(false) bool(true) string(11) "myfile2.txt" bool(true) bool(false) bool(true) string(10) "myfile.txt" bool(false) bool(false) bool(false) string(11) "myfile2.txt" bool(false) bool(false) bool(false)
Veja Também
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressedBZIP2() - Returns whether the entry is compressed using bzip2
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::isCompressedGZ() - Returns whether the entry is compressed using gz
- PharFileInfo::setCompressedBZIP2() - Compresses the current Phar entry within the phar using Bzip2 compression
- PharFileInfo::setUncompressed() - Uncompresses the current Phar entry within the phar, if it is compressed
- PharFileInfo::setCompressedGZ() - Compresses the current Phar entry within the phar using gz compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressAllFilesBZIP2() - Compresses all files in the current Phar archive using Bzip2 compression
- Phar::compressAllFilesGZ() - Compresses all files in the current Phar archive using Gzip compression
- Phar::getSupportedCompression() - Return array of supported compression algorithms
Phar::unlinkArchive
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::unlinkArchive — Completely remove a phar archive from disk and from memory
Descrição
Removes a phar archive for disk and memory.
Parâmetros
- archive
-
The path on disk to the phar archive.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Erros
PharException is thrown if there are any open file pointers to the phar archive, or any existing Phar, PharData, or PharFileInfo objects referring to the phar archive.
Exemplos
Exemplo #1 A Phar::unlinkArchive() example
<?php
// simple usage
Phar::unlinkArchive('/path/to/my.phar');
// more common example:
$p = new Phar('my.phar');
$fp = fopen('phar://my.phar/file.txt', 'r');
// this creates 'my.phar.gz'
$gp = $p->compress(Phar::GZ);
// remove all references to the archive
unset($p);
fclose($fp);
// now remove all traces of the archive
Phar::unlinkArchive('my.phar');
?>
Veja Também
- Phar::delete() - Delete a file within a phar archive
- Phar::offsetUnset() - remove a file from a phar
Phar::webPhar
(PHP >= 5.3.0, PECL phar >= 2.0.0)
Phar::webPhar — mapPhar for web-based phars. front controller for web applications
Descrição
Phar::mapPhar() for web-based phars. This method parses $_SERVER['REQUEST_URI'] and routes a request from a web browser to an internal file within the phar archive. In essence, it simulates a web server, routing requests to the correct file, echoing the correct headers and parsing PHP files as needed. This powerful method is part of what makes it easy to convert an existing PHP application into a phar archive. Combined with Phar::mungServer() and Phar::interceptFileFuncs(), any web application can be used unmodified from a phar archive.
Phar::webPhar() should only be called from the stub of a phar archive (see here for more information on what a stub is).
Parâmetros
- alias
-
The alias that can be used in phar:// URLs to refer to this archive, rather than its full path.
- index
-
The location within the phar of the directory index.
- f404
-
The location of the script to run when a file is not found. This script should output the proper HTTP 404 headers.
- mimetypes
-
An array mapping additional file extensions to MIME type. If the default mapping is sufficient, pass an empty array. By default, these extensions are mapped to these MIME types:
<?php
$mimes = array(
'phps' => Phar::PHPS, // pass to highlight_file()
'c' => 'text/plain',
'cc' => 'text/plain',
'cpp' => 'text/plain',
'c++' => 'text/plain',
'dtd' => 'text/plain',
'h' => 'text/plain',
'log' => 'text/plain',
'rng' => 'text/plain',
'txt' => 'text/plain',
'xsd' => 'text/plain',
'php' => Phar::PHP, // parse as PHP
'inc' => Phar::PHP, // parse as PHP
'avi' => 'video/avi',
'bmp' => 'image/bmp',
'css' => 'text/css',
'gif' => 'image/gif',
'htm' => 'text/html',
'html' => 'text/html',
'htmls' => 'text/html',
'ico' => 'image/x-ico',
'jpe' => 'image/jpeg',
'jpg' => 'image/jpeg',
'jpeg' => 'image/jpeg',
'js' => 'application/x-javascript',
'midi' => 'audio/midi',
'mid' => 'audio/midi',
'mod' => 'audio/mod',
'mov' => 'movie/quicktime',
'mp3' => 'audio/mp3',
'mpg' => 'video/mpeg',
'mpeg' => 'video/mpeg',
'pdf' => 'application/pdf',
'png' => 'image/png',
'swf' => 'application/shockwave-flash',
'tif' => 'image/tiff',
'tiff' => 'image/tiff',
'wav' => 'audio/wav',
'xbm' => 'image/xbm',
'xml' => 'text/xml',
);
?> - rewrites
-
An array mapping URI to internal file, simulating mod_rewrite of apache. For example:
would route calls to http://<host>/myphar.phar/myinfo to the file phar:///path/to/myphar.phar/myinfo.php, preserving GET/POST. This does not quite work like mod_rewrite in that it would not match http://<host>/myphar.phar/myinfo/another.<?php
array(
'myinfo' => 'myinfo.php'
);
?>
Valor Retornado
Não há valor retornado.
Erros
Throws PharException when unable to open the internal file to output, or if called from a non-stub. If an invalid array value is passed into mimetypes or to rewrites, then UnexpectedValueException is thrown.
Exemplos
Exemplo #1 A Phar::webPhar() example
With the example below, the created phar will display Hello World if one browses to /myphar.phar/index.php or to /myphar.phar, and will display the source of index.phps if one browses to /myphar.phar/index.phps.
<?php
// creating the phar archive:
try {
$phar = new Phar('myphar.phar');
$phar['index.php'] = '<?php echo "Hello World"; ?>';
$phar['index.phps'] = '<?php echo "Hello World"; ?>';
$phar->setStub('<?php
Phar::webPhar();
__HALT_COMPILER(); ?>');
} catch (Exception $e) {
// handle error here
}
?>
Veja Também
- Phar::mungServer() - Defines a list of up to 4 $_SERVER variables that should be modified for execution
- Phar::interceptFileFuncs() - instructs phar to intercept fopen, file_get_contents, opendir, and all of the stat-related functions
Índice
- Phar::addEmptyDir — Add an empty directory to the phar archive
- Phar::addFile — Add a file from the filesystem to the phar archive
- Phar::addFromString — Add a file from the filesystem to the phar archive
- Phar::apiVersion — Returns the api version
- Phar::buildFromDirectory — Construct a phar archive from the files within a directory.
- Phar::buildFromIterator — Construct a phar archive from an iterator.
- Phar::canCompress — Returns whether phar extension supports compression using either zlib or bzip2
- Phar::canWrite — Returns whether phar extension supports writing and creating phars
- Phar::compress — Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::compressAllFilesBZIP2 — Compresses all files in the current Phar archive using Bzip2 compression
- Phar::compressAllFilesGZ — Compresses all files in the current Phar archive using Gzip compression
- Phar::compressFiles — Compresses all files in the current Phar archive
- Phar::__construct — Construct a Phar archive object
- Phar::convertToData — Convert a phar archive to a non-executable tar or zip file
- Phar::convertToExecutable — Convert a phar archive to another executable phar archive file format
- Phar::copy — Copy a file internal to the phar archive to another new file within the phar
- Phar::count — Returns the number of entries (files) in the Phar archive
- Phar::createDefaultStub — Create a phar-file format specific stub
- Phar::decompress — Decompresses the entire Phar archive
- Phar::decompressFiles — Decompresses all files in the current Phar archive
- Phar::delMetadata — Deletes the global metadata of the phar
- Phar::delete — Delete a file within a phar archive
- Phar::extractTo — Extract the contents of a phar archive to a directory
- Phar::getMetadata — Returns phar archive meta-data
- Phar::getModified — Return whether phar was modified
- Phar::getSignature — Return MD5/SHA1/SHA256/SHA512/OpenSSL signature of a Phar archive
- Phar::getStub — Return the PHP loader or bootstrap stub of a Phar archive
- Phar::getSupportedCompression — Return array of supported compression algorithms
- Phar::getSupportedSignatures — Return array of supported signature types
- Phar::getVersion — Return version info of Phar archive
- Phar::hasMetadata — Returns whether phar has global meta-data
- Phar::interceptFileFuncs — instructs phar to intercept fopen, file_get_contents, opendir, and all of the stat-related functions
- Phar::isBuffering — Used to determine whether Phar write operations are being buffered, or are flushing directly to disk
- Phar::isCompressed — Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::isFileFormat — Returns true if the phar archive is based on the tar/phar/zip file format depending on the parameter
- Phar::isValidPharFilename — Returns whether the given filename is a valid phar filename
- Phar::isWritable — Returns true if the phar archive can be modified
- Phar::loadPhar — Loads any phar archive with an alias
- Phar::mapPhar — Reads the currently executed file (a phar) and registers its manifest
- Phar::mount — Mount an external path or file to a virtual location within the phar archive
- Phar::mungServer — Defines a list of up to 4 $_SERVER variables that should be modified for execution
- Phar::offsetExists — determines whether a file exists in the phar
- Phar::offsetGet — Gets a PharFileInfo object for a specific file
- Phar::offsetSet — set the contents of an internal file to those of an external file
- Phar::offsetUnset — remove a file from a phar
- Phar::running — Returns the full path on disk or full phar URL to the currently executing Phar archive
- Phar::setAlias — Set the alias for the Phar archive
- Phar::setDefaultStub — Used to set the PHP loader or bootstrap stub of a Phar archive to the default loader
- Phar::setMetadata — Sets phar archive meta-data
- Phar::setSignatureAlgorithm — set the signature algorithm for a phar and apply it.
- Phar::setStub — Used to set the PHP loader or bootstrap stub of a Phar archive
- Phar::startBuffering — Start buffering Phar write operations, do not modify the Phar object on disk
- Phar::stopBuffering — Stop buffering write requests to the Phar archive, and save changes to disk
- Phar::uncompressAllFiles — Uncompresses all files in the current Phar archive
- Phar::unlinkArchive — Completely remove a phar archive from disk and from memory
- Phar::webPhar — mapPhar for web-based phars. front controller for web applications
The PharData class
(No version information available, might only be in SVN)
Introdução
The PharData class provides a high-level interface to accessing and creating non-executable tar and zip archives. Because these archives do not contain a stub and cannot be executed by the phar extension, it is possible to create and manipulate regular zip and tar files using the PharData class even if phar.readonly php.ini setting is 1.
Sinopse da classe
PharData::addEmptyDir
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::addEmptyDir — Add an empty directory to the tar/zip archive
Descrição
With this method, an empty directory is created with path dirname. This method is similar to ZipArchive::addEmptyDir().
Parâmetros
- dirname
-
The name of the empty directory to create in the phar archive
Valor Retornado
no return value, exception is thrown on failure.
Exemplos
Exemplo #1 A PharData::addEmptyDir() example
<?php
try {
$a = new PharData('/path/to/my.tar');
$a->addEmptyDir('/full/path/to/file');
// demonstrates how this file is stored
$b = $a['full/path/to/file']->isDir();
} catch (Exception $e) {
// handle errors here
}
?>
Veja Também
- Phar::addEmptyDir() - Add an empty directory to the phar archive
- PharData::addFile() - Add a file from the filesystem to the tar/zip archive
- PharData::addFromString() - Add a file from the filesystem to the tar/zip archive
PharData::addFile
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::addFile — Add a file from the filesystem to the tar/zip archive
Descrição
With this method, any file or URL can be added to the tar/zip archive. If the optional second parameter localname is specified, the file will be stored in the archive with that name, otherwise the file parameter is used as the path to store within the archive. URLs must have a localname or an exception is thrown. This method is similar to ZipArchive::addFile().
Parâmetros
- file
-
Full or relative path to a file on disk to be added to the phar archive.
- localname
-
Path that the file will be stored in the archive.
Valor Retornado
no return value, exception is thrown on failure.
Exemplos
Exemplo #1 A PharData::addFile() example
<?php
try {
$a = new PharData('/path/to/my.tar');
$a->addFile('/full/path/to/file');
// demonstrates how this file is stored
$b = $a['full/path/to/file']->getContent();
$a->addFile('/full/path/to/file', 'my/file.txt');
$c = $a['my/file.txt']->getContent();
// demonstrate URL usage
$a->addFile('http://www.example.com', 'example.html');
} catch (Exception $e) {
// handle errors here
}
?>
Veja Também
- PharData::offsetSet() - set the contents of a file within the tar/zip to those of an external file or string
- Phar::addFile() - Add a file from the filesystem to the phar archive
- PharData::addFromString() - Add a file from the filesystem to the tar/zip archive
- PharData::addEmptyDir() - Add an empty directory to the tar/zip archive
PharData::addFromString
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::addFromString — Add a file from the filesystem to the tar/zip archive
Descrição
With this method, any string can be added to the tar/zip archive. The file will be stored in the archive with localname as its path. This method is similar to ZipArchive::addFromString().
Parâmetros
- localname
-
Path that the file will be stored in the archive.
- contents
-
The file contents to store
Valor Retornado
no return value, exception is thrown on failure.
Exemplos
Exemplo #1 A PharData::addFromString() example
<?php
try {
$a = new PharData('/path/to/my.tar');
$a->addFromString('path/to/file.txt', 'my simple file');
$b = $a['path/to/file.txt']->getContent();
// to add contents from a stream handle for large files, use offsetSet()
$c = fopen('/path/to/hugefile.bin');
$a['largefile.bin'] = $c;
fclose($c);
} catch (Exception $e) {
// handle errors here
}
?>
Veja Também
- PharData::offsetSet() - set the contents of a file within the tar/zip to those of an external file or string
- Phar::addFromString() - Add a file from the filesystem to the phar archive
- PharData::addFile() - Add a file from the filesystem to the tar/zip archive
- PharData::addEmptyDir() - Add an empty directory to the tar/zip archive
PharData::buildFromDirectory
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::buildFromDirectory — Construct a tar/zip archive from the files within a directory.
Descrição
Populate a tar/zip archive from directory contents. The optional second parameter is a regular expression (pcre) that is used to exclude files. Any filename that matches the regular expression will be included, all others will be excluded. For more fine-grained control, use PharData::buildFromIterator().
Parâmetros
- base_dir
-
The full or relative path to the directory that contains all files to add to the archive.
- regex
-
An optional pcre regular expression that is used to filter the list of files. Only file paths matching the regular expression will be included in the archive.
Valor Retornado
Phar::buildFromDirectory() returns an associative array mapping internal path of file to the full path of the file on the filesystem.
Erros
This method throws BadMethodCallException when unable to instantiate the internal directory iterators, or a PharException if there were errors saving the phar archive.
Exemplos
Exemplo #1 A PharData::buildFromDirectory() example
<?php
$phar = new PharData('project.tar');
// add all files in the project
$phar->buildFromDirectory(dirname(__FILE__) . '/project');
$phar2 = new PharData('project2.zip');
// add all files in the project, only include php files
$phar->buildFromDirectory(dirname(__FILE__) . '/project', '/\.php$/');
?>
Veja Também
- Phar::buildFromDirectory() - Construct a phar archive from the files within a directory.
- PharData::buildFromIterator() - Construct a tar or zip archive from an iterator.
PharData::buildFromIterator
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::buildFromIterator — Construct a tar or zip archive from an iterator.
Descrição
Populate a tar or zip archive from an iterator. Two styles of iterators are supported, iterators that map the filename within the tar/zip to the name of a file on disk, and iterators like DirectoryIterator that return SplFileInfo objects. For iterators that return SplFileInfo objects, the second parameter is required.
Exemplos
Exemplo #1 A PharData::buildFromIterator() with SplFileInfo
For most tar/zip archives, the archive will reflect an actual directory layout, and the second style is the most useful. For instance, to create a tar/zip archive containing the files in this sample directory layout:
/path/to/project/
config/
dist.xml
debug.xml
lib/
file1.php
file2.php
src/
processthing.php
www/
index.php
cli/
index.php
This code could be used to add these files to the "project.tar" tar archive:
<?php
$phar = new PharData('project.tar');
$phar->buildFromIterator(
new RecursiveIteratorIterator(
new RecursiveDirectoryIterator('/path/to/project')),
'/path/to/project');
?>
The file project.tar can then be used immediately. PharData::buildFromIterator() does not set values such as compression, metadata, and this can be done after creating the tar/zip archive.
As an interesting note, PharData::buildFromIterator() can also be used to copy the contents of an existing phar, tar or zip archive, as the PharData object descends from DirectoryIterator:
<?php
$phar = new PharData('project.tar');
$phar->buildFromIterator(
new RecursiveIteratorIterator(
new Phar('/path/to/anotherphar.phar')),
'phar:///path/to/anotherphar.phar/path/to/project');
$phar->setStub($phar->createDefaultStub('cli/index.php', 'www/index.php'));
?>
Exemplo #2 A PharData::buildFromIterator() with other iterators
The second form of the iterator can be used with any iterator that returns a key => value mapping, such as an ArrayIterator:
<?php
$phar = new PharData('project.tar');
$phar->buildFromIterator(
new ArrayIterator(
array(
'internal/file.php' => dirname(__FILE__) . '/somefile.php',
'another/file.jpg' => fopen('/path/to/bigfile.jpg', 'rb'),
)));
?>
Parâmetros
- iter
-
Any iterator that either associatively maps tar/zip file to location or returns SplFileInfo objects
- base_directory
-
For iterators that return SplFileInfo objects, the portion of each file's full path to remove when adding to the tar/zip archive
Valor Retornado
PharData::buildFromIterator() returns an associative array mapping internal path of file to the full path of the file on the filesystem.
Erros
This method returns UnexpectedValueException when the iterator returns incorrect values, such as an integer key instead of a string, a BadMethodCallException when an SplFileInfo-based iterator is passed without a base_directory parameter, or a PharException if there were errors saving the phar archive.
PharData::compress
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::compress — Compresses the entire tar/zip archive using Gzip or Bzip2 compression
Descrição
For tar archives, this method compresses the entire archive using gzip compression or bzip2 compression. The resulting file can be processed with the gunzip command/bunzip command, or accessed directly and transparently with the Phar extension.
For zip archives, this method fails with an exception. The zlib extension must be enabled to compress with gzip compression, the bzip2 extension must be enabled in order to compress with bzip2 compression.
In addition, this method automatically renames the archive, appending .gz, .bz2 or removing the extension if passed Phar::NONE to remove compression. Alternatively, a file extension may be specified with the second parameter.
Parâmetros
- compression
-
Compression must be one of Phar::GZ, Phar::BZ2 to add compression, or Phar::NONE to remove compression.
- extension
-
By default, the extension is .tar.gz or .tar.bz2 for compressing a tar, and .tar for decompressing.
Valor Retornado
A PharData object is returned.
Erros
Throws BadMethodCallException if the zlib extension is not available, or the bzip2 extension is not enabled.
Exemplos
Exemplo #1 A PharData::compress() example
<?php
$p = new PharData('/path/to/my.tar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p1 = $p->compress(Phar::GZ); // copies to /path/to/my.phar.gz
$p2 = $p->compress(Phar::BZ2); // copies to /path/to/my.phar.bz2
$p3 = $p2->compress(Phar::NONE); // exception: /path/to/my.phar already exists
?>
PharData::compressFiles
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::compressFiles — Compresses all files in the current tar/zip archive
Descrição
For tar-based archives, this method throws a BadMethodCallException, as compression of individual files within a tar archive is not supported by the file format. Use PharData::compress() to compress an entire tar-based archive.
For Zip-based archives, this method compresses all files in the archive using the specified compression. The zlib or bzip2 extensions must be enabled to take advantage of this feature. In addition, if any files are already compressed using bzip2/zlib compression, the respective extension must be enabled in order to decompress the files prior to re-compressing.
Parâmetros
- compression
-
Compression must be one of Phar::GZ, Phar::BZ2 to add compression, or Phar::NONE to remove compression.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Erros
Throws BadMethodCallException if the phar.readonly INI variable is on, the zlib extension is not available, or if any files are compressed using bzip2 compression and the bzip2 extension is not enabled.
Exemplos
Exemplo #1 A PharData::compressFiles() example
<?php
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressed(Phar::BZ2));
var_dump($file->isCompressed(Phar::GZ));
}
$p->compressFiles(Phar::GZ);
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressed(Phar::BZ2));
var_dump($file->isCompressed(Phar::GZ));
}
?>
O exemplo acima irá imprimir:
string(10) "myfile.txt" bool(false) bool(false) bool(false) string(11) "myfile2.txt" bool(false) bool(false) bool(false) string(10) "myfile.txt" int(4096) bool(false) bool(true) string(11) "myfile2.txt" int(4096) bool(false) bool(true)
Veja Também
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- PharData::decompressFiles() - Decompresses all files in the current zip archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- PharData::compress() - Compresses the entire tar/zip archive using Gzip or Bzip2 compression
- PharData::decompress() - Decompresses the entire Phar archive
PharData::__construct
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::__construct — Construct a non-executable tar or zip archive object
Descrição
Parâmetros
- fname
-
Path to an existing tar/zip archive or to-be-created archive
- flags
-
Flags to pass to Phar parent class RecursiveDirectoryIterator.
- alias
-
Alias with which this Phar archive should be referred to in calls to stream functionality.
- format
-
One of the file format constants available within the Phar class.
Erros
Throws BadMethodCallException if called twice; UnexpectedValueException if the Phar archive can't be opened.
Exemplos
Exemplo #1 A PharData::__construct() example
<?php
try {
$p = new PharData('/path/to/my.tar', CURRENT_AS_FILEINFO | KEY_AS_FILENAME);
} catch (UnexpectedValueException $e) {
die('Could not open my.tar');
} catch (BadMethodCallException $e) {
echo 'technically, this cannot happen';
}
echo file_get_contents('phar:///path/to/my.tar/example.txt');
?>
PharData::convertToData
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::convertToData — Convert a phar archive to a non-executable tar or zip file
Descrição
This method is used to convert a non-executable tar or zip archive to another non-executable format.
If no changes are specified, this method throws a BadMethodCallException. This method should be used to convert a tar archive to zip format or vice-versa. Although it is possible to simply change the compression of a tar archive using this method, it is better to use the PharData::compress() method for logical consistency.
If successful, the method creates a new archive on disk and returns a PharData object. The old archive is not removed from disk, and should be done manually after the process has finished.
Parâmetros
- format
-
This should be one of Phar::TAR or Phar::ZIP. If set to NULL, the existing file format will be preserved.
- compression
-
This should be one of Phar::NONE for no whole-archive compression, Phar::GZ for zlib-based compression, and Phar::BZ2 for bzip-based compression.
- extension
-
This parameter is used to override the default file extension for a converted archive. Note that .phar cannot be used anywhere in the filename for a non-executable tar or zip archive.
If converting to a tar-based phar archive, the default extensions are .tar, .tar.gz, and .tar.bz2 depending on specified compression. For zip-based archives, the default extension is .zip.
Valor Retornado
The method returns a PharData object on success and throws an exception on failure.
Erros
This method throws BadMethodCallException when unable to compress, an unknown compression method has been specified, the requested archive is buffering with Phar::startBuffering() and has not concluded with Phar::stopBuffering(), and a PharException if any problems are encountered during the phar creation process.
Exemplos
Exemplo #1 A PharData::convertToData() example
Using PharData::convertToData():
<?php
try {
$tarphar = new PharData('myphar.tar');
// note that myphar.tar is *not* unlinked
// convert it to the non-executable tar file format
// creates myphar.zip
$zip = $tarphar->convertToData(Phar::ZIP);
// create myphar.tbz
$tgz = $zip->convertToData(Phar::TAR, Phar::BZ2, '.tbz');
// creates myphar.phar.tgz
$phar = $tarphar->convertToData(Phar::PHAR); // throws exception
} catch (Exception $e) {
// handle the error here
}
?>
Veja Também
- Phar::convertToExecutable() - Convert a phar archive to another executable phar archive file format
- Phar::convertToData() - Convert a phar archive to a non-executable tar or zip file
- PharData::convertToExecutable() - Convert a non-executable tar/zip archive to an executable phar archive
PharData::convertToExecutable
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::convertToExecutable — Convert a non-executable tar/zip archive to an executable phar archive
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
This method is used to convert a non-executable tar or zip archive to an executable phar archive. Any of the three executable file formats (phar, tar or zip) can be used, and whole-archive compression can also be performed.
If no changes are specified, this method throws a BadMethodCallException.
If successful, the method creates a new archive on disk and returns a Phar object. The old archive is not removed from disk, and should be done manually after the process has finished.
Parâmetros
- format
-
This should be one of Phar::PHAR, Phar::TAR, or Phar::ZIP. If set to NULL, the existing file format will be preserved.
- compression
-
This should be one of Phar::NONE for no whole-archive compression, Phar::GZ for zlib-based compression, and Phar::BZ2 for bzip-based compression.
- extension
-
This parameter is used to override the default file extension for a converted archive. Note that all zip- and tar-based phar archives must contain .phar in their file extension in order to be processed as a phar archive.
If converting to a phar-based archive, the default extensions are .phar, .phar.gz, or .phar.bz2 depending on the specified compression. For tar-based phar archives, the default extensions are .phar.tar, .phar.tar.gz, and .phar.tar.bz2. For zip-based phar archives, the default extension is .phar.zip.
Valor Retornado
The method returns a Phar object on success and throws an exception on failure.
Erros
This method throws BadMethodCallException when unable to compress, an unknown compression method has been specified, the requested archive is buffering with Phar::startBuffering() and has not concluded with Phar::stopBuffering(), an UnexpectedValueException if write support is disabled, and a PharException if any problems are encountered during the phar creation process.
Exemplos
Exemplo #1 A PharData::convertToExecutable() example
Using PharData::convertToExecutable():
<?php
try {
$tarphar = new PharData('myphar.tar');
// convert it to the phar file format
// note that myphar.tar is *not* unlinked
$phar = $tarphar->convertToExecutable(Phar::PHAR); // creates myphar.phar
$phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php'));
// creates myphar.phar.tgz
$compressed = $tarphar->convertToExecutable(Phar::TAR, Phar::GZ, '.phar.tgz');
} catch (Exception $e) {
// handle the error here
}
?>
Veja Também
- Phar::convertToExecutable() - Convert a phar archive to another executable phar archive file format
- Phar::convertToData() - Convert a phar archive to a non-executable tar or zip file
- PharData::convertToData() - Convert a phar archive to a non-executable tar or zip file
PharData::copy
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::copy — Copy a file internal to the phar archive to another new file within the phar
Descrição
Copy a file internal to the tar/zip archive to another new file within the same archive. This is an object-oriented alternative to using copy() with the phar stream wrapper.
Parâmetros
- oldfile
-
- newfile
-
Valor Retornado
returns TRUE on success, but it is safer to encase method call in a try/catch block and assume success if no exception is thrown.
Erros
throws UnexpectedValueException if the source file does not exist, the destination file already exists, write access is disabled, opening either file fails, reading the source file fails, or a PharException if writing the changes to the phar fails.
Exemplos
Exemplo #1 A PharData::copy() example
This example shows using PharData::copy() and the equivalent stream wrapper performance of the same thing. The primary difference between the two approaches is error handling. All PharData methods throw exceptions, whereas the stream wrapper uses trigger_error().
<?php
try {
$phar = new PharData('myphar.tar');
$phar['a'] = 'hi';
$phar->copy('a', 'b');
echo $phar['b']; // outputs "phar://myphar.tar/b"
} catch (Exception $e) {
// handle error
}
// the stream wrapper equivalent of the above code.
// E_WARNINGS are triggered on error rather than exceptions.
copy('phar://myphar.tar/a', 'phar//myphar.tar/c');
echo file_get_contents('phar://myphar.tar/c'); // outputs "hi"
?>
PharData::decompress
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::decompress — Decompresses the entire Phar archive
Descrição
For tar-based archives, this method decompresses the entire archive.
For Zip-based archives, this method fails with an exception. The zlib extension must be enabled to decompress an archive compressed with gzip compression, and the bzip2 extension must be enabled in order to decompress an archive compressed with bzip2 compression.
In addition, this method automatically renames the file extension of the archive, .tar by default. Alternatively, a file extension may be specified with the second parameter.
Parâmetros
- extension
-
For decompressing, the default file extension is .phar.tar. Use this parameter to specify another file extension. Be aware that no non-executable archives cannot contain .phar in their filename.
Valor Retornado
A PharData object is returned.
Erros
Throws BadMethodCallException if the zlib extension is not available, or the bzip2 extension is not enabled.
Exemplos
Exemplo #1 A PharData::decompress() example
<?php
$p = new PharData('/path/to/my.tar', 0, 'my.tar.gz');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p3 = $p2->decompress(); // creates /path/to/my.tar
?>
Veja Também
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- PharData::compress() - Compresses the entire tar/zip archive using Gzip or Bzip2 compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- PharData::compress() - Compresses the entire tar/zip archive using Gzip or Bzip2 compression
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- PharData::compressFiles() - Compresses all files in the current tar/zip archive
- PharData::decompressFiles() - Decompresses all files in the current zip archive
PharData::decompressFiles
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::decompressFiles — Decompresses all files in the current zip archive
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
For tar-based archives, this method throws a BadMethodCallException, as compression of individual files within a tar archive is not supported by the file format. Use PharData::compress() to compress an entire tar-based archive.
For Zip-based archives, this method decompresses all files in the archive. The zlib or bzip2 extensions must be enabled to take advantage of this feature if any files are compressed using bzip2/zlib compression.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Erros
Throws BadMethodCallException if the zlib extension is not available, or if any files are compressed using bzip2 compression and the bzip2 extension is not enabled.
Exemplos
Exemplo #1 A PharData::decompressFiles() example
<?php
$p = new PharData('/path/to/my.zip');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p->compressFiles(Phar::GZ);
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressed(Phar::BZ2));
var_dump($file->isCompressed(Phar::GZ));
}
$p->decompressFiles();
foreach ($p as $file) {
var_dump($file->getFileName());
var_dump($file->isCompressed());
var_dump($file->isCompressed(Phar::BZ2));
var_dump($file->isCompressed(Phar::GZ));
}
?>
O exemplo acima irá imprimir:
string(10) "myfile.txt" int(4096) bool(false) bool(true) string(11) "myfile2.txt" int(4096) bool(false) bool(true) string(10) "myfile.txt" bool(false) bool(false) bool(false) string(11) "myfile2.txt" bool(false) bool(false) bool(false)
Veja Também
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- PharData::compressFiles() - Compresses all files in the current tar/zip archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- PharData::compress() - Compresses the entire tar/zip archive using Gzip or Bzip2 compression
- PharData::decompress() - Decompresses the entire Phar archive
PharData::delMetadata
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::delMetadata — Deletes the global metadata of a zip archive
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
Deletes the global metadata of the zip archive
Parâmetros
Valor Retornado
returns TRUE on success, but it is better to check for thrown exception, and assume success if none is thrown.
Erros
Throws PharException if errors occur while flushing changes to disk.
Exemplos
Exemplo #1 A PharData::delMetaData() example
<?php
try {
$phar = new PharData('myphar.zip');
var_dump($phar->getMetadata());
$phar->setMetadata("hi there");
var_dump($phar->getMetadata());
$phar->delMetadata();
var_dump($phar->getMetadata());
} catch (Exception $e) {
// handle errors
}
?>
O exemplo acima irá imprimir:
NULL string(8) "hi there" NULL
PharData::delete
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::delete — Delete a file within a tar/zip archive
Descrição
Delete a file within an archive. This is the functional equivalent of calling unlink() on the stream wrapper equivalent, as shown in the example below.
Parâmetros
- entry
-
Path within an archive to the file to delete.
Valor Retornado
returns TRUE on success, but it is better to check for thrown exception, and assume success if none is thrown.
Erros
Throws PharException if errors occur while flushing changes to disk.
Exemplos
Exemplo #1 A PharData::delete() example
<?php
try {
$phar = new PharData('myphar.zip');
$phar->delete('unlink/me.php');
// this is equivalent to:
unlink('phar://myphar.phar/unlink/me.php');
} catch (Exception $e) {
// handle errors
}
?>
PharData::extractTo
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::extractTo — Extract the contents of a tar/zip archive to a directory
Descrição
Extract all files within a tar/zip archive to disk. Extracted files and directories preserve permissions as stored in the archive. The optional parameters allow optional control over which files are extracted, and whether existing files on disk can be overwritten. The second parameter files can be either the name of a file or directory to extract, or an array of names of files and directories to extract. By default, this method will not overwrite existing files, the third parameter can be set to true to enable overwriting of files. This method is similar to ZipArchive::extractTo().
Parâmetros
- pathto
-
Path within an archive to the file to delete.
- files
-
The name of a file or directory to extract, or an array of files/directories to extract
- overwrite
-
Set to TRUE to enable overwriting existing files
Valor Retornado
returns TRUE on success, but it is better to check for thrown exception, and assume success if none is thrown.
Erros
Throws PharException if errors occur while flushing changes to disk.
Exemplos
Exemplo #1 A PharData::extractTo() example
<?php
try {
$phar = new PharData('myphar.tar');
$phar->extractTo('/full/path'); // extract all files
$phar->extractTo('/another/path', 'file.txt'); // extract only file.txt
$phar->extractTo('/this/path',
array('file1.txt', 'file2.txt')); // extract 2 files only
$phar->extractTo('/third/path', null, true); // extract all files, and overwrite
} catch (Exception $e) {
// handle errors
}
?>
PharData::isWritable
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::isWritable — Returns true if the tar/zip archive can be modified
Descrição
This method returns TRUE if the tar/zip archive on disk is not read-only. Unlike Phar::isWritable(), data-only tar/zip archives can be modified even if phar.readonly is set to 1.
Parâmetros
No parameters.
Valor Retornado
Returns TRUE if the tar/zip archive can be modified
Veja Também
- Phar::canWrite() - Returns whether phar extension supports writing and creating phars
- Phar::isWritable() - Returns true if the phar archive can be modified
PharData::offsetSet
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::offsetSet — set the contents of a file within the tar/zip to those of an external file or string
Descrição
This is an implementation of the ArrayAccess interface allowing direct manipulation of the contents of a tar/zip archive using array access brackets. offsetSet is used for modifying an existing file, or adding a new file to a tar/zip archive.
Parâmetros
- offset
-
The filename (relative path) to modify in a tar or zip archive.
- value
-
Content of the file.
Valor Retornado
No return values.
Erros
Throws PharException if there are any problems flushing changes made to the tar/zip archive to disk.
Exemplos
Exemplo #1 A PharData::offsetSet() example
offsetSet should not be accessed directly, but instead used via array access with the [] operator.
<?php
$p = new PharData('/path/to/my.tar');
try {
// calls offsetSet
$p['file.txt'] = 'Hi there';
} catch (Exception $e) {
echo 'Could not modify file.txt:', $e;
}
?>
PharData::offsetUnset
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::offsetUnset — remove a file from a tar/zip archive
Descrição
This is an implementation of the ArrayAccess interface allowing direct manipulation of the contents of a tar/zip archive using array access brackets. offsetUnset is used for deleting an existing file, and is called by the unset() language construct.
Parâmetros
- offset
-
The filename (relative path) to modify in the tar/zip archive.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Erros
Throws PharException if there are any problems flushing changes made to the tar/zip archive to disk.
Exemplos
Exemplo #1 A PharData::offsetUnset() example
<?php
$p = new PharData('/path/to/my.zip');
try {
// deletes file.txt from my.zip by calling offsetUnset
unset($p['file.txt']);
} catch (Exception $e) {
echo 'Could not delete file.txt: ', $e;
}
?>
PharData::setAlias
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::setAlias — dummy function (Phar::setAlias is not valid for PharData)
Descrição
Non-executable tar/zip archives cannot have an alias, so this method simply throws an exception.
Parâmetros
- alias
-
A shorthand string that this archive can be referred to in phar stream wrapper access. This parameter is ignored.
Valor Retornado
Erros
Throws PharException on all method calls
PharData::setDefaultStub
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::setDefaultStub — dummy function (Phar::setDefaultStub is not valid for PharData)
Descrição
Non-executable tar/zip archives cannot have a stub, so this method simply throws an exception.
Parâmetros
- index
-
Relative path within the phar archive to run if accessed on the command-line
- webindex
-
Relative path within the phar archive to run if accessed through a web browser
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Erros
Throws PharException on all method calls
Veja Também
- Phar::setDefaultStub() - Used to set the PHP loader or bootstrap stub of a Phar archive to the default loader
Phar::setMetadata
(PHP >= 5.3.0, PECL phar >= 1.0.0)
Phar::setMetadata — Sets phar archive meta-data
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
Phar::setMetadata() should be used to store customized data that describes something about the phar archive as a complete entity. PharFileInfo::setMetadata() should be used for file-specific meta-data. Meta-data can slow down the performance of loading a phar archive if the data is large.
Some possible uses for meta-data include specifying which file within the archive should be used to bootstrap the archive, or the location of a file manifest like » PEAR's package.xml file. However, any useful data that describes the phar archive may be stored.
Parâmetros
- metadata
-
Any PHP variable containing information to store that describes the phar archive
Valor Retornado
Não há valor retornado.
Exemplos
Exemplo #1 A Phar::setMetadata() example
<?php
// make sure it doesn't exist
@unlink('brandnewphar.phar');
try {
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
$p['file.php'] = '<?php echo "hello"';
$p->setMetadata(array('bootstrap' => 'file.php'));
var_dump($p->getMetadata());
} catch (Exception $e) {
echo 'Could not create and/or modify phar:', $e;
}
?>
O exemplo acima irá imprimir:
array(1) {
["bootstrap"]=>
string(8) "file.php"
}
Veja Também
- Phar::getMetadata() - Returns phar archive meta-data
- Phar::delMetadata() - Deletes the global metadata of the phar
- Phar::hasMetadata() - Returns whether phar has global meta-data
Phar::setSignatureAlgorithm
(PHP >= 5.3.0, PECL phar >= 1.1.0)
Phar::setSignatureAlgorithm — set the signature algorithm for a phar and apply it. The
Descrição
Nota:
Esta função requer a configuração do arquivo php.ini phar.readonly ser definida como 0 para funcionar os objetos Phar. Caso contrário, uma PharException será disparada.
set the signature algorithm for a phar and apply it. The signature algorithm must be one of Phar::MD5, Phar::SHA1, Phar::SHA256, Phar::SHA512, or Phar::PGP (pgp not yet supported and falls back to SHA-1).
Parâmetros
- sigtype
-
One of Phar::MD5, Phar::SHA1, Phar::SHA256, Phar::SHA512, or Phar::PGP
Valor Retornado
Não há valor retornado.
Erros
Throws UnexpectedValueException for many errors, BadMethodCallException if called for a zip- or a tar-based phar archive, and a PharException if any problems occur flushing changes to disk.
Veja Também
- Phar::getSupportedSignatures() - Return array of supported signature types
- Phar::getSignature() - Return MD5/SHA1/SHA256/SHA512/OpenSSL signature of a Phar archive
PharData::setStub
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharData::setStub — dummy function (Phar::setStub is not valid for PharData)
Descrição
Non-executable tar/zip archives cannot have a stub, so this method simply throws an exception.
Parâmetros
- stub
-
A string or an open stream handle to use as the executable stub for this phar archive. This parameter is ignored.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Erros
Throws PharException on all method calls
Índice
- PharData::addEmptyDir — Add an empty directory to the tar/zip archive
- PharData::addFile — Add a file from the filesystem to the tar/zip archive
- PharData::addFromString — Add a file from the filesystem to the tar/zip archive
- PharData::buildFromDirectory — Construct a tar/zip archive from the files within a directory.
- PharData::buildFromIterator — Construct a tar or zip archive from an iterator.
- PharData::compress — Compresses the entire tar/zip archive using Gzip or Bzip2 compression
- PharData::compressFiles — Compresses all files in the current tar/zip archive
- PharData::__construct — Construct a non-executable tar or zip archive object
- PharData::convertToData — Convert a phar archive to a non-executable tar or zip file
- PharData::convertToExecutable — Convert a non-executable tar/zip archive to an executable phar archive
- PharData::copy — Copy a file internal to the phar archive to another new file within the phar
- PharData::decompress — Decompresses the entire Phar archive
- PharData::decompressFiles — Decompresses all files in the current zip archive
- PharData::delMetadata — Deletes the global metadata of a zip archive
- PharData::delete — Delete a file within a tar/zip archive
- PharData::extractTo — Extract the contents of a tar/zip archive to a directory
- PharData::isWritable — Returns true if the tar/zip archive can be modified
- PharData::offsetSet — set the contents of a file within the tar/zip to those of an external file or string
- PharData::offsetUnset — remove a file from a tar/zip archive
- PharData::setAlias — dummy function (Phar::setAlias is not valid for PharData)
- PharData::setDefaultStub — dummy function (Phar::setDefaultStub is not valid for PharData)
- Phar::setMetadata — Sets phar archive meta-data
- Phar::setSignatureAlgorithm — set the signature algorithm for a phar and apply it. The
- PharData::setStub — dummy function (Phar::setStub is not valid for PharData)
The PharFileInfo class
(No version information available, might only be in SVN)
Introdução
The PharFileInfo class provides a high-level interface to the contents and attributes of a single file within a phar archive.
Sinopse da classe
PharFileInfo::chmod
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::chmod — Sets file-specific permission bits
Descrição
PharFileInfo::chmod() allows setting of the executable file permissions bit, as well as read-only bits. Writeable bits are ignored, and set at runtime based on the phar.readonly INI variable. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed if the file is within a Phar archive. Files within PharData archives do not have this restriction.
Valor Retornado
Não há valor retornado.
Exemplos
Exemplo #1 A PharFileInfo::chmod() example
<?php
// make sure it doesn't exist
@unlink('brandnewphar.phar');
try {
$p = new Phar('brandnewphar.phar', 0, 'brandnewphar.phar');
$p['file.sh'] = '#!/usr/local/lib/php
<?php echo "hi"; ?>';
// set executable bit
$p['file.sh']->chmod(0555);
var_dump($p['file.sh']->isExecutable());
} catch (Exception $e) {
echo 'Could not create/modify phar: ', $e;
}
?>
O exemplo acima irá imprimir:
bool(true)
PharFileInfo::compress
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharFileInfo::compress — Compresses the current Phar entry with either zlib or bzip2 compression
Descrição
This method compresses the file inside the Phar archive using either bzip2 compression or zlib compression. The bzip2 or zlib extension must be enabled to take advantage of this feature. In addition, if the file is already compressed, the respective extension must be enabled in order to decompress the file. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed if the file is within a Phar archive. Files within PharData archives do not have this restriction.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Erros
Throws BadMethodCallException if the phar.readonly INI variable is on, or if the bzip2/zlib extension is not available.
Exemplos
Exemplo #1 A PharFileInfo::compress() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$file = $p['myfile.txt'];
var_dump($file->isCompressed(Phar::BZ2));
$p['myfile.txt']->compress(Phar::BZ2);
var_dump($file->isCompressed(Phar::BZ2));
} catch (Exception $e) {
echo 'Create/modify operations on my.phar failed: ', $e;
}
?>
O exemplo acima irá imprimir:
bool(false) bool(true)
Veja Também
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressFiles() - Compresses all files in the current Phar archive
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::decompress() - Decompresses the entire Phar archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
PharFileInfo::__construct
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::__construct — Construct a Phar entry object
Descrição
This should not be called directly. Instead, a PharFileInfo object is initialized by calling Phar::offsetGet() through array access.
Parâmetros
- entry
-
The full url to retrieve a file. If you wish to retrieve the information for the file my/file.php from the phar boo.phar, the entry should be phar://boo.phar/my/file.php.
Erros
Throws BadMethodCallException if __construct() is called twice. Throws UnexpectedValueException if the phar URL requested is malformed, the requested phar cannot be opened, or the file can't be found within the phar.
Exemplos
Exemplo #1 A PharFileInfo::__construct() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['testfile.txt'] = "hi\nthere\ndude";
$file = $p['testfile.txt'];
foreach ($file as $line => $text) {
echo "line number $line: $text";
}
// this also works
$file = new PharFileInfo('phar:///path/to/my.phar/testfile.txt');
foreach ($file as $line => $text) {
echo "line number $line: $text";
}
} catch (Exception $e) {
echo 'Phar operations failed: ', $e;
}
?>
O exemplo acima irá imprimir:
line number 1: hi line number 2: there line number 3: dude line number 1: hi line number 2: there line number 3: dude
PharFileInfo::decompress
(PHP >= 5.3.0, PECL phar >= 2.0.0)
PharFileInfo::decompress — Decompresses the current Phar entry within the phar
Descrição
This method decompresses the file inside the Phar archive. Depending on how the file is compressed, the bzip2 or zlib extensions must be enabled to take advantage of this feature. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed if the file is within a Phar archive. Files within PharData archives do not have this restriction.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Erros
Throws BadMethodCallException if the phar.readonly INI variable is on, or if the bzip2/zlib extension is not available.
Exemplos
Exemplo #1 A PharFileInfo::decompress() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$file = $p['myfile.txt'];
$file->compress(Phar::GZ);
var_dump($file->isCompressed());
$p['myfile.txt']->decompress();
var_dump($file->isCompressed());
} catch (Exception $e) {
echo 'Create/modify failed for my.phar: ', $e;
}
?>
O exemplo acima irá imprimir:
int(4096) bool(false)
Veja Também
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressFiles() - Compresses all files in the current Phar archive
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::decompress() - Decompresses the entire Phar archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
PharFileInfo::delMetadata
(PHP >= 5.3.0, PECL phar >= 1.2.0)
PharFileInfo::delMetadata — Deletes the metadata of the entry
Descrição
Deletes the metadata of the entry, if any.
Parâmetros
No parameters.
Valor Retornado
Returns TRUE if successful, FALSE if the entry had no metadata. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed if the file is within a Phar archive. Files within PharData archives do not have this restriction.
Erros
Throws PharException if errors occurred while flushing changes to disk, and BadMethodCallException if write access is disabled.
Exemplos
Exemplo #1 A PharFileInfo::delMetaData() example
<?php
try {
$a = new Phar('myphar.phar');
$a['hi'] = 'hi';
var_dump($a['hi']->delMetadata());
$a['hi']->setMetadata('there');
var_dump($a['hi']->delMetadata());
var_dump($a['hi']->delMetadata());
} catch (Exception $e) {
// handle errors
}
?>
O exemplo acima irá imprimir:
bool(false) bool(true) bool(false)
Veja Também
- PharFileInfo::setMetadata() - Sets file-specific meta-data saved with a file
- PharFileInfo::hasMetadata() - Returns the metadata of the entry
- PharFileInfo::getMetadata() - Returns file-specific meta-data saved with a file
- Phar::setMetadata() - Sets phar archive meta-data
- Phar::hasMetadata() - Returns whether phar has global meta-data
- Phar::getMetadata() - Returns phar archive meta-data
PharFileInfo::getCRC32
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::getCRC32 — Returns CRC32 code or throws an exception if CRC has not been verified
Descrição
This returns the crc32() checksum of the file within the Phar archive.
Valor Retornado
The crc32() checksum of the file within the Phar archive.
Erros
Throws BadMethodCallException if the file has not yet had its CRC32 verified. This should be impossible with normal use, as the CRC is verified upon opening the file for reading or writing.
Exemplos
Exemplo #1 A PharFileInfo::getCRC32() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$file = $p['myfile.txt'];
echo $file->getCRC32();
} catch (Exception $e) {
echo 'Write operations on my.phar.phar failed: ', $e;
}
?>
O exemplo acima irá imprimir:
3633523372
PharFileInfo::getCompressedSize
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::getCompressedSize — Returns the actual size of the file (with compression) inside the Phar archive
Descrição
This returns the size of the file within the Phar archive. Uncompressed files will return the same value for getCompressedSize as they will with filesize()
Valor Retornado
The size in bytes of the file within the Phar archive on disk.
Exemplos
Exemplo #1 A PharFileInfo::getCompressedSize() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$file = $p['myfile.txt'];
echo $file->getCompressedSize();
} catch (Exception $e) {
echo 'Write operations failed on my.phar: ', $e;
}
?>
O exemplo acima irá imprimir:
2
Veja Também
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::decompress() - Decompresses the entire Phar archive
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
- Phar::compressFiles() - Compresses all files in the current Phar archive
PharFileInfo::getMetadata
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::getMetadata — Returns file-specific meta-data saved with a file
Descrição
Return meta-data that was saved in the Phar archive's manifest for this file.
Parâmetros
Valor Retornado
any PHP variable that can be serialized and is stored as meta-data for the file, or NULL if no meta-data is stored.
Exemplos
Exemplo #1 A PharFileInfo::getMetadata() example
<?php
// make sure it doesn't exist
@unlink('brandnewphar.phar');
try {
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
$p['file.txt'] = 'hello';
$p['file.txt']->setMetadata(array('user' => 'bill', 'mime-type' => 'text/plain'));
var_dump($p['file.txt']->getMetadata());
} catch (Exception $e) {
echo 'Could not create/modify brandnewphar.phar: ', $e;
}
?>
O exemplo acima irá imprimir:
array(2) {
["user"]=>
string(4) "bill"
["mime-type"]=>
string(10) "text/plain"
}
Veja Também
- PharFileInfo::setMetadata() - Sets file-specific meta-data saved with a file
- PharFileInfo::hasMetadata() - Returns the metadata of the entry
- PharFileInfo::delMetadata() - Deletes the metadata of the entry
- Phar::setMetadata() - Sets phar archive meta-data
- Phar::hasMetadata() - Returns whether phar has global meta-data
- Phar::getMetadata() - Returns phar archive meta-data
PharFileInfo::getPharFlags
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::getPharFlags — Returns the Phar file entry flags
Descrição
This returns the flags set in the manifest for a Phar. This will always return 0 in the current implementation.
Valor Retornado
The Phar flags (always 0 in the current implementation)
Exemplos
Exemplo #1 A PharFileInfo::getPharFlags() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$file = $p['myfile.txt'];
var_dump($file->getPharFlags());
} catch (Exception $e) {
echo 'Could not create/modify my.phar: ', $e;
}
?>
O exemplo acima irá imprimir:
int(0)
PharFileInfo::hasMetadata
(PHP >= 5.3.0, PECL phar >= 1.2.0)
PharFileInfo::hasMetadata — Returns the metadata of the entry
Descrição
Returns the metadata of a file within a phar archive.
Parâmetros
No parameters.
Valor Retornado
Returns FALSE if no metadata is set or is NULL, TRUE if metadata is not NULL
Veja Também
- PharFileInfo::setMetadata() - Sets file-specific meta-data saved with a file
- PharFileInfo::getMetadata() - Returns file-specific meta-data saved with a file
- PharFileInfo::delMetadata() - Deletes the metadata of the entry
- Phar::setMetadata() - Sets phar archive meta-data
- Phar::hasMetadata() - Returns whether phar has global meta-data
- Phar::getMetadata() - Returns phar archive meta-data
PharFileInfo::isCRCChecked
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::isCRCChecked — Returns whether file entry has had its CRC verified
Descrição
This returns whether a file within a Phar archive has had its CRC verified.
Valor Retornado
TRUE if the file has had its CRC verified, FALSE if not.
Exemplos
Exemplo #1 A PharFileInfo::isCRCChecked() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$file = $p['myfile.txt'];
var_dump($file->isCRCChecked());
} catch (Exception $e) {
echo 'Create/modify operations failed on my.phar: ', $e;
}
?>
O exemplo acima irá imprimir:
bool(true)
PharFileInfo::isCompressed
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::isCompressed — Returns whether the entry is compressed
Descrição
This returns whether a file is compressed within a Phar archive with either Gzip or Bzip2 compression.
Parâmetros
- compression_type
-
One of Phar::GZ or Phar::BZ2, defaults to any compression.
Valor Retornado
TRUE if the file is compressed within the Phar archive, FALSE if not.
Exemplos
Exemplo #1 A PharFileInfo::isCompressed() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p['myfile2.txt']->setCompressedGZ();
$file = $p['myfile.txt'];
$file2 = $p['myfile2.txt'];
var_dump($file->isCompressed());
var_dump($file2->isCompressed());
} catch (Exception $e) {
echo 'Create/modify on phar my.phar failed: ', $e;
}
?>
O exemplo acima irá imprimir:
bool(false) bool(true)
Veja Também
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::decompress() - Decompresses the current Phar entry within the phar
- PharFileInfo::compress() - Compresses the current Phar entry with either zlib or bzip2 compression
- Phar::decompress() - Decompresses the entire Phar archive
- Phar::compress() - Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::decompressFiles() - Decompresses all files in the current Phar archive
- Phar::compressFiles() - Compresses all files in the current Phar archive
PharFileInfo::isCompressedBZIP2
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::isCompressedBZIP2 — Returns whether the entry is compressed using bzip2
Descrição
Nota:
Este método tem sido removido da extensão phar a partir da versão 2.0.0. Implementações alternativas são possíveis usando PharFileInfo::isCompressed(), PharFileInfo::decompress(), e PharFileInfo::compress().
This returns whether a file is compressed within a Phar archive with Bzip2 compression.
Valor Retornado
TRUE if the file is compressed within the Phar archive using Bzip2, FALSE if not.
Exemplos
Exemplo #1 A PharFileInfo::isCompressedBZIP2() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p['myfile3.txt'] = 'hi';
$p['myfile2.txt']->setCompressedGZ();
$p['myfile3.txt']->setCompressedBZIP2();
$file = $p['myfile.txt'];
$file2 = $p['myfile2.txt'];
$file3 = $p['myfile3.txt'];
var_dump($file->isCompressedBZIP2());
var_dump($file2->isCompressedBZIP2());
var_dump($file3->isCompressedBZIP2());
} catch (Exception $e) {
echo 'Create/modify on phar my.phar failed: ', $e;
}
?>
O exemplo acima irá imprimir:
bool(false) bool(false) bool(true)
Veja Também
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::isCompressedGZ() - Returns whether the entry is compressed using gz
- PharFileInfo::setCompressedBZIP2() - Compresses the current Phar entry within the phar using Bzip2 compression
- PharFileInfo::setUncompressed() - Uncompresses the current Phar entry within the phar, if it is compressed
- PharFileInfo::setCompressedGZ() - Compresses the current Phar entry within the phar using gz compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressAllFilesBZIP2() - Compresses all files in the current Phar archive using Bzip2 compression
- Phar::compressAllFilesGZ() - Compresses all files in the current Phar archive using Gzip compression
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::uncompressAllFiles() - Uncompresses all files in the current Phar archive
PharFileInfo::isCompressedGZ
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::isCompressedGZ — Returns whether the entry is compressed using gz
Descrição
Nota:
Este método tem sido removido da extensão phar a partir da versão 2.0.0. Implementações alternativas são possíveis usando PharFileInfo::isCompressed(), PharFileInfo::decompress(), e PharFileInfo::compress().
This returns whether a file is compressed within a Phar archive with Gzip compression.
Valor Retornado
TRUE if the file is compressed within the Phar archive using Gzip, FALSE if not.
Exemplos
Exemplo #1 A PharFileInfo::isCompressedGZ() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$p['myfile2.txt'] = 'hi';
$p['myfile3.txt'] = 'hi';
$p['myfile2.txt']->setCompressedGZ();
$p['myfile3.txt']->setCompressedBZIP2();
$file = $p['myfile.txt'];
$file2 = $p['myfile2.txt'];
$file3 = $p['myfile3.txt'];
var_dump($file->isCompressedGZ());
var_dump($file2->isCompressedGZ());
var_dump($file3->isCompressedGZ());
} catch (Exception $e) {
echo 'Create/modify on phar my.phar failed: ', $e;
}
?>
O exemplo acima irá imprimir:
bool(false) bool(true) bool(false)
Veja Também
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressedBZIP2() - Returns whether the entry is compressed using bzip2
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::setCompressedBZIP2() - Compresses the current Phar entry within the phar using Bzip2 compression
- PharFileInfo::setUncompressed() - Uncompresses the current Phar entry within the phar, if it is compressed
- PharFileInfo::setCompressedGZ() - Compresses the current Phar entry within the phar using gz compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressAllFilesBZIP2() - Compresses all files in the current Phar archive using Bzip2 compression
- Phar::compressAllFilesGZ() - Compresses all files in the current Phar archive using Gzip compression
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::uncompressAllFiles() - Uncompresses all files in the current Phar archive
PharFileInfo::setCompressedBZIP2
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::setCompressedBZIP2 — Compresses the current Phar entry within the phar using Bzip2 compression
Descrição
Nota:
Este método tem sido removido da extensão phar a partir da versão 2.0.0. Implementações alternativas são possíveis usando PharFileInfo::isCompressed(), PharFileInfo::decompress(), e PharFileInfo::compress().
This method compresses the file inside the Phar archive using bzip2 compression. The bzip2 extension must be enabled to take advantage of this feature. In addition, if the file is already compressed using gzip compression, the zlib extension must be enabled in order to decompress the file. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Erros
Throws BadMethodCallException if the phar.readonly INI variable is on, or if the bzip2 extension is not available.
Exemplos
Exemplo #1 A PharFileInfo::setCompressedBZIP2() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$file = $p['myfile.txt'];
var_dump($file->isCompressedBZIP2());
$p['myfile.txt']->setCompressedBZIP2();
var_dump($file->isCompressedBZIP2());
} catch (Exception $e) {
echo 'Create/modify operations on my.phar failed: ', $e;
}
?>
O exemplo acima irá imprimir:
bool(false) bool(true)
Veja Também
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressedBZIP2() - Returns whether the entry is compressed using bzip2
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::isCompressedGZ() - Returns whether the entry is compressed using gz
- PharFileInfo::setUncompressed() - Uncompresses the current Phar entry within the phar, if it is compressed
- PharFileInfo::setCompressedGZ() - Compresses the current Phar entry within the phar using gz compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressAllFilesBZIP2() - Compresses all files in the current Phar archive using Bzip2 compression
- Phar::compressAllFilesGZ() - Compresses all files in the current Phar archive using Gzip compression
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::uncompressAllFiles() - Uncompresses all files in the current Phar archive
PharFileInfo::setCompressedGZ
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::setCompressedGZ — Compresses the current Phar entry within the phar using gz compression
Descrição
Nota:
Este método tem sido removido da extensão phar a partir da versão 2.0.0. Implementações alternativas são possíveis usando PharFileInfo::isCompressed(), PharFileInfo::decompress(), e PharFileInfo::compress().
This method compresses the file inside the Phar archive using gzip compression. The zlib extension must be enabled to take advantage of this feature. In addition, if the file is already compressed using bzip2 compression, the bzip2 extension must be enabled in order to decompress the file. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Erros
Throws BadMethodCallException if the phar.readonly INI variable is on, or if the zlib extension is not available.
Exemplos
Exemplo #1 A PharFileInfo::setCompressedGZ() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$file = $p['myfile.txt'];
var_dump($file->isCompressedGZ());
$p['myfile.txt']->setCompressedGZ();
var_dump($file->isCompressedGZ());
} catch (Exception $e) {
echo 'Create/modify operations on my.phar failed: ', $e;
}
?>
O exemplo acima irá imprimir:
bool(false) bool(true)
Veja Também
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressedBZIP2() - Returns whether the entry is compressed using bzip2
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::isCompressedGZ() - Returns whether the entry is compressed using gz
- PharFileInfo::setCompressedBZIP2() - Compresses the current Phar entry within the phar using Bzip2 compression
- PharFileInfo::setUncompressed() - Uncompresses the current Phar entry within the phar, if it is compressed
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressAllFilesBZIP2() - Compresses all files in the current Phar archive using Bzip2 compression
- Phar::compressAllFilesGZ() - Compresses all files in the current Phar archive using Gzip compression
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::uncompressAllFiles() - Uncompresses all files in the current Phar archive
PharFileInfo::setMetadata
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::setMetadata — Sets file-specific meta-data saved with a file
Descrição
PharFileInfo::setMetadata() should only be used to store customized data in a file that cannot be represented with existing information stored with a file. Meta-data can significantly slow down the performance of loading a phar archive if the data is large, or if there are many files containing meta-data. It is important to note that file permissions are natively supported inside a phar; it is possible to set them with the PharFileInfo::chmod() method. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed if the file is within a Phar archive. Files within PharData archives do not have this restriction.
Some possible uses for meta-data include passing a user/group that should be set when a file is extracted from the phar to disk. Other uses could include explicitly specifying a MIME type to return. However, any useful data that describes a file, but should not be contained inside of it may be stored.
Parâmetros
- metadata
-
Any PHP variable containing information to store alongside a file
Valor Retornado
Não há valor retornado.
Exemplos
Exemplo #1 A PharFileInfo::setMetadata() example
<?php
// make sure it doesn't exist
@unlink('brandnewphar.phar');
try {
$p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
$p['file.txt'] = 'hello';
$p['file.txt']->setMetadata(array('user' => 'bill', 'mime-type' => 'text/plain'));
var_dump($p['file.txt']->getMetaData());
} catch (Exception $e) {
echo 'Could not create/modify phar: ', $e;
}
?>
O exemplo acima irá imprimir:
array(2) {
["user"]=>
string(4) "bill"
["mime-type"]=>
string(10) "text/plain"
}
Veja Também
- PharFileInfo::hasMetadata() - Returns the metadata of the entry
- PharFileInfo::getMetadata() - Returns file-specific meta-data saved with a file
- PharFileInfo::delMetadata() - Deletes the metadata of the entry
- Phar::setMetadata() - Sets phar archive meta-data
- Phar::hasMetadata() - Returns whether phar has global meta-data
- Phar::getMetadata() - Returns phar archive meta-data
PharFileInfo::setUncompressed
(PHP >= 5.3.0, PECL phar >= 1.0.0)
PharFileInfo::setUncompressed — Uncompresses the current Phar entry within the phar, if it is compressed
Descrição
Nota:
Este método tem sido removido da extensão phar a partir da versão 2.0.0. Implementações alternativas são possíveis usando PharFileInfo::isCompressed(), PharFileInfo::decompress(), e PharFileInfo::compress().
This method decompresses the file inside the Phar archive. Depending on how the file is compressed, the bzip2 or zlib extensions must be enabled to take advantage of this feature. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Erros
Throws BadMethodCallException if the phar.readonly INI variable is on, or if the bzip2/zlib extension is not available.
Exemplos
Exemplo #1 A PharFileInfo::setUncompressed() example
<?php
try {
$p = new Phar('/path/to/my.phar', 0, 'my.phar');
$p['myfile.txt'] = 'hi';
$file = $p['myfile.txt'];
$file->setCompressedGZ();
var_dump($file->isCompressed());
$p['myfile.txt']->setUncompressed();
var_dump($file->isCompressed());
} catch (Exception $e) {
echo 'Create/modify failed for my.phar: ', $e;
}
?>
O exemplo acima irá imprimir:
bool(true) bool(false)
Veja Também
- PharFileInfo::getCompressedSize() - Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::isCompressedBZIP2() - Returns whether the entry is compressed using bzip2
- PharFileInfo::isCompressed() - Returns whether the entry is compressed
- PharFileInfo::isCompressedGZ() - Returns whether the entry is compressed using gz
- PharFileInfo::setCompressedBZIP2() - Compresses the current Phar entry within the phar using Bzip2 compression
- PharFileInfo::setCompressedGZ() - Compresses the current Phar entry within the phar using gz compression
- Phar::canCompress() - Returns whether phar extension supports compression using either zlib or bzip2
- Phar::isCompressed() - Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::compressAllFilesBZIP2() - Compresses all files in the current Phar archive using Bzip2 compression
- Phar::compressAllFilesGZ() - Compresses all files in the current Phar archive using Gzip compression
- Phar::getSupportedCompression() - Return array of supported compression algorithms
- Phar::uncompressAllFiles() - Uncompresses all files in the current Phar archive
Índice
- PharFileInfo::chmod — Sets file-specific permission bits
- PharFileInfo::compress — Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::__construct — Construct a Phar entry object
- PharFileInfo::decompress — Decompresses the current Phar entry within the phar
- PharFileInfo::delMetadata — Deletes the metadata of the entry
- PharFileInfo::getCRC32 — Returns CRC32 code or throws an exception if CRC has not been verified
- PharFileInfo::getCompressedSize — Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::getMetadata — Returns file-specific meta-data saved with a file
- PharFileInfo::getPharFlags — Returns the Phar file entry flags
- PharFileInfo::hasMetadata — Returns the metadata of the entry
- PharFileInfo::isCRCChecked — Returns whether file entry has had its CRC verified
- PharFileInfo::isCompressed — Returns whether the entry is compressed
- PharFileInfo::isCompressedBZIP2 — Returns whether the entry is compressed using bzip2
- PharFileInfo::isCompressedGZ — Returns whether the entry is compressed using gz
- PharFileInfo::setCompressedBZIP2 — Compresses the current Phar entry within the phar using Bzip2 compression
- PharFileInfo::setCompressedGZ — Compresses the current Phar entry within the phar using gz compression
- PharFileInfo::setMetadata — Sets file-specific meta-data saved with a file
- PharFileInfo::setUncompressed — Uncompresses the current Phar entry within the phar, if it is compressed
The PharException class
(Unknown)
Introdução
The PharException class provides a phar-specific exception class for try/catch blocks.
Sinopse da classe
PharException
(Unknown)
PharException — The PharException class provides a phar-specific exception class for try/catch blocks.
Descrição
Índice
- PharException — The PharException class provides a phar-specific exception class for try/catch blocks.
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Using Phar Archives
- Creating Phar Archives
- What makes a phar a phar and not a tar or a zip?
- Phar — The Phar class
- Phar::addEmptyDir — Add an empty directory to the phar archive
- Phar::addFile — Add a file from the filesystem to the phar archive
- Phar::addFromString — Add a file from the filesystem to the phar archive
- Phar::apiVersion — Returns the api version
- Phar::buildFromDirectory — Construct a phar archive from the files within a directory.
- Phar::buildFromIterator — Construct a phar archive from an iterator.
- Phar::canCompress — Returns whether phar extension supports compression using either zlib or bzip2
- Phar::canWrite — Returns whether phar extension supports writing and creating phars
- Phar::compress — Compresses the entire Phar archive using Gzip or Bzip2 compression
- Phar::compressAllFilesBZIP2 — Compresses all files in the current Phar archive using Bzip2 compression
- Phar::compressAllFilesGZ — Compresses all files in the current Phar archive using Gzip compression
- Phar::compressFiles — Compresses all files in the current Phar archive
- Phar::__construct — Construct a Phar archive object
- Phar::convertToData — Convert a phar archive to a non-executable tar or zip file
- Phar::convertToExecutable — Convert a phar archive to another executable phar archive file format
- Phar::copy — Copy a file internal to the phar archive to another new file within the phar
- Phar::count — Returns the number of entries (files) in the Phar archive
- Phar::createDefaultStub — Create a phar-file format specific stub
- Phar::decompress — Decompresses the entire Phar archive
- Phar::decompressFiles — Decompresses all files in the current Phar archive
- Phar::delMetadata — Deletes the global metadata of the phar
- Phar::delete — Delete a file within a phar archive
- Phar::extractTo — Extract the contents of a phar archive to a directory
- Phar::getMetadata — Returns phar archive meta-data
- Phar::getModified — Return whether phar was modified
- Phar::getSignature — Return MD5/SHA1/SHA256/SHA512/OpenSSL signature of a Phar archive
- Phar::getStub — Return the PHP loader or bootstrap stub of a Phar archive
- Phar::getSupportedCompression — Return array of supported compression algorithms
- Phar::getSupportedSignatures — Return array of supported signature types
- Phar::getVersion — Return version info of Phar archive
- Phar::hasMetadata — Returns whether phar has global meta-data
- Phar::interceptFileFuncs — instructs phar to intercept fopen, file_get_contents, opendir, and all of the stat-related functions
- Phar::isBuffering — Used to determine whether Phar write operations are being buffered, or are flushing directly to disk
- Phar::isCompressed — Returns Phar::GZ or PHAR::BZ2 if the entire phar archive is compressed (.tar.gz/tar.bz and so on)
- Phar::isFileFormat — Returns true if the phar archive is based on the tar/phar/zip file format depending on the parameter
- Phar::isValidPharFilename — Returns whether the given filename is a valid phar filename
- Phar::isWritable — Returns true if the phar archive can be modified
- Phar::loadPhar — Loads any phar archive with an alias
- Phar::mapPhar — Reads the currently executed file (a phar) and registers its manifest
- Phar::mount — Mount an external path or file to a virtual location within the phar archive
- Phar::mungServer — Defines a list of up to 4 $_SERVER variables that should be modified for execution
- Phar::offsetExists — determines whether a file exists in the phar
- Phar::offsetGet — Gets a PharFileInfo object for a specific file
- Phar::offsetSet — set the contents of an internal file to those of an external file
- Phar::offsetUnset — remove a file from a phar
- Phar::running — Returns the full path on disk or full phar URL to the currently executing Phar archive
- Phar::setAlias — Set the alias for the Phar archive
- Phar::setDefaultStub — Used to set the PHP loader or bootstrap stub of a Phar archive to the default loader
- Phar::setMetadata — Sets phar archive meta-data
- Phar::setSignatureAlgorithm — set the signature algorithm for a phar and apply it.
- Phar::setStub — Used to set the PHP loader or bootstrap stub of a Phar archive
- Phar::startBuffering — Start buffering Phar write operations, do not modify the Phar object on disk
- Phar::stopBuffering — Stop buffering write requests to the Phar archive, and save changes to disk
- Phar::uncompressAllFiles — Uncompresses all files in the current Phar archive
- Phar::unlinkArchive — Completely remove a phar archive from disk and from memory
- Phar::webPhar — mapPhar for web-based phars. front controller for web applications
- PharData — The PharData class
- PharData::addEmptyDir — Add an empty directory to the tar/zip archive
- PharData::addFile — Add a file from the filesystem to the tar/zip archive
- PharData::addFromString — Add a file from the filesystem to the tar/zip archive
- PharData::buildFromDirectory — Construct a tar/zip archive from the files within a directory.
- PharData::buildFromIterator — Construct a tar or zip archive from an iterator.
- PharData::compress — Compresses the entire tar/zip archive using Gzip or Bzip2 compression
- PharData::compressFiles — Compresses all files in the current tar/zip archive
- PharData::__construct — Construct a non-executable tar or zip archive object
- PharData::convertToData — Convert a phar archive to a non-executable tar or zip file
- PharData::convertToExecutable — Convert a non-executable tar/zip archive to an executable phar archive
- PharData::copy — Copy a file internal to the phar archive to another new file within the phar
- PharData::decompress — Decompresses the entire Phar archive
- PharData::decompressFiles — Decompresses all files in the current zip archive
- PharData::delMetadata — Deletes the global metadata of a zip archive
- PharData::delete — Delete a file within a tar/zip archive
- PharData::extractTo — Extract the contents of a tar/zip archive to a directory
- PharData::isWritable — Returns true if the tar/zip archive can be modified
- PharData::offsetSet — set the contents of a file within the tar/zip to those of an external file or string
- PharData::offsetUnset — remove a file from a tar/zip archive
- PharData::setAlias — dummy function (Phar::setAlias is not valid for PharData)
- PharData::setDefaultStub — dummy function (Phar::setDefaultStub is not valid for PharData)
- Phar::setMetadata — Sets phar archive meta-data
- Phar::setSignatureAlgorithm — set the signature algorithm for a phar and apply it. The
- PharData::setStub — dummy function (Phar::setStub is not valid for PharData)
- PharFileInfo — The PharFileInfo class
- PharFileInfo::chmod — Sets file-specific permission bits
- PharFileInfo::compress — Compresses the current Phar entry with either zlib or bzip2 compression
- PharFileInfo::__construct — Construct a Phar entry object
- PharFileInfo::decompress — Decompresses the current Phar entry within the phar
- PharFileInfo::delMetadata — Deletes the metadata of the entry
- PharFileInfo::getCRC32 — Returns CRC32 code or throws an exception if CRC has not been verified
- PharFileInfo::getCompressedSize — Returns the actual size of the file (with compression) inside the Phar archive
- PharFileInfo::getMetadata — Returns file-specific meta-data saved with a file
- PharFileInfo::getPharFlags — Returns the Phar file entry flags
- PharFileInfo::hasMetadata — Returns the metadata of the entry
- PharFileInfo::isCRCChecked — Returns whether file entry has had its CRC verified
- PharFileInfo::isCompressed — Returns whether the entry is compressed
- PharFileInfo::isCompressedBZIP2 — Returns whether the entry is compressed using bzip2
- PharFileInfo::isCompressedGZ — Returns whether the entry is compressed using gz
- PharFileInfo::setCompressedBZIP2 — Compresses the current Phar entry within the phar using Bzip2 compression
- PharFileInfo::setCompressedGZ — Compresses the current Phar entry within the phar using gz compression
- PharFileInfo::setMetadata — Sets file-specific meta-data saved with a file
- PharFileInfo::setUncompressed — Uncompresses the current Phar entry within the phar, if it is compressed
- PharException — The PharException class
- PharException — The PharException class provides a phar-specific exception class for try/catch blocks.
Rar Archiving
Introdução
Rar is a powerful and effective archiver created by Eugene Roshal. This extension gives you possibility to read Rar archives but doesn't support writing Rar archives, because this is not supported by the UnRar library and is directly prohibited by its license.
More information about Rar and UnRar can be found at » http://www.rarlabs.com/.
Instalação/Configuração
Índice
Dependências
Nenhuma biblioteca externa é necessária para compilar esta extensão.
Instalação
Rar is currently available through PECL » http://pecl.php.net/package/rar.
Also you can use the PECL installer to install the Rar extension, using the following command: pecl -v install rar.
You can always download the tar.gz package and install Rar by hand:
Exemplo #1 Rar installation
gunzip rar-xxx.tgz tar -xvf rar-xxx.tar cd rar-xxx phpize ./configure && make && make install
Windows users will enable php_rar.dll inside of php.ini in order to use these functions. Uma DLL para esta extenção PECL esta atualmente indisponível. Veja também a seção compilando no Windows section.
Configurações em Execução
Esta extensão não define nenhum parâmetro de configuração no php.ini.
Tipos Resource
This extension registers three internal classes: The archive representations returned by rar_open() – RarArchive –, the entry representations returned by rar_list() and rar_entry_get() – RarEntry and the exception type RarException.
This extension also register a stream resource, called "rar" and a URL wrapper called "rar wrapper" and registered under the prefix "rar".
Constantes pré-definidas
As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.
- RAR_HOST_MSDOS (integer)
- Use RarEntry::HOST_MSDOS instead.
- RAR_HOST_OS2 (integer)
- Use RarEntry::HOST_OS2 instead.
- RAR_HOST_WIN32 (integer)
- Use RarEntry::HOST_WIN32 instead.
- RAR_HOST_UNIX (integer)
- Use RarEntry::HOST_UNIX instead.
- RAR_HOST_BEOS (integer)
- Use RarEntry::HOST_BEOS instead.
Exemplos
See also the examples under rar:// wrapper.
Exemplo #1 On-the-fly decompression
<?php
if (!array_key_exists("i", $_GET) || !is_numeric($_GET["i"]))
die("Index unspecified or non-numeric");
$index = (int) $_GET["i"];
$arch = RarArchive::open("example.rar");
if ($arch === FALSE)
die("Cannot open example.rar");
$entries = $arch->getEntries();
if ($entries === FALSE)
die("Cannot retrieve entries");
if (!array_key_exists($index, $entries))
die("No such index: $index");
$orfilename = $entries[$index]->getName(); //UTF-8 encoded
$filesize = $entries[$index]->getUnpackedSize();
/* you could check HTTP_IF_MODIFIED_SINCE here and compare with
* $entries[$index]->getFileTime(). You could also send a
* "Last modified" header */
$fp = $entries[$index]->getStream();
if ($fp === FALSE)
die("Cannot open file with index $index insided the archive.");
$arch->close(); //no longer needed; stream is independent
function detectUserAgent() {
if (!array_key_exists('HTTP_USER_AGENT', $_SERVER))
return "Other";
$uas = $_SERVER['HTTP_USER_AGENT'];
if (preg_match("@Opera/@", $uas))
return "Opera";
if (preg_match("@Firefox/@", $uas))
return "Firefox";
if (preg_match("@Chrome/@", $uas))
return "Chrome";
if (preg_match("@MSIE ([0-9.]+);@", $uas, $matches)) {
if (((float)$matches[1]) >= 7.0)
return "IE";
}
return "Other";
}
/*
* We have 3 options:
* - For FF and Opera, which support RFC 2231, use that format.
* - For IE and Chrome, use attwithfnrawpctenclong
* (http://greenbytes.de/tech/tc2231/#attwithfnrawpctenclong)
* - For the others, convert to ISO-8859-1, if possible
*/
$formatRFC2231 = 'Content-Disposition: attachment; filename*=UTF-8\'\'%s';
$formatDef = 'Content-Disposition: attachment; filename="%s"';
switch (detectUserAgent()) {
case "Opera":
case "Firefox":
$orfilename = rawurlencode($orfilename);
$format = $formatRFC2231;
break;
case "IE":
case "Chrome":
$orfilename = rawurlencode($orfilename);
$format = $formatDef;
break;
default:
if (function_exists('iconv'))
$orfilename =
@iconv("UTF-8", "ISO-8859-1//TRANSLIT", $orfilename);
$format = $formatDef;
}
header(sprintf($format, $orfilename));
//cannot send error messages from now on (headers already sent)
//replace by real content type, perhaps infering from the file extension
$contentType = "application/octet-stream";
header("Content-Type: $contentType");
header("Content-Transfer-Encoding: binary");
header("Content-Length: $filesize");
if ($_SERVER['REQUEST_METHOD'] == "HEAD")
die();
while (!feof($fp)) {
$s = @fread($fp, 8192);
if ($s === false)
break; //useless to send error messages
echo $s;
}
?>
This example opens a RAR file and presents the requested file inside the RAR archive for download to the client.
Exemplo #2 RAR extension filesystem extraction example
<?php
$rar_file = rar_open('example.rar') or die("Can't open Rar archive");
$entries = rar_list($rar_file);
foreach ($entries as $entry) {
echo 'Filename: ' . $entry->getName() . "\n";
echo 'Packed size: ' . $entry->getPackedSize() . "\n";
echo 'Unpacked size: ' . $entry->getUnpackedSize() . "\n";
$entry->extract('/dir/extract/to/');
}
rar_close($rar_file);
?>
This example opens a RAR file archive and extracts each entry to the specified directory.
Rar Funções
rar_wrapper_cache_stats
(PECL rar >= 3.0.0)
rar_wrapper_cache_stats — Cache hits and misses for the URL wrapper
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Índice
- rar_wrapper_cache_stats — Cache hits and misses for the URL wrapper
The RarArchive class
(No version information available, might only be in SVN)
Introdução
This class represents a RAR archive, which may be formed by several volumes (parts) and which contains a number of RAR entries (i.e., files, directories and other special objects such as symbolic links).
Objects of this class can be traversed, yielding the entries stored in the respective RAR archive. Those entries can also be obtained through RarArchive::getEntry() and RarArchive::getEntries().
Sinopse da classe
RarArchive::close
rar_close
(PECL rar >= 2.0.0)
RarArchive::close -- rar_close — Close RAR archive and free all resources
Descrição
Estilo orientado a objetos (method):
Estilo de procedimentos:
Close RAR archive and free all allocated resources.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Histórico
| Versão | Descrição |
|---|---|
| 2.0.0 | The RAR entries returned by RarArchive::getEntry() and RarArchive::getEntries() are now invalidated when calling this method. This means that all instance methods called for such entries and not guaranteed to succeed. |
Exemplos
Exemplo #1 Estilo orientado a objetos
<?php
$rar_arch = RarArchive::open('latest_winrar.rar');
echo $rar_arch."\n";
$rar_arch->close();
echo $rar_arch."\n";
?>
O exemplo acima irá imprimir algo similar a:
RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)
Exemplo #2 Estilo de procedimentos
<?php
$rar_arch = rar_open('latest_winrar.rar');
echo $rar_arch."\n";
rar_close($rar_arch);
echo $rar_arch."\n";
?>
RarArchive::getComment
rar_comment_get
(PECL rar >= 2.0.0)
RarArchive::getComment -- rar_comment_get — Get comment text from the RAR archive
Descrição
Estilo orientado a objetos (method):
Estilo de procedimentos:
Get the (global) comment stored in the RAR archive. It may be up to 64 KiB long.
Nota:
This extension does not support comments at the entry level.
Valor Retornado
Returns the comment or NULL if there is none.
Nota:
RAR has currently no support for unicode comments. The encoding of the result of this function is not specified, but it will probably be Windows-1252.
Exemplos
Exemplo #1 Estilo orientado a objetos
<?php
$rar_arch = RarArchive::open('commented.rar');
echo $rar_arch->getComment();
?>
O exemplo acima irá imprimir algo similar a:
This is the comment of the file commented.rar.
Exemplo #2 Estilo de procedimentos
<?php
$rar_arch = rar_open('commented.rar');
echo rar_comment_get($rar_arch);
?>
RarArchive::getEntries
rar_list
(PECL rar >= 2.0.0)
RarArchive::getEntries -- rar_list — Get full list of entries from the RAR archive
Descrição
Estilo orientado a objetos (method):
Estilo de procedimentos:
Get entries list (files and directories) from the RAR archive.
Nota:
If the archive has entries with the same name, this method, together with RarArchive foreach iteration and array-like access with numeric indexes, are the only ones to access all the entries (i.e., RarArchive::getEntry() and the rar:// wrapper are insufficient).
Valor Retornado
rar_list() returns array of RarEntry objects or FALSE on failure.
Histórico
| Versão | Descrição |
|---|---|
| 3.0.0 | Support for RAR archives with repeated entry names is no longer defective. |
Exemplos
Exemplo #1 Estilo orientado a objetos
<?php
$rar_arch = RarArchive::open('solid.rar');
if ($rar_arch === FALSE)
die("Could not open RAR archive.");
$rar_entries = $rar_arch->getEntries();
if ($rar_entries === FALSE)
die("Could retrieve entries.");
echo "Found " . count($rar_entries) . " entries.\n";
foreach ($rar_entries as $e) {
echo $e;
echo "\n";
}
$rar_arch->close();
?>
O exemplo acima irá imprimir algo similar a:
Found 2 entries. RarEntry for file "tese.txt" (23b93a7a) RarEntry for file "unrardll.txt" (2ed64b6e)
Exemplo #2 Estilo de procedimentos
<?php
$rar_arch = rar_open('solid.rar');
if ($rar_arch === FALSE)
die("Could not open RAR archive.");
$rar_entries = rar_list($rar_arch);
if ($rar_entries === FALSE)
die("Could retrieve entries.");
echo "Found " . count($rar_entries) . " entries.\n";
foreach ($rar_entries as $e) {
echo $e;
echo "\n";
}
rar_close($rar_arch);
?>
RarArchive::getEntry
rar_entry_get
(PECL rar >= 2.0.0)
RarArchive::getEntry -- rar_entry_get — Get entry object from the RAR archive
Descrição
Estilo orientado a objetos (method):
Estilo de procedimentos:
Get entry object (file or directory) from the RAR archive.
Nota:
You can also get entry objects using RarArchive::getEntries().
Note that a RAR archive can have multiple entries with the same name; this method will retrieve only the first.
Parâmetros
- rarfile
-
A RarArchive object, opened with rar_open().
- entryname
-
Path to the entry within the RAR archive.
Nota:
The path must be the same returned by RarEntry::getName().
Valor Retornado
Returns the matching RarEntry object or FALSE on failure.
Exemplos
Exemplo #1 Estilo orientado a objetos
<?php
$rar_arch = RarArchive::open('solid.rar');
if ($rar_arch === FALSE)
die("Could not open RAR archive.");
$rar_entry = $rar_arch->getEntry('tese.txt');
if ($rar_entry === FALSE)
die("Could get such entry");
echo get_class($rar_entry)."\n";
echo $rar_entry;
$rar_arch->close();
?>
O exemplo acima irá imprimir algo similar a:
RarEntry RarEntry for file "tese.txt" (23b93a7a)
Exemplo #2 Estilo de procedimentos
<?php
$rar_arch = rar_open('solid.rar');
if ($rar_arch === FALSE)
die("Could not open RAR archive.");
$rar_entry = rar_entry_get($rar_arch, 'tese.txt');
if ($rar_entry === FALSE)
die("Could get such entry");
echo get_class($rar_entry)."\n";
echo $rar_entry;
rar_close($rar_arch);
?>
RarArchive::isBroken
rar_broken_is
(PECL rar >= 3.0.0)
RarArchive::isBroken -- rar_broken_is — Test whether an archive is broken (incomplete)
Descrição
Estilo orientado a objetos (method):
Estilo de procedimentos:
This function determines whether an archive is incomplete, i.e., if a volume is missing or a volume is truncated.
Valor Retornado
Returns TRUE if the archive is broken, FALSE otherwise. This function may also return FALSE if the passed file has already been closed. The only way to tell the two cases apart is to enable exceptions with RarException::setUsingExceptions(); however, this should be unnecessary as a program should not operate on closed files.
Exemplos
Exemplo #1 Estilo orientado a objetos
<?php
function retnull() { return null; }
$file = dirname(__FILE__) . "/multi_broken.part1.rar";
/* Third argument is used to omit notice */
$arch = RarArchive::open($file, null, 'retnull');
var_dump($arch->isBroken());
?>
O exemplo acima irá imprimir algo similar a:
bool(true)
Exemplo #2 Estilo de procedimentos
<?php
function retnull() { return null; }
$file = dirname(__FILE__) . "/multi_broken.part1.rar";
/* Third argument is used to omit notice */
$arch = rar_open($file, null, 'retnull');
var_dump(rar_broken_is($arch));
?>
RarArchive::isSolid
rar_solid_is
(PECL rar >= 2.0.0)
RarArchive::isSolid -- rar_solid_is — Check whether the RAR archive is solid
Descrição
Estilo orientado a objetos (method):
Estilo de procedimentos:
Check whether the RAR archive is solid. Individual file extraction is slower on solid archives.
Valor Retornado
Returns TRUE if the archive is solid, FALSE otherwise.
Exemplos
Exemplo #1 Estilo orientado a objetos
<?php
$arch1 = RarArchive::open("store_method.rar");
$arch2 = RarArchive::open("solid.rar");
echo "$arch1: " . ($arch1->isSolid()?'yes':'no') ."\n";
echo "$arch2: " . ($arch2->isSolid()?'yes':'no') . "\n";
?>
O exemplo acima irá imprimir algo similar a:
RAR Archive "C:\php_rar\trunk\tests\store_method.rar": no RAR Archive "C:\php_rar\trunk\tests\solid.rar": yes
Exemplo #2 Estilo de procedimentos
<?php
$arch1 = rar_open("store_method.rar");
$arch2 = rar_open("solid.rar");
echo "$arch1: " . (rar_solid_is($arch1)?'yes':'no') ."\n";
echo "$arch2: " . (rar_solid_is($arch2)?'yes':'no') . "\n";
?>
RarArchive::open
rar_open
(PECL rar >= 2.0.0)
RarArchive::open -- rar_open — Open RAR archive
Descrição
Estilo orientado a objetos (method):
Estilo de procedimentos:
Open specified RAR archive and return RarArchive instance representing it.
Nota:
If opening a multi-volume archive, the path of the first volume should be passed as the first parameter. Otherwise, not all files will be shown. This is by design.
Parâmetros
- filename
-
Path to the Rar archive.
- password
-
A plain password, if needed to decrypt the headers. It will also be used by default if encrypted files are found. Note that the files may have different passwords in respect to the headers and among them.
- volume_callback
-
A function that receives one parameter – the path of the volume that was not found – and returns a string with the correct path for such volume or NULL if such volume does not exist or is not known. The programmer should ensure the passed function doesn't cause loops as this function is called repeatedly if the path returned in a previous call did not correspond to the needed volume. Specifying this parameter omits the notice that would otherwise be emitted whenever a volume is not found; an implementation that only returns NULL can therefore be used to merely omit such notices.
Prior to version 2.0.0, this function would not handle relative paths correctly. Use realpath() as a workaround.
Valor Retornado
Returns the requested RarArchive instance or FALSE on failure.
Histórico
| Versão | Descrição |
|---|---|
| 3.0.0 | volume_callback was added. |
Exemplos
Exemplo #1 Estilo orientado a objetos
<?php
$rar_arch = RarArchive::open('encrypted_headers.rar', 'samplepassword');
if ($rar_arch === FALSE)
die("Failed opening file");
$entries = $rar_arch->getEntries();
if ($entries === FALSE)
die("Failed fetching entries");
echo "Found " . count($entries) . " files.\n";
if (empty($entries))
die("No valid entries found.");
$stream = reset($entries)->getStream();
if ($stream === FALSE)
die("Failed opening first file");
$rar_arch->close();
echo "Content of first one follows:\n";
echo stream_get_contents($stream);
fclose($stream);
?>
O exemplo acima irá imprimir algo similar a:
Found 2 files. Content of first one follows: Encrypted file 1 contents.
Exemplo #2 Estilo de procedimentos
<?php
$rar_arch = rar_open('encrypted_headers.rar', 'samplepassword');
if ($rar_arch === FALSE)
die("Failed opening file");
$entries = rar_list($rar_arch);
if ($entries === FALSE)
die("Failed fetching entries");
echo "Found " . count($entries) . " files.\n";
if (empty($entries))
die("No valid entries found.");
$stream = reset($entries)->getStream();
if ($stream === FALSE)
die("Failed opening first file");
rar_close($rar_arch);
echo "Content of first one follows:\n";
echo stream_get_contents($stream);
fclose($stream);
?>
Exemplo #3 Volume Callback
<?php
/* In this example, there's a volume named multi_broken.part1.rar
* whose next volume is named multi.part2.rar */
function resolve($vol) {
if (preg_match('/_broken/', $vol))
return str_replace('_broken', '', $vol);
else
return null;
}
$rar_file1 = rar_open(dirname(__FILE__).'/multi_broken.part1.rar', null, 'resolve');
$entry = $rar_file1->getEntry('file2.txt');
$entry->extract(null, dirname(__FILE__) . "/temp_file2.txt");
?>
RarArchive::setAllowBroken
(PECL rar >= 3.0.0)
RarArchive::setAllowBroken — Whether opening broken archives is allowed
Descrição
Estilo orientado a objetos (method):
Estilo de procedimentos:
This method defines whether broken archives can be read or all the operations that attempt to extract the archive entries will fail. Broken archives are archives for which no error is detected when the file is opened but an error occurs when reading the entries.
Parâmetros
- rarfile
-
A RarArchive object, opened with rar_open().
- allow_broken
-
Whether to allow reading broken files (TRUE) or not (FALSE).
Valor Retornado
Returns TRUE or FALSE on failure. It will only fail if the file has already been closed.
Exemplos
Exemplo #1 Estilo orientado a objetos
<?php
function retnull() { return null; }
$file = dirname(__FILE__) . "/multi_broken.part1.rar";
/* Third argument omits "volume not found" message */
$a = RarArchive::open($file, null, 'retnull');
$a->setAllowBroken(true);
foreach ($a->getEntries() as $e) {
echo "$e\n";
}
var_dump(count($a));
?>
O exemplo acima irá imprimir algo similar a:
RarEntry for file "file1.txt" (52b28202) int(1)
Exemplo #2 Estilo de procedimentos
<?php
function retnull() { return null; }
$file = dirname(__FILE__) . "/multi_broken.part1.rar";
/* Third argument omits "volume not found" message */
$a = rar_open($file, null, 'retnull');
rar_allow_broken_set($a, true);
foreach (rar_list($a) as $e) {
echo "$e\n";
}
var_dump(count($a));
?>
RarArchive::__toString
(PECL rar >= 2.0.0)
RarArchive::__toString — Get text representation
Descrição
Provides a string representation for this RarArchive object. It currently shows the full path name of the archive volume that was opened and whether the resource is valid or was already closed through a call to RarArchive::close().
This method may be used only for debugging purposes, as there are no guarantees as to which information the result contains or how it is formatted.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
A textual representation of this RarArchive object. The content of this representation is unspecified.
Exemplos
Exemplo #1 RarArchive::__toString() example
<?php
$rar_arch = RarArchive::open('latest_winrar.rar');
echo $rar_arch."\n";
$rar_arch->close();
echo $rar_arch."\n";
?>
O exemplo acima irá imprimir algo similar a:
RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)
Índice
- RarArchive::close — Close RAR archive and free all resources
- RarArchive::getComment — Get comment text from the RAR archive
- RarArchive::getEntries — Get full list of entries from the RAR archive
- RarArchive::getEntry — Get entry object from the RAR archive
- RarArchive::isBroken — Test whether an archive is broken (incomplete)
- RarArchive::isSolid — Check whether the RAR archive is solid
- RarArchive::open — Open RAR archive
- RarArchive::setAllowBroken — Whether opening broken archives is allowed
- RarArchive::__toString — Get text representation
The RarEntry class
(No version information available, might only be in SVN)
Introdução
A RAR entry, representing a directory or a compressed file inside a RAR archive.
Sinopse da classe
Constantes pré-definidas
- RarEntry::HOST_MSDOS
-
If the return value of RarEntry::getHostOs() equals this constant, MS-DOS was used to add this entry. Use instead of RAR_HOST_MSDOS.
- RarEntry::HOST_OS2
-
If the return value of RarEntry::getHostOs() equals this constant, OS/2 was used to add this entry. Intended to replace RAR_HOST_OS2.
- RarEntry::HOST_WIN32
-
If the return value of RarEntry::getHostOs() equals this constant, Microsoft Windows was used to add this entry. Intended to replace RAR_HOST_WIN32.
- RarEntry::HOST_UNIX
-
If the return value of RarEntry::getHostOs() equals this constant, an unspecified UNIX OS was used to add this entry. Intended to replace RAR_HOST_UNIX.
- RarEntry::HOST_MACOS
-
If the return value of RarEntry::getHostOs() equals this constant, Mac OS was used to add this entry.
- RarEntry::HOST_BEOS
-
If the return value of RarEntry::getHostOs() equals this constant, BeOS was used to add this entry. Intended to replace RAR_HOST_BEOS.
- RarEntry::ATTRIBUTE_WIN_READONLY
-
Bit that represents a Windows entry with a read-only attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
-
Bit that represents a Windows entry with a hidden attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
- RarEntry::ATTRIBUTE_WIN_SYSTEM
-
Bit that represents a Windows entry with a system attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
- RarEntry::ATTRIBUTE_WIN_DIRECTORY
-
Bit that represents a Windows entry with a directory attribute (entry is a directory). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows. See also RarEntry::isDirectory(), which also works with entries that were not added in WinRAR.
- RarEntry::ATTRIBUTE_WIN_ARCHIVE
-
Bit that represents a Windows entry with an archive attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
- RarEntry::ATTRIBUTE_WIN_DEVICE
-
Bit that represents a Windows entry with a device attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
- RarEntry::ATTRIBUTE_WIN_NORMAL
-
Bit that represents a Windows entry with a normal file attribute (entry is NOT a directory). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows. See also RarEntry::isDirectory(), which also works with entries that were not added in WinRAR.
- RarEntry::ATTRIBUTE_WIN_TEMPORARY
-
Bit that represents a Windows entry with a temporary attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
- RarEntry::ATTRIBUTE_WIN_SPARSE_FILE
-
Bit that represents a Windows entry with a sparse file attribute (file is an NTFS sparse file). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
- RarEntry::ATTRIBUTE_WIN_REPARSE_POINT
-
Bit that represents a Windows entry with a reparse point attribute (entry is an NTFS reparse point, e.g. a directory junction or a mount file system). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
- RarEntry::ATTRIBUTE_WIN_COMPRESSED
-
Bit that represents a Windows entry with a compressed attribute (NTFS only). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
- RarEntry::ATTRIBUTE_WIN_OFFLINE
-
Bit that represents a Windows entry with an offline attribute (entry is offline and not accessible). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
- RarEntry::ATTRIBUTE_WIN_NOT_CONTENT_INDEXED
-
Bit that represents a Windows entry with a not content indexed attribute (entry is to be indexed). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
- RarEntry::ATTRIBUTE_WIN_ENCRYPTED
-
Bit that represents a Windows entry with an encrypted attribute (NTFS only). To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
- RarEntry::ATTRIBUTE_WIN_VIRTUAL
-
Bit that represents a Windows entry with a virtual attribute. To be used with RarEntry::getAttr() on entries whose host OS is Microsoft Windows.
- RarEntry::ATTRIBUTE_UNIX_WORLD_EXECUTE
-
Bit that represents a UNIX entry that is world executable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
- RarEntry::ATTRIBUTE_UNIX_WORLD_WRITE
-
Bit that represents a UNIX entry that is world writable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
- RarEntry::ATTRIBUTE_UNIX_WORLD_READ
-
Bit that represents a UNIX entry that is world readable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
- RarEntry::ATTRIBUTE_UNIX_GROUP_EXECUTE
-
Bit that represents a UNIX entry that is group executable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
- RarEntry::ATTRIBUTE_UNIX_GROUP_WRITE
-
Bit that represents a UNIX entry that is group writable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
- RarEntry::ATTRIBUTE_UNIX_GROUP_READ
-
Bit that represents a UNIX entry that is group readable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
- RarEntry::ATTRIBUTE_UNIX_OWNER_EXECUTE
-
Bit that represents a UNIX entry that is owner executable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
- RarEntry::ATTRIBUTE_UNIX_OWNER_WRITE
-
Bit that represents a UNIX entry that is owner writable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
- RarEntry::ATTRIBUTE_UNIX_OWNER_READ
-
Bit that represents a UNIX entry that is owner readable. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
- RarEntry::ATTRIBUTE_UNIX_STICKY
-
Bit that represents the UNIX sticky bit. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
- RarEntry::ATTRIBUTE_UNIX_SETGID
-
Bit that represents the UNIX setgid attribute. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
- RarEntry::ATTRIBUTE_UNIX_SETUID
-
Bit that represents the UNIX setuid attribute. To be used with RarEntry::getAttr() on entries whose host OS is UNIX.
- RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET
-
Mask to isolate the last four bits (nibble) of UNIX attributes (_S_IFMT, the type of file mask). To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constants RarEntry::ATTRIBUTE_UNIX_FIFO, RarEntry::ATTRIBUTE_UNIX_CHAR_DEV, RarEntry::ATTRIBUTE_UNIX_DIRECTORY, RarEntry::ATTRIBUTE_UNIX_BLOCK_DEV, RarEntry::ATTRIBUTE_UNIX_REGULAR_FILE, RarEntry::ATTRIBUTE_UNIX_SYM_LINK and RarEntry::ATTRIBUTE_UNIX_SOCKET.
- RarEntry::ATTRIBUTE_UNIX_FIFO
-
Unix FIFOs will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.
- RarEntry::ATTRIBUTE_UNIX_CHAR_DEV
-
Unix character devices will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.
- RarEntry::ATTRIBUTE_UNIX_DIRECTORY
-
Unix directories will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET. See also RarEntry::isDirectory(), which also works with entries that were added in other operating systems.
- RarEntry::ATTRIBUTE_UNIX_BLOCK_DEV
-
Unix block devices will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.
- RarEntry::ATTRIBUTE_UNIX_REGULAR_FILE
-
Unix regular files (not directories) will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET. See also RarEntry::isDirectory(), which also works with entries that were added in other operating systems.
- RarEntry::ATTRIBUTE_UNIX_SYM_LINK
-
Unix symbolic links will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.
- RarEntry::ATTRIBUTE_UNIX_SOCKET
-
Unix sockets will have attributes whose last four bits have this value. To be used with RarEntry::getAttr() on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.
RarEntry::extract
(PECL rar >= 0.1)
RarEntry::extract — Extract entry from the archive
Descrição
RarEntry::extract() extracts the entry's data. It will create new file in the specified dir with the name identical to the entry's name, unless the second argument is specified. See below for more information.
Parâmetros
- dir
-
Path to the directory where files should be extracted. This parameter is considered if and only if filepath is not. If both parameters are empty an extraction to the current directory will be attempted.
- filepath
-
Path (relative or absolute) containing the directory and filename of the extracted file. This parameter overrides both the parameter dir and the original file name.
- password
-
The password used to encrypt this entry. If the entry is not encrypted, this value will not be used and can be omitted. If this parameter is omitted and the entry is encrypted, the password given to rar_open(), if any, will be used. If a wrong password is given, either explicitly or implicitly via rar_open(), CRC checking will fail and this method will fail and return FALSE. If no password is given and one is required, this method will fail and return FALSE. You can check whether an entry is encrypted with RarEntry::isEncrypted().
- extended_data
-
If TRUE, extended information such as NTFS ACLs and Unix owner information will be set in the extract files, as long as it's present in the archive.
Prior to version 2.0.0, this function would not handle relative paths correctly. Use realpath() as a workaround.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Histórico
| Versão | Descrição |
|---|---|
| 3.0.0 | extended_data was added. |
| 3.0.0 | Support for RAR archives with repeated entry names is no longer defective. |
Exemplos
Exemplo #1 RarEntry::extract() example
<?php
$rar_file = rar_open('example.rar') or die("Failed to open Rar archive");
$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");
$entry->extract('/dir/to'); // create /dir/to/Dir/file.txt
$entry->extract(false, '/dir/to/new_name.txt'); // create /dir/to/new_name.txt
?>
Exemplo #2 How to extract all files in archive:
<?php
/* example by Erik Jenssen aka erix */
$filename = "foobar.rar";
$filepath = "/home/foo/bar/";
$rar_file = rar_open($filepath.$filename);
$list = rar_list($rar_file);
foreach($list as $file) {
$entry = rar_entry_get($rar_file, $file);
$entry->extract("."); // extract to the current dir
}
rar_close($rar_file);
?>
RarEntry::getAttr
(PECL rar >= 0.1)
RarEntry::getAttr — Get attributes of the entry
Descrição
Returns the OS-dependent attributes of the archive entry.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Returns the attributes or FALSE on error.
Exemplos
Exemplo #1 RarEntry::getAttr() example
<?php
$rar_file = rar_open('example.rar') or die("Can't open Rar archive");
$entry = rar_entry_get($rar_file, 'dir/in/the/archive') or die("Can't find such entry");
$host_os = $entry->getHostOs();
$attr = $entry->getAttr();
switch($host_os) {
case RAR_HOST_MSDOS:
case RAR_HOST_OS2:
case RAR_HOST_WIN32:
case RAR_HOST_MACOS:
printf("%c%c%c%c%c%c\n",
($attr & 0x08) ? 'V' : '.',
($attr & 0x10) ? 'D' : '.',
($attr & 0x01) ? 'R' : '.',
($attr & 0x02) ? 'H' : '.',
($attr & 0x04) ? 'S' : '.',
($attr & 0x20) ? 'A' : '.');
break;
case RAR_HOST_UNIX:
case RAR_HOST_BEOS:
switch ($attr & 0xF000)
{
case 0x4000:
printf("d");
break;
case 0xA000:
printf("l");
break;
default:
printf("-");
break;
}
printf("%c%c%c%c%c%c%c%c%c\n",
($attr & 0x0100) ? 'r' : '-',
($attr & 0x0080) ? 'w' : '-',
($attr & 0x0040) ? (($attr & 0x0800) ? 's':'x'):(($attr & 0x0800) ? 'S':'-'),
($attr & 0x0020) ? 'r' : '-',
($attr & 0x0010) ? 'w' : '-',
($attr & 0x0008) ? (($attr & 0x0400) ? 's':'x'):(($attr & 0x0400) ? 'S':'-'),
($attr & 0x0004) ? 'r' : '-',
($attr & 0x0002) ? 'w' : '-',
($attr & 0x0001) ? 'x' : '-');
break;
}
rar_close($rar_file);
?>
RarEntry::getCrc
(PECL rar >= 0.1)
RarEntry::getCrc — Get CRC of the entry
Descrição
Returns an hexadecimal string representation of the CRC of the archive entry.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Returns the CRC of the archive entry or FALSE on error.
Histórico
| Versão | Descrição |
|---|---|
| 2.0.0 | This method now returns correct values for multiple volume archives. |
RarEntry::getFileTime
(PECL rar >= 0.1)
RarEntry::getFileTime — Get entry last modification time
Descrição
Gets entry last modification time.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Returns entry last modification time as string in format YYYY-MM-DD HH:II:SS, or FALSE on error.
RarEntry::getHostOs
(PECL rar >= 0.1)
RarEntry::getHostOs — Get entry host OS
Descrição
Returns the code of the host OS of the archive entry.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Returns the code of the host OS, or FALSE on error.
Exemplos
Exemplo #1 RarEntry::getHostOs() example (version >= 2.0.0)
<?php
$rar_file = rar_open('example.rar') or die("Failed to open Rar archive");
$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");
switch ($entry->getHostOs()) {
case RarEntry::HOST_MSDOS:
echo "MS-DOS\n";
break;
case RarEntry::HOST_OS2:
echo "OS2\n";
break;
case RarEntry::HOST_WIN32:
echo "Win32\n";
break;
case RarEntry::HOST_MACOS:
echo "MacOS\n";
break;
case RarEntry::HOST_UNIX:
echo "Unix/Linux\n";
break;
case RarEntry::HOST_BEOS:
echo "BeOS\n";
break;
}
?>
Exemplo #2 RarEntry::getHostOs() example (version <= 1.0.0)
<?php
$rar_file = rar_open('example.rar') or die("Failed to open Rar archive");
$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");
switch ($entry->getHostOs()) {
case RAR_HOST_MSDOS:
echo "MS-DOS\n";
break;
case RAR_HOST_OS2:
echo "OS2\n";
break;
case RAR_HOST_WIN32:
echo "Win32\n";
break;
case RAR_HOST_MACOS:
echo "MacOS\n";
break;
case RAR_HOST_UNIX:
echo "Unix/Linux\n";
break;
case RAR_HOST_BEOS:
echo "BeOS\n";
break;
}
?>
RarEntry::getMethod
(PECL rar >= 0.1)
RarEntry::getMethod — Get pack method of the entry
Descrição
RarEntry::getMethod() returns number of the method used when adding current archive entry.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Returns the method number or FALSE on error.
Exemplos
Exemplo #1 RarEntry::getMethod() example
<?php
$rar_file = rar_open('example.rar') or die("Failed to open Rar archive");
$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");
echo "Method number: " . $entry->getMethod();
?>
RarEntry::getName
(PECL rar >= 0.1)
RarEntry::getName — Get name of the entry
Descrição
Returns the name (with path) of the archive entry.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Returns the entry name as a string, or FALSE on error.
Histórico
| Versão | Descrição |
|---|---|
| 2.0.0 | As of version 2.0.0, the returned string is encoded in Unicode/UTF-8. |
Exemplos
Exemplo #1 RarEntry::getName() example
<?php
//this example is safe even in pages not encoded in UTF-8
//for those encoded in UTF-8, the call to mb_convert_encoding is unnecessary
$rar_file = rar_open('example.rar') or die("Failed to open Rar archive");
$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");
echo "Entry name: " . mb_convert_encoding(
htmlentities(
$entry->getName(),
ENT_COMPAT,
"UTF-8"
),
"HTML-ENTITIES",
"UTF-8"
);
?>
RarEntry::getPackedSize
(PECL rar >= 0.1)
RarEntry::getPackedSize — Get packed size of the entry
Descrição
Get packed size of the archive entry.
Nota:
Note that on platforms with 32-bit longs (that includes Windows x64), the maximum size returned is capped at 2 GiB. Check the constant PHP_INT_MAX.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Returns the packed size, or FALSE on error.
Histórico
| Versão | Descrição |
|---|---|
| 2.0.0 | This method now returns correct values of packed sizes bigger than 2 GiB on platforms with 64-bit integers and never returns negative values on other platforms. |
Exemplos
Exemplo #1 RarEntry::getPackedSize() example
<?php
$rar_file = rar_open('example.rar') or die("Failed to open Rar archive");
$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");
echo "Packed size of " . $entry->getName() . " = " . $entry->getPackedSize() . " bytes";
?>
RarEntry::getStream
(PECL rar >= 2.0.0)
RarEntry::getStream — Get file handler for entry
Descrição
Returns a file handler that supports read operations. This handler provides on-the-fly decompression for this entry.
The handler is not invalidated by calling rar_close().
The resulting stream has no integrity verification. In particular, file corruption and decryption with a wrong a key will not be detected. It is the programmer's responsability to use the entry's CRC to check for integrity, if he so wishes.
Parâmetros
- password
-
The password used to encrypt this entry. If the entry is not encrypted, this value will not be used and can be omitted. If this parameter is omitted and the entry is encrypted, the password given to rar_open(), if any, will be used. If a wrong password is given, either explicitly or implicitly via rar_open(), this method's resulting stream will produce wrong output. If no password is given and one is required, this method will fail and return FALSE. You can check whether an entry is encrypted with RarEntry::isEncrypted().
Valor Retornado
The file handler or FALSE on failure.
Histórico
| Versão | Descrição |
|---|---|
| 3.0.0 | Support for RAR archives with repeated entry names is no longer defective. |
Exemplos
Exemplo #1 RarEntry::getStream() example
<?php
$rar_file = rar_open('example.rar');
if ($rar_file === false)
die("Failed to open Rar archive");
$entry = rar_entry_get($rar_file, 'Dir/file.txt');
if ($entry === false)
die("Failed to find such entry");
$stream = $entry->getStream();
if ($stream === false)
die("Failed to obtain stream.");
rar_close($rar_file); //stream is independent from file
while (!feof($stream)) {
$buff = fread($stream, 8192);
if ($buff !== false)
echo $buff;
else
break; //fread error
}
fclose($stream);
?>
RarEntry::getUnpackedSize
(PECL rar >= 0.1)
RarEntry::getUnpackedSize — Get unpacked size of the entry
Descrição
Get unpacked size of the archive entry.
Nota:
Note that on platforms with 32-bit longs (that includes Windows x64), the maximum size returned is capped at 2 GiB. Check the constant PHP_INT_MAX.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Returns the unpacked size, or FALSE on error.
Histórico
| Versão | Descrição |
|---|---|
| 2.0.0 | This method now returns correct values of unpacked sizes bigger than 2 GiB on platforms with 64-bit integers and never returns negative values on other platforms. |
Valor Retornado
Exemplo #1 RarEntry::getUnpackedSize() example
<?php
$rar_file = rar_open('example.rar') or die("Failed to open Rar archive");
$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");
echo "Unpacked size of " . $entry->getName() . " = " . $entry->getPackedSize() . " bytes";
?>
RarEntry::getVersion
(PECL rar >= 0.1)
RarEntry::getVersion — Get minimum version of RAR program required to unpack the entry
Descrição
Returns minimum version of RAR program (e.g. WinRAR) required to unpack the entry. It is encoded as 10 * major version + minor version.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Returns the version or FALSE on error.
Exemplos
Exemplo #1 RarEntry::getVersion() example
<?php
$rar_file = rar_open('example.rar') or die("Failed to open Rar archive");
$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");
echo "Rar version required for unpacking: " . $entry->getVersion();
?>
RarEntry::isDirectory
(PECL rar >= 2.0.0)
RarEntry::isDirectory — Test whether an entry represents a directory
Descrição
Tests whether the current entry is a directory.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Returns TRUE if this entry is a directory and FALSE otherwise.
Notas
This function is only available starting with version 2.0.0, but one can also test whether an entry is a directory by checking the entry attributes, like this (only works for files compressed in RAR for Windows or Unix):
<?php
//...
//Open file, get entry and store in variable $e...
//...
$isDirectory = (bool) ((($e->getHostOs() == RAR_HOST_WIN32) && ($e->getAttr() & 0x10)) ||
(($e->getHostOs() == RAR_HOST_UNIX) && (($e->getAttr() & 0xf000) == 0x4000)));
?>
RarEntry::isEncrypted
(PECL rar >= 2.0.0)
RarEntry::isEncrypted — Test whether an entry is encrypted
Descrição
Tests whether the current entry contents are encrypted.
Nota:
The password used may differ between files inside the same RAR archive.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Returns TRUE if the current entry is encrypted and FALSE otherwise.
RarEntry::__toString
(PECL rar >= 2.0.0)
RarEntry::__toString — Get text representation of entry
Descrição
RarEntry::__toString() returns a textual representation for this entry. It includes whether the entry is a file or a directory (symbolic links and other special objects will be treated as files), the UTF-8 name of the entry and its CRC. The form and content of this representation may be changed in the future, so they cannot be relied upon.
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
A textual representation for the entry.
Índice
- RarEntry::extract — Extract entry from the archive
- RarEntry::getAttr — Get attributes of the entry
- RarEntry::getCrc — Get CRC of the entry
- RarEntry::getFileTime — Get entry last modification time
- RarEntry::getHostOs — Get entry host OS
- RarEntry::getMethod — Get pack method of the entry
- RarEntry::getName — Get name of the entry
- RarEntry::getPackedSize — Get packed size of the entry
- RarEntry::getStream — Get file handler for entry
- RarEntry::getUnpackedSize — Get unpacked size of the entry
- RarEntry::getVersion — Get minimum version of RAR program required to unpack the entry
- RarEntry::isDirectory — Test whether an entry represents a directory
- RarEntry::isEncrypted — Test whether an entry is encrypted
- RarEntry::__toString — Get text representation of entry
The RarException class
(No version information available, might only be in SVN)
Introdução
This class serves two purposes: it is the type of the exceptions thrown by the RAR extension functions and methods and it allows, through static methods to query and define the error behaviour of the extension, i.e., whether exceptions are thrown or only warnings are emitted.
The following error codes are used:
- -1 - error outside UnRAR library
- 11 - insufficient memory
- 12 - bad data
- 13 - bad archive
- 14 - unknown format
- 15 - file open error
- 16 - file create error
- 17 - file close error
- 18 - read error
- 19 - write error
- 20 - buffer too small
- 21 - unkown RAR error
- 22 - password required but not given
Sinopse da classe
RarException::isUsingExceptions
(PECL rar >= 2.0.0)
RarException::isUsingExceptions — Check whether error handling with exceptions is in use
Descrição
Checks whether the RAR functions will emit warnings and return error values or whether they will throw exceptions in most of the circumstances (does not include some programmatic errors such as passing the wrong type of arguments).
Parâmetros
Esta função não contém parâmetros.
Valor Retornado
Returns TRUE if exceptions are being used, FALSE otherwise.
Exemplos
Exemplo #1 RarException::isUsingExceptions() example
<?php
//The default is not to use exceptions
var_dump(RarException::isUsingExceptions());
?>
O exemplo acima irá imprimir algo similar a:
bool(false)
Veja Também
- RarException::setUsingExceptions() - Activate and deactivate error handling with exceptions
RarException::setUsingExceptions
(PECL rar >= 2.0.0)
RarException::setUsingExceptions — Activate and deactivate error handling with exceptions
Descrição
If and only if the argument is TRUE, then, instead of emitting warnings and returning a special value indicating error when the UnRAR library encounters an error, an exception of type RarException will be thrown.
Exceptions will also be thrown for the following errors, which occur outside the library (their error code will be -1):
- attempting some operations on a closed RarArchive object or a RarEntry object relative to the first;
- attempting to get an entry that does not exist with RarArchive::getEntry().
Parâmetros
- using_exceptions
-
Should be TRUE to activate exception throwing, FALSE to deactivate (the default).
Exemplos
Exemplo #1 RarException::setUsingExceptions() example
<?php
var_dump(RarException::isUsingExceptions());
$arch = RarArchive::open("does_not_exist.rar");
var_dump($arch);
RarException::setUsingExceptions(true);
var_dump(RarException::isUsingExceptions());
$arch = RarArchive::open("does_not_exist.rar");
var_dump($arch); //not reached
?>
O exemplo acima irá imprimir algo similar a:
bool(false)
Warning: RarArchive::open(): Failed to open does_not_exist.rar: ERAR_EOPEN (file open error) in C:\php_rar\trunk\tests\test.php on line 3
bool(false)
bool(true)
Fatal error: Uncaught exception 'RarException' with message 'unRAR internal error: Failed to open does_not_exist.rar: ERAR_EOPEN (file open error)' in C:\php_rar\trunk\tests\test.php:8
Stack trace:
#0 C:\php_rar\trunk\tests\test.php(8): RarArchive::open('does_not_exist....')
#1 {main}
thrown in C:\php_rar\trunk\tests\test.php on line 8
Veja Também
- RarException::isUsingExceptions() - Check whether error handling with exceptions is in use
Índice
- RarException::isUsingExceptions — Check whether error handling with exceptions is in use
- RarException::setUsingExceptions — Activate and deactivate error handling with exceptions
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Exemplos
- Rar Funções
- rar_wrapper_cache_stats — Cache hits and misses for the URL wrapper
- RarArchive — The RarArchive class
- RarArchive::close — Close RAR archive and free all resources
- RarArchive::getComment — Get comment text from the RAR archive
- RarArchive::getEntries — Get full list of entries from the RAR archive
- RarArchive::getEntry — Get entry object from the RAR archive
- RarArchive::isBroken — Test whether an archive is broken (incomplete)
- RarArchive::isSolid — Check whether the RAR archive is solid
- RarArchive::open — Open RAR archive
- RarArchive::setAllowBroken — Whether opening broken archives is allowed
- RarArchive::__toString — Get text representation
- RarEntry — The RarEntry class
- RarEntry::extract — Extract entry from the archive
- RarEntry::getAttr — Get attributes of the entry
- RarEntry::getCrc — Get CRC of the entry
- RarEntry::getFileTime — Get entry last modification time
- RarEntry::getHostOs — Get entry host OS
- RarEntry::getMethod — Get pack method of the entry
- RarEntry::getName — Get name of the entry
- RarEntry::getPackedSize — Get packed size of the entry
- RarEntry::getStream — Get file handler for entry
- RarEntry::getUnpackedSize — Get unpacked size of the entry
- RarEntry::getVersion — Get minimum version of RAR program required to unpack the entry
- RarEntry::isDirectory — Test whether an entry represents a directory
- RarEntry::isEncrypted — Test whether an entry is encrypted
- RarEntry::__toString — Get text representation of entry
- RarException — The RarException class
- RarException::isUsingExceptions — Check whether error handling with exceptions is in use
- RarException::setUsingExceptions — Activate and deactivate error handling with exceptions
Zip
Introdução
Esta extenção habilita você a transparentemente ler ou escrever arquivos compactados ZIP e os arquivos do mesmo.
Instalação/Configuração
Índice
Dependências
PHP 4
A versão embutida do PHP 4 requer » ZZIPlib, criada por Guido Draheim, versão 0.10.6 ou superior
PHP 5.2.0 ou superior
Esta extenção usa funções da » zlib criada por Jean-loup Gailly e Mark Adler.
Instalação
PHP 4
Nota:
O suporte a Zip antes do PHP 4.1.0 é experimental.
Por causa da extensão zip no PHP 4 zip não ser mantida nós recomendamos que a extensão PECL seja usada.
Sistemas Linux
Para usar estas funções você precisa compilar o PHP com suporte a zip usando a opção de configuração --with-zip[=DIR] , onde [DIR] é o prefixo da biblioteca instalada » ZZIPlib.
Windows
Usuários Windows precisam habilitar php_zip.dll no php.ini para usar estas funções.
PHP 5.2.0 e superior
Sistemas Linux
Para usar estas funções você precisa compilar o PHP com suporte a zip usando a opção de configuração --enable-zip .
Windows
Usuários Windows precisam habilitar php_zip.dll no php.ini para usar estas funções.
Instalação via PECL
Informações para a instalação desta extensão PECL podem ser encontradas no manual no capitulo intitulado Instalação de extensões PECL. Informações adicionais como novas versões, downloads, arquivos fontes, manutenções, e um Changelog, podem ser obtidos aqui: » http://pecl.php.net/package/zip.
Uma DLL para esta extenção PECL esta atualmente indisponível. Veja também a seção compilando no Windows section.
No PHP esta DLL reside no diretório extensions/ junto aos binários do PHP para Windows.
Configurações em Execução
Esta extensão não define nenhum parâmetro de configuração no php.ini.
Tipos Resource
Há dois tipos de tipos resource usada neste módulo. O primeiro é um Zip directory para arquivo Zip, o segundo Zip Entry para entradas de arquivos.
Constantes pré-definidas
As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.
ZipArchive usa constantes de classes. Há três tipos de constantes, Flags (FL_), erros (ER_) ou modo (sem prefixo).
- ZIPARCHIVE::CREATE (integer)
- Cria o arquivo se ele não existir.
- ZIPARCHIVE::OVERWRITE (integer)
- Sempre inicia um novo arquivo, este modo sobreescreverá o arquivo se ele já existir.
- ZIPARCHIVE::EXCL (integer)
- Emite erro se o arquivo já existir.
- ZIPARCHIVE::CHECKCONS (integer)
- Executa uma adicional verificação de consistência no arquivo, e emite erro se ele falhar.
- ZIPARCHIVE::FL_NOCASE (integer)
- Ignora maiúsculo e minúsculo no nome.
- ZIPARCHIVE::FL_NODIR (integer)
- Ignora componentes de diretório.
- ZIPARCHIVE::FL_COMPRESSED (integer)
- Lê a informação comprimida.
- ZIPARCHIVE::FL_UNCHANGED (integer)
- Usa os dados originais, ignorando mudanças.
- ZIPARCHIVE::CM_DEFAULT (integer)
- Melhor para descompactar ou armazenar.
- ZIPARCHIVE::CM_STORE (integer)
- Armazenado (não compresso).
- ZIPARCHIVE::CM_SHRINK (integer)
- shrunk
- ZIPARCHIVE::CM_REDUCE_1 (integer)
- compressão com fator 1
- ZIPARCHIVE::CM_REDUCE_2 (integer)
- compressão com fator 2
- ZIPARCHIVE::CM_REDUCE_3 (integer)
- compressão com fator 3
- ZIPARCHIVE::CM_REDUCE_4 (integer)
- compressão com fator 4
- ZIPARCHIVE::CM_IMPLODE (integer)
- implodido
- ZIPARCHIVE::CM_DEFLATE (integer)
- descompactado
- ZIPARCHIVE::CM_DEFLATE64 (integer)
- deflate64
- ZIPARCHIVE::CM_PKWARE_IMPLODE (integer)
- Compactação PKWARE
- ZIPARCHIVE::CM_BZIP2 (integer)
- Algoritmo BZIP2
- ZIPARCHIVE::ER_OK (integer)
- Sem erro.
- ZIPARCHIVE::ER_MULTIDISK (integer)
- Arquivos Multi-disk zip não suportados.
- ZIPARCHIVE::ER_RENAME (integer)
- Renomeia arquivo temporário falhado.
- ZIPARCHIVE::ER_CLOSE (integer)
- Fecha arquivo zip falhado
- ZIPARCHIVE::ER_SEEK (integer)
- Procura o erro
- ZIPARCHIVE::ER_READ (integer)
- Lê o erro
- ZIPARCHIVE::ER_WRITE (integer)
- Escreve o erro
- ZIPARCHIVE::ER_CRC (integer)
- CRC error
- ZIPARCHIVE::ER_ZIPCLOSED (integer)
- Containing zip archive was closed
- ZIPARCHIVE::ER_NOENT (integer)
- Arquivo não encontrado.
- ZIPARCHIVE::ER_EXISTS (integer)
- Arquivo já existente.
- ZIPARCHIVE::ER_OPEN (integer)
- Não foi possível abrir o arquivo.
- ZIPARCHIVE::ER_TMPOPEN (integer)
- Falha ao criar arquivo temporário.
- ZIPARCHIVE::ER_ZLIB (integer)
- Erro da Zlib
- ZIPARCHIVE::ER_MEMORY (integer)
- Falha na alocação de memória.
- ZIPARCHIVE::ER_CHANGED (string)
- Entrada foi modificada.
- ZIPARCHIVE::ER_COMPNOTSUPP (integer)
- Método de compressão não suportado.
- ZIPARCHIVE::ER_EOF (integer)
- Prematuro EOF
- ZIPARCHIVE::ER_INVAL (integer)
- Argumento inválido.
- ZIPARCHIVE::ER_NOZIP (integer)
- Não é um arquivo zip.
- ZIPARCHIVE::ER_INTERNAL (integer)
- Erro interno.
- ZIPARCHIVE::ER_INCONS (integer)
- Arquivo Zip inconsistente.
- ZIPARCHIVE::ER_REMOVE (integer)
- Não foi possível remove o arquivo.
- ZIPARCHIVE::ER_DELETED (integer)
- Entrada foi deletada.
Exemplos
Exemplo #1 Criando um arquivo Zip
<?php
$zip = new ZipArchive();
$filename = "./test112.zip";
if ($zip->open($filename, ZIPARCHIVE::CREATE)!==TRUE) {
exit("cannot open <$filename>\n");
}
$zip->addFromString("testfilephp.txt" . time(), "#1 This is a test string added as testfilephp.txt.\n");
$zip->addFromString("testfilephp2.txt" . time(), "#2 This is a test string added as testfilephp2.txt.\n");
$zip->addFile($thisdir . "/too.php","/testfromfile.php");
echo "numfiles: " . $zip->numFiles . "\n";
echo "status:" . $zip->status . "\n";
$zip->close();
?>
Exemplo #2 Exibindo detalhes dos arquivos e listando-os
<?php
$za = new ZipArchive();
$za->open('test_with_comment.zip');
print_r($za);
var_dump($za);
echo "numFiles: " . $za->numFiles . "\n";
echo "status: " . $za->status . "\n";
echo "statusSys: " . $za->statusSys . "\n";
echo "filename: " . $za->filename . "\n";
echo "comment: " . $za->comment . "\n";
for ($i=0; $i<$za->numFiles;$i++) {
echo "index: $i\n";
print_r($za->statIndex($i));
}
echo "numFile:" . $za->numFiles . "\n";
?>
Exemplo #3 Zip stream wrapper, lendo um OpenOffice meta info
<?php
$reader = new XMLReader();
$reader->open('zip://' . dirname(__FILE__) . '/test.odt#meta.xml');
$odt_meta = array();
while ($reader->read()) {
if ($reader->nodeType == XMLREADER::ELEMENT) {
$elm = $reader->name;
} else {
if ($reader->nodeType == XMLREADER::END_ELEMENT && $reader->name == 'office:meta') {
break;
}
if (!trim($reader->value)) {
continue;
}
$odt_meta[$elm] = $reader->value;
}
}
print_r($odt_meta);
?>
Este exemplo usa a velha API (PHP 4), ela abre um arquivo ZIP, ler cada arquivo do arquivo e imprime o conteúdo deles. O arquivo test2.zip usado neste exemplo é um arquivo de teste do fonte da distruição ZZIPlib.
Exemplo #4 Exemplo de uso
<?php
$zip = zip_open("/tmp/test2.zip");
if ($zip) {
while ($zip_entry = zip_read($zip)) {
echo "Name: " . zip_entry_name($zip_entry) . "\n";
echo "Actual Filesize: " . zip_entry_filesize($zip_entry) . "\n";
echo "Compressed Size: " . zip_entry_compressedsize($zip_entry) . "\n";
echo "Compression Method: " . zip_entry_compressionmethod($zip_entry) . "\n";
if (zip_entry_open($zip, $zip_entry, "r")) {
echo "File Contents:\n";
$buf = zip_entry_read($zip_entry, zip_entry_filesize($zip_entry));
echo "$buf\n";
zip_entry_close($zip_entry);
}
echo "\n";
}
zip_close($zip);
}
?>
Funções para Zip
zip_close
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PECL zip >= 1.0.0)
zip_close — Fecha um arquivo ZIP
Descrição
Fecha um dado arquivo ZIP.
Valor Retornado
Não há valor retornado.
Veja Também
- zip_open() - Abre um arquivo ZIPado
- zip_read() - Lê a próxima entrada em um arquivo ZIPado
zip_entry_close
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PECL zip >= 1.0.0)
zip_entry_close — Fecha o arquivo que está aberto
Descrição
Fecha uma especificada lista de entrada.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Veja Também
- zip_entry_open() - Abre um arquivo do arquivo ZIP
- zip_entry_read() - Lê de um arquivo aberto
zip_entry_compressedsize
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PECL zip >= 1.0.0)
zip_entry_compressedsize — Recupera o tamanho compactado do arquivo que está dentro do arquivo ZIP
Descrição
Retorna o tamanho do arquivo compactado dentro do arquivo ZIP especificado.
Valor Retornado
O tamanho da compressão.
Veja Também
- zip_open() - Abre um arquivo ZIPado
- zip_read() - Lê a próxima entrada em um arquivo ZIPado
zip_entry_compressionmethod
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PECL zip >= 1.0.0)
zip_entry_compressionmethod — Recupera qual o método de compressão foi utilizado no arquivo
Descrição
Recupera qual o método de compressão foi utilizado no arquivo passado por zip_entry.
Valor Retornado
O método de compressão.
Veja Também
- zip_open() - Abre um arquivo ZIPado
- zip_read() - Lê a próxima entrada em um arquivo ZIPado
zip_entry_filesize
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PECL zip >= 1.0.0)
zip_entry_filesize — Retorna o tamanho de um diretório de entrada
Descrição
Retorna o tamanho atual do especificado diretório de entrada.
Valor Retornado
O tamanho do diretório de entrada.
Veja Também
- zip_open() - Abre um arquivo ZIPado
- zip_read() - Lê a próxima entrada em um arquivo ZIPado
zip_entry_name
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PECL zip >= 1.0.0)
zip_entry_name — Retorna o nome do arquivo
Descrição
Retorna o nome do arquivo especificado.
Valor Retornado
O nome do diretório de entrada.
Veja Também
- zip_open() - Abre um arquivo ZIPado
- zip_read() - Lê a próxima entrada em um arquivo ZIPado
zip_entry_open
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PECL zip >= 1.0.0)
zip_entry_open — Abre um arquivo do arquivo ZIP
Descrição
Abre um arquivo para ser manipulado.
Parâmetros
- zip
-
Um válido manipulador de resource retornado por zip_open().
- zip_entry
-
Uma entrada de diretório retornada por zip_read().
- mode
-
Algum dos modos especificados na documentação da fopen().
Nota:
Atualmente, o modo é ignorado e o modo padrão suportado é "rb". Isto é devido ao fato que o suporte a zip no PHP é apenas de leitura.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Nota:
Infelizmente fopen() e outras funções similares, retornam o mesmo valor de zip_entry_open() , apenas indicam o resultado da operação efetuada e não são necessárias para abrir ou fechar um arquivo do arquivo ZIP.
Veja Também
- zip_entry_close() - Fecha o arquivo que está aberto
- zip_entry_read() - Lê de um arquivo aberto
zip_entry_read
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PECL zip >= 1.0.0)
zip_entry_read — Lê de um arquivo aberto
Descrição
Lê de um arquivo aberto.
Parâmetros
- zip_entry
-
Um arquivo retornado pela zip_read().
- length
-
O número de bytes para retornar. Se não especificado, esta função irá tentar ler 1024 bytes.
Nota:
Este deve ser o tamanho não comprimido que você deseja ler.
Valor Retornado
Retorna a informação lida, ou FALSE se o fim do arquivo for encontrado.
Veja Também
- zip_entry_open() - Abre um arquivo do arquivo ZIP
- zip_entry_close() - Fecha o arquivo que está aberto
- zip_entry_filesize() - Retorna o tamanho de um diretório de entrada
zip_open
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PECL zip >= 1.0.0)
zip_open — Abre um arquivo ZIPado
Parâmetros
- filename
-
O nome do arquivo ZIP para abrir.
Valor Retornado
Retorna a conexão com o arquivo que será usado com as funções zip_read() e zip_close() ou retorna o número de erros se filename não existir or em outro caso erro.
Veja Também
- zip_read() - Lê a próxima entrada em um arquivo ZIPado
- zip_close() - Fecha um arquivo ZIP
zip_read
(PHP 4 >= 4.1.0, PHP 5 >= 5.2.0, PECL zip >= 1.0.0)
zip_read — Lê a próxima entrada em um arquivo ZIPado
Valor Retornado
Retorna uma conexao com o arquivo ZIP para ser usado com as funções zip_entry_... ou FALSE se não houver arquivos para serem lidos ou número de erros no caso de outro erro.
Veja Também
- zip_open() - Abre um arquivo ZIPado
- zip_close() - Fecha um arquivo ZIP
- zip_entry_open() - Abre um arquivo do arquivo ZIP
- zip_entry_read() - Lê de um arquivo aberto
Índice
- zip_close — Fecha um arquivo ZIP
- zip_entry_close — Fecha o arquivo que está aberto
- zip_entry_compressedsize — Recupera o tamanho compactado do arquivo que está dentro do arquivo ZIP
- zip_entry_compressionmethod — Recupera qual o método de compressão foi utilizado no arquivo
- zip_entry_filesize — Retorna o tamanho de um diretório de entrada
- zip_entry_name — Retorna o nome do arquivo
- zip_entry_open — Abre um arquivo do arquivo ZIP
- zip_entry_read — Lê de um arquivo aberto
- zip_open — Abre um arquivo ZIPado
- zip_read — Lê a próxima entrada em um arquivo ZIPado
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Exemplos
- Funções para Zip
- zip_close — Fecha um arquivo ZIP
- zip_entry_close — Fecha o arquivo que está aberto
- zip_entry_compressedsize — Recupera o tamanho compactado do arquivo que está dentro do arquivo ZIP
- zip_entry_compressionmethod — Recupera qual o método de compressão foi utilizado no arquivo
- zip_entry_filesize — Retorna o tamanho de um diretório de entrada
- zip_entry_name — Retorna o nome do arquivo
- zip_entry_open — Abre um arquivo do arquivo ZIP
- zip_entry_read — Lê de um arquivo aberto
- zip_open — Abre um arquivo ZIPado
- zip_read — Lê a próxima entrada em um arquivo ZIPado
Compressão Zlib
Introdução
Este módulo lhe possibilita ler e gerar transparentemente arquivos comprimidos do tipo gzip (.gz), através de muitas das funções filesystem nas quais funcionam com arquivos gzip comprimidos (e arquivos não comprimidos também, mas não com sockets).
Nota:
A versão 4.0.4 introduziu um fopen-wrapper para arquivos .gz, assim você pode usar uma URL especial zlib: para acessar arquivos comprimidos transparentemente usando as funções f*() normais de acessos a arquivos se você colocar como prefixo no nome ou caminho zlib: ao chamar fopen(). Isto requer que você use uma biblioteca C em tempo de execução que tenha a função fopencookie(). Até agora apenas a GNU libc parace ser a única biblioteca que tenha este recurso.
No PHP 4.3.0, zlib: foi modificado para compress.zlib:// para previnir ambiguidades com nomes de arquivos contendo caracteres ':'. A função fopencookie() não é mais requerida. Maiores informações estão disponíveis em uma sessão sobre zlib://.
Instalação/Configuração
Índice
Dependências
Este módulo usa as funções da » zlib por Jean-loup Gailly e Mark Adler. Você terá que usar uma versão zlib >= à 1.0.9 com este módulo.
Instalação
O suporte a Zlib no PHP não esta ativado por padrão. Você precisa configurar o PHP com --with-zlib[=DIR]
A versão para Windows do PHP tem suporte embutido para esta extensão. Você não precisa carregar nenhuma extensão adicional para utilizar essas funções.
Nota: Suporte embutido para o zlib no Windows esta disponível partir do PHP 4.3.0.
Configurações em Execução
O comportamento dessas funções podem ser modificado pelas configurações do php.ini.
A extensão zlib oferece a opção de comprimir transparentemente suas páginas em tempo real, se o navegador requisitante suportar isto. Então existem três opções no arquivo de configuração php.ini.
| Nome | Padrão | Modificável | Modificação |
|---|---|---|---|
| zlib.output_compression | 0 | PHP_INI_ALL | Disponível desde o PHP 4.0.5. |
| zlib.output_compression_level | "-1" | PHP_INI_ALL | Disponível desde o PHP 4.3.0. |
| zlib.output_handler | "" | PHP_INI_ALL | Disponível desde o PHP 4.3.0. |
Aqui está uma breve explicação das diretrizes de configuração.
- zlib.output_compression booleano/inteiro
-
Serve para comprimir páginas de modo transparente. Se esta opção for mudada para "On" no php.ini ou na configuração do Apache, as páginas serão comprimidas se o navegador enviar um cabeçalho "Accept-Encoding: gzip" ou "deflate". "Content-Encoding: gzip" (respectivamente "deflate") e cabeçalhos "Vary: Accept-Encoding" serão adicionados para a saida. Em tempo de execução, isso só pode ser definido antes de enviar qualquer saída.
Esta opção também aceita valores inteiros em vez de valores booleanos "On"/"Off", usando isto você pode configurar o tamanho do buffer de saída (o padrão é 4KB).
Nota:
output_handler deve estar vazio se a diretriz estiver configurada em 'On'! Em vez disto você deve usar zlib.output_handler.
- zlib.output_compression_level inteiro
-
Nível de compressão usado para as saídas.
- zlib.output_handler string
-
Você não pode especificar tratamentos adicionais de saída se zlib.output_compression for ativado. Esta configuração faz o mesmo que a output_handler mas em uma ordem diferente.
Constantes pré-definidas
As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.
Exemplos
Este exemplo abre um arquivo temporário e gera uma string teste dentro dele, então ela mostra o conteúdo deste arquivo duas vezes.
Exemplo #1 Pequeno Exemplo da Zlib
<?php
$filename = tempnam('/tmp', 'zlibtest') . '.gz';
echo "<html>\n<head></head>\n<body>\n<pre>\n";
$s = "Only a test, test, test, test, test, test, test, test!\n";
// open file for writing with maximum compression
$zp = gzopen($filename, "w9");
// write string to file
gzwrite($zp, $s);
// close file
gzclose($zp);
// open file for reading
$zp = gzopen($filename, "r");
// read 3 char
echo gzread($zp, 3);
// output until end of the file and close it.
gzpassthru($zp);
gzclose($zp);
echo "\n";
// open file and print content (the 2nd time).
if (readgzfile($filename) != strlen($s)) {
echo "Error with zlib functions!";
}
unlink($filename);
echo "</pre>\n</body>\n</html>\n";
?>
Funções da Zlib
gzclose
(PHP 4, PHP 5)
gzclose — Fecha um ponteiro para um arquivo-gz
Descrição
Fecha o ponteiro para arquivo gz dado.
Parâmetros
- zp
-
O ponteiro de arquivo gz. Ele deve ser válido,e apontar para um arquivo aberto de maneira correta pela função gzopen().
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 gzclose() example
<?php
$gz = gzopen('somefile.gz','w9');
gzputs ($gz, 'I was added to somefile.gz');
gzclose($gz);
?>
gzcompress
(PHP 4 >= 4.0.1, PHP 5)
gzcompress — Comprime uma string
Descrição
Esta função comprime a string usando o formato de dados ZLIB.
Para detalhes sobre o algoritimo de compressão ZLIB veja o documento "» ZLIB Compressed Data Format Specification version 3.3" (RFC 1950).
Nota:
Isto não é o mesmo que a compressão gzip, a qual incluir alguns dados de cabeçalho. Veja gzencode() para compressão gzip.
Parâmetros
- data
-
Os dados a comprimir.
- level
-
The level of compression. Can be given as 0 for no compression up to 9 for maximum compression.
Valor Retornado
A string comprimida ou FALSE se um erro ocorreu.
Exemplos
Exemplo #1 Exemplo gzcompress()
<?php
$compressed = gzcompress('Compress me', 9);
echo $compressed;
?>
Veja Também
- gzdeflate() - Comprime uma string usando DEFLATE
- gzinflate() - Descomprime uma string usando DEFLATE
- gzuncompress() - Descomprime uma string com DEFLATED
- gzencode() - Cria uma string comprimida com gzip
gzdecode
(No version information available, might only be in SVN)
gzdecode — Decodifica uma string comprimida usando o gzip
Descrição
Essa função retorna a versão decodifica de data.
Parâmetros
- data
-
Os dados a serem decodificados, encodificados por gzencode().
- length
-
Tamanho máximo dos dados a serem decodificados.
Valor Retornado
A string decodificada, ou FALSE se um erro ocorrer.
gzdeflate
(PHP 4 >= 4.0.4, PHP 5)
gzdeflate — Comprime uma string usando DEFLATE
Descrição
Esta função comprime a string dada usando o formato de dados DEFLATE.
Para detalhes sobre o algoritimo de compressão DEFLATE veja o documento "» DEFLATE Compressed Data Format Specification version 1.3" (RFC 1951).
Parâmetros
- data
-
Os dados a comprimir.
- level
-
O nível de compressão. Pode ser dado como 0 para sem compressão até 9 para a máxima compressão. Se não for dados, o nível de compressão padrão será o nível de compressão padrão da biblioteca zlib.
Valor Retornado
A string comprimida ou FALSE se ocorreu um erro.
Exemplos
Exemplo #1 Exemplo gzdeflate()
<?php
$compressed = gzdeflate('Compress me', 9);
echo $compressed;
?>
Veja Também
- gzinflate() - Descomprime uma string usando DEFLATE
- gzcompress() - Comprime uma string
- gzuncompress() - Descomprime uma string com DEFLATED
- gzencode() - Cria uma string comprimida com gzip
gzencode
(PHP 4 >= 4.0.4, PHP 5)
gzencode — Cria uma string comprimida com gzip
Descrição
Esta função retorna uma versão comprimida dos dados de entrada data compatível com a saída do programa gzip.
Para maiores informações sobre o formato GZIP, veja o documento: » Especificação do formato de arquivo GZIP versão 4.3 (RFC 1952).
Parâmetros
- data
-
Os dados para codificar.
- level
-
O nível de compressão. Pode ser dado como 0 para sem compressão até 9 para a máxima compressão. Se não for dados, o nível de compressão padrão será o nível de compressão padrão da biblioteca zlib.
- encoding_mode
-
O modo de codificação. Pode ser FORCE_GZIP (o padrão) ou FORCE_DEFLATE.
Se você usar FORCE_DEFLATE, você obtém uma string comprimida padrão zlib (incluindo os cabeçalhos zlib) após o cabeçalho do arquivo gzip mas sem a somatória crc32 ao final.
Valor Retornado
A string codificada, ou FALSE se aconteceu um erro.
Histórico
| Versão | Descrição |
|---|---|
| 4.2 | level foi adicionado. gzencode() apenas tinha os parâmetros data e o opcional encoding_mode antes. |
Exemplos
Os dados resultantes contém os cabeçalhos apropriados e a estrutura de dados para fazer um arquivo .gz padrão, ex:
Exemplo #1 Criando um arquivo gzip
<?php
$data = implode("", file("bigfile.txt"));
$gzdata = gzencode($data, 9);
$fp = fopen("bigfile.txt.gz", "w");
fwrite($fp, $gzdata);
fclose($fp);
?>
Veja Também
- gzdecode() - Decodifica uma string comprimida usando o gzip
- gzdeflate() - Comprime uma string usando DEFLATE
- gzinflate() - Descomprime uma string usando DEFLATE
- gzuncompress() - Descomprime uma string com DEFLATED
- gzcompress() - Comprime uma string
gzeof
(PHP 4, PHP 5)
gzeof — Testa para o fim de um ponteiro de arquivo-gz
Descrição
Teste o ponteiro de arquivo GZ para o EOF (fim do arquivo).
Parâmetros
- zp
-
O ponteiro de arquivo gz. Ele deve ser válido, e deve apontar para um arquivo aberto de maneira bem sucedida por gzopen().
Valor Retornado
Retorna TRUE se o ponteiro de arquivo-gz esta no fim do arquivo ou se acontecer um erro, se não retorna FALSE.
Exemplos
Exemplo #1 gzeof() example
<?php
$gz = gzopen('somefile.gz', 'r');
while (!gzeof($gz)) {
echo gzgetc($gz);
}
gzclose($gz);
?>
gzfile
(PHP 4, PHP 5)
gzfile — Lê todo o arquivo-gz para uma matriz
Descrição
Esta função é identica a readgzfile(), exceto que ela retorna o arquivo em uma array.
Parâmetros
- filename
-
O nome do arquivo.
- use_include_path
-
Você pode definir esta parâmetro para 1, se você quer procurar o arquivo no include_path também.
Valor Retornado
Um array contendo o arquivo, uma linha por célula.
Exemplos
Exemplo #1 Exemplo gzfile()
<?php
$lines = gzfile('somefile.gz');
foreach ($lines as $line) {
echo $line;
}
?>
gzgetc
(PHP 4, PHP 5)
gzgetc — Obtém um caractere de um ponteiro de arquivo-gz
Descrição
Retorna uma string contendo um único (descomprimido) caractere lido a partir do arquivo gz.
Parâmetros
- zp
-
O ponteiro de arquivo-gz deve ser válido , e deve apontar para um arquivo aberto corretamente com gzopen().
Valor Retornado
O caractere descomprimido ou FALSE em caso de EOF (Diferentemente de gzeof()).
Exemplos
Exemplo #1 Exemplo gzgetc()
<?php
$gz = gzopen('somefile.gz', 'r');
while (!gzeof($gz)) {
echo gzgetc($gz);
}
gzclose($gz);
?>
gzgets
(PHP 4, PHP 5)
gzgets — Obtém uma linha de um ponteiro de arquivo
Descrição
Obtém uma (descomprimida) string até o tamanho length - 1 bytes lidos a partir do ponteiro de arquivo dado. A leitura termina quando length - 1 bytes tiverem sido lidos, em uma nova liha ou em EOF (o que vier primeiro).
Parâmetros
- zp
-
O ponteiro do arquivo deve ser válido, e deve apontar para um arquivo aberto corretamente com gzopen().
- length
-
O tamanho dos dados a pegar.
Valor Retornado
A string descomprimida, ou FALSE em caso de erro.
Exemplos
Exemplo #1 gzgets() example
<?php
$handle = gzopen('somefile.gz', 'r');
while (!gzeof($handle)) {
$buffer = gzgets($handle, 4096);
echo $buffer;
}
gzclose($handle);
?>
gzgetss
(PHP 4, PHP 5)
gzgetss — Obtém uma linha de um ponteiro de arquivo-gz e retira as tags HTML
Descrição
Identica a gzgets(), exceto que gzgetss() tenta retirar todas as tags HTML e todas as tags PHP do texto que lê.
Parâmetros
- zp
-
O ponteiro para o arquivo gz. Ele deve ser válido, e deve apontar para um arquivo aberto de maneira bem sucedida por gzopen().
- length
-
O tamanho dos dados a pegar.
- allowable_tags
-
Você pode usar esta parâmetro opcional para especificar as tags que não devem ser renovidas.
Valor Retornado
A string descomprimida e com as tags removidas, ou FALSE em caso de erro.
Histórico
| Versão | Descrição |
|---|---|
| 3.0.13 e 4.0.0 | Foi adicionado allowable_tags. |
Exemplos
Exemplo #1 Exemplo gzgetss()
<?php
$handle = gzopen('somefile.gz', 'r');
while (!gzeof($handle)) {
$buffer = gzgetss($handle, 4096);
echo $buffer;
}
gzclose($handle);
?>
Veja Também
- gzopen() - Abre um arquivo-gz
- gzgets() - Obtém uma linha de um ponteiro de arquivo
- strip_tags() - Retira as tags HTML e PHP de uma string
gzinflate
(PHP 4 >= 4.0.4, PHP 5)
gzinflate — Descomprime uma string usando DEFLATE
Descrição
Esta função descomprime uma string.
Parâmetros
- data
-
Os dados comprimidos por gzdeflate().
- length
-
O limite de tamanho dos dados a descompactar.
Valor Retornado
Os dados originais descomprimidos ou FALSE em caso de erro.
Esta função irá retornar um erro se os dados descomprimidos forem maiores do 32768 vezes o tamanho dos dados comprimidos de entrada data ou mais do que o parâmetro opcional length.
Exemplos
Exemplo #1 Exemplo gzinflate()
<?php
$compressed = gzdeflate('Compress me', 9);
$uncompressed = gzinflate($compressed);
echo $uncompressed;
?>
Veja Também
Veja também gzcompress() - Comprime uma string. gzuncompress() - Descomprime uma string com DEFLATED, gzdeflate() - Comprime uma string usando DEFLATE, e gzencode() - Cria uma string comprimida com gzip.
gzopen
(PHP 4, PHP 5)
gzopen — Abre um arquivo-gz
Descrição
Abre um arquivo-gz para leitura ou escrita. O parâmetro mode é igual a fopen() ("rb" ou "wb") mas pode incluir também um nível de compressão ("wb9") ou uma estratégia: 'f' para dados filtrados como em "wb6f", 'h' para compressão apenas com Huffman como em "wb1h". (Veja a descrição de deflateInit2 e zlib.h para maiores informações sobre o parâmetro strategy.)
gzopen() pode ser usada para ler um arquivo que não esteja no formato gzip; neste caso gzread() irá ler diretamente a partir do arquivo sem descompressão.
gzopen() retorna um ponteiro para arquivo aberto, após isso, tudo o que você ler apartir desse descritor de arquivo será transparentemente descomprimido e o que você escrever será comprimido.
Se falhar ao abrir, a função retorna FALSE.
Você pode usar o terceiro parâmetro, que é opcional, e defini-lo como "1", se você quiser procurar pelo arquivo no include_path, também.
Exemplo #1 Exemplo gzopen()
<?php
$fp = gzopen("/tmp/file.gz", "r");
?>
Veja também gzclose().
gzpassthru
(PHP 4, PHP 5)
gzpassthru — Envia todos os dados restantes em um ponteiro para arquivo-gz
Descrição
Lê até o EOF do ponteiro de arquivo-gz e escreve o (descomprimido) resultado para a saída padrão.
Se acontecer um erro, retorna FALSE.
O ponteiro para o arquivo deve ser válido, e deve apontar para um arquivo aberto corretamente com gzopen().
Descrição
Esta função é um apelido para: gzwrite().
gzread
(PHP 4, PHP 5)
gzread — Leitura de arquivos-gz segura para binários
Descrição
gzread() lê length bytes do ponteiro de arquivo gz. A leitura pára quando length (descomprimido) bytes forem lidos ou até o fim do arquivo, o que chegar primeiro.
Parâmetros
- zp
-
O ponteiro do arquivo gz. Precisa ser válido, e apontar para um arquivo aberto com sucesso por gzopen().
- length
-
O número de bytes a serem lidos.
Valor Retornado
The data that have been read.
Exemplos
Exemplo #1 Exemplo da gzread()
<?php
// Obtém o conteúdo de um arquivo-gz em uma string
$filename = "/usr/local/something.txt.gz";
$zd = gzopen($filename, "r");
$contents = gzread($zd, 10000);
gzclose($zd);
?>
Veja Também
- gzwrite() - Escrita segura para binário em arquivo-gz
- gzopen() - Abre um arquivo-gz
- gzgets() - Obtém uma linha de um ponteiro de arquivo
- gzgetss() - Obtém uma linha de um ponteiro de arquivo-gz e retira as tags HTML
- gzfile() - Lê todo o arquivo-gz para uma matriz
- gzpassthru() - Envia todos os dados restantes em um ponteiro para arquivo-gz
gzrewind
(PHP 4, PHP 5)
gzrewind — Retorna ao início a posição de um ponteiro para um arquivo-gz
Descrição
Define o indicador de posição para o dado arquivo gz para o início do arquivo.
Parâmetros
- zp
-
O ponteiro do arquivo gz. Ele deve ser válido e deve apontar para um arquivo aberto corretamente com gzopen().
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
gzseek
(PHP 4, PHP 5)
gzseek — Move o ponteiro de um arquivo-gz
Descrição
Define a posição do indicador do dado ponteiro de arquivo para a dada posição do byte dentro do arquivo. Equivalente a chamar (em C) gzseek(zp, offset, SEEK_SET).
Se o arquivo esta aberto para leitura, esta função é emulada mas pode ser extremamente lenta. Se o arquivo estiver aberto para escrita, apenas mudanças para a frente são suportadas; gzseek() então comprime uma sequencia de zeros até a nova posição de início.
Parâmetros
- zp
-
O ponteiro de arquivo gz. Ele precisa ser válido, e apontar para um arquivo aberto com sucesso por gzopen().
- offset
-
A posição desejada.
Valor Retornado
Em caso de sucesso, retorna 0; senão retorna -1. Note que mover a posição alem do fim do arquivo não é considerado um erro. past EOF is not considered an error.
Exemplos
Exemplo #1 Exemplo da gzseek()
<?php
$gz = gzopen('somefile.gz', 'r');
gzseek($gz,2);
echo gzgetc($gz);
gzclose($gz);
?>
Veja Também
- gztell() - Indica a posição de leitura/gravação em um ponteiro para arquivo-gz
- gzrewind() - Retorna ao início a posição de um ponteiro para um arquivo-gz
gztell
(PHP 4, PHP 5)
gztell — Indica a posição de leitura/gravação em um ponteiro para arquivo-gz
Descrição
Obtém a posição do ponteiro de arquivo; i.e., seu índice dentro do arquivo.
Parâmetros
- zp
-
O ponteiro de arquivo gz. Precisa ser válido, e deve apontar para um arquivo aberto corretamente com gzopen().
Valor Retornado
A posição do ponteiro do arquivo ou FALSE se um erro ocorrer.
Veja Também
- gzopen() - Abre um arquivo-gz
- gzseek() - Move o ponteiro de um arquivo-gz
- gzrewind() - Retorna ao início a posição de um ponteiro para um arquivo-gz
gzuncompress
(PHP 4 >= 4.0.1, PHP 5)
gzuncompress — Descomprime uma string com DEFLATED
Descrição
Esta função leva os dados data comprimidos por gzcompress() e retorna os dados originais descomprimidos ou FALSE em caso de erro. A função irá retornar um erro se os dados descompactados foram mais do que 32768 vezes o tamanho dos dados compactados data ou mais do que o parâmetro opcional length.
Veja também gzdeflate(), gzinflate(), gzcompress() e gzencode().
gzwrite
(PHP 4, PHP 5)
gzwrite — Escrita segura para binário em arquivo-gz
Descrição
gzwrite() escreve o conteúdo de string para o arquivo-gz.
Parâmetros
- zp
-
O ponteiro do arquivo gz. Precisa ser válido, e apontar para um arquivo aberto com sucesso por gzopen().
- string
-
A string a ser escrita.
- length
-
O número de bytes descompresso para escrever. Se fornecido, a escrita irá parar depos de length (descomprimido) bytes ter sido escritos, ou ao final de string, o que vier primeiro.
Nota:
Note que se o argumentolength for dado, então a configuração magic_quotes_runtime será ignorada e não serão retiradas as barras de string.
Valor Retornado
Retorna o número de (descomprimido) bytes escrito no dado stream do arquivo gz.
Exemplos
Exemplo #1 Exemplo da gzwrite()
<?php
$string = 'Some information to compress';
$gz = gzopen('somefile.gz','w9');
gzwrite($gz, $string);
gzclose($gz);
?>
readgzfile
(PHP 4, PHP 5)
readgzfile — Mostra um arquivo-gz
Descrição
Lê um arquivo, descomprime ele e escreve-o para a saída padrão.
readgzfile() pode ser usada para ler um arquivo o qual não esteja no formato gzip, neste caso readgzfile() irá ler diretamente do arquivo sem descompressão.
Parâmetros
- filename
-
O nome do arquivo. Este arquivo será aberto do sistema de arquivo e seu conteúdo escrito para saída padrão.
- use_include_path
-
Você pode definir este parâmetro opcional para 1, se você quer procurar pelo arquivo no include_path também.
Valor Retornado
Retorna o número de (descomprimidos) bytes lidos a partir do arquivo. Se acontecer um erro, é retornado FALSE e a menos que a função seja chamada como @readgzfile, uma mensagem de erro é mostrada.
Veja Também
- gzpassthru() - Envia todos os dados restantes em um ponteiro para arquivo-gz
- gzfile() - Lê todo o arquivo-gz para uma matriz
- gzopen() - Abre um arquivo-gz
zlib_get_coding_type
(PHP 4 >= 4.3.2, PHP 5)
zlib_get_coding_type — Retorna o tipo de codificação para a compressão de saída
Descrição
Retorna o tipo de codificação usado para a compressão de saída.
Valor Retornado
Possíveis valores de retorno são gzip, deflate, ou FALSE.
Índice
- gzclose — Fecha um ponteiro para um arquivo-gz
- gzcompress — Comprime uma string
- gzdecode — Decodifica uma string comprimida usando o gzip
- gzdeflate — Comprime uma string usando DEFLATE
- gzencode — Cria uma string comprimida com gzip
- gzeof — Testa para o fim de um ponteiro de arquivo-gz
- gzfile — Lê todo o arquivo-gz para uma matriz
- gzgetc — Obtém um caractere de um ponteiro de arquivo-gz
- gzgets — Obtém uma linha de um ponteiro de arquivo
- gzgetss — Obtém uma linha de um ponteiro de arquivo-gz e retira as tags HTML
- gzinflate — Descomprime uma string usando DEFLATE
- gzopen — Abre um arquivo-gz
- gzpassthru — Envia todos os dados restantes em um ponteiro para arquivo-gz
- gzputs — Sinônimo de gzwrite
- gzread — Leitura de arquivos-gz segura para binários
- gzrewind — Retorna ao início a posição de um ponteiro para um arquivo-gz
- gzseek — Move o ponteiro de um arquivo-gz
- gztell — Indica a posição de leitura/gravação em um ponteiro para arquivo-gz
- gzuncompress — Descomprime uma string com DEFLATED
- gzwrite — Escrita segura para binário em arquivo-gz
- readgzfile — Mostra um arquivo-gz
- zlib_get_coding_type — Retorna o tipo de codificação para a compressão de saída
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Exemplos
- Funções da Zlib
- gzclose — Fecha um ponteiro para um arquivo-gz
- gzcompress — Comprime uma string
- gzdecode — Decodifica uma string comprimida usando o gzip
- gzdeflate — Comprime uma string usando DEFLATE
- gzencode — Cria uma string comprimida com gzip
- gzeof — Testa para o fim de um ponteiro de arquivo-gz
- gzfile — Lê todo o arquivo-gz para uma matriz
- gzgetc — Obtém um caractere de um ponteiro de arquivo-gz
- gzgets — Obtém uma linha de um ponteiro de arquivo
- gzgetss — Obtém uma linha de um ponteiro de arquivo-gz e retira as tags HTML
- gzinflate — Descomprime uma string usando DEFLATE
- gzopen — Abre um arquivo-gz
- gzpassthru — Envia todos os dados restantes em um ponteiro para arquivo-gz
- gzputs — Sinônimo de gzwrite
- gzread — Leitura de arquivos-gz segura para binários
- gzrewind — Retorna ao início a posição de um ponteiro para um arquivo-gz
- gzseek — Move o ponteiro de um arquivo-gz
- gztell — Indica a posição de leitura/gravação em um ponteiro para arquivo-gz
- gzuncompress — Descomprime uma string com DEFLATED
- gzwrite — Escrita segura para binário em arquivo-gz
- readgzfile — Mostra um arquivo-gz
- zlib_get_coding_type — Retorna o tipo de codificação para a compressão de saída
- Bzip2
- LZF
- Phar
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Using Phar Archives
- Creating Phar Archives
- What makes a phar a phar and not a tar or a zip?
- Phar — The Phar class
- PharData — The PharData class
- PharFileInfo — The PharFileInfo class
- PharException — The PharException class
- Rar — Rar Archiving
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Exemplos
- Rar Funções
- RarArchive — The RarArchive class
- RarEntry — The RarEntry class
- RarException — The RarException class
- Zip
- Zlib — Compressão Zlib
Processamento de Cartão de Crédito
MCVE (Monetra) Payment
Introdução
These functions interface the MCVE (Monetra) API (libmonetra, formerly known as libmcve), allowing you to work directly with MCVE/Monetra from your PHP scripts. MCVE/Monetra is Main Street Softworks' solution to direct credit/debit/gift card processing for Linux/Unix/MacOSX/Windows ( » http://www.mainstreetsoftworks.com/ ). It lets you directly address the credit card clearing houses via your *nix box, modem and/or internet connection (bypassing the need for an additional service such as Authorize.Net or Pay Flow Pro). Using the MCVE/Monetra module for PHP, you can process credit cards directly through MCVE/Monetra via your PHP scripts. The following references will outline the process.
Nota:
MCVE/Monetra is the replacement for RedHat's CCVS. They contracted with RedHat in late 2001 to migrate all existing clientele to the MCVE platform.
Nota:
Esta extensão foi movida para o repositório » PECL e não é mais distribuida em conjunto com o PHP a partir do PHP 5.1.0.
Nota: Esta extensão não está disponível na plataforma Windows.
Instalação/Configuração
Índice
Dependências
The LibMonetra (formerly libmcve) library.
Instalação
Esta extensão » PECL não vem compilada com o PHP.
Informações para a instalação desta extensão PECL podem ser encontradas no manual no capitulo intitulado Instalação de extensões PECL. Informações adicionais como novas versões, downloads, arquivos fontes, manutenções, e um Changelog, podem ser obtidos aqui: » http://pecl.php.net/package/mcve.
Uma DLL para esta extenção PECL esta atualmente indisponível. Veja também a seção compilando no Windows section.
If installing without specifying the libmonetra path, PHP will attempt to look in the default LibMonetra Install location (/usr/local). If Monetra (MCVE) is in a non-standard location, run configure with: --with-mcve=$mcve_path , where $mcve_path is the path to your MCVE/Monetra installation. Please note that MCVE/Monetra support requires that $mcve_path/lib and $mcve_path/include exist, and include mcve.h or monetra.h under the include directory and libmcve.so and/or libmcve.a and/or libmonetra.so and/or libmonetra.a under the lib directory.
Since MCVE/Monetra has true server/client separation, there are no additional requirements for running PHP with MCVE support. To test your MCVE/Monetra extension in PHP, you may connect to testbox.monetra.com on port 8333 for IP, or port 8444 for SSL using the MCVE/Monetra PHP API. Use 'vitale' for your username, and 'test' for your password. Additional information about test facilities are available at » http://www.mainstreetsoftworks.com/.
Configurações em Execução
Esta extensão não define nenhum parâmetro de configuração no php.ini.
Constantes pré-definidas
As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.
MCVE Funções
Veja Também
Additional documentation about MCVE/Monetra's PHP API can be found at » http://www.mainstreetsoftworks.com/documentation.html. Main Street's documentation is complete and should be the primary reference for functions.
m_checkstatus
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_checkstatus — Check to see if a transaction has completed
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_connect
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_connect — Establish the connection to MCVE
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_connectionerror
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_connectionerror — Get a textual representation of why a connection failed
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_deletetrans
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_deletetrans — Delete specified transaction from MCVE_CONN structure
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_destroyconn
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_destroyconn — Destroy the connection and MCVE_CONN structure
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
Returns TRUE.
m_destroyengine
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_destroyengine — Free memory associated with IP/SSL connectivity
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
Valor Retornado
Não há valor retornado.
m_getcell
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_getcell — Get a specific cell from a comma delimited response by column name
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_getcellbynum
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_getcellbynum — Get a specific cell from a comma delimited response by column number
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_getcommadelimited
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_getcommadelimited — Get the RAW comma delimited data returned from MCVE
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_getheader
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_getheader — Get the name of the column in a comma-delimited response
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_initconn
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_initconn — Create and initialize an MCVE_CONN structure
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
Returns an MCVE_CONN resource.
m_initengine
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_initengine — Ready the client for IP/SSL Communication
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- location
-
Valor Retornado
m_iscommadelimited
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_iscommadelimited — Checks to see if response is comma delimited
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_maxconntimeout
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_maxconntimeout — The maximum amount of time the API will attempt a connection to MCVE
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_monitor
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_monitor — Perform communication with MCVE (send/receive data) Non-blocking
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_numcolumns
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_numcolumns — Number of columns returned in a comma delimited response
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_numrows
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_numrows — Number of rows returned in a comma delimited response
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_parsecommadelimited
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_parsecommadelimited — Parse the comma delimited response so m_getcell, etc will work
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_responsekeys
(PHP 5 >= 5.0.5, PECL mcve >= 1.0.0)
m_responsekeys — Returns array of strings which represents the keys that can be used for response parameters on this transaction
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_responseparam
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_responseparam — Get a custom response parameter
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_returnstatus
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_returnstatus — Check to see if the transaction was successful
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_setblocking
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_setblocking — Set blocking/non-blocking mode for connection
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_setdropfile
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_setdropfile — Set the connection method to Drop-File
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_setip
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_setip — Set the connection method to IP
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_setssl_cafile
(PHP 5 >= 5.0.5, PECL mcve >= 1.0.0)
m_setssl_cafile — Set SSL CA (Certificate Authority) file for verification of server certificate
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_setssl_files
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_setssl_files — Set certificate key files and certificates if server requires client certificate verification
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_setssl
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_setssl — Set the connection method to SSL
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_settimeout
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_settimeout — Set maximum transaction time (per trans)
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_sslcert_gen_hash
(PECL mcve >= 5.2.0)
m_sslcert_gen_hash — Generate hash for SSL client certificate verification
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- filename
-
Valor Retornado
m_transactionssent
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_transactionssent — Check to see if outgoing buffer is clear
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_transinqueue
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_transinqueue — Number of transactions in client-queue
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_transkeyval
(PHP 5 >= 5.0.5, PECL mcve >= 1.0.0)
m_transkeyval — Add key/value pair to a transaction. Replaces deprecated transparam()
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_transnew
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_transnew — Start a new transaction
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_transsend
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_transsend — Finalize and send the transaction
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_uwait
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_uwait — Wait x microsecs
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- microsecs
-
Valor Retornado
m_validateidentifier
(PHP 5 >= 5.0.5, PECL mcve >= 1.0.0)
m_validateidentifier — Whether or not to validate the passed identifier on any transaction it is passed to
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_verifyconnection
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_verifyconnection — Set whether or not to PING upon connect to verify connection
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
m_verifysslcert
(PHP 4 >= 4.3.9, PHP 5 <= 5.0.5, PECL mcve >= 1.0.0)
m_verifysslcert — Set whether or not to verify the server ssl certificate
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
Índice
- m_checkstatus — Check to see if a transaction has completed
- m_completeauthorizations — Number of complete authorizations in queue, returning an array of their identifiers
- m_connect — Establish the connection to MCVE
- m_connectionerror — Get a textual representation of why a connection failed
- m_deletetrans — Delete specified transaction from MCVE_CONN structure
- m_destroyconn — Destroy the connection and MCVE_CONN structure
- m_destroyengine — Free memory associated with IP/SSL connectivity
- m_getcell — Get a specific cell from a comma delimited response by column name
- m_getcellbynum — Get a specific cell from a comma delimited response by column number
- m_getcommadelimited — Get the RAW comma delimited data returned from MCVE
- m_getheader — Get the name of the column in a comma-delimited response
- m_initconn — Create and initialize an MCVE_CONN structure
- m_initengine — Ready the client for IP/SSL Communication
- m_iscommadelimited — Checks to see if response is comma delimited
- m_maxconntimeout — The maximum amount of time the API will attempt a connection to MCVE
- m_monitor — Perform communication with MCVE (send/receive data) Non-blocking
- m_numcolumns — Number of columns returned in a comma delimited response
- m_numrows — Number of rows returned in a comma delimited response
- m_parsecommadelimited — Parse the comma delimited response so m_getcell, etc will work
- m_responsekeys — Returns array of strings which represents the keys that can be used for response parameters on this transaction
- m_responseparam — Get a custom response parameter
- m_returnstatus — Check to see if the transaction was successful
- m_setblocking — Set blocking/non-blocking mode for connection
- m_setdropfile — Set the connection method to Drop-File
- m_setip — Set the connection method to IP
- m_setssl_cafile — Set SSL CA (Certificate Authority) file for verification of server certificate
- m_setssl_files — Set certificate key files and certificates if server requires client certificate verification
- m_setssl — Set the connection method to SSL
- m_settimeout — Set maximum transaction time (per trans)
- m_sslcert_gen_hash — Generate hash for SSL client certificate verification
- m_transactionssent — Check to see if outgoing buffer is clear
- m_transinqueue — Number of transactions in client-queue
- m_transkeyval — Add key/value pair to a transaction. Replaces deprecated transparam()
- m_transnew — Start a new transaction
- m_transsend — Finalize and send the transaction
- m_uwait — Wait x microsecs
- m_validateidentifier — Whether or not to validate the passed identifier on any transaction it is passed to
- m_verifyconnection — Set whether or not to PING upon connect to verify connection
- m_verifysslcert — Set whether or not to verify the server ssl certificate
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- MCVE Funções
- m_checkstatus — Check to see if a transaction has completed
- m_completeauthorizations — Number of complete authorizations in queue, returning an array of their identifiers
- m_connect — Establish the connection to MCVE
- m_connectionerror — Get a textual representation of why a connection failed
- m_deletetrans — Delete specified transaction from MCVE_CONN structure
- m_destroyconn — Destroy the connection and MCVE_CONN structure
- m_destroyengine — Free memory associated with IP/SSL connectivity
- m_getcell — Get a specific cell from a comma delimited response by column name
- m_getcellbynum — Get a specific cell from a comma delimited response by column number
- m_getcommadelimited — Get the RAW comma delimited data returned from MCVE
- m_getheader — Get the name of the column in a comma-delimited response
- m_initconn — Create and initialize an MCVE_CONN structure
- m_initengine — Ready the client for IP/SSL Communication
- m_iscommadelimited — Checks to see if response is comma delimited
- m_maxconntimeout — The maximum amount of time the API will attempt a connection to MCVE
- m_monitor — Perform communication with MCVE (send/receive data) Non-blocking
- m_numcolumns — Number of columns returned in a comma delimited response
- m_numrows — Number of rows returned in a comma delimited response
- m_parsecommadelimited — Parse the comma delimited response so m_getcell, etc will work
- m_responsekeys — Returns array of strings which represents the keys that can be used for response parameters on this transaction
- m_responseparam — Get a custom response parameter
- m_returnstatus — Check to see if the transaction was successful
- m_setblocking — Set blocking/non-blocking mode for connection
- m_setdropfile — Set the connection method to Drop-File
- m_setip — Set the connection method to IP
- m_setssl_cafile — Set SSL CA (Certificate Authority) file for verification of server certificate
- m_setssl_files — Set certificate key files and certificates if server requires client certificate verification
- m_setssl — Set the connection method to SSL
- m_settimeout — Set maximum transaction time (per trans)
- m_sslcert_gen_hash — Generate hash for SSL client certificate verification
- m_transactionssent — Check to see if outgoing buffer is clear
- m_transinqueue — Number of transactions in client-queue
- m_transkeyval — Add key/value pair to a transaction. Replaces deprecated transparam()
- m_transnew — Start a new transaction
- m_transsend — Finalize and send the transaction
- m_uwait — Wait x microsecs
- m_validateidentifier — Whether or not to validate the passed identifier on any transaction it is passed to
- m_verifyconnection — Set whether or not to PING upon connect to verify connection
- m_verifysslcert — Set whether or not to verify the server ssl certificate
SPPLUS Payment System
Introdução
Esta extensão dá a você possibilidade de usar o » SPPLUS Payment System do Caisse d'Epargne (um banco francês).
Nota: Esta extensão não está disponível na plataforma Windows.
Consulte os arquivos README no fonte do kit_php da distribuição para detalhes de configuração.
Instalação/Configuração
Índice
Dependências
Nota: Você precisa no mínimo do PHP 4.1.0 e SPPLUS v.3
Nota: Você precisará obter o novo kit_php para spplus. Sinta-se livre para contactar o manentedor se você não conseguir.
Instalação
pequena nota sobre a instalação:
- Você precisa no mínimo do PHP 4.3.0 para a compressão funcionar
- Para instalar em PHP 4.3.0 e superior no prompt de comando Unix, digite pear install pecl/spplus
Configurações em Execução
Esta extensão não define nenhum parâmetro de configuração no php.ini.
Tipos Resource
Esta extensão não possui nenhum tipo resource.
Constantes pré-definidas
Esta extensão não possui nenhuma constante.
Funções para SPPLUS
calcul_hmac
(PECL spplus >= 1.0.0)
calcul_hmac — Obtém uma chave hmac (precisa 8 argumentos)
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Notas
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
calculhmac
(PECL spplus >= 1.0.0)
calculhmac — Obtém uma chave hmac (precisa 2 argumentos)
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Notas
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
nthmac
(PECL spplus >= 1.0.0)
nthmac — Obtém uma chave nthmac (precisa 2 argumentos)
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Notas
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
signeurlpaiement
(PECL spplus >= 1.0.0)
signeurlpaiement — Obtém uma url de pagamento (precisa 2 argumentos)
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Notas
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Índice
- calcul_hmac — Obtém uma chave hmac (precisa 8 argumentos)
- calculhmac — Obtém uma chave hmac (precisa 2 argumentos)
- nthmac — Obtém uma chave nthmac (precisa 2 argumentos)
- signeurlpaiement — Obtém uma url de pagamento (precisa 2 argumentos)
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Funções para SPPLUS
- calcul_hmac — Obtém uma chave hmac (precisa 8 argumentos)
- calculhmac — Obtém uma chave hmac (precisa 2 argumentos)
- nthmac — Obtém uma chave nthmac (precisa 2 argumentos)
- signeurlpaiement — Obtém uma url de pagamento (precisa 2 argumentos)
Extensões para Criptografia
Crack
Introdução
Estas funções permitem a você usar a biblioteca CrackLib para testar a 'força' de uma senha. A 'força' de uma senha é testada pelo seu tamanho, uso de letras maiúsculas e minúsculas, e conferido em um dicionário CrackLib especificado. CrackLib irá também dar mensagens de diagnóstico utéis que irão ajudar a 'fortalecer' a sua senha.
Nota:
Esta extensão foi movida para o repositório » PECL e não é mais distribuida em conjunto com o PHP a partir do PHP 5.0.0.
Instalação/Configuração
Índice
Dependências
Maiores informações sobre a biblioteca CrackLib podem ser encontradas em » http://sourceforge.net/projects/cracklib.
Instalação
Esta extensão » PECL não vem compilada com o PHP. Informações para a instalação desta extensão PECL podem ser encontradas no manual no capitulo intitulado Instalação de extensões PECL. Informações adicionais como novas versões, downloads, arquivos fontes, manutenções, e um Changelog, podem ser obtidos aqui: » http://pecl.php.net/package/crack.
No PHP 4, os fontes desta estensão PECL podem ser encontrados no diretório ext/ ou dentro dos fontes do PHP ou no link PECL acima. Para poder usar estas funções você deverá compilar o PHP com suporte a Crack usando a opção de configuração --with-crack[=DIR] .
Usuários do windows devem abilitar php_crack.dll dentro do php.ini para poder usar estas funções. No PHP esta DLL reside no diretório extensions/ junto aos binários do PHP para Windows. Uma DLL para esta extenção PECL esta atualmente indisponível. Veja também a seção compilando no Windows section.
Configurações em Execução
O comportamento dessas funções podem ser modificado pelas configurações do php.ini.
| Nome | Padrão | Modificável | Changelog |
|---|---|---|---|
| crack.default_dictionary | NULL | PHP_INI_PERDIR | PHP_INI_SYSTEM no crack <= 0.2. Disponível desde PHP 4.0.5. Removido no PHP 5.0.0. |
Tipos Resource
A extenção CrackLib define um identificador de resource de dicionário retornado pela crack_opendict().
Constantes pré-definidas
Esta extensão não possui nenhuma constante.
Exemplos
Este exemplo mostra como abrir um dicionário CrackLib, testar uma dada senha, receber alguma mensagem de diagnóstico, e fechar o dicionário.
Exemplo #1 Exemplo da CrackLib
<?php
// Open CrackLib Dictionary
$dictionary = crack_opendict('/usr/local/lib/pw_dict')
or die('Unable to open CrackLib dictionary');
// Perform password check
$check = crack_check($dictionary, 'gx9A2s0x');
// Retrieve messages
$diag = crack_getlastmessage();
echo $diag; // 'strong password'
// Close dictionary
crack_closedict($dictionary);
?>
Nota:
Se crack_check() retorna TRUE, crack_getlastmessage() retornará 'strong password'.
Funções da Crack
crack_check
(PECL crack >= 0.1)
crack_check — Faz uma conferencia obscura com a senha indicada
Descrição
Realiza uma conferencia obscura com o password dado no dicionário especificado.
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Parâmetros
- dictionary
-
O dicionário crack lib. Se não for especificado, o último dicionário aberto é usado.
- password
-
O password testado.
Valor Retornado
Retorna TRUE se password é forte, ou FALSE se não for.
crack_closedict
(PECL crack >= 0.1)
crack_closedict — Fecha um dicionário CrackLib aberto
Descrição
crack_closedict() fecha o identificador de dictionary indicado.
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Parâmetros
- dictionary
-
O dicinário para fechar. Se não for especificado, o diretório atual é fechado.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
crack_getlastmessage
(PECL crack >= 0.1)
crack_getlastmessage — Retorna a mensagem do último teste de senha
Descrição
crack_getlastmessage() retorna a mensagem do último teste de senha.
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Valor Retornado
A mensagem do ultimo teste de senha ou FALSE se não houve testes feitos até agora.
A mensagem retornada é uma de:
- it's WAY too short
- it is too short
- it does not contain enough DIFFERENT characters
- it is all whitespace
- it is too simplistic/systematic
- it looks like a National Insurance number.
- it is based on a dictionary word
- it is based on a (reversed) dictionary word
- strong password
crack_opendict
(PECL crack >= 0.1)
crack_opendict — Abre um novo dicionário CrackLib
Descrição
crack_opendict() abre o dictionary CrackLib especificado para usar com a função crack_check().
Esta função é EXPERIMENTAL. O comportamento desta função, seu nome, incluindo toda documentação pode ser modificado sem aviso em futuras versões do PHP. Esta função deve ser usada por sua própria conta e risco.
Nota:
Apenas um dicionário pode estar aberto de cada vez.
Parâmetros
- dictionary
-
O caminho para o dicinário Cracklib.
Valor Retornado
Retorna o identificador de recurso do dicionário em caso de sucesso, ou FALSE em caso de falha.
Veja Também
- crack_check() - Faz uma conferencia obscura com a senha indicada
- crack_closedict() - Fecha um dicionário CrackLib aberto
Índice
- crack_check — Faz uma conferencia obscura com a senha indicada
- crack_closedict — Fecha um dicionário CrackLib aberto
- crack_getlastmessage — Retorna a mensagem do último teste de senha
- crack_opendict — Abre um novo dicionário CrackLib
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Exemplos
- Funções da Crack
- crack_check — Faz uma conferencia obscura com a senha indicada
- crack_closedict — Fecha um dicionário CrackLib aberto
- crack_getlastmessage — Retorna a mensagem do último teste de senha
- crack_opendict — Abre um novo dicionário CrackLib
HASH Message Digest Framework
Introdução
Message Digest (hash) engine. Allows direct or incremental processing of arbitrary length messages using a variety of hashing algorithms.
Instalação/Configuração
Índice
Dependências
The Hash extension requires no external libraries and is enabled by default as of PHP 5.1.2. It may be explicitly disabled by using the --disable-hash switch to configure. Earlier versions of PHP may incorporate the Hash extension by installing the » PECL module.
Instalação
Não há nenhuma instalação necessária para utilizar estas funções, elas fazem parte do núcleo do PHP.
Configurações em Execução
Esta extensão não define nenhum parâmetro de configuração no php.ini.
Constantes pré-definidas
As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.
- HASH_HMAC (integer)
- Optional flag for hash_init(). Indicates that the HMAC digest-keying algorithm should be applied to the current hashing context.
Hash Funções
hash_algos
(PHP 5 >= 5.1.2, PECL hash >= 1.1)
hash_algos — Return a list of registered hashing algorithms
Descrição
Valor Retornado
Returns a numerically indexed array containing the list of supported hashing algorithms.
Histórico
| Versão | Descrição |
|---|---|
| 5.4.0 | Support for joaat, fnv132 and fnv164 was added. Support for Salsa10 and Salsa20 was removed. |
| 5.3.0 | Support for md2, ripemd256, ripemd320, salsa10, salsa20, snefru256 and sha224 was added |
Exemplos
Exemplo #1 hash_algos() example
As of PHP 5.3.0, hash_algos() will return the following list of algorithm names.
<?php
print_r(hash_algos());
?>
O exemplo acima irá imprimir algo similar a:
Array
(
[0] => md2
[1] => md4
[2] => md5
[3] => sha1
[4] => sha224
[5] => sha256
[6] => sha384
[7] => sha512
[8] => ripemd128
[9] => ripemd160
[10] => ripemd256
[11] => ripemd320
[12] => whirlpool
[13] => tiger128,3
[14] => tiger160,3
[15] => tiger192,3
[16] => tiger128,4
[17] => tiger160,4
[18] => tiger192,4
[19] => snefru
[20] => snefru256
[21] => gost
[22] => adler32
[23] => crc32
[24] => crc32b
[25] => salsa10
[26] => salsa20
[27] => haval128,3
[28] => haval160,3
[29] => haval192,3
[30] => haval224,3
[31] => haval256,3
[32] => haval128,4
[33] => haval160,4
[34] => haval192,4
[35] => haval224,4
[36] => haval256,4
[37] => haval128,5
[38] => haval160,5
[39] => haval192,5
[40] => haval224,5
[41] => haval256,5
)
hash_copy
(PHP 5 >= 5.3.0)
hash_copy — Copy hashing context
Descrição
Valor Retornado
Returns a copy of Hashing Context resource.
Exemplos
Exemplo #1 hash_copy() example
<?php
$context = hash_init("md5");
hash_update($context, "data");
/* copy context to be able to continue using it */
$copy_context = hash_copy($context);
echo hash_final($context), "\n";
hash_update($copy_context, "data");
echo hash_final($copy_context), "\n";
?>
O exemplo acima irá imprimir:
8d777f385d3dfec8815d20f7496026dc 511ae0b1c13f95e5f08f1a0dd3da3d93
hash_file
(PHP 5 >= 5.1.2, PECL hash >= 1.1)
hash_file — Generate a hash value using the contents of a given file
Descrição
Parâmetros
- algo
-
Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..)
- filename
-
URL describing location of file to be hashed; Supports fopen wrappers.
- raw_output
-
When set to TRUE, outputs raw binary data. FALSE outputs lowercase hexits.
Valor Retornado
Returns a string containing the calculated message digest as lowercase hexits unless raw_output is set to true in which case the raw binary representation of the message digest is returned.
Exemplos
Exemplo #1 Using hash_file()
<?php
/* Create a file to calculate hash of */
file_put_contents('example.txt', 'The quick brown fox jumped over the lazy dog.');
echo hash_file('md5', 'example.txt');
?>
O exemplo acima irá imprimir:
5c6ffbdd40d9556b73a21e63c3e0e904
Veja Também
- hash() - Generate a hash value (message digest)
- hash_hmac_file() - Generate a keyed hash value using the HMAC method and the contents of a given file
- hash_update_file() - Pump data into an active hashing context from a file
- md5_file() - Calcula hash md5 de um dado arquivo
- sha1_file() - Calcula a hash sha1 de um arquivo
hash_final
(PHP 5 >= 5.1.2, PECL hash >= 1.1)
hash_final — Finalize an incremental hash and return resulting digest
Descrição
Parâmetros
- context
-
Hashing context returned by hash_init().
- raw_output
-
When set to TRUE, outputs raw binary data. FALSE outputs lowercase hexits.
Valor Retornado
Returns a string containing the calculated message digest as lowercase hexits unless raw_output is set to true in which case the raw binary representation of the message digest is returned.
Exemplos
Exemplo #1 hash_final() example
<?php
$ctx = hash_init('sha1');
hash_update($ctx, 'The quick brown fox jumped over the lazy dog.');
echo hash_final($ctx);
?>
O exemplo acima irá imprimir:
c0854fb9fb03c41cce3802cb0d220529e6eef94e
Veja Também
- hash_init() - Initialize an incremental hashing context
- hash_update() - Pump data into an active hashing context
- hash_update_stream() - Pump data into an active hashing context from an open stream
- hash_update_file() - Pump data into an active hashing context from a file
hash_hmac_file
(PHP 5 >= 5.1.2, PECL hash >= 1.1)
hash_hmac_file — Generate a keyed hash value using the HMAC method and the contents of a given file
Descrição
Parâmetros
- algo
-
Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..) See hash_algos() for a list of supported algorithms.
- filename
-
URL describing location of file to be hashed; Supports fopen wrappers.
- key
-
Shared secret key used for generating the HMAC variant of the message digest.
- raw_output
-
When set to TRUE, outputs raw binary data. FALSE outputs lowercase hexits.
Valor Retornado
Returns a string containing the calculated message digest as lowercase hexits unless raw_output is set to true in which case the raw binary representation of the message digest is returned.
Exemplos
Exemplo #1 hash_hmac_file() example
<?php
/* Create a file to calculate hash of */
file_put_contents('example.txt', 'The quick brown fox jumped over the lazy dog.');
echo hash_hmac_file('md5', 'example.txt', 'secret');
?>
O exemplo acima irá imprimir:
7eb2b5c37443418fc77c136dd20e859c
Veja Também
- hash_algos() - Return a list of registered hashing algorithms
- hash_hmac() - Generate a keyed hash value using the HMAC method
- hash_file() - Generate a hash value using the contents of a given file
hash_hmac
(PHP 5 >= 5.1.2, PECL hash >= 1.1)
hash_hmac — Generate a keyed hash value using the HMAC method
Descrição
Parâmetros
- algo
-
Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..) See hash_algos() for a list of supported algorithms.
- data
-
Message to be hashed.
- key
-
Shared secret key used for generating the HMAC variant of the message digest.
- raw_output
-
When set to TRUE, outputs raw binary data. FALSE outputs lowercase hexits.
Valor Retornado
Returns a string containing the calculated message digest as lowercase hexits unless raw_output is set to true in which case the raw binary representation of the message digest is returned.
Exemplos
Exemplo #1 hash_hmac() example
<?php
echo hash_hmac('ripemd160', 'The quick brown fox jumped over the lazy dog.', 'secret');
?>
O exemplo acima irá imprimir:
b8e7ae12510bdfb1812e463a7f086122cf37e4f7
Veja Também
- hash() - Generate a hash value (message digest)
- hash_algos() - Return a list of registered hashing algorithms
- hash_init() - Initialize an incremental hashing context
- hash_hmac_file() - Generate a keyed hash value using the HMAC method and the contents of a given file
hash_init
(PHP 5 >= 5.1.2, PECL hash >= 1.1)
hash_init — Initialize an incremental hashing context
Descrição
Parâmetros
- algo
-
Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..)
- options
-
Optional settings for hash generation, currently supports only one option: HASH_HMAC. When specified, the key must be specified.
- key
-
When HASH_HMAC is specified for options, a shared secret key to be used with the HMAC hashing method must be supplied in this parameter.
Valor Retornado
Returns a Hashing Context resource for use with hash_update(), hash_update_stream(), hash_update_file(), and hash_final().
Exemplos
Exemplo #1 Incremental hashing example
<?php
$ctx = hash_init('md5');
hash_update($ctx, 'The quick brown fox ');
hash_update($ctx, 'jumped over the lazy dog.');
echo hash_final($ctx);
?>
O exemplo acima irá imprimir:
5c6ffbdd40d9556b73a21e63c3e0e904
Veja Também
- hash() - Generate a hash value (message digest)
- hash_file() - Generate a hash value using the contents of a given file
- hash_hmac() - Generate a keyed hash value using the HMAC method
- hash_hmac_file() - Generate a keyed hash value using the HMAC method and the contents of a given file
hash_update_file
(PHP 5 >= 5.1.2, PECL hash >= 1.1)
hash_update_file — Pump data into an active hashing context from a file
Descrição
Parâmetros
- context
-
Hashing context returned by hash_init().
- filename
-
URL describing location of file to be hashed; Supports fopen wrappers.
- context
-
Stream context as returned by stream_context_create().
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Veja Também
- hash_init() - Initialize an incremental hashing context
- hash_update() - Pump data into an active hashing context
- hash_update_stream() - Pump data into an active hashing context from an open stream
- hash_final() - Finalize an incremental hash and return resulting digest
- hash() - Generate a hash value (message digest)
- hash_file() - Generate a hash value using the contents of a given file
hash_update_stream
(PHP 5 >= 5.1.2, PECL hash >= 1.1)
hash_update_stream — Pump data into an active hashing context from an open stream
Descrição
Parâmetros
- context
-
Hashing context returned by hash_init().
- handle
-
Open file handle as returned by any stream creation function.
- length
-
Maximum number of characters to copy from handle into the hashing context.
Valor Retornado
Actual number of bytes added to the hashing context from handle.
Exemplos
Exemplo #1 hash_update_stream() example
<?php
$fp = tmpfile();
fwrite($fp, 'The quick brown fox jumped over the lazy dog.');
rewind($fp);
$ctx = hash_init('md5');
hash_update_stream($ctx, $fp);
echo hash_final($ctx);
?>
O exemplo acima irá imprimir:
5c6ffbdd40d9556b73a21e63c3e0e904
Veja Também
- hash_init() - Initialize an incremental hashing context
- hash_update() - Pump data into an active hashing context
- hash_final() - Finalize an incremental hash and return resulting digest
- hash() - Generate a hash value (message digest)
- hash_file() - Generate a hash value using the contents of a given file
hash_update
(PHP 5 >= 5.1.2, PECL hash >= 1.1)
hash_update — Pump data into an active hashing context
Descrição
Parâmetros
- context
-
Hashing context returned by hash_init().
- data
-
Message to be included in the hash digest.
Valor Retornado
Returns TRUE.
Veja Também
- hash_init() - Initialize an incremental hashing context
- hash_update_file() - Pump data into an active hashing context from a file
- hash_update_stream() - Pump data into an active hashing context from an open stream
- hash_final() - Finalize an incremental hash and return resulting digest
hash
(PHP 5 >= 5.1.2, PECL hash >= 1.1)
hash — Generate a hash value (message digest)
Descrição
Parâmetros
- algo
-
Name of selected hashing algorithm (i.e. "md5", "sha256", "haval160,4", etc..)
- data
-
Message to be hashed.
- raw_output
-
When set to TRUE, outputs raw binary data. FALSE outputs lowercase hexits.
Valor Retornado
Returns a string containing the calculated message digest as lowercase hexits unless raw_output is set to true in which case the raw binary representation of the message digest is returned.
Histórico
| Versão | Descrição |
|---|---|
| 5.4.0 | The tiger algorithm now uses big-endian byte ordering. |
Exemplos
Exemplo #1 A hash() example
<?php
echo hash('ripemd160', 'The quick brown fox jumped over the lazy dog.');
?>
O exemplo acima irá imprimir:
ec457d0a974c48d5685a7efa03d137dc8bbde7e3
Veja Também
- hash_file() - Generate a hash value using the contents of a given file
- hash_hmac() - Generate a keyed hash value using the HMAC method
- hash_init() - Initialize an incremental hashing context
- md5() - Calcula o "hash MD5" de uma string
- sha1() - Calcula a hash sha1 de uma string
Índice
- hash_algos — Return a list of registered hashing algorithms
- hash_copy — Copy hashing context
- hash_file — Generate a hash value using the contents of a given file
- hash_final — Finalize an incremental hash and return resulting digest
- hash_hmac_file — Generate a keyed hash value using the HMAC method and the contents of a given file
- hash_hmac — Generate a keyed hash value using the HMAC method
- hash_init — Initialize an incremental hashing context
- hash_update_file — Pump data into an active hashing context from a file
- hash_update_stream — Pump data into an active hashing context from an open stream
- hash_update — Pump data into an active hashing context
- hash — Generate a hash value (message digest)
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Hash Funções
- hash_algos — Return a list of registered hashing algorithms
- hash_copy — Copy hashing context
- hash_file — Generate a hash value using the contents of a given file
- hash_final — Finalize an incremental hash and return resulting digest
- hash_hmac_file — Generate a keyed hash value using the HMAC method and the contents of a given file
- hash_hmac — Generate a keyed hash value using the HMAC method
- hash_init — Initialize an incremental hashing context
- hash_update_file — Pump data into an active hashing context from a file
- hash_update_stream — Pump data into an active hashing context from an open stream
- hash_update — Pump data into an active hashing context
- hash — Generate a hash value (message digest)
Mcrypt
Introdução
This is an interface to the mcrypt library, which supports a wide variety of block algorithms such as DES, TripleDES, Blowfish (default), 3-WAY, SAFER-SK64, SAFER-SK128, TWOFISH, TEA, RC2 and GOST in CBC, OFB, CFB and ECB cipher modes. Additionally, it supports RC6 and IDEA which are considered "non-free". CFB/OFB are 8bit by default.
Instalação/Configuração
Índice
Dependências
These functions work using » mcrypt. To use it, download libmcrypt-x.x.tar.gz from » http://mcrypt.sourceforge.net/ and follow the included installation instructions.
As of PHP 5.0.0 you will need libmcrypt Version 2.5.6 or greater.
Windows users will find the library is the PHP 5.2 Windows binaries release. PHP 5.3 Windows binaries uses the static version of the MCrypt library, no DLL are needed.
If you linked against libmcrypt 2.4.x or higher, the following additional block algorithms are supported: CAST, LOKI97, RIJNDAEL, SAFERPLUS, SERPENT and the following stream ciphers: ENIGMA (crypt), PANAMA, RC4 and WAKE. With libmcrypt 2.4.x or higher another cipher mode is also available; nOFB.
Instalação
You need to compile PHP with the --with-mcrypt[=DIR] parameter to enable this extension. DIR is the mcrypt install directory. Make sure you compile libmcrypt with the option --disable-posix-threads .
Configurações em Execução
O comportamento dessas funções podem ser modificado pelas configurações do php.ini.
| Nome | Padrão | Modificável | Histórico |
|---|---|---|---|
| mcrypt.algorithms_dir | NULL | PHP_INI_ALL | |
| mcrypt.modes_dir | NULL | PHP_INI_ALL |
Breve descrição das diretivas de configuração.
- mcrypt.algorithms_dir string
-
The directory that contains the algorithms. Defaults to the directories compiled within libmcrypt, which is typically /usr/local/lib/libmcrypt. See mcrypt_list_algorithms() for additional details.
- mcrypt.modes_dir string
-
The directory that contains the modes. Defaults to the directories compiled within libmcrypt, which is typically /usr/local/lib/libmcrypt. See mcrypt_list_modes() for additional details.
Constantes pré-definidas
As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.
Mcrypt can operate in four block cipher modes (CBC, OFB, CFB, and ECB). If linked against libmcrypt-2.4.x or higher the functions can also operate in the block cipher mode nOFB and in STREAM mode. Below you find a list with all supported encryption modes together with the constants that are defines for the encryption mode. For a more complete reference and discussion see Applied Cryptography by Schneier (ISBN 0-471-11709-9).
- MCRYPT_MODE_ECB (electronic codebook) is suitable for random data, such as encrypting other keys. Since data there is short and random, the disadvantages of ECB have a favorable negative effect.
- MCRYPT_MODE_CBC (cipher block chaining) is especially suitable for encrypting files where the security is increased over ECB significantly.
- MCRYPT_MODE_CFB (cipher feedback) is the best mode for encrypting byte streams where single bytes must be encrypted.
- MCRYPT_MODE_OFB (output feedback, in 8bit) is comparable to CFB, but can be used in applications where error propagation cannot be tolerated. It's insecure (because it operates in 8bit mode) so it is not recommended to use it.
- MCRYPT_MODE_NOFB (output feedback, in nbit) is comparable to OFB, but more secure because it operates on the block size of the algorithm.
- MCRYPT_MODE_STREAM is an extra mode to include some stream algorithms like "WAKE" or "RC4".
Some other mode and random device constants:
Mcrypt ciphers
Here is a list of ciphers which are currently supported by the mcrypt extension. For a complete list of supported ciphers, see the defines at the end of mcrypt.h. The general rule with the mcrypt-2.2.x API is that you can access the cipher from PHP with MCRYPT_ciphername. With the libmcrypt-2.4.x and libmcrypt-2.5.x API these constants also work, but it is possible to specify the name of the cipher as a string with a call to mcrypt_module_open().
- MCRYPT_3DES
- MCRYPT_ARCFOUR_IV (libmcrypt > 2.4.x only)
- MCRYPT_ARCFOUR (libmcrypt > 2.4.x only)
- MCRYPT_BLOWFISH
- MCRYPT_CAST_128
- MCRYPT_CAST_256
- MCRYPT_CRYPT
- MCRYPT_DES
- MCRYPT_DES_COMPAT (libmcrypt 2.2.x only)
- MCRYPT_ENIGMA (libmcrypt > 2.4.x only, alias for MCRYPT_CRYPT)
- MCRYPT_GOST
- MCRYPT_IDEA (non-free)
- MCRYPT_LOKI97 (libmcrypt > 2.4.x only)
- MCRYPT_MARS (libmcrypt > 2.4.x only, non-free)
- MCRYPT_PANAMA (libmcrypt > 2.4.x only)
- MCRYPT_RIJNDAEL_128 (libmcrypt > 2.4.x only)
- MCRYPT_RIJNDAEL_192 (libmcrypt > 2.4.x only)
- MCRYPT_RIJNDAEL_256 (libmcrypt > 2.4.x only)
- MCRYPT_RC2
- MCRYPT_RC4 (libmcrypt 2.2.x only)
- MCRYPT_RC6 (libmcrypt > 2.4.x only)
- MCRYPT_RC6_128 (libmcrypt 2.2.x only)
- MCRYPT_RC6_192 (libmcrypt 2.2.x only)
- MCRYPT_RC6_256 (libmcrypt 2.2.x only)
- MCRYPT_SAFER64
- MCRYPT_SAFER128
- MCRYPT_SAFERPLUS (libmcrypt > 2.4.x only)
- MCRYPT_SERPENT(libmcrypt > 2.4.x only)
- MCRYPT_SERPENT_128 (libmcrypt 2.2.x only)
- MCRYPT_SERPENT_192 (libmcrypt 2.2.x only)
- MCRYPT_SERPENT_256 (libmcrypt 2.2.x only)
- MCRYPT_SKIPJACK (libmcrypt > 2.4.x only)
- MCRYPT_TEAN (libmcrypt 2.2.x only)
- MCRYPT_THREEWAY
- MCRYPT_TRIPLEDES (libmcrypt > 2.4.x only)
- MCRYPT_TWOFISH (for older mcrypt 2.x versions, or mcrypt > 2.4.x )
- MCRYPT_TWOFISH128 (TWOFISHxxx are available in newer 2.x versions, but not in the 2.4.x versions)
- MCRYPT_TWOFISH192
- MCRYPT_TWOFISH256
- MCRYPT_WAKE (libmcrypt > 2.4.x only)
- MCRYPT_XTEA (libmcrypt > 2.4.x only)
You must (in CFB and OFB mode) or can (in CBC mode) supply an initialization vector (IV) to the respective cipher function. The IV must be unique and must be the same when decrypting/encrypting. With data which is stored encrypted, you can take the output of a function of the index under which the data is stored (e.g. the MD5 key of the filename). Alternatively, you can transmit the IV together with the encrypted data (see chapter 9.3 of Applied Cryptography by Schneier (ISBN 0-471-11709-9) for a discussion of this topic).
Exemplos
Mcrypt can be used to encrypt and decrypt using the above mentioned ciphers. If you linked against libmcrypt-2.2.x, the four important mcrypt commands (mcrypt_cfb(), mcrypt_cbc(), mcrypt_ecb(), and mcrypt_ofb()) can operate in both modes which are named MCRYPT_ENCRYPT and MCRYPT_DECRYPT, respectively.
Exemplo #1 Encrypt an input value with TripleDES under 2.2.x in ECB mode
<?php
$key = "this is a secret key";
$input = "Let us meet at 9 o'clock at the secret place.";
$encrypted_data = mcrypt_ecb (MCRYPT_3DES, $key, $input, MCRYPT_ENCRYPT);
?>
If you linked against libmcrypt 2.4.x or 2.5.x, these functions are still available, but it is recommended that you use the advanced functions.
Exemplo #2 Encrypt an input value with TripleDES under 2.4.x and higher in ECB mode
<?php
$key = "this is a secret key";
$input = "Let us meet at 9 o'clock at the secret place.";
$td = mcrypt_module_open('tripledes', '', 'ecb', '');
$iv = mcrypt_create_iv (mcrypt_enc_get_iv_size($td), MCRYPT_RAND);
mcrypt_generic_init($td, $key, $iv);
$encrypted_data = mcrypt_generic($td, $input);
mcrypt_generic_deinit($td);
mcrypt_module_close($td);
?>
Mcrypt Funções
mcrypt_cbc
(PHP 4, PHP 5)
mcrypt_cbc — Encrypts/decrypts data in CBC mode
Descrição
The first prototype is when linked against libmcrypt 2.2.x, the second when linked against libmcrypt 2.4.x or higher. The mode should be either MCRYPT_ENCRYPT or MCRYPT_DECRYPT.
This function should not be used anymore, see mcrypt_generic() and mdecrypt_generic() for replacements.
mcrypt_cfb
(PHP 4, PHP 5)
mcrypt_cfb — Encrypts/decrypts data in CFB mode
Descrição
The first prototype is when linked against libmcrypt 2.2.x, the second when linked against libmcrypt 2.4.x or higher. The mode should be either MCRYPT_ENCRYPT or MCRYPT_DECRYPT.
This function should not be used anymore, see mcrypt_generic() and mdecrypt_generic() for replacements.
mcrypt_create_iv
(PHP 4, PHP 5)
mcrypt_create_iv — Creates an initialization vector (IV) from a random source
Descrição
Creates an initialization vector (IV) from a random source.
The IV is only meant to give an alternative seed to the encryption routines. This IV does not need to be secret at all, though it can be desirable. You even can send it along with your ciphertext without losing security.
Parâmetros
- size
-
The size of the IV.
- source
-
The source of the IV. The source can be MCRYPT_RAND (system random number generator), MCRYPT_DEV_RANDOM (read data from /dev/random) and MCRYPT_DEV_URANDOM (read data from /dev/urandom). Prior to 5.3.0, MCRYPT_RAND was the only one supported on Windows.
Valor Retornado
Returns the initialization vector, or FALSE on error.
Histórico
| Versão | Descrição |
|---|---|
| 5.3.0 | MCRYPT_DEV_RANDOM and MCRYPT_DEV_URANDOM became available on Windows platforms. |
| 5.3.0 | It is no longer required to call srand() first. This is now done automatically. |
Exemplos
Exemplo #1 mcrypt_create_iv() Example
<?php
$size = mcrypt_get_iv_size(MCRYPT_CAST_256, MCRYPT_MODE_CFB);
$iv = mcrypt_create_iv($size, MCRYPT_DEV_RANDOM);
?>
Veja Também
- » http://www.ciphersbyritter.com/GLOSSARY.HTM#IV
- » http://www.quadibloc.com/crypto/co0409.htm
- Chapter 9.3 of Applied Cryptography by Schneier (ISBN 0-471-11709-9)
mcrypt_decrypt
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_decrypt — Decrypts crypttext with given parameters
Descrição
Decrypts the data and returns the unencrypted data.
Parâmetros
- cipher
-
One of the MCRYPT_ciphername constants, or the name of the algorithm as string.
- key
-
The key with which the data was encrypted. If it's smaller than the required keysize, it is padded with '\0'.
- data
-
The data that will be decrypted with the given cipher and mode. If the size of the data is not n * blocksize, the data will be padded with '\0'.
- mode
-
One of the MCRYPT_MODE_modename constants, or one of the following strings: "ecb", "cbc", "cfb", "ofb", "nofb" or "stream".
- iv
-
The iv parameter is used for the initialization in CBC, CFB, OFB modes, and in some algorithms in STREAM mode. If you do not supply an IV, while it is needed for an algorithm, the function issues a warning and uses an IV with all its bytes set to '\0'.
Valor Retornado
Returns the decrypted data as a string.
mcrypt_ecb
(PHP 4, PHP 5)
mcrypt_ecb — Deprecated: Encrypts/decrypts data in ECB mode
Descrição
The first prototype is when linked against libmcrypt 2.2.x, the second when linked against libmcrypt 2.4.x or higher. The mode should be either MCRYPT_ENCRYPT or MCRYPT_DECRYPT.
This function is deprecated and should not be used anymore, see mcrypt_generic() and mdecrypt_generic() for replacements.
mcrypt_enc_get_algorithms_name
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_enc_get_algorithms_name — Returns the name of the opened algorithm
Descrição
This function returns the name of the algorithm.
Parâmetros
- td
-
The encryption descriptor.
Valor Retornado
Returns the name of the opened algorithm as a string.
Exemplos
Exemplo #1 mcrypt_enc_get_algorithms_name() example
<?php
$td = mcrypt_module_open(MCRYPT_CAST_256, '', MCRYPT_MODE_CFB, '');
echo mcrypt_enc_get_algorithms_name($td). "\n";
$td = mcrypt_module_open('cast-256', '', MCRYPT_MODE_CFB, '');
echo mcrypt_enc_get_algorithms_name($td). "\n";
?>
O exemplo acima irá imprimir:
CAST-256 CAST-256
mcrypt_enc_get_block_size
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_enc_get_block_size — Returns the blocksize of the opened algorithm
Descrição
Gets the blocksize of the opened algorithm.
Parâmetros
- td
-
The encryption descriptor.
Valor Retornado
Returns the block size of the specified algorithm in bytes.
mcrypt_enc_get_iv_size
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_enc_get_iv_size — Returns the size of the IV of the opened algorithm
Descrição
This function returns the size of the IV of the algorithm specified by the encryption descriptor in bytes. An IV is used in cbc, cfb and ofb modes, and in some algorithms in stream mode.
Parâmetros
- td
-
The encryption descriptor.
Valor Retornado
Returns the size of the IV, or 0 if the IV is ignored by the algorithm.
mcrypt_enc_get_key_size
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_enc_get_key_size — Returns the maximum supported keysize of the opened mode
Descrição
Gets the maximum supported key size of the algorithm in bytes.
Parâmetros
- td
-
The encryption descriptor.
Valor Retornado
Returns the maximum supported key size of the algorithm in bytes.
mcrypt_enc_get_modes_name
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_enc_get_modes_name — Returns the name of the opened mode
Descrição
This function returns the name of the mode.
Parâmetros
- td
-
The encryption descriptor.
Valor Retornado
Returns the name as a string.
Exemplos
Exemplo #1 mcrypt_enc_get_modes_name() example
<?php
$td = mcrypt_module_open (MCRYPT_CAST_256, '', MCRYPT_MODE_CFB, '');
echo mcrypt_enc_get_modes_name($td). "\n";
$td = mcrypt_module_open ('cast-256', '', 'ecb', '');
echo mcrypt_enc_get_modes_name($td). "\n";
?>
O exemplo acima irá imprimir:
CFB ECB
mcrypt_enc_get_supported_key_sizes
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_enc_get_supported_key_sizes — Returns an array with the supported keysizes of the opened algorithm
Descrição
Gets the supported key sizes of the opened algorithm.
Parâmetros
- td
-
The encryption descriptor.
Valor Retornado
Returns an array with the key sizes supported by the algorithm specified by the encryption descriptor. If it returns an empty array then all key sizes between 1 and mcrypt_enc_get_key_size() are supported by the algorithm.
Exemplos
Exemplo #1 mcrypt_enc_get_supported_key_sizes() example
<?php
$td = mcrypt_module_open('rijndael-256', '', 'ecb', '');
var_dump(mcrypt_enc_get_supported_key_sizes($td));
?>
O exemplo acima irá imprimir:
array(3) {
[0]=>
int(16)
[1]=>
int(24)
[2]=>
int(32)
}
mcrypt_enc_is_block_algorithm_mode
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_enc_is_block_algorithm_mode — Checks whether the encryption of the opened mode works on blocks
Descrição
Tells whether the algorithm of the opened mode works on blocks (e.g. FALSE for stream, and TRUE for cbc, cfb, ofb)..
Parâmetros
- td
-
The encryption descriptor.
Valor Retornado
Returns TRUE if the mode is for use with block algorithms, otherwise it returns FALSE.
mcrypt_enc_is_block_algorithm
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_enc_is_block_algorithm — Checks whether the algorithm of the opened mode is a block algorithm
Descrição
Tells whether the algorithm of the opened mode is a block algorithm.
Parâmetros
- td
-
The encryption descriptor.
Valor Retornado
Returns TRUE if the algorithm is a block algorithm or FALSE if it is a stream one.
mcrypt_enc_is_block_mode
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_enc_is_block_mode — Checks whether the opened mode outputs blocks
Descrição
Tells whether the opened mode outputs blocks (e.g. TRUE for cbc and ecb, and FALSE for cfb and stream).
Parâmetros
- td
-
The encryption descriptor.
Valor Retornado
Returns TRUE if the mode outputs blocks of bytes, or FALSE if it outputs just bytes.
mcrypt_enc_self_test
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_enc_self_test — Runs a self test on the opened module
Descrição
This function runs the self test on the algorithm specified by the descriptor td.
Parâmetros
- td
-
The encryption descriptor.
Valor Retornado
If the self test succeeds it returns FALSE. In case of an error, it returns TRUE.
mcrypt_encrypt
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_encrypt — Encrypts plaintext with given parameters
Descrição
Encrypts the data and returns it.
Parâmetros
- cipher
-
One of the MCRYPT_ciphername constants, or the name of the algorithm as string.
- key
-
The key with which the data will be encrypted. If it's smaller than the required keysize, it is padded with '\0'. It is better not to use ASCII strings for keys.
It is recommended to use the mhash functions to create a key from a string.
- data
-
The data that will be encrypted with the given cipher and mode. If the size of the data is not n * blocksize, the data will be padded with '\0'.
The returned crypttext can be larger than the size of the data that was given by data.
- mode
-
One of the MCRYPT_MODE_modename constants, or one of the following strings: "ecb", "cbc", "cfb", "ofb", "nofb" or "stream".
- iv
-
Used for the initialization in CBC, CFB, OFB modes, and in some algorithms in STREAM mode. If you do not supply an IV, while it is needed for an algorithm, the function issues a warning and uses an IV with all its bytes set to '\0'.
Valor Retornado
Returns the encrypted data, as a string.
Exemplos
Exemplo #1 mcrypt_encrypt() Example
<?php
$iv_size = mcrypt_get_iv_size(MCRYPT_RIJNDAEL_256, MCRYPT_MODE_ECB);
$iv = mcrypt_create_iv($iv_size, MCRYPT_RAND);
$key = "This is a very secret key";
$text = "Meet me at 11 o'clock behind the monument.";
echo strlen($text) . "\n";
$crypttext = mcrypt_encrypt(MCRYPT_RIJNDAEL_256, $key, $text, MCRYPT_MODE_ECB, $iv);
echo strlen($crypttext) . "\n";
?>
O exemplo acima irá imprimir:
42 64
See also mcrypt_module_open() for a more advanced API and an example.
mcrypt_generic_deinit
(PHP 4 >= 4.0.7, PHP 5)
mcrypt_generic_deinit — This function deinitializes an encryption module
Descrição
This function terminates encryption specified by the encryption descriptor (td). It clears all buffers, but does not close the module. You need to call mcrypt_module_close() yourself. (But PHP does this for you at the end of the script.)
Parâmetros
- td
-
The encryption descriptor.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Veja Também
- mcrypt_module_open() - Opens the module of the algorithm and the mode to be used
- mcrypt_generic_init() - This function initializes all buffers needed for encryption
mcrypt_generic_end
(PHP 4 >= 4.0.2, PHP 5 <= 5.1.6)
mcrypt_generic_end — This function terminates encryption
Descrição
This function is deprecated, use mcrypt_generic_deinit() instead. It can cause crashes when used with mcrypt_module_close() due to multiple buffer frees.
This function terminates encryption specified by the encryption descriptor (td). Actually it clears all buffers, and closes all the modules used. Returns FALSE on error, or TRUE on success.
mcrypt_generic_init
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_generic_init — This function initializes all buffers needed for encryption
Descrição
You need to call this function before every call to mcrypt_generic() or mdecrypt_generic().
Parâmetros
- td
-
The encryption descriptor.
- key
-
The maximum length of the key should be the one obtained by calling mcrypt_enc_get_key_size() and every value smaller than this is legal.
- iv
-
The IV should normally have the size of the algorithms block size, but you must obtain the size by calling mcrypt_enc_get_iv_size(). IV is ignored in ECB. IV MUST exist in CFB, CBC, STREAM, nOFB and OFB modes. It needs to be random and unique (but not secret). The same IV must be used for encryption/decryption. If you do not want to use it you should set it to zeros, but this is not recommended.
Valor Retornado
The function returns a negative value on error: -3 when the key length was incorrect, -4 when there was a memory allocation problem and any other return value is an unknown error. If an error occurs a warning will be displayed accordingly. FALSE is returned if incorrect parameters were passed.
mcrypt_generic
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_generic — This function encrypts data
Descrição
This function encrypts data. The data is padded with "\0" to make sure the length of the data is n * blocksize. This function returns the encrypted data. Note that the length of the returned string can in fact be longer than the input, due to the padding of the data.
If you want to store the encrypted data in a database make sure to store the entire string as returned by mcrypt_generic, or the string will not entirely decrypt properly. If your original string is 10 characters long and the block size is 8 (use mcrypt_enc_get_block_size() to determine the blocksize), you would need at least 16 characters in your database field. Note the string returned by mdecrypt_generic() will be 16 characters as well...use rtrim($str, "\0") to remove the padding.
If you are for example storing the data in a MySQL database remember that varchar fields automatically have trailing spaces removed during insertion. As encrypted data can end in a space (ASCII 32), the data will be damaged by this removal. Store data in a tinyblob/tinytext (or larger) field instead.
Parâmetros
- td
-
The encryption descriptor.
The encryption handle should always be initialized with mcrypt_generic_init() with a key and an IV before calling this function. Where the encryption is done, you should free the encryption buffers by calling mcrypt_generic_deinit(). See mcrypt_module_open() for an example.
- data
-
The data to encrypt.
Valor Retornado
Returns the encrypted data.
Veja Também
- mdecrypt_generic() - Decrypts data
- mcrypt_generic_init() - This function initializes all buffers needed for encryption
- mcrypt_generic_deinit() - This function deinitializes an encryption module
mcrypt_get_block_size
(PHP 4, PHP 5)
mcrypt_get_block_size — Gets the block size of the specified cipher
Descrição
The first prototype is when linked against libmcrypt 2.2.x, the second when linked against libmcrypt 2.4.x or 2.5.x.
mcrypt_get_block_size() is used to get the size of a block of the specified cipher (in combination with an encryption mode).
It is more useful to use the mcrypt_enc_get_block_size() function as this uses the resource returned by mcrypt_module_open().
Parâmetros
- cipher
-
One of the MCRYPT_ciphername constants or the name of the algorithm as string.
- module
-
The module.
Valor Retornado
Gets the block size, as an integer.
Exemplos
Exemplo #1 mcrypt_get_block_size() example
This example shows how to use this function when linked against libmcrypt 2.4.x and 2.5.x.
<?php
echo mcrypt_get_block_size('tripledes', 'ecb'); // 8
?>
Veja Também
- mcrypt_get_key_size() - Gets the key size of the specified cipher
- mcrypt_enc_get_block_size() - Returns the blocksize of the opened algorithm
- mcrypt_encrypt() - Encrypts plaintext with given parameters
mcrypt_get_cipher_name
(PHP 4, PHP 5)
mcrypt_get_cipher_name — Gets the name of the specified cipher
Descrição
mcrypt_get_cipher_name() is used to get the name of the specified cipher.
mcrypt_get_cipher_name() takes the cipher number as an argument (libmcrypt 2.2.x) or takes the cipher name as an argument (libmcrypt 2.4.x or higher) and returns the name of the cipher or FALSE, if the cipher does not exist.
Parâmetros
- cipher
-
One of the MCRYPT_ciphername constants or the name of the algorithm as string.
Valor Retornado
This function returns the name of the cipher or FALSE, if the cipher does not exist.
Exemplos
Exemplo #1 mcrypt_get_cipher_name() Example
<?php
$cipher = MCRYPT_TripleDES;
echo mcrypt_get_cipher_name($cipher);
?>
O exemplo acima irá imprimir:
3DES
mcrypt_get_iv_size
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_get_iv_size — Returns the size of the IV belonging to a specific cipher/mode combination
Descrição
Gets the size of the IV belonging to a specific cipher/mode combination.
It is more useful to use the mcrypt_enc_get_iv_size() function as this uses the resource returned by mcrypt_module_open().
Parâmetros
- cipher
-
One of the MCRYPT_ciphername constants, or the name of the algorithm as string.
- mode
-
One of the MCRYPT_MODE_modename constants, or one of the following strings: "ecb", "cbc", "cfb", "ofb", "nofb" or "stream". The IV is ignored in ECB mode as this mode does not require it. You will need to have the same IV (think: starting point) both at encryption and decryption stages, otherwise your encryption will fail.
Valor Retornado
Returns the size of the Initialization Vector (IV) in bytes. On error the function returns FALSE. If the IV is ignored in the specified cipher/mode combination zero is returned.
Exemplos
Exemplo #1 mcrypt_get_iv_size() Example
<?php
echo mcrypt_get_iv_size(MCRYPT_CAST_256, MCRYPT_MODE_CFB) . "\n";
echo mcrypt_get_iv_size('des', 'ecb') . "\n";
?>
Veja Também
- mcrypt_get_block_size() - Gets the block size of the specified cipher
- mcrypt_enc_get_iv_size() - Returns the size of the IV of the opened algorithm
- mcrypt_create_iv() - Creates an initialization vector (IV) from a random source
mcrypt_get_key_size
(PHP 4, PHP 5)
mcrypt_get_key_size — Gets the key size of the specified cipher
Descrição
The first prototype is when linked against libmcrypt 2.2.x, the second when linked against libmcrypt 2.4.x or 2.5.x.
mcrypt_get_key_size() is used to get the size of a key of the specified cipher (in combination with an encryption mode).
It is more useful to use the mcrypt_enc_get_key_size() function as this uses the resource returned by mcrypt_module_open().
Exemplos
Exemplo #1 mcrypt_get_key_size() Example
<?php
echo mcrypt_get_key_size('tripledes', 'ecb');
?>
The example above shows how to use this function when linked against libmcrypt 2.4.x or 2.5.x.
O exemplo acima irá imprimir:
24
Veja Também
- mcrypt_get_block_size() - Gets the block size of the specified cipher
- mcrypt_enc_get_key_size() - Returns the maximum supported keysize of the opened mode
- mcrypt_encrypt() - Encrypts plaintext with given parameters
mcrypt_list_algorithms
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_list_algorithms — Gets an array of all supported ciphers
Descrição
Gets the list of all supported algorithms in the lib_dir parameter.
Parâmetros
- lib_dir
-
Specifies the directory where all algorithms are located. If not specified, the value of the mcrypt.algorithms_dir php.ini directive is used.
Valor Retornado
Returns an array with all the supported algorithms.
Exemplos
Exemplo #1 mcrypt_list_algorithms() Example
<?php
$algorithms = mcrypt_list_algorithms("/usr/local/lib/libmcrypt");
foreach ($algorithms as $cipher) {
echo "$cipher<br />\n";
}
?>
The example above will produce a list with all supported algorithms in the "/usr/local/lib/libmcrypt" directory.
mcrypt_list_modes
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_list_modes — Gets an array of all supported modes
Descrição
Gets the list of all supported modes in the lib_dir parameter.
Parâmetros
- lib_dir
-
Specifies the directory where all modes are located. If not specified, the value of the mcrypt.modes_dir php.ini directive is used.
Valor Retornado
Returns an array with all the supported modes.
Exemplos
Exemplo #1 mcrypt_list_modes() Example
<?php
$modes = mcrypt_list_modes();
foreach ($modes as $mode) {
echo "$mode <br />\n";
}
?>
The example above will produce a list with all supported algorithms in the default mode directory. If it is not set with the mcrypt.modes_dir php.ini directive, the default directory of mcrypt is used (which is /usr/local/lib/libmcrypt).
mcrypt_module_close
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_module_close — Closes the mcrypt module
Descrição
Closes the specified encryption handle.
Parâmetros
- td
-
The encryption descriptor.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
mcrypt_module_get_algo_block_size
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_module_get_algo_block_size — Returns the blocksize of the specified algorithm
Descrição
Gets the blocksize of the specified algorithm.
Parâmetros
- algorithm
-
The algorithm name.
- lib_dir
-
This optional parameter can contain the location where the mode module is on the system.
Valor Retornado
Returns the block size of the algorithm specified in bytes.
mcrypt_module_get_algo_key_size
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_module_get_algo_key_size — Returns the maximum supported keysize of the opened mode
Descrição
Gets the maximum supported keysize of the opened mode.
Parâmetros
- algorithm
-
The algorithm name.
- lib_dir
-
This optional parameter can contain the location where the mode module is on the system.
Valor Retornado
This function returns the maximum supported key size of the algorithm specified in bytes.
mcrypt_module_get_supported_key_sizes
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_module_get_supported_key_sizes — Returns an array with the supported keysizes of the opened algorithm
Descrição
Returns an array with the key sizes supported by the specified algorithm. If it returns an empty array then all key sizes between 1 and mcrypt_module_get_algo_key_size() are supported by the algorithm.
Parâmetros
- algorithm
-
The algorithm to be used.
- lib_dir
-
The optional lib_dir parameter can contain the location where the algorithm module is on the system.
Valor Retornado
Returns an array with the key sizes supported by the specified algorithm. If it returns an empty array then all key sizes between 1 and mcrypt_module_get_algo_key_size() are supported by the algorithm.
Veja Também
- mcrypt_enc_get_supported_key_sizes() - Returns an array with the supported keysizes of the opened algorithm
mcrypt_module_is_block_algorithm_mode
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_module_is_block_algorithm_mode — Returns if the specified module is a block algorithm or not
Descrição
This function returns TRUE if the mode is for use with block algorithms, otherwise it returns FALSE. (e.g. FALSE for stream, and TRUE for cbc, cfb, ofb).
Parâmetros
- mode
-
The mode to check.
- lib_dir
-
The optional lib_dir parameter can contain the location where the algorithm module is on the system.
Valor Retornado
This function returns TRUE if the mode is for use with block algorithms, otherwise it returns FALSE. (e.g. FALSE for stream, and TRUE for cbc, cfb, ofb).
mcrypt_module_is_block_algorithm
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_module_is_block_algorithm — This function checks whether the specified algorithm is a block algorithm
Descrição
This function returns TRUE if the specified algorithm is a block algorithm, or FALSE if it is a stream one.
Parâmetros
- algorithm
-
The algorithm to check.
- lib_dir
-
The optional lib_dir parameter can contain the location where the algorithm module is on the system.
Valor Retornado
This function returns TRUE if the specified algorithm is a block algorithm, or FALSE if it is a stream one.
mcrypt_module_is_block_mode
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_module_is_block_mode — Returns if the specified mode outputs blocks or not
Descrição
This function returns TRUE if the mode outputs blocks of bytes or FALSE if it outputs just bytes. (e.g. TRUE for cbc and ecb, and FALSE for cfb and stream).
Parâmetros
- mode
-
The mode to check.
- lib_dir
-
The optional lib_dir parameter can contain the location where the algorithm module is on the system.
Valor Retornado
This function returns TRUE if the mode outputs blocks of bytes or FALSE if it outputs just bytes. (e.g. TRUE for cbc and ecb, and FALSE for cfb and stream).
mcrypt_module_open
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_module_open — Opens the module of the algorithm and the mode to be used
Descrição
This function opens the module of the algorithm and the mode to be used. The name of the algorithm is specified in algorithm, e.g. "twofish" or is one of the MCRYPT_ciphername constants. The module is closed by calling mcrypt_module_close().
Parâmetros
- algorithm
-
The algorithm to be used.
- algorithm_directory
-
The algorithm_directory parameter is used to locate the encryption module. When you supply a directory name, it is used. When you set it to an empty string (""), the value set by the mcrypt.algorithms_dir php.ini directive is used. When it is not set, the default directory that is used is the one that was compiled into libmcrypt (usually /usr/local/lib/libmcrypt).
- mode
-
The mode to be used.
- mode_directory
-
The mode_directory parameter is used to locate the encryption module. When you supply a directory name, it is used. When you set it to an empty string (""), the value set by the mcrypt.modes_dir php.ini directive is used. When it is not set, the default directory that is used is the one that was compiled-in into libmcrypt (usually /usr/local/lib/libmcrypt).
Valor Retornado
Normally it returns an encryption descriptor, or FALSE on error.
Exemplos
Exemplo #1 mcrypt_module_open() Examples
<?php
$td = mcrypt_module_open(MCRYPT_DES, '',
MCRYPT_MODE_ECB, '/usr/lib/mcrypt-modes');
$td = mcrypt_module_open('rijndael-256', '', 'ofb', '');
?>
The first line in the example above will try to open the DES cipher from the default directory and the EBC mode from the directory /usr/lib/mcrypt-modes. The second example uses strings as name for the cipher and mode, this only works when the extension is linked against libmcrypt 2.4.x or 2.5.x.
Exemplo #2 Using mcrypt_module_open() in encryption
<?php
/* Open the cipher */
$td = mcrypt_module_open('rijndael-256', '', 'ofb', '');
/* Create the IV and determine the keysize length, use MCRYPT_RAND
* on Windows instead */
$iv = mcrypt_create_iv(mcrypt_enc_get_iv_size($td), MCRYPT_DEV_RANDOM);
$ks = mcrypt_enc_get_key_size($td);
/* Create key */
$key = substr(md5('very secret key'), 0, $ks);
/* Intialize encryption */
mcrypt_generic_init($td, $key, $iv);
/* Encrypt data */
$encrypted = mcrypt_generic($td, 'This is very important data');
/* Terminate encryption handler */
mcrypt_generic_deinit($td);
/* Initialize encryption module for decryption */
mcrypt_generic_init($td, $key, $iv);
/* Decrypt encrypted string */
$decrypted = mdecrypt_generic($td, $encrypted);
/* Terminate decryption handle and close module */
mcrypt_generic_deinit($td);
mcrypt_module_close($td);
/* Show string */
echo trim($decrypted) . "\n";
?>
Veja Também
- mcrypt_module_close() - Closes the mcrypt module
- mcrypt_generic() - This function encrypts data
- mdecrypt_generic() - Decrypts data
- mcrypt_generic_init() - This function initializes all buffers needed for encryption
- mcrypt_generic_deinit() - This function deinitializes an encryption module
mcrypt_module_self_test
(PHP 4 >= 4.0.2, PHP 5)
mcrypt_module_self_test — This function runs a self test on the specified module
Descrição
This function runs the self test on the algorithm specified.
Parâmetros
- algorithm
-
The algorithm to test.
- lib_dir
-
The optional lib_dir parameter can contain the location where the algorithm module is on the system.
Valor Retornado
The function returns TRUE if the self test succeeds, or FALSE when it fails.
Exemplos
Exemplo #1 mcrypt_module_self_test() example
<?php
var_dump(mcrypt_module_self_test(MCRYPT_RIJNDAEL_128)) . "\n";
var_dump(mcrypt_module_self_test(MCRYPT_BOGUS_CYPHER));
?>
O exemplo acima irá imprimir:
bool(true) bool(false)
mcrypt_ofb
(PHP 4, PHP 5)
mcrypt_ofb — Encrypts/decrypts data in OFB mode
Descrição
The first prototype is when linked against libmcrypt 2.2.x, the second when linked against libmcrypt 2.4.x or higher. The mode should be either MCRYPT_ENCRYPT or MCRYPT_DECRYPT.
This function should not be used anymore, see mcrypt_generic() and mdecrypt_generic() for replacements.
mdecrypt_generic
(PHP 4 >= 4.0.2, PHP 5)
mdecrypt_generic — Decrypts data
Descrição
This function decrypts data. Note that the length of the returned string can in fact be longer than the unencrypted string, due to the padding of the data.
Exemplos
Exemplo #1 mdecrypt_generic() Example
<?php
/* Data */
$key = 'this is a very long key, even too long for the cipher';
$plain_text = 'very important data';
/* Open module, and create IV */
$td = mcrypt_module_open('des', '', 'ecb', '');
$key = substr($key, 0, mcrypt_enc_get_key_size($td));
$iv_size = mcrypt_enc_get_iv_size($td);
$iv = mcrypt_create_iv($iv_size, MCRYPT_RAND);
/* Initialize encryption handle */
if (mcrypt_generic_init($td, $key, $iv) != -1) {
/* Encrypt data */
$c_t = mcrypt_generic($td, $plain_text);
mcrypt_generic_deinit($td);
/* Reinitialize buffers for decryption */
mcrypt_generic_init($td, $key, $iv);
$p_t = mdecrypt_generic($td, $c_t);
/* Clean up */
mcrypt_generic_deinit($td);
mcrypt_module_close($td);
}
if (strncmp($p_t, $plain_text, strlen($plain_text)) == 0) {
echo "ok\n";
} else {
echo "error\n";
}
?>
The example above shows how to check if the data before the encryption is the same as the data after the decryption. It is very important to reinitialize the encryption buffer with mcrypt_generic_init() before you try to decrypt the data.
The decryption handle should always be initialized with mcrypt_generic_init() with a key and an IV before calling this function. Where the encryption is done, you should free the encryption buffers by calling mcrypt_generic_deinit(). See mcrypt_module_open() for an example.
Veja Também
- mcrypt_generic() - This function encrypts data
- mcrypt_generic_init() - This function initializes all buffers needed for encryption
- mcrypt_generic_deinit() - This function deinitializes an encryption module
Índice
- mcrypt_cbc — Encrypts/decrypts data in CBC mode
- mcrypt_cfb — Encrypts/decrypts data in CFB mode
- mcrypt_create_iv — Creates an initialization vector (IV) from a random source
- mcrypt_decrypt — Decrypts crypttext with given parameters
- mcrypt_ecb — Deprecated: Encrypts/decrypts data in ECB mode
- mcrypt_enc_get_algorithms_name — Returns the name of the opened algorithm
- mcrypt_enc_get_block_size — Returns the blocksize of the opened algorithm
- mcrypt_enc_get_iv_size — Returns the size of the IV of the opened algorithm
- mcrypt_enc_get_key_size — Returns the maximum supported keysize of the opened mode
- mcrypt_enc_get_modes_name — Returns the name of the opened mode
- mcrypt_enc_get_supported_key_sizes — Returns an array with the supported keysizes of the opened algorithm
- mcrypt_enc_is_block_algorithm_mode — Checks whether the encryption of the opened mode works on blocks
- mcrypt_enc_is_block_algorithm — Checks whether the algorithm of the opened mode is a block algorithm
- mcrypt_enc_is_block_mode — Checks whether the opened mode outputs blocks
- mcrypt_enc_self_test — Runs a self test on the opened module
- mcrypt_encrypt — Encrypts plaintext with given parameters
- mcrypt_generic_deinit — This function deinitializes an encryption module
- mcrypt_generic_end — This function terminates encryption
- mcrypt_generic_init — This function initializes all buffers needed for encryption
- mcrypt_generic — This function encrypts data
- mcrypt_get_block_size — Gets the block size of the specified cipher
- mcrypt_get_cipher_name — Gets the name of the specified cipher
- mcrypt_get_iv_size — Returns the size of the IV belonging to a specific cipher/mode combination
- mcrypt_get_key_size — Gets the key size of the specified cipher
- mcrypt_list_algorithms — Gets an array of all supported ciphers
- mcrypt_list_modes — Gets an array of all supported modes
- mcrypt_module_close — Closes the mcrypt module
- mcrypt_module_get_algo_block_size — Returns the blocksize of the specified algorithm
- mcrypt_module_get_algo_key_size — Returns the maximum supported keysize of the opened mode
- mcrypt_module_get_supported_key_sizes — Returns an array with the supported keysizes of the opened algorithm
- mcrypt_module_is_block_algorithm_mode — Returns if the specified module is a block algorithm or not
- mcrypt_module_is_block_algorithm — This function checks whether the specified algorithm is a block algorithm
- mcrypt_module_is_block_mode — Returns if the specified mode outputs blocks or not
- mcrypt_module_open — Opens the module of the algorithm and the mode to be used
- mcrypt_module_self_test — This function runs a self test on the specified module
- mcrypt_ofb — Encrypts/decrypts data in OFB mode
- mdecrypt_generic — Decrypts data
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Mcrypt ciphers
- Exemplos
- Mcrypt Funções
- mcrypt_cbc — Encrypts/decrypts data in CBC mode
- mcrypt_cfb — Encrypts/decrypts data in CFB mode
- mcrypt_create_iv — Creates an initialization vector (IV) from a random source
- mcrypt_decrypt — Decrypts crypttext with given parameters
- mcrypt_ecb — Deprecated: Encrypts/decrypts data in ECB mode
- mcrypt_enc_get_algorithms_name — Returns the name of the opened algorithm
- mcrypt_enc_get_block_size — Returns the blocksize of the opened algorithm
- mcrypt_enc_get_iv_size — Returns the size of the IV of the opened algorithm
- mcrypt_enc_get_key_size — Returns the maximum supported keysize of the opened mode
- mcrypt_enc_get_modes_name — Returns the name of the opened mode
- mcrypt_enc_get_supported_key_sizes — Returns an array with the supported keysizes of the opened algorithm
- mcrypt_enc_is_block_algorithm_mode — Checks whether the encryption of the opened mode works on blocks
- mcrypt_enc_is_block_algorithm — Checks whether the algorithm of the opened mode is a block algorithm
- mcrypt_enc_is_block_mode — Checks whether the opened mode outputs blocks
- mcrypt_enc_self_test — Runs a self test on the opened module
- mcrypt_encrypt — Encrypts plaintext with given parameters
- mcrypt_generic_deinit — This function deinitializes an encryption module
- mcrypt_generic_end — This function terminates encryption
- mcrypt_generic_init — This function initializes all buffers needed for encryption
- mcrypt_generic — This function encrypts data
- mcrypt_get_block_size — Gets the block size of the specified cipher
- mcrypt_get_cipher_name — Gets the name of the specified cipher
- mcrypt_get_iv_size — Returns the size of the IV belonging to a specific cipher/mode combination
- mcrypt_get_key_size — Gets the key size of the specified cipher
- mcrypt_list_algorithms — Gets an array of all supported ciphers
- mcrypt_list_modes — Gets an array of all supported modes
- mcrypt_module_close — Closes the mcrypt module
- mcrypt_module_get_algo_block_size — Returns the blocksize of the specified algorithm
- mcrypt_module_get_algo_key_size — Returns the maximum supported keysize of the opened mode
- mcrypt_module_get_supported_key_sizes — Returns an array with the supported keysizes of the opened algorithm
- mcrypt_module_is_block_algorithm_mode — Returns if the specified module is a block algorithm or not
- mcrypt_module_is_block_algorithm — This function checks whether the specified algorithm is a block algorithm
- mcrypt_module_is_block_mode — Returns if the specified mode outputs blocks or not
- mcrypt_module_open — Opens the module of the algorithm and the mode to be used
- mcrypt_module_self_test — This function runs a self test on the specified module
- mcrypt_ofb — Encrypts/decrypts data in OFB mode
- mdecrypt_generic — Decrypts data
Mhash
Introdução
Essas funções são planejadas para trabalhar com » mhash. Com o Mhash você pode criar checksums, digests de mensagens, códigos de autenticação de mensagens e mais.
Esta é uma interface para a biblioteca mhash. O mhash suporta uma grande variedade de algoritmos de hash como MD5, SHA1, GOST e muitos outros. Para uma lista completa das hashs suportadas, verifique a documentação do mhash. A regra geral é: você pode acessar o algoritmo de hash a partir do PHP com MHASH_NOMEdoHASH, Por exemplo, para acessar o algoritmo TIGER, você utiliza a constante MHASH_TIGER.
Nota:
Esta extensão está obsoleta por Hash.
Instalação/Configuração
Índice
Dependências
Para usá-las, faça o download da distribuição do mhash em » http://mhash.sourceforge.net/ e siga as instruções de instalação inclusas.
Instalação
You need to compile PHP with the --with-mhash[=DIR] parameter to enable this extension. DIR is the mhash installation directory.
As of PHP 5.3.0, the mhash extension is emulated thru the Hash extension. This makes the mhash installation directory have no effect, and requires the hash extension enabled to make the mhash support available.
Configurações em Execução
Esta extensão não define nenhum parâmetro de configuração no php.ini.
Tipos Resource
Esta extensão não possui nenhum tipo resource.
Constantes pré-definidas
As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.
Aqui está a lista de hashes que são atualmente suportadas por mhash. Se uma hash não está listada aqui, mas é listada pelo mhash como suportada, você pode assumir seguramente que esta documentação está desatualizada.
- MHASH_ADLER32
- MHASH_CRC32
- MHASH_CRC32B
- MHASH_GOST
- MHASH_HAVAL128
- MHASH_HAVAL160
- MHASH_HAVAL192
- MHASH_HAVAL256
- MHASH_MD4
- MHASH_MD5
- MHASH_RIPEMD160
- MHASH_SHA1
- MHASH_SHA256
- MHASH_TIGER
- MHASH_TIGER128
- MHASH_TIGER160
Exemplos
Exemplo #1 Calcula o MD5 digest e hmac e imprimi como hex
<?php
$input = "what do ya want for nothing?";
$hash = mhash(MHASH_MD5, $input);
echo "The hash is " . bin2hex($hash) . "<br />\n";
$hash = mhash(MHASH_MD5, $input, "Jefe");
echo "The hmac is " . bin2hex($hash) . "<br />\n";
?>
Irá mostrar:
The hash is d03cb659cbf9192dcd066272249f8412 The hmac is 750c783e6ab0b503eaa86e310a5db738
Funções da Mhash
mhash_count
(PHP 4, PHP 5)
mhash_count — Ler o mais alto hash id disponível
Descrição
Obtém a mais alta hash id disponível.
Valor Retornado
Retorna a mais alta hash id. Hashes são numerados de 0 a este hash id.
Exemplos
Exemplo #1 Listando todas as hashes
<?php
$nr = mhash_count();
for ($i = 0; $i <= $nr; $i++) {
echo sprintf("O tamanho do bloco de %s é %d\n",
mhash_get_hash_name ($i),
mhash_get_block_size ($i));
}
?>
mhash_get_block_size
(PHP 4, PHP 5)
mhash_get_block_size — Ler o tamanho do bloco da hash específicada
Descrição
Obtém o tamanho de um bloco da hash especificada.
Parâmetros
- hash
-
O hash id. Uma das constantes MHASH_XXX.
Valor Retornado
Retorna o tamanho em bytes ou FALSE, se o hash não existe.
Exemplos
Exemplo #1 mhash_get_block_size() Example
<?php
echo mhash_get_block_size(MHASH_MD5); // 16
?>
mhash_get_hash_name
(PHP 4, PHP 5)
mhash_get_hash_name — Ler o nome da hash especificada
Descrição
Obtém o nome da especificada hash.
Parâmetros
- hash
-
O hash id. Uma das constantes MHASH_XXX.
Valor Retornado
Retorna o nome da hash ou FALSE, se a hash não existe.
Exemplos
Exemplo #1 Exemplo do mhash_get_hash_name()
<?php
echo mhash_get_hash_name(MHASH_MD5);
?>
mhash_keygen_s2k
(PHP 4 >= 4.0.4, PHP 5)
mhash_keygen_s2k — Gerar uma chave
Descrição
Gera um chave de acordo com hash apartir de uma password (senha) do usuário.
Este é o algoritmo Salted S2K como especificado no documento OpenPGP (» RFC 2440).
Tenha em mente que as senhas fornecidas pelos usuários não são boas para serem usadas como chaves em algoritmos criptográficos, pois usuários normalmente escolhem chaves que eles podem escrever no teclado. Estas senhas usam somente 6 a 7 bits por caracter (ou menos). É altamente recomendado usar algum tipo de transformação (como esta função) na chave dada pelo usuário.
Parâmetros
- hash
-
O hash id usado para criar uma chave. Um das constantes MHASH_XXX.
- password
-
A senha fornecida do usuário.
- salt
-
Deve ser diferente e aleatório o suficiente para que cada chave que você gere seja diferente. Este salt tem que ser sabido quando você checar as suas chaves (keys), logo é uma boa ideia que a chave siga o salt. O salt tem o comprimento fixo de 8 bytes e será completado com zeros se voce fornecer menos bytes.
- bytes
-
O tamanho da chave, em bytes.
Valor Retornado
Retorna a chave gerada como uma string, ou FALSE em erro.
mhash
(PHP 4, PHP 5)
mhash — Computa a hash
Descrição
mhash() aplica a função hash especificada por hash para o parâmetro data.
Parâmetros
- hash
-
O hash id. Uma das constantes MHASH_XXX.
- data
-
A entrada do usuário, como uma string.
- key
-
Se especificada, a função irá retornar o HMAC resultante. HMAC é o hashing com chave (keyed) para autenticações de mensagens, ou simplesmente um digest de mensagens que depende na chave específicada. Nem todos os algoritmos suportados em mhash podem ser usados em modo HMAC.
Valor Retornado
Retorna o hash resultante (também chamado digest) ou HMAC como uma string, ou FALSE em erros.
Índice
- mhash_count — Ler o mais alto hash id disponível
- mhash_get_block_size — Ler o tamanho do bloco da hash específicada
- mhash_get_hash_name — Ler o nome da hash especificada
- mhash_keygen_s2k — Gerar uma chave
- mhash — Computa a hash
- Introdução
- Instalação/Configuração
- Constantes pré-definidas
- Exemplos
- Funções da Mhash
- mhash_count — Ler o mais alto hash id disponível
- mhash_get_block_size — Ler o tamanho do bloco da hash específicada
- mhash_get_hash_name — Ler o nome da hash especificada
- mhash_keygen_s2k — Gerar uma chave
- mhash — Computa a hash
OpenSSL
Introdução
This module uses the functions of » OpenSSL for generation and verification of signatures and for sealing (encrypting) and opening (decrypting) data. OpenSSL offers many features that this module currently doesn't support. Some of these may be added in the future.
Instalação/Configuração
Índice
Dependências
In order to use the OpenSSL functions you need to install the » OpenSSL package. PHP between versions 4.0.5 and 4.3.1 will work with OpenSSL >= 0.9.5. Other versions (PHP <=4.0.4 and >= 4.3.2) require OpenSSL >= 0.9.6.
You are strongly encouraged to use the most recent OpenSSL version, otherwise your web server could be vulnerable to attack.
Instalação
To use PHP's OpenSSL support you must also compile PHP --with-openssl[=DIR] .
The OpenSSL library also has additional requirements for normal operation at run-time. Most notably, OpenSSL requires access to a random or pseudo-random number generator; on most Unix and Unix-like platforms (including Linux), this means that it must have access to a /dev/urandom or /dev/random device.
Nota: Note to Win32 Users
Para esta extensão funcionar, existem arquivos DLL que devem estar disponíveis no PATH do sistema Windows. Para saber como fazer isso, veja o FAQ intitulado "Como eu adiciono o meu diretório PHP no PATH no Windows". Embora copiando arquivos DLL da pasta do PHP no diretório system do Windows também funcione (porque o diretório system está por padrão no PATH do sistema), isto não é recomendado. Esta extensão requer que os seguintes arquivos estejam no PATH: libeay32.dll
Additionally, if you are planning to use the key generation and certificate signing functions, you will need to install a valid openssl.cnf file on your system. As of PHP 4.3.0, we include a sample configuration file in our win32 binary distributions. PHP 4.3.x and 4.4.x has the file in the openssl directory. PHP 5.x and 6.x has the file in the extras/openssl directory. If you are either using PHP 4.2.x or missing the file, you can obtain it from » the OpenSSL binaries page or by downloading a recent PHP release. Be aware that Windows Explorer hides the .cnf extension by default and says the file Type is SpeedDial.
PHP will search for the openssl.cnf using the following logic:
In your installation, you need to decide whether to install the configuration file at c:\usr\local\ssl\openssl.cnf or whether to install it someplace else and use environmental variables (possibly on a per-virtual-host basis) to locate the configuration file. Note that it is possible to override the default path from the script using the configargs of the functions that require a configuration file.
- the OPENSSL_CONF environmental variable, if set, will be used as the path (including filename) of the configuration file.
- the SSLEAY_CONF environmental variable, if set, will be used as the path (including filename) of the configuration file.
- The file openssl.cnf will be assumed to be found in the default certificate area, as configured at the time that the openssl DLL was compiled. This is usually means that the default filename is c:\usr\local\ssl\openssl.cnf.
Configurações em Execução
Esta extensão não define nenhum parâmetro de configuração no php.ini.
Tipos Resource
Esta extensão não possui nenhum tipo resource.
Constantes pré-definidas
Índice
- Purpose checking flags
- Padding flags for asymmetric encryption
- Key types
- PKCS7 Flags/Constants
- Signature Algorithms
- Ciphers
- Version constants
- Server Name Indication constants
As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.
Purpose checking flags
Padding flags for asymmetric encryption
PKCS7 Flags/Constants
The S/MIME functions make use of flags which are specified using a bitfield which can include one or more of the following values:
| Constant | Description |
|---|---|
| PKCS7_TEXT | Adds text/plain content type headers to encrypted/signed message. If decrypting or verifying, it strips those headers from the output - if the decrypted or verified message is not of MIME type text/plain then an error will occur. |
| PKCS7_BINARY | Normally the input message is converted to "canonical" format which is effectively using CR and LF as end of line: as required by the S/MIME specification. When this option is present, no translation occurs. This is useful when handling binary data which may not be in MIME format. |
| PKCS7_NOINTERN | When verifying a message, certificates (if any) included in the message are normally searched for the signing certificate. With this option only the certificates specified in the extracerts parameter of openssl_pkcs7_verify() are used. The supplied certificates can still be used as untrusted CAs however. |
| PKCS7_NOVERIFY | Do not verify the signers certificate of a signed message. |
| PKCS7_NOCHAIN | Do not chain verification of signers certificates: that is don't use the certificates in the signed message as untrusted CAs. |
| PKCS7_NOCERTS | When signing a message the signer's certificate is normally included - with this option it is excluded. This will reduce the size of the signed message but the verifier must have a copy of the signers certificate available locally (passed using the extracerts to openssl_pkcs7_verify() for example). |
| PKCS7_NOATTR | Normally when a message is signed, a set of attributes are included which include the signing time and the supported symmetric algorithms. With this option they are not included. |
| PKCS7_DETACHED | When signing a message, use cleartext signing with the MIME type "multipart/signed". This is the default if you do not specify any flags to openssl_pkcs7_sign(). If you turn this option off, the message will be signed using opaque signing, which is more resistant to translation by mail relays but cannot be read by mail agents that do not support S/MIME. |
| PKCS7_NOSIGS | Don't try and verify the signatures on a message |
Nota:
These constants were added in 4.0.6.
Signature Algorithms
- OPENSSL_ALGO_DSS1 (integer)
- OPENSSL_ALGO_SHA1 (integer)
- Used as default algorithm by openssl_sign() and openssl_verify().
- OPENSSL_ALGO_MD5 (integer)
- OPENSSL_ALGO_MD4 (integer)
- OPENSSL_ALGO_MD2 (integer)
Nota:
These constants were added in 5.0.0.
Ciphers
- OPENSSL_CIPHER_RC2_40 (integer)
- OPENSSL_CIPHER_RC2_128 (integer)
- OPENSSL_CIPHER_RC2_64 (integer)
- OPENSSL_CIPHER_DES (integer)
- OPENSSL_CIPHER_3DES (integer)
Nota:
These constants were added in 4.3.0.
- OPENSSL_CIPHER_AES_128_CBC (integer)
- OPENSSL_CIPHER_AES_192_CBC (integer)
- OPENSSL_CIPHER_AES_256_CBC (integer)
Nota:
These constants were added in 5.4.0.
Version constants
Nota:
These constants were added in 5.2.0.
Server Name Indication constants
- OPENSSL_TLSEXT_SERVER_NAME (string)
- Whether SNI support is available or not.
Nota:
This constant were added in 5.3.2 and requires PHP to be built with OpenSSL 0.9.8j or greater.
Key/Certificate parameters
Quite a few of the openssl functions require a key or a certificate parameter. PHP 4.0.5 and earlier have to use a key or certificate resource returned by one of the openssl_get_xxx() functions. Later versions may use one of the following methods:
-
Certificates
- An X.509 resource returned from openssl_x509_read()
- A string having the format file://path/to/cert.pem; the named file must contain a PEM encoded certificate
- A string containing the content of a certificate, PEM encoded
-
Public/Private Keys
- A key resource returned from openssl_get_publickey() or openssl_get_privatekey()
- For public keys only: an X.509 resource
- A string having the format file://path/to/file.pem - the named file must contain a PEM encoded certificate/private key (it may contain both)
- A string containing the content of a certificate/key, PEM encoded
- For private keys, you may also use the syntax array($key, $passphrase) where $key represents a key specified using the file:// or textual content notation above, and $passphrase represents a string containing the passphrase for that private key
Certificate Verification
When calling a function that will verify a signature/certificate, the cainfo parameter is an array containing file and directory names that specify the locations of trusted CA files. If a directory is specified, then it must be a correctly formed hashed directory as the openssl command would use.
OpenSSL Funções
openssl_cipher_iv_length
(PHP 5 >= PHP 5.3.3)
openssl_cipher_iv_length — Gets the cipher iv length
Descrição
Gets the cipher iv length.
Parâmetros
- method
-
The method.
Valor Retornado
Returns the cipher length on success, or FALSE on failure.
Erros
Emits an E_WARNING level error when the cipher algorithm is unknown.
Exemplos
Exemplo #1 openssl_cipher_iv_length() example
<?php
$method = 'AES-128-CBC';
$ivlen = openssl_cipher_iv_length($method);
echo $ivlen;
?>
O exemplo acima irá imprimir algo similar a:
16
openssl_csr_export_to_file
(PHP 4 >= 4.2.0, PHP 5)
openssl_csr_export_to_file — Exports a CSR to a file
Descrição
openssl_csr_export_to_file() takes the Certificate Signing Request represented by csr and saves it as ascii-armoured text into the file named by outfilename.
Parâmetros
- csr
-
- outfilename
-
Path to the output file.
- notext
-
O parâmetro opcional notext afeta a exibição da saída; se ele é FALSE então informação legível para humano é incluida na saída. O valor padrão do notext é TRUE.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Veja Também
- openssl_csr_export() - Exports a CSR as a string
- openssl_csr_new() - Generates a CSR
- openssl_csr_sign() - Sign a CSR with another certificate (or itself) and generate a certificate
openssl_csr_export
(PHP 4 >= 4.2.0, PHP 5)
openssl_csr_export — Exports a CSR as a string
Descrição
openssl_csr_export() takes the Certificate Signing Request represented by csr and stores it as ascii-armoured text into out, which is passed by reference.
Parâmetros
- csr
-
- out
-
- notext
-
O parâmetro opcional notext afeta a exibição da saída; se ele é FALSE então informação legível para humano é incluida na saída. O valor padrão do notext é TRUE.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Veja Também
- openssl_csr_export_to_file() - Exports a CSR to a file
- openssl_csr_new() - Generates a CSR
- openssl_csr_sign() - Sign a CSR with another certificate (or itself) and generate a certificate
openssl_csr_get_public_key
(PHP 5 >= 5.2.0)
openssl_csr_get_public_key — Returns the public key of a CERT
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
openssl_csr_get_subject
(PHP 5 >= 5.2.0)
openssl_csr_get_subject — Returns the subject of a CERT
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
openssl_csr_new
(PHP 4 >= 4.2.0, PHP 5)
openssl_csr_new — Generates a CSR
Descrição
openssl_csr_new() generates a new CSR (Certificate Signing Request) based on the information provided by dn, which represents the Distinguished Name to be used in the certificate.
Nota: Você precisa ter um válido openssl.cnf instalado para esta função operar corretamente. Veja as notas sobre a seção de instalação para mais informação.
Parâmetros
- dn
-
The Distinguished Name to be used in the certificate.
- privkey
-
privkey should be set to a private key that was previously generated by openssl_pkey_new() (or otherwise obtained from the other openssl_pkey family of functions). The corresponding public portion of the key will be used to sign the CSR.
- configargs
-
By default, the information in your system openssl.conf is used to initialize the request; you can specify a configuration file section by setting the config_section_section key of configargs. You can also specify an alternative openssl configuration file by setting the value of the config key to the path of the file you want to use. The following keys, if present in configargs behave as their equivalents in the openssl.conf, as listed in the table below.
Configuration overrides configargs key type openssl.conf equivalent description digest_alg string default_md Selects which digest method to use x509_extensions string x509_extensions Selects which extensions should be used when creating an x509 certificate req_extensions string req_extensions Selects which extensions should be used when creating a CSR private_key_bits integer default_bits Specifies how many bits should be used to generate a private key private_key_type integer none Specifies the type of private key to create. This can be one of OPENSSL_KEYTYPE_DSA, OPENSSL_KEYTYPE_DH or OPENSSL_KEYTYPE_RSA. The default value is OPENSSL_KEYTYPE_RSA which is currently the only supported key type. encrypt_key boolean encrypt_key Should an exported key (with passphrase) be encrypted? encrypt_key_cipher integer none One of cipher constants. - extraattribs
-
extraattribs is used to specify additional configuration options for the CSR. Both dn and extraattribs are associative arrays whose keys are converted to OIDs and applied to the relevant part of the request.
Valor Retornado
Returns the CSR.
Exemplos
Exemplo #1 Creating a self-signed-certificate
<?php
// Fill in data for the distinguished name to be used in the cert
// You must change the values of these keys to match your name and
// company, or more precisely, the name and company of the person/site
// that you are generating the certificate for.
// For SSL certificates, the commonName is usually the domain name of
// that will be using the certificate, but for S/MIME certificates,
// the commonName will be the name of the individual who will use the
// certificate.
$dn = array(
"countryName" => "UK",
"stateOrProvinceName" => "Somerset",
"localityName" => "Glastonbury",
"organizationName" => "The Brain Room Limited",
"organizationalUnitName" => "PHP Documentation Team",
"commonName" => "Wez Furlong",
"emailAddress" => "wez@example.com"
);
// Generate a new private (and public) key pair
$privkey = openssl_pkey_new();
// Generate a certificate signing request
$csr = openssl_csr_new($dn, $privkey);
// You will usually want to create a self-signed certificate at this
// point until your CA fulfills your request.
// This creates a self-signed cert that is valid for 365 days
$sscert = openssl_csr_sign($csr, null, $privkey, 365);
// Now you will want to preserve your private key, CSR and self-signed
// cert so that they can be installed into your web server, mail server
// or mail client (depending on the intended use of the certificate).
// This example shows how to get those things into variables, but you
// can also store them directly into files.
// Typically, you will send the CSR on to your CA who will then issue
// you with the "real" certificate.
openssl_csr_export($csr, $csrout) and var_dump($csrout);
openssl_x509_export($sscert, $certout) and var_dump($certout);
openssl_pkey_export($privkey, $pkeyout, "mypassword") and var_dump($pkeyout);
// Show any errors that occurred here
while (($e = openssl_error_string()) !== false) {
echo $e . "\n";
}
?>
openssl_csr_sign
(PHP 4 >= 4.2.0, PHP 5)
openssl_csr_sign — Sign a CSR with another certificate (or itself) and generate a certificate
Descrição
openssl_csr_sign() generates an x509 certificate resource from the given CSR.
Nota: Você precisa ter um válido openssl.cnf instalado para esta função operar corretamente. Veja as notas sobre a seção de instalação para mais informação.
Parâmetros
- csr
-
A CSR previously generated by openssl_csr_new(). It can also be the path to a PEM encoded CSR when specified as file://path/to/csr or an exported string generated by openssl_csr_export().
- cacert
-
The generated certificate will be signed by cacert. If cacert is NULL, the generated certificate will be a self-signed certificate.
- priv_key
-
priv_key is the private key that corresponds to cacert.
- days
-
days specifies the length of time for which the generated certificate will be valid, in days.
- configargs
-
You can finetune the CSR signing by configargs. See openssl_csr_new() for more information about configargs.
- serial
-
An optional the serial number of issued certificate. If not specified it will default to 0.
Valor Retornado
Returns an x509 certificate resource on success, FALSE on failure.
Histórico
| Versão | Descrição |
|---|---|
| 4.3.3 | The serial parameter was added. |
Exemplos
Exemplo #1 openssl_csr_sign() example - signing a CSR (how to implement your own CA)
<?php
// Let's assume that this script is set to receive a CSR that has
// been pasted into a textarea from another page
$csrdata = $_POST["CSR"];
// We will sign the request using our own "certificate authority"
// certificate. You can use any certificate to sign another, but
// the process is worthless unless the signing certificate is trusted
// by the software/users that will deal with the newly signed certificate
// We need our CA cert and its private key
$cacert = "file://path/to/ca.crt";
$privkey = array("file://path/to/ca.key", "your_ca_key_passphrase");
$usercert = openssl_csr_sign($csrdata, $cacert, $privkey, 365);
// Now display the generated certificate so that the user can
// copy and paste it into their local configuration (such as a file
// to hold the certificate for their SSL server)
openssl_x509_export($usercert, $certout);
echo $certout;
// Show any errors that occurred here
while (($e = openssl_error_string()) !== false) {
echo $e . "\n";
}
?>
openssl_decrypt
(PHP 5 >= 5.3.0)
openssl_decrypt — Decrypts data
Descrição
Takes a raw or base64 encoded string and decrypts it using a given method and key.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- data
-
The data.
- method
-
The cipher method.
- password
-
The password.
- raw_input
-
Setting to TRUE will take a raw encoded string, otherwise a base64 string is assumed for the data parameter.
- iv
-
A non-NULL Initialization Vector.
Valor Retornado
The decrypted string on success or FALSE on failure.
Erros
Emits an E_WARNING level error if an unknown cipher algorithm is passed via the method parameter.
Emits an E_WARNING level error if an empty value is passed in via the iv parameter.
Histórico
| Versão | Descrição |
|---|---|
| 5.3.3 | The iv parameter was added. |
openssl_dh_compute_key
(No version information available, might only be in SVN)
openssl_dh_compute_key — Computes shared secret for public value of remote DH key and local DH key
Descrição
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- pub_key
-
Public key
- dh_key
-
DH key
Valor Retornado
Returns computed key on success or FALSE on failure.
openssl_digest
(PHP 5 >= 5.3.0)
openssl_digest — Computes a digest
Descrição
Computes a digest hash value for the given data using a given method, and returns a raw or binhex encoded string.
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- data
-
The data.
- method
-
The digest method.
- raw_output
-
Setting to TRUE will return as raw output data, otherwise the return value is binhex encoded.
Valor Retornado
Returns the digested hash value on success or FALSE on failure.
Erros
Emits an E_WARNING level error if an unknown signature algorithm is passed via the method parameter.
openssl_encrypt
(PHP 5 >= 5.3.0)
openssl_encrypt — Encrypts data
Descrição
Encrypts given data with given method and key, returns a raw or base64 encoded string
Esta função não está documentada; somente a lista de argumentos está disponível.
Parâmetros
- data
-
The data.
- method
-
The cipher method.
- password
-
The password.
- raw_output
-
Setting to TRUE will return as raw output data, otherwise the return value is base64 encoded.
- iv
-
A non-NULL Initialization Vector.
Valor Retornado
Returns the encrypted string on success or FALSE on failure.
Erros
Emits an E_WARNING level error if an unknown cipher algorithm is passed in via the method parameter.
Emits an E_WARNING level error if an empty value is passed in via the iv parameter.
Histórico
| Versão | Descrição |
|---|---|
| 5.3.3 | The iv parameter was added. |
openssl_error_string
(PHP 4 >= 4.0.6, PHP 5)
openssl_error_string — Return openSSL error message
Descrição
openssl_error_string() returns the last error from the openSSL library. Error messages are queued, so this function should be called multiple times to collect all of the information. The last error will be the most recent one.
Valor Retornado
Returns an error message string, or FALSE if there are no more error messages to return.
Exemplos
Exemplo #1 openssl_error_string() example
<?php
// lets assume you just called an openssl function that failed
while ($msg = openssl_error_string())
echo $msg . "<br />\n";
?>
openssl_free_key
(PHP 4 >= 4.0.4, PHP 5)
openssl_free_key — Free key resource
Descrição
openssl_free_key() frees the key associated with the specified key_identifier from memory.
Parâmetros
- key_identifier
-
Valor Retornado
Não há valor retornado.
openssl_get_cipher_methods
(PHP 5 >= 5.3.0)
openssl_get_cipher_methods — Gets available cipher methods
Descrição
Gets a list of available cipher methods.
Valor Retornado
An array of available cipher methods.
Exemplos
Exemplo #1 openssl_get_cipher_methods() example
Shows how the available ciphers might look, and also which aliases might be available.
<?php
$ciphers = openssl_get_cipher_methods();
$ciphers_and_aliases = openssl_get_cipher_methods(true);
$cipher_aliases = array_diff($ciphers_and_aliases, $ciphers);
print_r($ciphers);
print_r($cipher_aliases);
?>
O exemplo acima irá imprimir algo similar a:
Array
(
[0] => AES-128-CBC
[1] => AES-128-CFB
[2] => AES-128-CFB1
[3] => AES-128-CFB8
[4] => AES-128-ECB
[5] => AES-128-OFB
[6] => AES-192-CBC
[7] => AES-192-CFB
[8] => AES-192-CFB1
[9] => AES-192-CFB8
[10] => AES-192-ECB
[11] => AES-192-OFB
[12] => AES-256-CBC
[13] => AES-256-CFB
[14] => AES-256-CFB1
[15] => AES-256-CFB8
[16] => AES-256-ECB
[17] => AES-256-OFB
[18] => BF-CBC
[19] => BF-CFB
[20] => BF-ECB
[21] => BF-OFB
[22] => CAST5-CBC
[23] => CAST5-CFB
[24] => CAST5-ECB
[25] => CAST5-OFB
[26] => DES-CBC
[27] => DES-CFB
[28] => DES-CFB1
[29] => DES-CFB8
[30] => DES-ECB
[31] => DES-EDE
[32] => DES-EDE-CBC
[33] => DES-EDE-CFB
[34] => DES-EDE-OFB
[35] => DES-EDE3
[36] => DES-EDE3-CBC
[37] => DES-EDE3-CFB
[38] => DES-EDE3-OFB
[39] => DES-OFB
[40] => DESX-CBC
[41] => IDEA-CBC
[42] => IDEA-CFB
[43] => IDEA-ECB
[44] => IDEA-OFB
[45] => RC2-40-CBC
[46] => RC2-64-CBC
[47] => RC2-CBC
[48] => RC2-CFB
[49] => RC2-ECB
[50] => RC2-OFB
[51] => RC4
[52] => RC4-40
[53] => aes-128-cbc
[54] => aes-128-cfb
[55] => aes-128-cfb1
[56] => aes-128-cfb8
[57] => aes-128-ecb
[58] => aes-128-ofb
[59] => aes-192-cbc
[60] => aes-192-cfb
[61] => aes-192-cfb1
[62] => aes-192-cfb8
[63] => aes-192-ecb
[64] => aes-192-ofb
[65] => aes-256-cbc
[66] => aes-256-cfb
[67] => aes-256-cfb1
[68] => aes-256-cfb8
[69] => aes-256-ecb
[70] => aes-256-ofb
[71] => bf-cbc
[72] => bf-cfb
[73] => bf-ecb
[74] => bf-ofb
[75] => cast5-cbc
[76] => cast5-cfb
[77] => cast5-ecb
[78] => cast5-ofb
[79] => des-cbc
[80] => des-cfb
[81] => des-cfb1
[82] => des-cfb8
[83] => des-ecb
[84] => des-ede
[85] => des-ede-cbc
[86] => des-ede-cfb
[87] => des-ede-ofb
[88] => des-ede3
[89] => des-ede3-cbc
[90] => des-ede3-cfb
[91] => des-ede3-ofb
[92] => des-ofb
[93] => desx-cbc
[94] => idea-cbc
[95] => idea-cfb
[96] => idea-ecb
[97] => idea-ofb
[98] => rc2-40-cbc
[99] => rc2-64-cbc
[100] => rc2-cbc
[101] => rc2-cfb
[102] => rc2-ecb
[103] => rc2-ofb
[104] => rc4
[105] => rc4-40
)
Array
(
[18] => AES128
[19] => AES192
[20] => AES256
[21] => BF
[26] => CAST
[27] => CAST-cbc
[32] => DES
[47] => DES3
[48] => DESX
[50] => IDEA
[55] => RC2
[82] => aes128
[83] => aes192
[84] => aes256
[85] => bf
[90] => blowfish
[91] => cast
[92] => cast-cbc
[97] => des
[112] => des3
[113] => desx
[115] => idea
[120] => rc2
)
openssl_get_md_methods
(PHP 5 >= 5.3.0)
openssl_get_md_methods — Gets available digest methods
Descrição
Gets a list of available digest methods.
Valor Retornado
An array of available digest methods.
Exemplos
Exemplo #1 openssl_get_md_methods() example
Shows how the available digests might look, and also which aliases might be available.
<?php
$digests = openssl_get_md_methods();
$digests_and_aliases = openssl_get_md_methods(true);
$digest_aliases = array_diff($digests_and_aliases, $digests);
print_r($digests);
print_r($digest_aliases);
?>
O exemplo acima irá imprimir algo similar a:
Array
(
[0] => DSA
[1] => DSA-SHA
[2] => MD2
[3] => MD4
[4] => MD5
[5] => RIPEMD160
[6] => SHA
[7] => SHA1
[8] => SHA224
[9] => SHA256
[10] => SHA384
[11] => SHA512
[12] => dsaEncryption
[13] => dsaWithSHA
[14] => ecdsa-with-SHA1
[15] => md2
[16] => md4
[17] => md5
[18] => ripemd160
[19] => sha
[20] => sha1
[21] => sha224
[22] => sha256
[23] => sha384
[24] => sha512
)
Array
(
[2] => DSA-SHA1
[3] => DSA-SHA1-old
[4] => DSS1
[9] => RSA-MD2
[10] => RSA-MD4
[11] => RSA-MD5
[12] => RSA-RIPEMD160
[13] => RSA-SHA
[14] => RSA-SHA1
[15] => RSA-SHA1-2
[16] => RSA-SHA224
[17] => RSA-SHA256
[18] => RSA-SHA384
[19] => RSA-SHA512
[28] => dsaWithSHA1
[29] => dss1
[32] => md2WithRSAEncryption
[34] => md4WithRSAEncryption
[36] => md5WithRSAEncryption
[37] => ripemd
[39] => ripemd160WithRSA
[40] => rmd160
[43] => sha1WithRSAEncryption
[45] => sha224WithRSAEncryption
[47] => sha256WithRSAEncryption
[49] => sha384WithRSAEncryption
[51] => sha512WithRSAEncryption
[52] => shaWithRSAEncryption
[53] => ssl2-md5
[54] => ssl3-md5
[55] => ssl3-sha1
)
Veja Também
- openssl_digest() - Computes a digest
- openssl_get_cipher_methods() - Gets available cipher methods
openssl_get_privatekey
(PHP 4 >= 4.0.4, PHP 5)
openssl_get_privatekey — Sinônimo de openssl_pkey_get_private()
Descrição
Esta função é um apelido para: openssl_pkey_get_private().
openssl_get_publickey
(PHP 4 >= 4.0.4, PHP 5)
openssl_get_publickey — Sinônimo de openssl_pkey_get_public()
Descrição
Esta função é um apelido para: openssl_pkey_get_public().
openssl_open
(PHP 4 >= 4.0.4, PHP 5)
openssl_open — Open sealed data
Descrição
openssl_open() opens (decrypts) sealed_data using the private key associated with the key identifier priv_key_id and the envelope key env_key, and fills open_data with the decrypted data. The envelope key is generated when the data are sealed and can only be used by one specific private key. See openssl_seal() for more information.
Parâmetros
- sealed_data
-
- open_data
-
If the call is successful the opened data is returned in this parameter.
- env_key
-
- priv_key_id
-
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 openssl_open() example
<?php
// $sealed and $env_key are assumed to contain the sealed data
// and our envelope key, both given to us by the sealer.
// fetch private key from file and ready it
$fp = fopen("/src/openssl-0.9.6/demos/sign/key.pem", "r");
$priv_key = fread($fp, 8192);
fclose($fp);
$pkeyid = openssl_get_privatekey($priv_key);
// decrypt the data and store it in $open
if (openssl_open($sealed, $open, $env_key, $pkeyid)) {
echo "here is the opened data: ", $open;
} else {
echo "failed to open data";
}
// free the private key from memory
openssl_free_key($pkeyid);
?>
openssl_pkcs12_export_to_file
(PHP 5 >= 5.2.2)
openssl_pkcs12_export_to_file — Exports a PKCS#12 Compatible Certificate Store File
Descrição
openssl_pkcs12_export_to_file() stores x509 into a file named by filename in a PKCS#12 file format.
Parâmetros
- x509
-
See Key/Certificate parameters for a list of valid values.
- filename
-
Path to the output file.
- priv_key
-
Private key component of PKCS#12 file.
- pass
-
Encryption password for unlocking the PKCS#12 file.
- args
-
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
openssl_pkcs12_export
(PHP 5 >= 5.2.2)
openssl_pkcs12_export — Exports a PKCS#12 Compatible Certificate Store File to variable.
Descrição
openssl_pkcs12_export() stores x509 into a string named by out in a PKCS#12 file format.
Parâmetros
- x509
-
See Key/Certificate parameters for a list of valid values.
- out
-
On success, this will hold the PKCS#12.
- priv_key
-
Private key component of PKCS#12 file.
- pass
-
Encryption password for unlocking the PKCS#12 file.
- args
-
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
openssl_pkcs12_read
(PHP 5 >= 5.2.2)
openssl_pkcs12_read — Parse a PKCS#12 Certificate Store into an array
Descrição
openssl_pkcs12_read() parses the PKCS#12 certificate store supplied by pkcs12 into a array named certs.
Parâmetros
- pkcs12
-
- certs
-
On success, this will hold the Certificate Store Data.
- pass
-
Encryption password for unlocking the PKCS#12 file.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
openssl_pkcs7_decrypt
(PHP 4 >= 4.0.6, PHP 5)
openssl_pkcs7_decrypt — Decrypts an S/MIME encrypted message
Descrição
Decrypts the S/MIME encrypted message contained in the file specified by infilename using the certificate and its associated private key specified by recipcert and recipkey.
Parâmetros
- infilename
-
- outfilename
-
The decrypted message is written to the file specified by outfilename.
- recipcert
-
- recipkey
-
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 openssl_pkcs7_decrypt() example
<?php
// $cert and $key are assumed to contain your personal certificate and private
// key pair, and that you are the recipient of an S/MIME message
$infilename = "encrypted.msg"; // this file holds your encrypted message
$outfilename = "decrypted.msg"; // make sure you can write to this file
if (openssl_pkcs7_decrypt($infilename, $outfilename, $cert, $key)) {
echo "decrypted!";
} else {
echo "failed to decrypt!";
}
?>
openssl_pkcs7_encrypt
(PHP 4 >= 4.0.6, PHP 5)
openssl_pkcs7_encrypt — Encrypt an S/MIME message
Descrição
openssl_pkcs7_encrypt() takes the contents of the file named infile and encrypts them using an RC2 40-bit cipher so that they can only be read by the intended recipients specified by recipcerts.
Parâmetros
- infile
-
- outfile
-
- recipcerts
-
Either a lone X.509 certificate, or an array of X.509 certificates.
- headers
-
headers is an array of headers that will be prepended to the data after it has been encrypted.
headers can be either an associative array keyed by header name, or an indexed array, where each element contains a single header line.
- flags
-
flags can be used to specify options that affect the encoding process - see PKCS7 constants.
- cipherid
-
One of cipher constants.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Histórico
| Versão | Descrição |
|---|---|
| 5.0.0 | The cipherid parameter was added. |
Exemplos
Exemplo #1 openssl_pkcs7_encrypt() example
<?php
// the message you want to encrypt and send to your secret agent
// in the field, known as nighthawk. You have his certificate
// in the file nighthawk.pem
$data = <<<EOD
Nighthawk,
Top secret, for your eyes only!
The enemy is closing in! Meet me at the cafe at 8.30am
to collect your forged passport!
HQ
EOD;
// load key
$key = file_get_contents("nighthawk.pem");
// save message to file
$fp = fopen("msg.txt", "w");
fwrite($fp, $data);
fclose($fp);
// encrypt it
if (openssl_pkcs7_encrypt("msg.txt", "enc.txt", $key,
array("To" => "nighthawk@example.com", // keyed syntax
"From: HQ <hq@example.com>", // indexed syntax
"Subject" => "Eyes only"))) {
// message encrypted - send it!
exec(ini_get("sendmail_path") . " < enc.txt");
}
?>
openssl_pkcs7_sign
(PHP 4 >= 4.0.6, PHP 5)
openssl_pkcs7_sign — Sign an S/MIME message
Descrição
openssl_pkcs7_sign() takes the contents of the file named infilename and signs them using the certificate and its matching private key specified by signcert and privkey parameters.
Parâmetros
- infilename
-
- outfilename
-
- signcert
-
- privkey
-
- headers
-
headers is an array of headers that will be prepended to the data after it has been signed (see openssl_pkcs7_encrypt() for more information about the format of this parameter).
- flags
-
flags can be used to alter the output - see PKCS7 constants.
- extracerts
-
extracerts specifies the name of a file containing a bunch of extra certificates to include in the signature which can for example be used to help the recipient to verify the certificate that you used.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
Exemplos
Exemplo #1 openssl_pkcs7_sign() example
<?php
// the message you want to sign so that recipient can be sure it was you that
// sent it
$data = <<<EOD
You have my authorization to spend $10,000 on dinner expenses.
The CEO
EOD;
// save message to file
$fp = fopen("msg.txt", "w");
fwrite($fp, $data);
fclose($fp);
// encrypt it
if (openssl_pkcs7_sign("msg.txt", "signed.txt", "mycert.pem",
array("file://mycert.pem", "mypassphrase"),
array("To" => "joes@example.com", // keyed syntax
"From: HQ <ceo@example.com>", // indexed syntax
"Subject" => "Eyes only")
)) {
// message signed - send it!
exec(ini_get("sendmail_path") . " < signed.txt");
}
?>
openssl_pkcs7_verify
(PHP 4 >= 4.0.6, PHP 5)
openssl_pkcs7_verify — Verifies the signature of an S/MIME signed message
Descrição
openssl_pkcs7_verify() reads the S/MIME message contained in the given file and examines the digital signature.
Parâmetros
- filename
-
Path to the message.
- flags
-
flags can be used to affect how the signature is verified - see PKCS7 constants for more information.
- outfilename
-
If the outfilename is specified, it should be a string holding the name of a file into which the certificates of the persons that signed the messages will be stored in PEM format.
- cainfo
-
If the cainfo is specified, it should hold information about the trusted CA certificates to use in the verification process - see certificate verification for more information about this parameter.
- extracerts
-
If the extracerts is specified, it is the filename of a file containing a bunch of certificates to use as untrusted CAs.
- content
-
You can specify a filename with content that will be filled with the verified data, but with the signature information stripped.
Valor Retornado
Returns TRUE if the signature is verified, FALSE if it is not correct (the message has been tampered with, or the signing certificate is invalid), or -1 on error.
Histórico
| Versão | Descrição |
|---|---|
| 5.1.0 | The content parameter was added. |
Notas
Nota: As specified in RFC 2045, lines may not be longer than 76 characters in the filename parameter.
openssl_pkey_export_to_file
(PHP 4 >= 4.2.0, PHP 5)
openssl_pkey_export_to_file — Gets an exportable representation of a key into a file
Descrição
openssl_pkey_export_to_file() saves an ascii-armoured (PEM encoded) rendition of key into the file named by outfilename.
Nota: Você precisa ter um válido openssl.cnf instalado para esta função operar corretamente. Veja as notas sobre a seção de instalação para mais informação.
Parâmetros
- key
-
- outfilename
-
Path to the output file.
- passphrase
-
The key can be optionally protected by a passphrase.
- configargs
-
configargs can be used to fine-tune the export process by specifying and/or overriding options for the openssl configuration file. See openssl_csr_new() for more information about configargs.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
openssl_pkey_export
(PHP 4 >= 4.2.0, PHP 5)
openssl_pkey_export — Gets an exportable representation of a key into a string
Descrição
openssl_pkey_export() exports key as a PEM encoded string and stores it into out (which is passed by reference).
Nota: Você precisa ter um válido openssl.cnf instalado para esta função operar corretamente. Veja as notas sobre a seção de instalação para mais informação.
Parâmetros
- key
-
- out
-
- passphrase
-
The key is optionally protected by passphrase.
- configargs
-
configargs can be used to fine-tune the export process by specifying and/or overriding options for the openssl configuration file. See openssl_csr_new() for more information about configargs.
Valor Retornado
Retorna TRUE em caso de sucesso ou FALSE em falhas.
openssl_pkey_free
(PHP 4 >= 4.2.0, PHP 5)
openssl_pkey_free — Frees a private key
Descrição
This function frees a private key created by openssl_pkey_new().
Parâmetros
- key
-
Resource holding the key.
Valor Retornado
Não há valor retornado.
openssl_pkey_get_details
(PHP 5 >= 5.2.0)
openssl_pkey_get_details — Returns an array with the key details
Descrição
This function returns the key details (bits, key, type).
Parâmetros
- key
-
Resource holding the key.
Valor Retornado
Returns an array with the key details in success or FALSE in failure. Returned array has indexes bits (number of bits), key (string representation of the public key) and type (type of the key which is one of OPENSSL_KEYTYPE_RSA, OPENSSL_KEYTYPE_DSA, OPENSSL_KEYTYPE_DH, OPENSSL_KEYTYPE_EC or -1 meaning unknown).
Depending on the key type used, additional details may be returned. Note that some elements may not always be available.
-
OPENSSL_KEYTYPE_RSA, an additional array key named "rsa",
containing the key data is returned.
Key Descrição "n" "e" "d" "p" "q" "dmp1" "dmq1" "iqmp" -
OPENSSL_KEYTYPE_DSA, an additional array key named "dsa",
containing the key data is returned.
Key Descrição "p" "q" "g" "priv_key" "pub_key" -
OPENSSL_KEYTYPE_DH, an additional array key named "dh",
containing the key data is returned.
Key Descrição "p" "g" "priv_key"