Manual do PHP

por:
Mehdi Achour
Friedhelm Betz
Antony Dovgal
Nuno Lopes
Hannes Magnusson
Georg Richter
Damien Seguy
Jakub Vrana
E muitos outros
2013-05-24
Editado por: Philip Olson
por:
Fernando Correa da Conceição
Marcelo Pereira Fonseca da Silva
Raphael Melo de Oliveira Bastos Sales
Renato Arruda
Ricardo Miranda Santos
André Luis Ferreira da Silva Bacci
Anderson Fortaleza
João Prado Maia
Claudio Pereira
Lucas Rocha
Alessander Pery Lopes Thomaz
Taniel Franklin
Thomas Gonzalez Miranda
Ernani Joppert Pontes Martins
Rafael Jaques
Felipe Nascimento Silva Pena
Diogo Galvão
Thiago Henrique Pojda
Amanda Vale
© 1997-2013 the PHP Documentation Group

Copyright

Copyright © 1997 - 2013 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 este manual. A última 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 como um todo ou em parte, modificado ou não, ou se você tem dúvidas, 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.

Authors and Contributors

We highlight the currently most active people on front page of the manual, but there are many more contributors who currently help in our work or have provided a great amount of help to the project in the past. There are a lot of unnamed people who help out with user notes on manual pages, which continually get included in the references, the work of whom we are also very thankful for. All of the lists provided below are in alphabetical order.

Authors and Editors

The following contributors should be recognized for the impact they have made and/or continue to make by adding content to the 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 and Andrei Zmievski.

The following contributors have done significant work editing the manual: Stig Bakken, Gabor Hojtsy, Hartmut Holzgraefe and Egon Schmid.

User Note Maintainers

The currently most active maintainers are: Daniel Brown, Nuno Lopes, Felipe Pena, Thiago Pojda and Maciek Sokolewicz.

These people have also put a lot of effort into managing user notes: 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 and Jeroen van Wolffelaar.

Começando

Introdução

Índice

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:

  • 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
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.

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

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'].
Para mais detalhes destas alterações, veja a seção variáveis pré-definidas.

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

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: 

User nobody
Group "#-1"
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.

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.

Aviso

We do not recommend using a threaded MPM in production with Apache 2. Use the prefork MPM, which is the default MPM with Apache 2.0 and 2.2. For information on why, read the related FAQ entry on using Apache2 with a 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.

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.

  1. 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)

  2. 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.
  3. gunzip php-x.x.x.tar.gz (se você tiver uma distribuição .gz, caso contrário vá para o passo 4).
  4. tar xvf php-x.x.x.tar
  5. Mude para o diretório recém-criado: cd ../php-x.x.x

  6. 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

  7. 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/.

  1. 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

  2. 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. 

    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"]
    (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.

  3. Configure o objeto padrão no arquivo obj.conf (para classes de servidor virtuais [versão 6.0+] no arquivo vserver.obj.conf): 

    <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>
    (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"

  4. Isso só é necessários se você quiser configurar um diretório que apenas consiste de scripts PHP (assim como um diretório cgi-bin): 

    <Object name="x-httpd-php">
ObjectType fn="force-type" type="magnus-internal/x-httpd-php"
Service fn=php4_execute [inikey=value inikey=value ...]
</Object>
    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.

  5. 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>

  6. 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...]
Onde XXX é o código do erro HTTP. Por favor remova qualquer outra diretiva Error que possa interferir com as suas. Se você quiser colocar uma página para todos os erros que podem existir, tire o parâmetro code. Seu script pode pegar o código do erro com $_SERVER['ERROR_TYPE'].

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...]
Tanto para os erros e as páginas de listagem do diretório a URI original e a URL traduzida estão nas variáveis $_SERVER['PATH_INFO'] e $_SERVER['PATH_TRANSLATED'].

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.

Aviso

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
Além disso, você pode precisar instalar (e possivelmente compilar) qualquer software adicional específico para sua configuração, como o Oracle ou MySQL.

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

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:

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:

  1. 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.

  2. 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): 

    # LoadModule php4_module libexec/httpd/libphp4.so

