Manual do PHP

Stig Sæther Bakken
Alexander Aulbach
Egon Schmid
Jim Winstead
Lars Torben Wilson
Rasmus Lerdorf
Andrei Zmievski
Jouni Ahto

Editado por

Stig Sæther Bakken
Egon Schmid
Renato Arruda
André L F S Bacci
Anderson Fortaleza
João Prado Maia
Claudio Pereira
Lucas Rocha
Alessander Pery Lopes Thomaz
Taniel Franklin
Thomas Gonzalez Miranda
Ernani Joppert Pontes Martins
Fernando Correa da Conceição

29-01-2003

Copyright

Este manual tem © Copyright 1997 - 2003 para o PHP Documentation Group. Os membros deste grupo são listados na primeira página deste manual.

Este manual pode ser redistribuído sob os termos da Licença Pública Geral (GNU) conforme publicada pela Free Software Foundation; a versão 2 da Licença ou (a seu critério) qualquer versão posterior.

A seção 'Extendendo PHP 4.0' deste manual tem copyright © 2000 para Zend Technologies, Ltd. Este material pode ser distribuido somente sob os termos e condições descritas na Open Publication License v1.0 ou posterior (a versão mais recente está disponível em http://www.opencontent.org/openpub/).


Índice
Prefácio
I. Começando
1. Introdução
2. A simple tutorial
3. Instalação
4. Configuração
5. Security
II. Referência da Linguagem
6. Sintaxe básica
7. Tipos
8. Variáveis
9. Constantes
10. Expressões
11. Operadores
12. Estruturas de Controle
13. Funções
14. Classes e Objetos
15. Referências
III. Características
16. HTTP authentication with PHP
17. Cookies
18. Gerenciar o upload de arquivos
19. Using remote files
20. Connection handling
21. Persistent Database Connections
22. Safe Mode
23. Utilizando o PHP na linha de comando
IV. Referência das Funções
I. Apache
II. Funções para manipulação de arrays
III. Aspell functions [deprecated]
IV. BCMath Funções Matemáticas de Precisão Arbitrária
V. Funções de compactação com Bzip2
VI. Calendar functions
VII. CCVS API Functions
VIII. COM support functions for Windows
IX. Classes e Objetos
X. ClibPDF functions
XI. Crack functions
XII. CURL, Client URL Library Functions
XIII. Cybercash payment functions
XIV. Crédit Mutuel CyberMUT functions
XV. Cyrus IMAP administration functions
XVI. Character type functions
XVII. Database (dbm-style) abstraction layer functions
XVIII. Funções data e hora
XIX. dBase functions
XX. DBM Functions [deprecated]
XXI. dbx functions
XXII. DB++ Functions
XXIII. Direct IO functions
XXIV. Diretórios
XXV. DOM XML functions
XXVI. .NET functions
XXVII. Error Handling and Logging Functions
XXVIII. FrontBase Functions
XXIX. filePro functions
XXX. Filesystem (Sistema de arquivos)
XXXI. Forms Data Format functions
XXXII. FriBiDi functions
XXXIII. FTP functions
XXXIV. Function Handling functions
XXXV. Gettext
XXXVI. GMP functions
XXXVII. HTTP functions
XXXVIII. Hyperwave functions
XXXIX. Hyperwave API functions
XL. iconv functions
XLI. Image functions
XLII. IMAP, POP3 and NNTP functions
XLIII. Informix functions
XLIV. InterBase functions
XLV. Ingres II functions
XLVI. IRC Gateway Functions
XLVII. PHP / Java Integration
XLVIII. LDAP functions
XLIX. Funções de E-Mail
L. mailparse functions
LI. Matemática e Trigonometria
LII. Multi-Byte String Functions
LIII. MCAL functions
LIV. Mcrypt Encryption Functions
LV. MCVE Payment Functions
LVI. Mhash - Funções de hash
LVII. Mimetype Functions
LVIII. Funções Microsoft SQL Server
LIX. Ming functions for Flash
LX. Funções de Miscelânea
LXI. mnoGoSearch Functions
LXII. mSQL functions
LXIII. MySQL
LXIV. Mohawk Software session handler functions
LXV. muscat functions
LXVI. Network Functions
LXVII. Ncurses terminal screen control functions
LXVIII. Lotus Notes functions
LXIX. Unified ODBC functions
LXX. Object Aggregation/Composition Functions
LXXI. Oracle 8 functions
LXXII. OpenSSL functions
LXXIII. Oracle functions
LXXIV. Ovrimos SQL functions
LXXV. Output Control Functions
LXXVI. Sobrecarga de propriedades e métodos de objetos
LXXVII. PDF functions
LXXVIII. Verisign Payflow Pro functions
LXXIX. PHP Options&Information
LXXX. POSIX functions
LXXXI. Funções para PostgreSQL
LXXXII. Process Control Functions
LXXXIII. Program Execution functions
LXXXIV. Printer functions
LXXXV. Pspell Functions
LXXXVI. GNU Readline
LXXXVII. GNU Recode functions
LXXXVIII. Regular Expression Functions (Perl-Compatible)
LXXXIX. qtdom functions
XC. Regular Expression Functions (POSIX Extended)
XCI. Semaphore, Shared Memory and IPC Functions
XCII. SESAM database functions
XCIII. Manejo de sessões
XCIV. Shared Memory Functions
XCV. Shockwave Flash functions
XCVI. SNMP functions
XCVII. Socket functions
XCVIII. Stream functions
XCIX. String functions
C. Funções Sybase
CI. Tokenizer functions
CII. Funções URL
CIII. Variable Functions
CIV. vpopmail functions
CV. W32api functions
CVI. WDDX Functions
CVII. XML parser functions
CVIII. XML-RPC functions
CIX. XSLT functions
CX. YAZ functions
CXI. YP/NIS Functions
CXII. Zip File Functions (Read Only Access)
CXIII. Funções de Compressão Zlib
V. Extending PHP 4.0
24. Overview
25. Extension Possibilities
26. Source Layout
27. PHP's Automatic Build System
28. Creating Extensions
29. Using Extensions
30. Troubleshooting
31. Source Discussion
32. Accepting Arguments
33. Creating Variables
34. Duplicating Variable Contents: The Copy Constructor
35. Returning Values
36. Printing Information
37. Startup and Shutdown Functions
38. Calling User Functions
39. Initialization File Support
40. Where to Go from Here
41. Reference: Some Configuration Macros
42. API Macros
43. Streams API for PHP Extension Authors
Overview
Streams Basics
Streams as Resources
Streams Common API Reference
Streams Dir API Reference
Streams File API Reference
Streams Socket API Reference
Streams Structures
Streams Constants
VI. FAQ: Perguntas Mais Freqüentes
44. General Information
45. Mailing lists
46. Obtaining PHP
47. Database issues
48. Installation
49. Build Problems
50. Using PHP
51. PHP and HTML
52. PHP and COM
53. PHP and other languages
54. Migrating from PHP 2 to PHP 3
55. Migrating from PHP 3 to PHP 4
56. Miscellaneous Questions
VII. Apêndices
A. A História do PHP e projetos relacionados
B. Migrating from PHP 3 to PHP 4
C. Migrating from PHP/FI 2 to PHP 3
D. O debugador do PHP
E. Extending PHP
F. Lista de funções sinônimas (aliases)
G. Palavras reservadas do PHP
H. List of Resource Types
I. List of Supported Protocols/Wrappers
J. List of Parser Tokens
K. Sobre o manual
L. Identificadores faltando (compilação do manual)

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 escrever páginas que serão geradas dinamicamente rapidamente, mas você pode fazer muito mais do que isso com PHP.

Esse manual consiste primariamente 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 desse manual em vários formatos em http://www.php.net/docs.php. Os arquivos para downloads são atualizados automaticamente assim que o conteúdo for modificado. Para mais informações sobre como esse manual é desenvolvido pode ser encontrado em 'Sobre o manual' do apêndice.

Veja também a história do PHP.

I. Começando


Capítulo 1. Introdução

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.

Uma resposta simples, mas o que isso significa?

Exemplo 1-1. Um exemplo introdutório

<html>
    <head>
        <title>Exemplo</title>
    </head>
    <body>

        <?php
        echo "Olá, Eu sou um script PHP!";
        ?>

    </body>
</html>

Note como isso é diferente de scripts CGI escritos em outras linguagens como Perl ou C --- ao invés de escrever um programa com um monte de comandos para imprimir HTML, você escreve um arquivo HTML com algum código inserido para fazer alguma coisa (nesse caso, imprimir um pouco de texto). O código PHP é delimitado por tags iniciais e finais 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. Se você tivesse um script similar ao acima em seu servidor, o cliente receberia os resultados da execução desse script, sem nenhum modo de determinar 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?.


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 se 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. Veja as instruções de instalação para maiores 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 GUI no lado do cliente (client-side). O PHP não é (provavelmente) a melhor linguagem para produção de aplicações com interfaces em janelas, mas o PHP faz isso muito bem, e se você deseja usar alguns recursos avançados do PHP em aplicações no lado do cliente poderá utilizar o PHP-GTK para escrever esses programas. E programas escritos desta forma ainda serão independentes de plataforma. O PHP-GTK é uma extensão do PHP, não disponível na distribuição oficial. Se você está interessado no PHP-GTK, visite seu website

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 não desenvolvendo nenhum recurso padrão de OOP (Object Oriented Programming, Programação Orientada a Objetos) na versão atual do PHP, muitas bibliotecas de código e grandes aplicações (incluindo a biblioteca PEAR) foram escritos somente utilizando OOP.

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 Ingres Oracle (OCI7 and OCI8)
dBase InterBase Ovrimos
Empress FrontBase PostgreSQL
FilePro (read-only) mSQL Solid
Hyperwave Direct MS-SQL Sybase
IBM DB2 MySQL Velocis
Informix ODBC Unix dbm

Também foi providenciado uma abstração de banco de dados DBX 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. Para acessar e processar documentos XML, são suportados os padrões SAX e DOM. Você ainda pode usar nossa extensão XSLT para transformar documentos XML.

Utilizando o PHP no campo do e-commerce, você poderá usar as funções específicas para Cybescash, CyberMUT, Verysign Payflow Pro e CCVS, práticos sistemas de pagamento online.

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


Capítulo 2. A simple tutorial

Here we would like to show the very basics of PHP in a short simple tutorial. This text only deals with dynamic webpage creation with PHP, though PHP is not only capable of creating webpages. See the section titled What can PHP do for more information.

PHP-enabled web pages are treated just like regular HTML pages and you can create and edit them the same way you normally create regular HTML pages.


What do I need?

In this tutorial we assume that your server has support for PHP activated and that all files ending in .php are handled by PHP. On most servers this is the default extension for PHP files, but ask your server administrator to be sure. If your server supports PHP then you don't need to do anything. Just create your .php files and put them in your web directory and the server will magically parse them for you. There is no need to compile anything nor do you need to install any extra tools. Think of these PHP-enabled files as simple HTML files with a whole new family of magical tags that let you do all sorts of things.

Let's say you want to save precious bandwidth and develop locally. In this case, you'll want to install a web server, such as Apache, and of course PHP. You'll most likely want to install a database as well, such as MySQL. You can install these individually or a simpler way is to locate a pre-configured package that automatically installs all of these with just a few mouse clicks. It's easy to setup a web server with PHP support on any operating system, including Linux and Windows. In linux, you may find rpmfind helpful for locating RPMs.


Your first PHP-enabled page

Create a file named hello.php and put it in your web servers root directory (DOCUMENT_ROOT) with the following content:

Exemplo 2-1. Our first PHP script: hello.php

<html>
 <head>
  <title>PHP Test</title>
 </head>
 <body>
 <?php echo "<p>Hello World</p>"; ?>
 </body>
</html>

Use your browser to access the file with your web access URL, ending with the "/hello.php" file reference. When developing locally this url will be something like http://localhost/hello.php or http://127.0.0.1/hello.php but this depends on the web servers configuration. Although this is outside the scope of this tutorial, see also the DocumentRoot and ServerName directives in your web servers configuration file. (on Apache this is httpd.conf). If everything is setup correctly, this file will be parsed by PHP and the following output will make it to your browser:

<html>
 <head>
  <title>PHP Test</title>
 </head>
 <body>
 <p>Hello World</p>
 </body>
</html>

Note that this is not like a CGI script. The file does not need to be executable or special in any way. Think of it as a normal HTML file which happens to have a set of special tags available to you that do a lot of interesting things.

This program is extremely simple and you really didn't need to use PHP to create a page like this. All it does is display: Hello World using the PHP echo() statement.

If you tried this example and it didn't output anything, or it prompted for download, or you see the whole file as text, chances are that the server you are on does not have PHP enabled. Ask your administrator to enable it for you using the Installation chapter of the manual. If you're developing locally, also read the installation chapter to make sure everything is configured properly. If problems continue to persist, don't hesitate to use one of the many PHP support options.

The point of the example is to show the special PHP tag format. In this example we used <?php to indicate the start of a PHP tag. Then we put the PHP statement and left PHP mode by adding the closing tag, ?>. You may jump in and out of PHP mode in an HTML file like this all you want. For more details, read the manual section on basic PHP syntax.

A Note on Text Editors: There are many text editors and Integrated Development Environments (IDEs) that you can use to create, edit and manage PHP files. A partial list of these tools is maintained at PHP Editor's List. If you wish to recommend an editor, please visit the above page and ask the page maintainer to add the editor to the list. Having an editor with syntax highlighting can be helpful.

A Note on Word Processors: Word processors such as StarOffice Writer, Microsoft Word and Abiword are not good choices for editing PHP files. If you wish to use one for this test script, you must ensure that you save the file as PLAIN TEXT or PHP will not be able to read and execute the script.

A Note on Windows Notepad: If you are writing your PHP scripts using Windows Notepad, you will need to ensure that your files are saved with the .php extension. (Notepad adds a .txt extension to files automatically unless you take one of the following steps to prevent it.) When you save the file and are prompted to provide a name for the file, place the filename in quotes (i.e. "hello.php"). Alternately, you can click on the 'Text Documents' drop-down menu in the save dialog box and change the setting to "All Files". You can then enter your filename without quotes.

Now that you've successfully created a simple PHP script that works, it's time to create the most famous PHP script! Make a call to the phpinfo() function and you'll see a lot of useful information about your system and setup such as available Predefined Variables, loaded PHP modules, and configuration settings. Take some time and review this important information.


Something Useful

Let's do something a bit more useful now. We are going to check what sort of browser the person viewing the page is using. In order to do that we check the user agent string that the browser sends as part of its HTTP request. This information is stored in a variable. Variables always start with a dollar-sign in PHP. The variable we are interested in right now is $_SERVER["HTTP_USER_AGENT"].

PHP Autoglobals Note: $_SERVER is a special reserved PHP variable that contains all web server information. It's known as an Autoglobal (or Superglobal). See the related manual page on Autoglobals for more information. These special variables were introduced in PHP 4.1.0. Before this time, we used the older $HTTP_*_VARS arrays instead, such as $HTTP_SERVER_VARS. Although deprecated, these older variables still exist. (See also the note on old code.)

To display this variable, we can simply do:

Exemplo 2-2. Printing a variable (Array element)

<?php echo $_SERVER["HTTP_USER_AGENT"]; ?>

A sample output of this script may be:
Mozilla/4.0 (compatible; MSIE 5.01; Windows NT 5.0)

There are many types of variables available in PHP. In the above example we printed an Array element. Arrays can be very useful.

$_SERVER is just one variable that's automatically made available to you by PHP. A list can be seen in the Reserved Variables section of the manual or you can get a complete list of them by creating a file that looks like this:

Exemplo 2-3. Show all predefined variables with phpinfo()

<?php phpinfo(); ?>

If you load up this file in your browser you will see a page full of information about PHP along with a list of all the variables available to you.

You can put multiple PHP statements inside a PHP tag and create little blocks of code that do more than just a single echo. For example, if we wanted to check for Internet Explorer we could do something like this:

Exemplo 2-4. Example using control structures and functions

<?php
if (strstr($_SERVER["HTTP_USER_AGENT"], "MSIE")) {
	echo "You are using Internet Explorer<br />";
}
?>

A sample output of this script may be:
You are using Internet Explorer<br />

Here we introduce a couple of new concepts. We have an if statement. If you are familiar with the basic syntax used by the C language this should look logical to you. If you don't know enough C or some other language where the syntax used above is used, you should probably pick up any introductory PHP book and read the first couple of chapters, or read the Language Reference part of the manual. You can find a list of PHP books at http://www.php.net/books.php.

The second concept we introduced was the strstr() function call. strstr() is a function built into PHP which searches a string for another string. In this case we are looking for "MSIE" inside $_SERVER["HTTP_USER_AGENT"]. If the string is found, the function returns TRUE and if it isn't, it returns FALSE. If it returns TRUE, the if statement evaluates to TRUE and the code within its {braces} is executed. Otherwise, it's not. Feel free to create similar examples, with if, else, and other functions such as strtoupper() and strlen(). Each related manual page contains examples too.

We can take this a step further and show how you can jump in and out of PHP mode even in the middle of a PHP block:

Exemplo 2-5. Mixing both HTML and PHP modes

<?php
if (strstr($_SERVER["HTTP_USER_AGENT"], "MSIE")) {
?>
<h3>strstr must have returned true</h3>
<center><b>You are using Internet Explorer</b></center>
<?php
} else {
?>
<h3>strstr must have returned false</h3>
<center><b>You are not using Internet Explorer</b></center>
<?php
}
?>

A sample output of this script may be:
<h3>strstr must have returned true</h3>
<center><b>You are using Internet Explorer</b></center>

Instead of using a PHP echo statement to output something, we jumped out of PHP mode and just sent straight HTML. The important and powerful point to note here is that the logical flow of the script remains intact. Only one of the HTML blocks will end up getting sent to the viewer depending on if strstr() returned TRUE or FALSE In other words, if the string MSIE was found or not.


Dealing with Forms

One of the most powerful features of PHP is the way it handles HTML forms. The basic concept that is important to understand is that any form element in a form will automatically be available to your PHP scripts. Please read the manual section on Variables from outside of PHP for more information and examples on using forms with PHP. Here's an example HTML form:

Exemplo 2-6. A simple HTML form

<form action="action.php" method="POST">
 Your name: <input type="text" name="name" />
 Your age: <input type="text" name="age" />
 <input type="submit">
</form>

There is nothing special about this form. It is a straight HTML form with no special tags of any kind. When the user fills in this form and hits the submit button, the action.php page is called. In this file you would have something like this:

Exemplo 2-7. Printing data from our form

Hi <?php echo $_POST["name"]; ?>.
You are <?php echo $_POST["age"]; ?> years old.

A sample output of this script may be:
Hi Joe.
You are 22 years old.

It should be obvious what this does. There is nothing more to it. The $_POST["name"] and $_POST["age"] variables are automatically set for you by PHP. Earlier we used the $_SERVER autoglobal, now above we just introduced the $_POST autoglobal which contains all POST data. Notice how the method of our form is POST. If we used the method GET then our form information would live in the $_GET autoglobal instead. You may also use the $_REQUEST autoglobal if you don't care the source of your request data. It contains a mix of GET, POST, COOKIE and FILE data. See also the import_request_variables() function.


Using old code with new versions of PHP

Now that PHP has grown to be a popular scripting language, there are more resources out there that have listings of code you can reuse in your own scripts. For the most part the developers of the PHP language have tried to be backwards compatible, so a script written for an older version should run (ideally) without changes in a newer version of PHP, in practice some changes will usually be needed.

Two of the most important recent changes that affect old code are:

  • The deprecation of the old $HTTP_*_VARS arrays (which need to be indicated as global when used inside a function or method). The following autoglobal arrays were introduced in PHP 4.1.0. They are: $_GET, $_POST, $_COOKIE, $_SERVER, $_ENV, $_REQUEST, and $_SESSION. The older $HTTP_*_VARS arrays, such as $HTTP_POST_VARS, still exist and have since PHP 3.

  • External variables are no longer registered in the global scope by default. In other words, as of PHP 4.2.0 the PHP directive register_globals is off by default in php.ini. The preferred method of accessing these values is via the autoglobal arrays mentioned above. Older scripts, books, and tutorials may rely on this directive being on. If on, for example, one could use $id from the URL http://www.example.com/foo.php?id=42. Whether on or off, $_GET['id'] is available.

For more details on these changes, see the section on predefined variables and links therein.


What's next?

With what you know now you should be able to understand most of the manual and also the various example scripts available in the example archives. You can also find other examples on the php.net websites in the links section: http://www.php.net/links.php.


Capítulo 3. Instalação


General Installation Considerations

Before installing first, you need to know what do you want to use PHP for. There are three main fields you can use PHP, as described in the What can PHP do? section:

  • Server-side scripting

  • Command line scripting

  • Client-side GUI applications

For the first and most common form, you need three things: PHP itself, a web server and a web browser. You probably already have a web browser, and depending on your operating system setup, you may also have a web server (eg. Apache on Linux or IIS on Windows). You may also rent webspace at a company. This way, you don't need to set up anything on your own, only write your PHP scripts, upload it to the server you rent, and see the results in your browser.

While setting up the server and PHP on your own, you have two choices for the method of connecting PHP to the server. For many servers PHP has a direct module interface (also called SAPI). These servers include Apache, Microsoft Internet Information Server, Netscape and iPlanet servers. Many other servers have support for ISAPI, the Microsoft module interface (OmniHTTPd for example). If PHP has no module support for your web server, you can always use it as a CGI processor. This means you set up your server to use the command line executable of PHP (php.exe on Windows) to process all PHP file requests on the server.

If you are also interested to use PHP for command line scripting (eg. write scripts autogenerating some images for you offline, or processing text files depending on some arguments you pass to them), you always need the command line executable. For more information, read the section about writing command line PHP applications. In this case, you need no server and no browser.

With PHP you can also write client side GUI applications using the PHP-GTK extension. This is a completely different approach than writing web pages, as you do not output any HTML, but manage windows and objects within them. For more information about PHP-GTK, please visit the site dedicated to this extension. PHP-GTK is not included in the official PHP distribution.

From now on, this section deals with setting up PHP for web servers on Unix and Windows with server module interfaces and CGI executables.

Downloading PHP, the source code, and binary distributions for Windows can be found at http://www.php.net/. We recommend you to choose a mirror nearest to you for downloading the distributions.


Unix/HP-UX installs

This section contains notes and hints specific to installing PHP on HP-UX systems.

Exemplo 3-1. Installation Instructions for HP-UX 10

From: paul_mckay@clearwater-it.co.uk
04-Jan-2001 09:49
(These tips are for PHP 4.0.4 and Apache v1.3.9) 

So you want to install PHP and Apache on a HP-UX 10.20 box? 

1. You need gzip, download a binary distribution from
http://hpux.connect.org.uk/ftp/hpux/Gnu/gzip-1.2.4a/gzip-1.2.4a-sd-10.20.depot.Z
uncompress the file and install using swinstall 

2. You need gcc, download a binary distribution from 
http://gatekeep.cs.utah.edu/ftp/hpux/Gnu/gcc-2.95.2/gcc-2.95.2-sd-10.20.depot.gz 
gunzip this file and install gcc using swinstall. 

3. You need the GNU binutils, you can download a binary distribution from 
http://hpux.connect.org.uk/ftp/hpux/Gnu/binutils-2.9.1/binutils-2.9.1-sd-10.20.depot.gz 
gunzip and install using swinstall. 

4. You now need bison, you can download a binary distribution from 
http://hpux.connect.org.uk/ftp/hpux/Gnu/bison-1.28/bison-1.28-sd-10.20.depot.gz 
install as above. 

5. You now need flex, you need to download the source from one of the
http://www.gnu.org mirrors. It is in the <filename>non-gnu</filename> directory of the ftp site. 
Download the file, gunzip, then tar -xvf it. Go into the newly created flex
directory and do a ./configure, then a make, and then a make install 

If you have errors here, it's probably because gcc etc. are not in your
PATH so add them to your PATH. 

Right, now into the hard stuff. 

6. Download the PHP and apache sources. 

7. gunzip and tar -xvf them. 

We need to hack a couple of files so that they can compile ok. 

8. Firstly the configure file needs to be hacked because it seems to lose
track of the fact that you are a hpux machine, there will be a
better way of doing this but a cheap and cheerful hack is to put 
    lt_target=hpux10.20 
on line 47286 of the configure script. 

9. Next, the Apache GuessOS file needs to be hacked. Under
apache_1.3.9/src/helpers change line 89 from 
    "echo "hp${HPUXMACH}-hpux${HPUXVER}"; exit 0" 
to: 
    "echo "hp${HPUXMACH}-hp-hpux${HPUXVER}"; exit 0" 
    
10. You cannot install PHP as a shared object under HP-UX so you must compile
it as a static, just follow the instructions at the Apache page. 

11. PHP and apache should have compiled OK, but Apache won't start. you need
to create a new user for Apache, eg www, or apache. You then change lines 252
and 253 of the conf/httpd.conf in Apache so that instead of 
    User nobody 
    Group nogroup 
you have something like 
    User www 
    Group sys 

This is because you can't run Apache as nobody under hp-ux. 
Apache and PHP should then work. 

Hope this helps somebody,
Paul Mckay.

Unix/Linux installs

This section contains notes and hints specific to installing PHP on Linux distributions.


Using Packages

Many Linux distributions have some sort of package installation system, such as RPM. This can assist in setting up a standard configuration, but if you need to have a different set of features (such as a secure server, or a different database driver), you may need to build PHP and/or your webserver. If you are unfamiliar with building and compiling your own software, it is worth checking to see whether somebody has already built a packaged version of PHP with the features you need.


Unix/Mac OS X installs

This section contains notes and hints specific to installing PHP on Mac OS X Server.


Using Packages

There are a few pre-packaged and pre-compiled versions of PHP for Mac OS X. This can help in setting up a standard configuration, but if you need to have a different set of features (such as a secure server, or a different database driver), you may need to build PHP and/or your web server yourself. If you are unfamiliar with building and compiling your own software, it's worth checking whether somebody has already built a packaged version of PHP with the features you need.


Compiling for OS X server

There are two slightly different versions of Mac OS X, client and server. The following is for OS X Server.

Exemplo 3-2. Mac OS X server install

1. Get the latest distributions of Apache and PHP
2. Untar them, and run the configure program on Apache like so.
    ./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 

4. You may also want to add this line: 
    setenv OPTIM=-O2 
    If you want the compiler to do some optimization. 
    
5. Next, go to the PHP 4 source directory and configure it. 
    ./configure --prefix=/usr \ 
    --sysconfdir=/etc \ 
    --localstatedir=/var \ 
    --mandir=/usr/share/man \ 
    --with-xml \ 
    --with-apache=/src/apache_1.3.12 

    If you have any other additions (MySQL, GD, etc.), be sure to add
    them here. For the --with-apache string, put in the path to your 
    apache source directory, for example "/src/apache_1.3.12". 
6. make
7. make install    
    This will add a directory to your Apache source directory under
    src/modules/php4.
    
8. Now, reconfigure Apache to build in 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 

    You may get a message telling you that libmodphp4.a is out of date.
    If so, go to the src/modules/php4 directory inside your apache
    source directory and run this command: 

    ranlib libmodphp4.a 

    Then go back to the root of the apache source directory and run the
    above configure command again. That'll bring the link table up to
    date. 

9. make

10. make install

11. copy and rename the php.ini-dist file to your "bin" directory from your
    PHP 4 source directory:
    cp php.ini-dist /usr/local/bin/php.ini 

    or (if your don't have a local directory) 

    cp php.ini-dist /usr/bin/php.ini

Compiling for MacOS X client

Those tips are graciously provided by Marc Liyanage.

The PHP module for the Apache web server included in Mac OS X. This version includes support for the MySQL and PostgreSQL databases.

NOTE: Be careful when you do this, you could screw up your Apache web server!

Do this to install:

  • 1. Open a terminal window

  • 2. Type "wget http://www.diax.ch/users/liyanage/software/macosx/libphp4.so.gz", wait for download to finish

  • 3. Type "gunzip libphp4.so.gz"

  • 4. Type "sudo apxs -i -a -n php4 libphp4.so"

Now type "sudo open -a TextEdit /etc/httpd/httpd.conf" TextEdit will open with the web server configuration file. Locate these two lines towards the end of the file: (Use the Find command)
#AddType application/x-httpd-php .php 
   #AddType application/x-httpd-php-source .phps
Remove the two hash marks (#), then save the file and quit TextEdit.

Finally, type "sudo apachectl graceful" to restart the web server.

PHP should now be up and running. You can test it by dropping a file into your "Sites" folder which is called "test.php". Into that file, write this line: "<?php phpinfo() ?>".

Now open up 127.0.0.1/~your_username/test.php in your web browser. You should see a status table with information about the PHP module.


Unix/OpenBSD installs

This section contains notes and hints specific to installing PHP on OpenBSD 3.2.


Using Binary Packages

Using binary packages to install PHP on OpenBSD is the recommended and simplest method. The core package has been separated from the various modules, and each can be installed and removed independently from the others. The files you need can be found on your OpenBSD CD or on the FTP site.

The main package you need to install is php4-core-4.2.3.tgz, which contains the basic engine (plus gettext and iconv). Next, take a look at the module packages, such as php4-mysql-4.2.3.tgz or php4-imap-4.2.3.tgz. You need to use the phpxs command to activate and deactivate these modules in your php.ini file.

Exemplo 3-3. OpenBSD Package Install Example

# pkg_add php4-core-4.2.3.tgz
# /usr/local/sbin/phpxs -s
# cp /usr/local/share/doc/php4/php.ini-recommended /var/www/conf/php.ini
  (add in mysql)
# pkg_add php4-mysql-4.2.3.tgz
# /usr/local/sbin/phpxs -a mysql
  (add in imap)
# pkg_add php4-imap-4.2.3.tgz
# /usr/local/sbin/phpxs -a imap
  (remove mysql as a test)
# pkg_delete php4-mysql-4.2.3
# /usr/local/sbin/phpxs -r mysql
  (install the PEAR libraries)
# pkg_add php4-pear-4.2.3.tgz

Read the packages(7) manual page for more information about binary packages on OpenBSD.


Using Ports

You can also compile up PHP from source using the ports tree. However, this is only recommended for users familiar with OpenBSD. The PHP4 port is split into three sub-directories: core, extensions and pear. The extensions directory generates sub-packages for all of the supported PHP modules. If you find you do not want to create some of these modules, use the no_* FLAVOR. For example, to skip building the imap module, set the FLAVOR to no_imap.


Older Releases

Older releases of OpenBSD used the FLAVORS system to compile up a statically linked PHP. Since it is hard to generate binary packages using this method, it is now deprecated. You can still use the old stable ports trees if you wish, but they are unsupported by the OpenBSD team. If you have any comments about this, the current maintainer for the port is Anil Madhavapeddy.


Unix/Solaris installs

This section contains notes and hints specific to installing PHP on Solaris systems.


Required software

Solaris installs often lack C compilers and their related tools. The required software is as follows:

  • gcc (recommended, other C compilers may work)

  • make

  • flex

  • bison

  • m4

  • autoconf

  • automake

  • perl

  • gzip

  • tar

  • GNU sed

In addition, you will need to install (and possibly compile) any additional software specific to your configuration, such as Oracle or MySQL.


Using Packages

You can simplify the Solaris install process by using pkgadd to install most of your needed components.


Installation on UNIX systems

This section will guide you through the general configuration and installation of PHP on Unix systems. Be sure to investigate any sections specific to your platform or web server before you begin the process.

Prerequisite knowledge and software:

  • Basic UNIX skills (being able to operate "make" and a C compiler, if compiling)

  • An ANSI C compiler (if compiling)

  • flex (for compiling)

  • bison (for compiling)

  • A web server

  • Any module specific components (such as gd, pdf libs, etc.)

There are several ways to install PHP for the Unix platform, either with a compile and configure process, or through various pre-packaged methods. This documentation is mainly focused around the process of compiling and configuring PHP.

The initial PHP setup and configuration process is controlled by the use of the commandline options of the configure script. This page outlines the usage of the most common options, but there are many others to play with. Check out the Complete list of configure options for an exhaustive rundown. There are several ways to install PHP:


Apache Module Quick Reference

PHP can be compiled in a number of different ways, but one of the most popular is as an Apache module. The following is a quick installation overview.

Exemplo 3-4. Quick Installation Instructions for PHP 4 (Apache Module Version)

1.  gunzip apache_1.3.x.tar.gz
2.  tar xvf apache_1.3.x.tar
3.  gunzip php-x.x.x.tar.gz
4.  tar xvf php-x.x.x.tar
5.  cd apache_1.3.x
6.  ./configure --prefix=/www
7.  cd ../php-x.x.x
8.  ./configure --with-mysql --with-apache=../apache_1.3.x --enable-track-vars
9.  make
10. make install
11. cd ../apache_1.3.x
12. ./configure --activate-module=src/modules/php4/libphp4.a
13. make
14. make install
15. cd ../php-x.x.x
16. cp php.ini-dist /usr/local/lib/php.ini
17. Edit your httpd.conf or srm.conf file and add: 
      AddType application/x-httpd-php .php

18. Use your normal procedure for restarting the Apache server. (You must
    stop and restart the server, not just cause the server to reload by
    use a HUP or USR1 signal.)

Building

When PHP is configured, you are ready to build the CGI executable. The command make should take care of this. If it fails and you can't figure out why, see the Problems section.


Installation on Windows systems

This section applies to Windows 95/98/Me and Windows NT/2000/XP. Do not expect PHP to work on 16 bit platforms such as Windows 3.1. Sometimes we refer to the supported Windows platforms as Win32.

There are two main ways to install PHP for Windows: either manually or by using the InstallShield installer.

If you have Microsoft Visual Studio, you can also build PHP from the original source code.

Once you have PHP installed on your Windows system, you may also want to load various extensions for added functionality.


Windows InstallShield

The Windows PHP installer available from the downloads page at http://www.php.net/downloads.php, this installs the CGI versionof PHP and, for IIS, PWS, and Xitami, configures the web server as well.

Nota: Also note, that while the InstallShield installer is an easy way to make PHP work, it is restricted in many aspects, as automatic setup of extensions for example is not supported. The whole set of supported extensions is only available by downloading the zip binary distribution.

Install your selected HTTP server on your system and make sure that it works.

Run the executable installer and follow the instructions provided by the installation wizard. Two types of installation are supported - standard, which provides sensible defaults for all the settings it can, and advanced, which asks questions as it goes along.

The installation wizard gathers enough information to set up the php.ini file and configure the web server to use PHP. For IIS and also PWS on NT Workstation, a list of all the nodes on the server with script map settings is displayed, and you can choose those nodes to which you wish to add the PHP script mappings.

Once the installation has completed the installer will inform you if you need to restart your system, restart the server, or just start using PHP.

Atenção

Be aware, that this setup of PHP is not secure. If you would like to have a secure PHP setup, you'd better go on the manual way, and set every option carefully. This automatically working setup gives you an instantly working PHP installation, but it is not meant to be used on online servers.


Manual Installation Steps

This install guide will help you manually install and configure PHP on your Windows webserver. You need to download the zip binary distribution from the downloads page at http://www.php.net/downloads.php. The original version of this guide was compiled by Bob Silva, and can be found at http://www.umesd.k12.or.us/php/win32install.html.

This guide provides manual installation support for:

  • Personal Web Server 3 and 4 or newer

  • Internet Information Server 3 and 4 or newer

  • Apache 1.3.x

  • OmniHTTPd 2.0b1 and up

  • Oreilly Website Pro

  • Xitami

  • Netscape Enterprise Server, iPlanet

PHP 4 for Windows comes in two flavours - a CGI executable (php.exe), and several SAPI modules (for example: php4isapi.dll). The latter form is new to PHP 4, and provides significantly improved performance and some new functionality. There is also a CLI version which is further described in the commandline chapter.

Atenção

The SAPI modules have been significantly improved in the 4.1 release, however, you may find that you encounter possible server errors or other server modules such as ASP failing, in older systems.

If you choose one of the SAPI modules and use Windows 95, be sure to download the DCOM update from the Microsoft DCOM pages. For the ISAPI module, an ISAPI 4.0 compliant Web server is required (tested on IIS 4.0, PWS 4.0 and IIS 5.0). IIS 3.0 is NOT supported. You should download and install the Windows NT 4.0 Option Pack with IIS 4.0 if you want native PHP support.

The following steps should be performed on all installations before the server specific instructions.

  • Extract the distribution file to a directory of your choice. c:\php\ is a good start. You probably do not want to use a path in which spaces are included (for example: c:\program files\php is not a good idea). Some web servers will crash if you do.

  • You need to ensure that the DLLs which PHP uses can be found. The precise DLLs involved depend on which web server you use and whether you want to run PHP as a CGI or as a server module. php4ts.dll is always used. If you are using a server module (e.g. ISAPI or Apache) then you will need the relevant DLL from the sapi folder. If you are using any PHP extension DLLs then you will need those as well. To make sure that the DLLs can be found, you can either copy them to the system directory (e.g. winnt/system32 or windows/system) or you can make sure that they live in the same directory as the main PHP executable or DLL your web server will use (e.g. php.exe, php4apache.dll).

    The PHP binary, the SAPI modules, and some extensions rely on external DLLs for execution. Make sure that these DLLs in the distribution exist in a directory that is in the Windows PATH. For example, if you enable php_oci8.dll in php.ini then you'll want to make sure the Oracle home directory can be seen in PATH so PHP can find oci.dll.

    The best bet to do it is to copy the files below into your system directory, which is typically:

    c:\windows\system for Windows 9x/ME
    c:\winnt\system32 for Windows NT/2000
    c:\windows\system32 for Windows XP

    The files to copy are:

    php4ts.dll, if it already exists there, overwrite it
    The files in your distribution's 'dlls' directory. If you have them already installed on your system, overwrite them only if something doesn't work correctly (Before overwriting them, it is a good idea to make a backup of them, or move them to another folder - just in case something goes wrong).

    Download the latest version of the Microsoft Data Access Components (MDAC) for your platform, especially if you use Microsoft Windows 9x/NT4. MDAC is available at http://www.microsoft.com/data/.

  • Copy your chosen ini file (see below) to your '%WINDOWS%' directory on Windows 9x/Me or to your '%SYSTEMROOT%' directory under Windows NT/2000/XP and rename it to php.ini. Your '%WINDOWS%' or '%SYSTEMROOT%' directory is typically:

    c:\windows for Windows 9x/ME/XP
    c:\winnt or c:\winnt40 for NT/2000 servers

    There are two ini files distributed in the zip file, php.ini-dist and php.ini-optimized. We advise you to use php.ini-optimized, because we optimized the default settings in this file for performance, and security. The best is to study all the ini settings and set every element manually yourself. If you would like to achieve the best security, then this is the way for you, although PHP works fine with these default ini files.

  • Edit your new php.ini file:

    • You will need to change the 'extension_dir' setting to point to your php-install-dir, or where you have placed your php_*.dll files. Please do not forget the last backslash. ex: c:\php\extensions\

    • If you are using OmniHTTPd, do not follow the next step. Set the 'doc_root' to point to your webservers document_root. For example: c:\apache\htdocs or c:\webroot

    • Choose which extensions you would like to load when PHP starts. See the section about Windows extensions, about how to set up one, and what is already built in. Note that on a new installation it is advisable to first get PHP working and tested without any extensions before enabling them in php.ini.

    • On PWS and IIS, you can set the browscap.ini to point to: c:\windows\system\inetsrv\browscap.ini on Windows 9x/Me, c:\winnt\system32\inetsrv\browscap.ini on NT/2000, and c:\windows\system32\inetsrv\browscap.ini on XP.

    • Note that the mibs directory supplied with the Windows distribution contains support files for SNMP. This directory should be moved to DRIVE:\usr\mibs (DRIVE being the drive where PHP is installed.)

    • If you're using NTFS on Windows NT, 2000 or XP, make sure that the user running the webserver has read permissions to your php.ini (e.g. make it readable by Everyone).

  • For PWS give execution permission to the webroot:

    • Start PWS Web Manager

    • Edit Properties of the "Home"-Directory

    • Select the "execute"-Checkbox


Building from source

Before getting started, it is worthwhile answering the question: "Why is building on Windows so hard?" Two reasons come to mind:

  1. Windows does not (yet) enjoy a large community of developers who are willing to freely share their source. As a direct result, the necessary investment in infrastructure required to support such development hasn't been made. By and large, what is available has been made possible by the porting of necessary utilities from Unix. Don't be surprised if some of this heritage shows through from time to time.

  2. Pretty much all of the instructions that follow are of the "set and forget" variety. So sit back and try follow the instructions below as faithfully as you can.


Requisitos

To compile and build PHP you need a Microsoft Development Environment. Microsoft Visuaul C++ 6.0 is recommended. To extract the downloaded files you need a extraction utilitiy (e.g.: Winzip). If you don't already have an unzip utility, you can get a free version from InfoZip.

Before you get started, you have to download...

Finally, you are going to need the source to PHP 4 itself. You can get the latest development version using anonymous CVS, a snapshot or the most recent released source tarball.


Putting it all together

After downloading the required packages you have to extract them in a proper place.

  • Create a working directory where all files end up after extracting, e.g: c:\work.

  • Create the directory win32build under your working directory (c:\work) and unzip win32build.zip into it.

  • Create the directory bindlib_w32 under your working directory (c:\work) and unzip bindlib_w32.zip into it.

  • Extract the downloaded PHP source code into your working directory (c:\work).

Following this steps your directory structure looks like this:

+--c:\work
|  |
|  +--bindlib_w32
|  |  |
|  |  +--arpa
|  |  |
|  |  +--conf
|  |  |
|  |  +--...
|  |
|  +--php-4.x.x
|  |  |
|  |  +--build
|  |  |
|  |  +--...
|  |  |
|  |  +--win32
|  |  |
|  |  +--...
|  |
|  +--win32build
|  |  |
|  |  +--bin
|  |  |
|  |  +--include
|  |  |
|  |  +--lib

Create the directories c:\usr\local\lib. Copy bison.simple from c:\work\win32build\bin to c:\usr\local\lib.

Nota: Cygwin users may omit the last step. A properly installed Cygwin environment provides the mandatory files bison.simple and bison.exe.


Configure MVC ++

The next step is to configure MVC ++ to prepare for compiling. Launch Microsoft Visual C++, and from the menu select Tools => Options. In the dialog, select the directories tab. Sequentially change the dropdown to Executables, Includes, and Library files. Your entries should look like this:

  • Executable files: c:\work\win32build\bin, Cygwin users: cygwin\bin

  • Include files: c:\work\win32build\include

  • Library files: c:\work\win32build\lib


Build resolv.lib

You must build the resolv.lib library. Decide whether you want to have debug symbols available (bindlib - Win32 Debug) or not (bindlib - Win32 Release). Build the appropriate configuration:

  • For GUI users, launch VC++, and then select File => Open Workspace, navigate to c:\work\bindlib_w32and select bindlib.dsw. Then select Build=>Set Active Configuration and select the desired configuration. Finally select Build=>Rebuild All.

  • For command line users, make sure that you either have the C++ environment variables registered, or have run vcvars.bat, and then execute one of the following commands:

    • msdev bindlib.dsp /MAKE "bindlib - Win32 Debug"

    • msdev bindlib.dsp /MAKE "bindlib - Win32 Release"

At this point, you should have a usable resolv.lib in either your c:\work\bindlib_w32\Debug or Release subdirectories. Copy this file into your c:\work\win32build\lib directory over the file by the same name found in there.


Compiling

The best way to get started is to build the CGI version.

  • For GUI users, launch VC++, and then select File => Open Workspace and select c:\work\php-4.x.x\win32\php4ts.dsw . Then select Build=>Set Active Configuration and select the desired configuration, either php4ts - Win32 Debug_TS or php4ts - Win32 Release_TS. Finally select Build=>Rebuild All.

  • For command line users, make sure that you either have the C++ environment variables registered, or have run vcvars.bat, and then execute one of the following commands from the c:\work\php-4.x.x\win32 directory:

    • msdev php4ts.dsp /MAKE "php4ts - Win32 Debug_TS"

    • msdev php4ts.dsp /MAKE "php4ts - Win32 Release_TS"

    • At this point, you should have a usable php.exe in either your c:\work\php-4.x.x.\Debug_TS or Release_TS subdirectories.

It is possible to do minor customization to the build process by editing the main/config.win32.h.in file. For example you can change the builtin extensions, the location of php.ini and

Next you may want to build the CLI version which is designed to use PHP from the command line. The steps are the same as for building the CGI version, except you have to select the php4ts_cli - Win32 Debug_TS or php4ts_cli - Win32 Release_TS project file. After a succcessfull compiling run you will find the php.exe in either the directory Release_TS\cli\ or Debug_TS\cli\.

Nota: If you want to use PEAR and the comfortable command line installer, the CLI-SAPI is mandatory. For more information about PEAR and the installer read the documantation at the PEAR website.

In order to build the SAPI module (php4isapi.dll for integrating PHP with Microsoft IIS, set your active configuration to php4isapi-whatever-config and build the desired dll.


Installation of Windows extensions

After installing PHP and a webserver on Windows, you will probably want to install some extensions for added functionality. The following table describes some of the extensions available. You can choose which extensions you would like to load when PHP starts by uncommenting the: 'extension=php_*.dll' lines in php.ini. You can also load a module dynamically in your script using dl().

The DLLs for PHP extensions are prefixed with 'php_' in PHP 4 (and 'php3_' in PHP 3). This prevents confusion between PHP extensions and their supporting libraries.

Nota: In PHP 4.0.6 BCMath, Calendar, COM, FTP, MySQL, ODBC, PCRE, Session, WDDX and XML support is built in. You don't need to load any additional extensions in order to use these functions. See your distributions README.txt or install.txt for a list of built in modules.

Nota: Some of these extensions need extra DLLs to work. Couple of them can be found in the distribution package, in the 'dlls' folder but some, for example Oracle (php_oci8.dll) require DLLs which are not bundled with the distribution package.

Copy the bundled DLLs from 'DLLs' folder to your Windows PATH, safe places are:

c:\windows\system for Windows 9x/Me
c:\winnt\system32 for Windows NT/2000
c:\windows\system32 for Windows XP

If you have them already installed on your system, overwrite them only if something doesn't work correctly (Before overwriting them, it is a good idea to make a backup of them, or move them to another folder - just in case something goes wrong).

Tabela 3-1. PHP Extensions

Extension Description Notes
php_bz2.dll bzip2 compression functions None
php_calendar.dll Calendar conversion functions Built in since PHP 4.0.3
php_cpdf.dll ClibPDF functions None
php_crack.dll Crack functions None
php3_crypt.dll Crypt functions unknown
php_ctype.dll ctype family functions None
php_curl.dll CURL, Client URL library functions Requires: libeay32.dll, ssleay32.dll (bundled)
php_cybercash.dll Cybercash payment functions None
php_db.dll DBM functions Deprecated. Use DBA instead (php_dba.dll)
php_dba.dll DBA: DataBase (dbm-style) Abstraction layer functions None
php_dbase.dll dBase functions None
php3_dbm.dll Berkeley DB2 library unknown
php_domxml.dll DOM XML functions Requires: libxml2.dll (bundled)
php_dotnet.dll .NET functions None
php_exif.dll Read EXIF headers from JPEG None
php_fbsql.dll FrontBase functions None
php_fdf.dll FDF: Forms Data Format functions. Requires: fdftk.dll (bundled)
php_filepro.dll filePro functions Read-only access
php_ftp.dll FTP functions Built-in since PHP 4.0.3
php_gd.dll GD library image functions None
php_gd2.dll GD2 library image functions None
php_gettext.dll Gettext functions Requires: gnu_gettext.dll (bundled)
php_hyperwave.dll HyperWave functions None
php_iconv.dll ICONV characterset conversion Requires: iconv-1.3.dll (bundled)
php_ifx.dll Informix functions Requires: Informix libraries
php_iisfunc.dll IIS management functions None
php_imap.dll IMAP POP3 and NNTP functions PHP 3: php3_imap4r1.dll
php_ingres.dll Ingres II functions Requires: Ingres II libraries
php_interbase.dll InterBase functions Requires: gds32.dll (bundled)
php_java.dll Java extension Requires: jvm.dll (bundled)
php_ldap.dll LDAP functions Requires: libsasl.dll (bundled)
php_mhash.dll Mhash Functions None
php_ming.dll Ming functions for Flash None
php_msql.dll mSQL functions Requires: msql.dll (bundled)
php3_msql1.dll mSQL 1 client unknown
php3_msql2.dll mSQL 2 client unknown
php_mssql.dll MSSQL functions Requires: ntwdblib.dll (bundled)
php3_mysql.dll MySQL functions Built-in in PHP 4
php3_nsmail.dll Netscape mail functions unknown
php3_oci73.dll Oracle functions unknown
php_oci8.dll Oracle 8 functions Requires: Oracle 8 client libraries
php_openssl.dll OpenSSL functions Requires: libeay32.dll (bundled)
php_oracle.dll Oracle functions Requires: Oracle 7 client libraries
php_pdf.dll PDF functions None
php_pgsql.dll PostgreSQL functions None
php_printer.dll Printer functions None
php_xslt.dll XSLT functions Requires: sablot.dll (bundled)
php_snmp.dll SNMP get and walk functions NT only!
php_sybase_ct.dll Sybase functions Requires: Sybase client libraries
php_yaz.dll YAZ functions None
php_zlib.dll ZLib compression functions None


Servers-CGI/Commandline

The default is to build PHP as a CGI program. This creates a commandline interpreter, which can be used for CGI processing, or for non-web-related PHP scripting. If you are running a web server PHP has module support for, you should generally go for that solution for performance reasons. However, the CGI version enables Apache users to run different PHP-enabled pages under different user-ids. Please make sure you read through the Security chapter if you are going to run PHP as a CGI.

As of PHP 4.3.0, some important additions have happened to PHP. A new SAPI named CLI also exists and it has the same name as the CGI binary. What is installed at {PREFIX}/bin/php depends on your configure line and this is described in detail in the manual section named Using PHP from the command line. For further details please read that section of the manual.


Testing

If you have built PHP as a CGI program, you may test your build by typing make test. It is always a good idea to test your build. This way you may catch a problem with PHP on your platform early instead of having to struggle with it later.


Benchmarking

If you have built PHP 3 as a CGI program, you may benchmark your build by typing make bench. Note that if Safe Mode is on by default, the benchmark may not be able to finish if it takes longer then the 30 seconds allowed. This is because the set_time_limit() can not be used in safe mode. Use the max_execution_time configuration setting to control this time for your own scripts. make bench ignores the configuration file.

Nota: make bench is only available for PHP 3.


Using Variables

Some server supplied enviroment variables are not defined in the current CGI/1.1 specification. Only the following variables are defined there; everything else should be treated as 'vendor extensions': 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 and SERVER_SOFTWARE


Servidores-Apache

Esta seção contém notas e dicas específicas para instalações do PHP em Apache, tanto para versões Unix quanto para Windows.


Detalhes ao instalar o PHP com Apache no Unix

Você pode selecionar argumentos para adicionar ao configure na linha 10 abaixo através da Lista completa de opções do configure . 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 3-5. Instruções de Instalação (Apache Versão de Módulo Compartilhado) para PHP 4

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. ./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 tres passos. Você somente precisará
  reiniciar o apache para o novo módulo funcionar. Não será necessário recompilar
  o Apache.

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

14. Edite o seu arquivo httpd.conf ou srm.conf e verifique que estas linas estejam presentes
    e não estejam comentadas:
  
   AddType application/x-httpd-php .php

   LoadModule php4_module        libexec/libphp4.so
 
  Você pode escolher qualquer extensão aqui. .php é simplesmente uma sugestão
  que nós damos. Você também pode incluir .html, e .php3 pode ser adicionado para 
  compatibilidade com versões antigas.
 
  O caminho no lado direito do comando LoadModule deve apontar para para o caminho
  do módulo PHP do seu sistema. O comando acima está correto para os passos
  mostrados acima.

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

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.

1. Inúmeras variações de sistemas Linux:
/etc/rc.d/init.d/httpd restart

2. Usando os scripts apachectl:
/caminho/para/apachectl stop
/caminho/para/apachectl start

3. httpdctl and httpsdctl (Usando OpenSSL), igual ao apachectl:
/caminho/para/httpsdctl stop
/caminho/para/httpsdctl start

4. Usando mod_ssl, ou outro servidor SSL, você pode querer iniciar ou
reiniciar manualmente:
/caminho/para/apachectl stop
/caminho/para/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

Isto irá criar uma biblioteca compartilhada libphp4.so que é carregada com o Apache usando uma linha LoadModule no arquivo httpd.conf do Apache. O suporte ao PostgreSQL está embutido dentro da biblioteca compartilhada libphp4.so.

./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=/caminho/para/apache_source --with-pgsql

Isto irá criar uma biblioteca libmodphp4.a, o arquivo mod_php4.c e vários arquivos dependentes e copiará eles para o diretório src/modules/php4 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/php4/libphp4.a e o sistema de compilação do Apache irá criar o arquivo libphp4.a e fará um link estático dentro do binário httpd. 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=/caminho/para/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.


Instalando o PHP em Windows com Apache 1.3.x

Existem duas maneiras de configurar o PHP para funcionar com o Apache 1.3.x em Windows. Uma é usando o binário CGI (php.exe), a outra é usando a bliblioteca compartilhada (DLL) como módulo para o Apache (SAPI). Nos dois casos você precisará parar o Servidor Apache, e editar seu arquivo srm.conf ou httpd.conf para configurar o Apache para funcionar com o PHP.

Vale deixar claro aqui que agora o módulo SAPI tornou-se muito mais estável no windows, nós recomendamos o seu uso em vez do binário CGI, por ele ser mais transparente e seguro.

Embora possa ter algumas variações de configurar o PHP com Apache, elas são fáceis suficientemente para ser feitas por um usuário sem experiência. Por favor consulte os Documentos do Apache para maiores diretivas de configuração.

Se você descompactou o pacote do PHP para c:\php\ como descrito na seção Passos de Instalação Manual, você precisará inserir estas linhas no seu arquivo de configuração do Apache para configurar o binário CGI:

  • ScriptAlias /php/ "c:/php/"

  • AddType application/x-httpd-php .php .phtml

  • Action application/x-httpd-php "/php/php.exe"

Note que a segunda linha na lista acima pode ser encontrada em versões atuais do arquivo httpd.conf, mas elas estão comentadas. Lembre-se também de trocar o caminho c:/php/ pelo caminho atual do PHP instalado em seu sistema.

Atenção

Usando a configuração do binário CGI, o seu servidor está aberto a vários tipos possívels de ataque. Por favor leia nossa seção Segurança em CGI para aprender como defender-se de ataques.

Se você preferir usar o PHP como um módulo no Apache, esteja certo de mover o arquivo php4ts.dll para o diretório windows/system (em Windows 9x/Me) ou winnt/system32 (para Windows NT/2000/XP), sobrescrevendo qualquer arquivo antigo. Então você deverá adiciomar as duas linhas a seguir em seu arquivo de configuração do Apache:

  • LoadModule php4_module c:/php/sapi/php4apache.dll

  • AddType application/x-httpd-php .php .phtml

Após mudar o arquivo de configuração, lembre-se de reiniciar o servidor, por exemplo, NET STOP APACHE seguido por NET START APACHE, se você roda o Apache como um Serviço Windows, ou use os atalhos comuns no menu iniciar.

Nota: Você irá descobrir que após usar o windows installer para Apache que você deverá definir a diretriz AddModule para mod_php4.c no arquivo de configuração (httpd.conf). Isto pode ser feito adicionando AddModule mod_php4.c para a lista AddModule, perto do começo do arquivo de configuração. Isto é especialmente importante se a diretriz ClearModuleList estiver definida. Falhas ao configurar isto pode resultar em não definir o PHP como um módulo para Apache.

Existem duas maneiras para você poder usar a função de destaque de códigos fonte, contudo dependerá da maneira de sua instalação para esta função funcionar corretamente. Se você configurou o Apache para usar o PHP como um módulo SAPI, então adicionando a seguinte linha ao seu arquivo de configuração você poderá usar esta função: AddType application/x-httpd-php-source .phps

Se você escolher configurar o Apache para usar o PHP como um binário CGI, você precisará usar a função show_source(). Para fazer isto simplesmente crie um arquivo de script PHP e adicione este código: <?php show_source ("php_original_script.php"); ?>. Troque php_original_script.php pelo nome do arquivo que você quer que seja mostrado o código fonte.

Nota: No Apache em Windows todas as barras invertidas em uma definição de caminho como descrito aqui "c:\diretorio\arquivo.ext", devem ser convertidas para barras normais, como descrito aqui "c:/diretorio/arquivo.ext".


Servers-Apache 2.0

This section contains notes and hints specific to Apache 2.0 installs of PHP, both for Unix and Windows versions.

Atenção

Do not use Apache 2.0 and PHP in a production environment neither on Unix nor on Windows.

You are highly encouraged to take a look at the Apache Documentation to get a basic understanding of the Apache 2.0 Server.


PHP and Apache 2.0 compatibility notes

The following versions of PHP are known to work with the most recent version of Apache 2.0:

These versions of PHP are compatible to Apache 2.0.40 and later.

Nota: Apache 2.0 SAPI-support started with PHP 4.2.0. PHP 4.2.3 its known to work in conjunction with Apache 2.0.39. Don't try to use this version of PHP with any other version of Apache. We do not recommend to use PHP 4.2.3 along with Apache 2.0.39.

All mentioned versions of PHP will work still with Apache 1.3.x.


PHP and Apache 2 on Linux

Download the most recent version of Apache 2.0 and a fitting PHP version from the above mentioned places. This quick guide covers only the basics to get started with Apache 2.0 and PHP. For more information read the Apache Documentation. The version numbers have been omitted here, to ensure the instructions are not incorrect. You will need to replace the 'NN' here with the correct values from your files.

Exemplo 3-6. Installation Instructions (Apache 2 Shared Module Version)

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

    Now you have Apache 2.0.NN available under /usr/local/apache2,
    configured with loadable module support and the standard MPM prefork.
    To test the installation use your normal procedure for starting
    the Apache server, e.g.:
    /usr/local/apache2/bin/apachectl start
    and stop the server to go on with the configuration for PHP:
    /usr/local/apache2/bin/apachectl stop.

9.  cd ../php4-NN
10. ./configure --with-apxs2=/usr/local/apache2/bin/apxs
11. make
12. make install
13. cp php.ini-dist /usr/local/lib/php.ini

    Edit your php.ini file to set PHP options. If
    you prefer this file in another location, use
    --with-config-file-path=/path in step 10.

14. Edit your httpd.conf file and check that these lines are
    present:
  
   LoadModule php4_module modules/libphp4.so
   AddType application/x-httpd-php .php

  You can choose any extension you wish here. .php is simply the one
  we suggest.
 
  The path on the right hand side of the LoadModule statement must point
  to the path of the PHP module on your system. The above statement is
  correct for the steps shown above.

15. Use your normal procedure for starting the Apache server, e.g.:
   /usr/local/apache2/bin/apachectl start

Following the steps above you will have a running Apache 2.0 with support for PHP as SAPI module. Of course there are many more configuration options available for both, Apache and PHP. For more information use ./configure --help in the corresponding source tree. In case you wish to build a multithreaded version of Apache 2.0 you must overwrite the standard MPM-Module prefork either with worker or perchild. To do so append to your configure line in step 6 above either the option --with-mpm=worker or --with-mpm=perchild. Take care about the consequences and understand what you are doing. For more information read the Apache documentation about the MPM-Modules.

Nota: To build a multithreaded version of Apache your system must support threads. This also implies to build PHP with experimental Zend Thread Safety (ZTS). Therefore not all extensions might be available. The recommended setup is to build Apache with the standard prefork MPM-Module.


PHP and Apache 2.0 on Windows

Consider to read the Windows specific notes for Apache 2.0.

Atenção

Apache 2.0 is designed to run on Windows NT 4.0, Windows 2000 or Windows XP. At this time, support for Windows 9x is incomplete. Apache 2.0 is not expected to work on those platforms at this time.

Download the most recent version of Apache 2.0 and a fitting PHP version from the above mentioned places. Follow the Manual Installation Steps and come back to go on with the integration of PHP and Apache.

There are two ways to set up PHP to work with Apache 2.0 on Windows. One is to use the CGI binary the other is to use the Apache module DLL. In either case you need to stop the Apache server, and edit your httpd.conf to configure Apache to work with PHP.

You need to insert these three lines to your Apache httpd.conf configuration file to set up the CGI binary:

Exemplo 3-7. PHP and Apache 2.0 as CGI

ScriptAlias /php/ "c:/php/"
AddType application/x-httpd-php .php
Action application/x-httpd-php "/php/php.exe"

If you would like to use PHP as a module in Apache 2.0, be sure to move php4ts.dll to winnt/system32 (for Windows NT/2000) or windows/system32 (for Windows XP), overwriting any older file. You need to insert these two lines to your Apache httpd.conf configuration file to set up the PHP-Module for Apache 2.0:

Exemplo 3-8. PHP and Apache 2.0 as Module

LoadModule php4_module c:/php/sapi/php4apache2.dll
AddType application/x-httpd-php .php

Nota: Remember to substitute the c:/php/ for your actual path to PHP in the above examples.

Atenção

Don't mix up your installation with dll files from different PHP versions . You have the only choice to use the dll's and extensions that ship with your downloaded PHP version.


Servers-Caudium

PHP 4 can be built as a Pike module for the Caudium webserver. Note that this is not supported with PHP 3. Follow the simple instructions below to install PHP 4 for Caudium.

Exemplo 3-9. Caudium Installation Instructions

1.  Make sure you have Caudium installed prior to attempting to
    install PHP 4. For PHP 4 to work correctly, you will need Pike
    7.0.268 or newer. For the sake of this example we assume that
    Caudium is installed in /opt/caudium/server/.
2.  Change directory to php-x.y.z (where x.y.z is the version number).
3.  ./configure --with-caudium=/opt/caudium/server
4.  make
5.  make install
6.  Restart Caudium if it's currently running.
7.  Log into the graphical configuration interface and go to the
    virtual server where you want to add PHP 4 support.
8.  Click Add Module and locate and then add the PHP 4 Script Support module.
9.  If the documentation says that the 'PHP 4 interpreter isn't
    available', make sure that you restarted the server. If you did
    check /opt/caudium/logs/debug/default.1 for any errors related to
    <filename>PHP4.so</filename>. Also make sure that 
    <filename>caudium/server/lib/[pike-version]/PHP4.so</filename>
    is present.
10. Configure the PHP Script Support module if needed.

You can of course compile your Caudium module with support for the various extensions available in PHP 4. See the complete list of configure options for an exhaustive rundown.

Nota: When compiling PHP 4 with MySQL support you must make sure that the normal MySQL client code is used. Otherwise there might be conflicts if your Pike already has MySQL support. You do this by specifying a MySQL install directory the --with-mysql option.


Servers-fhttpd

To build PHP as an fhttpd module, answer "yes" to "Build as an fhttpd module?" (the --with-fhttpd=DIR option to configure) and specify the fhttpd source base directory. The default directory is /usr/local/src/fhttpd. If you are running fhttpd, building PHP as a module will give better performance, more control and remote execution capability.


Servers-IIS/PWS

This section contains notes and hints specific to IIS (Microsoft Internet Information Server). Installing PHP for PWS/IIS 3, PWS 4 or newer and IIS 4 or newer versions.

Important for CGI users: Read the faq on cgi.force_redirect for important details. This directive needs to be set to 0.


Windows and PWS/IIS 3

The recommended method for configuring these servers is to use the REG file included with the distribution (pws-php4cgi.reg). You may want to edit this file and make sure the extensions and PHP install directories match your configuration. Or you can follow the steps below to do it manually.

Atenção

These steps involve working directly with the Windows registry. One error here can leave your system in an unstable state. We highly recommend that you back up your registry first. The PHP Development team will not be held responsible if you damage your registry.

  • Run Regedit.

  • Navigate to: HKEY_LOCAL_MACHINE /System /CurrentControlSet /Services /W3Svc /Parameters /ScriptMap.

  • On the edit menu select: New->String Value.

  • Type in the extension you wish to use for your php scripts. For example .php

  • Double click on the new string value and enter the path to php.exe in the value data field. ex: c:\php\php.exe.

  • Repeat these steps for each extension you wish to associate with PHP scripts.

The following steps do not affect the web server installation and only apply if you want your php scripts to be executed when they are run from the command line (ex. run c:\myscripts\test.php) or by double clicking on them in a directory viewer window. You may wish to skip these steps as you might prefer the PHP files to load into a text editor when you double click on them.

  • Navigate to: HKEY_CLASSES_ROOT

  • On the edit menu select: New->Key.

  • Name the key to the extension you setup in the previous section. ex: .php

  • Highlight the new key and in the right side pane, double click the "default value" and enter phpfile.

  • Repeat the last step for each extension you set up in the previous section.

  • Now create another New->Key under HKEY_CLASSES_ROOT and name it phpfile.

  • Highlight the new key phpfile and in the right side pane, double click the "default value" and enter PHP Script.

  • Right click on the phpfile key and select New->Key, name it Shell.

  • Right click on the Shell key and select New->Key, name it open.

  • Right click on the open key and select New->Key, name it command.

  • Highlight the new key command and in the right side pane, double click the "default value" and enter the path to php.exe. ex: c:\php\php.exe -q %1. (don't forget the %1).

  • Exit Regedit.

  • If using PWS on Windows, reboot to reload the registry.

PWS and IIS 3 users now have a fully operational system. IIS 3 users can use a nifty tool from Steven Genusa to configure their script maps.


Windows and PWS 4 or newer

When installing PHP on Windows with PWS 4 or newer version, you have two options. One to set up the PHP CGI binary, the other is to use the ISAPI module DLL.

If you choose the CGI binary, do the following:

  • Edit the enclosed pws-php4cgi.reg file (look into the SAPI dir) to reflect the location of your php.exe. Backslashes should be escaped, for example: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\w3svc\parameters\Script Map] ".php"="c:\\php\\php.exe" Now merge this registery file into your system; you may do this by double-clicking it.

  • In the PWS Manager, right click on a given directory you want to add PHP support to, and select Properties. Check the 'Execute' checkbox, and confirm.

If you choose the ISAPI module, do the following:

  • Edit the enclosed pws-php4isapi.reg file (look into the SAPI dir) to reflect the location of your php4isapi.dll. Backslashes should be escaped, for example: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\w3svc\parameters\Script Map] ".php"="c:\\php\\sapi\\php4isapi.dll" Now merge this registery file into your system; you may do this by double-clicking it.

  • In the PWS Manager, right click on a given directory you want to add PHP support to, and select Properties. Check the 'Execute' checkbox, and confirm.


Windows NT/2000/XP and IIS 4 or newer

To install PHP on an NT/2000/XP Server running IIS 4 or newer, follow these instructions. You have two options to set up PHP, using the CGI binary (php.exe) or with the ISAPI module.

In either case, you need to start the Microsoft Management Console (may appear as 'Internet Services Manager', either in your Windows NT 4.0 Option Pack branch or the Control Panel=>Administrative Tools under Windows 2000/XP). Then right click on your Web server node (this will most probably appear as 'Default Web Server'), and select 'Properties'.

If you want to use the CGI binary, do the following:

  • Under 'Home Directory', 'Virtual Directory', or 'Directory', click on the 'Configuration' button, and then enter the App Mappings tab.

  • Click Add, and in the Executable box, type: c:\php\php.exe (assuming that you have unziped PHP in c:\php\).

  • In the Extension box, type the file name extension you want associated with PHP scripts. Leave 'Method exclusions' blank, and check the Script engine checkbox. You may also like to check the 'check that file exists' box - for a small performance penalty, IIS (or PWS) will check that the script file exists and sort out authentication before firing up php. This means that you will get sensible 404 style error messages instead of cgi errors complaining that php did not output any data.

    You must start over from the previous step for each extension you want associated with PHP scripts. .php and .phtml are common, although .php3 may be required for legacy applications.

  • Set up the appropriate security. (This is done in Internet Service Manager), and if your NT Server uses NTFS file system, add execute rights for I_USR_ to the directory that contains php.exe.

To use the ISAPI module, do the following:

  • If you don't want to perform HTTP Authentication using PHP, you can (and should) skip this step. Under ISAPI Filters, add a new ISAPI filter. Use PHP as the filter name, and supply a path to the php4isapi.dll.

  • Under 'Home Directory', click on the 'Configuration' button. Add a new entry to the Application Mappings. Use the path to the php4isapi.dll as the Executable, supply .php as the extension, leave Method exclusions blank, and check the Script engine checkbox.

  • Stop IIS completely (NET STOP iisadmin)

  • Start IIS again (NET START w3svc)


Servers-Netscape and iPlanet

This section contains notes and hints specific to Netscape and iPlanet installs of PHP, both for Sun Solaris and Windows versions.

You can find more information about setting up PHP for the Netscape Enterprise Server here: http://benoit.noss.free.fr/php/install-php4.html


Installing PHP with Netscape on Sun Solaris

To build PHP with NES or iPlanet web servers, enter the proper install directory for the --with-nsapi = DIR option. The default directory is usually /opt/netscape/suitespot/. Please also read /php-xxx-version/sapi/nsapi/nsapi-readme.txt.

Exemplo 3-10. Installation Example for Netscape Enterprise on Solaris

Instructions for Sun Solaris 2.6 with Netscape Enterprise Server 3.6
From: bhager@invacare.com

1. Install the following packages from www.sunfreeware.com or another
download site: 

    flex-2_5_4a-sol26-sparc-local 
    gcc-2_95_2-sol26-sparc-local 
    gzip-1.2.4-sol26-sparc-local 
    perl-5_005_03-sol26-sparc-local 
    bison-1_25-sol26-sparc-local 
    make-3_76_1-sol26-sparc-local 
    m4-1_4-sol26-sparc-local 
    autoconf-2.13 
    automake-1.4 
    mysql-3.23.24-beta (if you want mysql support) 
    tar-1.13 (GNU tar) 

2. Make sure your path includes the proper directories
    PATH=.:/usr/local/bin:/usr/sbin:/usr/bin:/usr/ccs/bin 
    export PATH 

3. gunzip php-x.x.x.tar.gz (if you have a .gz dist, otherwise go to 4) 
4. tar xvf php-x.x.x.tar 
5. cd ../php-x.x.x 

6. For the following step, make sure /opt/netscape/suitespot/ is where
   your netscape server is installed. Otherwise, change to correct path:
    /configure --with-mysql=/usr/local/mysql --with-nsapi=/opt/netscape/suitespot/ --enable-track-vars --enable-libgcc 
7. make 
8. make install
After performing the base install and reading the appropriate readme file, you may need to performs some additional configuration steps.

Firstly you may need to add some paths to the LD_LIBRARY_PATH environment for Netscape to find all the shared libs. This can best done in the start script for your Netscape server. Windows users can probably skip this step. The start script is often located in: /path/to/server/https-servername/start

You may also need to edit the configuration files that are located in:/path/to/server/https-servername/config/.

Exemplo 3-11. Configuration Example for Netscape Enterprise

Configuration Instructions for Netscape Enterprise Server
From: bhager@invacare.com

1. Add the following line to mime.types:
    type=magnus-internal/x-httpd-php exts=php

2. Add the following to obj.conf, shlib will vary depending on
    your OS, for unix it will be something like
    /opt/netscape/suitespot/bin/libphp4.so.

    You should place the following lines after mime types init.
    Init fn="load-modules" funcs="php4_init,php4_close,php4_execute,php4_auth_trans" shlib="/php4/nsapiPHP4.dll"
    Init fn=php4_init errorString="Failed to initialize PHP!"

    <object name="default">
    . 
    . 
    . 
    .#NOTE this next line should happen after all 'ObjectType' and before all 'AddLog' lines 
    Service fn="php4_execute" type="magnus-internal/x-httpd-php" 
    . 
    . 
    </Object>


    <Object name="x-httpd-php"> 
    ObjectType fn="force-type" type="magnus-internal/x-httpd-php" 
    Service fn=php4_execute 
    </Object> 


    Authentication configuration 

    PHP authentication cannot be used with any other authentication. ALL AUTHENTICATION IS 
    PASSED TO YOUR PHP SCRIPT. To configure PHP Authentication for the entire server, add 
    the following line: 

    <Object name="default"> 
    AuthTrans fn=php4_auth_trans 
    . 
    . 
    . 
    . 
    </Object> 

    To use PHP Authentication on a single directory, add the following: 

    <Object ppath="d:\path\to\authenticated\dir\*"> 
    AuthTrans fn=php4_auth_trans 
    </Object>

If you are running Netscape Enterprise 4.x, then you should use the following:

Exemplo 3-12. Configuration Example for Netscape Enterprise 4.x

Place these lines after the mime types init, and everything else is similar
to the example configuration above.
From: Graeme Hoose (GraemeHoose@BrightStation.com)

Init fn="load-modules" shlib="/path/to/server4/bin/libphp4.so" funcs="php4_init,php4_close,php4_execute,php4_auth_trans"
Init fn="php4_init" LateInit="yes"

Installing PHP with Netscape on Windows

To Install PHP as CGI (for Netscape Enterprise Server, iPlanet, perhaps Fastrack), do the following:

  • Copy php4ts.dll to your systemroot (the directory where you installed windows)

  • Make a file association from the command line. Type the following two lines:
    assoc .php=PHPScript
    ftype PHPScript=c:\php\php.exe %1 %*

  • In the Netscape Enterprise Administration Server create a dummy shellcgi directory and remove it just after (this step creates 5 important lines in obj.conf and allow the web server to handle shellcgi scripts).

  • In the Netscape Enterprise Administration Server create a new mime type (Category: type, Content-Type: magnus-internal/shellcgi, File Suffix:php).

  • Do it for each web server instance you want php to run

More details about setting up PHP as a CGI executable can be found here: http://benoit.noss.free.fr/php/install-php.html

To Install PHP as NSAPI (for Netscape Enterprise Server, iPlanet, perhaps Fastrack, do the following:

  • Copy php4ts.dll to your systemroot (the directory where you installed windows)

  • Make a file association from the command line. Type the following two lines:
    assoc .php=PHPScript
    ftype PHPScript=c:\php\php.exe %1 %*

  • In the Netscape Enterprise Administration Server create a new mime type (Category: type, Content-Type: magnus-internal/x-httpd-php, File Suffix:php).

  • Stop your web service and edit obj.conf. At the end of the Init section, place these two lines (necessarily after mime type init!):
    Init fn="load-modules" funcs="php4_init,php4_close,php4_execute,php4_auth_trans" shlib="c:/php/sapi/php4nsapi.dll"
    Init fn="php4_init" errorString="Failed to initialise PHP!"

  • In The < Object name="default" > section, place this line necessarily after all 'ObjectType' and before all 'AddLog' lines:
    Service fn="php4_execute" type="magnus-internal/x-httpd-php"

  • At the end of the file, create a new object called x-httpd-php, by inserting these lines:
    <Object name="x-httpd-php">
    ObjectType fn="force-type" type="magnus-internal/x-httpd-php"
    Service fn=php4_execute
    </Object>

  • Restart your web service and apply changes

  • Do it for each web server instance you want PHP to run

More details about setting up PHP as an NSAPI filter can be found here: http://benoit.noss.free.fr/php/install-php4.html


Servers-OmniHTTPd Server

This section contains notes and hints specific to OmniHTTPd.


OmniHTTPd 2.0b1 and up for Windows

You need to complete the following steps to make PHP work with OmniHTTPd. This is a CGI executable setup. SAPI is supported by OmniHTTPd, but some tests have shown that it is not so stable to use PHP as an ISAPI module.

Important for CGI users: Read the faq on cgi.force_redirect for important details. This directive needs to be set to 0.

  • Step 1: Install OmniHTTPd server.

  • Step 2: Right click on the blue OmniHTTPd icon in the system tray and select Properties

  • Step 3: Click on Web Server Global Settings

  • Step 4: On the 'External' tab, enter: virtual = .php | actual = c:\path-to-php-dir\php.exe, and use the Add button.

  • Step 5: On the Mime tab, enter: virtual = wwwserver/stdcgi | actual = .php, and use the Add button.

  • Step 6: Click OK

Repeat steps 2 - 6 for each extension you want to associate with PHP.

Nota: Some OmniHTTPd packages come with built in PHP support. You can choose at setup time to do a custom setup, and uncheck the PHP component. We recommend you to use the latest PHP binaries. Some OmniHTTPd servers come with PHP 4 beta distributions, so you should choose not to set up the built in support, but install your own. If the server is already on your machine, use the Replace button in Step 4 and 5 to set the new, correct information.


Servers-Oreilly Website Pro

This section contains notes and hints specific to Oreilly Website Pro.


Oreilly Website Pro 2.5 and up for Windows

This list describes how to set up the PHP CGI binary or the ISAPI module to work with Oreilly Website Pro on Windows.

  • Edit the Server Properties and select the tab "Mapping".

  • From the List select "Associations" and enter the desired extension (.php) and the path to the CGI exe (ex. c:\php\php.exe) or the ISAPI DLL file (ex. c:\php\sapi\php4isapi.dll).

  • Select "Content Types" add the same extension (.php) and enter the content type. If you choose the CGI executable file, enter 'wwwserver/shellcgi', if you choose the ISAPI module, enter 'wwwserver/isapi' (both without quotes).


Servers-Sambar

This section contains notes and hints specific to the Sambar server for Windows.


Sambar Windows

This list describes how to set up the ISAPI module to work with the Sambar server on Windows.

  • Find the file called mappings.ini (in the config directory) in the Sambar isntall directory.

  • Open mappings.ini and add the following line under [ISAPI]:

    *.php = c:\php\php4isapi.dll

    (This line assumes that PHP was installed in c:\php.)

  • Now restart the Sambar server for the changes to take effect.


Servers-Xitami

This section contains notes and hints specific to Xitami.


Xitami for Windows

This list describes how to set up the PHP CGI binary to work with Xitami on Windows.

Important for CGI users: Read the faq on cgi.force_redirect for important details. This directive needs to be set to 0.

  • Make sure the webserver is running, and point your browser to xitamis admin console (usually http://127.0.0.1/admin), and click on Configuration.

  • Navigate to the Filters, and put the extension which PHP should parse (i.e. .php) into the field File extensions (.xxx).

  • In Filter command or script put the path and name of your php executable i.e. c:\php\php.exe.

  • Press the 'Save' icon.

  • Restart the server to reflect changes.


Servers-Other web servers

PHP can be built to support a large number of web servers. Please see Server-related options for a full list of server-related configure options. The PHP CGI binaries are compatible with almost all webservers supporting the CGI standard.


Problems?

Read the FAQ

Some problems are more common than others. The most common ones are listed in the PHP FAQ, part of this manual.


Other problems

If you are still stuck, someone on the PHP installation mailing list may be able to help you. You should check out the archive first, in case someone already answered someone else who had the same problem as you. The archives are available from the support page on http://www.php.net/. To subscribe to the PHP installation mailing list, send an empty mail to php-install-subscribe@lists.php.net. The mailing list address is php-install@lists.php.net.

If you want to get help on the mailing list, please try to be precise and give the necessary details about your environment (which operating system, what PHP version, what web server, if you are running PHP as CGI or a server module, etc.), and preferably enough code to make others able to reproduce and test your problem.


Bug reports

If you think you have found a bug in PHP, please report it. The PHP developers probably don't know about it, and unless you report it, chances are it won't be fixed. You can report bugs using the bug-tracking system at http://bugs.php.net/. Please do not send bug reports in mailing list or personal letters. The bug system is also suitable to submit feature requests.

Read the How to report a bug document before submitting any bug reports!


Complete list of configure options

Nota: These are only used at compile time. If you want to alter PHP's runtime configuration, please see the chapter on Configuration.

The following is a complete list of options supported by PHP 4 configure scripts (as of 4.1.0), used when compiling in Unix-like environments. Some are available in PHP 3, some in PHP 4, and some in both. This is not noted yet.

There are general configuration options for the configure script, consult the appropriate manual pages for GNU autoconf or use the command configure --help for a full, up-to-date list.


Configure Options in PHP 4

Nota: These options are only used in PHP 4 as of PHP 4.1.0. Some are available in older versions of PHP 4, some even in PHP 3, some only in PHP 4.1.0. If you want to compile an older version, some options will probably not be available.


Database options

--with-dbplus

Include dbplus support.

--with-adabas[=DIR]

Include Adabas D support. DIR is the Adabas base install directory, defaults to /usr/local.

--with-sapdb[=DIR]

Include SAP DB support. DIR is SAP DB base install directory, defaults to /usr/local.

--with-solid[=DIR]

Include Solid support. DIR is the Solid base install directory, defaults to /usr/local/solid.

--with-ibm-db2[=DIR]

Include IBM DB2 support. DIR is the DB2 base install directory, defaults to /home/db2inst1/sqllib.

--with-empress[=DIR]

Include Empress support. DIR is the Empress base install directory, defaults to $EMPRESSPATH. From PHP4, this option only supports Empress Version 8.60 and above.

--with-empress-bcs[=DIR]

Include Empress Local Access support. DIR is the Empress base install directory, defaults to $EMPRESSPATH. From PHP4, this option only supports Empress Version 8.60 and above.

--with-birdstep[=DIR]

Include Birdstep support. DIR is the Birdstep base install directory, defaults to /usr/local/birdstep.

--with-custom-odbc[=DIR]

Include a user defined ODBC support. The DIR is ODBC install base directory, which defaults to /usr/local. Make sure to define CUSTOM_ODBC_LIBS and have some odbc.h in your include dirs. E.g., you should define following for Sybase SQL Anywhere 5.5.00 on QNX, prior to run configure script: CPPFLAGS="-DODBC_QNX -DSQLANY_BUG" LDFLAGS=-lunix CUSTOM_ODBC_LIBS="-ldblib -lodbc".

--with-iodbc[=DIR]

Include iODBC support. DIR is the iODBC base install directory, defaults to /usr/local.

--with-esoob[=DIR]

Include Easysoft OOB support. DIR is the OOB base install directory, defaults to /usr/local/easysoft/oob/client.

--with-unixODBC[=DIR]

Include unixODBC support. DIR is the unixODBC base install directory, defaults to /usr/local.

--with-openlink[=DIR]

Include OpenLink ODBC support. DIR is the OpenLink base install directory, defaults to /usr/local. This is the same as iODBC.

--with-dbmaker[=DIR]

Include DBMaker support. DIR is the DBMaker base install directory, defaults to where the latest version of DBMaker is installed (such as /home/dbmaker/3.6).

--disable-unified-odbc

Disable unified ODBC support. Only applicable if iODBC, Adabas, Solid, Velocis or a custom ODBC interface is enabled. PHP 3 only!


Graphics options

--without-gd

Disable GD support. PHP 3 only!

--with-imagick

The imagick extension has been moved to PECL in PEAR and can be found here. Install instructions for PHP 4 can be found on the PEAR site.

Simply doing --with-imagick is only supported in PHP 3 unless you follow the instructions found on the PEAR site.

--with-ming[=DIR]

Include ming support.


Misc options

--enable-force-cgi-redirect

Enable the security check for internal server redirects. You should use this if you are running the CGI version with Apache.

--enable-discard-path

If this is enabled, the PHP CGI binary can safely be placed outside of the web tree and people will not be able to circumvent .htaccess security.

--with-fastcgi=SRCDIR

Build PHP as FastCGI application.

--enable-debug

Compile with debugging symbols.

--with-layout=TYPE

Sets how installed files will be laid out. Type is one of PHP (default) or GNU.

--with-pear=DIR

Install PEAR in DIR (default PREFIX/lib/php).

--without-pear

Do not install PEAR.

--enable-sigchild

Enable PHP's own SIGCHLD handler.

--disable-rpath

Disable passing additional runtime library search paths.

--enable-libgcc

Enable explicitly linking against libgcc.

--enable-php-streams

Include experimental php streams. Do not use unless you are testing the code!

--with-zlib-dir=<DIR>

Define the location of zlib install directory.

--with-aspell[=DIR]

Include ASPELL support.

--with-ccvs[=DIR]

Include CCVS support.

--with-cybercash[=DIR]

Include CyberCash support. DIR is the CyberCash MCK install directory.

--with-icap[=DIR]

Include ICAP support.

--with-ircg-config

Path to the ircg-config script.

--with-ircg

Include ircg support.

--enable-mailparse

Enable mailparse support.

--with-muscat[=DIR]

Include muscat support.

--with-satellite[=DIR]

Enable CORBA support via Satellite (EXPERIMENTAL) DIR is the base directory for ORBit.

--enable-trans-sid

Enable transparent session id propagation.

--with-system-regex

Use system regex library (deprecated).

--with-vpopmail[=DIR]

Include vpopmail support.

--with-tsrm-pthreads

Use POSIX threads (default).

--enable-shared[=PKGS]

Build shared libraries [default=yes].

--enable-static[=PKGS]

Build static libraries [default=yes].

--enable-fast-install[=PKGS]

Optimize for fast installation [default=yes].

--with-gnu-ld

Assume the C compiler uses GNU ld [default=no].

--disable-libtool-lock

Avoid locking (might break parallel builds).

--with-pic

Try to use only PIC/non-PIC objects [default=use both].

--enable-memory-limit

Compile with memory limit support.

--disable-url-fopen-wrapper

Disable the URL-aware fopen wrapper that allows accessing files via HTTP or FTP.

--enable-versioning

Export only required symbols. See INSTALL for more information.

--with-imsp[=DIR]

Include IMSp support (DIR is IMSP's include dir and libimsp.a dir). PHP 3 only!

--with-mck[=DIR]

Include Cybercash MCK support. DIR is the cybercash mck build directory, defaults to /usr/src/mck-3.2.0.3-linux for help look in extra/cyberlib. PHP 3 only!

--with-mod-dav=DIR

Include DAV support through Apache's mod_dav, DIR is mod_dav's installation directory (Apache module version only!) PHP 3 only!

--enable-debugger

Compile with remote debugging functions. PHP 3 only!

--enable-versioning

Take advantage of versioning and scoping provided by Solaris 2.x and Linux. PHP 3 only!


PHP options

--enable-maintainer-mode

Enable make rules and dependencies not useful (and sometimes confusing) to the casual installer.

--with-config-file-path=PATH

Sets the path in which to look for php.ini, defaults to PREFIX/lib.

--enable-safe-mode

Enable safe mode by default.

--with-exec-dir[=DIR]

Only allow executables in DIR when in safe mode defaults to /usr/local/php/bin.

--enable-magic-quotes

Enable magic quotes by default.

--disable-short-tags

Disable the short-form <? start tag by default.


Server options

--with-aolserver=DIR

Specify path to the installed AOLserver.

--with-apxs[=FILE]

Build shared Apache module. FILE is the optional pathname to the Apache apxs tool; defaults to apxs. Make sure you specify the version of apxs that is actually installed on your system and NOT the one that is in the apache source tarball.

--with-apache[=DIR]

Build Apache module. DIR is the top-level Apache build directory, defaults to /usr/local/apache.

--with-mod_charset

Enable transfer tables for mod_charset (Rus Apache).

--with-apxs2[=FILE]

Build shared Apache 2.0 module. FILE is the optional pathname to the Apache apxs tool; defaults to apxs.

--with-fhttpd[=DIR]

Build fhttpd module. DIR is the fhttpd sources directory, defaults to /usr/local/src/fhttpd.

--with-isapi=DIR

Build PHP as an ISAPI module for use with Zeus.

--with-nsapi=DIR

Specify path to the installed Netscape Server.

--with-phttpd=DIR

No information yet.

--with-pi3web=DIR

Build PHP as a module for use with Pi3Web.

--with-roxen=DIR

Build PHP as a Pike module. DIR is the base Roxen directory, normally /usr/local/roxen/server.

--enable-roxen-zts

Build the Roxen module using Zend Thread Safety.

--with-servlet[=DIR]

Include servlet support. DIR is the base install directory for the JSDK. This SAPI prereqs the java extension must be built as a shared dl.

--with-thttpd=SRCDIR

Build PHP as thttpd module.

--with-tux=MODULEDIR

Build PHP as a TUX module (Linux only).


Capítulo 4. Configuração

O arquivo de configuração

O arquivo de configuração (chamado php3.ini no PHP 3.0, e simplesmente php.ini no PHP 4.0) é lido quando o PHP inicia. Para as versões de módulos de servidor do PHP, isso só acontece uma vez quando o servidor é iniciado. Para as versões CGI e CLI acontece em cada execução.

A localização padrão do php.ini é uma opção de compilação (veja a FAQ correspondente), mas pode ser modificada para as versões CGI e CLI com o opcional -c (mais informações em utilizando o PHP na linha de comando). Você também pode utilizar a variavável ambiente PHPRC para colocar caminhos adicionais para a procura do arquivo php.ini.

Note que nem todas as diretivas do PHP estão documentadas a seguir. Para uma lista completa, leia o seu próprio e bem comentado arquivo php.ini. Você também pode ver a versão mais atualizada diretamente do CVS.

Nota: O valor default da diretiva register_globals mudou de on para off a partir do PHP 4.2.0.

Exemplo 4-1. php.ini example

; qualquer texto depois de um ponto e vírgula não delimitado (;) é ignorado
[php] ; marcadores de seção (texto entre colchetes) também são ignorados
; Valores booleanos podem ser:
;    true, on, yes
; ou false, off, no, none
register_globals = off
magic_quotes_gpc = yes

; você pode delimitar strings com aspas
include_path = ".:/usr/local/lib/php"

; barras invertidas são tratadas da mesma maneira que outros caracteres
include_path = ".;c:\php\lib"


Como alterar as configurações definidas

Rodando o PHP como módulo do Apache

Quando usando o PHP como um módulo do Apache, você também pode mudar as definições de configuração usando diretivas na configuração do Apache (httpd.conf) e dos arquivos .htaccess (Você irá precisar de privilégios "AllowOverride Options" ou "AllowOverride All")

Com o PHP 3.0, existem diretivas Apache que correspondem a cada definição de configuração no nome php3.ini, exceto o nome predefinido por "php3_".

Com o PHP 4.0, existem várias diretivas do Apache que lhe permitem mudar a configuração PHP dentro do arquivo de configuração do Apache.

php_value nome valor

Isso define o valor da variável especificada.

php_flag nome on|off

Isto é usado para definir uma opção de configuração Booleana.

php_admin_value nome valor

Isto define o valor da variável especificada. Definições de configuração "Admin" só podem ser definidas a partir dos arquivos principais de configuração do Apache, e não dos arquivos .htaccess.

php_admin_flag nome on|off

Isto é usado para definir uma opção de configuração Booleana.

Exemplo 4-2. Exemplo de configuração do Apache

<IfModule mod_php4.c>
  php_value include_path ".:/usr/local/lib/php"
  php_admin_flag safe_mode on
</IfModule>
<IfModule mod_php3.c>
  php3_include_path ".:/usr/local/lib/php"
  php3_safe_mode on
</IfModule>

Nota: Constantes PHP não existem fora do PHP. Por exemplo, no httpd.conf não adianta utilizar-se de constantes PHP como E_ALL ou E_NOTICE para configurar a diretiva error_reporting, pois elas não tem nenhum sentido e serão avaliados como 0. Nesses casos, utilize seus valores de bit. Essas constantes só podem ser utilizadas dentro do php.ini


Outras interfaces para o PHP

Independentemente da interface do PHP, você pode mudar certos valores em tempo de execução em seus scripts através ini_set(). A tabela seguinte explica em que nível as diretivas podem ser modificadas.

Tabela 4-1. Definições das constantes PHP_INI_*

Constante Valor Significado
PHP_INI_USER 1 Diretiva pode ser modificada em seus scripts
PHP_INI_PERDIR 2 Diretiva pode ser modificada no .htaccess e nas diretivas VHost do httpd.conf.
PHP_INI_SYSTEM 4 Diretiva pode ser modificada no php.ini ou httpd.conf (mas não em blocos VHost do httpd.conf).
PHP_INI_ALL 7 Diretiva pode ser modificada em qualquer lugar

Você pode visualizar as configurações das diretivas na saída de phpinfo(). Você também pode acessar os valores individuais das configurações utilizando ini_get() ou get_cfg_var().


Diretivas de configuração

Opções Httpd

Tabela 4-2. Opções Httpd

Nome Padrão Alterável
async_send "0" PHP_INI_ALL


Opções da Linguagem

Tabela 4-3. Opções gerais da linguagem

Nome Padrão Alterável
short_open_tag On PHP_INI_SYSTEM|PHP_INI_PERDIR
asp_tags Off PHP_INI_SYSTEM|PHP_INI_PERDIR
precision "14" PHP_INI_ALL
y2k_compliance Off PHP_INI_ALL
allow_call_time_pass_reference On PHP_INI_SYSTEM|PHP_INI_PERDIR
expose_php On PHP_INI_SYSTEM

Descrição resumida das diretivas de configuração.

short_open_tag boolean

Informa quando a tag reduzida (<? ?>) do PHP pode ser permitida. Se você quiser usar o PHP em combinação com XML, você pode desligar essa opção para poder utilizar <?xml ?> inline. De outra forma, você pode imprimir com o PHP, por exemplo: <?php echo '<?xml version="1.0"'; ?>. Se desligado, você precisará utilizar a forma longa da tag de abertura do PHP (<?php ?>).

Nota: Esta diretiva também afeta o atalho <?=, que é idêntico a <? echo. A utilização desse atalho requer short_open_tag ligado.

asp_tags boolean

Ativa a utilização das tags estilo ASP <% %> em adição as tags <?php ?>. Isto inclui o atalho de impressão de valores <%= $var %>. Para mais informações, veja Alternando do HTML.

Nota: O suporte a tags estilo APS foi acrescentado no 3.0.4.

precision integer

O número de dígitos significantes exibidos em números de ponto flutuante.

y2k_compliance boolean

Força a especificação Ano 2002 (poderá causar problemas com browsers não compatíveis)

allow_call_time_pass_reference boolean

Especifica a habilidade em forçar que argumentos possam ser passados por referência na chamada de uma função. Este método é obsoleto e logo não será mais suportado nas futuras versões do PHP/Zend. O método recomendado para especificar que argumentos devem ser passados por referência é pela declaração da função. Você é encorajado em tentar desligar essa opção e verificar se seus scripts trabalham adequadamente de forma a garantir que elas irã funcionar nas futuras versões da linguagem (você receberá um alerta cada vez que utilizar esse recurso, e o argumento será passado por valor em vez de por referência).

Veja também Referências Explicadas.

expose_php boolean

Decide se o PHP poderá expor o fato de que ele está instalado no servidor (acrescentando sua assinatura no header do servidor web). Isto não causa problemas de segurança de qualquer forma, mas torna possível determinar se você usa o PHP em seu servidor ou não.


Limitação de recursos

Tabela 4-4. Limitação de recursos

Nome Padrão Alterável
memory_limit "8M" PHP_INI_ALL

Descrição resumida das diretivas de configuração.

memory_limit integer

Isto configura a quantidade máxima de memória, em bytes, que um script poderá alocar. Isto ajuda a prevenir que scripts mal escritos acabem com toda a memória disponível do servidor.

Veja também max_execution_time.


Manipulação de dados

Tabela 4-5. Opções configuráveis para manipulação de dados

Nome Padrão Alterável
track-vars "On" PHP_INI_??
arg_separator.output "&" PHP_INI_ALL
arg_separator.input "&" PHP_INI_SYSTEM|PHP_INI_PERDIR
variables_order "EGPCS" PHP_INI_ALL
register_globals "Off" PHP_INI_PERDIR|PHP_INI_SYSTEM
register_argc_argv "On" PHP_INI_PERDIR|PHP_INI_SYSTEM
post_max_size "8M" PHP_INI_SYSTEM|PHP_INI_PERDIR
gpc_order "GPC" PHP_INI_ALL
auto_prepend_file "" PHP_INI_SYSTEM|PHP_INI_PERDIR
auto_append_file "" PHP_INI_SYSTEM|PHP_INI_PERDIR
default_mimetype "text/html" PHP_INI_ALL
default_charset "iso-8859-1" PHP_INI_ALL
always_populate_raw_post_data "0" PHP_INI_SYSTEM|PHP_INI_PERDIR
allow_webdav_methods "0" PHP_INI_SYSTEM|PHP_INI_PERDIR

Descrição resumida das diretivas de configuração.

track_vars boolean

Se ativado, quaisquer variáveis Environment, GET, POST, Cookie e Server encontradas poderão ser acessadas nos arrays globais associativos $_ENV, $_GET, $_POST, $_COOKIE e $_SERVER.

Note que a partir do PHP 4.0.3, track_vars está sempre ativado.

arg_separator.output string

O separador de parâmetros em URLs geradas pelo PHP.

arg_separator.input string

Lista dos separador(es) utilizados pelo PHP para interpretar URLs em variáveis.

Nota: Cada caracter nesta diretiva é considerado como um separador!

variables_order string

Configura a ordem de interpretação das variáveis EGPCS (Environment, GET, POST, Cookie e Server). O default dessa diretiva é "EGPCS". Configurando para "GP", por exemplo, fará com que o PHP ignore completamente variáveis de ambiente (E), cookies (C) e do servidor (S), sendo que qualquer variável GET será sobrescrita por qualquer variável do método POST com o mesmo nome.

Veja também register_globals.

register_globals boolean

Ativa ou não o registro de variáveis EGPCS (Environment, GET, POST, Cookie e Server) como variáveis globais. Por exemplo: se register_globals = on, a URL http://www.example.com/test.php?id=3 irá criar a variável $id. Ou, $DOCUMENT_ROOT de $_SERVER['DOCUMENT_ROOT']. Você pode desligar essa diretiva se você não deseja sujar o escopo global de seus scripts com dados do usuário. Desde o PHP 4.2.0, o padrão dessa diretiva é off. É preferível utilizar as variáveis predefinidas do PHP, como as superglobals: $_ENV, $_GET, $_POST, $_COOKIE e $_SERVER. Leia cuidadosamente o capitulo de segurança em Utilizando register_globals para mais informações.

Veja que register_globals não pode ser alterado em tempo de execução (ini_set()). Entretanto, você pode utilizar o .htaccess se seu host permitir como descrito anteriormente. Um exemplo de entrada do .htaccess: php_flag register_globals on.

Nota: register_globals é afetada pela diretiva variables_order .

register_argc_argv boolean

Configura quando o PHP deve declarar ou não as variáveis argv e argc (que podem conter dados do método GET).

Veja também Utilizando o PHP em linha de comando. Além, essa diretiva foi criada no PHP 4.0.0 e sempre foi "ativa" antes disso.

post_max_size integer

Configura o tamanho máximo dos dados postados. Esta configuração também afeta o upload de arquivos. Para receber arquivos grandes, esse valor precisa ser maior que upload_max_filesize.

Se o limite de memória estiver ativado em seu script de configuração, memory_limit também afeta o upload de arquivos. Falando diretamente, memory_limit precisa ser maior que post_max_size.

gpc_order string

Informa a ordem de interpretação das variáveis GET/POST/COOKIE. O padrão dessa diretiva é "GPC". Configurando para "GP", por exemplo, fará com que o PHP ignore completamente cookies e que sobrescreva qualquer dado postado via GET por variáveis postados via POST que tenham o mesmo nome.

Nota: Esta opção não está disponível no PHP 4. Utilize variables_order no seu lugar.

auto_prepend_file string

Especifica o nome do arquivo que será automaticamente interpretado antes do arquivo principal. O arquivo é incluído como se ele fosse chamado com a função include(), então include_path é utilizado.

O valor especial none desabilita a auto inclusão.

auto_append_file string

Especifica se o nome do arquivo que será automaticamente interpretado depois do arquivo principal. O arquivo é incluído como se ele fosse chamada a função include(), então include_path é utilizado.

O valor especial none desabilita a auto inclusão.

Nota: Se o script é terminado com exit(), a auto inclusão não irá ocorrer.

default_mimetype string

default_charset string

A partir da versão 4.0b4, o PHP sempre emite a codificação de caracter por padrão no header Content-type:. Para desabilitar o envio do código de página, simplesmente deixe a diretiva em branco.

always_populate_raw_post_data boolean

Sempre preenche a variável $HTTP_RAW_POST_DATA.

allow_webdav_methods boolean

Permite a manipulação de headers HTTP com scripts PHP (com PROPFIND, PROPPATCH, MOVE, COPY, etc). Se você quiser obter os dados postados dessas requisições, ative always_populate_raw_post_data para isso.

Veja também magic_quotes_gpc, magic-quotes-runtime, e magic_quotes_sybase.


Paths and Directories

Tabela 4-6. Opções de configuração de caminhos e diretórios

Nome Padrão Alterável
include_path PHP_INCLUDE_PATH PHP_INI_ALL
doc_root PHP_INCLUDE_PATH PHP_INI_SYSTEM
user_dir NULL PHP_INI_SYSTEM
extension_dir PHP_EXTENSION_DIR PHP_INI_SYSTEM
cgi.force_redirect "1" PHP_INI_SYSTEM
cgi.redirect_status_env "" PHP_INI_SYSTEM
fastcgi.impersonate "0" PHP_INI_SYSTEM

Descrição resumida das diretivas de configuração.

include_path string

Especifica a lista de diretórios onde as funções require(), include() and fopen_with_path() procurarão por arquivos. O formato é o mesmo que o da variável ambiente PATH: uma lista de diretórios, separador por vírgula no UNIX ou ponto e vírgula no Windows.

Exemplo 4-3. include_path UNIX

include_path=.:/home/httpd/php-lib

Exemplo 4-4. include_path Windows

include_path=".;c:\www\phplib"
O default dessa diretiva é . (somente o diretório atual).

doc_root string

O "diretório root" do PHP no servidor. Utilizado somente se for preenchido. Se o PHP estiver configurado com safe mode, nenhum arquivo acima desse diretório será acessível. Se o PHP não estiver compilado com FORCE_REDIRECT, você DEVE configurar doc_root se estiver rodando o PHP como CGI sob qualquer servidor web (que não o IIS) Outra alternativa é configurar a diretiva cgi.force_redirect, abaixo.

user_dir string

O caminho base do usado como diretório home do usuário para arquivos PHP, por exemplo public_html.

extension_dir string

Diretório de onde o PHP poderá carregar dinamicamente as extensões. Veja também enable_dl e dl().

extension string

Que extensões dinamicamente carregáveis devem ser carregadas quando o PHP inicia.

cgi.force_redirect boolean

cgi.force_redirect é necessário para prover segurança quando rodando o PHP como módulo sob a maioria dos servidores web. Se deixado indefinido, o PHP assume como ativo. Você pode desligá-lo SOB SEU RISCO.

Nota: Usuários Windows: Você PODE desligar isso no ISS, e de fato, você DEVE fazê-lo. Para que o OmniHTTPD ou Xitami funcionem, você PRECISA desligá-lo.

cgi.cgi.redirect_status_env string

Se cgi.force_redirect estiver ativado, e se não estiver rodando o PHP sob os servidores web Apache ou Netscape (iPlanet), você PRECISARÁ configurar uma variável de ambiente que o PHP procurará para saber se ele pode continuar a execução.

Nota: Configurar essa variável PODERÁ causar problemas de segurança, POR ISSO SAIBA QUE ESTEJA FAZENDO PRIMEIRO.

fastcgi.impersonate string

FastCGI sob o IIS (em sistemas baseados em WinNT) suporta a habilidade de despersonalizar tokens de segurança da chamado do cliente. Isto permite ao ISS definir o contexto de segurança da requisição que está rodando. mod_fastcgi sob o Apache ainda não suporta esse recurso (17/03/2002). Configure 1 se estiver rodando sob o ISS. O padrão é zero.


Upload de arquivos

Tabela 4-7. Opções de configuração para upload de arquivos

Nome Padrão Alterável
file_uploads "1" PHP_INI_SYSTEM
upload_tmp_dir NULL PHP_INI_SYSTEM
upload_max_filesize "2M" PHP_INI_SYSTEM|PHP_INI_PERDIR

Descrição resumida das diretivas de configuração.

file_uploads boolean

Permite ou não upload de arquivos HTTP. Veja também upload_max_filesize, upload_tmp_dir e post_max_size directives.

upload_tmp_dir string

O diretório temporário utilizado para armazenar arquivos quando realizando o upload de arquivos. Ele precisa ter permissão de escrita para qualquer usuário que for rodar o PHP. Se não especificado, o PHP utilizará o default do sistema.

upload_max_filesize integer

O tamanho máximo de um arquivo para upload.


SQL Geral

Tabela 4-8. Opções de configuração SQL gerais

Nome Padrão Alterável
sql.safe_mode "0" PHP_INI_SYSTEM

Descrição resumida das diretivas de configuração.

sql.safe_mode boolean


Diretivas de configuração do debugador

debugger.host string

Nome DNS ou endereço IP do host utilizado pelo debugador.

debugger.port string

Porta utilizado pelo debugador.

debugger.enabled boolean

Controle de ativação do debugador.


Capítulo 5. Security

PHP is a powerful language and the interpreter, whether included in a web server as a module or executed as a separate CGI binary, is able to access files, execute commands and open network connections on the server. These properties make anything run on a web server insecure by default. PHP is designed specifically to be a more secure language for writing CGI programs than Perl or C, and with correct selection of compile-time and runtime configuration options, and proper coding practices, it can give you exactly the combination of freedom and security you need.

As there are many different ways of utilizing PHP, there are many configuration options controlling its behaviour. A large selection of options guarantees you can use PHP for a lot of purposes, but it also means there are combinations of these options and server configurations that result in an insecure setup.

The configuration flexibility of PHP is equally rivalled by the code flexibility. PHP can be used to build complete server applications, with all the power of a shell user, or it can be used for simple server-side includes with little risk in a tightly controlled environment. How you build that environment, and how secure it is, is largely up to the PHP developer.

This chapter starts with some general security advice, explains the different configuration option combinations and the situations they can be safely used, and describes different considerations in coding for different levels of security.


General considerations

A completely secure system is a virtual impossibility, so an approach often used in the security profession is one of balancing risk and usability. If every variable submitted by a user required two forms of biometric validation (such as a retinal scan and a fingerprint), you would have an extremely high level of accountability. It would also take half an hour to fill out a fairly complex form, which would tend to encourage users to find ways of bypassing the security.

The best security is often inobtrusive enough to suit the requirements without the user being prevented from accomplishing their work, or over-burdening the code author with excessive complexity. Indeed, some security attacks are merely exploits of this kind of overly built security, which tends to erode over time.

A phrase worth remembering: A system is only as good as the weakest link in a chain. If all transactions are heavily logged based on time, location, transaction type, etc. but the user is only verified based on a single cookie, the validity of tying the users to the transaction log is severely weakened.

When testing, keep in mind that you will not be able to test all possibilities for even the simplest of pages. The input you may expect will be completely unrelated to the input given by a disgruntled employee, a cracker with months of time on their hands, or a housecat walking across the keyboard. This is why it's best to look at the code from a logical perspective, to discern where unexpected data can be introduced, and then follow how it is modified, reduced, or amplified.

The Internet is filled with people trying to make a name for themselves by breaking your code, crashing your site, posting inappropriate content, and otherwise making your day interesting. It doesn't matter if you have a small or large site, you are a target by simply being online, by having a server that can be connected to. Many cracking programs do not discern by size, they simply trawl massive IP blocks looking for victims. Try not to become one.


Installed as CGI binary

Possible attacks

Using PHP as a CGI binary is an option for setups that for some reason do not wish to integrate PHP as a module into server software (like Apache), or will use PHP with different kinds of CGI wrappers to create safe chroot and setuid environments for scripts. This setup usually involves installing executable PHP binary to the web server cgi-bin directory. CERT advisory CA-96.11 recommends against placing any interpreters into cgi-bin. Even if the PHP binary can be used as a standalone interpreter, PHP is designed to prevent the attacks this setup makes possible:

  • Accessing system files: http://my.host/cgi-bin/php?/etc/passwd

    The query information in a url after the question mark (?) is passed as command line arguments to the interpreter by the CGI interface. Usually interpreters open and execute the file specified as the first argument on the command line.

    When invoked as a CGI binary, PHP refuses to interpret the command line arguments.

  • Accessing any web document on server: http://my.host/cgi-bin/php/secret/doc.html

    The path information part of the url after the PHP binary name, /secret/doc.html is conventionally used to specify the name of the file to be opened and interpreted by the CGI program. Usually some web server configuration directives (Apache: Action) are used to redirect requests to documents like http://my.host/secret/script.php to the PHP interpreter. With this setup, the web server first checks the access permissions to the directory /secret, and after that creates the redirected request http://my.host/cgi-bin/php/secret/script.php. Unfortunately, if the request is originally given in this form, no access checks are made by web server for file /secret/script.php, but only for the /cgi-bin/php file. This way any user able to access /cgi-bin/php is able to access any protected document on the web server.

    In PHP, compile-time configuration option --enable-force-cgi-redirect and runtime configuration directives doc_root and user_dir can be used to prevent this attack, if the server document tree has any directories with access restrictions. See below for full the explanation of the different combinations.


Case 1: only public files served

If your server does not have any content that is not restricted by password or ip based access control, there is no need for these configuration options. If your web server does not allow you to do redirects, or the server does not have a way to communicate to the PHP binary that the request is a safely redirected request, you can specify the option --enable-force-cgi-redirect to the configure script. You still have to make sure your PHP scripts do not rely on one or another way of calling the script, neither by directly http://my.host/cgi-bin/php/dir/script.php nor by redirection http://my.host/dir/script.php.

Redirection can be configured in Apache by using AddHandler and Action directives (see below).


Case 2: using --enable-force-cgi-redirect

This compile-time option prevents anyone from calling PHP directly with a url like http://my.host/cgi-bin/php/secretdir/script.php. Instead, PHP will only parse in this mode if it has gone through a web server redirect rule.

Usually the redirection in the Apache configuration is done with the following directives:

Action php-script /cgi-bin/php
AddHandler php-script .php

This option has only been tested with the Apache web server, and relies on Apache to set the non-standard CGI environment variable REDIRECT_STATUS on redirected requests. If your web server does not support any way of telling if the request is direct or redirected, you cannot use this option and you must use one of the other ways of running the CGI version documented here.


Case 3: setting doc_root or user_dir

To include active content, like scripts and executables, in the web server document directories is sometimes consider an insecure practice. If, because of some configuration mistake, the scripts are not executed but displayed as regular HTML documents, this may result in leakage of intellectual property or security information like passwords. Therefore many sysadmins will prefer setting up another directory structure for scripts that are accessible only through the PHP CGI, and therefore always interpreted and not displayed as such.

Also if the method for making sure the requests are not redirected, as described in the previous section, is not available, it is necessary to set up a script doc_root that is different from web document root.

You can set the PHP script document root by the configuration directive doc_root in the configuration file, or you can set the environment variable PHP_DOCUMENT_ROOT. If it is set, the CGI version of PHP will always construct the file name to open with this doc_root and the path information in the request, so you can be sure no script is executed outside this directory (except for user_dir below).

Another option usable here is user_dir. When user_dir is unset, only thing controlling the opened file name is doc_root. Opening an url like http://my.host/~user/doc.php does not result in opening a file under users home directory, but a file called ~user/doc.php under doc_root (yes, a directory name starting with a tilde [~]).

If user_dir is set to for example public_php, a request like http://my.host/~user/doc.php will open a file called doc.php under the directory named public_php under the home directory of the user. If the home of the user is /home/user, the file executed is /home/user/public_php/doc.php.

user_dir expansion happens regardless of the doc_root setting, so you can control the document root and user directory access separately.


Case 4: PHP parser outside of web tree

A very secure option is to put the PHP parser binary somewhere outside of the web tree of files. In /usr/local/bin, for example. The only real downside to this option is that you will now have to put a line similar to:

#!/usr/local/bin/php

as the first line of any file containing PHP tags. You will also need to make the file executable. That is, treat it exactly as you would treat any other CGI script written in Perl or sh or any other common scripting language which uses the #! shell-escape mechanism for launching itself.

To get PHP to handle PATH_INFO and PATH_TRANSLATED information correctly with this setup, the php parser should be compiled with the --enable-discard-path configure option.


Installed as an Apache module

When PHP is used as an Apache module it inherits Apache's user permissions (typically those of the "nobody" user). This has several impacts on security and authorization. For example, if you are using PHP to access a database, unless that database has built-in access control, you will have to make the database accessable to the "nobody" user. This means a malicious script could access and modify the database, even without a username and password. It's entirely possible that a web spider could stumble across a database administrator's web page, and drop all of your databases. You can protect against this with Apache authorization, or you can design your own access model using LDAP, .htaccess files, etc. and include that code as part of your PHP scripts.

Often, once security is established to the point where the PHP user (in this case, the apache user) has very little risk attached to it, it is discovered that PHP is now prevented from writing any files to user directories. Or perhaps it has been prevented from accessing or changing databases. It has equally been secured from writing good and bad files, or entering good and bad database transactions.

A frequent security mistake made at this point is to allow apache root permissions, or to escalate apache's abilitites in some other way.

Escalating the Apache user's permissions to root is extremely dangerous and may compromise the entire system, so sudo'ing, chroot'ing, or otherwise running as root should not be considered by those who are not security professionals.

There are some simpler solutions. By using open_basedir you can control and restrict what directories are allowed to be used for PHP. You can also set up apache-only areas, to restrict all web based activity to non-user, or non-system, files.


Filesystem Security

PHP is subject to the security built into most server systems with respect to permissions on a file and directory basis. This allows you to control which files in the filesystem may be read. Care should be taken with any files which are world readable to ensure that they are safe for reading by all users who have access to that filesystem.

Since PHP was designed to allow user level access to the filesystem, it's entirely possible to write a PHP script that will allow you to read system files such as /etc/passwd, modify your ethernet connections, send massive printer jobs out, etc. This has some obvious implications, in that you need to ensure that the files that you read from and write to are the appropriate ones.

Consider the following script, where a user indicates that they'd like to delete a file in their home directory. This assumes a situation where a PHP web interface is regularly used for file management, so the Apache user is allowed to delete files in the user home directories.

Exemplo 5-1. Poor variable checking leads to....

<?php
// remove a file from the user's home directory
$username = $_POST['user_submitted_name'];
$homedir = "/home/$username";
$file_to_delete = "$userfile";
unlink ("$homedir/$userfile");
echo "$file_to_delete has been deleted!";
?>
Since the username is postable from a user form, they can submit a username and file belonging to someone else, and delete files. In this case, you'd want to use some other form of authentication. Consider what could happen if the variables submitted were "../etc/" and "passwd". The code would then effectively read:

Exemplo 5-2. ... A filesystem attack

<?php
// removes a file from anywhere on the hard drive that
// the PHP user has access to. If PHP has root access:
$username = "../etc/";
$homedir = "/home/../etc/";
$file_to_delete = "passwd";
unlink ("/home/../etc/passwd");
echo "/home/../etc/passwd has been deleted!";
?>
There are two important measures you should take to prevent these issues.

  • Only allow limited permissions to the PHP web user binary.

  • Check all variables which are submitted.

Here is an improved script:

Exemplo 5-3. More secure file name checking

<?php
// removes a file from the hard drive that
// the PHP user has access to.
$username = $_SERVER['REMOTE_USER']; // using an authentication mechanisim

$homedir = "/home/$username";

$file_to_delete = basename("$userfile"); // strip paths
unlink ($homedir/$file_to_delete);

$fp = fopen("/home/logging/filedelete.log","+a"); //log the deletion
$logstring = "$username $homedir $file_to_delete";
fputs ($fp, $logstring);
fclose($fp);

echo "$file_to_delete has been deleted!";
?>
However, even this is not without it's flaws. If your authentication system allowed users to create their own user logins, and a user chose the login "../etc/", the system is once again exposed. For this reason, you may prefer to write a more customized check:

Exemplo 5-4. More secure file name checking

<?php
$username = $_SERVER['REMOTE_USER']; // using an authentication mechanisim
$homedir = "/home/$username";

if (!ereg('^[^./][^/]*$', $userfile))
     die('bad filename'); //die, do not process

if (!ereg('^[^./][^/]*$', $username))
     die('bad username'); //die, do not process
//etc...
?>

Depending on your operating system, there are a wide variety of files which you should be concerned about, including device entries (/dev/ or COM1), configuration files (/etc/ files and the .ini files), well known file storage areas (/home/, My Documents), etc. For this reason, it's usually easier to create a policy where you forbid everything except for what you explicitly allow.


Database Security

Nowadays, databases are cardinal components of any web based application by enabling websites to provide varying dynamic content. Since very sensitive or secret informations can be stored in such database, you should strongly consider to protect them somehow.

To retrieve or to store any information you need to connect to the database, send a legitimate query, fetch the result, and close the connecion. Nowadays, the commonly used query language in this interaction is the Structured Query Language (SQL). See how an attacker can tamper with an SQL query.

As you can realize, PHP cannot protect your database by itself. The following sections aim to be an introduction into the very basics of how to access and manipulate databases within PHP scripts.

Keep in mind this simple rule: defence in depth. In the more place you take the more action to increase the protection of your database, the less probability of that an attacker succeeds, and exposes or abuse any stored secret information. Good design of the database schema and the application deals with your greatest fears.


Designing Databases

The first step is always to create the database, unless you want to use an existing third party's one. When a database is created, it is assigned to an owner, who executed the creation statement. Usually, only the owner (or a superuser) can do anything with the objects in that database, and in order to allow other users to use it, privileges must be granted.

Applications should never connect to the database as its owner or a superuser, because these users can execute any query at will, for example, modifying the schema (e.g. dropping tables) or deleting its entire content.

You may create different database users for every aspect of your application with very limited rights to database objects. The most required privileges should be granted only, and avoid that the same user can interact with the database in different use cases. This means that if intruders gain access to your database using one of these credentials, they can only effect as many changes as your application can.

You are encouraged not to implement all the business logic in the web application (i.e. your script), instead to do it in the database schema using views, triggers or rules. If the system evolves, new ports will be intended to open to the database, and you have to reimplement the logic in each separate database client. Over and above, triggers can be used to transparently and automatically handle fields, which often provides insight when debugging problems with your application or tracing back transactions.


Connecting to Database

You may want to estabilish the connections over SSL to encrypt client/server communications for increased security, or you can use ssh to encrypt the network connection between clients and the database server. If either of them is done, then monitoring your traffic and gaining informations in this way will be a hard work.


Encrypted Storage Model

SSL/SSH protects data travelling from the client to the server, SSL/SSH does not protect the persistent data stored in a database. SSL is an on-the-wire protocol.

Once an attacker gains access to your database directly (bypassing the webserver), the stored sensitive data may be exposed or misused, unless the information is protected by the database itself. Encrypting the data is a good way to mitigate this threat, but very few databases offer this type of data encryption.

The easiest way to work around this problem is to first create your own encryption package, and then use it from within your PHP scripts. PHP can assist you in this case with its several extensions, such as Mcrypt and Mhash, covering a wide variety of encryption algorithms. The script encrypts the data be stored first, and decrypts it when retrieving. See the references for further examples how encryption works.

In case of truly hidden data, if its raw representation is not needed (i.e. not be displayed), hashing may be also taken into consideration. The well-known example for the hashing is storing the MD5 hash of a password in a database, instead of the password itself. See also crypt() and md5().

Exemplo 5-5. Using hashed password field

// storing password hash
$query  = sprintf("INSERT INTO users(name,pwd) VALUES('%s','%s');",
            addslashes($username), md5($password));
$result = pg_exec($connection, $query);

// querying if user submitted the right password
$query = sprintf("SELECT 1 FROM users WHERE name='%s' AND pwd='%s';",
            addslashes($username), md5($password));
$result = pg_exec($connection, $query);

if (pg_numrows($result) > 0) {
    echo "Welcome, $username!";
}
else {
    echo "Authentication failed for $username.";
}

SQL Injection

Many web developers are unaware of how SQL queries can be tampered with, and assume that an SQL query is a trusted command. It means that SQL queries are able to circumvent access controls, thereby bypassing standard authentication and authorization checks, and sometimes SQL queries even may allow access to host operating system level commands.

Direct SQL Command Injection is a technique where an attacker creates or alters existing SQL commands to expose hidden data, or to override valuable ones, or even to execute dangerous system level commands on the database host. This is accomplished by the application taking user input and combining it with static parameters to build a SQL query. The following examples are based on true stories, unfortunately.

Owing to the lack of input validation and connecting to the database on behalf of a superuser or the one who can create users, the attacker may create a superuser in your database.

Exemplo 5-6. Splitting the result set into pages ... and making superusers (PostgreSQL and MySQL)

$offset = argv[0]; // beware, no input validation!
$query  = "SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET $offset;";
// with PostgreSQL 
$result = pg_exec($conn, $query);
// with MySQL
$result = mysql_query($query);
Normal users click on the 'next', 'prev' links where the $offset is encoded into the URL. The script expects that the incoming $offset is decimal number. However, someone tries to break in with appending urlencode()'d form of the following to the URL

// in case of PostgreSQL
0;
insert into pg_shadow(usename,usesysid,usesuper,usecatupd,passwd)
    select 'crack', usesysid, 't','t','crack'
    from pg_shadow where usename='postgres';
--

// in case of MySQL
0;
UPDATE user SET Password=PASSWORD('crack') WHERE user='root';
FLUSH PRIVILEGES;

If it happened, then the script would present a superuser access to him. Note that 0; is to supply a valid offset to the original query and to terminate it.

Nota: It is common technique to force the SQL parser to ignore the rest of the query written by the developer with -- which is the comment sign in SQL.

A feasible way to gain passwords is to circumvent your search result pages. What the attacker needs only is to try if there is any submitted variable used in SQL statement which is not handled properly. These filters can be set commonly in a preceding form to customize WHERE, ORDER BY, LIMIT and OFFSET clauses in SELECT statements. If your database supports the UNION construct, the attacker may try to append an entire query to the original one to list passwords from an arbitrary table. Using encrypted password fields is strongly encouraged.

Exemplo 5-7. Listing out articles ... and some passwords (any database server)

$query  = "SELECT id, name, inserted, size FROM products
                  WHERE size = '$size'
                  ORDER BY $order LIMIT $limit, $offset;";
$result = odbc_exec($conn, $query);
The static part of the query can be combined with another SELECT statement which reveals all passwords:

'
union select '1', concat(uname||'-'||passwd) as name, '1971-01-01', '0' from usertable;
--

If this query (playing with the ' and --) were assigned to one of the variables used in $query, the query beast awakened.

SQL UPDATEs are also subject to attacking your database. These queries are also threatened by chopping and appending an entirely new query to it. But the attacker might fiddle with the SET clause. In this case some schema information must be possessed to manipulate the query successfully. This can be acquired by examing the form variable names, or just simply brute forcing. There are not so many naming convention for fields storing passwords or usernames.

Exemplo 5-8. From resetting a password ... to gaining more privileges (any database server)

$query = "UPDATE usertable SET pwd='$pwd' WHERE uid='$uid';";
But a malicious user sumbits the value ' or uid like'%admin%'; -- to $uid to change the admin's password, or simply sets $pwd to "hehehe', admin='yes', trusted=100 " (with a trailing space) to gain more privileges. Then, the query will be twisted:

// $uid == ' or uid like'%admin%'; --
$query = "UPDATE usertable SET pwd='...' WHERE uid='' or uid like '%admin%'; --";

// $pwd == "hehehe', admin='yes', trusted=100 "
$query = "UPDATE usertable SET pwd='hehehe', admin='yes', trusted=100 WHERE ...;"

A frightening example how operating system level commands can be accessed on some database hosts.

Exemplo 5-9. Attacking the database host's operating system (MSSQL Server)

$query  = "SELECT * FROM products WHERE id LIKE '%$prod%'";
$result = mssql_query($query);
If attacker submits the value a%' exec master..xp_cmdshell 'net user test testpass /ADD' -- to $prod, then the $query will be:

$query  = "SELECT * FROM products
                    WHERE id LIKE '%a%'
                    exec master..xp_cmdshell 'net user test testpass /ADD'--";
$result = mssql_query($query);

MSSQL Server executes the SQL statements in the batch including a command to add a new user to the local accounts database. If this application were running as sa and the MSSQLSERVER service is running with sufficient privileges, the attacker would now have an account with which to access this machine.

Nota: Some of the examples above is tied to a specific database server. This does not mean that a similar attack is impossible against other products. Your database server may be so vulnerable in other manner.


Avoiding techniques

You may plead that the attacker must possess a piece of information about the database schema in most examples. You are right, but you never know when and how it can be taken out, and if it happens, your database may be exposed. If you are using an open source, or publicly available database handling package, which may belong to a content management system or forum, the intruders easily produce a copy of a piece of your code. It may be also a security risk if it is a poorly designed one.

These attacks are mainly based on exploiting the code not being written with security in mind. Never trust on any kind of input, especially which comes from the client side, even though it comes from a select box, a hidden input field or a cookie. The first example shows that such a blameless query can cause disasters.

  • Never connect to the database as a superuser or as the database owner. Use always customized users with very limited privileges.

  • Check if the given input has the expected data type. PHP has a wide range of input validating functions, from the simplest ones found in Variable Functions and in Character Type Functions (e.g. is_numeric(), ctype_digit() respectively) onwards the Perl compatible Regular Expressions support.

  • If the application waits for numerical input, consider to verify data with is_numeric(), or silently change its type using settype(), or use its numeric representation by sprintf().

    Exemplo 5-10. A more secure way to compose a query for paging

    settype($offset, 'integer');
    $query = "SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET $offset;";
    
    // please note %d in the format string, using %s would be meaningless
    $query = sprintf("SELECT id, name FROM products ORDER BY name LIMIT 20 OFFSET %d;",
                     $offset);

  • Quote each non numeric user input which is passed to the database with addslashes() or addcslashes(). See the first example. As the examples shows, quotes burnt into the static part of the query is not enough, and can be easily hacked.

  • Do not print out any database specific information, especially about the schema, by fair means or foul. See also Error Reporting and Error Handling and Logging Functions.

  • You may use stored procedures and previously defined cursors to abstract data access so that users do not directly access tables or views, but this solution has another impacts.

Besides these, you benefit from logging queries either within your script or by the database itself, if it supports. Obviously, the logging is unable to prevent any harmful attempt, but it can be helpful to trace back which application has been circumvented. The log is not useful by itself, but through the information it contains. The more detail is generally better.


Error Reporting

With PHP security, there are two sides to error reporting. One is beneficial to increasing security, the other is detrimental.

A standard attack tactic involves profiling a system by feeding it improper data, and checking for the kinds, and contexts, of the errors which are returned. This allows the system cracker to probe for information about the server, to determine possible weaknesses. For example, if an attacker had gleaned information about a page based on a prior form submission, they may attempt to override variables, or modify them:

Exemplo 5-11. Attacking Variables with a custom HTML page

<form method="post" action="attacktarget?username=badfoo&password=badfoo">
<input type="hidden" name="username" value="badfoo">
<input type="hidden" name="password" value="badfoo">
</form>

The PHP errors which are normally returned can be quite helpful to a developer who is trying to debug a script, indicating such things as the function or file that failed, the PHP file it failed in, and the line number which the failure occured in. This is all information that can be exploited. It is not uncommon for a php developer to use show_source(), highlight_string(), or highlight_file() as a debugging measure, but in a live site, this can expose hidden variables, unchecked syntax, and other dangerous information. Especially dangerous is running code from known sources with built-in debugging handlers, or using common debugging techniques. If the attacker can determine what general technique you are using, they may try to brute-force a page, by sending various common debugging strings:

Exemplo 5-12. Exploiting common debugging variables

<form method="post" action="attacktarget?errors=Y&amp;showerrors=1"&debug=1">
<input type="hidden" name="errors" value="Y">
<input type="hidden" name="showerrors" value="1">
<input type="hidden" name="debug" value="1">
</form>

Regardless of the method of error handling, the ability to probe a system for errors leads to providing an attacker with more information.

For example, the very style of a generic PHP error indicates a system is running PHP. If the attacker was looking at an .html page, and wanted to probe for the back-end (to look for known weaknesses in the system), by feeding it the wrong data they may be able to determine that a system was built with PHP.

A function error can indicate whether a system may be running a specific database engine, or give clues as to how a web page or programmed or designed. This allows for deeper investigation into open database ports, or to look for specific bugs or weaknesses in a web page. By feeding different pieces of bad data, for example, an attacker can determine the order of authentication in a script, (from the line number errors) as well as probe for exploits that may be exploited in different locations in the script.

A filesystem or general PHP error can indicate what permissions the webserver has, as well as the structure and organization of files on the web server. Developer written error code can aggravate this problem, leading to easy exploitation of formerly "hidden" information.

There are three major solutions to this issue. The first is to scrutinize all functions, and attempt to compensate for the bulk of the errors. The second is to disable error reporting entirely on the running code. The third is to use PHP's custom error handling functions to create your own error handler. Depending on your security policy, you may find all three to be applicable to your situation.

One way of catching this issue ahead of time is to make use of PHP's own error_reporting(), to help you secure your code and find variable usage that may be dangerous. By testing your code, prior to deployment, with E_ALL, you can quickly find areas where your variables may be open to poisoning or modification in other ways. Once you are ready for deployment, by using E_NONE, you insulate your code from probing.

Exemplo 5-13. Finding dangerous variables with E_ALL

<?php
if ($username) {  // Not initialized or checked before usage
    $good_login = 1;
}
if ($good_login == 1) { // If above test fails, not initialized or checked before usage
    fpassthru ("/highly/sensitive/data/index.html");
}
?>


Using Register Globals

One feature of PHP that can be used to enhance security is configuring PHP with register_globals = off. By turning off the ability for any user-submitted variable to be injected into PHP code, you can reduce the amount of variable poisoning a potential attacker may inflict. They will have to take the additional time to forge submissions, and your internal variables are effectively isolated from user submitted data.

While it does slightly increase the amount of effort required to work with PHP, it has been argued that the benefits far outweigh the effort.

Exemplo 5-14. Working with register_globals=on

<?php
if ($username) {  // can be forged by a user in get/post/cookies
    $good_login = 1;
}

if ($good_login == 1) { // can be forged by a user in get/post/cookies,
    fpassthru ("/highly/sensitive/data/index.html");
}
?>

Exemplo 5-15. Working with register_globals = off

<?php
if($_COOKIE['username']){
    // can only come from a cookie, forged or otherwise
    $good_login = 1;
    fpassthru ("/highly/sensitive/data/index.html");
}
?>
By using this wisely, it's even possible to take preventative measures to warn when forging is being attempted. If you know ahead of time exactly where a variable should be coming from, you can check to see if submitted data is coming from an inappropriate kind of submission. While it doesn't guarantee that data has not been forged, it does require an attacker to guess the right kind of forging.

Exemplo 5-16. Detecting simple variable poisoning

<?php
if ($_COOKIE['username'] &&
    !$_POST['username'] &&
    !$_GET['username'] ) {
    // Perform other checks to validate the user name...
    $good_login = 1;
    fpassthru ("/highly/sensitive/data/index.html");
} else {
   mail("admin@example.com", "Possible breakin attempt", $_SERVER['REMOTE_ADDR']);
   echo "Security violation, admin has been alerted.";
   exit;
}
?>
Of course, simply turning off register_globals does not mean code is secure. For every piece of data that is submitted, it should also be checked in other ways.


User Submitted Data

The greatest weakness in many PHP programs is not inherent in the language itself, but merely an issue of code not being written with security in mind. For this reason, you should always take the time to consider the implications of a given piece of code, to ascertain the possible damage if an unexpected variable is submitted to it.

Exemplo 5-17. Dangerous Variable Usage

<?php
// remove a file from the user's home directory... or maybe
// somebody else's?
unlink ($evil_var);

// Write logging of their access... or maybe an /etc/passwd entry?
fputs ($fp, $evil_var);

// Execute something trivial.. or rm -rf *?
system ($evil_var);
exec ($evil_var);

?>
You should always carefully examine your code to make sure that any variables being submitted from a web browser are being properly checked, and ask yourself the following questions:

  • Will this script only affect the intended files?

  • Can unusual or undesirable data be acted upon?

  • Can this script be used in unintended ways?

  • Can this be used in conjunction with other scripts in a negative manner?

  • Will any transactions be adequately logged?

By adequately asking these questions while writing the script, rather than later, you prevent an unfortunate re-write when you need to increase your security. By starting out with this mindset, you won't guarantee the security of your system, but you can help improve it.

You may also want to consider turning off register_globals, magic_quotes, or other convenience settings which may confuse you as to the validity, source, or value of a given variable. Working with PHP in error_reporting(E_ALL) mode can also help warn you about variables being used before they are checked or initialized (so you can prevent unusual data from being operated upon).


Hiding PHP

In general, security by obscurity is one of the weakest forms of security. But in some cases, every little bit of extra security is desirable.

A few simple techniques can help to hide PHP, possibly slowing down an attacker who is attempting to discover weaknesses in your system. By setting expose_php = off in your php.ini file, you reduce the amount of information available to them.

Another tactic is to configure web servers such as apache to parse different filetypes through PHP, either with an .htaccess directive, or in the apache configuration file itself. You can then use misleading file extensions:

Exemplo 5-18. Hiding PHP as another language

# Make PHP code look like other code types
AddType application/x-httpd-php .asp .py .pl
Or obscure it completely:

Exemplo 5-19. Using unknown types for PHP extensions

# Make PHP code look like unknown types
AddType application/x-httpd-php .bop .foo .133t
Or hide it as html code, which has a slight performance hit because all html will be parsed through the PHP engine:

Exemplo 5-20. Using html types for PHP extensions

# Make all PHP code look like html
AddType application/x-httpd-php .htm .html
For this to work effectively, you must rename your PHP files with the above extensions. While it is a form of security through obscurity, it's a minor preventative measure with few drawbacks.


Keeping Current

PHP, like any other large system, is under constant scrutiny and improvement. Each new version will often include both major and minor changes to enhance and repair security flaws, configuration mishaps, and other issues that will affect the overall security and stability of your system.

Like other system-level scripting languages and programs, the best approach is to update often, and maintain awareness of the latest versions and their changes.

II. Referência da Linguagem


Capítulo 6. Sintaxe básica

Alternado/Escaping do HTML

Quando o PHP interpreta um arquivo, ele simplesmente repassa o texto do arquivo até encontrar uma das tags especiais que lhe diz para começar a interpretar o texto como código PHP. O interpretador então executa todo o código que encontra, até chegar em uma tag de fechamento PHP, que novamente o coloca simplesmente repassando texto novamente. Este é o mecanismo que permite a inclusão de código PHP dentro do HTML: qualquer coisa fora das tags PHP é deixado como encontrado, enquanto tudo dentro é interpretado e executado.

Há quatro conjuntos de tags que podem ser usadas para marcar blocos de código PHP. Delas, somente duas (<?php. . .?> e <script language="php">. . .</script>) são sempre disponíveis. As outras podem ser ativadas ou desativadas a partir do arquivo de configuração php.ini. Enquanto as formas reduzidas das tags ou no seu estilo ASP serem convenientes, elas não são portáveis em todas as versões. Além disso, se você pretende incluir código PHP em XML ou XHTML, você precisará usar a forma <?php ... ?> para compatibilidade com o padrão XML.

As tags suportadas pelo PHP são:

Exemplo 6-1. Maneiras de alternar do HTML

1.  <?php echo("se você precisa dispor documentos XHTML ou XML, use assim\n"); ?>

2.  <? echo ("este é o mais simples, como uma instrução de processamento SGML\n"); ?>
    <?= espressao ?> Uma redução de "<? echo expressao ?>"

3.  <script language="php">
        echo ("alguns editores (como o FrontPage) não
              gostam de processas instruções");
    </script>

4.  <% echo ("Você também pode usar tags ASP opcionalmente"); %>
    <%= $variavel; # Uma redução para "<% echo ..." %>

O primeiro método, <?php. . .?>, é o preferencial, já que ele permite o uso do PHP em códigos padrão XML como o XHTML.

O segundo método pode não estar sempre disponível. Tags curtas estão disponíveis apenas quando ativadas. Isto pode ser realizando através da função short_tags() (PHP 3 somente), ativando a diretiva de configuração short_open_tag no arquivo de configuração do PHP ou compilando o PHP com a opção --enable-short-tags no configure. Mesmo que ele esteja configurado por default no php.ini-dist, o uso de tags curtas é desencorajado.

A quarta maneira só está disponível se a tag estilo ASP for ativada utilizando a diretiva asp_tags no arquivo de configuração.

Nota: O suporte as tags estilo APS foi incorporada na versão 3.0.4.

Nota: A utilização das tags curtas deve ser evitada quando do desenvolvimento de aplicações ou bibliotecas com intenção de redistribuição ou no desenvolvimento de serviços em PHP que não ficarão sob seu controle, uma vez que as tags curtas podem não estar disponíveis no servidor de instalação. Para portabilidade de código para distribuição, tenha certeza de não usar tags curtas.

A tag de fechamento incluirá uma linha nova linha em branco automaticamente se uma não estiver presente. Além, a tag de fechamento automaticamente implica num ponto e vírgula: você não precisa ter um ponto e vírgula no fim da última linha de código PHP.

O PHP também suporta a utilização de estruturas como essa:

Exemplo 6-2. Alternagem avançada

<?php
if ($expression) {
    ?>
    <strong>Isso é verdadeiro.</strong>
    <?php
} else {
    ?>
    <strong>Isto é falso.</strong>
    <?php
}
?>
Isso funciona como esperado porque quando o PHP encontra a tag de fechamento ?>, ele simplesmente começa a imprimir tudo até encontrar outra tag de abertura. Obviamente, o exemplo acima se aplica a exibição de grandes blocos de texto, uma vez que sair do modo de interpretação do PHP é geralmente mais eficiente que imprimir todo o texto através de funções como echo(), print() e outras.


Separador de instruções

Instruções são separadas da mesma forma que o C ou o Perl - cada instrução termina com um ponto e vírgula.

A tag de fechamento (?>) também implica no fim de uma instrução, então os exemplos seguintes são equivalentes:

<?php
    echo "Isto é um teste";
?>

<?php echo "Isto é um outro teste" ?>


Comentários

O PHP suporta comentários do 'C', 'C++' e Unix shell. Por exemplo

<?php
    echo "Isto é um teste"; //Comentário de uma linha no C++
    /* Isto é um comentário de mais de uma linha
       e aqui temos outra linha */
    echo "Isto é um outro teste";
    echo "O último teste"; #Comentário no estilo Unix shell
?>

Os comentário de uma linha só tem efeito até o fim da linha ou fim do bloco de código PHP atual, o que ocorrer primeiro.

<h1>Isto é um <?php # echo " simples";?> exemplo.</h1>
<p>No título acima você lerá 'Isto é um exemplo'.

Você precisa ser cuidadoso com comentários estilo 'C' encadeados, pois eles podem causar problemas em grandes blocos.

<?php
 /*
    echo "Isto é um teste"; /* Este comentário causará um erro */
 */
?>

Os comentários de uma linha somente agem até o fim da linha atual ou o fim do bloco de código PHP, o que ocorrer primeiro. Isto significa que código HTML após // ?> SERÁ impresso: ?> continuará desligando o modo PHP, retornando para o modo HTML, e o // não pode influenciar isso.


Capítulo 7. Tipos

Introdução

O PHP suporta os oitos tipos primitivos.

São quatros tipos básicos:

Dois tipos compostos:

E finalmente dois tipos especiais:

Este manual também introduz alguns pseudo-tipos por razões de legibilidade:

O tipo da variável geralmente não é configurado pelo programador: isto é decidido em tempo de execução pelo PHP, dependendo do contexto no qual a variável é usada.

Nota: Se você quiser checar o tipo e valor de uma certa expressão, utilize var_dump().

Se você simplesmente quiser uma representação legível de seu tipo para debugagem, use gettype(). Para verificar por certos tipos, não use gettype(), mas sim as funções is_type.

Se você quiser forçar a conversão de uma variável para um certo tipo, você pode moldar (casting) a variável ou usar a função settype() nela.

Note que uma variável pode se comportar de maneiras diferentes em certas situações, dependendo de qual tipo ela é no momento. Para mais informações, veja a seção Manipulação de tipos.


Booleanos

Este é o tipo mais fácil. Umbooleano expressa um valor de 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 insensitivas ao caso.

$foo = True; // assimila o valor TRUE para $foo

Usualmente você pode utilizar algum tipo de operador que retorne um valor booleano, e passá-lo para uma estrutura de controle.

// == é um operador que 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.

Quando convertendo para booleano, os seguintes valores são considerados FALSE:

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

Atenção

-1 é considerado TRUE, como qualquer valor não zero (negativos ou positivos)!


Inteiros

Um inteiro é um número do conjunto Z = {..., -2, -1, 0, 1, 2, ...}.

Veja também: Inteiros de tamanho arbitrário e Números de ponto flutuante


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

$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)
O tamanho de um inteiro é dependente de plataforma, sendo um numero aproximado a 2 bilhões o valor mais comum (número de 32 bits com sinal). O PHP não suporta inteiros não sinalizados.


Overflow de inteiros

Se você especifica um número além dos limites do tipo inteiro, ele será interpretado como um ponto flutuante. Assim, se você realizar uma operação que resulte em um número além dos limites do tipo inteiro, um ponto flutuante será retornado também.

$ numero_grande =  2147483647;
var_dump($numero_grande);
// saida: int(2147483647)

$numero_grande =  2147483648;
var_dump($numero_grande);
// saida: float(2147483648)

// isto também é permitido para especificação de números hexadecimais:
var_dump( 0x80000000 );
// saida: float(2147483648)

$milhao = 1000000;
$numero_grande =  50000 * $milhao;
var_dump($numero_grande);
// saida: float(50000000000)

Atenção

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.

var_dump( 25/7 );
// saida: float(3.5714285714286)


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.

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!

Atenção

Nunca modifique uma fração desconhecida para inteiro, porque isto pode fornecer resultados inesperados as vezes.

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 strings

Veja Conversão de strings


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 (AKA "floats", "doubles" ou "números reais") podem ser especificados utilizando qualquer uma das sintaxes seguintes:
$a = 1.234; $a = 1.2e3; $a = 7E-10;
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 decimais digitais um valor comum (número de 64 bits no formato IEEE).

Precisão de números de ponto flutuante

É sabido 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.


Strings

Uma string é uma série de caracteres. No PHP, 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.

Nota: Não há nenhum problema nas strings se tornarem muito grandes. Não há nenhum limite para o tamanho de strings imposta pelo PHP, então não há razão para se preocupar com strings longas.


Sintaxe

Uma string literal pode ser especificada de três 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.

Nota: No PHP 3, um aviso com nível E_NOTICE será emitido quando isto acontecer.

Nota: Diferentemente das duas outras sintaxes, variáveis não serão substituídas quando elas ocorrerem dentro de strings delimitadas por apóstrofes.

echo 'isto é uma string comum';
echo 'Você pode incluir novas linhas em strings,
dessa maneira';
echo 'Arnold disse uma vez: "I\'ll be back"';
// saida: ... "I'll be back"
echo 'Você tem certeza em apagar C:\\*.*?';
// saida: ... apagar C:\*.*?
echo 'Você tem certeza em apagar C:\*.*?';
// output: ... apagar C:\*.*?
echo 'Estou tentando incluir uma nova linha \n neste ponto';
// output: ... nova linha \n neste ponto


Aspas

Se a string é delimitada entre aspas ("), o PHP entende mais seqüências de escape para caracteres especiais:

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

Novamente se você tentar escapar qualquer outro caracter, a contra barra será impressa também!

Mas o mais importante dado a respeito 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

Outra maneira para delimitar strings é utilizando a sintaxe heredoc ("<<<"). É informado um identificador depois de <<<, então a string, e então o mesmo identificador para fechar a delimitação.

O identificador de fechamento precisa começar na primeira coluna da linha. Além, o identificador utilizado 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.

Atenção

É 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 endentado, e que não pode haver nenhum espaço ou tabulações antes ou depois do ponto e vírgula.

Textos heredoc se comportam como strings 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 7-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;
?>

Nota: O suporte a heredoc foi acrescentado no PHP 4.


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

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.

$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

Similarmente, você também pode interpretar um índice de array ou uma propriedade de objeto. Com índices de arrays, o colchete de fechamento (]) marca o final do índice. Para propriedades de objetos se aplicam as mesmas regras das variáveis comuns, embora não exista um truque para as propriedades de objetos como para as variáveis.

$frutas = array( 'morangos' => 'vermelho' , 'banana' => 'amarelo' );

// note que isto funciona diferentemente fora de delimitadores de string
echo "Uma banana é $frutas[banana].";

echo "Este quadrado tem $square->width metros de lado.";

// Não 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 desta maneira.

De fato, você pode incluir qualquer valor no que esteja no espaço de nomes dentro de strings com esta sintaxe. Você simplesmente escreve a expressão da mesma maneira que faria fora da string, e então incluí-la entre chaves. Desde que você não pode escapar '{', esta sintaxe somente será reconhecida quando o $ é imediatamente seguido de um {. (Utilize "{\$" ou "\{$" para obter um literal "{$"). Alguns exemplos para tornar isso mais claro:

$maravilhoso = 'fantástico';
echo "Isto é { $maravilhoso}"; // não funciona, imprime: Isto é { fantástico}
echo "Isto é {$maravilhoso}";  // funciona, imprime: Isto é fantástico
echo "Este quadrado tem {$square->width}00 centímetros de lado.";
echo "E isto funciona: {$arr[4][3]}";

// E isto está errado pela mesma razão
// como $foo[bar] é incorreto fora de uma string.
echo "Isto está errado: {$arr[foo][3]}";

echo "Você deve fazer desta maneira: {$arr['foo'][3]}";
echo "Você pode sempre escrever {$obj->values[3]->name}";
echo "Este é o valor da variável chamada $name: {${$name}}";


Acesso a caracteres da string

Caracteres nas strings podem ser acessados apenas especificando o deslocamento baseado em zero do caracter desejado depois da string dentro de chaves.

Nota: Para manutenção de compatibilidade, você ainda pode utilizar colchetes. Entretanto, esta sintaxe for marcada como em extinção desde o PHP 4.

Exemplo 7-3. Alguns exemplos com strings

<?php
/* Assimilando uma string. */
$str = "Isto é uma string";

/* Anexando a ela. */
$str = $str . " com uma pouco mais de texto";

/* Outra maneira de acrescentar, incluindo uma nova linha. */
$str .= " e um fim de linha no final (duh).\n";

/* Esta string será mostrada assim '<p>Número: 9</p>' */
$num = 9;
$str = "<p>Número: $num</p>";

/* Isto será apenas '<p>Número: $num</p>' */
$num = 9;
$str = '<p>Número: $num</p>';

/* Pega o primeiro caracter de uma string */
$str = 'Isto é um teste.';
$first = $str{0};

/* Pega o último caracter da string. */
$str = 'Isto ainda é um teste.';
$last = $str{strlen($str)-1};
?>


Funções ú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á uma grande quantidade de 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 para busca e substituição avançada.(em dois sabores: Perl e POSIX estendido).

Há também funções para strings URL e funções para criptografia e descriptografia de strings (mcrypt e mhash).

Finalmente, se você ainda não encontrar o que está procurando, veja também as funções de tipos de caracteres.


Conversão de strings

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.

$foo = 1 + "10.5";                // $foo é ponto flutuante (11.5)
$foo = 1 + "-1.3e3";              // $foo é ponto flutuante (-1299)
$foo = 1 + "bob-1.3e3";           // $foo é ponto inteiro (1)
$foo = 1 + "bob3";                // $foo é ponto inteiro (1)
$foo = 1 + "10 Small Pigs";       // $foo é ponto inteiro (11)
$foo = 4 + "10.2 Little Piggies"; // $foo é ponto flutuante (14.2)
$foo = "10.0 pigs " + 1;          // $foo é ponto flutuante (11)
$foo = "10.0 pigs " + 1.0;        // $foo é ponto flutuante (11)

Para mais informações sobre esta conversão, veja página do manual UNIX de strtod(3).

Se você deseja testar qualquer um dos exemplo dessa seção, você pode copiar e colar os exemplos e inserir as linhas seguintes para ver por si mesmo como isso funciona.

echo "\$foo==$foo; tipo " . gettype ($foo) . "<br />\n";


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 .

Uma chave pode ser tanto um inteiro ou uma string. Se a chave é uma representação padrão de um inteiro, ele será interpretado assim (por exemplo, "8" será interpretado como 8, enquanto "08" será interpretado como "08").

O valor pode ser qualquer coisa.

Se omitir a chave, o maior índice inteiro é obtido, e a nova chave será esse máximo + 1. Como inteiros podem ser negativos, isto também é verdadeiro para índices negativos. Sendo, por exemplo, o maior índice -6, resultará em um novo índice -5. Se nenhum índice inteiro existir ainda, a chave será 0 (zero). Se você especifica uma chave que já possui um valor assimilada a ela, então o valor é sobrescrito.

Utilizar true como chave será interpretado como inteiro 1 na chave. Utilizando false como chave será avaliado como o inteiro 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.

array( [chave =>] valor
     , ...
     )
// chave pode ser string ou integer não negativo
// valor pode ser qualquer coisa


Criando/modificando com a sintaxe de colchetes

Você pode também modificar um array existente, explicitando assimilando valores.

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 string ou inteiro não negativo
// 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 nele. Se você quiser remover um par chave/valor, você precisa aplicar unset() nele.


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.

$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');
*/

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:

$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 constantes não definidas são convertidas em uma string com o mesmo nome.

Como explicado na seção sintaxe, a chave precisa estar entre colchetes ('[' e ']'). Isto significa que você pode escrever coisas como isso:

echo $arr[ foo(true) ];

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 E_* antes.

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

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

Então, como é possível que $foo[bar] funcione? 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, 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: Quando você liga error_reporting em E_ALL, você irá ver as notícias que o PHP gera quando um índice é utilizado sem ser definido (coloque a linha error_reporting(E_ALL); em seu script).

Nota: Com strings delimitadas por aspas, uma outra sintaxe é válida. Veja interpretação de variáveis em string para mais detalhes.


Exemplos

O tipo array do PHP é muito versátil, por isso temos aqui alguns exemplos para mostrar todo o poder dos arrays.

// isto
$a = array( 'color' => 'vermelha'
          , 'taste' => 'doce'
          , 'shape' => 'redonda'
          , 'name'  => 'maçã'
          ,            4        // a chave será 0
          );

// isto é equivalente a acima
$a['cor'] = 'vermelha';
$a['sabor'] = 'doce';
$a['formato'] = '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 7-4. Utilizando array()

// Array como (propriedade-)mapa
$map = array( 'versão'     => 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 7-5. Coleção

$cores = array('vermelho','azul','verde','amarelo');

foreach ( $cores as $cor ) {
    echo "Você gosta de $cor?\n";
}

/* saida:
Você gosta de vermelho?
Você gosta de azul?
Você gosta de verde?
Você gosta de amarelo?
*/

Note que atualmente não se pode mudar os valores de um array diretamente dentro de um loop. Superar essa limitação é possível da seguinte forma:

Exemplo 7-6. Coleção

foreach ($cores as $key => $cor) {
    // não funciona:
    //$cor = strtoupper($cor);

    //funciona:
    $cores[$key] = strtoupper($cor);
}
print_r($cores);

/* saida:
Array
(
    [0] => VERMELHO
    [1] => AZUL
    [2] => VERDE
    [3] => AMARELO
)
*/

Este exemplo cria um array na base 1.

Exemplo 7-7. Array baseado em 1

$primeiroquarto  = array(1 => 'Janeiro', 'Fevereiro', 'Março');
print_r($primeiroquarto);

/* saida:
Array
(
    [1] => 'Janeiro'
    [2] => 'Fevereiro'
    [3] => 'Março'
)
*/

Exemplo 7-8. Preenchendo um array real

// preenchendo um array com todos os itens de um diretório
$handle = opendir('.');
while ($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.

Exemplo 7-9. Ordenando arrays

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-10. Arrays recursivos e multidimensionais

$fruits = array ( "frutas"  => array ( "a" => "laranja"
                                     , "b" => "banana"
                                     , "c" => "maçã"
                                     )
                , "numeros" => array ( 1
                                     , 2
                                     , 3
                                     , 4
                                     , 5
                                     , 6
                                     )
                , "buracos" => array (      "primeiro"
                                     , 5 => "segundo"
                                     ,      "terceiro"
                                     )
                );

Objetos

Inicialização de objetos

Para inicializar um objeto, você usa a instrução new, criando uma instância do objeto em uma variável.

<?php
class foo
{
    function do_foo()
    {
        echo "Fazendo foo.";
    }
}

$bar = new foo;
$bar->do_foo();
?>

Para uma explicação completa, consulte a seção Classes e Objetos.


Resource

Recurso é uma variável especial, mantendo uma referência de recurso externo. Recursos são criados e utilizados 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


Liberando recursos

Através do sistema de contagem de referências introduzido com o engine da Zend no PHP 4, é automaticamente detectado quando um recurso não mais é referenciado (assim como o 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 (insensitiva ao caso) NULL.

$var = NULL;

Veja também is_null() e unset().


Pseudo-tipos 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

Some functions like call_user_function() or usort() accept user defined callback functions as a parameter. Callback functions can not only be simple functions but also object methods including static class methods.

A PHP function is simply passed by its name as a string. You can pass any builtin or user defined function with the exception of array(), echo(), empty(), eval(), exit(), isset(), list(), print() and unset().

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.

Exemplo 7-11. Exemplo de funções callback

<?php

// Exemplo simples de callback
function foobar() {
    echo "Olá mundo!";
}
call_user_function("foobar");

// Exemplo de métodos callback
class foo {
  function bar() {
    echo "Olá mundo!";
  }
}

$foo = new foo;

call_user_function(array($foo, "bar")); // chamada do método do objeto

call_user_function(array("foo", "bar")); // chamada do método estático da classe

?>


Manipulação de tipos

O PHP não requer (ou suporta) a definição de tipo explicita 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ê assimila um valor string para a variável var, var se torna uma string. Se você então assimila 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 inteiros então o resultado será um inteiro. Note que isso NÃO muda os tipos dos operadores: apenas muda em como esses operadores são avaliados.

$foo = "0";  // $foo é string (ASCII 48)

$foo += 2;   // $foo é agora um inteiro (2)
$foo = $foo + 1.3;  // $foo é agora um float (3.3)
$foo = 5 + "10 Little Piggies"; // $foo é inteiro (15)
$foo = 5 + "10 Small Pigs";     // $foo é inteiro (15)

Se os últimos dois exemplos lhe parecerem estranhos, veja Conversão de strings.

Se você deseja 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().

Se quiser 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.

$a = "1";     // $a é uma string
$a[0] = "f";  // E com relação aos índices da string? O que acontece?

Desde que o PHP suporta indexação de strings através de offsets utilizando a mesma sintaxe da indexação de arrays, o exemplo acima nos deixa um problema: $a se tornou um array sendo o primeiro elemento "f", ou será que "f" se tornou o primeiro caracter da string $a ?

Por essa razão, como no PHP 3.0.12 e PHP 4.0b3-RC4, o resultado dessa conversão automática é considerada como indefinida. Correções, entretanto, estão sendo discutidas.


Moldando Tipos - Type Casting

A moldagem 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.

$foo = 10;   // $foo é um inteiro
$bar = (float) $foo;   // $bar é um número de ponto flutuante

As moldagens permitidas são:

  • (int), (integer) - molde para inteiro

  • (bool), (boolean) - molde para booleano

  • (float), (double), (real) - molde para número de ponto flutuante

  • (string) - molde para string

  • (array) - molde para array

  • (object) - molde para objeto

Nota: Em vez de moldar uma variável para string, você também pode circundar a variável entre aspas.

Note que tabulações e espaços são permitidos dentro dos parênteses, então o seguinte são funcionalmente equivalentes:

$foo = (int) $bar;
$foo = ( int ) $bar;

Pode não ser tão óbvio o que exatamente ocorre quando se molda entre certos tipos. Para mais informações, veja essas seções:

Quando moldando ou forçando a conversão de um array para string, o resultado será a palavra Array. Quando moldando ou forçando o tipo de um objeto para string, o resultado será a palavra Object.

Quando moldando de uma variável escalar ou string para um array, a variável se torna o primeiro elemento do array:

$var = 'ciao';
$arr = (array) $var;
echo $arr[0];  // outputs 'ciao'

Quando moldando de uma variável escalar ou string para um objeto, a variável se torna um atributo do objeto: o nome do atributo se chamará 'scalar':

$var = 'ciao';
$obj = (object) $var;
echo $obj->scalar;  // imprime 'ciao'


Capítulo 8. Variáveis

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 nossos propósitos, as letras a-z, A-Z e os caracteres ASCII de 127 a 255 (0x7f-0xff).

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

No PHP 3, 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 4 oferece um outro meio de atribuir valores a variáveis: a 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. Isto significa também que nenhuma cópia é realizada, de modo que a atribuição ocorre mais rapidamente. Entretanto, qualquer aumento de velocidade só será realmente notado em *loops* complexos ou em atribuições de grandes arrays ou objetos.

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


Variáveis Predefinidas

O PHP oferece um grande número de variáveis predefinidas 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.

Atenção

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 predefinidas 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 Predefinidas 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 'autoglobais' ou '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 predefinidas do PHP e sua natureza, veja a seção Variáveis Predefinidas. Veja também que todas as outras variáveis predefinidas antigas ($HTTP_*_VARS) ainda existem.

Se todos os indicadores não estiverem configurados no variables_order, seus arrays superglobais predefinidos respectivos estarão vazios.

Superglobais do PHP

$GLOBALS

Contém um referência para todas as variáveis que são atualmente disponíveis dentro do escopo global do script. As chaves desse array são os nomes das variáveis globais. $GLOBALS existe desde o PHP 3.

$_SERVER

Variáveis criadas pelo servidor web ou diretamente relacionadas ao ambiente de execução do script atual. Análogo ao antigo array $HTTP_SERVER_VARS (que ainda continua disponível, mas em decadência).

$_GET

Variáveis postadas para o script via método HTTP GET. Análogo ao antigo array $HTTP_GET_VARS (que ainda continua disponível, mas em decadência).

$_POST

Variáveis postadas para o script via método HTTP POST. Análogo ao antigo array $HTTP_POST_VARS (que ainda continua disponível, mas em decadência).

$_COOKIE

Variáveis postadas para o script via cookies HTTP. Análogo ao antigo array $HTTP_COOKIE_VARS (que ainda continua disponível, mas em decadência).

$_FILES

Variáveis postadas para o script via transferência de arquivos HTTP. Análogo ao antigo array $HTTP_POST_FILES (que ainda continua disponível, mas em decadência). Veja uploads via método POST para maiores informações.

$_ENV

Variáveis disponíveis no script do ambiente de execução. Análogo ao antigo array $HTTP_ENV_VARS (que ainda continua disponível, mas em decadência).

$_REQUEST

Variáveis postadas para o script por todas os mecanismos de input, e que não podem ter seu conteúdo garantido de qualquer forma. A presença e a ordem de inclusão das variáveis nesse array é definida de acordo com a diretiva de configuração variables_order. Este array não tem um equivalente nas versões anteriores do PHP 4.1.0. Veja também import_request_variables().

Nota: Quando executando na linha de comando , isto não inclui as entradas argv e argc; elas estão presentes no array $_SERVER.

$_SESSION

Variáveis que estão atualmente registradas na sessão do script. Análogo ao antigo array $HTTP_SESSION_VARS (que ainda continua disponível, mas em decadência). Veja a sessão funções de manipulação de Sessões para maiores informações.


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) */
}

Test();
?>

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. Um exemplo:

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

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

<?php
function test_global()
{
    // A maioria das variaveis predefinidas nao sao 'super' e requerem
    // 'global' para serem disponiveis para funcoes em qualquer escopo.
    global $HTTP_POST_VARS;

    print $HTTP_POST_VARS['name'];

    // Superglobais são disponiveis em qualquer escopo e
    // nao precisam de 'global'. Superglobais existem
    // desde o PHP 4.1.0
    print $_POST['name'];
}
?>

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:

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

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

<?php
function Teste()
{
    static $count = 0;

    $count++;
    echo $count;
    if ($count < 10) {
        Test ();
    }
    $count--;
}
?>

O Zend Engine 1, base do PHP4, implementa os modificadores static e global para variáveis em termos de referência. Por exemplo, uma variá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.

Atenção

Verifique que variáveis variáveis não podem ser utilizadas com os novos arrays superglobais. Isto significa que você não pode fazer coisas como ${$_GET}. Se você está procurando uma maneira de manipular as superglobais como as antigas HTTP_*_VARS, você deve tentar referenciá-las.


Variáveis externas ao PHP

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 8-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 8-2. Acessando dados de um formulário HTML via POST

<?php
// Disponível desde o PHP 4.1.0

   print $_POST['username'];
   print $_REQUEST['username'];

   import_request_variables('p', 'p_');
   print $p_username;

// Disponível deste o PHP 3.

   print $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.

   print $username;
?>

Utilizar um formulário GET é similar, exceto que você use a variável GET predefinida. 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 8-3. Variáveis de formulários mais complexos

<?php
if ($HTTP_POST_VARS['action'] == 'submitted') {
    print '<pre>';

    print_r($HTTP_POST_VARS);
    print '<a href="'. $HTTP_SERVER_VARS['PHP_SELF'] .'">De novo</a>';

    print '</pre>';
} else {
?>
<form action="<?php echo $HTTP_SERVER_VARS['PHP_SELF']; ?>" 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="hidden" name="action" value="submitted">
    <input type="submit" name="submit" value="Enviar dados!">
</form>
<?php
}
?>

No PHP 3, os arrays variáveis de formulários eram limitados a uma dimensão. No PHP 4, essa restrição não existe mais.


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 8-4. Exemplo setcookie()

<?php
$count++;
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.


Capítulo 9. Constantes

Uma constante é um identificador (nome) para um valor simples. Como o nome sugere, esse valor não pode mudar durante a execução do script (as 'constantes mágicas' __FILE__ e __LINE__ parecem ser uma exceção a essa regra, mas elas não são realmente constantes). As constantes são sensíveis ao caso 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]*

Nota: Para nossos exemplos, as letras a-z, A-Z e os caracteres ASCII do 127 ao 255 (0x7f-0xff).

O escopo de uma constante é global. Você pode acessá-la em qualquer lugar em seu script sem se preocupar com seus escopo.


Sintaxe

Você pode definir uma constante utilizando-se da função define(). Quando uma constante é definida, ela não pode ser mais modificada ou anulada.

Somente dados escalares (boolean, integer, float e string) pode ser colocados em constantes.

Você pode obter o valor de uma constante simplismente especificando seu nome. Diferentemente de variáveis, você não pode prefixar 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. Uma notice será informada quando isso acontecer. Use a função defined() se você precisar saber se uma constante está definida ou não.

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ó podem conter valores escalares.

Exemplo 9-1. Definindo Constantes

<?php
define("CONSTANT", "Hello world.");
echo CONSTANT; // imprime "Hello world."
echo Constant; // imprime "Constant" e gera um alerta notice.
?>


Constantes Predefinidas

O PHP fornece um grande número de constantes 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, por carregamento dinamico ou por compilação direta.

A lista de constantes predefinidas está disponível na seção Constantes Predefinidas.


Capítulo 10. 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:

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 funções), 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.

Obviamente, os valores em PHP não têm que ser inteiros, e muito freqüentemente eles não são. O PHP suporta três tipos de valores escalares: valores inteiros, valores de ponto flutuante e valores de string (valores escalares são valores que você não pode quebrar em pedaços menores, diferente de matrizes, por exemplo). O PHP também suporta dois tipos compostos (não-escalares): matrizes e objetos. Cada um destes tipos de valor podem ser atribuídos a variáveis ou retornadas de funções.

Até agora, os usuários de PHP/FI 2 não sentiriam qualquer mudança. Porém, o PHP traz expressões bem mais novas, da mesma forma que muitas outras linguagens. 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, 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/FI 2 e muitas outras linguagens podem estar familiarizados com a notação de variável++ e variável--. Estes são os operadores de incremento e decremento. 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 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ão são expressões de comparação. Estas expressões são avaliadas como 0 ou 1, significando FALSE ou TRUE, respectivamente. O PHP suporta > (maior que), >= (maior ou igual), == (igual), != (diferente), < (menor que) e <=(menor ou igual). Estas expressões são usadas mais freqüentemente dentro de instruções condicionais, como em 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:

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

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 <emphasis>antes</emphasis>
                       do incremento, 2*6 = 12 a $f */
$g = double(++$e);  /* atribui o dobro do valor de $e <emphasis>depois</emphasis>
                       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. */

No começo do capítulo, nós dissemos que descreveríamos os vários tipos de comandos, e como prometido, expressões podem ser comandos. Porém, nem toda expressão é um comando. Neste caso, um comando tem a forma 'expr' ';', ou seja, uma expressão seguida de ponto-e-vírgula. E '$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.


Capítulo 11. Operadores


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.

A tabela seguinte mostra a precedência dos operadores, da menor precedência para a maior.

Tabela 11-1. Precedência dos operadores

Associação Operador
esquerda ,
esquerda or
esquerda xor
esquerda and
direita print
esquerda = += -= *= /= .= %= &= |= ^= ~= <<= >>=
esquerda ? :
esquerda ||
esquerda &&
esquerda |
esquerda ^
esquerda &
não associativo == != === !==
não associativo < <= > >=
esquerda << >>
esquerda + - .
esquerda * / %
direita ! ~ ++ -- (int) (float) (string) (array) (object) @
direita [
não associativo new


Operadores Aritméticos

Lembra-se da aritmética básica da escola? Estes operadores funcionam exatamente como aqueles.

Tabela 11-2. Operadores Aritméticos

Exemplo Nome Resultado
$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, mesmo que os dois operandos sejam inteiros (ou strings que sejam convetidos para inteiros).


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:

$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 binários, aritméticos e de 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:

$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. O PHP 4 suporta atribuições por referência, usando a sintaxe $var = &$outra_var;, mas isto não é possível no PHP3. '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.


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 caracteres dessa string.

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

Tabela 11-3. 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")

Operadores de Comparação

Operadores de comparação, como os seus nomes implicam, permitem que você compare dois valores.

Tabela 11-4. 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 (somente para 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 (somente para o 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.

Outro operador condicional é o operador "?:" (ou trinário), que opera como no C e em muitas outras linguagens.

(expr1) ? (expr2) : (expr3);

Esta expressão avalia para expr2 se expr1 é avaliada como TRUE, ou expr3 se expr1 é avaliada como FALSE.


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 global $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') ou
    die ("Falha abrindo arquivo: '$php_errormsg'");

// Isto funciona para qualquer expressão, não apenas para funções:
$value = @$cache[$key];
// você não receberá nenhum aviso se a chave $key não existir.

?>

Nota: O operador @ funciona somente em expressões. Uma regra simples para lembrar disso: se você pode pegar o valor de alguma coisa, você pode prefixar isso com o @. Assim, você pode prefixar chamadas de variáveis, funções e include()s, constantes e afins. Você não pode prefixar definições de funções ou classe, estruturas condicionais como o if, foreach e assim por diante.

Veja também: error_reporting().

Nota: O prefixo de controle de erro "@" não desabilita mensagens que são resultado de erros de interpretação (parse errors).

Atenção

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

$output = `ls -al`;
echo "<pre>$output</pre>";

Nota: O operador de execução fica desabilitado quando o safe mode está ativo ou shell_exec() está desabilitado.

Veja também: escapeshellcmd(), exec(), passthru(), popen(), shell_exec() e system().


Operadores de Incremento/Decremento

O PHP suporta operadores de pré e pós-incremento e decremento no estilo C.

Tabela 11-5. 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";
?>


Operadores Lógicos

Tabela 11-6. 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.)


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.

$a = "Olá ";
$b = $a . "mundo!"; // agora $b contém "Olá mundo!"

$a = "Olá ";
$a .= "mundo!";     // agora $a contém "Olá mundo!"


Operadores de Arrays

O único operador de arrays no PHP é o +. Ele acrescenta o array informado à direita no array informado à esquerda, onde chaves duplicadas NÃO são sobrescritos.

$a = array("a" => "maçã", "b" => "banana");
$b = array("a" =>"pêra", "b" => "framboesa", "c" => "morango");

$c = $a + $b;

var_dump($c);
array(3) {
  ["a"]=>
  string(5) "maçã"
  ["b"]=>
  string(6) "banana"
  ["c"]=>
  string(6) "morango"
}


Capítulo 12. Estruturas de Controle

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

A construção if é uma das mais importantes implementações de muitas linguagens, incluindo o PHP. Ela permite a execução condicional de fragmentos de código. O PHP implementa uma estrutura if que é similar àquela do C:

if (expressao)
    instrucoes

Como descrita na seção sobre expressões , expressao é avaliado por seu contexto Booleano. Se expressao for avaliado como TRUE, o PHP executará instrucoes, e se for avaliado como FALSE, ele será ignorado. Maiores informações sobre a avaliação para FALSE podem ser encontradas na seção Convertendo para Booleanos .

Os exemplos a seguir mostrariam que a é maior que b se $a for maior que $b:

if ($a > $b)
    print "a é maior que b";

Freqüentemente você vai querer ter mais que uma instrução seja executado condicionalmente. E é claro, não há necessidade de englobar cada instrução com uma cláusula if. Em vez disso, você pode colocar várias instruções em um agrupamento de comandos. Por exemplo, este código mostraria a é maior que b se $a for maior que $b, e então atribuiria o valor de $a para $b:

if ($a > $b) {
    print "a é maior que b";
    $b = $a;
}

Comandos if podem ser aninhados indefinidamente dentro de outros comandos if, o que faz com que você complete a flexibilidade para a execução condicional de várias partes do seu programa.


else

Freqüentemente você vai querer executar uma instrução se uma certa condição for encontrada, e uma instrução diferente se a condição não for encontrada. Isto é o que o else faz. else estende um comando if para executar uma instrução caso a expressão no comando if seja avaliada como FALSE. Por exemplo, o código a seguir mostraria a é maior que b se $a for maior que $b, e a NÃO é maior que b caso contrário:

if ($a > $b) {
    print "a é maior que b";
} else {
    print "a NÃO é maior que b";
}

O comando else só é executado se a expressão if for avaliada como FALSE, e se havendo qualquer expressão elseif, somente se todas elas forem avaliadas como FALSE também (veja elseif).


elseif

elseif, como seu nome sugere, é uma combinação de if e else. Da mesma forma que o else, ele estende um comando if para executar uma instrução diferente no caso de a expressão if original ser avaliada como FALSE. Porém, ao contrário de else, ele executará aquela expressão alternativa somente se a expressão condicional do elseif for avaliada como TRUE. Por exemplo, o código a seguir mostraria a é maior que b, a é igual a b ou a é menor que b:

if ($a > $b) {
    print "a é maior que b";
} elseif ($a == $b) {
    print "a é igual a b";
} else {
    print "a é menor que b b";
}

Podem haver vários elseifs dentro da mesma instrução if. A primeira expressão elseif (se houver) que for avaliada como TRUE será executada. No PHP, você também pode escrever 'else if' (em duas palavras) e o comportamento será idêntico a um 'elseif' (em uma só palavra). O significado sintático é ligeiramente diferente (se você está familiarizado com C, eles tem o mesmo comportamento), mas no final de contas ambos teriam exatamente o mesmo comportamento.

O comando elseif só é executado se a expressão if precedente e quaisquer expressões elseif anteriores forem avaliadas como FALSE, e a expressão elseif atual for avaliada como TRUE.


Sintaxe alternativa para estruturas de controle

O PHP oferece uma sintaxe alternativa para algumas das suas estruturas de controle: if, while, for, foreach e switch. Em cada caso, a forma básica da sintaxe alternativa é mudar o sinal de abertura para dois-pontos (:) e o sinal de fechamento para endif;, endwhile;, endfor;, endforeach; ou endswitch;, respectivamente.

<?php if ($a == 5): ?>
A é igual a 5
<?php endif; ?>

No exemplo acima, o bloco HTML "A é igual a 5" está aninhado dentro de uma instrução if escrito na sintaxe alternativa. O bloco HTML será mostrado somente se $a é igual a 5.

A sintaxe alternativa se aplica a else e elseif também. A seguir temos uma estrutura if com elseif e else no formato alternativo:

if ($a == 5):
    print "a igual a 5";
    print "...";
elseif ($a == 6):
    print "a igual a 6";
    print "!!!";
else:
    print "a não é nem 5 nem 6";
endif;

Veja também: while, for e if para mais exemplos.


while

Loops while são o tipo mais simples de criar um 'loop' em PHP. Eles se comportam como seus compatíveis em C. O formato básico de um comando while é:

while (expressao) instrucoes

O significado de um comando while é simples. Ele pede que o PHP execute os comandos aninhados repetidamente, enquanto a expressão do while é avaliada como TRUE. O valor da expressão é verificada cada vez que se passa no começo do 'loop', desta forma, mesmo que este valor mude durante a execução do(s) comando(s) aninhado(s), a execução não parará até que o fim da iteração (cada vez que o PHP executa os comandos dentro do 'loop' é uma iteração). Às vezes, se a expressão while é avaliada como FALSE logo no início, o(s) comando(s) aninhado(s) não será(ão) rodado(s) nem uma vez sequer.

Como no comando if, você pode agrupar múltiplos comandos dentro do mesmo laço while englobando um grupo de instruções com chaves, ou usando a sintaxe alternativa:

while (expressao): instrucoes ... endwhile;

Os exemplos a seguir são idênticos, e ambos imprimem números de 1 to 10:

/* exemplo 1 */

$i = 1;
while ($i <= 10) {
    print $i++;  /* o valor impresso será
                    $i depois do acréscimo
                    (post-increment) */
}

/* exemplo 2 */

$i = 1;
while ($i <= 10):
    print $i;
    $i++;
endwhile;


do..while

Loops do..while são bem similares aos loops while, exceto pelo fato de que a condição é verificada no fim de cada iteração em vez de no começo. A diferença principal dos loops while regulares é que a primeira iteração de um loop do..while é garantidamente executada (a condição só é verificada no fim da iteração) enquanto que ele pode não rodar necessariamente em um loop while normal (a condição é verificada no começo de cada iteração, se ela é avaliada como FALSE logo no começo, a execução do loop terminaria imediatamente).

Há apenas uma sintaxe para loops do..while:

$i = 0;
do {
   print $i;
} while ($i>0);

O loop acima rodaria exatamente uma vez, desde que depois da primeira iteração, quando a condição é verificada, ela é avaliada como FALSE ($i não é maior que zero 0) e a execução do loop termina.

Usuários avançados de C podem estar familiarizados com o uso diferenciado do loop do..while, para permitir o fim da execução no meio dos blocos de código, englobando-os com do..while(0), e usando a instrução break . O fragmento de código a seguir demonstra isso:

do {
    if ($i < 5) {
        print "i não é grande o suficiente";
        break;
    }
    $i *= $factor;
    if ($i < $minimum_limit) {
        break;
    }
    print "i está Ok";

     ...process i...

} while(0);

Não se preocupe se você não entendeu isto da forma certa ou de jeito nenhum. Você pode codificar scripts simples ou mesmo poderosos sem usar esse 'recurso'.


for

Loops for são os laços mais complexos em PHP. Eles se comportam como os seus compatíveis em C. A sintaxe de um loop for é:

for (expr1; expr2; expr3) instrucoes

A primeira expressão (expr1) é avaliada (executada) uma vez incondicionalmente no começo do loop.

No começo de cada iteração, expr2 é avaliada. Se ela é avaliada como TRUE, o loop continua e o(s) comando(s) aninhado(s) é(são) executado(s). Se é avaliada como FALSE, a execução do 'loop' termina.

No fim de cada iteração, expr3 é avaliada (executada).

Cada uma das expressões pode ser vazia. expr2 vazia significa que o loop pode rodar indefinidamente (PHP considera-a implicitamente como TRUE, como em C). Isto pode não ser tão inútil quanto você pode pensar, pois freqüentemente você pode querer terminar o 'loop' usando uma instrução break condicional em vez de usar a expressão-verdade do for.

Considere os seguintes exemplos. Todos eles mostram números de 1 a 10:

/* exemplo 1 */

for ($i = 1; $i <= 10; $i++) {
    print $i;
}

/* exemplo 2 */

for ($i = 1;;$i++) {
    if ($i > 10) {
        break;
    }
    print $i;
}

/* exemplo 3 */

$i = 1;
for (;;) {
    if ($i > 10) {
        break;
    }
    print $i;
    $i++;
}

/* exemplo 4 */

for ($i = 1; $i <= 10; print $i, $i++);

Obviamente, o primeiro exemplo parece ser o mais bonito (ou talvez o quarto), mas você pode perceber que a possível utilização de expressões vazias em laços for se torna prático em algumas ocasiões.

O PHP também suporta a "sintaxe de dois-pontos" alternativa para laços for:

for (expr1; expr2; expr3): instrucoes; ...; endfor;

Outras linguagens têm uma instrução foreach para varrer uma matriz ou tabela de hashing. O PHP 3 não tem uma construção deste tipo; O PHP 4 possui (veja foreach). No PHP 3, você pode combinar while com as funções list() e each() para obter o mesmo efeito. Veja a documentação para estas funções para exemplos.


foreach

O PHP4 (mas não o PHP3) inclui um construtor foreach, muito parecido com o PERL e outras linguagens. Isto oferece uma maneira fácil de iterar sobre matrizes. foreach funciona somente com arrays, e lançará um erro se tentar utilizá-lo em uma variável de qualquer tipo diferente ou em variáveis não inicializadas. Há duas sintaxes; a segunda é uma abreviatura, mas útil, da primeira:

foreach(expressao_array as $valor) instrucoes
foreach(expressao_array as $chave => $valor) instrucoes

A primeira forma varre uma dada matriz dada por expressao_array. Em cada 'loop', o valor do elemento corrente é atribuído a $valor e o ponteiro interno da matriz é avançado em uma posição (assim, no próxima iteração você estará olhando para o próximo elemento).

A segunda forma faz a mesma coisa, exceto pelo fato de que a chave do elemento atual será atribuído à variável $chave em cada iteração.

Nota: Quando o foreach inicia sua primeira execução, o ponteiro interno da matriz é zerado automaticamente para o primeiro elemento do array. Isto significa que você não precisa chamar reset() antes de um loop foreach .

Nota: Note também que foreach opera sobre uma cópia do array especificado, não o próprio array, portanto o ponteiro da array não é modificado como na instrução each(), que altera o elemento do array selecionado, mas isso não se reflete o array original.

Nota: foreach tem a habilidade de evitar mensagens de erro com '@'.

Você pode ter notado que os seguintes itens são funcionalmente idênticos:

reset ($arr);
while (list(, $value) = each ($arr)) {
    echo "Valor: $value<br>\n";
}

foreach ($arr as $value) {
    echo "Valor: $value<br>\n";
}

Os seguintes também são funcionalmente idênticos:

reset ($arr);
while (list($key, $value) = each ($arr)) {
    echo "Chave: $key; Valor: $value<br>\n";
}

foreach ($arr as $key => $value) {
    echo "Chave: $key; Valor: $value<br>\n";
}

Mais alguns exemplos para demonstrar os usos:

/* exemplo foreach 1: somente valores */

$a = array (1, 2, 3, 17);

foreach ($a as $v) {
   print "Valor atual de \$a: $v.\n";
}

/* exemplo foreach 2: valores (com as chaves impressas para ilustração) */

$a = array (1, 2, 3, 17);

$i = 0; /* para exemplo somente */

foreach($a as $v) {
    print "\$a[$i] => $v.\n";
    $i++;
}

/* exemplo foreach 3: chaves e valores */

$a = array (
    "um" => 1,
    "dois" => 2,
    "três" => 3,
    "dezessete" => 17
);

foreach($a as $k => $v) {
    print "\$a[$k] => $v.\n";
}

/* exemplo foreach 4: arrays multidimensionais */

$a[0][0] = "a";
$a[0][1] = "b";
$a[1][0] = "y";
$a[1][1] = "z";

foreach($a as $v1) {
    foreach ($v1 as $v2) {
        print "$v2\n";
    }
}

/* exemplo foreach 5: arrays dinâmicos */

foreach(array(1, 2, 3, 4, 5) as $v) {
    print "$v\n";
}


break

break cancela a execução do comando for, foreach while, do..while ou switch atual.

break aceita um argumento numérico opcional que diz a ele quantas estruturas aninhadas englobadas devem ser quebradas.

$arr = array ('um', 'dois', 'três', 'quatro', 'PARE', 'cinco');
while (list (, $val) = each ($arr)) {
    if ($val == 'PARE') {
        break;    /* Você poderia colocar 'break 1;' aqui. */
    }
    echo "$val<br>\n";
}

/* Utilizando o argumento opcional. */

$i = 0;
while (++$i) {
    switch ($i) {
    case 5:
        echo "No 5<br>\n";
        break 1;  /* Sai somente do switch. */
    case 10:
        echo "No 10; saindo<br>\n";
        break 2;  /* Sai do switch e while. */
    default:
        break;
    }
}


continue

continue é usado dentro de estruturas de loops para saltar o resto da iteração do loop atual e continuar a execução no início da próxima iteração.

continue aceita um argumento numérico opcional que diz a ele de quantos níveis de loops aninhados ele deve saltar até o fim.

while (list ($key, $value) = each ($arr)) {
    if (!($key % 2)) { // pula itens pares
        continue;
    }
    do_something_odd ($value);
}

$i = 0;
while ($i++ < 5) {
    echo "Fora<br>\n";
    while (1) {
        echo "&nbsp;&nbsp;Meio<br>\n";
        while (1) {
            echo "&nbsp;&nbsp;Dentro<br>\n";
            continue 3;
        }
        echo "Isto nunca será exibido.<br>\n";
    }
    echo "Nem isso.<br>\n";
}


switch

A instrução switch é similar a uma série de instruções IFs seguidas. Em muitas ocasiões, você poderá ter que comparar a mesma variável (ou expressão) com muitos valores diferentes, executando códigos diferentes dependendo com qual valor ele se encaixar. É exatamente para isso que a instrução switch faz.

Os exemplos seguintes mostram duas maneiras diferentes de escrever a mesma coisa, uma utilizando uma série de iss e a outra utlizando a instrução switch:

if ($i == 0) {
    print "i igual a 0";
}
if ($i == 1) {
    print "i igual a 1";
}
if ($i == 2) {
    print "i igual a 2";
}

switch ($i) {
    case 0:
        print "i igual a 0";
        break;
    case 1:
        print "i igual a 1";
        break;
    case 2:
        print "i igual a 2";
        break;
}

É importante entender como a instrução switch funciona para evitar enganos. A instrução switch executa linha a linha (atualmente, instrução a instrução). No início, nenhum código é executado. Somente quando uma instrução case é encontrada com um valor que combina com a expressão do switch faz com que o PHP execute as instruções a partir daí. O PHP continua executando as instruções até o fim do bloco switch ou na primeira vez que encontrar uma instrução break. Se você não escrever uma instrução break no fim das instruções case, o PHP continuará executando os cases seguintes. Exemplo:

switch ($i) {
    case 0:
        print "i igual a 0";
    case 1:
        print "i igual a 1";
    case 2:
        print "i igual a 2";
}

Aqui, se $i é igual a zero, o PHP executará todas as instruções print!. Se $i é igual a 1, o PHP executará os últimas duas instruções print, e somente se $i for igual a 2, você terá o comportamento 'esperado' apenas onde 'i igual a 2' será mostrado. Então é importante não se esquecer das instruções break (e as vezes não colocá-las para obter esse resultado em certas circunstâncias).

Em uma instrução switch, a condição somente será avaliada e resultado comparado para cada instrução case. Em uma instrução elseif, a condição é avaliada novamente. Se sua condição é mais complicada que um simples comparação e/ou e dentro de um loop, um switch é mais rápido.

Um case pode não ter nenhuma instrução dentro, o que simplesmente passa o controle para o próximo case.

switch ($i) {
    case 0:
    case 1:
    case 2:
        print "i é menor que 3 mas não negativo";
        break;
    case 3:
        print "i é 3";
}

Um case especial é o default. Esse case é executado quando nenhum outro case combina. Ele precisa ser a última instrução case. Por exemplo:

switch ($i) {
    case 0:
        print "i igual a 0";
        break;
    case 1:
        print "i igual a 1";
        break;
    case 2:
        print "i igual a 2";
        break;
    default:
        print "i não é igual a 0, 1 ou 2";
}

A expressão avaliada pelo case precisa ser um tipo simples, ou seja, inteiros, números de ponto flutuante e strings. Arrays ou objetos não podem ser utilizados a não ser que eles impliquem num tipo simples.

A sintaxe alternativa para estruturas de controle é suportada para os switches. Para maiores informações, veja Sintaxe alternativa para estruturas de controle.

switch ($i):
    case 0:
        print "i igual a 0";
        break;
    case 1:
        print "i igual a 1";
        break;
    case 2:
        print "i igual a 2";
        break;
    default:
        print "i não é igual a 0, 1 ou 2";
endswitch;


declare

O construtor declare é utilizado para configurar diretivas de execução para blocos de código. A sintaxe do declare é similar a sintaxe de outros construtores de controle.

declare (diretiva) instrucao

A seção diretiva permite o comportamento do bloco declare a ser configurado. Atualmente somente uma diretiva é reconhecida: a diretiva ticks. (veja abaixo para maiores informações em diretiva ticks)

A parte instrucao do bloco declare será executada. Como ela é executada e que efeitos colaterais que podem ocorrem durante a execução dependem da configuração diretiva.


Ticks

Um tick é um evento que ocorre para cada N níveis de instruções executados pelo interpretador com o bloco declare. O valor para N é especificado utilizando ticks=N nos blocos declare das seções diretiva.

O(s) evento(s) que ocorre(m) em cada tick são especificados utilizando register_tick_function(). Veja o exemplo abaixo para maiores detalhes. Note que mais de um evento pode ocorrer em cada tick.

Exemplo 12-1. Histórico de um trecho de código PHP

<?php
// Uma função que grava o tempo entre as chamadas
function profile ($dump = FALSE)
{
    static $profile;

    // Retorna os tempos preservados no histórico, então apaga
    if ($dump) {
        $temp = $profile;
        unset ($profile);
        return ($temp);
    }

    $profile[] = microtime ();
}

// Ativa o manipulador do tick
register_tick_function("profile");

// Inicializa a função antes de declarar o bloco
profile ();

// Roda um trecho de código, disparando um tick a cada duas instruções
declare (ticks=2) {
    for ($x = 1; $x < 50; ++$x) {
        echo similar_text (md5($x), md5($x*$x)), "<br />;";
    }
}

// Mostra os dados guardados no histórico
print_r (profile (TRUE));
?>
No exemplo acima, o bloco 'declare' grava os tempos a cada segundo nível dentro das instruções no bloco enquanto executam. Esta informação pode ser utilizada para encontrar áreas lentas em segmentos particulares de código. Este processo pode ser realizado de outras formas, mas a utilização de ticks é mais conveniente e fácil de implementar.

Ticks são idealizados para debug, implementação de multitask simples, processos de I/O em background e afins.

Veja também: register_tick_function() e unregister_tick_function().


return

Se chamada em uma função, a instrução return() termina imediatamente a execução da função atual e retorna seu argumento como o valor da função. return() também termina a execução de uma instrução eval() ou de um script.

Se chamada no escopo global, a execução do script atual será terminada. Se o arquivo do script atual foi incluído com include() ou require(), então a execução é devolvida para o arquivo chamador. Especificamente para arquivos de script incluídos com include(), o valor fornecido para return() será devolvido como o valor da chamada include(). Se return() for chamado do arquivo de script principal, então o programa pára. Se o arquivo de script atual é o configurado em auto_prepend_file ou auto_append_file do arquivo de configuração, então a execução desses scripts é finalizada.

Para maiores informações, veja Retornando Valores.

Nota: Note que return() é um construtor de linguagem e não uma função, e parênteses em volta do seus argumentos não são necessários -- de fato, é mais comum não colocá-los que usá-los, sem, entretanto, haver diferença de um jeito ou de outro.


require()

A instrução require() inclui a avalia um arquivo específico.

Informações detalhadas de como essa inclusão funciona está descrita na documentação do include().

require() e include() são idênticos em todas as formas exceto pela manipulação de erros. include() produz um Warning enquanto require() produzirá um Fatal Error. Em outras palavras, não hesite em utilizar require() se na falta de um arquivo quiser parar o processamento da página. include() não se comporta da mesma maneira, e o script poderá continuar nessa situação. Em todo caso, vale a pena confirmar a configuração da diretiva include_path.

Exemplo 12-2. Exemplos de require()s simples

<?php

require 'prepend.php';

require $somefile;

require ('somefile.txt');

?>

Vaja a documentação de include() para mais exemplos.

Nota: Até o PHP 4.0.2, havia o seguinte comportamento: require() mesmo que a linha onde ele está nunca seja executada. É por isso que instruções condicionais não afetam require(). Entretanto, se a linha onde ocorre o require() não for executada, nada do código incluído do arquivo também será. Similarmente, estruturas de loop não afetam o funcionamento do require(). Mas o código incluído pela função será submetida ao loop. A instrução require() apenas ocorre uma vez.

Atenção

A versões Windows do PHP anteriores ao PHP 4.3 não suportam acesso a arquivos remotos através desta função, mesmo se allow_url_fopen estiver ativado.

Veja também: include(), require_once(), include_once(), eval(), file(), readfile(), virtual() e include_path.


include()

A instrução include() inclui e avalia o arquivo informado.

A documentação a seguir se aplica também a require(). Esses dois construtores são idênticos a exceção de como eles manipulam erros. include() produz um Warning enquanto require() produzirá um Fatal Error. Em outras palavras, utilize require() se você deseja que um arquivo faltando interrompa o processamento da página. include() não se comporta da mesma maneira, permitindo que o script continue nessas situações. Em todo caso, vale a pena confirmar a configuração da diretiva include_path.

Quando um arquivo é incluído, seu código entra no escopo de variável da linha onde a inclusão ocorre. Qualquer variável disponível da linha onde a chamada da inclusão ocorre estará disponível para o arquivo incluído, daquele ponto em diante.

Exemplo 12-3. Exemplos de include()s simples

variaveis.php
<?php

$cor = 'verde';
$fruta = 'maçã';

?>

teste.php
<?php

echo "Uma $fruta $cor"; // Uma

include 'vars.php';

echo "Uma $fruta $cor"; // Uma maçã verde

?>

Se o include ocorre dentro de uma função do arquivo principal, então todo o código incluído será executado como se ele tivesse sido definido dentro daquela função. Da mesma forma, ele seguirá o escopo de variáveis da função.

Exemplo 12-4. Incluindo dentro de funções

<?php

function foo()
{
global $cor;

    include 'variaveis.php';

    echo "Uma $fruta $cor";
}

/* variaveis.php está no escopo de foo(),   *
.* então $fruta NÃO está disponível fora de *
.* seu escopo. $cor estará porque ela foi   *
.* declarada como global                    */

foo();                    // Uma maçã verde
echo "A $fruta $cor";   // Uma maçã

?>

Quando um arquivo é incluído, o interpretador sai do modo PHP e entra no modo HTML (no começo do arquivo incluído), e alterna novamente no seu fim. Por isso, qualquer código dentro do arquivo incluído que precisa ser executado como código PHP tem de ser delimitado por tags válidas de abertura e fechamento.

Se "URL fopen wrappers" estão ativas no PHP (normalmente na configuração default), você pode especificar um arquivo utilizando uma URL (via HTTP ou qualquer outro wrapper suportado --- veja Apêndice I para uma lista dos protocolos) em vez de uma caminho local. Se o servidor apontado interpreta o arquivo informado como código PHP, variáveis podem ser passadas ao arquivo incluído na URL de requisição como num HTTP GET. Isto não é necessariamente a mesma coisa que incluir o arquivo e compartilhar o escopo de variável do arquivo principal: o script será executado no servidor remoto e apenas seu resultado será incluído no script local.

Atenção

A versões Windows do PHP anteriores ao PHP 4.3 não suportam acesso a arquivos remotos através desta função, mesmo se allow_url_fopen estiver ativado.

Exemplo 12-5. include() através de HTTP

<?php

/* Este exemplo assume que www.exemplo.com está configurado para interpretar *
 * arquivos .php mas não .txt. Além, 'Funciona' aqui significa que as        *
 * variáveis $foo e $bar estão disponíveis no arquivo incluído               */

// Não funciona: arquivos txt não são manipulados em www.example.com como PHP
include 'http://www.exemplo.com/arquivo.txt?foo=1&bar=2';

// Não funciona: procura por um arquivo chamado 'arquivo.php?foo=1&bar=2' no
// sistemas de arquivo local.
include 'arquivo.php?foo=1&bar=2';

// Funciona.
include 'http://www.exemplo.com/arquivo.php?foo=1&bar=2';

$foo = 1;
$bar = 2;
include 'arquivo.txt';  // Funciona.
include 'arquivo.php';  // Funciona.

?>
Vaja também: Arquivos Remotos, fopen() e file() para informações relacionadas.

Por serem include() e require() dois construtores de linguagem especiais, você precisa delimitá-los como um bloco de instruções quando utilizados dentro de instruções condicionais.

Exemplo 12-6. include() e instruções condicionais

<?php

// Isto está errado e não funcionará como desejado
if ($condition)
    include $arquivo;
else
    include $outro;


// E este está correto
if ($condition) {
    include $arquivo;
} else {
    include $outro;
}

?>

Também é possível executar uma instrução return() dentro de um arquivo incluído de maneira a finalizar o processamento daquele arquivo e retornar para o script que o chamou. Também é possível retornar valores de arquivos incluídos. Você pode pegar o valor de retorno de um include como faria com uma função normal.

Nota: No PHP 3, o return não pode aparecer dento de um bloco a não ser que ele seja um bloco de função, e nesse caso return() se aplica apenas para a função e não para todo o arquivo.

Exemplo 12-7. Instruções include() e return()

return.php
<?php

$var = 'PHP';

return $var;

?>

noreturn.php
<?php

$var = 'PHP';

?>

testreturns.php
<?php

$foo = include 'return.php';

echo $foo; // imprime 'PHP'

$bar = include 'noreturn.php';

echo $bar; // imprime 1

?>

$bar assimila o valor 1 porque a inclusão foi realizada com sucesso. Verifique a diferença entre os exemplo. O primeiro utiliza return() dentro do arquivo incluído enquanto que o outro não. Há outras maneiras de "incluir" arquivos dentro de variáveis, com fopen(), file() ou utilizando include() através das Funções de Controle de Output.

Veja também: require(), require_once(), include_once(), readfile(), virtual() e include_path.


require_once()

A instrução require_once() incluí e avalia o arquivo especificado durante a execução do script. Seu comportamento é similar ao da instrução require(), a não ser que o arquivo informado já tenha sido incluído, não refazendo a operação novamente. Veja a documentação de require() para maiores informações sobre como essa instrução funciona.

require_once() pode ser utilizado nos casos em que o mesmo arquivo pode acabar sendo incluído mais de uma vez durante a execução de um script em particular, quando na verdade ele só pode ser incluído apenas uma, para evitar problemas com redefinições de funções, alterações nos valores de variáveis, etc.

Para exemplos de utilização de require_once() e include_once(), veja o código do PEAR incluído nas últimas distribuições do código fonte do PHP.

Nota: require_once() foi acrescentado a partir PHP 4.0.1pl2

Nota: Esteja avisado que o comportamento de require_once() e include_once() pode não ser o que você espera em um sistema operacional insensitivo ao caso (como o Windows).

Exemplo 12-8. require_once() é sensitivo ao caso

require_once("a.php"); // isto irá incluir a.php
require_once("A.php"); // isto irá incluir a.php de novo no Windows!

Atenção

A versões Windows do PHP anteriores ao PHP 4.3 não suportam acesso a arquivos remotos através desta função, mesmo se allow_url_fopen estiver ativado.

Veja também: require(), include(), include_once(), get_required_files(), get_included_files(), readfile() e virtual().


include_once()

A instrução include_once() inclui e avalia o arquivo especificado durante a execução de um script. Seu comportamento é similar a instrução include(), a não ser que o arquivo informado já tenha sido incluído, não refazendo a operação novamente. Como o nome sugere, ele será incluído apenas uma vez.

include_once() pode ser utilizado nos casos em que o mesmo arquivo pode acabar sendo incluído mais de uma vez durante a execução de um script em particular, quando na verdade ele só pode ser incluído apenas uma para evitar problemas com redefinições de funções, alterações nos valores de variáveis, etc.

Para maiores informações utilizando require_once() e include_once(), veja o código do PEAR incluído nas últimas distribuições do código fonte do PHP.

Nota: include_once() foi acrescentado a partir PHP 4.0.1pl2

Nota: Esteja avisado que o comportamento de include_once() e require_once() pode não ser o que você espera em um sistema operacional insensitivo ao caso (como o Windows).

Exemplo 12-9. include_once() é sensitivo ao caso

include_once("a.php"); // isto irá incluir a.php
include_once("A.php"); // isto irá incluir a.php de novo no Windows!

Atenção

A versões Windows do PHP anteriores ao PHP 4.3 não suportam acesso a arquivos remotos através desta função, mesmo se allow_url_fopen estiver ativado.

Veja também: include(), require(), require_once(), get_required_files(), get_included_files(), readfile() e virtual().


Capítulo 13. Funções

Funções definidas pelo usuário

Uma função pode ser definida usando-se a sintaxe como a seguinte:

function foo ($argumento_1, $argumento_2, ..., $argumento_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.

No PHP3, as funções precisam ser definidas antes de serem referenciadas. Esse requisito não existe no PHP4.

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.

O PHP3 não suporta número variável de argumentos para funções, apesar de os argumentos padrões serem suportados (veja Valores padrão de argumentos para mais informações). O PHP4 suporta ambos: veja Número de argumentos variável e as referências das funções func_num_args(), func_get_arg() e func_get_args() para mais informações.


Argumentos de funções

Informações podem ser passadas para funções através da lista de argumentos, que é uma lista de variáveis e/ou constantes delimitados por vírgulas.

O PHP suporta a passagem de argumentos por valor (o padrão), passagem por referência e valores padrão de argumento . Listas de argumentos de comprimento variável são suportadas apenas no PHP4 e posterior; veja Número de argumentos variável e as referências das funções func_num_args(), func_get_arg() e func_get_args() para mais informações. Um efeito similar pode ser atingido no PHP 3 pela passagem de um array de argumentos para uma função:

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). Se você deseja permitir que uma função modifique seus argumentos, você precisa passá-los por referência.

Se você quer que um argumento para uma função sempre seja passado por referência, você pode preceder o nome do argumento com um "e comercial" (&) na definição da função:

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:

function cafeteira ($tipo = "cappuccino")
{
    return "Fazendo uma xícara de café $type.\n";
}
echo cafeteira ();
echo cafeteira ("expresso");

A saída do código acima será:
Fazendo uma xícara de café cappucino.
Fazendo uma xícara de café expresso.

O valor padrão precisa ser uma expressão constante, não (por exemplo) uma variável ou um membro de classe.

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:

function iogurtera ($tipo = "azeda", $sabor)
{
    return "Fazendo uma taça de $tipo $sabor.\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:

function iogurtera ($sabor, $tipo = "azeda")
{
    return "Fazendo uma taça de $tipo $sabor.\n";
}

echo iogurtera ("framboesa");   // funciona

A saída deste exemplo é:
Fazendo uma taça de framboesa azeda.


Número variável de argumentos

O PHP4 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.

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 devolvidos retornando por uma lista.

function numeros_pequenos()
{
    return array (0, 1, 2);
}
list ($zero, $um, $dois) = numeros_pequenos();

Para retornar uma referência de uma função, você precisa utilizar o operador de referência & tanto na declaração da função como quando assimilando o valor retornado para a variável.

function &retorna_referencia()
{
    return $alguma_referencia;
}

$nova_referencia =& retorna_referencia();

Para mais detalhes sobre referências, leia a seção Referências.


old_function

O comando old_function permite que você declare uma função usando uma sintaxe idêntica ao PHP/FI2 (exceto pelo fato de que você precisa substituir 'function' com 'old_function').

Esta é uma implementação obsoleta, e deve ser usada somente pelo conversor PHP/FI2->PHP3.

Atenção

Funções declaradas como old_function não podem ser chamadas a partir de código interno do PHP. Entre outras coisas, isso significa que você não pode usá-las em funções como usort(), array_walk() e register_shutdown_function(). Você pode contornar essa limitação escrevendo um invólucro de função (no formato PHP3 normal) para chamar o old_function.


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(), unset(), isset(), empty(), include() ou print().

Exemplo 13-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";
}

$func = 'foo';
$func();
$func = 'bar';
$func('teste');
?>

Veja também: Variáveis variáveis e function_exists().


Capítulo 14. Classes e Objetos

class

Uma classe é uma coleção de variáveis e funções trabalhando com essas variáveis. Uma classe é definida usando-se a seguinte sintaxe:

<?php
class CarrinhoDeCompras
{
    var $items;  // Itens do carrinho de compras

    // Acrescenta a quantidade $num do artigo $artnr no carrinho

    function add_item ($artnr, $num)
    {
        $this->items[$artnr] += $num;
    }

    // Retira a quantidade $num de artigos $artnr do carrinho

    function remove_item ($artnr, $num)
    {
        if ($this->items[$artnr] > $num) {
            $this->items[$artnr] -= $num;
            return true;
        } else {
            return false;
        }
    }
}
?>

Isto define uma classe chamada CarrinhoDeCompras que consiste de uma matriz associativa de artigos no carrinho e duas funções para acrescentar e remover itens deste carrinho.

Cuidado

Os cuidados a seguir devem ser tomados a partir do PHP 4:

O nome stdClass é utilizado internamente pela Zend e é uma palavra reservada. Você não pode ter uma classe chamada stdClass no PHP.

O nome de função __sleep e __wakeup são especialmente mágicos para as classes PHP. Você não pode ter esses nomes em nenhuma de suas classes a não ser que você deseje aplicar essa funcionalidade mágica com elas. Veja abaixo para mais detalhes.

O PHP reserva todos os nomes de funções começando com __ como mágicas. É recomendável que você não utilize nome de funções começando com __ no PHP a não ser que você precise dessas funcionalidades mágicas.

Nota: No PHP 4, somente inicializações com constantes são permitidas para variáveis com var. Para inicializar variáveis com valores não constantes, você precisará de uma função de inicialização chamada automaticamente quando o objeto for construído a partir da classe. Por isso, essa função é conhecida como construtor (veja baixo).

<?php
/* Nenhuma delas funcionarão com o PHP 4 */
class CarrinhoDeCompras
{
    var $data_de_hoje = date("Y-m-d");
    var $nome = $primeiro_nome;
    var $proprietario = 'Fred ' . 'Jones';
    var $items = array("VCR", "TV");
}

/* Esta é a forma como deve ser feito */
class CarrinhoDeCompras
{
    var $data_de_hoje;
    var $nome;
    var $proprietario;
    var $items;

    function CarrinhoDeCompras()
    {
        $this->data_de_hoje = date("Y-m-d");
        $this->nome = $GLOBALS['primeiro_nome'];
        /* etc. . . */
    }
}
?>

Classes são tipos, ou seja, são apenas um modelo das variáveis normais. Você pode criar uma variável (ou instância) do tipo desejado com o operador new.

<?php
$carrinho = new CarrinhoDeCompras;
$carrinho->add_item("10", 1);

$outro_carrinho = new CarrinhoDeCompras;
$outro_carrinho->add_item("0815", 3);

Isto cria os objetos $carrinho e $outro_carrinho, ambos a partir da classe CarrinhoDeCompras. A função add_item() do objeto $carrinho foi chamada e acrescentou 1 item do artigo número 10 a ele. 3 itens do artigo número 0815 foi acrescentado no $outro_carrinho.

Ambos, $carrinho e $outro_carrinho, tem as funções add_item(), remove_item() e a variável itens. Elas são funções e variáveis distintas entre si. Você pode pensar no objetos como os diretórios de um sistema de arquivos. Num disco você pode ter dois arquivos diferentes README.TXT, partindo de que eles estão em diretórios diferentes. Da mesma forma que você teria de especificar o caminho completo para acessar cada arquivo a partir do diretório principal, você também tem de especificar o nome completo do objeto e função que você quer chamar. Em termos do PHP, o diretório principal pode ser o escopo global de nomes, e o separador de diretórios ->. Portanto, os nomes $carrinho->items e $outro_carrinho->items são duas variáveis diferentes. Note que a variável é chamada $carrinho->items e não $carrinho->$items, mesmo porque, um nome de variável em PHP tem apenas um único sinal de cifrão.

// correcto, apenas um $
$carrinho->items = array("10" => 1);

// inválido, porque $carrinho->$items se transforma em $carrinho->""
$carrinho->$items = array("10" => 1);

// correto, mas pode ou não ser o que você quer:
// $carrinho->$myvar se torna $carrinho->items
$myvar = 'items';
$carrinho->$myvar = array("10" => 1);

Quando definindo uma classe, você não pode saber com que nome os objetos serão acessados em seus programas: enquanto escrevia a classe CarrinhoDeCompras, é impossível saber se o objeto criado a partir dela será chamado $carrinho ou $outro_carrinho (ou ainda ambos). Assim, você não pode escrever $carrinho>items dentro da própria classe CarrinhoDeCompras. Entretanto, para poder acessar suas próprias funções e variáveis de dentro da classe, pode-se utilizar a pseudo-variável $this, que pode ser lida como 'eu mesmo' ou 'objeto atual'. Dessa forma, '$this->items[$artnr] += $num' pode ser lido como 'acrescente $num para o contador $artnr do meu array items' ou 'acrescente $num para o contador $artnr do array do objeto atual'.

Nota: Há funções muito boas para manipulação de classes e objetos. Dê uma olhada em Funções de Classes e Objetos


extends

Permite classes com variáveis e funções similares a uma outra classe. De fato, é uma boa prática definir classes genéricas que podem ser utilizadas em todos os seus projetos, e adaptar essas classes com as necessidades específicas de cada projeto. Para facilitar isso, classes podem ser extensões de outras classes. A classe estendida ou derivada tem todas as variáveis e funções da classe base (isto é chamado herança, afora o fato que ninguém morreu) e mais aquelas que venha a acrescentar na versão estendida. Não é possível subtrair uma classe, ou seja, indefinir quaisquer funções ou variáveis existentes. Uma classe estendida é sempre dependente de uma única classe base, e portanto, herança múltipla não é suportada. Classes são estendidas utilizando a instrução 'extends'.

class CarrinhoDeComprasNomeado extends CarrinhoDeCompras
{
    var $proprietario;

    function set_proprietario ($name)
    {
        $this->proprietario = $name;
    }
}

Isto define uma classe chamada CarrinhoDeComprasNomeado que tem todas as variáveis e funções de CarrinhoDeCompras mais a variável $proprietario e uma função set_proprietario(). Você pode criar um carrinho nomeado da maneira usual e configurar e obter o proprietário do carrinho. Você ainda pode continuar utilizando carrinhos normais e carrinhos nomeados:

$ncart = new CarrinhoDeComprasNomeado;
$ncart->set_proprietario("kris");
print $ncart->proprietario;
$ncart->add_item("10", 1);  // (funcionalidade herdade do CarrinhoDeCompras)

Isto é chamado relacionamento "pai-filho". Você cria uma classe pai e utiliza extends para criar uma nova classe baseada na classe pai: sua classe filha. Você ainda pode criar uma nova classe estendida a partir dessa classe filha e assim por diante.

Nota: As classes precisam ser definidas antes de serem utilizadas! Se você estender a classe CarrinhoDeComprasNomeado da classe CarrinhoDeCompras, você precisa antes criar a classe chamada CarrinhoDeCompras. Se você quiser criar uma outra classe chamada CarrinhoDeComprasNomeadoAmarelo baseada na classe CarrinhoDeComprasNomeado você tem que definir CarrinhoDeComprasNomeado primeiro. Trocando em miúdos: a ordem em que as classes são definidas é importante.


Construtores

Cuidado

Os construtores se comportam diferentemente entre o PHP 3 e o PHP 4. A semântica do PHP 4 é atualmente preferencial.

Construtores são funções numa classe que são automaticamente chamados quando você cria uma nova instância da classe com new. No PHP 3, uma função se torna um construtor quando ele tem o mesmo nome da classe. No PHP 4, uma função se torna um construtor quando ele tem o mesmo nome da classe onde ela foi definida (a diferença é sutil, mas crucial --- veja abaixo).

// Funciona no PHP 3 e 4
class CarrinhoDeComprasAutomatico extends CarrinhoDeCompras
{
    function CarrinhoDeComprasAutomatico()
    {
        $this->add_item ("10", 1);
    }
}

Isto define uma classe chamada CarrinhoDeComprasAutomatico que é um CarrinhoDeCompras mais um construtor que inicializa o carrinho com um item do artigo numero "10" cada vez que um novo CarrinhoDeComprasAutomatico for criado com "new". Construtores pode ter argumentos e esses argumentos podem ser opcionais, o que os torna muito mais práticos. Para permitir a criação de classes sem parâmetros, todos os parâmetros dos construtores pode ser feitos opcionais simplesmente por terem valores default.

// Funciona no PHP 3 e 4
class CarrinhoDeComprasComConstrutor extends CarrinhoDeCompras
{
    function CarrinhoDeComprasComConstrutor($item = "10", $num = 1)
    {
        $this->add_item ($item, $num);
    }
}

// Fazendo compras do mesmo modo antigo

$carrinho_default = new CarrinhoDeComprasComConstrutor;

// Fazendo compres de verdade

$carrinhho_diferente = new CarrinhoDeComprasComConstrutor("20", 17);

Você pode usar o operador @ para esconder erros gerados no construtor do objeto, por exemplo: @new.

Cuidado

No PHP 3, classes derivadas e construtores tem uma série de limitações. Os exemplo seguintes precisam ser lidos cuidadosamente para que você entenda essas limitações.

class A
{
    function A()
    {
      echo "Eu sou o construtor de A.<br>\n";
    }
}

class B extends A
{
    function C()
    {
        echo "Eu sou uma função normal.<br>\n";
    }
}

// nenhum construtor é chamado no PHP 3
$b = new B;

No PHP 3, nenhum construtor é chamado no exemplo acima. A regra no PHP 3 é: 'Um construtor é uma função com o mesmo nome da classe'. O nome da classe é B, e não há nenhuma função chamada B() na classe B. Nada ocorre.

Isto foi corrigido no PHP 4 pela instrução de outra regra: Se uma classe não tem construtor, o construtor da classe base é chamado, se existir. O exemplo acima teriam impresso 'Eu sou o construtor de A<br>'. no PHP 4.

class A
{
    function A()
    {
        echo "Eu sou o construtor de A.<br>\n";
    }

    function B()
    {
        echo "Eu sou uma função normal chamada B na classe A.<br>\n";
        echo "Eu não sou o construtor de A.<br>\n";
    }
}

class B extends A
{
    function C()
    {
        echo "Eu sou uma função normal.<br>\n";
    }
}

// Isto irá chamar B() como um construtor.
$b = new B;

No PHP 3, a função B() na classe A se tornará silenciosamente um construtor na classe B, mesmo que isso nunca tenha sido planejado. A regra no PHP 3 é: 'Um construtor é uma função com o mesmo nome da classe'. PHP 3 não se preocupa se a função foi definida na classe B, ou se ela foi herdada.

Isto foi corrigido no PHP 4 pela modificação da regra para: 'Um construtor é uma função com o mesmo nome da classe onde ela é definida.'. Assim, no PHP 4, como a classe B não tem nenhuma função construtora definida nela mesma então o construtor da classe base será chamado, imprimindo 'Eu sou o construtor de A.<br>'.

Cuidado

Nem o PHP 3 ou o 4 chamam automaticamente os construtores da classe base a partir do construtor da classe derivada. É de sua responsabilidade propagar a chamada dos construtores herança acima, onde apropriado.

Nota: Não existem destrutores no PHP 3 ou 4. Mas você pode usar register_shutdown_function() para simular a maioria dos efeitos de destrutores.

Destrutores são funções que são chamadas automaticamente quando um objeto é destruído, ou pela utilização de unset() ou pela simples saída do escopo. Não existem destrutores no PHP.


::

Cuidado

O seguinte é valido para o PHP 4 somente.

As vezes pode ser útil se referir a funções e variáveis na classe base ou referenciar funções em classes que não possuem qualquer instância. O operador :: pode ser utilizado nessas ocasiões.

class A
{
    function exemplo()
    {
        echo "Eu sou a função original A::exemplo().<br>\n";
    }
}

class B extends A
{
    function exemplo()
    {
        echo "Eu sou a função redefinida B::exemplo().<br>\n";
        A::exemplo();
    }
}

// Nao ha nenhum objeto da classe A.
// Isto ira imprimir
//   Eu sou a função original A::exemplo().<br>
A::exemplo();

// cria um objeto a partir da classe B
$b = new B;

// Isto ira imprimir
//   Eu sou a função redefinida B::exemplo().<br>
//   Eu sou a função original A::exemplo().<br>
$b->exemplo();

O exemplo acima chama a função exemplo() da classe A, mas não há nenhum objeto da classe A, então não podemos escrever $a->exemplo() ou qualquer coisa similar, Em vez disso, nós chamamos exemplo() como uma 'função de classe', ou seja, como uma função da classe propriamente dita, não qualquer objeto dessa classe.

Existem funções de classe, mas não variáveis de classe. De fato, não há nenhum objeto durante toda a execução. Assim, uma função de classe não pode usar qualquer variável de objeto (mas pode usar variáveis locais e globais), e nunca podendo utilizar-se de $this.

Ainda no exemplo acima, a classe B redefine a função exemplo(). A definição da função original na classe A é ocultada e nunca disponível, a não ser que você se referencie especificamente a implementação de exemplo() da classe A utilizando-se do operador ::. Escrevemos A::exemplo() para isso (de fato, você também pode escrever parent::exemplo(), como mostrado na próxima seção).

Nesse contexto, existe um objeto e ele pode ter variáveis de objeto. Assim, quando utilizado de DENTRO de uma função de objeto, você pode usar $this e variáveis de objeto.


parent

Você pode se encontrar escrevendo código que precisa referenciar a variáveis e funções na classe base. Isto é particularmente verdade se você derivou uma classe como um refinamento ou especialização de código de sua classe base.

Em vez de utilizar o nome literal da classe base em seu código, você pode usar o nome especial parent, que se refere ao nome da sua classe base como informado na declaração extends. Fazendo isso, evita assim a utilização do nome da sua classe base em mais de um lugar. Se sua árvore de herança mudar durante a implementação, a modificação é mais facilmente realizada pela simples alteração da declaração extends de suas classes.

class A
{
    function exemplo()
    {
        echo "Eu sou A:exemplo() e provenho funcionalidades básicas.<br>\n";
    }
}

class B extends A
{
    function exemplo()
    {
        echo "Eu sou B::exemplo() e provenho funcionalidades adicionais.<br>\n";
        parent::exemplo();
    }
}

$b = new B;

// Isto ira chamar B::exemplo(), que por sua vez chama A::exemplo().
$b->exemplo();


Serializando objetos - objetos em sessões

Nota: No PHP 3, objetos perdem suas associações entre classes através do processo de serialização e desserialização. A variável resultante é do tipo objeto, mas sem classe nem métodos, algo bem sem utilidade (de fato, ele se torna apenas um array com uma sintaxe engraçada).

Cuidado

As informações seguintes se aplicam somente ao PHP 4.

serialize() retorna uma string contendo uma representação linear de qualquer valor que pode ser armazenado no PHP. unserialize() pode ser utilizado para recriar os valores da variável original. Usando serialize para salvar um objeto irá preservar todas as variáveis de um objeto. As funções de um objeto não serão salvas, apenas o nome da classe.

Para ser possível fazer o unserialize() de um objeto, a classe do objeto precisa estar definida. Ou seja, se você tem um objeto $a da classe A em page1.php e a serializa, você consegue uma string que se refere a classe A e contém todos os valores de variáveis contidos em $a. Se você precisa desserializa-la em page2.php, recriando $a da classe A, a definição da classe A precisa estar presente na page2.php. Isto pode por ser feito, por exemplo, armazenando a definição da classe A em um arquivo separado, incluindo este arquivo e ambos os arquivos page1.php e page2.php.

classe_a.inc.php:
  class A
  {
      var $um = 1;

      function mostre_um()
      {
          echo $this->um;
      }
  }

page1.php:
  include("classe_a.inc.php");

  $a = new A;
  $s = serialize($a);
  // armazena $s em algum lugar que page2,php possa encontra-la
  $fp = fopen("armazenamento", "w");
  fputs($fp, $s);
  fclose($fp);

page2.php:
  // Isto e preciso para que unserialize funcione normalmente
  include("classe_a.inc.php");

  $s = implode("", @file("armazenamento"));
  $a = unserialize($s);

  // Agora podemos usar a funcao mostre_um() do objeto $a
  $a->mostre_um();

Se você está utilizando sessões e usar session_register() para registrar objetos, esses objetos serão serializados automaticamente no final de cada script PHP, e automaticamente desserializados em cada uma das páginas seguintes. Isto significa que esse objetos podem estar em qualquer uma de suas páginas desde que elas sejam parte de sua sessão.

É extremamente recomendável que você inclua as definições de classe de todos os objetos registrados de todas as suas páginas, mesmo que você não use essas classes em todas as suas páginas. Se você não o fizer e um objeto for desserializado sem sua definição de classe presente, ele perde usa associação com a classe e se torna um objeto da classe stdClass, sem qualquer funções disponíveis. o que as deixa silenciosamente sem funcionalidade.

Assim, se no exemplo acima $a se tornar parte de uma sessão pela utilização de session_register("a"), você precisa incluir o arquivo classe_a.inc.php em todos as suas páginas, não somente em page1.php e page2.php.


As funções mágicas __sleep e __wakeup

serialize() verifica se sua classe tem uma função com o nome mágico __sleep. Se sim, essa função será executada antes de qualquer serialização. Assim é possível controlar a persistência do objeto enquanto deve retornar um array com os nomes de todas as variáveis daquele objeto que precisam ser serializadas.

__sleep é planejado para fechar quaisquer conexões com bancos de dados que o objeto tenha, realizar commits pendentes ou realizar tarefas de limpeza semelhantes. A função também é útil se você tem objetos muito grandes que não precisam ser salvos completamente.

Da mesma forma, unserialize() verifica pela presença de uma função com o nome mágico __wakeup. Se presente, esta função pode reconstruir quaisquer recursos que o objeto tenha.

__wakeup é planejado para restabelecer conexões com bancos de dados perdidas durante a serialização e para realizar outras tarefas de reinicialização.


Referências dentro do construtor

A criação de referências em construtores pode gerar resultados confusos. Esta seção tentará ajudá-lo e evitar essas situações.

class Foo
{
    function Foo($name)
    {
        // cria uma referencia dentro do array global $globalref
        global $globalref;
        $globalref[] = &$this;
        // configura o nome conforme o parametro
        $this->setName($name);
        // e o mostra
        $this->echoName();
    }

    function echoName()
    {
        echo "<br>",$this->name;
    }

    function setName($name)
    {
        $this->name = $name;
    }
}

Vamos verificar, abaixo, se há alguma diferença entre $bar1, que foi criado usando operador de cópia =, e $bar2 que foi criado usando o operador de referência =& ...

$bar1 = new Foo('configurado no construtor');
$bar1->echoName();
$globalref[0]->echoName();

/* saida:
configurado no construtor
configurado no construtor
configurado no construtor */

$bar2 =& new Foo('configurado no construtor');
$bar2->echoName();
$globalref[1]->echoName();

/* saida:
configurado no construtor
configurado no construtor
configurado no construtor */

Aparentemente não há nenhuma diferença, mas de fato há uma muito significativa: $bar1 e $globalref[0] não se referenciam, elas NÃO são a mesma variável. Isto acontece porque "new" não retorna uma referência por default. Ao invés, retorna uma cópia.

Nota: Isto não causa perda de performance (desde que o PHP 4 usa a contagem de referências) retornando copias em vez de referências. Do contrário, isso oferece melhora por simplificar o trabalho com cópias ao invés de referências, porque a criação de referências toma mais tempo enquanto a criação de cópias virtualmente não toma tempo algum (a não ser no caso de grandes arrays ou objetos, onde um deles é modificado e o(s) outro(s) também na seqüência, então é melhor usar referências para mudar todos ao mesmo tempo).

Para comprovar o que escrevemos acima, analise o seguinte código.

// Agora nos vamos mudar o nome. O que voce espera?
// Voce pode acreditar que ambos $bar1 e $globalref[0] mudem seus nomes...
$bar1->setName('configurado por fora');

// Como mencionado, este nao eh o caso.
$bar1->echoName();
$globalref[0]->echoName();

/* output:
configurado por fora
configurado no construtor */

// Agora vamos ver a diferenca entre $bar2 e $globalref[1]
$bar2->setName('configurado por fora');

// Por sorte, eles nao sao apenas iguais, eles sao a mesma variavel
// Assim, $bar2->name e $globalref[1]->name sao o mesmo tambem
$bar2->echoName();
$globalref[1]->echoName();

/* output:
configurado por fora
configurado por fora */

E apenas mais um exemplo final. Entenda-o com cuidado.

class A
{
    function A($i)
    {
        $this->value = $i;
        // tente entender porque aqui nos nao precisamos de referencia
        $this->b = new B($this);
    }

    function createRef()
    {
        $this->c = new B($this);
    }

    function echoValue()
    {
        echo "<br>","classe ",get_class($this),': ',$this->value;
    }
}


class B
{
    function B(&$a)
    {
        $this->a = &$a;
    }

    function echoValue()
    {
        echo "<br>","classe ",get_class($this),': ',$this->a->value;
    }
}

// Tente entender porque usando uma simples copia aqui ter
// um resultado indesejavel na linha marcada com *
$a =& new A(10);
$a->createRef();

$a->echoValue();
$a->b->echoValue();
$a->c->echoValue();

$a->value = 11;

$a->echoValue();
$a->b->echoValue(); // *
$a->c->echoValue();

/*
output:
classe A: 10
classe B: 10
classe B: 10
classe A: 11
classe B: 11
classe B: 11
*/


Capítulo 15. Referências

O que são referências

Referências, em PHP, significa acessar o mesmo conteúdo de variável através de vários nomes. Isto não é parecido como os ponteiros em C: aqui temos apelidos numa tabela simbólica. Note que no PHP nomes de variáveis e conteúdo de variável são tratados diferentemente, então um mesmo conteúdo pode ter nomes diferentes. A analogia mais próxima é a dos arquivos e seus nomes em sistemas UNIX: nomes de variáveis são o caminho completo dos arquivos, enquanto o conteúdo da variável são os dados desse arquivo. Assim, referências pode ser tomadas como os links físicos dentro do sistema de arquivos UNIX.


O as referências fazem

Referências PHP permitem fazer duas variáveis se referirem ao mesmo conteúdo. Ou seja:

$a =& $b

aqui $a e $b apontam para a mesma variável.

Nota: $a e $b são completamente iguais aqui, mas não porque $a está apontando para $b ou vice versa, mas sim que $a e $b apontam para o mesmo lugar.

A mesma sintaxe pode ser utilizada com funções, que retornem referências, e com o operador new (a partir do PHP 4.0.4):

$bar =& new fooclass();
$foo =& find_var ($bar);

Nota: A não utilização do operador & causará a cópia do objeto. Se você utiliza $this em classes, ele operará na instância atual do objeto. A assimilação sem & irá copiar a instância (o objeto em si) e $this irá operar na cópia, podendo não ser esse procedimento sempre desejável. Normalmente você precisará trabalhar com uma instância única, seja por motivos de performance ou de consumo de memória.

Você pode utilizar o operador @ para esconder quaisquer erros em construtores na forma @new, mas isto não funciona quando utilizada a instrução &new. Esta é uma limitação da Zend Engine e irá gerar um erro de interpretação (parser error).

A segunda coisa que referências permitem é passar variáveis por referência. Isto é feito marcando uma variável local de uma função e a variável do escopo chamador como referências ao mesmo conteúdo. Exemplo:

function foo (&$var)
{
    $var++;
}

$a=5;
foo ($a);

fará que $a seja 6. Isto acontece porque na função foo a variável $var se refere ao mesmo conteúdo que $a. Veja explicações mais detalhadas em passagem por referência.

Em terceiro lugar, referências permitem também retorno por referência.


O que as referências não são

Como dito anteriormente, referências não são ponteiros. Isto significa que o construtor seguinte não fará o que você espera:

function foo (&$var)
{
    $var =& $GLOBALS["baz"];
}
foo($bar);

Acontece que $var na função foo estará apontada para $bar na chamada, mas ela será re-apontada para $GLOBALS["baz"]. Não existe maneira de apontar $bar no escopo chamador para qualquer outra coisa utilizando o mecanismo de referências, desde que $bar não está disponível na função foo (ela é representa por $var, mas $var somente tem o conteúdo da variável e não um relacionamento nome para valor na tabela simbólica).


Passagem por referência

Você pode passar variáveis para funções por referência, então a função poderá modificar seus argumentos. A sintaxe é a seguinte:

function foo (&$var)
{
    $var++;
}

$a=5;
foo ($a);
// $a é 6 aqui

Note que não há o sinal de referência na chamada da função, somente na definição da função. A marcação na definição da função sozinha é suficiente para configurar corretamente a passagem de argumentos por referência.

As coisas a seguir podem ser passadas por referência:

  • Variáveis. Exemplo: foo($a)

  • Instrução new. Exemplo foo(new foobar())

  • Outra referência, retornada de uma função. Exemplo:

    function &bar()
    {
        $a = 5;
        return $a;
    }
    foo(bar());

    Veja explicações sobre isso em retorno por referência.

Nenhuma outra expressão poderá ser passada por referência, com resultados indefinidos. Por exemplo, o exemplo seguinte de passagem por referência é inválido:

function bar() // Note a falta do &
{
    $a = 5;
    return $a;
}
foo(bar());

foo($a = 5) // Expressão, não é variável
foo(5) // Constante, não é variável

Essas limitações valem para o PHP 4.0.4 em diante.


Retornando referências

Retorno por referência é útil quando você precisa utilizar uma função para localizar variável cuja referência precisa ser obtida. Para retornar referências, utilize esta sintaxe:

function &procura_var ($param)
{
    ...codigo...
    return $variavel_encontrada;
}

$foo =& procura_var ($bar);
$foo->x = 2;

Neste exemplo, a propriedade do objeto retornado pela função procura_var precissa ser assimilada, não copiada, como acontecerá se não utilizar a sintaxe de referências.

Nota: Diferentemente da passagem de parâmetros por referência, aqui você precisa utilizar & em ambos os lugares --- primeiro para indicar o retorno por referência (e não a cópia), e depois para indicar a ligação da referência (em vez da assimilação convencional) que precisa ser explícita.


Destruindo referências

Quando você quebra uma referência, ela apenas pára de fazer o apontamento entre o nome da variável e o conteúdo. Mas isto não significa que o conteúdo da variável será destruído. Por exemplo:

$a = 1;
$b =& $a;
unset ($a);

não apaga $b, apenas $a.

Novamente, é mais fácil pensar em analogia ao comando UNIX unlink.


Demonstrando referências

Vários construtores sintáticos do PHP são implementados através de mecanismos de referência, assim, tudo o explicado até aqui sobre referências também se aplica a esses construtores. Alguns desses construtores, como a passagem e o retorno de referências foram mencionados acima. Outros construtores que também utilizam referências são:


global

Quando você declara uma variável com global, você está de fato criando um referência para a variável global. Isto significa que isto é o mesmo que:

$var =& $GLOBALS["var"];

O que significa também que destruir $var não apaga a variável global.


$this

Num método de objeto, $this sempre referencia o instância atual.


Capítulo 16. HTTP authentication with PHP

The HTTP Authentication hooks in PHP are only available when it is running as an Apache module and is hence not available in the CGI version. In an Apache module PHP script, it is possible to use the header() function to send an "Authentication Required" message to the client browser causing it to pop up a Username/Password input window. Once the user has filled in a username and a password, the URL containing the PHP script will be called again with the predefined variables PHP_AUTH_USER, PHP_AUTH_PW, and PHP_AUTH_TYPE set to the user name, password and authentication type respectively. These predefined variables are found in the $_SERVER and $HTTP_SERVER_VARS arrays. Only "Basic" authentication is supported. See the header() function for more information.

PHP Version Note: Autoglobals, such as $_SERVER, became available in PHP version 4.1.0. $HTTP_SERVER_VARS has been available since PHP 3.

An example script fragment which would force client authentication on a page is as follows:

Exemplo 16-1. HTTP Authentication example

<?php
  if (!isset($_SERVER['PHP_AUTH_USER'])) {
    header('WWW-Authenticate: Basic realm="My Realm"');
    header('HTTP/1.0 401 Unauthorized');
    echo 'Text to send if user hits Cancel button';
    exit;
  } else {
    echo "<p>Hello {$_SERVER['PHP_AUTH_USER']}.</p>";
    echo "<p>You entered {$_SERVER['PHP_AUTH_PW']} as your password.</p>";
  }
?>

Compatibility Note: Please be careful when coding the HTTP header lines. In order to guarantee maximum compatibility with all clients, the keyword "Basic" should be written with an uppercase "B", the realm string must be enclosed in double (not single) quotes, and exactly one space should precede the 401 code in the HTTP/1.0 401 header line.

Instead of simply printing out PHP_AUTH_USER and PHP_AUTH_PW, as done in the above example, you may want to check the username and password for validity. Perhaps by sending a query to a database, or by looking up the user in a dbm file.

Watch out for buggy Internet Explorer browsers out there. They seem very picky about the order of the headers. Sending the WWW-Authenticate header before the HTTP/1.0 401 header seems to do the trick for now.

As of PHP 4.3.0, in order to prevent someone from writing a script which reveals the password for a page that was authenticated through a traditional external mechanism, the PHP_AUTH variables will not be set if external authentication is enabled for that particular page and safe mode is enabled. Regardless, REMOTE_USER can be used to identify the externally-authenticated user. So, you can use $_SERVER['REMOTE_USER'].

Configuration Note: PHP uses the presence of an AuthType directive to determine whether external authentication is in effect.

Note, however, that the above does not prevent someone who controls a non-authenticated URL from stealing passwords from authenticated URLs on the same server.

Both Netscape Navigator and Internet Explorer will clear the local browser window's authentication cache for the realm upon receiving a server response of 401. This can effectively "log out" a user, forcing them to re-enter their username and password. Some people use this to "time out" logins, or provide a "log-out" button.

Exemplo 16-2. HTTP Authentication example forcing a new name/password

<?php
  function authenticate() {
    header('WWW-Authenticate: Basic realm="Test Authentication System"');
    header('HTTP/1.0 401 Unauthorized');
    echo "You must enter a valid login ID and password to access this resource\n";
    exit;
  }
 
  if (!isset($_SERVER['PHP_AUTH_USER']) ||
      ($_POST['SeenBefore'] == 1 && $_POST['OldAuth'] == $_SERVER['PHP_AUTH_USER'])) {
   authenticate();
  } 
  else {
   echo "<p>Welcome: {$_SERVER['PHP_AUTH_USER']}<br>";
   echo "Old: {$_REQUEST['OldAuth']}";
   echo "<form action='{$_SERVER['PHP_SELF']}' METHOD='POST'>\n";
   echo "<input type='hidden' name='SeenBefore' value='1'>\n";
   echo "<input type='hidden' name='OldAuth' value='{$_SERVER['PHP_AUTH_USER']}'>\n";
   echo "<input type='submit' value='Re Authenticate'>\n";
   echo "</form></p>\n";
  }
?>

This behavior is not required by the HTTP Basic authentication standard, so you should never depend on this. Testing with Lynx has shown that Lynx does not clear the authentication credentials with a 401 server response, so pressing back and then forward again will open the resource as long as the credential requirements haven't changed. The user can press the '_' key to clear their authentication information, however.

Also note that this does not work using Microsoft's IIS server and the CGI version of PHP due to a limitation of IIS.

Nota: If safe mode is enabled, the uid of the script is added to the realm part of the WWW-Authenticate header.


Capítulo 17. Cookies

O PHP suporta transparentemente cookies HTTP. Cookies são um mecanismo para guardar dados no navegador remoto possibilitando o acompanhamento ou identificação de usuários que retornam. Você pode criar cookies usando a função setcookie(). Os cookies são uma parte do cabeçalho HTTP, logo setcookie() precisa ser chamada antes que qualquer outro dado seja enviado ao navegador. Esta é a mesma limitação que a função header() tem. Você pode usar as funções de output buferizado para atrasar as impressões do script até que você tenha decidido ou não configurar qualquer cookie ou enviar mais headers.

Qualquer cookie enviado por você para o cliente automaticamente será uma variável do PHP assim como dados de postagens GET ou POST, dependendo dos valores de register_globals e variables_order. Se você deseja assimilar vários valores em um único cookie, simplesmente acrescente [] ao nome do cookie.

NO PHP 4.1.0 e posteriores, o array superglobal $_COOKIE sempre estará preenchido com quaisquer cookies enviados do cliente. $HTTP_COOKIE_VARS, existente nas versões anteriores do PHP, também, quando a variável de configuração track_vars estiver ativa.

Para mais detalhes, incluindo comentários sobre problemas de browsers, veja a função setcookie().


Capítulo 18. Gerenciar o upload de arquivos

Upload de arquivos com o método POST

O PHP é capaz de receber o upload de qualquer browser que siga a norma RFC-1867 (o que inclui Netscape Navigator 3 ou posterior, Microsoft Internet Explorer 3 com um patch da Microsoft, ou posterior sem patch). Isto permite que se faça o upload de arquivos de texto e binários. Com as funções de autenticação e manipulação de arquivos do PHP, você tem o controle completo de quem pode fazer o upload de arquivo e o que fazer com o arquivo após seu upload.

Nota Sobre Configurações Relacionadas: Veja também file_uploads, upload_max_filesize, upload_tmp_dir, e post_max_size no php.ini

Note que o PHP também suporta o método PUT para upload de arquivos como o usado por Netscape Composer e W3C's Amaya clients. Veja Suporte ao Método Put para maiores detalhes.

Uma tela para upload de arquivo pode ser criada com um formulário especial parecido com este:

Exemplo 18-1. Formulário para Upload de Arquivo

<form enctype="multipart/form-data" action="_URL_" method="post">
<input type="hidden" name="MAX_FILE_SIZE" value="30000">
Send this file: <input name="userfile" type="file">
<input type="submit" value="Enviar Arquivo">
</form>
A _URL_ deve indicar um arquivo PHP. O campo hidden MAX_FILE_SIZE deve vir antes do campo input e seu valor é o limite aceito de tamanho do arquivo. O valor é em bytes.

Atenção

O valor de MAX_FILE_SIZE é um aviso para o browser. É fácil contornar este limite. Então não conte que o browser irá obedecer a sua vontade. O que foi estabelecido para maximum-size no PHP não pode ser enganado.

As variáveis definidas para o upload de arquivos são diferentes dependendo da versão e da configuração. A autoglobal $_FILES existe desde o PHP 4.1.0. A array $HTTP_POST_FILES existe desde o PHP 4.0.0. Estas array irão conter toda a informação do upload do arquivo. Usar $_FILES é preferido. Se a opção register_globals é on, os nomes de variáveis relacionados também existirão. O padrão de register_globals é off desde o PHP 4.2.0.

Os conteúdos de $_FILES do nosso script de exemplo é como segue. Note que isso assume que o nome do upload do arquivo é userfile, como o usado no exemplo acima.

$_FILES['userfile']['name']

O nome original do arquivo no computador do usuário.

$_FILES['userfile']['type']

O tipo mime do arquivo, se o browser deu esta informação. Um exemplo pode ser "image/gif".

$_FILES['userfile']['size']

O tamanho, em bytes, do arquivo.

$_FILES['userfile']['tmp_name']

O nome temporário do arquivo, como foi guardado no servidor.

$_FILES['userfile']['error']

O código de erro associado a este upload de arquivo. ['error'] foi adicionado no PHP 4.2.0

Nota: Em versões anteriores a 4.1.0 o nome era $HTTP_POST_FILES e não é uma variável autoglobal como $_FILES é. PHP 3 não suporta $HTTP_POST_FILES.

Quando register_globals esta em on no php.ini, variáveis adicionais estão disponíveis. Por exemplo, $userfile_name será igual a $_FILES['userfile']['name'], $userfile_type será igual a $_FILES['userfile']['type'], etc. Lembre-se que desde o PHP 4.2.0, o padrão para register_globals é off. É preferrível não depender desta opção.

Os arquivos serão guardados no diretório temporário do servidor, a menos que outro lugar seja especificado com a opção upload_tmp_dir no php.ini. O diretório padrão do servidor pode ser mudado se mudando o valor da variável de ambiente TMPDIR no ambiente onde o PHP esta sendo executado PHP. Mudando-a com putenv() de um script PHP não irá funcionar. Esta variável de ambiente também pode ser usada para se ter certeza que outras operações estão funcionando no arquivo do upload.

Note que deve se definir upload_temp_dir no php.ini ou TMPDIR, não podendo estarem ambos vazios, sendo recomendado no mínimo upload_tmp_dir.

Exemplo 18-2. Validando o upload de arquivos

Veja também as funções is_uploaded_file() e move_uploaded_file() para maiores informações. O seguinte exemplo irá processar o envio de um arquivo que vem de um formulário.

<?php
// Nas versões anteriores a 4.1.0, $HTTP_POST_FILES deve ser usado ao invés de $_FILES.
// Nas versões anteriores a 4.0.3, use copy() e is_uploaded_file() ao invés move_uploaded_file

$uploaddir = '/var/www/uploads/';

print "<pre>";
if (move_uploaded_file($_FILES['userfile']['tmp_name'], $uploaddir . $_FILES['userfile']['name'])) {
    print "O arquivo é valido e foi carregado com sucesso. Aqui esta alguma informação:\n";
    print_r($_FILES);
} else {
    print "Possivel ataque de upload! Aqui esta alguma informação:\n";
    print_r($_FILES);
}

?>

O script PHP que irá receber o arquivo do upload deve implementar qualquer lógica que for necessária para determinar o que deve ser feito com o arquivo do upload. Você pode, por exemplo, usar a variável $_FILES['userfile']['size'] para descartar qualquer arquivo que seja muito pequeno ou muito grande. Você pode usar a variável $_FILES['userfile']['type'] que não sejam de um certo tipo. Desde o PHP 4.2.0, você pode usar $_FILES['userfile']['error'] e planejar a sua lógica de acordo com os códigos de erro. Qualquer que seja a lógica, você deve excluir o arquivo do diretório temporário ou move-lo para outro lugar.

O arquivo será excluído do diretório temporário ao fim do script se não tiver sido movido ou renomeado.


Explicação das mensagens de erro

Desde o PHP 4.2.0, PHP retorna um código de erro apropriado na array do arquivo. O código de erro pode ser encontrado em ['error'] na array que é criada durante o upload do arquivo. Em outras palavras, o erro deve ser encontrado em $_FILES['userfile']['error'].

UPLOAD_ERR_OK

Valor: 0; não houve erro, o upload foi bem sucedido.

UPLOAD_ERR_INI_SIZE

Valor 1; O arquivo no upload é maior do que o limite definido em upload_max_filesize no php.ini.

UPLOAD_ERR_FORM_SIZE

Valor: 2; O arquivo ultrapassa o limite de tamanho em MAX_FILE_SIZE que foi especificado no formulário html.

UPLOAD_ERR_PARTIAL

Valor: 3; o upload do arquivo foi feito parcialmente.

UPLOAD_ERR_NO_FILE

Valor: 4; Não foi feito o upload do arquivo.

Nota: Estas tornaram-se constantes no PHP 4.3.0


Problemas comuns

O item MAX_FILE_SIZE não pode especificar um tamanho de arquivo com tamanho maior do que o especificado no php.ini em upload_max_filesize. O padrão é 2 Megabytes.

Se o limite de memória esta ativado, um maior memory_limit pode ser necessário. tenha certeza de estabelecer um memory_limit grande o suficiente.

Se max_execution_time for muito pequeno, a execução do script pode ultrapassar o limite de tempo. Tenha certeza de estabelecer um max_execution_time grande o suficiente.

Se post_max_size for muito pequeno, arquivos grandes não poderão ser carregados. Tenha certeza de estabelecer post_max_size grande o suficiente.

Não validar o arquivo que você esta operando pode permitir que os usuários acessem informações sensíveis em outros diretórios.

Por favor note que o CERN httpd aparenta cortar tudo iniciando após o primeiro espaço do header content-type que ele recebe do cliente. Se for este o caso, CERN httpd não irá suportar o upload de arquivos.

Devido ao grande número de estilos de listagem de diretórios nós não podemos garantir que arquivos com nomes exóticos(como que contém espaço) sejam manuseados corretamente.


Carregando múltiplos arquivos

Múltiplos arquivos podem ser carregados usando-se diferentes name para input.

Também é possível carregar vários arquivos simultaneamente e ter a informação organizada automaticamente para você em arrays. Para fazer assim, você precisa usar a mesma sintaxe no formulário HTML que você usa para múltiplos selects e checkboxes:

Nota: O Suporte para carregar múltiplos arquivos foi adicionado na versão 3.0.10.

Exemplo 18-3. Carregando múltiplos arquivos

<form action="file-upload.php" method="post" enctype="multipart/form-data">
  Send these files:<br>
  <input name="userfile[]" type="file"><br>
  <input name="userfile[]" type="file"><br>
  <input type="submit" value="Send files">
</form>

Quando o formulário acima é submetido, as matrizes $_FILES['userfile'], $_FILES['userfile']['name'], e $_FILES['userfile']['size'] serão inicializadas (assim como $HTTP_POST_FILES para versões do PHP anterior a 4.1.0). Quando register_globals esta em on, globals para os arquivos carregados também são inicializadas. Cada um destes será uma array indexada numericamente dos valores apropriados para os arquivos submetidos.

Por exemplo, assuma que os nomes de arquivos tenham sido submetidos /home/test/review.html e /home/test/xwp.out. Neste caso, $_FILES['userfile']['name'][0] deve conter o valor review.html, e $_FILES['userfile']['name'][1] deve conter o valor xwp.out. Similarmente, $_FILES['userfile']['size'][0] deve conter o tamanho de review.html, e assim por diante.

$_FILES['userfile']['name'][0], $_FILES['userfile']['tmp_name'][0], $_FILES['userfile']['size'][0], e $_FILES['userfile']['type'][0] também são definidas.


Suporte ao método PUT

O suporte ao método PUT mudou entre PHP 3 e PHP 4. No PHP 4, deve se usar a entrada padrão para ler os conteúdos de um PUT.

Exemplo 18-4. Salvando arquivos HTTP PUT com o PHP 4

<?php
/* PUT data vem do stdin stream */
$putdata = fopen("php://stdin","r");

/* Abre um arquivo para escrita */
$fp = fopen("myputfile.ext","w");

/* Lê os dados 1KB de cada vez
   e escreve no arquivo */
while ($data = fread($putdata,1024))
  fwrite($fp,$data);

/* Fecha os streams */
fclose($fp);
fclose($putdata);
?>

Nota: Toda a documentação abaixo aplica-se ao PHP 3 somente.

PHP prove suporte para o método HTTP PUT usado por clientes como Netscape Composer e W3C Amaya. Requisições PUT são muito mais simples do que o upload de arquivo e se parecem com isto:

PUT /path/filename.html HTTP/1.1

Isto normalmente indica que o cliente remoto gostaria de salvar o conteúdo que se segue como: /path/filename.html na sua arvore web. É obvio que não é uma boa idéia para o Apache ou o PHP automaticamente permitir que todos possam sobrescrever arquivos na sua arvore web. Então, para manusear este tipo de requisição você tem primeiro que dizer ao seu servidor web que você quer que um certo script PHP cuide da requisição. No apache você faz isto com a diretiva Script. Pode ser colocada praticamente em qualquer lugar do seu arquivo de configuração do Apache. Um lugar comum é dentro de um bloco <Directory> ou talvez dentro de um bloco <Virtualhost>. Uma linha como esta deve fazer o truque:

Script PUT /put.php

Isto diz para o apache enviar todas as requisições PUT que estejam no contexto que você colocou esta linha para o script put.php. Isto assume, é claro, que você tem o PHP ativado para a extensão .php e que o PHP esta ativo.

Dentro do seu arquivo put.php você deve então fazer algo parecido com isto:

<?php copy($PHP_UPLOADED_FILE_NAME,$DOCUMENT_ROOT.$REQUEST_URI); ?>

Isto deve copiar o arquivo para a localização requisitada pelo cliente remoto. Você provavelmente quer fazer alguma checagem e/ou autenticar o usuário antes de fazer esta copia de arquivo. O único truque aqui é que quando o php vê uma requisição com o método PUT ele guarda o arquivo carregado em um arquivo temporário justo como se fosse manuseado pelo método POST. Quando a requisição termina, este arquivo temporário é apagado. Assim seu script de manuseio do PUT tem que copiar este arquivo em outro lugar. O nome deste arquivo temporário esta na variável $PHP_PUT_FILENAME, e você pode ver o nome de arquivo de destino sugerido em $REQUEST_URI (deve variar em servidores diferentes do apache). Este nome do arquivo de destino é o que o cliente remoto especificou. Você não tem que ouvir o cliente. Você pode, por exemplo, copiar todos os arquivos carregados para um diretório especial de uploads.


Capítulo 19. Using remote files

As long as allow_url_fopen is enabled in php.ini, you can use HTTP and FTP URLs with most of the functions that take a filename as a parameter. In addition, URLs can be used with the include(), include_once(), require() and require_once() statements. See Apêndice I for more information about the protocols supported by PHP.

Nota: In PHP 4.0.3 and older, in order to use URL wrappers, you were required to configure PHP using the configure option --enable-url-fopen-wrapper.

Nota: The Windows versions of PHP earlier than PHP 4.3 did not support remote file accessing for the following functions: include(), include_once(), require(), require_once(), and the imagecreatefromXXX functions in the Referência XLI, Image functions extension.

For example, you can use this to open a file on a remote web server, parse the output for the data you want, and then use that data in a database query, or simply to output it in a style matching the rest of your website.

Exemplo 19-1. Getting the title of a remote page

<?php
$file = fopen ("http://www.example.com/", "r");
if (!$file) {
    echo "<p>Unable to open remote file.\n";
    exit;
}
while (!feof ($file)) {
    $line = fgets ($file, 1024);
    /* This only works if the title and its tags are on one line */
    if (eregi ("<title>(.*)</title>", $line, $out)) {
        $title = $out[1];
        break;
    }
}
fclose($file);
?>

You can also write to files on an FTP server (provided that you have connected as a user with the correct access rights). You can only create new files using this method; if you try to overwrite a file that already exists, the fopen() call will fail.

To connect as a user other than 'anonymous', you need to specify the username (and possibly password) within the URL, such as 'ftp://user:password@ftp.example.com/path/to/file'. (You can use the same sort of syntax to access files via HTTP when they require Basic authentication.)

Exemplo 19-2. Storing data on a remote server

<?php
$file = fopen ("ftp://ftp.example.com/incoming/outputfile", "w");
if (!$file) {
    echo "<p>Unable to open remote file for writing.\n";
    exit;
}
/* Write the data here. */
fputs ($file, $_SERVER['HTTP_USER_AGENT'] . "\n");
fclose ($file);
?>

Nota: You might get the idea from the example above that you can use this technique to write to a remote log file. Unfortunately that would not work because the fopen() call will fail if the remote file already exists. To do distributed logging like that, you should take a look at syslog().


Capítulo 20. Connection handling

Nota: The following applies to 3.0.7 and later.

Internally in PHP a connection status is maintained. There are 3 possible states:

  • 0 - NORMAL

  • 1 - ABORTED

  • 2 - TIMEOUT

When a PHP script is running normally the NORMAL state, is active. If the remote client disconnects the ABORTED state flag is turned on. A remote client disconnect is usually caused by the user hitting his STOP button. If the PHP-imposed time limit (see set_time_limit()) is hit, the TIMEOUT state flag is turned on.

You can decide whether or not you want a client disconnect to cause your script to be aborted. Sometimes it is handy to always have your scripts run to completion even if there is no remote browser receiving the output. The default behaviour is however for your script to be aborted when the remote client disconnects. This behaviour can be set via the ignore_user_abort php.ini directive as well as through the corresponding "php_value ignore_user_abort" Apache .conf directive or with the ignore_user_abort() function. If you do not tell PHP to ignore a user abort and the user aborts, your script will terminate. The one exception is if you have registered a shutdown function using register_shutdown_function(). With a shutdown function, when the remote user hits his STOP button, the next time your script tries to output something PHP will detect that the connection has been aborted and the shutdown function is called. This shutdown function will also get called at the end of your script terminating normally, so to do something different in case of a client disconnect you can use the connection_aborted() function. This function will return TRUE if the connection was aborted.

Your script can also be terminated by the built-in script timer. The default timeout is 30 seconds. It can be changed using the max_execution_time php.ini directive or the corresponding "php_value max_execution_time" Apache .conf directive as well as with the set_time_limit() function. When the timer expires the script will be aborted and as with the above client disconnect case, if a shutdown function has been registered it will be called. Within this shutdown function you can check to see if a timeout caused the shutdown function to be called by calling the connection_timeout() function. This function will return TRUE if a timeout caused the shutdown function to be called.

One thing to note is that both the ABORTED and the TIMEOUT states can be active at the same time. This is possible if you tell PHP to ignore user aborts. PHP will still note the fact that a user may have broken the connection, but the script will keep running. If it then hits the time limit it will be aborted and your shutdown function, if any, will be called. At this point you will find that connection_timeout() and connection_aborted() return TRUE. You can also check both states in a single call by using the connection_status(). This function returns a bitfield of the active states. So, if both states are active it would return 3, for example.


Capítulo 21. Persistent Database Connections

Persistent connections are SQL links that do not close when the execution of your script ends. When a persistent connection is requested, PHP checks if there's already an identical persistent connection (that remained open from earlier) - and if it exists, it uses it. If it does not exist, it creates the link. An 'identical' connection is a connection that was opened to the same host, with the same username and the same password (where applicable).

Nota: There are other extensions that provide persistent connections, such as the IMAP extension.

People who aren't thoroughly familiar with the way web servers work and distribute the load may mistake persistent connects for what they're not. In particular, they do not give you an ability to open 'user sessions' on the same SQL link, they do not give you an ability to build up a transaction efficiently, and they don't do a whole lot of other things. In fact, to be extremely clear about the subject, persistent connections don't give you any functionality that wasn't possible with their non-persistent brothers.

Why?

This has to do with the way web servers work. There are three ways in which your web server can utilize PHP to generate web pages.

The first method is to use PHP as a CGI "wrapper". When run this way, an instance of the PHP interpreter is created and destroyed for every page request (for a PHP page) to your web server. Because it is destroyed after every request, any resources that it acquires (such as a link to an SQL database server) are closed when it is destroyed. In this case, you do not gain anything from trying to use persistent connections -- they simply don't persist.

The second, and most popular, method is to run PHP as a module in a multiprocess web server, which currently only includes Apache. A multiprocess server typically has one process (the parent) which coordinates a set of processes (its children) who actually do the work of serving up web pages. When each request comes in from a client, it is handed off to one of the children that is not already serving another client. This means that when the same client makes a second request to the server, it may be serviced by a different child process than the first time. What a persistent connection does for you in this case it make it so each child process only needs to connect to your SQL server the first time that it serves a page that makes use of such a connection. When another page then requires a connection to the SQL server, it can reuse the connection that child established earlier.

The last method is to use PHP as a plug-in for a multithreaded web server. Currently PHP 4 has support for ISAPI, WSAPI, and NSAPI (on Windows), which all allow PHP to be used as a plug-in on multithreaded servers like Netscape FastTrack (iPlanet), Microsoft's Internet Information Server (IIS), and O'Reilly's WebSite Pro. The behavior is essentially the same as for the multiprocess model described before. Note that SAPI support is not available in PHP 3.

If persistent connections don't have any added functionality, what are they good for?

The answer here is extremely simple -- efficiency. Persistent connections are good if the overhead to create a link to your SQL server is high. Whether or not this overhead is really high depends on many factors. Like, what kind of database it is, whether or not it sits on the same computer on which your web server sits, how loaded the machine the SQL server sits on is and so forth. The bottom line is that if that connection overhead is high, persistent connections help you considerably. They cause the child process to simply connect only once for its entire lifespan, instead of every time it processes a page that requires connecting to the SQL server. This means that for every child that opened a persistent connection will have its own open persistent connection to the server. For example, if you had 20 different child processes that ran a script that made a persistent connection to your SQL server, you'd have 20 different connections to the SQL server, one from each child.

Note, however, that this can have some drawbacks if you are using a database with connection limits that are exceeded by persistent child connections. If your database has a limit of 16 simultaneous connections, and in the course of a busy server session, 17 child threads attempt to connect, one will not be able to. If there are bugs in your scripts which do not allow the connections to shut down (such as infinite loops), the database with only 16 connections may be rapidly swamped. Check your database documentation for information on handling abandoned or idle connections.

Atenção

There are a couple of additional caveats to keep in mind when using persistent connections. One is that when using table locking on a persistent connection, if the script for whatever reason cannot release the lock, then subsequent scripts using the same connection will block indefinitely and may require that you either restart the httpd server or the database server. Another is that when using transactions, a transaction block will also carry over to the next script which uses that connection if script execution ends before the transaction block does. In either case, you can use register_shutdown_function() to register a simple cleanup function to unlock your tables or roll back your transactions. Better yet, avoid the problem entirely by not using persistent connections in scripts which use table locks or transactions (you can still use them elsewhere).

An important summary. Persistent connections were designed to have one-to-one mapping to regular connections. That means that you should always be able to replace persistent connections with non-persistent connections, and it won't change the way your script behaves. It may (and probably will) change the efficiency of the script, but not its behavior!

See also fbsql_pconnect(), ibase_pconnect(), ifx_pconnect(), imap_popen(), ingres_pconnect(), msql_pconnect(), mssql_pconnect(), mysql_pconnect(), OCIPLogon(), odbc_pconnect(), Ora_pLogon(), pfsockopen(), pg_pconnect(), and sybase_pconnect().


Capítulo 22. Safe Mode

The PHP safe mode is an attempt to solve the shared-server security problem. It is architecturally incorrect to try to solve this problem at the PHP level, but since the alternatives at the web server and OS levels aren't very realistic, many people, especially ISP's, use safe mode for now.


Security and Safe Mode

Tabela 22-1. Security and Safe Mode Configuration Directives

Name Default Changeable
safe_mode "0" PHP_INI_SYSTEM
safe_mode_gid "0" PHP_INI_SYSTEM
safe_mode_include_dir NULL PHP_INI_SYSTEM
safe_mode_exec_dir "" PHP_INI_SYSTEM
safe_mode_allowed_env_vars PHP_ PHP_INI_SYSTEM
safe_mode_protected_env_vars LD_LIBRARY_PATH PHP_INI_SYSTEM
open_basedir NULL PHP_INI_SYSTEM
disable_functions "" PHP_INI_SYSTEM
For further details and definition of the PHP_INI_* constants see ini_set().

Here is a short explanation of the configuration directives.

safe_mode boolean

Whether to enable PHP's safe mode. Read the Security and chapter for more information.

safe_mode_gid boolean

By default, Safe Mode does a UID compare check when opening files. If you want to relax this to a GID compare, then turn on safe_mode_gid. Whether to use UID (FALSE) or GID (TRUE) checking upon file access.

safe_mode_include_dir string

UID/GID checks are bypassed when including files from this directory and its subdirectories (directory must also be in include_path or full path must including).

As of PHP 4.2.0, this directive can take a semi-colon separated path in a similar fashion to the include_path directive, rather than just a single directory.

The restriction specified is actually a prefix, not a directory name. This means that "safe_mode_include_dir = /dir/incl" also allows access to "/dir/include" and "/dir/incls" if they exist. When you want to restrict access to only the specified directory, end with a slash. For example: "safe_mode_include_dir = /dir/incl/"

safe_mode_exec_dir string

If PHP is used in safe mode, system() and the other functions executing system programs refuse to start programs that are not in this directory.

safe_mode_allowed_env_vars string

Setting certain environment variables may be a potential security breach. This directive contains a comma-delimited list of prefixes. In Safe Mode, the user may only alter environment variables whose names begin with the prefixes supplied here. By default, users will only be able to set environment variables that begin with PHP_ (e.g. PHP_FOO=BAR).

Nota: If this directive is empty, PHP will let the user modify ANY environment variable!

safe_mode_protected_env_vars string

This directive contains a comma-delimited list of environment variables that the end user won't be able to change using putenv(). These variables will be protected even if safe_mode_allowed_env_vars is set to allow to change them.

open_basedir string

Limit the files that can be opened by PHP to the specified directory-tree, including the file itself. This directive is NOT affected by whether Safe Mode is turned On or Off.

When a script tries to open a file with, for example, fopen or gzopen, the location of the file is checked. When the file is outside the specified directory-tree, PHP will refuse to open it. All symbolic links are resolved, so it's not possible to avoid this restriction with a symlink.

The special value . indicates that the directory in which the script is stored will be used as base-directory.

Under Windows, separate the directories with a semicolon. On all other systems, separate the directories with a colon. As an Apache module, open_basedir paths from parent directories are now automatically inherited.

The restriction specified with open_basedir is actually a prefix, not a directory name. This means that "open_basedir = /dir/incl" also allows access to "/dir/include" and "/dir/incls" if they exist. When you want to restrict access to only the specified directory, end with a slash. For example: "open_basedir = /dir/incl/"

Nota: Support for multiple directories was added in 3.0.7.

The default is to allow all files to be opened.

disable_functions string

This directive allows you to disable certain functions for security reasons. It takes on a comma-dilimited list of function names. disable_functions is not affected by Safe Mode.

This directive must be set in php.ini For example, you cannot set this in httpd.conf.

See also: register_globals, display_errors, and log_errors

When safe_mode is on, PHP checks to see if the owner of the current script matches the owner of the file to be operated on by a file function. For example:
-rw-rw-r--    1 rasmus   rasmus       33 Jul  1 19:20 script.php 
-rw-r--r--    1 root     root       1116 May 26 18:01 /etc/passwd
Running this script.php
<?php
 readfile('/etc/passwd'); 
?>
results in this error when safe mode is enabled:
Warning: SAFE MODE Restriction in effect. The script whose uid is 500 is not 
allowed to access /etc/passwd owned by uid 0 in /docroot/script.php on line 2

However, there may be environments where a strict UID check is not appropriate and a relaxed GID check is sufficient. This is supported by means of the safe_mode_gid switch. Setting it to On performs the relaxed GID checking, setting it to Off (the default) performs UID checking.

If instead of safe_mode, you set an open_basedir directory then all file operations will be limited to files under the specified directory For example (Apache httpd.conf example):
<Directory /docroot>
  php_admin_value open_basedir /docroot 
</Directory>
If you run the same script.php with this open_basedir setting then this is the result:
Warning: open_basedir restriction in effect. File is in wrong directory in 
/docroot/script.php on line 2

You can also disable individual functions. Note that the disable_functions directive can not be used outside of the php.ini file which means that you cannot disable functions on a per-virtualhost or per-directory basis in your httpd.conf file. If we add this to our php.ini file:
disable_functions readfile,system
Then we get this output:
Warning: readfile() has been disabled for security reasons in 
/docroot/script.php on line 2


Functions restricted/disabled by safe mode

This is a still probably incomplete and possibly incorrect listing of the functions limited by safe mode.

Tabela 22-2. Safe mode limited functions

Function Limitations
dbmopen() Verifica se o(s) arquivo(s) e/ou diretório(s) que serão afetados por esta operação tem o mesmo UID (proprietário) do script que está sendo executado.
dbase_open() Verifica se o(s) arquivo(s) e/ou diretório(s) que serão afetados por esta operação tem o mesmo UID (proprietário) do script que está sendo executado.
filepro() Verifica se o(s) arquivo(s) e/ou diretório(s) que serão afetados por esta operação tem o mesmo UID (proprietário) do script que está sendo executado.
filepro_rowcount() Verifica se o(s) arquivo(s) e/ou diretório(s) que serão afetados por esta operação tem o mesmo UID (proprietário) do script que está sendo executado.
filepro_retrieve() Verifica se o(s) arquivo(s) e/ou diretório(s) que serão afetados por esta operação tem o mesmo UID (proprietário) do script que está sendo executado.
ifx_*() sql_safe_mode restrictions, (!= safe mode)
ingres_*() sql_safe_mode restrictions, (!= safe mode)
mysql_*() sql_safe_mode restrictions, (!= safe mode)
pg_loimport() Verifica se o(s) arquivo(s) e/ou diretório(s) que serão afetados por esta operação tem o mesmo UID (proprietário) do script que está sendo executado.
posix_mkfifo() Verifica se o diretório que será afetado por esta operação tem o mesmo UID (proprietário) do script qur está sendo executado.
putenv() Obeys the safe_mode_protected_env_vars and safe_mode_allowed_env_vars ini-directives. See also the documentation on putenv()
move_uploaded_file() Verifica se o(s) arquivo(s) e/ou diretório(s) que serão afetados por esta operação tem o mesmo UID (proprietário) do script que está sendo executado.
chdir() Verifica se o diretório que será afetado por esta operação tem o mesmo UID (proprietário) do script qur está sendo executado.
dl() Esta função é desabilitada no safe-mode
backtick operator Esta função é desabilitada no safe-mode
shell_exec() (functional equivalent of backticks) Esta função é desabilitada no safe-mode
exec() You can only execute executables within the safe_mode_exec_dir. For practical reasons it's currently not allowed to have .. components in the path to the executable.
system() You can only execute executables within the safe_mode_exec_dir. For practical reasons it's currently not allowed to have .. components in the path to the executable.
passthru() You can only execute executables within the safe_mode_exec_dir. For practical reasons it's currently not allowed to have .. components in the path to the executable.
popen() You can only execute executables within the safe_mode_exec_dir. For practical reasons it's currently not allowed to have .. components in the path to the executable.
mkdir() Verifica se o diretório que será afetado por esta operação tem o mesmo UID (proprietário) do script qur está sendo executado.
rmdir() Verifica se o(s) arquivo(s) e/ou diretório(s) que serão afetados por esta operação tem o mesmo UID (proprietário) do script que está sendo executado.
rename() Verifica se o(s) arquivo(s) e/ou diretório(s) que serão afetados por esta operação tem o mesmo UID (proprietário) do script que está sendo executado. Verifica se o diretório que será afetado por esta operação tem o mesmo UID (proprietário) do script qur está sendo executado.
unlink() Verifica se o(s) arquivo(s) e/ou diretório(s) que serão afetados por esta operação tem o mesmo UID (proprietário) do script que está sendo executado. Verifica se o diretório que será afetado por esta operação tem o mesmo UID (proprietário) do script qur está sendo executado.
copy() Verifica se o(s) arquivo(s) e/ou diretório(s) que serão afetados por esta operação tem o mesmo UID (proprietário) do script que está sendo executado. Verifica se o diretório que será afetado por esta operação tem o mesmo UID (proprietário) do script qur está sendo executado. (on source and target)
chgrp() Verifica se o(s) arquivo(s) e/ou diretório(s) que serão afetados por esta operação tem o mesmo UID (proprietário) do script que está sendo executado.
chown() Verifica se o(s) arquivo(s) e/ou diretório(s) que serão afetados por esta operação tem o mesmo UID (proprietário) do script que está sendo executado.
chmod() Verifica se o(s) arquivo(s) e/ou diretório(s) que serão afetados por esta operação tem o mesmo UID (proprietário) do script que está sendo executado. In addition, you cannot set the SUID, SGID and sticky bits
touch() Verifica se o(s) arquivo(s) e/ou diretório(s) que serão afetados por esta operação tem o mesmo UID (proprietário) do script que está sendo executado. Verifica se o diretório que será afetado por esta operação tem o mesmo UID (proprietário) do script qur está sendo executado.
symlink() Verifica se o(s) arquivo(s) e/ou diretório(s) que serão afetados por esta operação tem o mesmo UID (proprietário) do script que está sendo executado. Verifica se o diretório que será afetado por esta operação tem o mesmo UID (proprietário) do script qur está sendo executado. (note: only the target is checked)
link() Verifica se o(s) arquivo(s) e/ou diretório(s) que serão afetados por esta operação tem o mesmo UID (proprietário) do script que está sendo executado. Verifica se o diretório que será afetado por esta operação tem o mesmo UID (proprietário) do script qur está sendo executado. (note: only the target is checked)
getallheaders() In safe mode, headers beginning with 'authorization' (case-insensitive) will not be returned. Warning: this is broken with the aol-server implementation of getallheaders()!
header() In safe mode, the uid of the script is added to the realm part of the WWW-Authenticate header if you set this header (used for HTTP Authentication).
PHP_AUTH variables In safe mode, the variables PHP_AUTH_USER, PHP_AUTH_PW, and PHP_AUTH_TYPE are not available in $_SERVER. Regardless, you can still use REMOTE_USER for the USER. (note: only affected since PHP 4.3.0)
highlight_file(), show_source() Verifica se o(s) arquivo(s) e/ou diretório(s) que serão afetados por esta operação tem o mesmo UID (proprietário) do script que está sendo executado. Verifica se o diretório que será afetado por esta operação tem o mesmo UID (proprietário) do script qur está sendo executado. (note: only affected since PHP 4.2.1)
parse_ini_file() Verifica se o(s) arquivo(s) e/ou diretório(s) que serão afetados por esta operação tem o mesmo UID (proprietário) do script que está sendo executado. Verifica se o diretório que será afetado por esta operação tem o mesmo UID (proprietário) do script qur está sendo executado. (note: only affected since PHP 4.2.1)
Any function that uses php4/main/fopen_wrappers.c ??


Capítulo 23. Utilizando o PHP na linha de comando

A partir versão 4.3, o PHP suporta um novo tipo SAPI (Server Application Programming Interface) chamado CLI que significa Command Line Interface. Como o próprio nome indica, essa SAPI tem foco no desenvolvimento de aplicações shell (ou no terminal/linha de comando) com o PHP. As diferenças entre a CLI SAPI e as outras SAPIs são detalhadas neste capítulo.

A CLI SAPI foi liberada primeiramente com o PHP 4.2.0, mas ainda em estágio experimental, sendo necessário ativá-la explicitamente com a opção --enable-cli durante o ./configure. Desde o PHP 4.0.3 a CLI SAPI não mais é experimental e é sempre compilada e instalada como o arquivo php (chamado php.exe no Windows), no formato binário executável.

Diferenças importantes das CLI SAPI comparada com outras SAPIs:

  • Diferentemente da CGI SAPI, nenhum header é impresso na saída.

    A CGI SAPI possui um meio de suprimir os headers HTTP, mas não há uma chave equivalente para ativá-los na CLI SAPI.

    A versão CLI é definida silenciosa por padrão. Mas a chave -q é mantida para compatibilidade, de forma que você possa utilizar scripts CGI antigos.

    Ela não altera o diretório de execução para o do script. (a chave -C também é mantida para compatibilidade).

    Mensagens de erro em texto simples (sem formatação HTML).

  • Estas são as diretivas do php.ini que são sobrescritas pela CLI SAPI porque não fazem sentido no ambiente shell:

    Tabela 23-1. Diretivas php.ini sobrescritas

    Diretiva Valor default CLI SAPI Comentários
    html_errors FALSE Pode ser bem difícil de ler mensagens de erro no seu shell quando elas estão embebidas dentro de tags HTML, por isso essa diretiva tem default para FALSE.
    implicit_flush TRUE Essa diretiva causa que qualquer saída gerada de um print(), echo() e semelhantes sejam imediatamente escritas para o output e não cacheadas em nenhum buffer. Você ainda pode usar o output buffering se você precisa atrasar ou manipular a saída padrão.
    max_execution_time 0 (unlimited) Devido as infinitas possibilidades da utilização do PHP em ambientes shell, tempo máximo de execução foi configurado para ilimitado. Enquanto aplicações escritas para web são geralmente executadas em poucos segundos, aplicações no shell tendem a ter um tempo de execução mais longo.
    register_argc_argv TRUE As variáveis globais do PHP $argc (número de argumentos passados para aplicação) e $argv (array com os argumentos atuais) são sempre presentes e preenchidos com os valores apropriados quando utilizando a CLI SAPI.

    Nota: Estas diretivas não podem ser inicializadas com outros valores do arquivo de configuração php.ini ou um arquivo personalizado (se informado). Esta limitação existe porque estes valores são aplicados depois que todos os arquivos de configuração são analisados. Entretanto, seus valores podem ser modificados durante a execução (o que pode não fazer sentido para todas elas, por exemplo, register_argc_argv).

  • Para facilicar a operação no ambiente shell, as seguintes constantes estão definidas:

    Tabela 23-2. Constantes específicas CLI

    Constante Descrição
    STDIN Um stream já aberto para o stdin. Isto economiza ter de abrí-lo com
    $stdin = fopen('php://stdin', 'r');
    STDOUT Um stream já aberto para o stdout. Isto economiza ter de abrí-lo com
    $stdout = fopen('php://stdout', 'w');
    STDERR Um stream já aberto para o stderr. Isto economiza ter de abrí-lo com
    $stderr = fopen('php://stderr', 'w');

    Considerando isso, você não precisará mais abrí-los, por exemplo o stderr você mesmo, mas simplesmente usar a constante em vez do recurso stream:
    php -r 'fwrite(STDERR, "stderr\n");'
    Você não precissa fechar explicitamente esses streams. Isto é realizado automaticamente pelo PHP.

  • A CLI SAPI não modifica o diretório de execução atual para o diretório onde o script é interpretado!

    Exemplo mostrando a diferença da CGI SAPI:
    <?php
        /* Nossa aplicação de teste */
        echo getcwd(), "\n";
    ?>

    Quando utilizando a versão CGI, a saída é
    $ pwd
    /tmp
    
    $ php-cgi -f outro_diretorio/test.php
    /tmp/outro_diretorio
    Isto mostra como o PHP modifica o diretório atual para aquela onde o script é executado.

    Utilizando a versão CLI SAPI:
    $ pwd
    /tmp
    
    $ php -f outro_diretorio/test.php
    /tmp
    E isto mostra a grande flexibilidade ferramentas shell em PHP.

    Nota: A CGI SAPI suporta o comportamento da CLI SAPI utilizando a chave -C quando de sua execução na linha de comando.

A lista de opções de linha de comando fornecidas pelo binário do PHP pode ser solicitada a qualquer tempo executando o PHP com a opção -h:
Usage: php [options] [-f] <file> [args...]
       php [options] -r <code> [args...]
       php [options] [-- args...]
  -s               Display colour syntax highlighted source.
  -w               Display source with stripped comments and whitespace.
  -f <file>        Parse <file>.
  -v               Version number
  -c <path>|<file> Look for php.ini file in this directory
  -a               Run interactively
  -d foo[=bar]     Define INI entry foo with value 'bar'
  -e               Generate extended information for debugger/profiler
  -z <file>        Load Zend extension <file>.
  -l               Syntax check only (lint)
  -m               Show compiled in modules
  -i               PHP information
  -r <code>        Run PHP <code> without using script tags <?..?>
  -h               This help

  args...          Arguments passed to script. Use -- args when first argument
                   starts with - or script is read from stdin

A CLI SAPI fornecer três maneiras diferentes para você executar seu código PHP:

  1. Chamando o PHP para executar um arquivo determinado.

    php my_script.php
    
    php -f my_script.php
    De ambas maneiras (utilizando ou não a opção -f) o arquivo informado my_script.php é executado. Você pode escolher qualquer arquivo para executar, seus scripts PHP não precisam terminar com a extensão .php, podendo ter qualquer nome ou extensão que você deseje.

  2. Passar o código PHP para execução diretamente a linha de comando.

    php -r 'print_r(get_defined_constants());'
    É preciso ter especial cuidado com a substituição de variáveis shell e delimitação de strings utilizada.

    Nota: Leia o exemplo cuidadosamente, observando que não há tags de abertura ou fechamento! A opção -r simplesmente não precisa delas. Utilizando-as você obterá erros de interpretação.

  3. Fornece código PHP para interpretação via a entrada padrão (stdin).

    Isto mostra a habilidade poderosa de como criar dinamicamente código PHP e fornecê-lo ao binário, como demonstrado neste exemplo (apenas demonstrativo):
    $ alguma_aplicacao | algum_filtro | php | sort -u >final_output.txt

Você não pode combinar nenhum das três maneiras para executar código.

Assim como qualquer aplicação shell, não somente o binário do PHP aceita um certo número de argumentos, mas também seu script PHP também pode recebê-los. O número de argumentos que podem ser passados para seu script não é limitado ao PHP (mas o shell tem um certo limite de tamanho em caracteres que podem ser informados, e não há um padrão para esse limite). Os argumentos passados para seu script são disponibilizados no array global $argv. No índice zero sempre conterá o nome do script (podendo ser - no caso de código PHP estar vindo da entrada padrão ou da opção de linha de comando -r). O segunda variável global $argc contém o número de elementos no array $argv (mas não o número de argumentos passados para seu script.

Os argumentos que você deseja passar para seu script não podem começar com o caracter - e isso não pode ser modificado. Passando argumentos para seu script que comecem com um - causará problemas porque o PHP tentará manuseá-los. Para prevenir isso, utilize o separador de argumentos --. Depois que os argumentos são interpretados pelo PHP, todos os argumentos restantes são repassados intocados para seu script.

# Isto não executará o código fornecido e irá fazer o PHP mostrar sua ajuda
$ php -r 'var_dump($argv);' -h
Usage: php [options] [-f] <file> [args...]
[...]

# Isto passará o argumento '-h' para seu script e prevenirá o PHP de usá-lo
$ php -r 'var_dump($argv);' -- -h
array(2) {
  [0]=>
  string(1) "-"
  [1]=>
  string(2) "-h"
}

Entretanto, há ainda uma outra maneira de se utilizar o PHP no shell. Você pode escrever um script que na primeira linha tenha #!/usr/bin/php e na seqüência tenha código PHP normal, incluindo as tags de início e fim e os atributos de execução do arquivo. Desta maneira ele pode ser executado como um script shell ou PERL normalmente:
#!/usr/bin/php
<?php
    var_dump($argv);
?>
Assumindo que o arquivo foi nomeado como teste e está no diretório atual, nós podemos fazer o seguinte:
$ chmod 755 teste
$ ./test -h -- foo
array(4) {
  [0]=>
  string(6) "./teste"
  [1]=>
  string(2) "-h"
  [2]=>
  string(2) "--"
  [3]=>
  string(3) "foo"
}
Como você viu, dessa forma não há problemas em passar parâmetros para seu script que comecem com o caracter -

Tabela 23-3. Opções de linha de comando

Opção Descrição
-s

Mostra o código fonte com destaque de cores.

Esta opção usa o mecanismo interno para interpretar o arquivo e produzir uma versão HTML do fonte com destaque de cores e a envia para a saída padrão. Note que ele somente gerará blocos de <code> [...] </code>, mas não headers HTML.

Nota: Esta opção não funciona juntamente com a opção -r.

-w

Mostra o fonte sem comentários e espaços em branco.

Nota: Esta opção não funciona juntamente com a opção -r.

-f

Interpreta e executa o arquivo informado com a opção -f Esta diretiva é opcional e pode ser deixada de lado. Informar somente o nome do arquivo para execução é suficiente.

-v

Imprime as versões o PHP, PHP SAPI e Zend para a saída padrão, por exemplo:
$ php -v
PHP 4.3.0-dev (cli), Copyright (c) 1997-2002 The PHP Group
Zend Engine v1.2.1, Copyright (c) 1998-2002 Zend Technologies

-c

Esta opção informa um diretório onde procurar pelo php.ini ou especifica um arquivo INI personalizado diretamente (não presisa ser obrigatoriamente php.ini), por exemplo:
$ php -c /custom/directory/ my_script.php

$ php -c /custom/directory/custom-file.ini my_script.php

-a

Executa o PHP no modo interativo.

-d

Esta opção permite definir um valor personalizado para qualquer diretiva de configuração permitida no php.ini. Sintaxe:
-d diretiva[=valor]

Examples:
# Omitindo a parte do valor irá configurar a diretiva para "1"
$ php -d max_execution_time -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(1) "1"

# Passando um valor vazio irá configurar a diretiva para ""
php -d max_execution_time= -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(0) ""

# A diretiva de configuração será preenchida com qualquer coisa informada depois do caracter =''
$  php -d max_execution_time=20 -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(2) "20"
$  php -d max_execution_time=instonaofazsentido -r '$foo = ini_get("max_execution_time"); var_dump($foo);'
string(15) "instonaofazsentido"

-e

Gera informações estendidas para o debugador/profiler.

-z

Carrega a extensão Zend. Se somente o nome de arquivo é fornecido, o PHP tenta carregar essa extensão do caminho default de bibliotecas do seu sistema (geralmente especificado em /etc/ld.so.conf em sistemas Linux). Passando um nome de arquivo com o caminho absoluto irá evitar a procura no caminho das bibliotecas de sistema. Um nome de arquivo com uma informação de diretório relativa fará com que o PHP apenas tente carregar a extensão no caminho relativo ao diretório atual.

-l

Esta opção fornece uma maneira conveniente apenas realizar uma checagem de sintaxe no código PHP fornecido. No sucesso, o texto No syntax errors detected in <arquivo> é impresso na saída padrão e informado o código de saida de sistema 0. Em caso de erro, o texto Errors parsing <filename> juntamente com o a mensagem do interpretador interno é impressa para a saída padrão e o código de saída de sistema é 255.

Esta opção não procura por erros fatais (como funções não definidas). Use -f se você deseja detectar erros fatais também.

Nota: Esta opção não trabalha com a opção -r

-m

Utilizando essa opção, o PHP imprime os módulos PHP e Zend compilados (e carregados):
$ php -m
[PHP Modules]
xml
tokenizer
standard
session
posix
pcre
overload
mysql
mbstring
ctype

[Zend Modules]

-i Esta opção de linha de comando chama a função phpinfo() e imprime seus resultados. Se o PHP não está funcionando bem, é interessante fazer um php -i para observar qualquer mensagem de erro impressa antes ou dentro das tabelas de informação. Como a saída é em HTML, ela é um pouco grande.
-r

Esta opção permite a execução de código PHP direto da linha de comando. As tags de início e fim do PHP (<?php e ?>) não são necessárias e causarão erros de interpretação.

Nota: Cuidados deverão ser tomados utilizando dessa forma para evitar que haja substituição de variáveis pelo shell.

Exemplo mostrando um erro de interpretação
$ php -r "$foo = get_defined_constants();"
Command line code(1) : Parse error - parse error, unexpected '='
O problema aqui decorre do sh/bash realizar substituições de variáveis sempre quando se utilizam aspas ("). Desde que a variável $foo não deve estar definida, ela é substituída por nada o que faz que o código passado para o PHP para execução seja:
$ php -r " = get_defined_constants();"
A maneira correta é utilizar apóstrofos ('). Variáveis em strings delimitadas por apóstrofos não são substituidas pelo sh/bash.
$ php -r '$foo = get_defined_constants(); var_dump($foo);'
array(370) {
  ["E_ERROR"]=>
  int(1)
  ["E_WARNING"]=>
  int(2)
  ["E_PARSE"]=>
  int(4)
  ["E_NOTICE"]=>
  int(8)
  ["E_CORE_ERROR"]=>
  [...]
Se você estiver utilizando um shell diferente do sh/bash, você pode experimentar comportamentos diferenciados. Sinta-se livre para abrir um aviso de bug ou enviar um e-mail para phpdoc@lists.php.net. Você vai rapidamente conseguir problemas quando tentar obter variáveis do ambiente dentro do código ou quando utilizar barras invertidas para escape. Esteja avisado.

-h Com essa opção, você pode obter informações sobre a lista atual de opções de linha de comando pequenas descrições sobre o que elas fazem.

O PHP executável pode ser utilizando para rodar scripts PHP absolutamente independente de um servidor web. Se você está num sistema Unix, você pode acrescentar uma linha especial na primeira linha de seu script e torná-lo executável, então o sistema operacional saberá que programa deverá rodar o script. Na plataforma Windows, você pode associar php.exe -q com o clique duplo em arquivos .php ou fazer um arquivo batch para rodar seus scripts através do PHP. A primeira linha acrescentada ao script nos Unix não funcionam no Windows, por isso você não pode escrever programas independentes de plataforma desse jeito. Um exemplo simples de como escrever um programa para a linha de comando segue abaixo:

Exemplo 23-1. Um script para rodar na linha de comando (script.php)

#!/usr/bin/php
<?php

if ($argc != 2 || in_array($argv[1], array('--help', '-help', '-h', '-?'))) {
?>

Este é um script de linha de comando com um parâmetro.

  Uso:
  <?php echo $argv[0]; ?> <opcao>

  <opcao> pode ser qualquer palavra que
  você queira imprimir. Com as opções --help, -help, -h
  ou -?, você pode obter essa ajuda.

<?php
} else {
    echo $argv[1];
}
?>

No script acima, nós utilizamos uma primeira linha especial para indicar que este arquivo precisa rodar pelo PHP. Como nós trabalhamos com a versão CLI aqui, não serão impressos headers HTTP. Há duas variáveis que você precisa conhecer para escrever aplicações em linha de comando com o PHP: $argc e $argv. O primeiro é o número de argumentos mais um (o nome do script executando). O segundo é um array contendo os argumentos, começando com o nome do script no índice zero ($argv[0]).

No programa acima é verificado se há apenas um argumento fornecido. Se o argumento for --help, -help, -h ou -?, é impresso uma mensagem de ajuda, imprimindo o nome do script dinamicamente. Qualquer outro argumento é exibido como informado.

Para rodar esse aplicativo nos Unix, basta torná-lo executável e o chamar diretamente como script.php exibaisso ou script.php -h. No Windows, você pode fazer um arquivo batch para esta tarefa:

Exemplo 23-2. Arquivo batch para rodar um script em linha de comando (script.bat)

@c:\php\php.exe script.php %1 %2 %3 %4

Assumindo que você nomeou o programa acima como script.php, e você tem um php.exe em c:\php\php.exe este arquivo batch irá rodar com os seguintes parâmetros: script.bat exibaisso ou script.bat -h.

Veja também a documentação da extensão Readline para mais funções que você pode usar para incrementar suas aplicações para linha de comando em PHP.

IV. Referência das Funções

Índice
I. Apache
II. Funções para manipulação de arrays
III. Aspell functions [deprecated]
IV. BCMath Funções Matemáticas de Precisão Arbitrária
V. Funções de compactação com Bzip2
VI. Calendar functions
VII. CCVS API Functions
VIII. COM support functions for Windows
IX. Classes e Objetos
X. ClibPDF functions
XI. Crack functions
XII. CURL, Client URL Library Functions
XIII. Cybercash payment functions
XIV. Crédit Mutuel CyberMUT functions
XV. Cyrus IMAP administration functions
XVI. Character type functions
XVII. Database (dbm-style) abstraction layer functions
XVIII. Funções data e hora
XIX. dBase functions
XX. DBM Functions [deprecated]
XXI. dbx functions
XXII. DB++ Functions
XXIII. Direct IO functions
XXIV. Diretórios
XXV. DOM XML functions
XXVI. .NET functions
XXVII. Error Handling and Logging Functions
XXVIII. FrontBase Functions
XXIX. filePro functions
XXX. Filesystem (Sistema de arquivos)
XXXI. Forms Data Format functions
XXXII. FriBiDi functions
XXXIII. FTP functions
XXXIV. Function Handling functions
XXXV. Gettext
XXXVI. GMP functions
XXXVII. HTTP functions
XXXVIII. Hyperwave functions
XXXIX. Hyperwave API functions
XL. iconv functions
XLI. Image functions
XLII. IMAP, POP3 and NNTP functions
XLIII. Informix functions
XLIV. InterBase functions
XLV. Ingres II functions
XLVI. IRC Gateway Functions
XLVII. PHP / Java Integration
XLVIII. LDAP functions
XLIX. Funções de E-Mail
L. mailparse functions
LI. Matemática e Trigonometria
LII. Multi-Byte String Functions
LIII. MCAL functions
LIV. Mcrypt Encryption Functions
LV. MCVE Payment Functions
LVI. Mhash - Funções de hash
LVII. Mimetype Functions
LVIII. Funções Microsoft SQL Server
LIX. Ming functions for Flash
LX. Funções de Miscelânea
LXI. mnoGoSearch Functions
LXII. mSQL functions
LXIII. MySQL
LXIV. Mohawk Software session handler functions
LXV. muscat functions
LXVI. Network Functions
LXVII. Ncurses terminal screen control functions
LXVIII. Lotus Notes functions
LXIX. Unified ODBC functions
LXX. Object Aggregation/Composition Functions
LXXI. Oracle 8 functions
LXXII. OpenSSL functions
LXXIII. Oracle functions
LXXIV. Ovrimos SQL functions
LXXV. Output Control Functions
LXXVI. Sobrecarga de propriedades e métodos de objetos
LXXVII. PDF functions
LXXVIII. Verisign Payflow Pro functions
LXXIX. PHP Options&Information
LXXX. POSIX functions
LXXXI. Funções para PostgreSQL
LXXXII. Process Control Functions
LXXXIII. Program Execution functions
LXXXIV. Printer functions
LXXXV. Pspell Functions
LXXXVI. GNU Readline
LXXXVII. GNU Recode functions
LXXXVIII. Regular Expression Functions (Perl-Compatible)
LXXXIX. qtdom functions
XC. Regular Expression Functions (POSIX Extended)
XCI. Semaphore, Shared Memory and IPC Functions
XCII. SESAM database functions
XCIII. Manejo de sessões
XCIV. Shared Memory Functions
XCV. Shockwave Flash functions
XCVI. SNMP functions
XCVII. Socket functions
XCVIII. Stream functions
XCIX. String functions
C. Funções Sybase
CI. Tokenizer functions
CII. Funções URL
CIII. Variable Functions
CIV. vpopmail functions
CV. W32api functions
CVI. WDDX Functions
CVII. XML parser functions
CVIII. XML-RPC functions
CIX. XSLT functions
CX. YAZ functions
CXI. YP/NIS Functions
CXII. Zip File Functions (Read Only Access)
CXIII. Funções de Compressão Zlib

I. Apache

Introdução

Estas funções estão somente disponíveis com o PHP rodando como módulo do Apache 1.x.


Instalação

Para instalar o PHP no Apache 1.x, veja a seção Apache no capítulo de instalação.


Configuração durante execução

O comportamento do módulo PHP sob o Apache é afetado pelas configurações no php.ini. As diretivas de configuração no php.ini podem ser sobrescritas por diretivas php_flag no arquivo de configuração do servidor ou por arquivos .htaccess locais.

Exemplo 1. Desligando a interpretação do PHP em um diretório com o .htaccess

php_flag engine off

Tabela 1. Opções de configuração no Apache

Nome Valor Default Alterabilidade Descrição
engine On PHP_INI_ALL liga ou desliga a interpretação pelo PHP
child_terminate Off PHP_INI_ALL especifica se os scripts PHP podem solicitar a eliminação do processo filho no final da requisição. Detalhes na função apache_child_terminate()
last_modified Off PHP_INI_ALL envia a data de modificação do script PHP como um header Last-Modified:
xbit_hack Off PHP_INI_ALL interpreta arquivos marcados executáveis como scripts PHP, independentemente do final do arquivo

Descrição resumida das diretivas de configuração.

engine boolean

Esta diretiva somente é útil para a versão módulo do Apache do PHP. Ela pode ser usada para ligar ou desligar a interpretação do PHP em nível de diretório ou em nível de servidor virtual. Colocando engine off nos lugares apropriados do arquivo httpd.conf, o PHP pode ser ativado ou desativado.


Tipos Resource

Esta extensão não possui nenhum tipo resource.


Constantes Predefinidas

Esta extensão não possui nenhuma constante.

Índice
apache_child_terminate -- Finaliza o processo Apache depois da requisição
apache_lookup_uri --  Realiza uma requisição parcial para a URI especificada e retorna todas as informações sobre ela
apache_note -- Obtém e seta notas de requisição
apache_request_headers -- Obtem todos os headers HTTP
apache_response_headers --  Obtêm todos os headers da resposta HTTP
apache_setenv -- Configura uma variável no ambiente do sub processo Apache
ascii2ebcdic -- Converte uma string de ASCII para EBCDIC
ebcdic2ascii -- Converte uma string de EBCDIC para ASCII
getallheaders -- Obtem todos os headers HTTP
virtual -- Realiza uma sub-requisição no Apache

apache_child_terminate

(PHP 4 >= 4.0.5)

apache_child_terminate -- Finaliza o processo Apache depois da requisição

Descrição

bool apache_child_terminate ( void)

apache_child_terminate() registrará o processo Apache executando a requisição atual do PHP para finalização quando a execução do código PHP terminar. Isto pode se utilizado para terminar um processo depois que um script que tiver um alto consumo de memória for rodado e quando essa memória normalmente só é liberada internamente, mas não é devolviva para o sistema operacional.

Nota: A disponibilidade desse recurso é controlado pela diretiva php.ini apache.child_terminate, que está definida off por default.

Este recurso não está disponível em versões multi-thread do Apache, como a versão para Windows 32 bits.

Veja também exit().

apache_lookup_uri

(PHP 3>= 3.0.4, PHP 4 )

apache_lookup_uri --  Realiza uma requisição parcial para a URI especificada e retorna todas as informações sobre ela

Descrição

object apache_lookup_uri ( string filename)

Isto realiza uma requisição parcial para uma URI. Trabalha o suficiente para obter todas as informações importantes sobre o recurso dado e retorna esta informação em uma classe. As propriedades da classe retornada são:

status
the_request
status_line
method
content_type
handler
uri
filename
path_info
args
boundary
no_cache
no_local_copy
allowed
send_bodyct
bytes_sent
byterange
clength
unparsed_uri
mtime
request_time

Nota: apache_lookup_uri() somente funciona quando o PHP está instalado como um módulo do Apache.

apache_note

(PHP 3>= 3.0.2, PHP 4 )

apache_note -- Obtém e seta notas de requisição

Descrição

string apache_note ( string note_name [, string note_value])

apache_note() é uma função específica do Apache que obtém e seta valores em uma tabela de notas de requisição. Se for chamada com um argumento, ela retorna o valor atual da nota note_name. Se for chamada com dois argumentos, ela seta o valor da nota note_name para note_value e retorna o valor anterior da nota note_name.

apache_request_headers

(PHP 4 >= 4.3.0)

apache_request_headers -- Obtem todos os headers HTTP

Descrição

array apache_request_headers ( void)

apache_request_headers() retorna um array associativo de todos os headers HTTP da requisição atual. Ela é somente suportada se o PHP roda como um módulo do Apache.

Nota: Antes do PHP 4.3.0, apache_request_headers() era chamado getallheaders(). Depois do PHP 4.3.0, getallheaders() é um sinônimo para apache_request_headers().

Exemplo 1. Exemplo apache_request_headers()

<?php
$headers = apache_request_headers();

foreach ($headers as $header => $value) {
    echo "$header: $value <br />\n";
}
?>

Nota: Você também pode obter o valor das variáveis CGI comuns lendo-as a partir do ambiente, o que funciona caso esteja ou não utilizando o PHP como módulo do Apache. Faça um phpinfo() para ver uma lista dessas variáveis chamadas variáveis ambiente.

apache_response_headers

(PHP 4 >= 4.3.0)

apache_response_headers --  Obtêm todos os headers da resposta HTTP

Descrição

array apache_response_headers ( void)

Retorna um array com todos os headers de resposta do Apache. Esta funcionalidade foi acrescentada a partir do PHP 4.3.0.

Veja também getallheaders() e headers_sent().

apache_setenv

(PHP 4 >= 4.2.0)

apache_setenv -- Configura uma variável no ambiente do sub processo Apache

Descrição

int apache_setenv ( string variable, string value [, bool walk_to_top])

Atenção

Esta função não está documentada, somente a lista de argumentos está disponível.

ascii2ebcdic

(PHP 3>= 3.0.17)

ascii2ebcdic -- Converte uma string de ASCII para EBCDIC

Descrição

int ascii2ebcdic ( string ascii_str)

ascii2ebcdic() é uma função específica do Apache, somente disponível em sistemas operacionais baseados no EBCDIC (OS/390, BS2000). Ela converte a string codificada em ASCII ascii_str em sua representação equivalente em EBCDIC (binary safe), retornando o resultado.

Veja também a função inversa ebcdic2ascii()

ebcdic2ascii

(PHP 3>= 3.0.17)

ebcdic2ascii -- Converte uma string de EBCDIC para ASCII

Description

int ebcdic2ascii ( string ebcdic_str)

ebcdic2ascii() é uma função específica do Apache, somente disponível em sistemas operacionais baseados no EBCDIC (OS/390, BS2000). Ela converte a string codificada em EBCDIC ebcdic_str em sua representação equivalente em ASCII (binary safe), retornando o resultado.

Veja também a função inversa ascii2ebcdic()

getallheaders

(PHP 3, PHP 4 )

getallheaders -- Obtem todos os headers HTTP

Descrição

array getallheaders ( void)

getallheaders() é um sinônimo para apache_request_headers(). Ela retorna um array associativo de todos os headers HTTP da requisição atual. Veja a documentação de apache_request_headers() para mais detalhes do funcionamento dessa função.

Nota: No PHP 4.3.0, getallheaders() se tornou um apelido de apache_request_headers(). Essencialmente, ela foi renomeada. Isto porque a função somente funciona quando o PHP é compilado com um módulo do Apache.

Veja também apache_request_headers().

virtual

(PHP 3, PHP 4 )

virtual -- Realiza uma sub-requisição no Apache

Descrição

int virtual ( string filename)

virtual() é uma função específica do Apache que é equivalente a <!--#include virtual...--> no mod_include. Ela realiza uma sub-requisição do Apache. Ela é útil para incluir scripts de CGI ou arquivos .shtml, ou qualquer outra coisa que você possa analisar através do Apache. Note que para um script CGI, o script precisa gerar um cabeçalho CGI válido. Isto significa que, no mínimo, ele precisa gerar um cabeçalho Content-type. Para arquivos PHP, você precisa usar include() ou require(). virtual() não pode ser usado para incluir um documento que é um arquivo PHP.

Para executar a sub-requisição, todos osbuffer são finalizados e enviados para o browser. Headers pendentes são enviados também.

II. Funções para manipulação de arrays

Introdução

Essas funções permitem a interação e manipulação de arrays de várias formas. Arrays são essenciais para armazenar, gerenciar, operar sobre um conjunto de variáveis.

Arrays simples e multidimensionais (matrizes) são suportados, e podem ser criados pelo usuário ou por outras funções. Existem diversas funções específicas para bancos de dados para preencher arrays com os dados retornados em consultas, e vários outros tipos de funções também retornam arrays.

Por favor, veja a seção Arrays do manual para uma explicação mais detalhada sobre como arrays são implementados e utilizados no PHP.


Requisitos

Nenhuma biblioteca externa é necessária para compilar esta extensão.


Instalação

Não há nenhuma instalação nescessária para utilizar estas funções, elas fazem parte do núcleo do PHP.


Configuração durante execução

Esta extenção não define nenhum parâmetro de configuração no php.ini.


Tipos Resource

Esta extensão não possui nenhum tipo resource.


Constantes Predefinidas

As constantes listadas abaixo estão sempre disponíveis como parte do núcleo do PHP.

CASE_LOWER (integer)

CASE_LOWER é usada com a função array_change_key_case() e é usada em chaves de arrays para torná-las minúsculas. É o valor padrão utilizado em array_change_key_case().

CASE_UPPER (integer)

CASE_UPPER é usada com a função array_change_key_case() e é usada em chaves de arrays para torná-las maiúsculas.

Sinais de ordenação:

SORT_ASC (integer)

SORT_ASC é usada com array_multisort() para ordenar em ordem crescente.

SORT_DESC (integer)

SORT_DESC é usada com array_multisort() para ordenar em ordem descrescente

Sinais de tipos de ordenação: usadas por várias funções de ordenação

SORT_REGULAR (integer)

SORT_REGULAR é usada para comparar itens normalmente.

SORT_NUMERIC (integer)

SORT_NUMERIC é usada para comparar itens numericamente.

SORT_STRING (integer)

SORT_STRING é usada para comparar itens como se fossem strings.


Veja Também

Veja também is_array(), explode(), implode(), split(), preg_split() e join().

Índice
array_change_key_case -- Retorna um array com todas as chaves string em maiúsculo ou minúsculo
array_chunk -- Divide um array em pedaços
array_count_values -- Conta as frequências de cada valor de um array
array_diff_assoc -- Computes the difference of arrays with additional index check
array_diff -- Analisa as diferenças entre arrays
array_fill -- Preenche um array com valores
array_filter --  Filtra os elementos de um array utilizando uma função
array_flip -- Inverte as relações entre chaves e valores
array_intersect_assoc -- Computes the intersection of arrays with additional index check
array_intersect -- Calcula a interseção entre arrays
array_key_exists -- Checa se uma chave ou índice existe em um array
array_keys -- Retorna todas as chaves de um array
array_map --  Aplica uma função em todos os elementos dos arrays dados
array_merge_recursive -- Funde dois ou mais arrays recursivamente
array_merge -- Funde dois ou mais arrays
array_multisort -- Ordena múltiplos arrays ou arrays multi-dimensionais
array_pad --  Expande um array para um certo comprimento utilizando um determinado valor
array_pop -- Retira um elemento do final do array
array_push --  Adiciona um ou mais elementos no final de um array
array_rand --  Retorna um ou mais elementos aleatórios de um array
array_reduce --  Reduz um array para um único valor através de um processo iterativo utilizando uma função.
array_reverse --  Retorna um array com os elementos na ordem inversa
array_search --  Procura por um valor em um array e retorna sua chave correspondente caso seja encontrado
array_shift --  Retira o primeiro elemento de um array
array_slice -- Extrai uma parcela de um array
array_splice --  Remove uma parcela do array e substitui com outros elementos
array_sum --  Calcula a soma dos elementos de um array
array_unique -- Remove o valores duplicados de um array
array_unshift --  Adiciona um ou mais elementos no início de um array
array_values -- Retorna todos os valores de um array
array_walk --  Aplica uma determinada funcão em cada elemento de um array
array --  Cria um array
arsort --  Ordena um array em ordem descrescente mantendo a associação entre índices e valores
asort --  Ordena um array mantendo a associação entre índices e valores
compact --  Cria um array contendo variáveis e seus valores
count -- Conta o número de elementos de uma variável
current -- Retorna o elemento corrente em um array
each --  Retorna o par chave/valor corrente de um array e avança o seu cursor
end --  Faz o ponteiro interno de um array apontar para o seu último elemento
extract --  Importa variáveis para a tabela de símbolos a partir de um array
in_array -- Retorna TRUE se um valor existe no array
key -- Retorna uma chave de um array associativo
krsort -- Ordena um array pelas chaves em ordem descrescente
ksort -- Ordena um array pelas chaves
list --  Cria variáveis como se fossem arrays
natcasesort --  Ordena um array utilizando o algoritmo da "ordem natural" sem diferenciar maiúsculas e minúsculas
natsort --  Ordena um array utilizando o algoritmo da "ordem natural"
next --  Avança o ponteiro interno de um array
pos -- Retorna o elemento atual do array
prev -- Retrocede o ponteiro interno de um array
range --  Cria um array contendo uma faixa de elementos
reset --  Faz o ponteiro interno de um array apontar para o seu primeiro elemento
rsort -- Ordena um array em ordem descrescente
shuffle -- Mistura os elementos de um array
sizeof -- Retorna o número de elementos de uma variável
sort -- Ordena um array
uasort --  Ordena um array utilizando uma função de comparação definida pelo usuário e mantendo as associações entre chaves e valores
uksort --  Ordena um array pelas chaves utilizando uma função de comparação definida pelo usuário.
usort --  Ordena um array pelos valores utilizando uma função de comparação definida pelo usuário

array_change_key_case

(PHP 4 >= 4.2.0)

array_change_key_case -- Retorna um array com todas as chaves string em maiúsculo ou minúsculo

Descrição

array array_change_key_case ( array input [, int case])

array_change_key_case() altera as chaves chaves do array input para maiúsculo ou minúsculo. A mudança depende do último parâmetro (opcional) case. Você pode passar duas constantes para ele, CASE_UPPER e CASE_LOWER. O padrão é CASE_LOWER. Essa função deixará os índices numéricos inalterados.

Exemplo 1. Exemplo de array_change_key_case()

$input_array = array("primeiRo" => 1, "segunDo" => 4);
print_r(array_change_key_case($input_array, CASE_UPPER);

A saída deste programa será:
Array
(
    [PRIMEIRO] => 1
    [SEGUNDO] => 2
)

array_chunk

(PHP 4 >= 4.2.0)

array_chunk -- Divide um array em pedaços

Descrição

array array_chunk ( array input, int size [, bool preserve_keys])

array_chunk() divide um array em diversos arrays tendo como tamanho o valor de size. Você provavelmente terá um array com menos valores no final. Serão gerados arrays como membros de um array multidimensional com índices numéricos começando de 0 (zero).

Passando o valor TRUE para o parâmetro opcional preserve_keys, pode-se forçar a preservação das chaves do array original. Se for passado o valor FALSE, novos índices numéricos serão gerados em cada array resultante começando de 0 (zero). O padrão é FALSE.

Exemplo 1. Exemplo de array_chunk()

$input_array = array('a', 'b', 'c', 'd', 'e');
print_r(array_chunk($input_array, 2));
print_r(array_chunk($input_array, 2, TRUE));

A saída deste programa será:
Array
(
    [0] => Array
        (
            [0] => a
            [1] => b
        )

    [1] => Array
        (
            [0] => c
            [1] => d
        )

    [2] => Array
        (
            [0] => e
        )

)
Array
(
    [0] => Array
        (
            [0] => a
            [1] => b
        )

    [1] => Array
        (
            [2] => c
            [3] => d
        )

    [2] => Array
        (
            [4] => e
        )

)

array_count_values

(PHP 4 )

array_count_values -- Conta as frequências de cada valor de um array

Descrição

array array_count_values ( array input)

array_count_values() retorna um array utilizando os valores do array input como chaves e seus respectivos números de ocorrências como valores.

Exemplo 1. Exemplo de array_count_values()

$array = array (1, "ola", 1, "mundo", "ola");
array_count_values ($array);

Array
(
    [1] => 2
    [ola] => 2
    [mundo] => 1
)

array_diff_assoc

(PHP 4 >= 4.3.0)

array_diff_assoc -- Computes the difference of arrays with additional index check

Description

array array_diff_assoc ( array array1, array array2 [, array ...])

array_diff_assoc() returns an array containing all the values from array1 that are not present in any of the other arguments. Note that the keys are used in the comparison unlike array_diff().

Exemplo 1. array_diff_assoc() example

<?php
$array1 = array ("a" => "green", "b" => "brown", "c" => "blue", "red");
$array2 = array ("a" => "green", "yellow", "red");
$result = array_diff_assoc ($array1, $array2);

/* The result is:
Array
(
    [b] => brown
    [c] => blue
    [0] => red
)
*/
?>

In our example above you see the "a" => "green" pair is present in both arrays and thus it is not in the ouput from the function. Unlike this, the pair 0 => "red" is in the ouput because in the second argument "red" has key which is 1.

Two values from key => value pairs are considered equal only if (string) $elem1 === (string) $elem2 . In other words a strict check takes place so the string representations must be the same.

Nota: Please note that this function only checks one dimension of a n-dimensional array. Of course you can check deeper dimensions by using, for example, array_diff_assoc($array1[0], $array2[0]);.

See also array_diff(), array_intersect(), and array_intersect_assoc().

array_diff

(PHP 4 >= 4.0.1)

array_diff -- Analisa as diferenças entre arrays

Descrição

array array_diff ( array array1, array array2 [, array ...])

array_diff() retorna um array contendo todos os valores de array1 que não estão presentes em nenhum dos outros argumentos. Note que as chaves são preservadas.

Exemplo 1. Exemplo de array_diff()

$array1 = array ("a" => "verde", "vermelho", "azul", "vermelho");
$array2 = array ("b" => "verde", "amarelo", "vermelho");
$result = array_diff ($array1, $array2);

O exemplo acima faz com que $result seja array ("azul");. Ocorrências multiplas em $array1 são tratados da mesma forma.

Nota: Dois elementos são considerados iguais se, e somente se, (string) $elem1 === (string) $elem2. Em palavras: quando a representação em string é a mesma.

Nota: Note que esta função faz compara apenas uma dimensão de um array com dimensão n. Mas, obviamente, você pode comparar outras dimensões usando array_diff($array1[0], $array2[0]);.

Atenção

Não estava funcionando no PHP 4.0.4!

Veja também array_intersect().

array_fill

(PHP 4 >= 4.2.0)

array_fill -- Preenche um array com valores

Descrição

array array_fill ( int start_index, int num, mixed value)

array_fill() preenche um array com o número de entradas igual a num com o valor do parâmetro value, e chaves começando a partir de start_index.

Exemplo 1. Exemplo de array_fill()

$a = array_fill(5, 6, 'banana');

/*
$a agora tem os seguintes valores:

$a[5]  = "banana";
$a[6]  = "banana";
$a[7]  = "banana";
$a[8]  = "banana";
$a[9]  = "banana";
$a[10] = "banana";
*/

array_filter

(PHP 4 >= 4.0.6)

array_filter --  Filtra os elementos de um array utilizando uma função

Descrição

array array_filter ( array input [, mixed callback])

array_filter() retorna um array contendo todos os elementos do array input filtrados de acordo com uma função aplicada. Se o array input for associativo, as chaves são preservadas.

Exemplo 1. Exemplo de array_filter()

function impar($var) {
    return ($var % 2 == 1);
}

function par($var) {
    return ($var % 2 == 0); 
}

$array1 = array ("a" => 1, "b" => 2, "c" => 3, "d" => 4, "e" => 5);
$array2 = array (6, 7, 8, 9, 10, 11, 12);

echo "Impares: \n";
print_r(array_filter($array1, "impar"));
echo "Pares: \n";
print_r(array_filter($array2, "par"));

A saída deste programa seria:
Impares:
Array
(
    [a] => 1
    [c] => 3
    [e] => 5
)
Pares:
Array
(
    [0] => 6
    [2] => 8
    [4] => 10
    [6] => 12
)

As funções utilizadas por array_filter() não devem alterar os valores do array.. Por exemplo, adicionar ou remover um elemento, pode apagar o array ao qual está sendo aplicada array_filter(). Se este array for alterado, o comportamento desta função se torna imprevisvel.

Veja também array_map() e array_reduce().

array_flip

(PHP 4 )

array_flip -- Inverte as relações entre chaves e valores

Descrições

array array_flip ( array trans)

array_flip() retorna um array com com a relação entre suas chaves e valores invertida, ou seja, as chaves de trans passam a ser os valores e os valores de trans passam a ser as chaves.

Note que os valores de trans devem ser chaves válidas, ou seja, eles precisam ser inteiros não negativos ou string. Um aviso será mostrado se um valor é de um tipo inválido para chaves, e o par chave/valor em questão não será invertido.

Se um valor tem várias ocorrências, a última chave será usada como valor, e todos os outros serão perdidos.

array_flip() retorna FALSE se falhar.

Exemplo 1. Exemplo de array_flip()

$trans = array_flip ($trans);
$original = strtr ($str, $trans);

Exemplo 2. Exemplo de array_flip() : colisão

$trans = array ("a" => 1, "b" => 1, "c" => 2);
$trans = array_flip ($trans);
print_r($trans);

Agora $trans é:
Array
(
    [1] => b
    [2] => c
)

array_intersect_assoc

(PHP 4 >= 4.3.0)

array_intersect_assoc -- Computes the intersection of arrays with additional index check

Description

array array_intersect_assoc ( array array1, array array2 [, array ...])

array_intersect_assoc() returns an array containing all the values of array1 that are present in all the arguments. Note that the keys are used in the comparison unlike in array_intersect().

Exemplo 1. array_intersect_assoc() example

<?php
$array1 = array ("a" => "green", "b" => "brown", "c" => "blue", "red");
$array2 = array ("a" => "green", "yellow", "red");
$result_array = array_intersect_assoc ($array1, $array2);

/* $result_array will look like:

Array
(
    [a] => green
)

*/
?>

In our example you see that only the pair "a" => "green" is present in both arrays and thus is returned. The value "red" is not returned because in $array1 it's key is 2 while the key of "red" in $array2 it is 1.

The two values from the key => value pairs are considered equal only if (string) $elem1 === (string) $elem2 . In otherwords a strict type check is executed so the string representation must be the same.

See also array_intersect(), array_diff() and array_diff_assoc().

array_intersect

(PHP 4 >= 4.0.1)

array_intersect -- Calcula a interseção entre arrays

Descrição

array array_intersect ( array array1, array array2 [, array ...])

array_intersect() retorna um array contendo todos os valores de array1 que estão presentes nos outros argumentos. Note que as chaves são preservadas.

Exemplo 1. Exemplo de array_intersect()

$array1 = array ("a" => "verde", "vermelho", "azul");
$array2 = array ("b" => "verde", "amarelo", "vermelho");
$result = array_intersect ($array1, $array2);

Isso faz com que $result tenha
Array
(
    [a] => verde
    [0] => vermelho
)

Nota: Dois elementos são considerados iguais se, e somente se, (string) $elem1 === (string) $elem2. Em palavras: quando a representação em string é a mesma.

Atenção

Essa função não funcionava no PHP 4.0.4!

Veja também array_diff().

array_key_exists

(PHP 4 >= 4.1.0)

array_key_exists -- Checa se uma chave ou índice existe em um array

Descrição

bool array_key_exists ( mixed key, array search)

array_key_exists() retorna TRUE se a chave key existe no array. key pode ser qualquer valor possível para uma chave de array.

Exemplo 1. Exemplo de array_key_exists()

$busca_array = array("primeiro" => 1, "segundo" => 4);
if (array_key_exists("primeiro", $busca_array)) {
    echo "O elemento 'primeiro' está no array!";
}

Nota: O nome dessa função é key_exists() no PHP versão 4.0.6.

Veja também isset().

array_keys

(PHP 4 )

array_keys -- Retorna todas as chaves de um array

Descrição

array array_keys ( array input [, mixed search_value])

array_keys() retorna as chaves, numéricas e string, do array input.

Se o parâmetro opcional search_value for especificado, então apenas as chaves para esse valor serão retornadas. Do contrário, todas as chaves de input serão retornadas.

Exemplo 1. Exemplo de array_keys()

$array = array (0 => 100, "cor" => "vermelho");
print_r(array_keys ($array));

$array = array ("azul", "vermelho", "verde", "azul", "azul");
print_r(array_keys ($array, "azul")); 

$array = array ("cor" => array("azul", "vermelho", "verde"), "tamanho" => array("pequeno", "medio", "grande"));
print_r(array_keys ($array));

A saída deste programa seria:
Array
(
    [0] => 0
    [1] => cor
)
Array
(
    [0] => 0
    [1] => 3
    [2] => 4
)
Array
(
    [0] => cor
    [1] => tamanho
)

Nota: Essa função adicionada no PHP 4. Abaixo está uma implementação para aqueles que ainda usam PHP 3.

Exemplo 2. Implementação de array_keys() para usuários do PHP 3

function array_keys ($arr, $term="") {
    $t = array();
    while (list($k,$v) = each($arr)) {
        if ($term && $v != $term) {
            continue;
            $t[] = $k;
        }
        return $t;
    }
}

Veja também array_values().

array_map

(PHP 4 >= 4.0.6)

array_map --  Aplica uma função em todos os elementos dos arrays dados

Descrição

array array_map ( mixed callback, array arr1 [, array arr2...])

array_map() retorna um array contendo todos os elementos de arr1 depois de aplicada uma determinada função em cada um. O número de parâmetros que esta função aceita deve coincidir com o número de arrays passados para a array_map()

Exemplo 1. Exemplo de array_map()

<?php
function cubo($n) {
    return $n*$n*$n;
}

$a = array(1, 2, 3, 4, 5);
$b = array_map("cubo", $a);
print_r($b);
?>

E programa acima faz com que $b tenha:
Array
(
    [0] => 1
    [1] => 8
    [2] => 27
    [3] => 64
    [4] => 125
)

Exemplo 2. array_map() - usando mais de um array

<?php
function mostrar_Espanhol($n, $m) {
    return "O número $n é chamado de $m na Espanha";
}

function map_Espanhol($n, $m) {
    return array ($n => $m);
}

$a = array(1, 2, 3, 4, 5);
$b = array("uno", "dos", "tres", "cuatro", "cinco");

$c = array_map("mostrar_Espanhol", $a, $b);
print_r($c);

$d = array_map("map_Espanhol", $a , $b);
print_r($d);
?>

Resultará em:
// Saída de $c
Array
(
    [0] => O número 1 é chamado de uno na Espanha
    [1] => O número 2 é chamado de dos na Espanha
    [2] => O número 3 é chamado de tres na Espanha
    [3] => O número 4 é chamado de cuatro na Espanha
    [4] => O número 5 é chamado de cinco na Espanha
)

// Saída de $d
Array
(
    [0] => Array
        (
            [1] => uno
        )

    [1] => Array
        (
            [2] => dos
        )

    [2] => Array
        (
            [3] => tres
        )

    [3] => Array
        (
            [4] => cuatro
        )

    [4] => Array
        (
            [5] => cinco
        )

)

Normalmente quando se usa dois ou mais arrays, eles devem ter o mesmo tamanho porque a função callback é aplicada paralelamente nos elementos correpondentes. Se os arrays tem tamanhos diferentes, o menor array será extendido com elementos vazios.

Uma forma interessante de se usar esta função é na construção de um array de arrays, o que pode ser facilmente feito usando NULL como o nome da função callback.

Exemplo 3. Criando um array de arrays

<?php
$a = array(1, 2, 3, 4, 5);
$b = array("um", "dois", "tres", "quatro", "cinco");
$c = array("uno", "dos", "tres", "cuatro", "cinco");

$d = array_map(null, $a, $b, $c);
print_r($d);
?>

A saída do programa acima seria:
Array
(
    [0] => Array
        (
            [0] => 1
            [1] => one
            [2] => uno
        )

    [1] => Array
        (
            [0] => 2
            [1] => two
            [2] => dos
        )

    [2] => Array
        (
            [0] => 3
            [1] => three
            [2] => tres
        )

    [3] => Array
        (
            [0] => 4
            [1] => four
            [2] => cuatro
        )

    [4] => Array
        (
            [0] => 5
            [1] => five
            [2] => cinco
        )

)

Veja também array_filter(), array_reduce() e array_walk().

array_merge_recursive

(PHP 4 >= 4.0.1)

array_merge_recursive -- Funde dois ou mais arrays recursivamente

Descrição

array array_merge_recursive ( array array1, array array2 [, array ...])

array_merge_recursive() funde os elementos de dois ou mais arrays de forma que os elementos de um são colocados no final do array anterior. Retorna o array resultante da fusão.

Se os arrays dados tem as mesmas chaves string, então os valores para uma chave são fundidos em um array, e isso é feito recursivamente, sendo que, se um dos valores for um array também, este função irá fundi-lo com os valores correspondentes no array resultante também. Se, no entanto, os arrays tem as mesmas chaves numéricas, o último valor para uma chave não sobrescreverá o valor original, e sim adicionado ao array resultante.

Exemplo 1. Exemplo de array_merge_recursive()

$ar1 = array ("cor" => array ("favorita" => "vermelho"), 5);
$ar2 = array (10, "cor" => array ("favorita" => "verde", "azul"));
$result = array_merge_recursive ($ar1, $ar2);

Neste caso $result será:
Array
(
    [color] => Array
        (
            [favorita] => Array
                (
                    [0] => vermelho
                    [1] => verde
                )

            [0] => azul
        )

    [0] => 5
    [1] => 10
)

Veja também array_merge().

array_merge

(PHP 4 )

array_merge -- Funde dois ou mais arrays

Descrição

array array_merge ( array array1, array array2 [, array ...])

array_merge() funde os elementos dois ou mais arrays de forma que os elementos de um são colocados no final do array anterior. Retorna o array resultante da fusão.

Se os arrays dados têm as mesmas chaves string, então o último valor para uma chave irá sobrescrever o valor anterior. Se, no entanto, os arrays tem as mesmas chaves numéricas, o último valor para uma chave não sobrescreverá o valor original, e sim adicionado ao array resultante.

Exemplo 1. Exemplo de array_merge()

$array1 = array ("cor" => "vermelho", 2, 4);
$array2 = array ("a", "b", "cor" => "verde", "forma" => "trapezoide", 4);
$result = array_merge ($array1, $array2);

Neste caso $result será:
Array
(
    [cor] => verde
    [0] => 2
    [1] => 4
    [2] => a
    [3] => b
    [forma] => trapezoide
    [4] => 4
)

Exemplo 2. Exemplo simples de array_merge()

$array1 = array();
$array2 = array(1 => "data");
$result = array_merge($array1, $array2);

Não esqueça que as chaves numéricas serão reordenadas!
Array
(
    [0] => data
)

Se você quer preservar os arrays e apenas concatená-los, o operador +:
$array1 = array();
$array2 = array(1 => "data");
$result = $array1 + $array2;
As chaves numéricas serão preservadas e as associações originais permanecem.
Array
(
    [1] => data
)

Nota: Chaves coincidentes serão sobrescritas usando as regras de primeira ocorrência.

Veja também array_merge_recursive().

array_multisort

(PHP 4 )

array_multisort -- Ordena múltiplos arrays ou arrays multi-dimensionais

Descrição

bool array_multisort ( array ar1 [, mixed arg [, mixed ... [, array ...]]])

array_multisort() pode ser usada para ordenar vários arrays de uma vez ou apenas um array multi-dimensional de acordo com uma das dimensões. A associação entre chaves e valores é mantida.

Os arrays dados são tratados como colunas de uma tabela a ser classificada pelas linhas - isso lembra a funcionalidade da cláusula ORDER BY da SQL. O primeiro array é o principal na ordenação. As linhas (valores) no primeiro array serve de base para a ordenação do próximo, e assim por diante.

A estrutura de argumentos dessa função não é muito normal, mas bastante flexível. O primeiro argumento de todos deve ser um array. Subsequentemente, cada argumento pode ser um array ou um dos sinais de classificação da lista a seguir.

Sinais de ordem de classificação:

  • SORT_ASC - classifica na ordem crescente

  • SORT_DESC - classifica na ordem descrescente

Sinais de tipos de ordenação:

  • SORT_REGULAR - compara os elementos normalmente

  • SORT_NUMERIC - compara os elementos como itens numéricos

  • SORT_STRING - compara os elementos como strings

Não podem existir dois sinais de ordenação do mesmo tipo especificados para um mesmo array. Os sinais de ordenação especificados depois de um array se aplicam apenas para esse array - a eles são atribuídos por padrão os valores SORT_ASC e SORT_REGULAR depois de cada novo argumento do tipo array.

Retorna TRUE em caso de sucesso ou FALSE em falhas.

Exemplo 1. Ordenando múltiplos arrays

$ar1 = array ("10", 100, 100, "a");
$ar2 = array (1, 3, "2", 1);
array_multisort ($ar1, $ar2);

Nesse exemplo, depois da ordenação, o primeiro array terá 10, "a", 100, 100. O segundo conterá 1, 1, "2", 3. Os elementos do segundo array que correpondem aos do primeiro (100 e 100) também foram ordenados.

Exemplo 2. Ordenando um array multi-dimensional

$ar = array (array ("10", 100, 100, "a"), array (1, 3, "2", 1));
array_multisort ($ar[0], SORT_ASC, SORT_STRING, 
                 $ar[1], SORT_NUMERIC, SORT_DESC);

Nesse exemplo, depois da ordenação, o primeiro array terá 10, 100, 100, "a" (foi ordenado como strings em ordem crescente), e o segundo conterá 1, 3, "2", 1 (classificado como números, em ordem descrescente).

array_pad

(PHP 4 )

array_pad --  Expande um array para um certo comprimento utilizando um determinado valor

Descrição

array array_pad ( array input, int pad_size, mixed pad_value)

array_pad() retorna uma cópia de input expandido para o comprimento especificado por pad_size com o valor pad_value. Se pad_size for positivo então o array é expandido pela direita, se for negativo, pela esquerda. Se o valor absoluto de pad_size for menor ou igual ao comprimento de input, então ele permanece inalterado.

Exemplo 1. Exemplo de array_pad()

$input = array (12, 10, 9);

$result = array_pad ($input, 5, 0);
// $result é array (12, 10, 9, 0, 0)

$result = array_pad ($input, -7, -1);
// $result é array (-1, -1, -1, -1, 12, 10, 9)

$result = array_pad ($input, 2, "noop");
// Não será expandido

array_pop

(PHP 4 )

array_pop -- Retira um elemento do final do array

Descrição

mixed array_pop ( array array)

array_pop() retira e retorna o último elemento de array, diminuindo array em um elemento. Se array estiver vazio (ou se não for um array), o valor NULL é retornado.

Exemplo 1. Exemplo de array_pop()

$cesta = array ("laranja", "banana", "melancia", "morango");
$fruta = array_pop ($cesta);

Depois disso, $cesta terá 3 elementos:
Array
(
    [0] => laranja
    [1] => banana
    [2] => melancia
)
e morango será passado para $fruta.

Atenção

Esta função pode retornar o booleano FALSE, mas também pode retornar um valor não-booleano que pode ser avaliado como FALSE, como 0 ou "". Leia a seção em Booleanos para maiores informações. Utilize o operador === para testar o valor retornado por esta função.

Veja também array_push(), array_shift(), e array_unshift().

array_push

(PHP 4 )

array_push --  Adiciona um ou mais elementos no final de um array

Descrição

int array_push ( array array, mixed var [, mixed ...])

array_push() trata array como uma pilha, e adiciona as variáveis passadas como argumentos no final de array. O comprimento de array aumenta de acordo com o número de variáveis adicionadas. Tem o mesmo efeito de:
$array[] = $var;
repetido para cada argumento var.

Retorna o novo número de elementos do array.

Exemplo 1. Exemplo de array_push()

$cesta = array ("laranja", "morango");
array_push ($cesta, "melancia", "batata");

Neste caso $stack teria os seguintes elementos:
Array
(
    [0] => laranja
    [1] => morango
    [2] => melancia
    [3] => batata
)

Veja também: array_pop(), array_shift(), e array_unshift().

array_rand

(PHP 4 )

array_rand --  Retorna um ou mais elementos aleatórios de um array

Descrição

mixed array_rand ( array input [, int num_req])

array_rand() é bastante útil quando se quer conseguir aleatoriamente um ou mais elementos de um array. Ela recebe o array input e outro argumento opcional num_req o qual especifica quantos elementos se quer conseguir - se não for especificado, o padrão é 1.

Se estiver pegando apenas um elemento, array_rand() retorna a chave para este elemento aleatório. De outra forma, ele retorna um array com as chaves desses elementos aleatórios. Assim é possível conseguir chaves e valores aleatórios a partir da mesma função.

Não esqueça de chamar a função srand() para disparar o gerador de números aleatórios.

Exemplo 1. Exemplo de array_rand()

srand ((float) microtime() * 10000000);
$input = array ("Neo", "Morpheus", "Trinity", "Cypher", "Tank");
$rand_keys = array_rand ($input, 2);
print $input[$rand_keys[0]]."\n";
print $input[$rand_keys[1]]."\n";

array_reduce

(PHP 4 >= 4.0.5)

array_reduce --  Reduz um array para um único valor através de um processo iterativo utilizando uma função.

Descrição

mixed array_reduce ( array input, mixed callback [, int initial])

array_reduce() aplica iterativamente a função definida em callback nos elementos de input, de forma a reduzi-lo a um único valor. Se o argumento opcional initial for passado, ele será utilizado no início do processo, ou como um resultado final se o array estiver vazio.

Exemplo 1. Exemplo de array_reduce()

function soma($v, $w) {
    $v += $w;
    return $v;
}

function multiplicacao($v, $w) {
    $v *= $w;
    return $v;
}

$a = array(1, 2, 3, 4, 5);
$x = array();
$b = array_reduce($a, "soma");
$c = array_reduce($a, "multiplicacao", 10);
$d = array_reduce($x, "soma", 1);

Isso resultará em $b contendo 15, $c contendo 1200 (= 1*2*3*4*5*10), e $d contendo 1.

Veja também array_filter(), array_map().

array_reverse

(PHP 4 )

array_reverse --  Retorna um array com os elementos na ordem inversa

Descrição

array array_reverse ( array array [, bool preserve_keys])

array_reverse() recebe o argumento array e retorna um novo array com a ordem dos elementos invertida, preservando as chaves se o argumento preserve_keys for TRUE.

Exemplo 1. Exemplo de array_reverse()

$input = array ("php", 4.0, array ("verde", "vermelho"));
$result = array_reverse ($input);
$result_keyed = array_reverse ($input, TRUE);

O programa acima fará com que $result e $result_keyed tenham os mesmos elementos, mas note a diferença entre as chaves. A saída de $result e $result_keyed será:
Array
(
    [0] => Array
        (
            [0] => verde
            [1] => vermelho
        )

    [1] => 4
    [2] => php
)
Array
(
    [2] => Array
        (
            [0] => verde
            [1] => vermelho
        )

    [1] => 4
    [0] => php
)

Nota: O segundo argumento foi adicionado no PHP 4.0.3.

array_search

(PHP 4 >= 4.0.5)

array_search --  Procura por um valor em um array e retorna sua chave correspondente caso seja encontrado

Descrição

mixed array_search ( mixed needle, array haystack [, bool strict])

Procura em haystack pelo valor needle e retorna sua chave se for encontrado no array, e FALSE em caso contrário.

Nota: A partir do PHP 4.2.0, array_search() retorna NULL em caso de falha ao invés de FALSE.

Se o terceiro parâmetro opcional strict for passado como TRUE então array_search() também fará uma checagem de tipos de needle em haystack.

Atenção

Esta função pode retornar o booleano FALSE, mas também pode retornar um valor não-booleano que pode ser avaliado como FALSE, como 0 ou "". Leia a seção em Booleanos para maiores informações. Utilize o operador === para testar o valor retornado por esta função.

Veja também array_keys() e in_array().

array_shift

(PHP 4 )

array_shift --  Retira o primeiro elemento de um array

Descrição

mixed array_shift ( array array)

array_shift() retira o primeiro elemento de array e o retorna, diminuindo array em um elemento e movendo todos os outros elementos para trás. Todas as chaves numéricas alteradas para começar a contar a de 0 (zero), enquanto chaves string permanecerão inalteradas. Se array estiver vazio (ou se não for um array), o valor NULL é retornado.

Exemplo 1. Exemplo de array_shift()

$cesta = array ("laranja", "banana", "melancia", "morango");
$fruta = array_shift ($cesta);

O programa acima resultaria em $stack tendo 3 elementos:
Array
(
    [0] => banana
    [1] => melancia
    [2] => morango
)
e laranja seria passado para $fruta.

Veja também array_unshift(), array_push() e array_pop().

array_slice

(PHP 4 )

array_slice -- Extrai uma parcela de um array

Descrição

array array_slice ( array array, int offset [, int length])

array_slice() retorna a sequência de elementos de array especificada pelos parâmetros offset e length.

Se offset for positivo, a sequência começará do início de array. Se offset for negativo, a sequência começará dessa distância do final de array.

Se length for especificado e positivo, então a sequência terá essa quantidade de elementos. Se length for especificado e negativo então a sequência pará dessa quantidade elementos a partir do final do array. Se for omitido, então a sequência terá todos os elementos a partir de offset até o final de array.

Note que array_slice() ignorará chaves e irá calcular os inícios e comprimentos dos intervalos baseada na posição absoluta dos elementos no array.

Exemplo 1. Exemplos de array_slice()

$input = array ("a", "b", "c", "d", "e");

$output = array_slice ($input, 2);      // retorna "c", "d", e "e"
$output = array_slice ($input, 2, -1);  // retorna "c", "d"
$output = array_slice ($input, -2, 1);  // retorna "d"
$output = array_slice ($input, 0, 3);   // retorna "a", "b", e "c"

Veja também array_splice().

array_splice

(PHP 4 )

array_splice --  Remove uma parcela do array e substitui com outros elementos

Descrição

array array_splice ( array input, int offset [, int length [, array replacement]])

array_splice() remove a sequência de elementos do array input especificados por offset e length, e os substitui com os elementos do array replacement, se for especificado. Retorna um array contendo os elementos removidos.

Se offset for positivo então o começo da região a ser removida será nessa posição a partir do início do array input. Se offset for negativo então o ínicio será dessa distância do final de input.

Se length for omitido, todos os elementos a partir de offset até o final do array serão removidos. Se length for especificado e positivo, então essa quantidade de elementos será removida. Se length for especificado e negativo então o final da região a ser removida será dessa quantidade de elementos a partir do final do array. Dica: para remover todos elementos a partir de offset até o final do array quando replacement também é especificado, use count($input) para o argumento length.

Se o array replacement for especificado, então os elementos removidos serão substituidos pelo elementos desse array. Se offset e length são dados de forma que nada será removido, então os elementos de replacement serão inseridos no lugar especificado por offset. Dica: se a substituição for de apenas um elemento então não será necessário colocar array() para ele, a não ser que elementos seja um array.

As seguintes equivalências abaixo são válidas:
array_push ($input, $x, $y)     array_splice ($input, count ($input), 0, 
                                             array ($x, $y))
array_pop ($input)              array_splice ($input, -1)
array_shift ($input)            array_splice ($input, 0, 1)
array_unshift ($input, $x, $y)  array_splice ($input, 0, 0, array ($x, $y))
$input[$x] = $y                 array_splice ($input, $x, 1, $y)

Retorna um array contendo os elementos removidos.

Exemplo 1. Exemplos de array_splice()

$input = array ("vermelho", "verde", "azul", "amarelo");
array_splice ($input, 2);      
// $input será agora array ("vermelho", "verde")

$input = array ("vermelho", "verde", "azul", "amarelo");
array_splice ($input, 1, -1);  
// $input será agora array ("vermelho", "amarelo")

$input = array ("vermelho", "verde", "azul", "amarelo");
array_splice ($input, 1, count($input), "laranja");  
// $input será agora array ("vermelho", "laranja")

$input = array ("vermelho", "verde", "azul", "amarelo");
array_splice ($input, -1, 1, array("preto", "marrom")); 
// $input será agora array ("vermelho", "verde", "azul", "preto", "marrom")

Veja também array_slice().

array_sum

(PHP 4 >= 4.0.4)

array_sum --  Calcula a soma dos elementos de um array

Descrição

mixed array_sum ( array arr)

array_sum() retorna a soma dos valores de um array como inteiro ou real.

Exemplo 1. Exemplos de array_sum()

$a = array(2, 4, 6, 8);
echo "soma(a) = ".array_sum($a)."\n";

$b = array("a" => 1.2, "b" => 2.3, "c" => 3.4);
echo "soma(b) = ".array_sum($b)."\n";

A saída do programa acima seria:
soma(a) = 20
soma(b) = 6.9

Nota: Até a versão 4.0.6 do PHP, o array em si é modificado e converte strings para valores numéricos (as quais na maioria das vezes é convertida para zero a depender dos seus valores).

array_unique

(PHP 4 >= 4.0.1)

array_unique -- Remove o valores duplicados de um array

Descrição

array array_unique ( array array)

array_unique() recebe o argumento array e retorna um novo array sem valores duplicados.

Note que as chaves são preservadas. array_unique() ordena inicialmente os valores como strings mantendo a primeira chave encontrada para cada valor, e ignorando as chaves encontradas posteriormente. Isso não significa que a chave do primeiro valor do array ainda desordenado será mantido.

Nota: Dois elementos são considerados iguais se, e somente se, (string) $elem1 === (string) $elem2. Em palavras: quando a represetação em string é a mesma.

O primeiro será usado.

Atenção

Essa função não funcionava no PHP 4.0.4!

Exemplo 1. Exemplo de array_unique()

$input = array ("a" => "verde", "vermelho", "b" => "verde", "azul", "vermelho");
$result = array_unique ($input);
print_r($result);

A saída seria:
Array
(
    [b] => verde
    [1] => azul
    [2] => vermelho
)

Exemplo 2. array_unique() e tipos

$input = array (4, "4", "3", 4, 3, "3");
$result = array_unique ($input);
var_dump($result);

A saída do programa acima seria (PHP 4.0.6):
array(2) {
  [3]=> 
  int(4)
  [4]=> 
  int(3)
}

array_unshift

(PHP 4 )

array_unshift --  Adiciona um ou mais elementos no início de um array

Descrição

int array_unshift ( array array, mixed var [, mixed ...])

array_unshift() adiciona os elementos passados como argumentos no início de array. Note que a lista de elementos é adicionada como um todo, de forma que eles ficam na mesma ordem. Todas as chaves numéricas serão modificadas para começar a contar de 0 (zero) enquanto chaves strings permanecerão inalteradas.

Retorna o novo número de elementos de array.

Exemplo 1. Exemplo de array_unshift()

$cesta = array ("laranja", "banana");
array_unshift ($cesta, "melancia", "morango");

O programa acima resultaria em $queue contendo os seguintes elementos:
Array
(
    [0] => melancia
    [1] => morango
    [2] => laranja
    [3] => banana
)

Veja também array_shift(), array_push() e array_pop().

array_values

(PHP 4 )

array_values -- Retorna todos os valores de um array

Descrição

array array_values ( array input)

array_values() retorna todos os valores do array input.

Exemplo 1. Exemplo de array_values()

$array = array ("tamanho" => "G", "cor" => "dourado");
print_r(array_values ($array));

A saída seria:
Array
(
    [0] => G
    [1] => dourado
)

Nota: Essa função foi adicionada no PHP 4, abaixo segue uma implementação para aqueles que ainda usam PHP 3.

Exemplo 2. Implementação de array_values() para PHP 3 users

function array_values ($arr) {
    $t = array();
    while (list($k, $v) = each ($arr)) {
        $t[] = $v;
    }
    return $t;
}

Veja também array_keys().

array_walk

(PHP 3>= 3.0.3, PHP 4 )

array_walk --  Aplica uma determinada funcão em cada elemento de um array

Descrição

int array_walk ( array arr, string func [, mixed userdata])

Aplica uma função definida pelo usuário nomeada pelo argumento func em cada elemento de arr. Normalmente, func recebe dois argumentos: o primeiro é o valor do elemento e o segundo, sua chave. Se userdata for especificado, ele será usado como terceiro argumento da função do usuário.

Se func necessita de mais argumentos do que o que está sendo passado para ela, um erro do nível E_WARNING será gerado a cada vez que array_walk() executar func. Esses avisos podem ser suprimidos adicionando o operador @ à chamada da função array_walk(), ou usando error_reporting().

Nota: Se func precisar alterar realmente os valores do array, especifique que o primeiro parâmetro de func deve ser passado por referência. Então qualquer mudança feita nesses elementos serão feitas no próprio array também.

Nota: A passagem das chaves e do terceiro argumento para func foi adicionada no PHP 4.0.0.

array_walk() não é afetada pelo ponteiro interno do array arr. array_walk() irá percorrer todo o array independente da posição atual do ponteiro interno. Para reiniciar o ponteiro, use reset(). No PHP 3, array_walk() reinicia o ponteiro.

Usuários não podem alterar o array a partir da função definida para ser usada. Por exemplo, adicionar/remover elementos, removerá o array no qual array_walk() está sendo aplicada. Se o array for alterado, o comportamento desta função se torna imprevisível.

Exemplo 1. Exemplo de array_walk()

<?php
$frutas = array ("d" => "limao", "a" => "laranja", "b" => "banana", "c" => "melancia");

function test_alter (&$item1, $key, $prefix) {
    $item1 = "$prefix: $item1";
}

function test_print ($item2, $key) {
    echo "$key. $item2<br>\n";
}

echo "Antes ...:\n";
array_walk ($frutas, 'test_print');

array_walk ($frutas, 'test_alter', 'fruta');
echo "... e depois:\n";

array_walk ($frutas, 'test_print');
?>

A saída do programa acima seria:
Antes ...:
d. limao
a. laranja
b. banana
c. melancia
... e depois:
d. fruit: limao
a. fruit: laranja
b. fruit: banana
c. fruit: melancia

Veja também array_map(), list(), foreach, each() e call_user_func_array().

array

(PHP 3, PHP 4 )

array --  Cria um array

Descrição

array array ( [mixed ...])

Retorna um array a partir dos valores fornecidos. Índices podem ser atribuidos aos valores através do operador =>.

Nota: array() é uma estrutura utilizada para representar literais de arrays, e não uma função.

A sintaxe "index => values", separados por vírgulas, definem índice e valores respectivamente. O índice por de ser do tipo string ou numérico. Quando o índice é omitido, um índice numérico inteiro é automaticamente gerado, começando do 0. Se o índice é um inteiro, o próximo índice a ser gerado será igual ao maior índice inteiro + 1. Note que quando dois índices idênticos são definidos, o último sobrescreve o primeiro.

O exemplo a seguir demonstra como criar um array com duas dimensões, como especificar chaves em arrays associativos, e como definir índices numéricos em arrays normais.

Exemplo 1. Exemplo de array()

$frutas = array (
    "frutas"  => array ("a"=>"laranja", "b"=>"banana", "c"=>"melancia"),
    "numeros" => array (1, 2, 3, 4, 5, 6),
    "buracos"   => array ("primeiro", 5 => "segundo", "terceiro")
);

Exemplo 2. Indexação automática com array()

$array = array( 1, 1, 1, 1,  1, 8 => 1,  4 => 1, 19, 3 => 13);
print_r($array);

vai mostrar :
Array 
(
    [0] => 1
    [1] => 1
    [2] => 1
    [3] => 13
    [4] => 1
    [8] => 1
    [9] => 19
)

Note que o índice 3 é definido duas vezes, e retêm seu último valor 13. O índice 4 é definido depois do índice 8, e o índice gerado depois dele foi 9, uma vez que o maior índice era 8.

Esse exemplo cria um array com o índices a partir do 1.

Exemplo 3. Array com índices a partir do 1 com array()

$trimestre  = array(1 => 'Janeiro', 'Fevereiro', 'Marco');
print_r($trimestre);

vai mostrar :
Array 
(
    [1] => 'Janeiro'
    [2] => 'Fevereiro'
    [3] => 'Marco'
)

Veja também array_pad(), list() e range().

arsort

(PHP 3, PHP 4 )

arsort --  Ordena um array em ordem descrescente mantendo a associação entre índices e valores

Descrição

void arsort ( array array [, int sort_flags])

Esta função ordena um array de forma que a correlação entre índices e valores é mantida. É usada principalmente para ordenar arrays associativos onde a ordem dos elementos é um fator importante.

Exemplo 1. Exemplo de arsort()

$frutas = array ("d" => "limao", "a" => "laranja", "b" => "banana", "c" => "melancia");
arsort ($frutas);
reset ($frutas);
while (list ($chave, $valor) = each ($frutas)) {
    echo "$chave = $valor\n";
}

A saída deste exemplo seria:
c = melancia
d = limao
a = laranja
b = banana

As frutas foram ordenadas na ordem alfabética inversa, e os índices associados a cada valor foram mantidos.

Você pode modificar o comportamento da ordenação usando o parâmetro opcional sort_flags, para mais detalhes veja sort().

Veja também: asort(), rsort(), ksort() e sort().

asort

(PHP 3, PHP 4 )

asort --  Ordena um array mantendo a associação entre índices e valores

Descrição

void asort ( array array [, int sort_flags])

Essa função ordena um array de forma que a correlação entre índices e valores é mantida. É usada principalmente para ordenar arrays associativos onde a ordem dos elementos é um fator importante.

Exemplo 1. Exemplo de asort()

$frutas = array ("d" => "limao", "a" => "laranja", "b" => "banana", "c" => "melancia");
asort ($frutas);
reset ($frutas);
while (list ($chave, $valor) = each ($frutas)) {
    echo "$chave = $valor\n";
}

A saída desse programa seria:
b = banana
a = laranja
d = limao
c = melancia

As frutas foram ordenadas na ordem alfabética, e os índices associados a cada valor foram mantidos.

Você pode modificar o comportamento da ordenação usando o parâmetro opcional sort_flags, para mais detalhes veja sort().

veja também arsort(), rsort(), ksort() e sort().

compact

(PHP 4 )

compact --  Cria um array contendo variáveis e seus valores

Descrição

array compact ( mixed varname [, mixed ...])

compact() recebe um número variável de parâmetros. Cada parâmetro pode ser tanto uma string contendo o nome da variável, como um array com nomes de variáveis. Sendo um array, ele pode conter outros arrays de nomes de variáveis; compact() trata isso recursivamente.

Para cada um dos parâmetros passados, compact() procura uma variável com o nome especificado na tabela de símbolos e a adiciona no array de saída de forma que o nome da variável será a chave e o seu conteúdo será o valor para esta chave. Em resumo, ela faz o oposto de extract(). Retorna um array de saída com todas as variáveis adicionadas a ele.

Qualquer string com nome de uma variável que não exista será simplesmente ignorada.

Exemplo 1. Exemplo de compact()

$cidade = "Sao Paulo";
$estado = "SP";
$evento = "SIGGRAPH";

$localidade = array ("cidade", "estado");

$result = compact ("evento", "nada_aqui", $localidade);

Depois disso, $result será:
Array
(
    [evento] => SIGGRAPH
    [cidade] => Sao Paulo
    [estado] => SP
)

Veja também extract().

count

(PHP 3, PHP 4 )

count -- Conta o número de elementos de uma variável

Descrição

int count ( mixed var)

Retorna o número de elementos de var, que normalmente é um array (uma vez que qualquer outra coisa terá apenas um elemento).

Se var não for um array, 1 será retornado (excessão: count(NULL) retorna 0).

Atenção

count() pode retornar 0 para uma variável que não existe, mas também pode retornar 0 para uma variável que tenha sido inicializada como um array vazio. Use isset() para checar se a variável existe.

Por favor, veja a sessão Arrays do manual para uma explicação mais detalhada sobre como os arrays são implementados e utilizados no PHP.

Exemplo 1. Exemplo de count()

$a[0] = 1; 
$a[1] = 3; 
$a[2] = 5; 
$result = count ($a);
// $result == 3

$b[0] = 7;
$b[5] = 9;
$b[10] = 11;
$result = count ($b);
// $result == 3;

Nota: A função sizeof() é um alias para count().

Veja também is_array(), isset() e strlen().

current

(PHP 3, PHP 4 )

current -- Retorna o elemento corrente em um array

Descrição

mixed current ( array array)

Todo array tem um ponteiro interno para o elemento "atual", o qual é inicializado para apontar para o primeiro elemento inserido em um array.

A função current() simplesmente retorna o elemento do array para o qual esse ponteiro interno está apontando. Não move o ponteiro de forma alguma. Se o ponteiro interno estiver apontando para além do final da lista de elementos, current() retorna FALSE.

Atenção

Se o array contêm elementos vazios (0 ou "", uma string vazia) então esta função retorna FALSE para esses elementos. Isso faz com que seja impossível determinar se você está realmente no final da lista de elementos de um array usando current(). Para percorrer devidamente um array que pode conter elementos vazios, use a função each().

Veja também end(), next(), prev() e reset().

each

(PHP 3, PHP 4 )

each --  Retorna o par chave/valor corrente de um array e avança o seu cursor

Descrição

array each ( array array)

Retorna o par chave/valor corrente de array e avança o seu cursor. Esse par é retornado num array de quatro elementos, com as chaves 0, 1, key, e value. Os elementos 0 e key contêm o nome da chave do elemento do array, e 1 e value contêm o valor.

Se o cursor interno do array estiver apontando para além do final do array, each() retorna FALSE.

Exemplo 1. Exemplos de each()

$foo = array ("bob", "fred", "jussi", "jouni", "egon", "marliese");
$bar = each ($foo);

$bar agora contém os seguintes pares de chaves e valores:

  • 0 => 0
  • 1 => 'bob'
  • key => 0
  • value => 'bob'
$foo = array ("Robert" => "Bob", "Seppo" => "Sepi");
$bar = each ($foo);

$bar agora contém os seguintes pares de chaves e valores:

  • 0 => 'Robert'
  • 1 => 'Bob'
  • key => 'Robert'
  • value => 'Bob'

each() é tipicamente usada em conjunto com list() para percorrer um array; por exemplo, $_POST:

Exemplo 2. Percorrendo $HTTP_POST_VARS usando each()

echo "Valores submetidos pelo método POST:<br>";
reset ($_POST);
while (list ($chave, $valor) = each ($_POST)) {
    echo "$chave => $valor<br>";
}

Depois da execução de each(), o cursor interno do array vai apontar para o prócimo elemento do array, ou no último elemento se ele chegar ao final do array. Você deve usar reset() se quiser percorrer o array novamente.

Veja também key(), list(), current(), reset(), next(), prev() e foreach.

end

(PHP 3, PHP 4 )

end --  Faz o ponteiro interno de um array apontar para o seu último elemento

Descrição

mixed end ( array array)

end() avança o ponteiro interno de array até o seu último elemento, e retorna esse elemento.

Exemplo 1. Exemplo simples de end()

<?php

  $frutas = array('melancia','banana','morango');
    
  print end($frutas); // morango
?>

Veja também current(), each(), end(), next() e reset().

extract

(PHP 3>= 3.0.7, PHP 4 )

extract --  Importa variáveis para a tabela de símbolos a partir de um array

Descrição

int extract ( array var_array [, int extract_type [, string prefix]])

Essa função é usada para importar variáveis a partir de um array para a tabela de símbolos corrente. Recebe o array associativo var_array e trata as suas chaves como os nomes das variáveis e os valores como valores das variáveis. Para cada par chave/valor ele criará uma variável na tabela de símbolos corrente, seguindo os parâmetros extract_type e prefix.

Nota: Desde a versão 4.0.5, essa função retorna o número de variáveis extraídas.

Nota: EXTR_IF_EXISTS e EXTR_PREFIX_IF_EXISTS foram adicionadas na versão 4.2.0.

Nota: EXTR_REFS foi adicionada na versão 4.3.0.

extract() checa se cada chave do array constitui um nome de variável válido e por colisões com as variáveis já existentes na tabela de símbolos. O modo com que chaves inválidas ou númericas e colisões são tratadas é determinado pelo argumento extract_type. Esse argumento pode receber os seguintes valores:

EXTR_OVERWRITE

Se houver uma colisão, sobrescreve a variável existente.

EXTR_SKIP

Se houver uma colisão, não sobrescreve a variável existente.

EXTR_PREFIX_SAME

Se houver uma colisão, adiciona um prefixo ao nome da variável definido pelo argumento prefix.

EXTR_PREFIX_ALL

Adiciona um prefixo ao nome de todas as variáveis definido por prefix. Desde o PHP 4.0.5 estão incluídos nomes numéricos.

EXTR_PREFIX_INVALID

Adiciona um prefixo definido por prefix apenas para variáveis como nomes inválidos ou numéricos. Essa opção foi adicionada no PHP 4.0.5.

EXTR_IF_EXISTS

Só sobrescreve a variável se ela já existe na tabela de símbolos corrente, caso contrário, não faz nada. Isso é útil quando se quer definir uma lista de variáveis válidas e então extrair só as que foram definidas em $_REQUEST, por exemplo. Essa opção foi adicionada no PHP 4.2.0.

EXTR_PREFIX_IF_EXISTS

Só cria nomes de variáveis usando o prefixo se na tabela de símbolos já existe uma variável com o nome sem esse prefixo. Essa opção foi adicionada no PHP 4.2.0.

EXTR_REFS

Extrai variáveis como referências, ou seja, os valores das variáveis importadas ainda estarão referenciando os valores do parâmetro var_array. Essa opção pode ser usada sozinha ou em conjunto com as outras usando o operador 'ou' em extract_type. Essa opação foi adicionada no PHP 4.3.0.

Se extract_type não for especificado, é assumido o valor EXTR_OVERWRITE por padrão.

Note que prefix só é necessário se extract_type for EXTR_PREFIX_SAME, EXTR_PREFIX_ALL, ou EXTR_PREFIX_INVALID, EXTR_PREFIX_INVALID ou EXTR_IF_EXISTS. Se o nome com o prefixo não for um nome de variável válido, ela não será importada para a tabela de símbolos.

extract() retorna o número de variáveis importadas com sucesso para a tabela de símbolos.

Uma possível utilização de extract() e na importação de variáveis contidas num array associativo retornado pela função wddx_deserialize().

Exemplo 1. Exemplo de extract()

<?php

/* Suponha que $var_array é um array retornado pela função
   wddx_deserialize */

$tamanho = "grande";
$var_array = array ("cor" => "azul",
                    "tamanho"  => "medio",
                    "forma" => "esfera");
extract ($var_array, EXTR_PREFIX_SAME, "wddx");

print "$cor, $tamanho, $forma, $wddx_tamanho\n";

?>

O exemplo acima produziria:
azul, grande, esfera, medio

O $tamanho não foi sobrescrito, porque nós especificamos EXTR_PREFIX_SAME, o que resultou na criação da variável $wddx_tamanho. Se EXTR_SKIP fosse utilizado, então $wddx_tamanho não seria criada. EXTR_OVERWRITE teria feito com que $tamanho tivesse o valor "medio", e EXTR_PREFIX_ALL resultaria em novas variáveis com os nomes $wddx_cor, $wddx_tamanho, e $wddx_forma.

Você deve usar um array associativo, um array indexado numericamente não produzirá resultados.

Veja também compact().

in_array

(PHP 4 )

in_array -- Retorna TRUE se um valor existe no array

Descrição

bool in_array ( mixed needle, array haystack [, bool strict])

Procura em haystack pelo valor needle e retorna TRUE se este valor for encontrado no array, e FALSE em caso contrário.

Se o terceiro parâmetro strict for TRUE então in_array() também irá checar os tipos de needle em haystack.

Nota: Se needle for uma string, a comparação é feita diferenciando caracteres maiúsculos e minúsculos.

Nota: Em versões do PHP mais antigas que 4.2.0 needle não pode ser um array.

Exemplo 1. Exemplo de in_array()

$os = array ("Mac", "NT", "Irix", "Linux");
if (in_array ("Irix", $os)) {
    print "Tem Irix";
}
if (in_array ("mac", $os)) {
    print "Tem mac";
}

A segunda condicional falha pois in_array() diferencia letras minúsculas e maiúsculas. Então, a saída seria:
Tem Irix

Exemplo 2. in_array() com checagem de tipos

<?php
$a = array('1.10', 12.4, 1.13);

if (in_array('12.4', $a, TRUE))
    echo "'12.4' encontrado com checagem de tipo\n";
if (in_array(1.13, $a, TRUE))
    echo "1.13 encontrado com checagem de tipo\n";
?>

A saída seria:
1.13 encontrado com checagem de tipo

Exemplo 3. Exemplo de in_array() passando um array para needle

<?php
$a = array(array('p', 'h'), array('p', 'r'), 'o');

if (in_array(array ('p', 'h'), $a))
    echo "'ph' foi encontrado\n";
if (in_array(array ('f', 'i'), $a))
    echo "'fi' foi encontrado\n";
if (in_array('o', $a))
    echo "'o' foi encontrado\n";
?>

A saída seria:
'ph' foi encontrado 
'o' foi encontrado

Veja também array_search().

key

(PHP 3, PHP 4 )

key -- Retorna uma chave de um array associativo

Descrição

mixed key ( array array)

key() retorna a chave da posição corrente de um array.

Veja também current() e next().

krsort

(PHP 3>= 3.0.13, PHP 4 )

krsort -- Ordena um array pelas chaves em ordem descrescente

Descrição

int krsort ( array array [, int sort_flags])

Ordena um array pelas chaves em ordem descrescente, mantendo a correlação entre entre as chaves e os valores. Essa função é bastante útil em arrays associativos.

Exemplo 1. Exemplo de krsort()

$frutas = array ("d" => "limao", "a" => "laranja", "b" => "banana", "c" => "melancia");
krsort ($frutas);
reset ($frutas);
while (list ($chave, $valor) = each ($frutas)) {
    echo "$chave = $valor\n";
}

A saída deste programa seria:

d = limao
c = melancia
b = banana
a = laranja

Você pode alterar o comportamento da ordenação utilizando o parâmetro opcional sort_flags, para mais detalhes veja sort().

Veja também asort(), arsort(), ksort() sort(), natsort() e rsort().

ksort

(PHP 3, PHP 4 )

ksort -- Ordena um array pelas chaves

Descrição

int ksort ( array array [, int sort_flags])

Ordena um array pelas chaves, mantendo a correlação entre as chaves e os valores. Essa função é bastante útil principalmente para arrays associativos.

Exemplo 1. Exemplo de ksort()

$frutas = array ("d" => "limao", "a" => "laranja", "b" => "banana", "c" => "melancia");
ksort ($frutas);
reset ($frutas);
while (list ($chave, $valor) = each ($frutas)) {
    echo "$chave = $valor\n";
}

O programa acima mostraria:

a = laranja
b = banana
c = melancia
d = limao

Você pode modificar o comportamento da ordenação através do parâmetro opcional sort_flags, para mais detalhes veja sort().

Veja também asort(), arsort(), krsort(), uksort(), sort(), natsort() e rsort().

Nota: O segundo parâmetro foi adicionado a partir do PHP 4.

list

(PHP 3, PHP 4 )

list --  Cria variáveis como se fossem arrays

Descrição

void list ( mixed ...)

Assim como array(), não é exatamente uma função, e sim uma construção da própria linguagem. list() é usada para criar uma lista de variáveis em apenas um operação.

Nota: list() só funciona em arrays com índices numéricos e assume que esses índices começam de 0 (zero).

Exemplo 1. Exemplo de list()

<?php

$info = array('Café', 'marrom', 'cafeína');

// Listando todas as variáveis
list($bebida, $cor, $substancia) = $info;
print "$bebida is $cor e $substancia a faz especial.\n";

// Listando apenas alguns deles
list($bebida, , $substanciar) = $info;
print "$bebida tem $substancia.\n";

// Ou ignoramos os primeiros valores para conseguir apenas o último 
list( , , $substancia) = $info;
print "I need $substancia!\n";

?>

Exemplo 2. Exemplo de list()

<table>
 <tr>
  <th>Lista de empregados</th>
  <th>Salário</th>
 </tr>

<?php

$result = mysql_query ("SELECT id, nome, salario FROM empregados", $conn);
while (list ($id, $nome, $salario) = mysql_fetch_row ($result)) {
    print (" <tr>\n".
           "  <td><a href=\"info.php?id=$id\">$nome</a></td>\n".
           "  <td>$salario</td>\n".
           " </tr>\n");
}

?>

</table>

Atenção

A função list() assinala os valores começando pelos parâmetros da direita. Se você está usando variáveis normais, então não precisa se preocupar com esse detalhe. Mas se você está usando arrays com índices você normalmente iria esperar que a ordem dos índices no array fosse da esquerda para a direita, mas não é isso que acontece. O índice é criado na ordem reversa.

Exemplo 3. Usando list() com índices de array

<?php

$info = array('café', 'marrom', 'cafeína');

list($a[0], $a[1], $a[2]) = $info;

var_dump($a);

?>
O retorno desse script é o seguinte (note a ordem dos elementos em comparação com o array original):
array(3) {
  [2]=>
  string(8) "cafeína"
  [1]=>
  string(5) "marrom"
  [0]=>
  string(6) "café"
}

Veja também each(), array() e extract().

natcasesort

(PHP 4 )

natcasesort --  Ordena um array utilizando o algoritmo da "ordem natural" sem diferenciar maiúsculas e minúsculas

Descrição

void natcasesort ( array array)

Essa função implementa o algoritmo de ordenação que ordena strings alfanuméricas da forma que os humanos fariam. Essa forma de ordenação é denominada "ordenação natural".

natcasesort() é uma versão de natsort() que não diferencia letras maiúsculas e minúsculas. Veja natsort() para saber a diferença entre esse algoritmo e os algoritmos utlizados normalmente para ordenação de strings.

Para mais informações veja: Martin Pool's Natural Order String Comparison page.

Veja também sort(), natsort(), strnatcmp() e strnatcasecmp().

natsort

(PHP 4 )

natsort --  Ordena um array utilizando o algoritmo da "ordem natural"

Descrição

void natsort ( array array)

Essa função é um implementação do algoritmo que ordena strings alfanuméricas da forma como um ser humano faria. Isso é chamado de "ordenação natural". Um exemplo da diferença entre esse algoritmo e o algoritmo com o qual o computador classifica strings (usado em sort()) pode ser visto abaixo:

Exemplo 1. Exemplo de natsort()

$array1 = $array2 = array ("img12.png", "img10.png", "img2.png", "img1.png");
 
sort($array1);
echo "Classificação normal\n";
print_r($array1);

natsort($array2);
echo "\nClassificação da \"ordem natural\"\n";
print_r($array2);

O código acima geraria a seguinte saída:

Classificação normal
Array
(
    [0] => img1.png
    [1] => img10.png
    [2] => img12.png
    [3] => img2.png
)

Classificação da "ordem natural"
Array
(
    [3] => img1.png
    [2] => img2.png
    [1] => img10.png
    [0] => img12.png
)

Para mais informações veja: Martin Pool's Natural Order String Comparison page.

Nota: Se quiser manter a correlação entre chaves e valores, considere a possibilidade de utilizar usort($arr, 'strnatcmp').

Veja também natcasesort(), strnatcmp() e strnatcasecmp().

next

(PHP 3, PHP 4 )

next --  Avança o ponteiro interno de um array

Descrição

mixed next ( array array)

Retorna o elemento do array que está na próxima posição que é apontada pelo ponteiro interno do array, ou FALSE caso não existam mais elementos.

next() funciona de forma semelhante a current(), com uma diferença. Ele avança o ponteiro interno do array em uma posição antes de retornar o elemento. Isso significa que ela retorna o próximo elemento do array avançando o ponteiro interno em uma posição. Se o ponteiro interno apontar para além do final da lista de elementos , next() retorna FALSE.

Atenção

Se o array contiver elementos vazios, ou se elementos tiverem chaves com 0 como valor então essa função retorna FALSE para esses elementos. Para percorrer um array que pode conter elementos vazios ou elementos que tenham chaves com 0 como valor veja a função each().

Veja também current(), end(), prev() e reset().

pos

(PHP 3, PHP 4 )

pos -- Retorna o elemento atual do array

Descrição

mixed pos ( array array)

Essa função é um alias para current().

Veja também end(), next(), prev() e reset().

prev

(PHP 3, PHP 4 )

prev -- Retrocede o ponteiro interno de um array

Descrição

mixed prev ( array array)

Retorna o elemento do array que está na posição anterior a posição apontada pelo ponteiro interno, ou FALSE se houver mais elementos.

Atenção

Se o array contiver elementos vazios então essa função retornará FALSE para esses elementos. Para percorrer corretamente arrays que podem conter elementos vazios veja a função each().

prev() funciona da mesma forma que next(), com a única diferença sendo de que a primeira retrocede o ponteiro interno em uma posição ao invés de avançá-lo.

Veja também current(), end(), next() e reset().

range

(PHP 3>= 3.0.8, PHP 4 )

range --  Cria um array contendo uma faixa de elementos

Descrição

array range ( mixed low, mixed high [, int step])

range() retorna um array com elementos de low até high, com intervalo fechado. Se low > high, será de high até low.

Se o parâmetro step for especificado, será usado como o incremento entre os elementos da sequência. step deve ser um inteiro positivo. Se não for especificado, step terá valor igual a 1.

Exemplo 1. Exemplos de range()

foreach(range(0, 9) as $numero) {
    echo $numero;
}
foreach(range(0, 100, 10) as $numero) {
    echo $numero;
}
foreach(range('a', 'z') as $letra) {
    echo $letra;
}
foreach(range('z', 'a') as $letra) {
    echo $letra;
}

Nota: Até a versão 4.1.0, a função range() só gerava arrays de inteiros em ordem crescente. O suporte para sequências de caracteres e arrays descrescentes foi adicionado no PHP 4.1.0. O parâmetro step foi adicionado na versão 5.0.0.

Exemplo 2. Simulando faixas decrescentes e sequências de caracteres

# array_reverse pode ser usada para inverter a ordem da faixa de valores 
foreach(array_reverse(range(0,9)) as $numero) {
    echo $numero;
}

# array_map() pode ser usada para transformar inteiros em caracteres usando chr()
foreach(array_map('chr', range(ord('a'),ord('z'))) as $caracter) {
    echo $caracter;
}

Veja shuffle() para outro exemplo de utilização dessa função.

reset

(PHP 3, PHP 4 )

reset --  Faz o ponteiro interno de um array apontar para o seu primeiro elemento

Descrição

mixed reset ( array array)

reset() retrocede o ponteiro interno de array para o primeiro elemento.

reset() retorna o valor do primeiro elemento do array.

Veja também current(), each(), next(), e prev().

rsort

(PHP 3, PHP 4 )

rsort -- Ordena um array em ordem descrescente

Descrição

void rsort ( array array [, int sort_flags])

Essa função ordena um array em ordem descrescente (do maior para o menor).

Exemplo 1. Exemplo de rsort()

$frutas = array ("limao", "laranja", "banana", "melancia");
rsort ($frutas);
reset ($frutas);
while (list ($chave, $valor) = each ($frutas)) {
    echo "$chave = $valor\n";
}

Esse exemplo mostraria:

0 = melancia
1 = limao
2 = laranja
3 = banana

As frutas foram ordenadas em ordem alfabética decrescente.

Você pode alterar o comportamento da ordenação utilizando o parâmetro opcional sort_flags, para mais detalhes veja sort().

Veja também arsort(), asort(), ksort(), sort() e usort().

shuffle

(PHP 3>= 3.0.8, PHP 4 )

shuffle -- Mistura os elementos de um array

Descrição

void shuffle ( array array)

Essa função mistura de forma aleatória os elementos de um array. Você deve usar essa função em conjunto com srand().

Exemplo 1. Exemplo de shuffle()

$numeros = range (1,20);
srand ((float)microtime()*1000000);
shuffle ($numeros);
while (list (, $numero) = each ($numeros)) {
    echo "$numero ";
}

Veja também arsort(), asort(), ksort(), rsort(), sort() e usort().

sizeof

(PHP 3, PHP 4 )

sizeof -- Retorna o número de elementos de uma variável

Descrição

int sizeof ( mixed var)

A função sizeof() é um alias para count().

Veja também count().

sort

(PHP 3, PHP 4 )

sort -- Ordena um array

Descrição

void sort ( array array [, int sort_flags])

Essa função ordena um array. Os elementos serão ordenados do menor para o maior ao final da execução dessa função.

Exemplo 1. Exemplo de sort()

<?php

$frutas = array ("limao", "laranja", "banana", "melancia");
sort ($frutas);
reset ($frutas);
while (list ($chave, $valor) = each ($frutas)) {
    echo "frutas[".$chave."] = ".$valor."\n";
}
 
?>

A saída desse programa seria:

fruits[0] = banana
fruits[1] = laranja
fruits[2] = limao
fruits[3] = melancia

As frutas foram classificadas em ordem alfabética.

O segundo argumento opcional sort_flags pode ser usado para modificar o comportamento da ordenação podendo receber os seguintes valores:

Sinais de tipo de ordenação:

  • SORT_REGULAR - compara os itens normalmente

  • SORT_NUMERIC - compara os itens como valores numéricos

  • SORT_STRING - compara os itens como strings

Veja também arsort(), asort(), ksort(), natsort(), natcasesort(), rsort(), usort(), array_multisort() e uksort().

Nota: O segundo parâmetro foi adicionado a partir do PHP 4.

uasort

(PHP 3>= 3.0.4, PHP 4 )

uasort --  Ordena um array utilizando uma função de comparação definida pelo usuário e mantendo as associações entre chaves e valores

Descrição

void uasort ( array array, function cmp_function)

Essa função ordena um array de forma que a correlação entre chaves e valores é mantida. Esta função é usada principalmente para classificar arrays associativos onde a ordem dos elementos é um fator importante. A função de comparacão é definida pelo usuário.

Nota: Por favor, veja usort() e uksort() para exemplos de funções de comparação definidas pelo usuário.

Veja também usort(), uksort(), sort(), asort(), arsort(), ksort() e rsort().

uksort

(PHP 3>= 3.0.4, PHP 4 )

uksort --  Ordena um array pelas chaves utilizando uma função de comparação definida pelo usuário.

Descrição

void uksort ( array array, function cmp_function)

Essa função irá ordenar as chaves de um array usando uma função de comparação definida pelo usuário. Se o array precisa ser classificado utilizando um critério não trivial, você deve usar essa função.

Exemplo 1. Exemplo de uksort()

function cmp ($a, $b) {   
    if ($a == $b) return 0;
    return ($a > $b) ? -1 : 1;
}

$a = array (4 => "quatro", 3 => "tres", 20 => "vinte", 10 => "dez");

uksort ($a, "cmp");

while (list ($chave, $valor) = each ($a)) {
    echo "$chave: $valor\n";
}

Esse exemplo mostraria:

20: vinte
10: dez
4: quatro
3: tres

Veja também usort(), uasort(), sort(), asort(), arsort(), ksort(), natsort() e rsort().

usort

(PHP 3>= 3.0.3, PHP 4 )

usort --  Ordena um array pelos valores utilizando uma função de comparação definida pelo usuário

Descrição

void usort ( array array, string cmp_function)

Essa função irá ordenar um array pelos valores usando uma função de classificação definida pelo usuário. Se o array precisar ser ordenado utilizando um critério não trivial, você deve usar essa função.

A função de comparação deve retornar um inteiro menor, igual ou maior que zero se o primeiro argumento for considerado respectivamente menor, igual, ou maior que o segundo.

Nota: Se dois elementos são considerados iguais, a ordem deles fica indefinida no array resultante. Até o PHP 4.0.6 as funções definidas pelo usuário manteriam a ordem original desses elementos, mas com o novo algoritmo de ordenação introduzido no 4.1.0 esse não é o caso, pois não existe solução para fazer isso de modo eficiente.

Exemplo 1. Exemplo de usort()

function cmp ($a, $b) {   
    if ($a == $b) return 0;
    return ($a > $b) ? -1 : 1;
}

$a = array (3, 2, 5, 6, 1);

usort ($a, "cmp");

while (list ($chave, $valor) = each ($a)) {
    echo "$chave: $valor\n";
}

Esse exemplo mostraria:

0: 6
1: 5
2: 3
3: 2
4: 1

Nota: Obviamente que nesse caso trivial a função rsort() seria mais apropriada.

Exemplo 2. Exemplo de usort() usando um array multi-dimensional

function cmp ($a, $b) {
    return strcmp($a["fruta"], $b["fruta"]);
} 

$frutas[0]["fruta"] = "limoes";
$frutas[1]["fruta"] = "abacaxis";
$frutas[2]["fruta"] = "goiabas";

usort($frutas, "cmp"); 

while (list ($chave, $valor) = each ($frutas)) {
    echo "\$frutas[$chave]: " . $valor["fruta"] . "\n";
}

Na ordenação de um array multi-dimensional, $a e $b contêm referências para o primeiro índice do array.

Esse exemplo mostraria:

$fruits[0]: abacaxis
$fruits[1]: goiabas
$fruits[2]: limoes

Nota: Ao invés de um nome de função, um array contendo uma referência de objeto e ao nome de método também pode ser fornecidos.

Exemplo 3. Exemplo de usort() usando uma função membro de um objeto

class TestObj {
    var $name;

    function TestObj($name)
    {
        $this->name = $name;
    }

    /* Essa é a função estática de comparação */
    function cmp_obj($a, $b)
    {
        $al = strtolower($a->name);
        $bl = strtolower($b->name);
        if ($al == $bl) return 0;
        return ($al > $bl) ? +1 : -1;
    }
}

$a[] = new TestObj("c");
$a[] = new TestObj("b");
$a[] = new TestObj("d");

uasort($a, array ("TestObj", "cmp_obj"));

foreach ($a as $item) {
    print $item->name."\n";
}

Esse exemplo mostraria:

b
c
d

Veja também uasort(), uksort(), sort(), asort(), arsort(),ksort(), natsort(), e rsort().

III. Aspell functions [deprecated]

Introdução

The aspell() functions allows you to check the spelling on a word and offer suggestions.


Requisitos

aspell works only with very old (up to .27.* or so) versions of aspell library. Neither this module, nor those versions of aspell library are supported any longer. If you want to use spell-checking capabilities in PHP, use pspell instead. It uses pspell library and works with newer versions of aspell.


Instalação

You need the aspell library, available from: http://aspell.sourceforge.net/.


Veja Também

See also pspell.

Índice
aspell_check_raw --  Check a word without changing its case or trying to trim it [deprecated]
aspell_check -- Check a word [deprecated]
aspell_new -- Load a new dictionary [deprecated]
aspell_suggest -- Suggest spellings of a word [deprecated]

aspell_check_raw

(PHP 3>= 3.0.7, PHP 4 <= 4.2.3)

aspell_check_raw --  Check a word without changing its case or trying to trim it [deprecated]

Description

bool aspell_check_raw ( int dictionary_link, string word)

aspell_check_raw() checks the spelling of a word, without changing its case or trying to trim it in any way and returns TRUE if the spelling is correct, FALSE if not.

Exemplo 1. aspell_check_raw()

$aspell_link = aspell_new("english");

if (aspell_check_raw($aspell_link, "test")) {
    echo "This is a valid spelling";
} else {
    echo "Sorry, wrong spelling";
}

aspell_check

(PHP 3>= 3.0.7, PHP 4 <= 4.2.3)

aspell_check -- Check a word [deprecated]

Description

bool aspell_check ( int dictionary_link, string word)

aspell_check() checks the spelling of a word and returns TRUE if the spelling is correct, FALSE if not.

Exemplo 1. aspell_check()

$aspell_link = aspell_new("english");

if (aspell_check($aspell_link, "testt")) {
    echo "This is a valid spelling";
} else {
    echo "Sorry, wrong spelling";
}

aspell_new

(PHP 3>= 3.0.7, PHP 4 <= 4.2.3)

aspell_new -- Load a new dictionary [deprecated]

Description

int aspell_new ( string master [, string personal])

aspell_new() opens up a new dictionary and returns the dictionary link identifier for use in other aspell functions. Returns FALSE on error.

Exemplo 1. aspell_new()

$aspell_link = aspell_new("english");

aspell_suggest

(PHP 3>= 3.0.7, PHP 4 <= 4.2.3)

aspell_suggest -- Suggest spellings of a word [deprecated]

Description

array aspell_suggest ( int dictionary_link, string word)

aspell_suggest() returns an array of possible spellings for the given word.

Exemplo 1. aspell_suggest()

$aspell_link = aspell_new("english");

if (!aspell_check($aspell_link, "test")) {
    $suggestions = aspell_suggest($aspell_link, "test");

    foreach ($suggestions as $suggestion) {
        echo "Possible spelling: $suggestion<br>\n"; 
    }
}

IV. BCMath Funções Matemáticas de Precisão Arbitrária

Introdução

Para matemática de precisão arbitrária, o PHP oferece a Calculadora Binária com suporte a números de qualquer tamanho e precisão, representados como strings.


Requisitos

Desde o PHP 4.0.4, a libbcmath é distribuída junto com o PHP. Você não precisa de nenhuma biblioteca externa para esta estensão.


Instalação

No PHP 4, estas funções somente serão disponíveis se PHP foi configurado com --enable-bcmath. No PHP 3, estas funções somente serão disponíveis se PHP não foi configurado com --disable-bcmath.


Configuração durante execução

O comportamento dessas funções podem ser modificado pelas configurações do php.ini.

Tabela 1. Opções de configuração da BC Math

Nome Padrão Alterável
bcmath.scale 0 PHP_INI_ALL
Para mais detalhes e definições para as constantes PHP_INI_* veja a função ini_set().

Segue uma breve descrição das diretivas de configuração.

bcmath.scale integer

Número de casas decimais para todas as funções BC Math.


Tipos Resource

Esta extensão não possui nenhum tipo resource.


Constantes Predefinidas

Esta extensão não possui nenhuma constante.

Índice
bcadd -- Adicionar dois números de precisão arbitrária
bccomp -- Comparar dois números de precisão arbitrária
bcdiv -- Dividir dois números de precisão arbitrária
bcmod --  Obter o módulo de um número com precisão arbitrária
bcmul -- Multiplicar dois números de precisão arbitrária
bcpow --  Elevar um número de precisão arbitrária a outro
bcpowmod --  Raise an arbitrary precision number to another, reduced by a specified modulus.
bcscale --  Configura o paramentro escala para todas as funções bc
bcsqrt --  Obter a raiz quadrada de um número de precisão arbitrária
bcsub --  Subtrair um número de precisão arbitrária de outro

bcadd

(PHP 3, PHP 4 )

bcadd -- Adicionar dois números de precisão arbitrária

Descrição

string bcadd ( string operador_da_esquerda, string operador_da_direita [, int escala])

Adiciona o operador_da_esquerda ao operador_da_direita e retorna a soma em uma string. O parametro opcional escala é usado para configurar o número de digitos depois do ponto decimal a ser usados no resultado.

Veja também bcsub().

bccomp

(PHP 3, PHP 4 )

bccomp -- Comparar dois números de precisão arbitrária

Descrição

int bccomp ( string operador_da_esquerda, string operador_da_direita [, int escala])

Compara o operador_da_esquerda com o operador_da_direita e retorna o resultado como um inteiro. O parametro opcional escala é usado para configurar o número de digitos depois do ponto decimal que serão utilizados na comparação. O valor retornado será 0 se os operadores são iguais. Se o operador_da_esquerda for maior do que o operador_da_direita o valor a ser retornado será +1 e se o operador_da_esquerda é menor do que o operador_da_direita o valor retornado é -1.

bcdiv

(PHP 3, PHP 4 )

bcdiv -- Dividir dois números de precisão arbitrária

Descrição

string bcdiv ( string operador_da_esquerda, string operador_da_direita [, int escala])

Divide o operador_da_esquerda pelo operador_da_direita e retorna o resultado. O parametro opcional escala é usado para configurar o número de dígitos depois do ponto decimal que serão mostrados no resultado.

Veja também bcmul().

bcmod

(PHP 3, PHP 4 )

bcmod --  Obter o módulo de um número com precisão arbitrária

Descrição

string bcmod ( string operador_da_esquerda, string modulo)

Obter o módulo do operador_da_esquerda usando modulo.

Veja também bcdiv().

bcmul

(PHP 3, PHP 4 )

bcmul -- Multiplicar dois números de precisão arbitrária

Descrição

string bcmul ( string operador_da_esquerda, string operador_da_direita [, int escala])

Multipica o operador_da_esquerda pelo operador_da_direita e retorna o resultado. O parametro opcional escala configura o número de dígitos depois do ponto decimal que serão mostrados no resultado.

Veja também bcdiv().

bcpow

(PHP 3, PHP 4 )

bcpow --  Elevar um número de precisão arbitrária a outro

Description

string bcpow ( string x, string y [, int escala])

Elevar x a potência de y. O parametro opcional escala configura o número de dígitos depois do ponto decimal que serão mostrados no resultado.

Veja também bcsqrt().

bcpowmod

(PHP 5 CVS only)

bcpowmod --  Raise an arbitrary precision number to another, reduced by a specified modulus.

Description

string bcpowmod ( string x, string y, string modulus [, int scale])

Use the fast-exponentiation method to raise x to the power y with respect to the modulus modulus. The optional scale can be used to set the number of digits after the decimal place in the result.

The following two statements are functionally identical. The bcpowmod() version however, executes in less time and can accept larger parameters.

<?php
$a = bcpowmod($x,$y,$mod);

$b = bcmod(bcpow($x,$y),$mod);

/* $a and $b are equal to each other. */
?>

Nota: Because this method uses the modulus operation, non-natural numbers may give unexpected results. A natural number is any positive non-zero integer.

See also bcpow(), and bcmod().

bcscale

(PHP 3, PHP 4 )

bcscale --  Configura o paramentro escala para todas as funções bc

Descrição

string bcscale ( int escala)

Esta função configura o padrão (default) para o parametro escala de todas as chamadas as funções bc math subsequentes. Este valor será utilizado caso o parametro escala não seja especificado em chamadas as bcmath subsequentes.

bcsqrt

(PHP 3, PHP 4 )

bcsqrt --  Obter a raiz quadrada de um número de precisão arbitrária

Descrição

string bcsqrt ( string operador [, int scale])

Retorna a raiz quadrada do operador. O parametro opcional escala configura o número de digitos depois do ponto decimal que serão mostrados no resultado.

See also bcpow().

bcsub

(PHP 3, PHP 4 )

bcsub --  Subtrair um número de precisão arbitrária de outro

Descrição

string bcsub ( string operador_da_esquerda, string operador_da_direita [, int escala])

Subtrair o operador_da_direita do operador_da_esquerda e retorna o resultado em uma string. O parametro opcional escala é usado para configurar o número de digitos depois do ponto decimal que serão mostrados no resultado.

Veja também bcadd().

V. Funções de compactação com Bzip2

Introdução

As funções para bzip2 são usadas para ler e escrever, de forma transparente, arquivos compactados do tipo bzip2 (.bz2).


Requisitos

Este módulo utiliza as funções da biblioteca bzip2 desenvolvida por Julian Seward


Instalação

O suporte às funções para Bzip2 no PHP não é habilitado por padrão. Você precisa usar a opção de configuração --with-bz2 quando for compilar o PHP para habilitar o suporte a bzip2. Este módulo requer bzip2/libbzip2, versão >= 1.0.x.


Configuração durante execução

Esta extenção não define nenhum parâmetro de configuração no php.ini.


Tipos Resource

Esta extensão define um tipo de recurso (resource): um ponteiro para arquivo que identifica o arquivo bzip2 que está sendo usado.


Constantes Predefinidas

Esta extensão não possui nenhuma constante.


Exemplos

Este exemplo abre um arquivo temporário e escreve uma string de test nele, e então mostra o conteúdo do arquivo.

Exemplo 1. Um exemplo simples de bzip2

<?php

$arquivo = "/tmp/testfile.bz2";
$str = "This is a test string.\n";

// abre o arquivo para escrita
$bz = bzopen($arquivo, "w");

// escreve a string no arquivo
bzwrite($bz, $str);

// fecha o arquivo
bzclose($bz);

// abre o arquivo para leitura
$bz = bzopen($arquivo, "r");

// lê 10 caracteres
print bzread($bz, 10);

// imprime até o final do arquivo (ou os próximos 1024 caracteres)  
print bzread($bz);

// fecha o arquivo
bzclose($bz);

?>
Índice
bzclose -- Fecha um ponteiro de arquivo bzip2
bzcompress -- Comprime uma string em dados no formato bzip2
bzdecompress -- Descomprime dados no formato bzip2
bzerrno -- Retorna um número de erro do bzip2
bzerror -- Retorna o número e string de erro do bzip2 como um array
bzerrstr -- Retorna a string de erro do bzip2
bzflush -- Força a escrita de todos os dados que estão no buffer
bzopen -- Abre um arquivo comprimido com bzip2
bzread -- Leitura binary-safe de um arquivo bzip2
bzwrite -- Escrita binary-safe em um arquivo bzip2

bzclose

(PHP 4 >= 4.0.4)

bzclose -- Fecha um ponteiro de arquivo bzip2

Descrição

int bzclose ( resource bz)

Fecha o arquivo bzip2 referenciado pelo ponteiro bz.

Retorna TRUE em caso de sucesso ou FALSE em falhas.

O ponteiro de arquivo deve ser válido, e deve apontar para um arquivo aberto com sucesso com bzopen().

Veja também bzopen().

bzcompress

(PHP 4 >= 4.0.4)

bzcompress -- Comprime uma string em dados no formato bzip2

Descrição

string bzcompress ( string source [, int blocksize [, int workfactor]])

bzcompress() comprime a string source e a retorna no formato de dados codificados com bzip2.

O parâmetro opcional blocksize especifica o tamanho do bloco utilizado no momento de compressão e deve ser um número de 1 a 9, com 9 sendo a melhor taxa de compressão, mas usando mais recursos para fazê-lo. O valor padrão de blocksize é 4.

O parâmetro opcional workfactor controla como a fase de compressão irá se comportar quando ocorrer o pior caso: a entrada de dados muito repetitivos. O seu valor pode ser de 0 até 250, com 0 sendo um caso especial, e 30 o valor padrão. Independente do valor de workfactor, a saída gerada será a mesma.

Exemplo 1. Exemplo de bzcompress()

<?php
$str = "demonstracao de dados comprimidos";
$bzstr = bzcompress($str, 9);
print($bzstr);
?>

Veja também bzdecompress().

bzdecompress

(PHP 4 >= 4.0.4)

bzdecompress -- Descomprime dados no formato bzip2

Descrição

string bzdecompress ( string source [, int small])

bzdecompress() descomprime a string source string contendo dados no formato bzip2 e retorna o seu valor. Se o parâmetro opcional small for TRUE, um algoritmo alternativo de descompressão, com a utilização de menos memória (a máxima quantidade de memória requerida é em torno de 2300K), será usado mas funciona com a metade da velocidade. Veja a documentação do bzip2 para mais informações sobre essa característica.

Exemplo 1. bzdecompress()

<?php
$start_str = "Esse cara é legal?";
$bzstr = bzcompress($start_str);

print( "String comprimida: " );
print( $bzstr );
print( "\n<br>\n" );

$str = bzdecompress($bzstr);
print( "String descomprimida: " );
print( $str );
print( "\n<br>\n" );
?>

Veja também bzcompress().

bzerrno

(PHP 4 >= 4.0.4)

bzerrno -- Retorna um número de erro do bzip2

Descrição

int bzerrno ( resource bz)

Retorna o número do erro de qualquer erro do bzip2 retornado pelo ponteiro de arquivo bz.

Veja também bzerror() e bzerrstr().

bzerror

(PHP 4 >= 4.0.4)

bzerror -- Retorna o número e string de erro do bzip2 como um array

Descrição

array bzerror ( resource bz)

Retorna o número e string do erro, em um array associativo, de qualquer erro retornado pelo ponteiro de arquivo bz.

Exemplo 1. Exemplo de bzerror()

<?php
$error = bzerror($bz);

echo $error["errno"];
echo $error["errstr"];
?>

Veja também bzerrno() e bzerrstr().

bzerrstr

(PHP 4 >= 4.0.4)

bzerrstr -- Retorna a string de erro do bzip2

Descrição

string bzerrstr ( resource bz)

Retorna a string de erro de qualquer erro retornado pelo ponteiro de arquivo bz.

Veja também bzerrno() e bzerror().

bzflush

(PHP 4 >= 4.0.4)

bzflush -- Força a escrita de todos os dados que estão no buffer

Descrição

int bzflush ( resource bz)

Força a escrita de todos os dados do bzip2 que estão em buffer para o ponteiro de arquivo bz.

Retorna TRUE em caso de sucesso ou FALSE em falhas.

Veja também bzread() e bzwrite().

bzopen

(PHP 4 >= 4.0.4)

bzopen -- Abre um arquivo comprimido com bzip2

Descrição

resource bzopen ( string filename, string mode)

Abre um arquivo bzip2 (.bz2) para leitura ou escrita. O parâmetro filename é o nome do arquivo a ser aberto. mode é similar ao da função fopen() (`r' para leitura, `w' para escrita, etc.).

Se esta função falhar, retorna FALSE, do contrário retorna um ponteiro de arquivo aberto.

Exemplo 1. Exemplo de bzopen()

<?php
$bz = bzopen("/tmp/foo.bz2", "r");
$arquivo_descomprimido = bzread($bz, filesize("/tmp/foo.bz2"));
bzclose($bz);

print( "O conteúdo de /tmp/foo.bz2 é: " );
print( "\n<br>\n" );
print( $arquivo_descomprimido );
?>

Veja também bzclose().

bzread

(PHP 4 >= 4.0.4)

bzread -- Leitura binary-safe de um arquivo bzip2

Descrição

string bzread ( resource bz [, int length])

bzread() lê o número de bytes equivalente a length do ponteiro de arquivo bzip2 referenciado por bz. A leitura pára quando a a quantidade de bytes referenciados por length (descomprimidos) foram lidos ou EOF foi alcançado, o que acontecer primeiro. Se o parâmetro opcional length não for especificado, bzread() irá ler 1024 bytes (descomprimidos) de cada vez.

Exemplo 1. Exemplo de bzread()

<?php
$bz = bzopen("/tmp/foo.bz2", "r");
$str = bzread($bz, 2048);
print( $str );
?>

Veja também bzwrite() e bzopen().

bzwrite

(PHP 4 >= 4.0.4)

bzwrite -- Escrita binary-safe em um arquivo bzip2

Descrição

int bzwrite ( resource bz, string data [, int length])

bzwrite() escreve o conteúdo da string data no arquivo referenciado pelo ponteiro de arquivo bzip2 bz. Se o parâmetro opcional length for passado, a escrita irá parar depois deste número de bytes (descomprimidos) foram escritos ou se o final da string foi alcançado, o que acontecer primeiro.

Exemplo 1. Exemplo de bzwrite()

<?php
$str = "dados descomprimidos";
$bz = bzopen("/tmp/foo.bz2", "w");
bzwrite($bz, $str, strlen($str));
bzclose($bz);
?>

Veja também bzread() e bzopen().

VI. Calendar functions

Introdução

The calendar extension presents a series of functions to simplify converting between different calendar formats. The intermediary or standard it is based on is the Julian Day Count. The Julian Day Count is a count of days starting from January 1st, 4713 B.C. To convert between calendar systems, you must first convert to Julian Day Count, then to the calendar system of your choice. Julian Day Count is very different from the Julian Calendar! For more information on Julian Day Count, visit http://serendipity.magnet.ch/hermetic/cal_stud/jdn.htm. For more information on calendar systems visit http://genealogy.org/~scottlee/cal-overview.html. Excerpts from this page are included in these instructions, and are in quotes.


Instalação

To get these functions to work, you have to compile PHP with --enable-calendar.

The windows version of PHP has built in support for this extension. You do not need to load any additional extension in order to use these functions.


Configuração durante execução

Esta extenção não define nenhum parâmetro de configuração no php.ini.


Tipos Resource

Esta extensão não possui nenhum tipo resource.


Constantes Predefinidas

As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.

CAL_GREGORIAN (integer)

CAL_JULIAN (integer)

CAL_JEWISH (integer)

CAL_FRENCH (integer)

CAL_NUM_CALS (integer)

CAL_DOW_DAYNO (integer)

CAL_DOW_SHORT (integer)

CAL_DOW_LONG (integer)

CAL_MONTH_GREGORIAN_SHORT (integer)

CAL_MONTH_GREGORIAN_LONG (integer)

CAL_MONTH_JULIAN_SHORT (integer)

CAL_MONTH_JULIAN_LONG (integer)

CAL_MONTH_JEWISH (integer)

CAL_MONTH_FRENCH (integer)

The following constants are available since PHP 4.3.0 :

CAL_EASTER_DEFAULT (integer)

CAL_EASTER_ROMAN (integer)

CAL_EASTER_ALWAYS_GREGORIAN (integer)

CAL_EASTER_ALWAYS_JULIAN (integer)

Índice
cal_days_in_month -- Return the number of days in a month for a given year and calendar
cal_from_jd -- Converts from Julian Day Count to a supported calendar and return extended information
cal_info -- Returns information about a particular calendar
cal_to_jd -- Converts from a supported calendar to Julian Day Count
easter_date --  Get UNIX timestamp for midnight on Easter of a given year
easter_days --  Get number of days after March 21 on which Easter falls for a given year
FrenchToJD --  Converts a date from the French Republican Calendar to a Julian Day Count
GregorianToJD --  Converts a Gregorian date to Julian Day Count
JDDayOfWeek -- Returns the day of the week
JDMonthName -- Returns a month name
JDToFrench --  Converts a Julian Day Count to the French Republican Calendar
JDToGregorian -- Converts Julian Day Count to Gregorian date
JDToJewish --  Converts a Julian Day Count to the Jewish Calendar
JDToJulian --  Converts a Julian Day Count to a Julian Calendar Date
jdtounix -- Convert Julian Day to UNIX timestamp
JewishToJD --  Converts a date in the Jewish Calendar to Julian Day Count
JulianToJD --  Converts a Julian Calendar date to Julian Day Count
unixtojd -- Convert UNIX timestamp to Julian Day

cal_days_in_month

(PHP 4 >= 4.1.0)

cal_days_in_month -- Return the number of days in a month for a given year and calendar

Description

int cal_days_in_month ( int calendar, int month, int year)

This function will return the number of days in the month of year for the specified calendar.

See also jdtounix().

cal_from_jd

(PHP 4 >= 4.1.0)

cal_from_jd -- Converts from Julian Day Count to a supported calendar and return extended information

Description

array cal_from_jd ( int jd, int calendar)

Atenção

Esta função não está documentada, somente a lista de argumentos está disponível.

cal_info

(PHP 4 >= 4.1.0)

cal_info -- Returns information about a particular calendar

Description

array cal_info ( int calendar)

Atenção

Esta função não está documentada, somente a lista de argumentos está disponível.

cal_to_jd

(PHP 4 >= 4.1.0)

cal_to_jd -- Converts from a supported calendar to Julian Day Count

Description

int cal_to_jd ( int calendar, int month, int day, int year)

Atenção

Esta função não está documentada, somente a lista de argumentos está disponível.

easter_date

(PHP 3>= 3.0.9, PHP 4 )

easter_date --  Get UNIX timestamp for midnight on Easter of a given year

Description

int easter_date ( [int year])

Returns the UNIX timestamp corresponding to midnight on Easter of the given year.

Since PHP 4.3.0, the year parameter is optional and defaults to the current year according to the localtime if ommited.

Warning: This function will generate a warning if the year is outside of the range for UNIX timestamps (i.e. before 1970 or after 2037).

Exemplo 1. easter_date() example

echo date ("M-d-Y", easter_date(1999));        /* "Apr-04-1999" */
echo date ("M-d-Y", easter_date(2000));        /* "Apr-23-2000" */
echo date ("M-d-Y", easter_date(2001));        /* "Apr-15-2001" */

The date of Easter Day was defined by the Council of Nicaea in AD325 as the Sunday after the first full moon which falls on or after the Spring Equinox. The Equinox is assumed to always fall on 21st March, so the calculation reduces to determining the date of the full moon and the date of the following Sunday. The algorithm used here was introduced around the year 532 by Dionysius Exiguus. Under the Julian Calendar (for years before 1753) a simple 19-year cycle is used to track the phases of the Moon. Under the Gregorian Calendar (for years after 1753 - devised by Clavius and Lilius, and introduced by Pope Gregory XIII in October 1582, and into Britain and its then colonies in September 1752) two correction factors are added to make the cycle more accurate.

(The code is based on a C program by Simon Kershaw, <webmaster@ely.anglican.org>)

See easter_days() for calculating Easter before 1970 or after 2037.

easter_days

(PHP 3>= 3.0.9, PHP 4 )

easter_days --  Get number of days after March 21 on which Easter falls for a given year

Description

int easter_days ( [int year [, int method]])

Returns the number of days after March 21 on which Easter falls for a given year. If no year is specified, the current year is assumed.

Since PHP 4.3.0, the year parameter is optional and defaults to the current year according to the localtime if ommited.

The method parameter was also introduced in PHP 4.3.0 and allows to calculate easter dates based on the Gregorian calendar during the years 1582 - 1752 when set to CAL_EASTER_ROMAN. See the calendar constants for more valid constants.

This function can be used instead of easter_date() to calculate Easter for years which fall outside the range of UNIX timestamps (i.e. before 1970 or after 2037).

Exemplo 1. easter_days() example

echo easter_days (1999);        /* 14, i.e. April 4   */
echo easter_days (1492);        /* 32, i.e. April 22  */
echo easter_days (1913);        /*  2, i.e. March 23  */

The date of Easter Day was defined by the Council of Nicaea in AD325 as the Sunday after the first full moon which falls on or after the Spring Equinox. The Equinox is assumed to always fall on 21st March, so the calculation reduces to determining the date of the full moon and the date of the following Sunday. The algorithm used here was introduced around the year 532 by Dionysius Exiguus. Under the Julian Calendar (for years before 1753) a simple 19-year cycle is used to track the phases of the Moon. Under the Gregorian Calendar (for years after 1753 - devised by Clavius and Lilius, and introduced by Pope Gregory XIII in October 1582, and into Britain and its then colonies in September 1752) two correction factors are added to make the cycle more accurate.

(The code is based on a C program by Simon Kershaw, <webmaster@ely.anglican.org>)

See also easter_date().

FrenchToJD

(PHP 3, PHP 4 )

FrenchToJD --  Converts a date from the French Republican Calendar to a Julian Day Count

Description

int frenchtojd ( int month, int day, int year)

Converts a date from the French Republican Calendar to a Julian Day Count.

These routines only convert dates in years 1 through 14 (Gregorian dates 22 September 1792 through 22 September 1806). This more than covers the period when the calendar was in use.

GregorianToJD

(PHP 3, PHP 4 )

GregorianToJD --  Converts a Gregorian date to Julian Day Count

Description

int gregoriantojd ( int month, int day, int year)

Valid Range for Gregorian Calendar 4714 B.C. to 9999 A.D.

Although this function can handle dates all the way back to 4714 B.C., such use may not be meaningful. The Gregorian calendar was not instituted until October 15, 1582 (or October 5, 1582 in the Julian calendar). Some countries did not accept it until much later. For example, Britain converted in 1752, The USSR in 1918 and Greece in 1923. Most European countries used the Julian calendar prior to the Gregorian.

Exemplo 1. Calendar functions

<?php
$jd = GregorianToJD (10,11,1970);
echo "$jd\n";
$gregorian = JDToGregorian ($jd);
echo "$gregorian\n";
?>

JDDayOfWeek

(PHP 3, PHP 4 )

JDDayOfWeek -- Returns the day of the week

Description

mixed jddayofweek ( int julianday, int mode)

Returns the day of the week. Can return a string or an integer depending on the mode.

Tabela 1. Calendar week modes

Mode Meaning
0 Returns the day number as an int (0=sunday, 1=monday, etc)
1 Returns string containing the day of week (english-gregorian)
2 Returns a string containing the abbreviated day of week (english-gregorian)

JDMonthName

(PHP 3, PHP 4 )

JDMonthName -- Returns a month name

Description

string jdmonthname ( int julianday, int mode)

Returns a string containing a month name. mode tells this function which calendar to convert the Julian Day Count to, and what type of month names are to be returned.

Tabela 1. Calendar modes

Mode Meaning Values
0 Gregorian - abbreviated Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
1 Gregorian January, February, March, April, May, June, July, August, September, October, November, December
2 Julian - abbreviated Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
3 Julian January, February, March, April, May, June, July, August, September, October, November, December
4 Jewish Tishri, Heshvan, Kislev, Tevet, Shevat, AdarI, AdarII, Nisan, Iyyar, Sivan, Tammuz, Av, Elul
5 French Republican Vendemiaire, Brumaire, Frimaire, Nivose, Pluviose, Ventose, Germinal, Floreal, Prairial, Messidor, Thermidor, Fructidor, Extra

JDToFrench

(PHP 3, PHP 4 )

JDToFrench --  Converts a Julian Day Count to the French Republican Calendar

Description

string jdtofrench ( int juliandaycount)

Converts a Julian Day Count to the French Republican Calendar.

JDToGregorian

(PHP 3, PHP 4 )

JDToGregorian -- Converts Julian Day Count to Gregorian date

Description

string jdtogregorian ( int julianday)

Converts Julian Day Count to a string containing the Gregorian date in the format of "month/day/year".

JDToJewish

(PHP 3, PHP 4 )

JDToJewish --  Converts a Julian Day Count to the Jewish Calendar

Description

string jdtojewish ( int julianday)

Converts a Julian Day Count the the Jewish Calendar.

JDToJulian

(PHP 3, PHP 4 )

JDToJulian --  Converts a Julian Day Count to a Julian Calendar Date

Description

string jdtojulian ( int julianday)

Converts Julian Day Count to a string containing the Julian Calendar Date in the format of "month/day/year".

jdtounix

(PHP 4 )

jdtounix -- Convert Julian Day to UNIX timestamp

Description

int jdtounix ( int jday)

This function will return a UNIX timestamp corresponding to the Julian Day given in jday or FALSE if jday is not inside the UNIX epoch (Gregorian years between 1970 and 2037 or 2440588 <= jday <= 2465342 ). The time returned is localtime (and not GMT).

See also unixtojd().

JewishToJD

(PHP 3, PHP 4 )

JewishToJD --  Converts a date in the Jewish Calendar to Julian Day Count

Description

int jewishtojd ( int month, int day, int year)

Although this function can handle dates all the way back to the year 1 (3761 B.C.), such use may not be meaningful. The Jewish calendar has been in use for several thousand years, but in the early days there was no formula to determine the start of a month. A new month was started when the new moon was first observed.

JulianToJD

(PHP 3, PHP 4 )

JulianToJD --  Converts a Julian Calendar date to Julian Day Count

Description

int juliantojd ( int month, int day, int year)

Valid Range for Julian Calendar 4713 B.C. to 9999 A.D.

Although this function can handle dates all the way back to 4713 B.C., such use may not be meaningful. The calendar was created in 46 B.C., but the details did not stabilize until at least 8 A.D., and perhaps as late at the 4th century. Also, the beginning of a year varied from one culture to another - not all accepted January as the first month.

Cuidado

Remember, the current calendar system being used worldwide is the Gregorian calendar. gregoriantojd() can be used to convert such dates to their Julian Day count.

unixtojd

(PHP 4 )

unixtojd -- Convert UNIX timestamp to Julian Day

Description

int unixtojd ( [int timestamp])

Return the Julian Day for a UNIX timestamp (seconds since 1.1.1970), or for the current day if no timestamp is given.

See also jdtounix().

VII. CCVS API Functions

Introdução

These functions interface the CCVS API, allowing you to work directly with CCVS from your PHP scripts. CCVS is RedHat's solution to the "middle-man" in credit card processing. It lets you directly address the credit card clearing houses via your *nix box and a modem. Using the CCVS module for PHP, you can process credit cards directly through CCVS via your PHP Scripts. The following references will outline the process.

Nota: CCVS has been discontinued by Red Hat and there are no plans to issue further keys or support contracts. Those looking for a replacement can consider MCVE by Main Street Softworks as a potential replacement. It is similar in design and has documented PHP support!


Instalação

To enable CCVS Support in PHP, first verify your CCVS installation directory. You will then need to configure PHP with the --with-ccvs option. If you use this option without specifying the path to your CCVS installation, PHP will attempt to look in the default CCVS Install location (/usr/local/ccvs). If CCVS is in a non-standard location, run configure with: --with-ccvs=$ccvs_path, where $ccvs_path is the path to your CCVS installation. Please note that CCVS support requires that $ccvs_path/lib and $ccvs_path/include exist, and include cv_api.h under the include directory and libccvs.a under the lib directory.

Additionally, a ccvsd process will need to be running for the configurations you intend to use in your PHP scripts. You will also need to make sure the PHP Processes are running under the same user as your CCVS was installed as (e.g. if you installed CCVS as user 'ccvs', your PHP processes must run as 'ccvs' as well.)


Veja Também

Additional information about CCVS can be found at http://www.redhat.com/products/ccvs. RedHat maintains slightly outdated but still useful documentation at http://www.redhat.com/products/ccvs/support/CCVS3.3docs/ProgPHP.html.

Índice
ccvs_add -- Add data to a transaction
ccvs_auth --  Perform credit authorization test on a transaction
ccvs_command --  Performs a command which is peculiar to a single protocol, and thus is not available in the general CCVS API
ccvs_count --  Find out how many transactions of a given type are stored in the system
ccvs_delete -- Delete a transaction
ccvs_done -- Terminate CCVS engine and do cleanup work
ccvs_init -- Initialize CCVS for use
ccvs_lookup --  Look up an item of a particular type in the database #
ccvs_new -- Create a new, blank transaction
ccvs_report -- Return the status of the background communication process
ccvs_return --  Transfer funds from the merchant to the credit card holder
ccvs_reverse --  Perform a full reversal on an already-processed authorization
ccvs_sale --  Transfer funds from the credit card holder to the merchant
ccvs_status -- Check the status of an invoice
ccvs_textvalue -- Get text return value for previous function call
ccvs_void --  Perform a full reversal on a completed transaction

ccvs_add

(4.0.2 - 4.2.3 only)

ccvs_add -- Add data to a transaction

Description

string ccvs_add ( string session, string invoice, string argtype, string argval)

Atenção

Esta função não está documentada, somente a lista de argumentos está disponível.

ccvs_auth

(4.0.2 - 4.2.3 only)

ccvs_auth --  Perform credit authorization test on a transaction

Description

string ccvs_auth ( string session, string invoice)

Atenção

Esta função não está documentada, somente a lista de argumentos está disponível.

ccvs_command

(4.0.2 - 4.2.3 only)

ccvs_command --  Performs a command which is peculiar to a single protocol, and thus is not available in the general CCVS API

Description

string ccvs_command ( string session, string type, string argval)

Atenção

Esta função não está documentada, somente a lista de argumentos está disponível.

ccvs_count

(4.0.2 - 4.2.3 only)

ccvs_count --  Find out how many transactions of a given type are stored in the system

Description

int ccvs_count ( string session, string type)

Atenção

Esta função não está documentada, somente a lista de argumentos está disponível.

ccvs_delete

(4.0.2 - 4.2.3 only)

ccvs_delete -- Delete a transaction

Description

string ccvs_delete ( string session, string invoice)

Atenção

Esta função não está documentada, somente a lista de argumentos está disponível.

ccvs_done

(4.0.2 - 4.2.3 only)

ccvs_done -- Terminate CCVS engine and do cleanup work

Description

string ccvs_done ( string sess)

Atenção

Esta função não está documentada, somente a lista de argumentos está disponível.

ccvs_init

(4.0.2 - 4.2.3 only)

ccvs_init -- Initialize CCVS for use

Description

string ccvs_init ( string name)

Atenção

Esta função não está documentada, somente a lista de argumentos está disponível.

ccvs_lookup

(4.0.2 - 4.2.3 only)

ccvs_lookup --  Look up an item of a particular type in the database #

Description

string ccvs_lookup ( string session, string invoice, int inum)

Atenção

Esta função não está documentada, somente a lista de argumentos está disponível.

ccvs_new

(4.0.2 - 4.2.3 only)

ccvs_new -- Create a new, blank transaction

Description

string ccvs_new ( string session, string invoice)

Atenção

Esta função não está documentada, somente a lista de argumentos está disponível.

ccvs_report

(4.0.2 - 4.2.3 only)

ccvs_report -- Return the status of the background communication process

Description

string ccvs_report ( string session, string type)

Atenção

Esta função não está documentada, somente a lista de argumentos está disponível.

ccvs_return

(4.0.2 - 4.2.3 only)

ccvs_return --  Transfer funds from the merchant to the credit card holder

Description

string ccvs_return ( string session, string invoice)

Atenção

Esta função não está documentada, somente a lista de argumentos está disponível.

ccvs_reverse

(4.0.2 - 4.2.3 only)

ccvs_reverse --  Perform a full reversal on an already-processed authorization

Description

string ccvs_reverse ( string session, string invoice)

Atenção

Esta função não está documentada, somente a lista de argumentos está disponível.

ccvs_sale

(4.0.2 - 4.2.3 only)

ccvs_sale --  Transfer funds from the credit card holder to the merchant

Description

string ccvs_sale ( string session, string invoice)

Atenção

Esta função não está documentada, somente a lista de argumentos está disponível.

ccvs_status

(4.0.2 - 4.2.3 only)

ccvs_status -- Check the status of an invoice

Description

string ccvs_status ( string session, string invoice)

Atenção

Esta função não está documentada, somente a lista de argumentos está disponível.

ccvs_textvalue

(4.0.2 - 4.2.3 only)

ccvs_textvalue -- Get text return value for previous function call

Description

string ccvs_textvalue ( string session)

Atenção

Esta função não está documentada, somente a lista de argumentos está disponível.

ccvs_void

(4.0.2 - 4.2.3 only)

ccvs_void --  Perform a full reversal on a completed transaction

Description

string ccvs_void ( string session, string invoice)

Atenção

Esta função não está documentada, somente a lista de argumentos está disponível.

VIII. COM support functions for Windows

Introdução

COM is a technology which allows the reuse of code written in any language (by any language) using a standard calling convention and hiding behind APIs the implementation details such as what machine the Component is stored on and the executable which houses it. It can be thought of as a super Remote Procedure Call (RPC) mechanism with some basic object roots. It separates implementation from interface.

COM encourages versioning, separation of implementation from interface and hiding the implementation details such as executable location and the language it was written in.


Requisitos

COM functions are only available on the Windows version of PHP.


Instalação

Não há nenhuma instalação nescessária para utilizar estas funções, elas fazem parte do núcleo do PHP.

The windows version of PHP has built in support for this extension. You do not need to load any additional extension in order to use these functions.


Configuração durante execução

O comportamento dessas funções podem ser modificado pelas configurações do php.ini.

Tabela 1. Com configuration options

Name Default Changeable
com.allow_dcom "0" PHP_INI_SYSTEM
com.autoregister_typelib "0" PHP_INI_SYSTEM
com.autoregister_verbose "0" PHP_INI_SYSTEM
com.autoregister_casesensitive "1" PHP_INI_SYSTEM
com.typelib_file "" PHP_INI_SYSTEM
For further details and definition of the PHP_INI_* constants see ini_set().


Constantes Predefinidas

As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.

CLSCTX_INPROC_SERVER (integer)

CLSCTX_INPROC_HANDLER (integer)

CLSCTX_LOCAL_SERVER (integer)

CLSCTX_REMOTE_SERVER (integer)

CLSCTX_SERVER (integer)

CLSCTX_ALL (integer)

VT_NULL (integer)

VT_EMPTY (integer)

VT_UI1 (integer)

VT_I2 (integer)

VT_I4 (integer)

VT_R4 (integer)

VT_R8 (integer)

VT_BOOL (integer)

VT_ERROR (integer)

VT_CY (integer)

VT_DATE (integer)

VT_BSTR (integer)

VT_DECIMAL (integer)

VT_UNKNOWN (integer)

VT_DISPATCH (integer)

VT_VARIANT (integer)

VT_I1 (integer)

VT_UI2 (integer)

VT_UI4 (integer)

VT_INT (integer)

VT_UINT (integer)

VT_ARRAY (integer)

VT_BYREF (integer)

CP_ACP (integer)

CP_MACCP (integer)

CP_OEMCP (integer)

CP_UTF7 (integer)

CP_UTF8 (integer)

CP_SYMBOL (integer)

CP_THREAD_ACP (integer)


Veja Também

For further information on COM read the COM specification or perhaps take a look at Don Box's Yet Another COM Library (YACL)

Índice
COM -- COM class
VARIANT -- VARIANT class
com_addref --  Increases the components reference counter.
com_get --  Gets the value of a COM Component's property
com_invoke --  Calls a COM component's method.
com_isenum -- Grabs an IEnumVariant
com_load_typelib -- Loads a Typelib
com_load --  Creates a new reference to a COM component
com_propget --  Gets the value of a COM Component's property
com_propput --  Assigns a value to a COM component's property
com_propset --  Assigns a value to a COM component's property
com_release --  Decreases the components reference counter.
com_set --  Assigns a value to a COM component's property

COM

(no version information, might be only in CVS)

COM -- COM class

Sinopse

$obj = new COM("server.object")

Description

The COM class provides a framework to integrate (D)COM components into your php scripts.

Methods

string COM::COM ( string module_name [, string server_name [, int codepage]])

COM class constructor. Parameters:

module_name

name or class-id of the requested component.

server_name

name of the DCOM server from which the component should be fetched. If NULL, localhost is assumed. To allow DCOM com.allow_dcom has to be set to TRUE in php.ini.

codepage

specifies the codepage that is used to convert php-strings to unicode-strings and vice versa. Possible values are CP_ACP, CP_MACCP, CP_OEMCP, CP_SYMBOL, CP_THREAD_ACP, CP_UTF7 and CP_UTF8.

Exemplo 1. COM example (1)

// starting word
$word = new COM("word.application") or die("Unable to instanciate Word");
print "Loaded Word, version {$word->Version}\n";

//bring it to front
$word->Visible = 1;

//open an empty document
$word->Documents->Add();

//do some weird stuff
$word->Selection->TypeText("This is a test...");
$word->Documents[1]->SaveAs("Useless test.doc");

//closing word
$word->Quit();

//free the object
$word->Release();
$word = null;

Exemplo 2. COM example (2)

$conn = new COM("ADODB.Connection") or die("Cannot start ADO");
$conn->Open("Provider=SQLOLEDB; Data Source=localhost;
Initial Catalog=database; User ID=user; Password=password");

$rs = $conn->Execute("SELECT * FROM sometable");    // Recordset

$num_columns = $rs->Fields->Count();
echo $num_columns . "\n";

for ($i=0; $i < $num_columns; $i++)
{
    $fld[$i] = $rs->Fields($i);
}

$rowcount = 0;
while (!$rs->EOF)
{
    for ($i=0; $i < $num_columns; $i++)
    {
        echo $fld[$i]->value . "\t";
    }
    echo "\n";
    $rowcount++;            // increments rowcount
    $rs->MoveNext();
}

$rs->Close();
$conn->Close();

$rs->Release();
$conn->Release();

$rs = null;
$conn = null;

VARIANT

(no version information, might be only in CVS)

VARIANT -- VARIANT class

Sinopse

$vVar = new VARIANT($var)

Description

A simple container to wrap variables into VARIANT structures.

Methods

string VARIANT::VARIANT ( [mixed value [, int type [, int codepage]]])

VARIANT class constructor. Parameters:

value

initial value. if omitted an VT_EMPTY object is created.

type

specifies the content type of the VARIANT object. Possible values are VT_UI1, VT_UI2, VT_UI4, VT_I1, VT_I2, VT_I4, VT_R4, VT_R8, VT_INT, VT_UINT, VT_BOOL, VT_ERROR, VT_CY, VT_DATE, VT_BSTR, VT_DECIMAL, VT_UNKNOWN, VT_DISPATCH and VT_VARIANT. These values are mutual exclusive, but they can be combined with VT_BYREF to specify being a value. If omitted, the type of value is used. Consult the msdn library for additional information.

codepage

specifies the codepage that is used to convert php-strings to unicode-strings and vice versa. Possible values are CP_ACP, CP_MACCP, CP_OEMCP, CP_SYMBOL, CP_THREAD_ACP, CP_UTF7 and CP_UTF8.

com_addref

(4.1.0 - 4.3.0 only)

com_addref --  Increases the components reference counter.

Description

void com_addref ( void)

Increases the components reference counter.

com_get

(PHP 3>= 3.0.3, 4.0.5 - 4.3.0 only)

com_get --  Gets the value of a COM Component's property

Description

mixed com_get ( resource com_object, string property)

Returns the value of the property of the COM component referenced by com_object. Returns FALSE on error.

com_invoke

(PHP 3>= 3.0.3)

com_invoke --  Calls a COM component's method.

Description

mixed com_invoke ( resource com_object, string function_name [, mixed function parameters, ...])

com_invoke() invokes a method of the COM component referenced by com_object. Returns FALSE on error, returns the function_name's return value on success.

com_isenum

(4.1.0 - 4.3.0 only)

com_isenum -- Grabs an IEnumVariant

Description

void com_isenum ( object com_module)

Atenção

Esta função não está documentada, somente a lista de argumentos está disponível.

com_load_typelib

(4.1.0 - 4.3.0 only)

com_load_typelib -- Loads a Typelib

Description

void com_load_typelib ( string typelib_name [, int case_insensitive])

Atenção

Esta função não está documentada, somente a lista de argumentos está disponível.

com_load

(PHP 3>= 3.0.3)

com_load --  Creates a new reference to a COM component

Description

string com_load ( string module name [, string server name [, int codepage]])

com_load() creates a new COM component and returns a reference to it. Returns FALSE on failure. Possible values for codepage are CP_ACP, CP_MACCP, CP_OEMCP, CP_SYMBOL, CP_THREAD_ACP, CP_UTF7 and CP_UTF8.

com_propget

(PHP 3>= 3.0.3, 4.0.5 - 4.3.0 only)

com_propget --  Gets the value of a COM Component's property

Description

mixed com_propget ( resource com_object, string property)

This function is an alias for com_get().

com_propput

(PHP 3>= 3.0.3, 4.0.5 - 4.3.0 only)

com_propput --  Assigns a value to a COM component's property

Description

void com_propput ( resource com_object, string property, mixed value)

This function is an alias for com_set().

com_propset

(PHP 3>= 3.0.3, 4.0.5 - 4.3.0 only)

com_propset --  Assigns a value to a COM component's property

Description

void com_propset ( resource com_object, string property, mixed value)

This function is an alias for com_set().

com_release

(4.1.0 - 4.3.0 only)

com_release --  Decreases the components reference counter.

Description

void com_release ( void)

Decreases the components reference counter.

com_set

(PHP 3>= 3.0.3, 4.0.5 - 4.3.0 only)

com_set --  Assigns a value to a COM component's property

Description

void com_set ( resource com_object, string property, mixed value)

Sets the value of the property of the COM component referenced by com_object. Returns the newly set value if succeeded, FALSE on error.

IX. Classes e Objetos

Introdução

Estas funções permitem obter informações sobre classes e instâncias de objetos. Você pode obter o nome da classe ao qual um objeto pertence, bem como suas propriedades e métodos. Usando estas funções, você pode descobrir não apenas a classe de um objeto, mas também seu parentesco (no caso, de qual objeto de classe ele extende).


Exemplos

Neste exemplo, nós primeiramente definiremos uma classe base e uma extensão da classe. A classe base descreve um vegetal comum, que é comestível ou não e que tem sua cor. A sub-classe Espinafre adiciona um método para cozinhá-lo e outro para descobrir se ele está cozido.

Exemplo 1. classes.inc

<?php

// base class with member properties and methods
class Vegetable {

    var $edible;
    var $color;

    function Vegetable( $edible, $color="green" ) {
        $this->edible = $edible;
        $this->color = $color;
    }

    function is_edible() {
        return $this->edible;
    }

    function what_color() {
        return $this->color;
    }
    
} // end of class Vegetable

// extends the base class
class Spinach extends Vegetable {

    var $cooked = false;

    function Spinach() {
        $this->Vegetable( true, "green" );
    }

    function cook_it() {
        $this->cooked = true;
    }

    function is_cooked() {
        return $this->cooked;
    }
    
} // end of class Spinach

?>

Nós instânciamos 2 objetos destas classes e exibimos informações sobre elas, incluindo o parentesco de suas classes. Nós também definimos algumas funções úteis, principalmente ter uma boa saída de variáveis.

Exemplo 2. test_script.php

<pre>
<?php

include "classes.inc";

// utility functions

function print_vars($obj) {
    $arr = get_object_vars($obj);
    while (list($prop, $val) = each($arr))
        echo "\t$prop = $val\n";
}

function print_methods($obj) {
    $arr = get_class_methods(get_class($obj));
    foreach ($arr as $method)
        echo "\tfunction $method()\n";
}

function class_parentage($obj, $class) {
    global $$obj;
    if (is_subclass_of($$obj, $class)) {
        echo "Object $obj belongs to class ".get_class($$obj);
        echo " a subclass of $class\n";
    } else {
        echo "Object $obj does not belong to a subclass of $class\n";
    }
}

// instantiate 2 objects

$veggie = new Vegetable(true,"blue");
$leafy = new Spinach();

// print out information about objects
echo "veggie: CLASS ".get_class($veggie)."\n";
echo "leafy: CLASS ".get_class($leafy);
echo ", PARENT ".get_parent_class($leafy)."\n";

// show veggie properties
echo "\nveggie: Properties\n";
print_vars($veggie);

// and leafy methods
echo "\nleafy: Methods\n";
print_methods($leafy);

echo "\nParentage:\n";
class_parentage("leafy", "Spinach");
class_parentage("leafy", "Vegetable");
?>
</pre>

Uma coisa importante para notar no exemplo acima é que o objeto $leafy é uma instância da classe Espinafre que é uma subclasse de Vegetal, então a última parte do script acima retornará:

[...]
Parentage:
Object leafy does not belong to a subclass of Spinach
Object leafy belongs to class spinach a subclass of Vegetable

Índice
call_user_method_array --  Chama métodos de usuário dado uma matriz de parâmetros [obsoleto]
call_user_method --  Chama um método de usuário num objeto específico [obsoleto]
class_exists -- Checa se uma classe foi definida
get_class_methods -- Retorna uma matriz associativa com nomes de métodos da classe
get_class_vars --  Retorna uma matriz das propriedades padrão da classe
get_class -- Retorna o nome da classe de um objeto
get_declared_classes -- Retorna uma matriz com os nomes das classes definidas
get_object_vars -- Retorna uma matriz associativa com as propriedades do objeto
get_parent_class -- Devolve o nome da classe pai para o objeto ou classe
is_a --  Retorna TRUE se o objeto é desta classe ou tem esta classe como uma de suas classes pai.
is_subclass_of --  Retorna TRUE se o objeto tem esta classe como uma de suas classes pai
method_exists -- Checa se o método da classe existe

call_user_method_array

(PHP 4 >= 4.0.5)

call_user_method_array --  Chama métodos de usuário dado uma matriz de parâmetros [obsoleto]

Descrição

mixed call_user_method_array ( string method_name, object obj [, array paramarr])

Atenção

A funçãocall_user_method_array() é obselta a partir do PHP 4.1.0. Utilize a variante call_user_func_array() com a sintaxe array(&$obj, "method_name").

Chama o método method_name do objeto de usuáro obj, usando os parâmetros em paramarr.

Veja também call_user_func_array(), call_user_func() e call_user_method().

Nota: Esta função foi adicionada no código CVS antes da liberaçao do PHP 4.0.4pl1

call_user_method

(PHP 3>= 3.0.3, PHP 4 )

call_user_method --  Chama um método de usuário num objeto específico [obsoleto]

Descrição

mixed call_user_method ( string method_name, object obj [, mixed parameter [, mixed ...]])

Atenção

A função call_user_method() é obsoleta desde o PHP 4.1.0, portanto utilize a variante call_user_func() com a sintaxe array(&$obj, "method_name").

Chama o método method_name do objeto de usuário obj. Um exemplo de seu uso segue abaixo, onde nós definimos uma classe, instanciamos um objeto e usamos call_user_method() para chamar indiretamente seu método print_info.

<?php
class Country {
    var $NAME;
    var $TLD;

    function Country($name, $tld) {
        $this->NAME = $name;
        $this->TLD = $tld;
    }

    function print_info($prestr="") {
        echo $prestr."Country: ".$this->NAME."\n";
        echo $prestr."Top Level Domain: ".$this->TLD."\n";
    }
}

$cntry = new Country("Peru","pe");

echo "* Chamando o método diretamente\n";
$cntry->print_info();

echo "\n* Chamando o método indiretamente\n";
call_user_method ("print_info", $cntry, "\t");
?>

Veja também call_user_func_array(), call_user_func() e call_user_method_array().

class_exists

(PHP 4 )

class_exists -- Checa se uma classe foi definida

Descrição

bool class_exists ( string class_name)

Esta função retorna TRUE se a classe dada por class_name foi definida, caso contrário retorna FALSE.

get_class_methods

(PHP 4 )

get_class_methods -- Retorna uma matriz associativa com nomes de métodos da classe

Descrição

array get_class_methods ( mixed class_name)

Esta função retorna uma matriz com nomes dos métodos definidos para a classe especificada por class_name.

Nota: A partir do PHP 4.0.6, você pode especificar o próprio objeto em vez no nome da classe em class_name. Por exemplo:

$class_methods = get_class_methods($my_class); // veja um exemplo completo abaixo

Exemplo 1. Exemploget_class_methods()

<?php

class myclass {
    // constructor
    function myclass() {
        return(TRUE);
    }

    // method 1
    function myfunc1() {
        return(TRUE);
    }

    // method 2
    function myfunc2() {
        return(TRUE);
    }
}

$my_object = new myclass();

$class_methods = get_class_methods(get_class($my_object));

foreach ($class_methods as $method_name) {
    echo "$method_name\n";
}

?>

Produzirá:

myclass
myfunc1
myfunc2

Veja também get_class_vars() e get_object_vars().

get_class_vars

(PHP 4 )

get_class_vars --  Retorna uma matriz das propriedades padrão da classe

Descrição

array get_class_vars ( string class_name)

Esta função retornará uma matriz associativa com as propriedades padrão da classe. Os elementos resultantes da matriz estão na forma nome_variavel => valor.

Nota: Variáveis de classe não iniciadas não serão exibidos por get_class_vars().

Exemplo 1. Exemplo get_class_vars()

<?php

class myclass {

    var $var1; // esta não tem valor default...
    var $var2 = "xyz";
    var $var3 = 100;

    // construtor
    function myclass() {
        return(TRUE);
    }

}

$my_class = new myclass();

$class_vars = get_class_vars(get_class($my_class));

foreach ($class_vars as $name => $value) {
    echo "$name : $value\n";
}

?>

Produzirá:

var2 : xyz
var3 : 100

Veja também get_class_methods() e get_object_vars()

get_class

(PHP 4 )

get_class -- Retorna o nome da classe de um objeto

Descrição

string get_class ( object obj)

Esta função retorna o nome da classe da qual o objeto obj é instância. Retorna FALSE se obj não é um objeto.

Nota: get_class() retorna um nome de uma classe definida pelo usuário em minúsculas. Uma classe definida em uma extensão do PHP é retornada em sua notação original.

Veja também get_parent_class(), gettype() e is_subclass_of().

get_declared_classes

(PHP 4 )

get_declared_classes -- Retorna uma matriz com os nomes das classes definidas

Descrição

array get_declared_classes ( void)

Esta função retorna uma matriz com os nomes das classes declaradas no script em execução.

Nota: A partir do PHP 4.0.1pl2, três classes extras são retornadas no início da matriz: stdClass (definida em Zend/zend.c), OverloadedTestClass (definida em ext/standard/basic_functions.c) e Directory (definida em ext/standard/dir.c).

Note também que, dependendo de quais bibliotecas você tenha compilado no PHP, classes adicionais poderão estar presentes. Isto significa que você não será capaz de distinguir suas próprias classes usando estes nomes. Há uma lista de classes predefinidas na seção Classes Predefinidas dos apêndices.

get_object_vars

(PHP 4 )

get_object_vars -- Retorna uma matriz associativa com as propriedades do objeto

Descrição

array get_object_vars ( object obj)

Esta função retorna uma matriz associativa com as propriedades definidas do objeto informado em obj. Se variáveis declaradas na classe de qual obj é uma instância e que não tenham valores assimilados, esses não serão retornados na matriz.

Exemplo 1. Uso de get_object_vars()

<?php
class Point2D {
    var $x, $y;
    var $label;

    function Point2D($x, $y) {
        $this->x = $x;
        $this->y = $y;
    }

    function setLabel($label) {
        $this->label = $label;
    }

    function getPoint() {
        return array("x" => $this->x,
                     "y" => $this->y,
                     "label" => $this->label);
    }
}

// "$label" is declared but not defined
$p1 = new Point2D(1.233, 3.445);
print_r(get_object_vars($p1));

$p1->setLabel("point #1");
print_r(get_object_vars($p1));

?>
A saída do programa acima será:
Array
 (
     [x] => 1.233
     [y] => 3.445
 )

 Array
 (
     [x] => 1.233
     [y] => 3.445
     [label] => point #1
 )

Veja também get_class_methods() e get_class_vars()!

get_parent_class

(PHP 4 )

get_parent_class -- Devolve o nome da classe pai para o objeto ou classe

Descrição

string get_parent_class ( mixed obj)

Se obj é um objeto, retorna o nome da classe pai da classe da qual o obj é uma instância.

Seobj é uma string, retorna o nome da classe pai da classe com aquele nome. Esta funcionalidade foi adicionada no PHP 4.0.5.

Veja também get_class() e is_subclass_of()

is_a

(PHP 4 >= 4.2.0)

is_a --  Retorna TRUE se o objeto é desta classe ou tem esta classe como uma de suas classes pai.

Descrição

bool is_a ( object object, string class_name)

Esta função retorna TRUE se o objeto é desta classe ou tem esta classe como uma de suas classes pai, caso contrário retorna FALSE.

Veja também get_class(), get_parent_class(), e is_subclass_of().

is_subclass_of

(PHP 4 )

is_subclass_of --  Retorna TRUE se o objeto tem esta classe como uma de suas classes pai

Descrição

bool is_subclass_of ( object object, string class_name)

Esta função retorna TRUE se o objeto object, pertence a uma classe que é uma sub-classe de class_name, caso contrário retorna FALSE.

Veja também get_class(), get_parent_class() e is_a().

method_exists

(PHP 4 )

method_exists -- Checa se o método da classe existe

Descrição

bool method_exists ( object object, string method_name)

Esta função retorma TRUE se o método dado pelo method_name foi definido para o dado object, caso contrário FALSE.

X. ClibPDF functions

Introdução

ClibPDF lets you create PDF documents with PHP. ClibPDF functionality and API are similar to PDFlib. This documentation should be read alongside the ClibPDF manual since it explains the library in much greater detail.

Many functions in the native ClibPDF and the PHP module, as well as in PDFlib, have the same name. All functions except for cpdf_open() take the handle for the document as their first parameter.

Currently this handle is not used internally since ClibPDF does not support the creation of several PDF documents at the same time. Actually, you should not even try it, the results are unpredictable. I can't oversee what the consequences in a multi threaded environment are. According to the author of ClibPDF this will change in one of the next releases (current version when this was written is 1.10). If you need this functionality use the pdflib module.

A nice feature of ClibPDF (and PDFlib) is the ability to create the pdf document completely in memory without using temporary files. It also provides the ability to pass coordinates in a predefined unit length. (This feature can also be simulated by pdf_translate() when using the PDFlib functions.)

Another nice feature of ClibPDF is the fact that any page can be modified at any time even if a new page has been already opened. The function cpdf_set_current_page() allows to leave the current page and presume modifying an other page.

Most of the functions are fairly easy to use. The most difficult part is probably creating a very simple PDF document at all. The following example should help you to get started. It creates a document with one page. The page contains the text "Times-Roman" in an outlined 30pt font. The text is underlined.


Requisitos

In order to use the ClibPDF functions you need to install the ClibPDF package. It is available for download from FastIO, but requires that you purchase a license for commercial use. PHP requires that you use cpdflib >= 2.


Instalação

To get these functions to work, you have to compile PHP with --with-cpdflib[=DIR]. DIR is the cpdflib install directory, defaults to /usr. In addition you can specify the jpeg library and the tiff library for ClibPDF to use. To do so add to your configure line the options --with-jpeg-dir[=DIR] --with-tiff-dir[=DIR].


Configuração durante execução

Esta extenção não define nenhum parâmetro de configuração no php.ini.


Constantes Predefinidas

As contantes abaixo são definidas por esta extensão e somente estarão disponíveis quando a extensão foi compilada com o PHP ou carregada dinamicamente durante a execução.

CPDF_PM_NONE (integer)

CPDF_PM_OUTLINES (integer)

CPDF_PM_THUMBS (integer)

CPDF_PM_FULLSCREEN (integer)

CPDF_PL_SINGLE (integer)

CPDF_PL_1COLUMN (integer)

CPDF_PL_2LCOLUMN (integer)

CPDF_PL_2RCOLUMN (integer)


Exemplos

Exemplo 1. Simple ClibPDF Example

<?php
$cpdf = cpdf_open(0);
cpdf_page_init($cpdf, 1, 0, 595, 842, 1.0);
cpdf_add_outline($cpdf, 0, 0, 0, 1, "Page 1");
cpdf_begin_text($cpdf);
cpdf_set_font($cpdf, "Times-Roman", 30, "WinAnsiEncoding");
cpdf_set_text_rendering($cpdf, 1);
cpdf_text($cpdf, "Times Roman outlined", 50, 750);
cpdf_end_text($cpdf);
cpdf_moveto($cpdf, 50, 740);
cpdf_lineto($cpdf, 330, 740);
cpdf_stroke($cpdf);
cpdf_finalize($cpdf);
Header("Content-type: application/pdf");
cpdf_output_buffer($cpdf);
cpdf_close($cpdf);
?>

The pdflib distribution contains a more complex example which creates a series of pages with an analog clock. Here is that example converted into PHP using the ClibPDF extension:

Exemplo 2. pdfclock example from pdflib 2.0 distribution

<?php
$radius = 200;
$margin = 20;
$pagecount = 40;

$pdf = cpdf_open(0);
cpdf_set_creator($pdf, "pdf_clock.php3");
cpdf_set_title($pdf, "Analog Clock");
  
while($pagecount-- > 0) {
  cpdf_page_init($pdf, $pagecount+1, 0, 2 * ($radius + $margin), 2 * ($radius + $margin), 1.0);
  
  cpdf_set_page_animation($pdf, 4, 0.5, 0, 0, 0);  /* wipe */
  
  cpdf_translate($pdf, $radius + $margin, $radius + $margin);
  cpdf_save($pdf);
  cpdf_setrgbcolor($pdf, 0.0, 0.0, 1.0);
  
  /* minute strokes */
  cpdf_setlinewidth($pdf, 2.0);
  for ($alpha = 0; $alpha < 360; $alpha += 6)
    {
    cpdf_rotate($pdf, 6.0);
    cpdf_moveto($pdf, $radius, 0.0);
    cpdf_lineto($pdf, $radius-$margin/3, 0.0);
    cpdf_stroke($pdf);
    }
  
  cpdf_restore($pdf);
  cpdf_save($pdf);
 
  /* 5 minute strokes */
  cpdf_setlinewidth($pdf, 3.0);
  for ($alpha = 0; $alpha < 360; $alpha += 30)
  {
    cpdf_rotate($pdf, 30.0);
    cpdf_moveto($pdf, $radius, 0.0);
    cpdf_lineto($pdf, $radius-$margin, 0.0);
    cpdf_stroke($pdf);
  }

  $ltime = getdate();

  /* draw hour hand */
  cpdf_save($pdf);
  cpdf_rotate($pdf, -(($ltime['minutes']/60.0) + $ltime['hours'] - 3.0) * 30.0);
  cpdf_moveto($pdf, -$radius/10, -$radius/20);
  cpdf_lineto($pdf, $radius/2, 0.0);
  cpdf_lineto($pdf, -$radius/10, $radius/20);
  cpdf_closepath($pdf);
  cpdf_fill($pdf);
  cpdf_restore($pdf);

  /* draw minute hand */
  cpdf_save($pdf);
  cpdf_rotate($pdf, -(($ltime['seconds']/60.0) + $ltime['minutes'] - 15.0) * 6.0);
  cpdf_moveto($pdf, -$radius/10, -$radius/20);
  cpdf_lineto($pdf, $radius * 0.8, 0.0);
  cpdf_lineto($pdf, -$radius/10, $radius/20);
  cpdf_closepath($pdf);
  cpdf_fill($pdf);
  cpdf_restore($pdf);

  /* draw second hand */
  cpdf_setrgbcolor($pdf, 1.0, 0.0, 0.0);
  cpdf_setlinewidth($pdf, 2);
  cpdf_save($pdf);
  cpdf_rotate($pdf, -(($ltime['seconds'] - 15.0) * 6.0));
  cpdf_moveto($pdf, -$radius/5, 0.0);
  cpdf_lineto($pdf, $radius, 0.0);
  cpdf_stroke($pdf);
  cpdf_restore($pdf);

  /* draw little circle at center */
  cpdf_circle($pdf, 0, 0, $radius/30);
  cpdf_fill($pdf);

  cpdf_restore($pdf);

  cpdf_finalize_page($pdf, $pagecount+1);
}

cpdf_finalize($pdf);
Header("Content-type: application/pdf");
cpdf_output_buffer($pdf);
cpdf_close($pdf);
?>

Veja Também

See also the PDFlib extension documentation.

Índice
cpdf_add_annotation -- Adds annotation
cpdf_add_outline -- Adds bookmark for current page
cpdf_arc -- Draws an arc
cpdf_begin_text -- Starts text section
cpdf_circle -- Draw a circle
cpdf_clip -- Clips to current path
cpdf_close -- Closes the pdf document
cpdf_closepath_fill_stroke -- Close, fill and stroke current path
cpdf_closepath_stroke -- Close path and draw line along path
cpdf_closepath -- Close path
cpdf_continue_text -- Output text in next line
cpdf_curveto -- Draws a curve
cpdf_end_text -- Ends text section
cpdf_fill_stroke -- Fill and stroke current path
cpdf_fill -- Fill current path
cpdf_finalize_page -- Ends page
cpdf_finalize -- Ends document
cpdf_global_set_document_limits -- Sets document limits for any pdf document
cpdf_import_jpeg -- Opens a JPEG image
cpdf_lineto -- Draws a line
cpdf_moveto -- Sets current point
cpdf_newpath -- Starts a new path
cpdf_open -- Opens a new pdf document
cpdf_output_buffer -- Outputs the pdf document in memory buffer
cpdf_page_init -- Starts new page
cpdf_place_inline_image -- Places an image on the page
cpdf_rect -- Draw a rectangle
cpdf_restore -- Restores formerly saved environment
cpdf_rlineto -- Draws a line
cpdf_rmoveto -- Sets current point
cpdf_rotate_text --  Sets text rotation angle
cpdf_rotate -- Sets rotation
cpdf_save_to_file -- Writes the pdf document into a file
cpdf_save -- Saves current environment
cpdf_scale -- Sets scaling
cpdf_set_action_url --  Sets hyperlink
cpdf_set_char_spacing -- Sets character spacing
cpdf_set_creator -- Sets the creator field in the pdf document
cpdf_set_current_page -- Sets current page
cpdf_set_font_directories --  Sets directories to search when using external fonts
cpdf_set_font_map_file --  Sets fontname to filename translation map when using external fonts
cpdf_set_font -- Select the current font face and size
cpdf_set_horiz_scaling -- Sets horizontal scaling of text
cpdf_set_keywords -- Sets the keywords field of the pdf document
cpdf_set_leading -- Sets distance between text lines
cpdf_set_page_animation -- Sets duration between pages
cpdf_set_subject -- Sets the subject field of the pdf document
cpdf_set_text_matrix -- Sets the text matrix
cpdf_set_text_pos -- Sets text position
cpdf_set_text_rendering -- Determines how text is rendered
cpdf_set_text_rise -- Sets the text rise
cpdf_set_title -- Sets the title field of the pdf document
cpdf_set_viewer_preferences --  How to show the document in the viewer
cpdf_set_word_spacing -- Sets spacing between words
cpdf_setdash -- Sets dash pattern
cpdf_setflat -- Sets flatness
cpdf_setgray_fill -- Sets filling color to gray value
cpdf_setgray_stroke -- Sets drawing color to gray value
cpdf_setgray -- Sets drawing and filling color to gray value
cpdf_setlinecap -- Sets linecap parameter
cpdf_setlinejoin -- Sets linejoin parameter
cpdf_setlinewidth -- Sets line width
cpdf_setmiterlimit -- Sets miter limit
cpdf_setrgbcolor_fill -- Sets filling color to rgb color value
cpdf_setrgbcolor_stroke -- Sets drawing color to rgb color value
cpdf_setrgbcolor -- Sets drawing and filling color to rgb color value
cpdf_show_xy -- Output text at position
cpdf_show -- Output text at current position
cpdf_stringwidth -- Returns width of text in current font
cpdf_stroke -- Draw line along path
cpdf_text -- Output text with parameters
cpdf_translate -- Sets origin of coordinate system

cpdf_add_annotation

(PHP 3>= 3.0.12, PHP 4 )

cpdf_add_annotation -- Adds annotation

Description

void cpdf_add_annotation ( int pdf document, float llx, float lly, float urx, float ury, string title, string content [, int mode])

The cpdf_add_annotation() adds a note with the lower left corner at (llx, lly) and the upper right corner at (urx, ury).

The optional parameter mode determines the unit length. If it's 0 or omitted the default unit as specified for the page is used. Otherwise the coordinates are measured in postscript points disregarding the current unit.

cpdf_add_outline

(PHP 3>= 3.0.9, PHP 4 )

cpdf_add_outline --