# AddModule mod_php4.c
    Perceba a localização/caminho. Quando compilar o PHP no futuro, os arquivos acima devem ser substituidos ou comentados.

  3. 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>

  4. 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.
  5. 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.
  6. 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
  7. 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(); ?>

  8. 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

  1. Pegue a última distribuição do Apache e PHP.

  2. 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

  3. Se você quiser que o compilador faça alguma otimização, você pode também querer adicionar essa linha: 

    setenv OPTIM=-O2

  4. Depois, vá para o diretório onde os fontes do PHP 4 estão e configure ele. 

    ./configure --prefix=/usr \
    --sysconfdir=/etc \
    --localstatedir=/var \
    --mandir=/usr/share/man \
    --with-xml \
    --with-apache=/src/apache_1.3.12
    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.

  5. Digite make e make install. Isso irá adicionar um diretório para nos fontes do Apache em src/modules/php4.

  6. Agora, reconfigure o Apache para montar junto com o PHP 4. 

    ./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
    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.

  7. 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.ini ou (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.

Aviso

Tenha cuidado quando for fazer isso, vocêo pode estragar seu servidor Apache!

Faça isso para instalar:

  1. Abra uma janela de terminal.
  2. Digite wget http://www.diax.ch/users/liyanage/software/macosx/libphp4.so.gz, e espere o download terminar.
  3. Digite gunzip libphp4.so.gz.
  4. Digite sudo apxs -i -a -n php4 libphp4.so

  5. 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)) 

    #AddType application/x-httpd-php .php 
#AddType application/x-httpd-php-source .phps
    Remove os caracteres de comentários (#), e depois salve o arquivo e saia do TextEdit.

  6. Finalmente, digite sudo apachectl graceful e 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

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.

Aviso

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.

Aviso

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).

Aviso

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ê também pode usar a mesma sintaxe para especificar o diretório de configuração do Apache (APACHEDIR), do Sambar (SAMBARDIR), e do Xitami (XITAMIDIR).

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).

Aviso

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.

Aviso

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:

  1. In the Windows Start Menu choose "Run:", type "inetmgr" and click "Ok";

  2. 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";

  3. Click the "Directory Security" tab;

  4. Take note of a "User name:" field in the "Authentication Methods" dialog

Anonymous authenication for IIS 5.1 and IIS 6.0

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:

  1. In the Windows Start Menu choose "Run:", type "inetmgr" and click "Ok";

  2. Right-click on the "Web Sites" node in the tree view and select "Properties";

  3. Click the "Documents" tab;

  4. Click the "Add..." button and enter "index.php" for the "Default content page:".

Setting index.php as default document for IIS

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:

  1. In the Windows Start Menu choose "Run:", type "optionalfeatures.exe" and click "Ok";

  2. In the "Windows Features" dialog expand "Internet Information Services", "World Wide Web Services", "Application Development Features" and then enable the "CGI" checkbox;

  3. Click OK and wait until the installation is complete.

Enabling FastCGI support for IIS7 on Windows Vista SP1 and Windows 7

To enable FastCGI support on Windows Server 2008 and Windows Server 2008 R2:

  1. In the Windows Start Menu choose "Run:", type "CompMgmtLauncher" and click "Ok";

  2. If the "Web Server (IIS)" role is not present under the "Roles" node, then add it by clicking "Add Roles";

  3. If the "Web Server (IIS)" role is present, then click "Add Role Services" and then enable the "CGI" checkbox under "Application Development" group;

  4. Click "Next" and then "Install" and wait for the installation to complete.

Enabling FastCGI support on Windows Server 2008 and Windows Server 2008 R2

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:

  1. In the Windows Start Menu choose "Run:", type "inetmgr" and click "Ok";

  2. In the IIS Manager user interface select the server node in the "Connections" tree view;

  3. In the "Features View" page open the "Handler Mappings" feature;

    Create IIS handler mapping for PHP : Locate Handler Mappings

  4. In the "Actions" pane click "Add Module Mapping...";

  5. 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

  6. Click "Request Restrictions" button and then configure the mapping to invoke handler only if request is mapped to a file or a folder;

  7. Click OK on all the dialogs to save the configuration.

Create IIS handler mapping for PHP : Add Handler Mapping

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: Remember that when adding path values in the Apache configuration files on Windows, all backslashes such as c:\directory\file.ext should be converted to forward slashes: c:/directory/file.ext. A trailing slash may also be necessary for directories.

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
Note que a segunda linha na lista acima pode ser encontrada na versão padrão do httpd.conf, mas está comentada. Lembre-se de substituir também o c:/php/ pelo caminho do PHP no seu sistema.

Aviso

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/

Aviso

We do not recommend using a threaded MPM in production with Apache 2. Use the prefork MPM, which is the default MPM with Apache 2.0 and 2.2. For information on why, read the related FAQ entry on using Apache2 with a 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.

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.

Aviso

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: Remember that when adding path values in the Apache configuration files on Windows, all backslashes such as c:\directory\file.ext should be converted to forward slashes: c:/directory/file.ext. A trailing slash may also be necessary for directories.

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"

Aviso

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.

Aviso

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. 

    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"]
    (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.

  • 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': 

    Service fn="php4_execute" type="magnus-internal/x-httpd-php" [inikey=value inikey=value ...]
    (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"

  • Isso só é necessário se você quiser configurar um diretório que só consiste de scripts PHP (como em um diretório cgi-bin): 

    <Object name="x-httpd-php">
ObjectType fn="force-type" type="magnus-internal/x-httpd-php"
Service fn=php4_execute [inikey=value inikey=value ...]
</Object>
    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.

  • 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...]
onde XXX é o código de erro HTTP. Por favor apague qualquer outra diretiva Error que podem interferir com as suas. Se você quiser colocar uma página para todos os erros que podem existir, não informe o parâmetro code. Seu script pode determinar qual o erro pela variável $_SERVER['ERROR_TYPE'].

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...]
Tanto para páginas de erro e de listagem de diretório a URI original e a URI traduzida estão nas variáveis $_SERVER['PATH_INFO'] e $_SERVER['PATH_TRANSLATED'].

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"
onde XX é o número de versão correto da DLL. Para obter esse valor, procure na pasta raiz do servidor para o nome correto da DLL. A DLL com o maior tamanho é a certa.

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]:

    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
    (Essa linha presume que o PHP foi instalado em c:\php.)

  • 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.

Aviso

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 and Zlib

No PHP 5 (atualizado PHP 5.0.4), as seguintes mudanças existem. Embutido: DOM, LibXML, Iconv, SimpleXML, SPL and 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ões do PHP
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 Overload Integrado desde o PHP 4.3.0 >= 5.0.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.

    Nota:

    Both PATH and PATHEXT are important pre-existing system variables in Windows, and care should be taken to not overwrite either variable, only to add to them.

  • Append 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.

  • Append 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
or, if your "C:\PHP Scripts" path is in the PATH environment variable: 
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: 

dir | "C:\PHP Scripts\script" -arg1 -arg2 -arg3
or 
dir | script -arg1 -arg2 -arg3
You may find that the script simply hangs and nothing is output. To get this operational, you need to make another registry change. 
Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\policies\Explorer]
"InheritConsoleHandles"=dword:00000001
Further information regarding this issue can be found in this » Microsoft Knowledgebase Article : 321788.

Installation on Cloud Computing platforms

Índice

PHP installs on the cloud. To the PHP cloud!

Microsoft Azure

PHP installs on the » Azure cloud platform.

See also the » Azure SDK for PHP.

Amazon EC2

PHP installs on the » EC2 cloud platform.

See also the » AWS SDK for PHP.

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, ondemand, dynamic. This option is mandatory.

static - the number of child processes is fixed (pm.max_children).

ondemand - the processes spawn on demand (when requested, as opposed to dynamic, where pm.start_servers are started when the service is started.

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 certain 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
PHP settings passed with php_value or php_flag will overwrite their previous value. Please note that defining disable_functions or disable_classes will not overwrite previously defined php.ini values, but will append the new value instead.

Settings defined with php_admin_value and php_admin_flag cannot be overriden with ini_set().

As of 5.3.3, PHP settings are also possible to be set in webserver.

Exemplo #2 set PHP settings in nginx.conf

set $php_value "pcre.backtrack_limit=424242";
set $php_value "$php_value \n pcre.recursion_limit=99999";
fastcgi_param  PHP_VALUE $php_value;

fastcgi_param  PHP_ADMIN_VALUE "open_basedir=/var/www/htdocs";
Cuidado

Because these settings are passed to php-fpm as fastcgi headers, php-fpm should not be bound to a worldwide accessible address. Otherwise, anyone could alter the PHP configuration options. See also listen.allowed_clients.

Instalação das extensões PECL

Índice

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().

Definição dos modos PHP_INI_*
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_value nome 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_value para configurar valores booleanos. php_flag (veja abaixo) deve ser usada, ao invés.

php_flag nome 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_value nome valor

Configura o valor da diretiva especificada. Isso não pode ser usado em arquivos .htaccess. Qualquer tipo diretiva configurada com php_admin_value não pode ser sobrescrita por diretivas .htaccess ou ini_set().. Para limpar um valor configurado anteriormente, use o valor none.

php_admin_flag nome 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_flag nã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>

Cuidado

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().

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
}
?>
Isto funciona como o esperado, porque o quando PHP atinge o ?> fechando as tags, ele simplesmente começa a enviar para a saída qualquer coisa (exceto newlines em seguida - veja separação de instruções) que encontre até que atinja outra tag de abertura. O exemplo dado aqui é resumido, claro, mas para escrever grandes blocos de texto, sair do modo de interpretação do PHP é geralmente mais eficiente do que enviar todo o texto atráves de echo ou print.

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

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:

Qualquer outro valor é considerado TRUE (incluindo qualquer recurso).
Aviso

-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)
?>
Formalmente, as possíveis representação de inteiros são: 
decimal     : [1-9][0-9]*
            | 0

hexadecimal : 0[xX][0-9a-fA-F]+

octal       : 0[0-7]+

integer     : [+-]?decimal
            | [+-]?hexadecimal
            | [+-]?octal
O tamanho de um inteiro é dependente de plataforma, sendo um número aproximado a 2 bilhões o valor mais comum (número de 32 bits com sinal). O PHP não suporta inteiros sem sinal. O tamanho do inteiro pode ser determinado pela constante PHP_INT_SIZE, e seu o valor máximo com a constante PHP_INT_MAX desde o PHP 4.4.0 e PHP 5.0.5.

Aviso

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)
?>
Aviso

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!

Aviso

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!
?>
Para maiores informações, veja o alerta sobre a precisão de número flutuante..

De outros tipos

Cuidado

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;
?>
Formalmente:
LNUM          [0-9]+
DNUM          ([0-9]*[\.]{LNUM}) | ({LNUM}[\.][0-9]*)
EXPONENT_DNUM ( ({LNUM} | {DNUM}) [eE][+-]? {LNUM})
O tamanho de um número de ponto flutuante é dependente de plataforma, sendo o máximo de ~1.8e308 com uma precisão de 14 dígitos decimais um valor comum (número de 64 bits no formato IEEE).

Aviso

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ó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üências de escape
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.

Aviso

É 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': \x41

Nota:

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.

Aviso

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

Aviso

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 coisa
Se $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.

Aviso

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.

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
?>
Isto está errado, mas funciona. Então, porque está errado? A razão está neste código, que tem uma constante indefinida (bar) em vez de uma string ('bar' - repare nos delimitadores), e o PHP pode no futuro definir constantes que, infelizmente em seu código, podem ter o mesmo nome. Isto funciona, porque o PHP automaricamente converte uma string base (uma string não delimitada que não corresponde a nenhum símbolo conhecido) em uma string que contém a string base. Por exemplo, se não existir uma constante definida com o nome bar, então o PHP irá substituí-la pela string 'bar' e usá-la.

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)];
?>
Isto é um exemplo de utilização de um valor de retorno de função como um índice de array. O PHP conhece constantes, como você deve ter visto algumas E_* antes.
<?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";
?>
Note que E_ERROR é um identificador válido, assim como bar no primeiro exemplo. Mas no último exemplo seria a mesma coisa que escrevendo:
<?php
$error_descriptions[1] = "Um erro fatal ocorreu";
$error_descriptions[2] = "O PHP emitiu um alarme";
$error_descriptions[8] = "Apenas um aviso informal";
?>
porque E_ERROR é igual a 1, e assim por diante.

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());
?>
Acima aparece duas chaves chamadas 'AA', embora uma delas é atualmente chamada '\0A\0A'.

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;
?>

Veja também as funções is_null() e unset().

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.

number

number indica que um parâmetro pode ser tanto um integer ou float.

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.

Dica

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.

Aviso

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.

Aviso

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 */
?>
Dessa forma, o interpretador entende isso como uma variável nomeada $varname, seguida do operador de concatenação de strings, seguida de um identificador (uma string não delimitada que não bate com nenhuma palavra chave ou reservada) 'ext'. Obviamente, isso não tem os resultados pretendidos.

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]*

Dica

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):

Algumas constantes "mágicas" do PHP
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() and 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

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.

Precedência dos operadores
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 and string
esquerda << >> Bit-a-bit
não associativo < <= > >= <> comparação
não associativo == != === !== comparação
esquerda & Bit-a-bit and 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
?>
Use parênteses para aumenta a legibilidade do código.

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.

Operadores Aritméticos
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

?>

Operadores Bit-a-bit
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")
Aviso

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.

Operadores de comparação
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).

Comparação com vários tipos
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'];
}

?>
A expressão (expr1) ? (expr2) : (expr3) é avaliada para expr2 se expr1 é avaliada como TRUE, ou expr3 se expr1 é avaliada como FALSE.

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 includes, 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).

Aviso

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.

Operadores de Incremento/Decremento
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

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 à:

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

Operadores de array
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);
?>
Quando executado, o script produz uma saída assim: 
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

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, PHP 5)

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, PHP 5)

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";
}
?>
The else statement is only executed if the if expression evaluated to FALSE, and if there were any elseif expressions - only if they evaluated to FALSE as well (see elseif).

elseif/else if

(PHP 4, PHP 5)

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, PHP 5)

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.

See also while, for, and if for further examples.

while

(PHP 4, PHP 5)

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, PHP 5)

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, PHP 5)

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;

It's a common thing to many users to iterate through 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 < count($people); ++$i) {
    $people[$i]['salt'] = mt_rand(000000, 999999);
}
?>

The above code can be slow, because the array size is fetched on every iteration. Since the size never changes, the loop be easily optimized by using an intermediate variable to store the size instead of repeatedly calling count():

<?php
$people = array(
    array('name' => 'Kalle', 'salt' => 856412),
    array('name' => 'Pierre', 'salt' => 215863)
);

for($i = 0, $size = count($people); $i < $size; ++$i) {
    $people[$i]['salt'] = mt_rand(000000, 999999);
}
?>

foreach

(PHP 4, PHP 5)

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;
}
?>

Aviso

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 usage:

<?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";
}
?>

Unpacking nested arrays with list()

(PHP 5 >= 5.5.0)

PHP 5.5 added the ability to iterate over an array of arrays and unpack the nested array into loop variables by providing a list() as the value.

For example:

<?php
$array = [
    [1, 2],
    [3, 4],
];

foreach ($array as list($a, $b)) {
    // $a contains the first element of the nested array,
    // and $b contains the second element.
    echo "A: $a; B: $b\n";
}
?>

O exemplo acima irá imprimir:

A: 1; B: 2
A: 3; B: 4

You can provide fewer elements in the list() than there are in the nested array, in which case the leftover array values will be ignored:

<?php
$array = [
    [1, 2],
    [3, 4],
];

foreach ($array as list($a)) {
    // Note that there is no $b here.
    echo "$a\n";
}
?>

O exemplo acima irá imprimir:

1
3

A notice will be generated if there aren't enough array elements to fill the list():

<?php
$array = [
    [1, 2],
    [3, 4],
];

foreach ($array as list($a, $b, $c)) {
    echo "A: $a; B: $b; C: $c\n";
}
?>

O exemplo acima irá imprimir:


Notice: Undefined offset: 2 in example.php on line 7
A: 1; B: 2; C: 

Notice: Undefined offset: 2 in example.php on line 7
A: 3; B: 4; C:

break

(PHP 4, PHP 5)

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;
    }
}
?>

Changelog for break
Versão Descrição
5.4.0 break 0; is no longer valid. In previous versions it was interpreted the same as break 1;.
5.4.0 Removed the ability to pass in variables (e.g., $num = 2; break $num;) as the numerical argument.

continue

(PHP 4, PHP 5)

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. The default value is 1, thus skipping to the end of the current loop.

<?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.)

Changelog for continue
Versão Descrição
5.4.0 continue 0; is no longer valid. In previous versions it was interpreted the same as continue 1;.
5.4.0 Removed the ability to pass in variables (e.g., $num = 2; continue $num;) as the numerical argument.

switch

(PHP 4, PHP 5)

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, PHP 5)

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
?>

Cuidado

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().

See also zend.script_encoding.

return

(PHP 4, PHP 5)

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 included or required, then control is passed back to the calling file. Furthermore, if the current script file was included, 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, PHP 5)

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, PHP 5)

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 include wrappers" are enabled in PHP, 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.

Aviso

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.

?>

Aviso

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: include returns FALSE on failure and raises a warning. Successful includes, unless overridden by the included file, return 1. 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, PHP 5)

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, PHP 5)

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.

What's the worse thing that could happen if you use goto?
Image courtesy of » xkcd

Funções

Índice

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]*.

Dica

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

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

Dica

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 non-static properties may be accessed by using -> (Object Operator): $this->property (where property is the name of the property). Static properties are accessed by using the :: (Double Colon): self::$property. See Static Keyword for more information on the difference between static and non-static properties.

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 Classes

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.

Dica

spl_autoload_register() fornece uma alternativa mais flexível para 'autoloading' de classes. Por esta razão, o uso da função __autoload() é desencorajado e pode estar obsoleto ou ser removido no futuro.

Nota:

Antes do PHP 5.3.0 exceções disparadas na função __autoload não podiam ser pegas no bloco catch e resultavam em um erro fatal. De PHP 5.3.0 em diante exceções disparadas na função __autoload podem ser pegas no bloco catch, com uma condição. Se disparada uma exceção customizada, então a classe da exceção customizada deve estar disponível. A função __autoload deve ser usada recursivamente para carregar a classe de exceção customizada.

Nota:

Autoloading não é disponível usando PHP em modo interativo CLI.

Nota:

Se o nome da classe é usado por exemplo em call_user_func() então ela pode conter alguns caracteres perigosos como ../. É recomendado não usar entrada de usuário nestas funções ou pelo menos verificar a entrada em __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 ...
*/
?>

Exemplo #3 Autoloading with exception handling for 5.3.0+

This example throws an exception and demonstrates the try/catch block.

<?php
function __autoload($name) {
    echo "Want to load $name.\n";
    throw new Exception("Unable to load $name.");
}

try {
    $obj = new NonLoadableClass();
} catch (Exception $e) {
    echo $e->getMessage(), "\n";
}
?>

O exemplo acima irá imprimir:

Want to load NonLoadableClass.
Unable to load NonLoadableClass.

Exemplo #4 Autoloading com manipulação de exceção para 5.3.0+ - Faltando exceção customizada.

Este exemplo dispara uma exceção para uma exceção customizada não carregável.

<?php
function __autoload($name) {
    echo "Want to load $name.\n";
    throw new MissingException("Unable to load $name.");
}

try {
    $obj = new NonLoadableClass();
} catch (Exception $e) {
    echo $e->getMessage(), "\n";
}
?>

O exemplo acima irá imprimir:

Want to load NonLoadableClass.
Want to load MissingException.

Fatal error: Class 'MissingException' not found in testMissingException.php on line 4

Veja Também

Construtores e Destrutores

Construtores

void __construct ([ mixed $args [, $... ]] )

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

void __destruct ( void )

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 classes 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 Classes

PHP 5 introduz métodos e classes abstratos. Não é permitido criar uma instância de uma classe que foi definida como abstrata e qualquer classe que contenha 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 abstrato é definido como protected, a implementação da função deve ser definida ou como protected ou public, mas não private. Além disso, as assinaturas dos métodos devem coincidir, ou seja, as induções de tipos e o número de argumentos requeridos devem ser os mesmos. Isto também se aplica aos construtores a partir do PHP 5.4. Antes do 5.4 as assinaturas dos construtores poderiam ser diferentes.

Exemplo #1 Exemplo de classe abstrata

<?php
abstract class ClasseAbstrata
{
    // Força a classe que estende ClasseAbstrata 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 are 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<