Skip to content

3. Fundamentos do PHP

3.1. Estrutura de pastas dos scripts

Os scripts deste capítulo estão em duas pastas dentro da pasta [scripts-console] do código do curso:

php8-oct-2026
└── scripts-console
    ├── basics
    │   ├── phpinfo.php
    │   ├── basics-01.php
    │   ├── basics-02.php
    │   ├── ...
    │   ├── basics-17.php
    │   └── info.txt
    └── json
        ├── family.json
        ├── json-01.php
        ├── json-02.php
        └── json-03.php

São scripts de “console”: executam-se em um terminal com o comando [php script-name.php] e enviam seus resultados a esse mesmo terminal. Os scripts web, executados pelo servidor [Apache] do [Laragon] e exibidos por um navegador, serão vistos mais adiante.

3.2. Configuração do PHP

O PHP vem pré-configurado por meio de um arquivo de texto chamado [php.ini]. Todas essas configurações podem ser alteradas por programação. A configuração do PHP influencia muito a execução dos scripts. Por isso, é importante entendê-la. O script a seguir, [phpinfo.php], permite fazer isso:

1
2
3
4
5
6
<?php

declare(strict_types=1);

// exibe a configuração do PHP
phpinfo();

Comentários:

  • linha 3: esta linha aparecerá no início de todos os scripts deste curso. Vamos explicá-la na seção sobre conversões de tipo;
  • Linha 6: a função [phpinfo] exibe a configuração do PHP.

Vamos abrir um terminal na pasta [scripts-console/basics] e executar o script. Eis um trecho:

> php phpinfo.php
phpinfo()
PHP Version => 8.5.11
…
Server API => Command Line Interface
…
PHP API => 20250925
PHP Extension => 20250925
Zend Extension => 420250925
PHP Integer Size => 64 bits
Debug Build => no
Zend Memory Manager => enabled
IPv6 Support => enabled
…
display_errors => STDOUT => STDOUT
error_reporting => 30719 => 30719
memory_limit => 512M => 512M
max_execution_time => 0 => 0
…

A função [phpinfo] exibe aqui quase 1.500 linhas de configuração. Não vamos comentá-las, pois a maioria diz respeito a usos avançados do PHP. Destaquemos algumas:

  • [PHP Version]: a versão do PHP em uso, neste caso a 8.5;
  • [Server API]: a forma como o PHP foi iniciado. [Command Line Interface] (CLI) designa o interpretador executado em um terminal. Quando o PHP é executado pelo servidor [Apache], essa linha muda, e a configuração pode ser diferente;
  • [display_errors] e [error_reporting]: o PHP exibe todos os erros, avisos e notificações de descontinuação. O valor 30719 corresponde à constante [E_ALL] a partir do PHP 8.4. Essa é a configuração necessária durante o treinamento: um aviso quase sempre indica um erro de programação.

Uma linha importante da saída completa é a linha [Loaded Configuration File]: ela indica qual arquivo [php.ini] foi usado para configurar o PHP que executa seus scripts. Com o [Laragon], é um arquivo como [C:\laragon\bin\php\php-8.5.x-Win32-vs17-x64\php.ini]. Você também pode obtê-lo diretamente com o comando [php --ini]. Se quiser modificar a configuração de execução do PHP, é esse o arquivo a editar (o [Laragon] dá acesso a ele pelo menu, na seção [PHP > php.ini]). Há inúmeros comentários nesse arquivo explicando a finalidade das diversas configurações.

3.3. Um primeiro exemplo

3.3.1. O código

A seguir, um programa [basics-01.php] que demonstra os recursos básicos do PHP:

<?php

// verificação estrita dos tipos dos parâmetros e dos resultados das funções
declare(strict_types=1);

// isto é um comentário
// variável usada sem ter sido declarada
$name = "dupont";
// uma saída na tela
print "name=$name\n";
// um array com elementos de tipos diferentes
$array = ["one", "two", 3, 4];
// seu número de elementos
$n = count($array);
// um laço
for ($i = 0; $i < $n; $i++) {
    print "array[$i]=$array[$i]\n";
}
// inicialização de 2 variáveis com o conteúdo de um array
[$string1, $string2] = ["string1", "string2"];
// concatenação das 2 strings
$string3 = $string1 . $string2;
// exibe o resultado
print "[$string1,$string2,$string3]\n";
// uso de uma função
display($string1);
// o tipo de uma variável pode ser conhecido
displayType("n", $n);
displayType("string1", $string1);
displayType("array", $array);
// o tipo de uma variável pode mudar durante a execução
$n = "has changed";
displayType("n", $n);
// uma função pode retornar um resultado
$res1 = f1(4);
print "res1=$res1\n";
// uma função pode retornar um array de valores
[$res1, $res2, $res3] = f2();
print "(res1,res2,res3)=[$res1,$res2,$res3]\n";
// poderíamos ter recuperado esses valores em um array
$t = f2();
for ($i = 0; $i < count($t); $i++) {
    print "t[$i]=$t[$i]\n";
}
// alguns testes
for ($i = 0; $i < count($t); $i++) {
    // exibe apenas as strings
    if (gettype($t[$i]) === "string") {
        print "t[$i]=$t[$i]\n";
    }
}
// operadores de comparação == e ===
if ("2" == 2) {
    print "with the == operator, the string 2 is equal to the integer 2\n";
} else {
    print "with the == operator, the string 2 is not equal to the integer 2\n";
}
if ("2" === 2) {
    print "with the === operator, the string 2 is equal to the integer 2\n";
} else {
    print "with the === operator, the string 2 is not equal to the integer 2\n";
}
// uma comparação cujo resultado mudou com o PHP 8
if (0 == "abc") {
    print "with the == operator, the integer 0 is equal to the string abc\n";
} else {
    print "with the == operator, the integer 0 is not equal to the string abc\n";
}
// outros testes
for ($i = 0; $i < count($t); $i++) {
    // exibe apenas os inteiros > 10
    if (is_int($t[$i]) && $t[$i] > 10) {
        print "t[$i]=$t[$i]\n";
    }
}
// um laço while
$t = [8, 5, 0, -2, 3, 4];
$i = 0;
$sum = 0;
while ($i < count($t) && $t[$i] > 0) {
    print "t[$i]=$t[$i]\n";
    $sum += $t[$i];   // $sum = $sum + $t[$i]
    $i++;             // $i = $i + 1
}
print "sum=$sum\n";

// fim do programa
exit;

//----------------------------------
function display(string $string): void
{
    // exibe $string
    print "string=$string\n";
}

//----------------------------------
function displayType(string $name, mixed $variable): void
{
    // exibe o tipo de $variable
    print "type[variable $" . $name . "]=" . gettype($variable) . "\n";
}

//----------------------------------
function f1(int $param): int
{
    // soma 10 a $param
    return $param + 10;
}

//----------------------------------
function f2(): array
{
    // retorna 3 valores
    return ["one", 0, 100];
}

Os resultados:

> php basics-01.php
name=dupont
array[0]=one
array[1]=two
array[2]=3
array[3]=4
[string1,string2,string1string2]
string=string1
type[variable $n]=integer
type[variable $string1]=string
type[variable $array]=array
type[variable $n]=string
res1=14
(res1,res2,res3)=[one,0,100]
t[0]=one
t[1]=0
t[2]=100
t[0]=one
with the == operator, the string 2 is equal to the integer 2
with the === operator, the string 2 is not equal to the integer 2
with the == operator, the integer 0 is not equal to the string abc
t[2]=100
t[0]=8
t[1]=5
sum=13

Comentários:

  • linha 4: instrui o PHP a verificar estritamente os tipos declarados dos parâmetros e dos retornos das funções. Voltaremos a isso na seção sobre mudanças de tipo. Por enquanto, observe que todos os scripts deste curso começam assim;
  • linha 8: em PHP, as variáveis não são declaradas. Elas têm um tipo dinâmico, que pode mudar ao longo do tempo. [$name] representa a variável de identificador [name];
  • linha 10: para escrever na tela, pode-se usar a instrução [print] ou a instrução [echo];
  • Linha 12: a notação [[...]] serve para definir um array. A notação [$array[$i]] representa o elemento de número [$i] do array [$array], em que o primeiro elemento tem o número 0. A notação mais antiga [array("one", "two", 3, 4)] ainda é aceita, mas não a usaremos;
  • linha 14: a função [count($array)] retorna o número de elementos do array [$array];
  • linhas 16–18: um laço. Como esse laço contém apenas uma instrução, as chaves são opcionais. No restante deste documento, usaremos sempre chaves, qualquer que seja o número de instruções;
  • linha 17: as strings são delimitadas por aspas duplas " ou aspas simples '. Dentro de aspas duplas, as variáveis [$variable] são avaliadas (diz-se também “interpoladas”), mas não dentro de aspas simples;
  • linha 20: é possível atribuir os elementos de um array a várias variáveis em uma única operação. Aqui, [$string1="string1"] e [$string2="string2"]. Essa sintaxe, chamada de desestruturação, substitui a função [list] das versões antigas do PHP: [list($string1, $string2) = ...] ainda é aceito;
  • linha 22: o operador . (ponto) é o operador de concatenação de strings;
  • Linhas 91–95: a palavra-chave [function] define uma função. Uma função pode ser definida em qualquer lugar do script, até depois de ter sido usada. Aqui, [string $string] indica que o parâmetro [$string] deve ser uma string, e [: void] indica que a função não retorna resultado. Essas declarações de tipo são opcionais em PHP, mas as usaremos sistematicamente: elas documentam o código e permitem que o PHP (e o editor) detectem erros;
  • linha 98: o tipo [mixed] (PHP 8.0) significa “qualquer tipo”. O parâmetro [$variable] pode aceitar um inteiro, uma string, um array etc.;
  • linha 101: a função predefinida [gettype($variable)] retorna uma string que representa o tipo de [$variable]. Os resultados mostram que esse tipo pode mudar ao longo do tempo: [$n] é primeiro um inteiro e depois uma string;
  • linha 105: uma função retorna um resultado com a instrução [return]. O tipo desse resultado é declarado depois dos parênteses: [: int]. O código chamador pode ignorar ou recuperar os resultados de uma função;
  • linha 112: uma função pode retornar vários valores agrupando-os em um array;
  • linhas 53–62: o operador [===] faz uma comparação estrita de dois elementos: eles devem ter o mesmo tipo e o mesmo valor para serem iguais. O operador [] é menos estrito: dois elementos podem ser iguais sem serem do mesmo tipo. Nesse caso, a comparação é feita depois que ambos os elementos são convertidos para o mesmo tipo. É bastante fácil “deixar passar” essas conversões implícitas e acabar com resultados inesperados, como descobrir que uma condição é verdadeira quando se esperava que fosse falsa. Para evitar essa armadilha, usaremos sempre o operador de comparação [=] (e sua negação, [!==]);
  • linhas 64–68: um exemplo dessas conversões implícitas. No PHP 7, a string “abc” era convertida no número 0, e a expressão [0 == "abc"] era verdadeira! Desde o PHP 8.0, ao comparar um número com uma string que não representa um número, o número é convertido em string, e a expressão é falsa. O comportamento de [] mudou, portanto, de uma versão para outra: mais um motivo para preferir [=];
  • Linha 72: a função [is_int] retorna [true] se seu parâmetro for um inteiro. Da mesma forma, existem [is_string], [is_float], [is_bool], [is_array]… O operador [&&] é o E lógico. Também é possível usar os operadores lógicos [||] (OU) e [!] (NÃO). O PHP também aceita as palavras-chave [and] e [or], mas sua prioridade menor que a da atribuição pode levar a resultados inesperados: não as usaremos;
  • linha 80: um laço [while]. Ele para assim que a condição é falsa — neste caso, assim que o array termina de ser percorrido ou um elemento negativo ou nulo é encontrado;
  • Linha 88: a instrução [exit] interrompe a execução do script. As funções que vêm depois não são executadas nesse ponto, mas são reconhecidas por todo o script.

Observe que o script não termina com a tag de fechamento do código PHP [?>] . Ela não é essencial. Além disso, em um contexto web, pode causar problemas se for seguida de espaços ou quebras de linha, difíceis de detectar porque não são visíveis em um editor de texto. A recomendação [PSR-12], aliás, especifica que ela deve ser omitida em arquivos que contêm apenas PHP. Por isso, no restante deste documento, nós a omitiremos sistematicamente.

Nota: neste documento, usaremos a palavra-chave [print] para exibir texto no console. Outra forma de fazer o mesmo é usar a palavra-chave [echo]. Há diferenças sutis entre essas duas palavras-chave, mas, no contexto deste documento, elas não terão importância. Portanto, se você preferir usar [echo], fique à vontade.

3.3.2. Uso do VS Code

Para trabalhar com os scripts do curso, abra a pasta [php8-oct-2026] no [VS Code] (menu [File > Open Folder]). A árvore de arquivos aparece no explorador, no lado esquerdo da janela. Para executar um script:

  • abra um terminal integrado (menu [Terminal > New Terminal]). Ele abre na pasta [php8-oct-2026];
  • navegue até a pasta do script: [cd scripts-console/basics];
  • execute o script: [php basics-01.php]. Os resultados são exibidos no terminal. Como alternativa, no explorador de arquivos, você pode clicar com o botão direito na pasta [basics] e selecionar [Open in Integrated Terminal].

Se o comando [php] não for reconhecido, é porque a pasta do PHP não está no PATH do Windows: o [Laragon] a adiciona lá quando você marca a opção correspondente em seu menu [Tools > Path]. O comando [php -v] deve exibir a versão 8.5.

A extensão [PHP Intelephense] analisa o código enquanto você digita e sinaliza problemas com uma linha ondulada sob o código incorreto. Passar o mouse sobre essa linha exibe a mensagem. Todos os problemas do arquivo são listados no painel [Problems] (menu [View > Problems]). Entre os avisos úteis:

  • [Undefined variable]: uma variável está sendo usada sem ter sido inicializada. Costuma ser um erro de digitação no nome da variável;
  • [Undefined function]: está sendo chamada uma função que não existe; novamente, costuma ser um erro de digitação;
  • [Expected type 'int'. Found 'string'.]: um parâmetro efetivo não tem o tipo declarado pela função. Esse é um dos grandes benefícios das declarações de tipo: o erro é sinalizado antes mesmo da execução;
  • [Expected 2 arguments. Found 1.]: o número de parâmetros efetivos não corresponde à definição da função.

Passar o mouse sobre o nome de uma função exibe sua assinatura (parâmetros, tipos, valor de retorno) e sua documentação, inclusive para as funções predefinidas do PHP. Para garantir que o [Intelephense] conheça as novidades recentes da linguagem, verifique as configurações do [VS Code] (menu [File > Preferences > Settings], pesquise “intelephense php version”) e confira se a versão do PHP especificada é a 8.5. Ao aprender a linguagem, convém corrigir todos os avisos relatados. É uma ótima maneira de aprender.

O [Intelephense] também pode formatar um arquivo (clique com o botão direito, [Format Document]) segundo as recomendações de codificação da [PSR-12]. As PSR (PHP Standard Recommendations) são diretrizes para produzir código padronizado, facilitando assim a interoperabilidade e a manutenção de código escrito por pessoas diferentes. Elas são publicadas pelo [PHP-FIG] no site www.php-fig.org. As recomendações [PSR-1] e [PSR-12] estabelecem as regras de escrita do código. Eis as regras da [PSR-1]:

Elemento
Regra
Constantes de classe
As constantes de classe DEVEM ser escritas em letras maiúsculas, com o caractere _ como separador.
Ex.: [const VAT_RATE]
Métodos
Os nomes de métodos DEVEM ser escritos em camelCase.
Exemplo: [public function executeBatchTaxes()]
Propriedades
Os nomes de propriedades DEVEM ser escritos de forma consistente dentro de uma mesma base de código, como StudlyCaps, camelCase ou under_score.
Exemplos: [$AnnualSalary], [$annualSalary], [$annual_salary]
Efeitos colaterais
Um arquivo DEVE declarar novos símbolos (classes, funções, constantes etc.) sem nenhum efeito colateral, ou executar código com efeitos colaterais, mas NÃO DEVE fazer as duas coisas.
Tipos
Os nomes de tipos (classes, interfaces etc.) DEVEM ser escritos em StudlyCaps. Cada tipo fica em seu próprio arquivo e em um namespace de pelo menos um nível.
Exemplo: [class ScholarshipStudent]

A regra dos efeitos colaterais determina que um arquivo deve conter:

  • ou declarações de tipos (classes, interfaces), funções ou constantes;
  • ou código executável sem declarações de novos tipos.

Por simplicidade, os exemplos deste capítulo não seguem essa regra: cada script é um único arquivo que define suas funções e as utiliza. Dividir o código em vários arquivos seria trabalhoso demais para exemplos básicos. Na aplicação apresentada como fio condutor deste documento, procuraremos seguir essas recomendações o mais fielmente possível, uma vez que ela seja escrita com classes.

3.4. Escopo das variáveis

3.4.1. Exemplo 1

O script [basics-02.php] é o seguinte:

<?php

declare(strict_types=1);

// escopo das variáveis

function f1(): void
{
    // usamos a variável global $i
    global $i;
    $i++;
    $j = 10;
    print "f1[i,j]=[$i,$j]\n";
}

function f2(): void
{
    // usamos a variável global $i
    global $i;
    $i++;
    $j = 20;
    print "f2[i,j]=[$i,$j]\n";
}

function f3(): void
{
    // usamos uma variável local $i
    $i = 4;
    $j = 30;
    print "f3[i,j]=[$i,$j]\n";
}

// testes
$i = 0;
$j = 0;  // estas duas variáveis só são conhecidas por uma função f
// se ela declarar explicitamente com a instrução global
// que deseja usá-las
f1();
f2();
f3();
print "test[i,j]=[$i,$j]\n";

Os resultados:

1
2
3
4
5
> php basics-02.php
f1[i,j]=[1,10]
f2[i,j]=[2,20]
f3[i,j]=[4,30]
test[i,j]=[2,0]

Comentários:

  • Linhas 34–35: definem duas variáveis, [$i] e [$j], no programa principal. Essas variáveis não são reconhecidas dentro das funções. Assim, na linha 12, a variável [$j] da função [f1] é uma variável local da função [f1] e é diferente da variável [$j] do programa principal;
  • linha 10: uma função pode acessar uma variável chamada [$variable] do programa principal por meio da palavra-chave [global]. Aqui, a instrução refere-se à variável global [$i] do programa principal;
  • linha 28: a função [f3] não declarou [$i] como global; sua variável [$i] é uma variável local, sem relação com a do programa principal.

O uso de [global] não é recomendado: uma função que modifica variáveis globais é difícil de entender e de testar. É preferível que uma função receba seus dados por meio de seus parâmetros e retorne seus resultados por meio de [return]. É o que faremos no exemplo seguinte.

3.4.2. Exemplo 2

O script [basics-03.php] é o seguinte:

<?php

declare(strict_types=1);

// o escopo de uma variável é global em relação aos blocos de código
$i = 0;
{
    $i = 4;
    $i++;
}
print "i=$i\n";

Os resultados:

> php basics-03.php
i=5

Comentários:

Em algumas linguagens, uma variável definida entre chaves tem escopo limitado a essas chaves: ela não é acessível fora delas. Os resultados acima mostram que não é o caso do PHP. A variável [$i] usada na linha 8, dentro das chaves, é a mesma usada nas linhas 6 e 11, fora delas.

3.5. Mudanças de tipo

As variáveis em PHP não têm tipo fixo. O tipo pode mudar em tempo de execução, conforme o valor atribuído à variável. Em operações que envolvem dados de tipos variados, o interpretador PHP faz conversões implícitas para levar os operandos a um tipo comum. Essas conversões implícitas, se o desenvolvedor não as conhece, podem ser fonte de erros difíceis de detectar. A seguir, um script [basics-04.php] que demonstra conversões implícitas e explícitas. Comecemos pela primeira parte:

<?php

// tipos estritos na passagem de parâmetros
declare(strict_types=1);

// conversões implícitas de tipo
// tipo --> bool
print "Conversion to a boolean------------------------------\n";
showBool("abcd", "abcd");
showBool("", "");
showBool("[1, 2, 3]", [1, 2, 3]);
showBool("[]", []);
showBool("null", null);
showBool("0.0", 0.0);
showBool("0", 0);
showBool("4.6", 4.6);
showBool("\"0\"", "0");

function showBool(string $prefix, mixed $var): void
{
    print "(bool) $prefix : ";
    // a conversão de $var para booleano é feita automaticamente no teste a seguir
    if ($var) {
        print "true";
    } else {
        print "false";
    }
    print "\n";
}

Comentários:

  • linha 4: solicita a verificação estrita dos tipos dos parâmetros de uma função, quando o tipo é especificado (e do tipo de seu valor de retorno). Explicaremos essa instrução um pouco mais adiante;
  • linha 19: a finalidade da função [showBool] é demonstrar a conversão implícita (automática) feita pelo interpretador PHP quando um valor de qualquer tipo precisa ser convertido em booleano (linha 23);
  • linha 19: o parâmetro [$prefix] deve ser do tipo [string]. O parâmetro [$var] é do tipo [mixed]: o parâmetro efetivo pode, portanto, ser de qualquer tipo. A função [showBool] não retorna valor ([void]);
  • Linha 23: na instrução [if ($var)], o valor de [$var] deve ser convertido em booleano para que o [if] possa ser avaliado. Surpreendentemente, o interpretador PHP retorna um resultado para qualquer tipo de valor que lhe seja fornecido;
  • linhas 9–17: o valor do parâmetro da função para [showBool] será, sucessivamente:
    • linha 9: uma string não vazia: resultado [true] (maiúsculas e minúsculas não importam, TRUE=true);
    • linha 10: uma string vazia: resultado [false];
    • linha 11: um array não vazio: resultado [true];
    • linha 12: um array vazio: resultado [false];
    • linha 13: o valor [null] (nenhum valor): resultado [false];
    • linha 14: o número real 0: resultado [false];
    • linha 15: o inteiro 0: resultado [false];
    • linha 16: um número real (ou inteiro) diferente de 0: resultado [true];
    • linha 17: uma armadilha: a string "0" é convertida em [false], enquanto qualquer outra string não vazia é convertida em [true].

É o que mostram as saídas de tela resultantes:

Conversion to a boolean------------------------------
(bool) abcd : true
(bool)  : false
(bool) [1, 2, 3] : true
(bool) [] : false
(bool) null : false
(bool) 0.0 : false
(bool) 0 : false
(bool) 4.6 : true
(bool) "0" : false

Continuemos com o código do script:

// conversões implícitas de string para um tipo numérico
// string --> número
print "Conversion string to number------------------------------\n";
showNumber("12");
showNumber("45.67");
showNumber("12abcd");
try {
    showNumber("abcd");
} catch (TypeError $error) {
    print "(abcd): error [" . $error->getMessage() . "]\n";
}

function showNumber(string $var): void
{
    $number = $var + 1;
    var_dump($number);
    print "($var): $number\n";
}

Comentários:

  • linha 43: a função [showNumber] aceita um parâmetro do tipo [string] e não retorna resultado ([void]);
  • linha 45: esse parâmetro é usado em uma operação aritmética, o que obrigará o interpretador PHP a tentar converter [$var] em número:
    • linha 34: converterá a string "12" no inteiro 12;
    • linha 35: converterá a string "45.67" no número real 45.67;
    • linha 36: a string "12abcd" começa com um número. O PHP usa esse número, 12, mas emite um aviso;
    • linha 38: a string "abcd" não contém nenhum número. No PHP 7, ela era convertida em 0 com um simples aviso. Desde o PHP 8.0, essa operação não é mais possível: o PHP lança um erro do tipo [TypeError] que, se não for interceptado, encerraria o script;
  • linhas 37–41: a estrutura [try { ... } catch (TypeError $error) { ... }] permite interceptar esse erro e continuar a execução. [$error->getMessage()] é a mensagem de erro. As exceções serão vistas em um capítulo posterior; por ora, basta saber que o código do bloco [catch] é executado quando o código do bloco [try] provoca um erro [TypeError].

Eis os resultados da execução:

Conversion string to number------------------------------
int(13)
(12): 13
float(46.67)
(45.67): 46.67

Warning: A non-numeric value encountered in .../php8-oct-2026/scripts-console/basics/basics-04.php on line 45
int(13)
(12abcd): 13
(abcd): error [Unsupported operand types: string + int]

A função [var_dump] exibe o tipo e o valor de seu parâmetro: int(13) é o inteiro 13, e float(46.67) é o número de ponto flutuante 46,67.

Observe que a instrução [declare(strict_types=1)] não impediu que a string "12" fosse convertida em número. Este é um ponto importante: o modo estrito se aplica apenas à passagem de parâmetros para funções e aos resultados que elas retornam. Ele não afeta as conversões feitas pelos operadores (+, ., ==…) nem pelo [if]. Eis o que ele muda:

  • sem [declare(strict_types=1)] (o chamado modo “coercivo”), se uma função espera um [int] e recebe a string “12”, o PHP converte a string no inteiro 12;
  • com [declare(strict_types=1)] (modo estrito), a mesma chamada resulta em um erro [TypeError]. O parâmetro efetivo deve ser exatamente do tipo esperado. Há uma exceção: um [int] é aceito onde se espera um [float].

Essa instrução deve ser a primeira do arquivo e se aplica apenas às chamadas de função feitas nesse arquivo. Vamos usá-la em todos os scripts: ela transforma conversões silenciosas, que são fontes de erros, em erros relatados. Veremos um exemplo na seção sobre passagem de parâmetros.

Vamos continuar o código do script com as conversões explícitas de tipo:

// conversões explícitas de tipo
// para int
print "Explicit conversion to int------------------------------\n";
showInt("12.45");
showInt(67.8);
showInt(true);
showInt(null);

function showInt(mixed $var): void
{
    print "parameter: ";
    var_dump($var);
    print "result of the conversion: ";
    var_dump((int) $var);
}

Comentários:

  • Linha 58: a função [showInt] aceita um parâmetro de qualquer tipo ([mixed]) e não retorna resultado. Ela converte o parâmetro [$var] em inteiro (linha 63). Em geral, para converter uma variável do tipo [$var] para o tipo T, escreve-se [(T) $var], em que T pode ser: int, bool, float, string, array ou object. As notações (integer), (boolean), (double) e (binary) das versões antigas do PHP são obsoletas: o PHP 8.5 as sinaliza como descontinuadas. A sintaxe (real), por sua vez, foi removida a partir do PHP 8.0;
  • linha 53: converte a string "12.45" no inteiro 12;
  • linha 54: converte o número de ponto flutuante 67.8 no inteiro 67 (a parte decimal é perdida);
  • linha 55: converte o booleano [true] no inteiro 1 (o booleano [false] no inteiro 0);
  • linha 56: converte o valor [null] no inteiro 0.

É o que mostram as saídas de tela:

1
2
3
4
5
6
7
8
9
Explicit conversion to int------------------------------
parameter: string(5) "12.45"
result of the conversion: int(12)
parameter: float(67.8)
result of the conversion: int(67)
parameter: bool(true)
result of the conversion: int(1)
parameter: NULL
result of the conversion: int(0)

Continuamos a análise do script com a conversão explícita de valores para o tipo [float]:

// para float
print "Explicit conversion to float------------------------------\n";
showFloat("12.45");
showFloat(67);
showFloat(true);
showFloat(null);

function showFloat(mixed $var): void
{
    print "parameter: ";
    var_dump($var);
    print "result of the conversion: ";
    var_dump((float) $var);
}

Comentários:

  • linha 73: a função [showFloat] recebe um parâmetro de qualquer tipo e não retorna resultado;
  • linha 78: o valor desse parâmetro é convertido explicitamente em [float];
  • linha 68: a string "12.45" é convertida no número real 12.45;
  • linha 69: o inteiro 67 é convertido no número real 67;
  • linha 70: o valor booleano [true] é convertido no número real 1 (o valor [false] é convertido no número 0);
  • linha 71: o valor [null] é convertido no número real 0.

É o que mostra a saída de tela:

1
2
3
4
5
6
7
8
9
Explicit conversion to float------------------------------
parameter: string(5) "12.45"
result of the conversion: float(12.45)
parameter: int(67)
result of the conversion: float(67)
parameter: bool(true)
result of the conversion: float(1)
parameter: NULL
result of the conversion: float(0)

Concluímos a apresentação do script examinando as conversões para o tipo [string]:

// para string
print "Explicit conversion to string------------------------------\n";
showString(5);
showString(6.7);
showString(false);
showString(null);

function showString(mixed $var): void
{
    print "parameter: ";
    var_dump($var);
    print "result of the conversion: ";
    var_dump((string) $var);
}

Comentários:

  • linha 88: a função [showString] recebe um parâmetro de qualquer tipo e não retorna resultado;
  • linha 93: o valor do parâmetro é convertido para o tipo [string];
  • linha 83: o inteiro 5 será convertido na string "5";
  • linha 84: o número de ponto flutuante 6.7 será convertido na string "6.7";
  • linha 85: o booleano [false] será convertido em uma string vazia;
  • linha 86: o valor [null] será convertido em uma string vazia.

Eis os resultados na tela:

1
2
3
4
5
6
7
8
9
Explicit conversion to string------------------------------
parameter: int(5)
result of the conversion: string(1) "5"
parameter: float(6.7)
result of the conversion: string(3) "6.7"
parameter: bool(false)
result of the conversion: string(0) ""
parameter: NULL
result of the conversion: string(0) ""

3.6. Arrays

3.6.1. Arrays unidimensionais padrão

Há duas notações para arrays em PHP:

$array = ["one", 2, "three"];
$opposites = ["small" => "big", "beautiful" => "ugly", "expensive" => "cheap"];

O array 1 é chamado de array (ou lista), e o array 2 é chamado de dicionário ou array associativo, em que os elementos são denotados como chave => valor. A notação [$opposites["beautiful"]] refere-se ao valor associado à chave "beautiful". Neste caso, é a string "ugly". O array 1 é simplesmente uma variante do dicionário e poderia ser escrito assim:

$array = [0 => "one", 1 => 2, 2 => "three"];

Isso nos dá [$array[2]="three"]. No fim das contas, só existem dicionários. No caso de um array clássico de n elementos, as chaves são os inteiros do intervalo [0,n-1].

O script [basics-05.php] demonstra operações de manipulação de um array de valores:

<?php

declare(strict_types=1);

// arrays clássicos
// inicialização
$tab1 = [0, 1, 2, 3, 4, 5];
// percurso - 1
print "tab1 has " . count($tab1) . " elements\n";
for ($i = 0; $i < count($tab1); $i++) {
    print "tab1[$i]=$tab1[$i]\n";
}
// percurso - 2
print "tab1 has " . count($tab1) . " elements\n";
foreach ($tab1 as $key => $value) {
    print "tab1[$key]=$value\n";
}
// adição de elementos
$tab1[] = $i++;
$tab1[] = $i++;
// percurso - 3
print "tab1 has " . count($tab1) . " elements\n";
$i = 0;
foreach ($tab1 as $element) {
    print "tab1[$i]=$element\n";
    $i++;
}
// remoção do último elemento
array_pop($tab1);
// percurso - 4
print "tab1 has " . count($tab1) . " elements\n";
for ($i = 0; $i < count($tab1); $i++) {
    print "tab1[$i]=$tab1[$i]\n";
}
// remoção do primeiro elemento
array_shift($tab1);
// percurso - 5
print "tab1 has " . count($tab1) . " elements\n";
for ($i = 0; $i < count($tab1); $i++) {
    print "tab1[$i]=$tab1[$i]\n";
}
// adição no final do array
array_push($tab1, -2);
// percurso - 6
print "tab1 has " . count($tab1) . " elements\n";
for ($i = 0; $i < count($tab1); $i++) {
    print "tab1[$i]=$tab1[$i]\n";
}
// adição no início do array
array_unshift($tab1, -1);
// percurso - 7
print "tab1 has " . count($tab1) . " elements\n";
for ($i = 0; $i < count($tab1); $i++) {
    print "tab1[$i]=$tab1[$i]\n";
}
// primeiro e último elementos (PHP 8.5)
print "first element: " . array_first($tab1) . ", last element: " . array_last($tab1) . "\n";

Os resultados:

> php basics-05.php
tab1 has 6 elements
tab1[0]=0
tab1[1]=1
tab1[2]=2
tab1[3]=3
tab1[4]=4
tab1[5]=5
tab1 has 6 elements
tab1[0]=0
tab1[1]=1
tab1[2]=2
tab1[3]=3
tab1[4]=4
tab1[5]=5
tab1 has 8 elements
tab1[0]=0
tab1[1]=1
tab1[2]=2
tab1[3]=3
tab1[4]=4
tab1[5]=5
tab1[6]=6
tab1[7]=7
tab1 has 7 elements
tab1[0]=0
tab1[1]=1
tab1[2]=2
tab1[3]=3
tab1[4]=4
tab1[5]=5
tab1[6]=6
tab1 has 6 elements
tab1[0]=1
tab1[1]=2
tab1[2]=3
tab1[3]=4
tab1[4]=5
tab1[5]=6
tab1 has 7 elements
tab1[0]=1
tab1[1]=2
tab1[2]=3
tab1[3]=4
tab1[4]=5
tab1[5]=6
tab1[6]=-2
tab1 has 8 elements
tab1[0]=-1
tab1[1]=1
tab1[2]=2
tab1[3]=3
tab1[4]=4
tab1[5]=5
tab1[6]=6
tab1[7]=-2
first element: -1, last element: -2

Comentários:

  • Linha 15: o array é percorrido com um [foreach]. Esse elemento de sintaxe permite percorrer um dicionário (e, portanto, um array) com duas sintaxes diferentes: [foreach ($dictionary as $key => $value)] e [foreach ($array as $value)]. A primeira sintaxe retorna um par (chave, valor) a cada iteração, enquanto a segunda retorna apenas o valor. O curso de PHP 7 usava aqui a função [each], que já era obsoleta na época: ela foi removida no PHP 8.0. [foreach] é a forma padrão de percorrer um array;
  • Linha 19: a notação [$array[] = value] adiciona o elemento [value] como último elemento de [$array]. Aqui, [$i] é igual a 6 depois do primeiro laço [for]: o 6 é adicionado, depois o 7;
  • linha 24: uma iteração com a segunda sintaxe do [foreach];
  • linha 29: a função [array_pop($array)] remove o último elemento de [$array];
  • linha 36: a função [array_shift($array)] remove o primeiro elemento de [$array]. Os elementos restantes são renumerados a partir de 0;
  • linha 43: a função [array_push($array, value)] adiciona [value] como último elemento de [$array];
  • linha 50: a função [array_unshift($array, value)] adiciona [value] como primeiro elemento de [$array];
  • linha 57: as funções [array_first] e [array_last], introduzidas no PHP 8.5, retornam o primeiro e o último elemento de um array (ou [null] se o array estiver vazio).

3.6.2. O dicionário ou array associativo

O script [basics-06.php] é o seguinte:

<?php

declare(strict_types=1);

// dicionários
$spouses = ["Pierre" => "Gisèle", "Paul" => "Virginie", "Jacques" => "Lucette", "Jean" => ""];
// percurso - 1
print "Number of elements in the dictionary: " . count($spouses) . "\n";
foreach ($spouses as $key => $value) {
    print "spouses[$key]=$value\n";
}
// ordenação do dicionário por chave
ksort($spouses);
// percurso - 2
foreach ($spouses as $key => $value) {
    print "spouses[$key]=$value\n";
}
// lista das chaves do dicionário
$keys = array_keys($spouses);
for ($i = 0; $i < count($keys); $i++) {
    print "keys[$i]=$keys[$i]\n";
}
// lista dos valores do dicionário
$values = array_values($spouses);
for ($i = 0; $i < count($values); $i++) {
    print "values[$i]=$values[$i]\n";
}
// um array clássico é uma lista? e um dicionário?
print "values is a list: " . var_export(array_is_list($values), true) . "\n";
print "spouses is a list: " . var_export(array_is_list($spouses), true) . "\n";
// busca de uma chave
exists($spouses, "Jacques");
exists($spouses, "Lucette");
exists($spouses, "Jean");
// valor padrão se a chave não existir: operador ??
print "spouse of Lucette: " . ($spouses["Lucette"] ?? "unknown") . "\n";
// remoção de um par chave-valor
unset($spouses["Jean"]);
print "Number of elements in the dictionary: " . count($spouses) . "\n";
foreach ($spouses as $key => $value) {
    print "spouses[$key]=$value\n";
}
// fim
exit;

function exists(array $spouses, string $husband): void
{
    // verifica se a chave $husband existe no dicionário $spouses
    if (isset($spouses[$husband])) {
        print "The key [$husband] exists, associated with the value [$spouses[$husband]]\n";
    } else {
        print "The key [$husband] does not exist\n";
    }
}

Os resultados:

> php basics-06.php
Number of elements in the dictionary: 4
spouses[Pierre]=Gisèle
spouses[Paul]=Virginie
spouses[Jacques]=Lucette
spouses[Jean]=
spouses[Jacques]=Lucette
spouses[Jean]=
spouses[Paul]=Virginie
spouses[Pierre]=Gisèle
keys[0]=Jacques
keys[1]=Jean
keys[2]=Paul
keys[3]=Pierre
values[0]=Lucette
values[1]=
values[2]=Virginie
values[3]=Gisèle
values is a list: true
spouses is a list: false
The key [Jacques] exists, associated with the value [Lucette]
The key [Lucette] does not exist
The key [Jean] exists, associated with the value []
spouse of Lucette: unknown
Number of elements in the dictionary: 3
spouses[Jacques]=Lucette
spouses[Paul]=Virginie
spouses[Pierre]=Gisèle

Comentários:

O código acima aplica a um dicionário o que vimos antes para um array simples. Comentaremos apenas as novidades:

  • linha 13: a função [ksort] (ordenação por chave) ordena um dicionário na ordem natural das chaves;
  • linha 19: a função [array_keys($dictionary)] retorna a lista das chaves do dicionário em forma de array;
  • linha 24: a função [array_values($dictionary)] retorna a lista dos valores do dicionário em forma de array;
  • linha 29: a função [array_is_list] (PHP 8.1) retorna [true] se as chaves do array forem 0, 1, 2… nessa ordem, ou seja, se o array for uma lista. A função [var_export] retorna a representação PHP de um valor (“true” ou “false”);
  • linha 46: a função [exists] recebe um array ([array]) e uma string ([string]);
  • linha 49: a função [isset($variable)] retorna [true] se a variável [$variable] existe e não tem o valor [null]; caso contrário, retorna [false]. Aplicada a um elemento de array, determina se uma chave existe. A função [array_key_exists($key, $array)] faz o mesmo, mas retorna [true] mesmo que o valor associado à chave seja [null];
  • linha 36: o operador [??] (“null coalescing”) retorna seu operando da esquerda se ele existir e não for [null], e o operando da direita caso contrário. É uma forma concisa de obter um valor padrão para uma chave ausente, sem aviso;
  • linha 38: a função [unset($variable)] exclui a variável [$variable], que aqui é um elemento do dicionário.

3.6.3. Arrays multidimensionais

O script [basics-07.php] é o seguinte:

<?php

declare(strict_types=1);

// arrays multidimensionais clássicos
// inicialização
$multi = [[0, 1, 2], [10, 11, 12, 13], [20, 21, 22, 23, 24]];
// percurso
for ($i1 = 0; $i1 < count($multi); $i1++) {
    for ($i2 = 0; $i2 < count($multi[$i1]); $i2++) {
        print "multi[$i1][$i2]=" . $multi[$i1][$i2] . "\n";
    }
}
// dicionários multidimensionais
// inicialização
$multi = ["zero" => [0, 1, 2], "one" => [10, 11, 12, 13], "two" => [20, 21, 22, 23, 24]];
// percurso
foreach ($multi as $key => $value) {
    for ($i2 = 0; $i2 < count($value); $i2++) {
        print "multi[$key][$i2]={$multi[$key][$i2]}\n";
    }
}

Resultados:

> php basics-07.php
multi[0][0]=0
multi[0][1]=1
multi[0][2]=2
multi[1][0]=10
multi[1][1]=11
multi[1][2]=12
multi[1][3]=13
multi[2][0]=20
multi[2][1]=21
multi[2][2]=22
multi[2][3]=23
multi[2][4]=24
multi[zero][0]=0
multi[zero][1]=1
multi[zero][2]=2
multi[one][0]=10
multi[one][1]=11
multi[one][2]=12
multi[one][3]=13
multi[two][0]=20
multi[two][1]=21
multi[two][2]=22
multi[two][3]=23
multi[two][4]=24

Comentários:

  • Linha 7: os elementos do array [$multi] são, eles mesmos, arrays;
  • linha 11: dentro de uma string delimitada por aspas, a interpolação simples de [$multi[$i1][$i2]] não funciona: o PHP avaliaria apenas [$multi[$i1]]. Por isso, tiramos a expressão da string e usamos a concatenação;
  • linha 16: o array [$multi] torna-se um dicionário (chave, valor) em que cada valor é um array;
  • linha 20: outra solução: dentro de uma string delimitada por aspas, a notação [{$expression}] permite avaliar uma expressão complexa. Voltaremos a isso na próxima seção.

3.7. Strings

3.7.1. Notação

O script [basics-08.php] é o seguinte:

<?php

declare(strict_types=1);

// notação de strings
$string1 = "one";
$string2 = 'one';
print "[$string1,$string2]\n";
// entre aspas simples, as variáveis não são avaliadas
print '[$string1,$string2]' . "\n";
// a notação {$...} delimita a expressão a ser avaliada
$person = ["name" => "dupont", "age" => 34];
print "{$person['name']} is {$person['age']} years old\n";
// uma string de várias linhas (heredoc)
$text = <<<END
    name: $string1
    age: {$person['age']}
    END;
print "$text\n";

Resultados:

1
2
3
4
5
6
> php basics-08.php
[one,one]
[$string1,$string2]
dupont is 34 years old
name: one
age: 34

Comentários:

  • Linhas 6–7: uma string pode ser delimitada por aspas duplas ou simples;
  • linha 8: quando delimitada por aspas duplas, as variáveis são avaliadas;
  • linha 10: entre aspas simples, elas não são avaliadas: a string é exibida como está. Da mesma forma, [\n] não designa aqui uma quebra de linha, daí a concatenação de ["\n"];
  • linha 13: a notação [{$...}] permite avaliar, dentro de uma string, expressões mais complexas que uma simples variável — neste caso, elementos de um dicionário. A notação [${variable}] das versões antigas do PHP está descontinuada desde o PHP 8.2: não deve ser usada;
  • Linhas 15–18: a sintaxe [heredoc] permite que uma string se estenda por várias linhas. A string começa depois de [<<<END] e termina com o marcador [END] (o nome é arbitrário). As variáveis dentro dela são avaliadas como se estivessem entre aspas. A partir do PHP 7.3, o marcador final pode ser indentado: essa indentação é então removida de todas as linhas da string.

3.7.2. Comparação

O script [basics-09.php] é o seguinte:

<?php

// respeito estrito ao tipo dos parâmetros das funções
declare(strict_types=1);

// função de comparação
function compareStrings(string $string1, string $string2): void
{
    // compara string1 e string2
    if ($string1 === $string2) {
        print "[$string1] is equal to [$string2]\n";
    } else {
        print "[$string1] is different from [$string2]\n";
    }
}

// testes de comparação de strings
compareStrings("abcd", "abcd");
compareStrings("", "");
compareStrings("1", "");

// busca de uma substring (PHP 8)
$file = "taxpayersdata.txt";
print "[$file] contains [data]: " . var_export(str_contains($file, "data"), true) . "\n";
print "[$file] starts with [tax]: " . var_export(str_starts_with($file, "tax"), true) . "\n";
print "[$file] ends with [.json]: " . var_export(str_ends_with($file, ".json"), true) . "\n";
// posição de uma substring
print "position of [data] in [$file]: " . strpos($file, "data") . "\n";
// tamanho, maiúsculas
print "length of [$file]: " . strlen($file) . ", in uppercase: " . strtoupper($file) . "\n";
// atenção: strlen conta bytes, mb_strlen conta caracteres
print "strlen(\"café\")=" . strlen("café") . ", mb_strlen(\"café\")=" . mb_strlen("café") . "\n";

Resultados:

> php basics-09.php
[abcd] is equal to [abcd]
[] is equal to []
[1] is different from []
[taxpayersdata.txt] contains [data]: true
[taxpayersdata.txt] starts with [tax]: true
[taxpayersdata.txt] ends with [.json]: false
position of [data] in [taxpayersdata.txt]: 9
length of [taxpayersdata.txt]: 17, in uppercase: TAXPAYERSDATA.TXT
strlen("café")=5, mb_strlen("café")=4

Comentários:

  • Linha 10: poderíamos ter usado o comparador [] em vez de [=]. Este último operador é mais restritivo, pois exige que os dois operandos sejam do mesmo tipo. Observe que, aqui, ele poderia ter sido substituído pelo operador [] já que o tipo dos dois parâmetros está fixado em [string]* na assinatura da função. No entanto, continuaremos a usar *[=];
  • linha 24: a função [str_contains($string, $substring)] (PHP 8.0) retorna [true] se [$substring] estiver presente em [$string];
  • linha 25: a função [str_starts_with] (PHP 8.0) verifica o início de uma string;
  • linha 26: a função [str_ends_with] (PHP 8.0) verifica o fim de uma string;
  • linha 28: a função [strpos($string, $substring)] retorna a posição de [$substring] em [$string], em que o primeiro caractere tem a posição 0, e [false] se a substring estiver ausente. Antes do PHP 8, a presença de uma substring era verificada com [strpos(...) !== false], uma notação enganosa, já que a posição 0 é convertida em [false]: [str_contains] é muito mais legível;
  • linha 30: a função [strlen] retorna o comprimento de uma string, e [strtoupper] a converte em maiúsculas;
  • linha 32: [strlen] conta bytes, não caracteres. Os arquivos do curso são codificados em UTF-8, em que um caractere acentuado ocupa dois bytes: “café” tem 4 caracteres, mas 5 bytes. As funções da extensão [mbstring] (mb_strlen, mb_substr, mb_strtoupper…) operam sobre caracteres.

3.7.3. Relações entre strings e arrays

O script [basics-10.php] é o seguinte:

<?php

declare(strict_types=1);

// string para array
$string = "1:2:3:4";
$tab = explode(":", $string);
// percurso do array
print "tab has " . count($tab) . " elements\n";
for ($i = 0; $i < count($tab); $i++) {
    print "tab[$i]=$tab[$i]\n";
}
// array para string
$string2 = implode(":", $tab);
print "string2=$string2\n";
// vamos adicionar um campo vazio
$string .= ":";
print "string=$string\n";
$tab = explode(":", $string);
// percurso do array
print "tab has " . count($tab) . " elements\n";
for ($i = 0; $i < count($tab); $i++) {
    print "tab[$i]=$tab[$i]\n";
} // agora temos 5 elementos, sendo o último vazio
// vamos adicionar outro campo vazio
$string .= ":";
print "string=$string\n";
$tab = explode(":", $string);
// percurso do array
print "tab has " . count($tab) . " elements\n";
for ($i = 0; $i < count($tab); $i++) {
    print "tab[$i]=$tab[$i]\n";
} // agora temos 6 elementos, sendo os dois últimos vazios

Resultados:

> php basics-10.php
tab has 4 elements
tab[0]=1
tab[1]=2
tab[2]=3
tab[3]=4
string2=1:2:3:4
string=1:2:3:4:
tab has 5 elements
tab[0]=1
tab[1]=2
tab[2]=3
tab[3]=4
tab[4]=
string=1:2:3:4::
tab has 6 elements
tab[0]=1
tab[1]=2
tab[2]=3
tab[3]=4
tab[4]=
tab[5]=

Comentários:

  • Linha 7: a função [explode($separator, $string)] recupera os campos de [$string] separados por [$separator]. Assim, [explode(":", $string)] recupera os elementos de [$string]—separados pela string ":" — em forma de array;
  • Linha 14: a função [implode($separator, $array)] faz a operação inversa da função [explode]. Ela retorna uma string formada pelos elementos de [$array] separados por [$separator];
  • linha 17: o operador [.=] acrescenta uma string ao final de outra. Os resultados mostram que um campo vazio no fim de uma string resulta em um elemento vazio no array retornado por [explode].

3.7.4. Expressões regulares

O script [basics-11.php] é o seguinte:

<?php

// tipo estrito para os parâmetros das funções
declare(strict_types=1);

// expressões regulares em php
// recuperação dos diferentes campos de uma string
// o padrão: uma sequência de dígitos cercada por quaisquer caracteres
// queremos recuperar apenas a sequência de dígitos
$pattern = "/(\d+)/";
// comparamos a string com o padrão
comparePattern2String($pattern, "xyz1234abcd");
comparePattern2String($pattern, "12 34");
comparePattern2String($pattern, "abcd");

// o padrão: uma sequência de dígitos cercada por quaisquer caracteres
// queremos a sequência de dígitos, assim como os campos que a seguem e a precedem
$pattern = "/^(.*?)(\d+)(.*?)$/";
// comparamos a string com o padrão
comparePattern2String($pattern, "xyz1234abcd");
comparePattern2String($pattern, "12 34");
comparePattern2String($pattern, "abcd");

// o padrão - uma data no formato dd/mm/aa
$pattern = "/^\s*(\d\d)\/(\d\d)\/(\d\d)\s*$/";
comparePattern2String($pattern, "10/05/97");
comparePattern2String($pattern, "  04/04/01  ");
comparePattern2String($pattern, "5/1/01");

// o padrão - um número decimal
$pattern = "/^\s*([+-]?)\s*(\d+\.\d*|\.\d+|\d+)\s*/";
comparePattern2String($pattern, "187.8");
comparePattern2String($pattern, "-0.6");
comparePattern2String($pattern, "4");
comparePattern2String($pattern, ".6");
comparePattern2String($pattern, "4.");
comparePattern2String($pattern, " + 4");

// fim
exit;

// --------------------------------------------------------------------------
function comparePattern2String(string $pattern, string $string): void
{
    // compara a string $string com o padrão $pattern
    // comparamos a string com o padrão
    $fields = [];
    $matches = preg_match($pattern, $string, $fields);
    // exibe os resultados
    print "\nResults($pattern,$string)\n";
    if ($matches === 1) {
        for ($i = 0; $i < count($fields); $i++) {
            print "fields[$i]=$fields[$i]\n";
        }
    } else {
        print "The string [$string] does not match the pattern [$pattern]\n";
    }
}

Resultados:

> php basics-11.php

Results(/(\d+)/,xyz1234abcd)
fields[0]=1234
fields[1]=1234

Results(/(\d+)/,12 34)
fields[0]=12
fields[1]=12

Results(/(\d+)/,abcd)
The string [abcd] does not match the pattern [/(\d+)/]

Results(/^(.*?)(\d+)(.*?)$/,xyz1234abcd)
fields[0]=xyz1234abcd
fields[1]=xyz
fields[2]=1234
fields[3]=abcd

Results(/^(.*?)(\d+)(.*?)$/,12 34)
fields[0]=12 34
fields[1]=
fields[2]=12
fields[3]= 34

Results(/^(.*?)(\d+)(.*?)$/,abcd)
The string [abcd] does not match the pattern [/^(.*?)(\d+)(.*?)$/]

Results(/^\s*(\d\d)\/(\d\d)\/(\d\d)\s*$/,10/05/97)
fields[0]=10/05/97
fields[1]=10
fields[2]=05
fields[3]=97

Results(/^\s*(\d\d)\/(\d\d)\/(\d\d)\s*$/,  04/04/01  )
fields[0]=  04/04/01
fields[1]=04
fields[2]=04
fields[3]=01

Results(/^\s*(\d\d)\/(\d\d)\/(\d\d)\s*$/,5/1/01)
The string [5/1/01] does not match the pattern [/^\s*(\d\d)\/(\d\d)\/(\d\d)\s*$/]

Results(/^\s*([+-]?)\s*(\d+\.\d*|\.\d+|\d+)\s*/,187.8)
fields[0]=187.8
fields[1]=
fields[2]=187.8

Results(/^\s*([+-]?)\s*(\d+\.\d*|\.\d+|\d+)\s*/,-0.6)
fields[0]=-0.6
fields[1]=-
fields[2]=0.6

Results(/^\s*([+-]?)\s*(\d+\.\d*|\.\d+|\d+)\s*/,4)
fields[0]=4
fields[1]=
fields[2]=4

Results(/^\s*([+-]?)\s*(\d+\.\d*|\.\d+|\d+)\s*/,.6)
fields[0]=.6
fields[1]=
fields[2]=.6

Results(/^\s*([+-]?)\s*(\d+\.\d*|\.\d+|\d+)\s*/,4.)
fields[0]=4.
fields[1]=
fields[2]=4.

Results(/^\s*([+-]?)\s*(\d+\.\d*|\.\d+|\d+)\s*/, + 4)
fields[0]= + 4
fields[1]=+
fields[2]=4

Comentários:

Aqui, usamos expressões regulares para extrair os diversos campos de uma string. As expressões regulares permitem superar as limitações da função [explode]. O princípio é comparar uma string com outra string chamada padrão, usando a função [preg_match]: [$matches = preg_match($pattern, $string, $fields)] (linha 48). A função [preg_match] retorna o inteiro 1 se o padrão for encontrado na string, e 0 caso contrário. Se for encontrado, [$fields[0]] representa a substring que corresponde ao padrão. Além disso, se o padrão contiver subpadrões entre parênteses, [$fields[1]] é a parte de [$string] que corresponde ao primeiro subpadrão, [$fields[2]] é a parte de [$string] que corresponde ao segundo subpadrão, e assim por diante. Voltemos ao script:

  • linha 10: o padrão corresponde a uma sequência de um ou mais (+) dígitos (\d) que aparece em qualquer lugar de uma string. Além disso, o padrão define um subpadrão entre parênteses;
  • linha 12: o padrão /(\d+)/ é comparado com a string "xyz1234abcd". Vemos que a substring 1234 corresponde ao padrão. Portanto, [$fields[0]] é igual a "1234". Além disso, o padrão tem um subpadrão entre parênteses. Teremos [$fields[1]="1234"];
  • linha 13: o padrão /(\d+)/ é comparado com a string "12 34". Vemos que as substrings 12 e 34 correspondem ao padrão. A comparação para na primeira substring que corresponde ao padrão. Portanto, teremos [$fields[0]=12] e [$fields[1]=12];
  • Linha 14: o padrão /(\d+)/ é comparado com a string "abcd". Nenhuma correspondência é encontrada;
  • linha 51: [preg_match] retorna um inteiro (e [false] se houver um erro no padrão): ele é comparado estritamente com 1.

Vamos explicar os padrões usados no restante do código:

$pattern = "/^(.*?)(\d+)(.*?)$/";

corresponde ao início da string (^), seguido de zero ou mais (*) caracteres quaisquer (.), seguido de um ou mais (+) dígitos, seguido de zero ou mais (*) caracteres quaisquer (.). O padrão (.*) corresponde a zero ou mais caracteres quaisquer. Esse padrão corresponde a qualquer string. Assim, no padrão /^(.*)(\d+)(.*)$/, o primeiro subpadrão (.*) corresponderia a todos os dígitos, exceto o último, que é o único que sobra para o subpadrão (\d+). O padrão (.*?)(\d+) corresponde a 0 ou mais caracteres quaisquer até o próximo subpadrão (?), que neste caso é \d+. Portanto, os dígitos deixam de ser capturados pelo padrão (.*). O padrão acima corresponde, assim, a [start of the string (^), a sequence of any characters (.*?), a sequence of one or more digits (\d+), a sequence of any characters (.*?), the end of the string ($)].

$pattern = "/^\s*(\d\d)\/(\d\d)\/(\d\d)\s*$/";

corresponde a [start of the string (^), a sequence of 0 or more spaces (\s*), 2 digits (\d\d), the character / (\/), 2 digits, /, 2 digits, a sequence of 0 or more spaces (\s*), the end of the string ($)].

$pattern = "/^\s*([+-]?)\s*(\d+\.\d*|\.\d+|\d+)\s*/";

corresponde a [start of the string (^), 0 or more spaces (\s*), a + or - sign ([+-]) presente 0 ou 1 vez (?), uma sequência de 0 ou mais espaços (\s*), 1 ou mais dígitos seguidos de um ponto decimal seguido de zero ou mais dígitos (\d+\.\d*) ou (|) um ponto decimal (\.) seguido de um ou mais dígitos (\d+) ou (|) um ou mais dígitos (\d+), uma sequência de 0 ou mais espaços (\s*)]. O curso de PHP 7 o escrevia como [+|-]: entre colchetes, o caractere | não tem significado especial, e esse padrão também aceitava o símbolo | antes de um número. [+-] é a notação correta.

Nota: o termo [space] em expressões regulares designa um conjunto de caracteres: espaço em branco, nova linha \n, tabulação \t, retorno de carro \r, avanço de página \f…

3.8. Funções

3.8.1. Forma de passagem de parâmetros

O script [basics-12.php] é o seguinte:

<?php

// como os parâmetros são passados a uma função
// respeito estrito aos tipos dos parâmetros
declare(strict_types=1);

function f(int &$i, int $j): void
{
    // $i será obtido por referência
    // $j será obtido por valor
    $i++;
    $j++;
    print "f[i,j]=[$i,$j]\n";
}

// testes
$i = 0;
$j = 0;
// $i e $j são passados à função f
f($i, $j);
print "test[i,j]=[$i,$j]\n";

Resultados:

1
2
3
> php basics-12.php
f[i,j]=[1,1]
test[i,j]=[1,0]

Comentários:

O código acima demonstra as duas formas de passar parâmetros a uma função. Considere o exemplo a seguir:

1
2
3
4
5
6
7
8
9
function f(int &$a, int $b): void
{
    …
}

// programa principal
$i = 10;
$j = 20;
f($i, $j);
  • Linha 1: define os parâmetros formais [$a] e [$b] da função [f]. Essa função processa esses dois parâmetros formais;
  • Linha 9: chama a função [f] com dois parâmetros efetivos, [$i] e [$j]. As relações entre os parâmetros formais ([$a], [$b]) e os parâmetros efetivos ([$i], [$j]) são definidas pelas linhas 1 e 9:
    • [&$a]: o símbolo & indica que o parâmetro formal [$a] assumirá o valor do endereço do parâmetro efetivo [$i]. Em outras palavras, [$a] e [$i] são duas referências ao mesmo local de memória. Manipular o parâmetro formal [$a] equivale a manipular o parâmetro efetivo [$i]. A execução do código demonstra isso. Essa forma de passagem é adequada para parâmetros de saída. Ela é chamada de “passagem por referência”;
    • [$b]: o parâmetro formal [$b] assumirá o valor do parâmetro efetivo [$j]. É a passagem por valor. Os parâmetros formal e efetivo são duas variáveis diferentes. Manipular o parâmetro formal [$b] não tem efeito sobre o parâmetro efetivo [$j]. A execução do código demonstra isso. Essa forma de passagem é adequada para parâmetros de entrada.

Considere a função [swap], que aceita dois parâmetros formais: [$a] e [$b]. A função troca os valores desses dois parâmetros. Assim, quando [swap($i, $j)] é chamada, o código chamador espera que os valores dos dois parâmetros efetivos sejam trocados. São, portanto, parâmetros de saída (eles são modificados). Escreveremos, então:

1
2
3
4
function swap(mixed &$a, mixed &$b): void
{
    [$a, $b] = [$b, $a];
}

Nota: pode-se pensar que a passagem por referência também é adequada para grandes conjuntos de dados, arrays e dicionários, a fim de evitar copiá-los. Isso é desnecessário: o PHP, na verdade, só copia um array passado por valor se a função o modificar. Portanto, a passagem por referência deve ser reservada para parâmetros de saída.

O script a seguir, [basics-13.php], mostra exemplos adicionais:

<?php

// como os parâmetros são passados
// sem declare(strict_types=1) neste script: estamos no modo "coercivo"

function f(&$i, $j)
{
    // $i será obtido por referência
    // $j será obtido por valor
    $i++;
    $j++;
    print "f[i,j]=[$i,$j]\n";
}

function g(int &$i, int $j): void
{
    // $i será obtido por referência
    // $j será obtido por valor
    $i++;
    $j++;
    print "g[i,j]=[$i,$j]\n";
}

// testes
$i = 0;
$j = 0;
// $i e $j são passados à função f
f($i, $j);
print "test[i,j]=[$i,$j]\n";
// $i e $j são passados à função g
g($i, $j);
print "test[i,j]=[$i,$j]\n";
// passamos parâmetros float para f
$a = 5.0;
$b = 6.2;
f($a, $b);
print "test[a,b]=[$a,$b]\n";
// passamos parâmetros float para g
$a = 5.0;
$b = 6.0;
g($a, $b);
print "test[a,b]=[$a,$b]\n";

Comentários:

  • linha 4: ao contrário de todos os outros scripts deste curso, este script não inclui a instrução [declare(strict_types=1)]: o PHP opera no modo “coercivo”;
  • Linhas 6–13: a função [f] do parágrafo anterior, mas com os parâmetros sem tipo;
  • linhas 15–22: a função [g] faz o mesmo que a função [f], mas os tipos dos parâmetros esperados são especificados. Ela espera dois parâmetros do tipo [int]. Queremos ver o que acontece quando o parâmetro efetivo passado à função não tem o tipo esperado por ela;
  • linhas 25–26: [$i] e [$j] são dois inteiros;
  • linha 28: chamada da função [f] com parâmetros do tipo esperado;
  • linha 31: chamada da função [g] com parâmetros do tipo esperado;
  • linhas 34–35: as variáveis [$a] e [$b] são do tipo [float];
  • linha 36: chamada da função [f] com parâmetros do tipo [float];
  • Linhas 39–41: chamada da função [g] com parâmetros do tipo [float], que não é o tipo esperado.

Resultados:

1
2
3
4
5
6
7
8
9
> php basics-13.php
f[i,j]=[1,1]
test[i,j]=[1,0]
g[i,j]=[2,1]
test[i,j]=[2,0]
f[i,j]=[6,7.2]
test[a,b]=[6,6.2]
g[i,j]=[6,7]
test[a,b]=[6,6]
  • A função [f], cujos parâmetros não têm tipo, aceitou os dois parâmetros do tipo [float] e os processou da seguinte forma: [$i] é 6.0 (exibido como 6), e [$j] é 7.2;
  • a função [g] aceitou os dois parâmetros do tipo [float] mas os converteu para o tipo [int]. Isso pode ser visto na variável [$a], passada por referência, que se tornou o inteiro 6.

Os números de ponto flutuante 5.0 e 6.0 não têm parte decimal: convertê-los em inteiros não resulta em nenhuma perda de informação. O que aconteceria com o número de ponto flutuante 5.3? No PHP 7, ele era convertido silenciosamente no inteiro 5. Desde o PHP 8.1, essa conversão, que perde informação, é marcada como obsoleta (deprecated): ela se tornará um erro em uma versão futura do PHP.

Vamos agora fazer a mesma coisa no modo estrito. O script [basics-13b.php] é idêntico ao script [basics-13.php] exceto por começar com a instrução:

declare(strict_types=1);

Essa instrução especifica que os tipos dos parâmetros formais devem ser respeitados. Caso contrário, um erro é reportado. Os resultados da execução são então:

> php basics-13b.php
f[i,j]=[1,1]
test[i,j]=[1,0]
g[i,j]=[2,1]
test[i,j]=[2,0]
f[i,j]=[6,7.2]
test[a,b]=[6,6.2]

Fatal error: Uncaught TypeError: g(): Argument #1 ($i) must be of type int, float given, called in .../php8-oct-2026/scripts-console/basics/basics-13b.php on line 42 and defined in .../php8-oct-2026/scripts-console/basics/basics-13b.php:16
Stack trace:
#0 .../php8-oct-2026/scripts-console/basics/basics-13b.php(42): g(5.0, 6.0)
#1 {main}
  thrown in .../php8-oct-2026/scripts-console/basics/basics-13b.php on line 16

O interpretador PHP lançou um erro [TypeError] para indicar que o primeiro parâmetro passado à função [g] era do tipo errado: g(): Argument #1 ($i) must be of type int; float was provided. A mensagem indica o número da linha da chamada incorreta (42) e o da definição da função (16). Como esse erro não é capturado (não há [try / catch]), o script é encerrado. Recomenda-se ser estrito quanto aos tipos dos parâmetros sempre que possível, para detectar erros nas chamadas de funções: é por isso que todos os scripts do curso começam com [declare(strict_types=1)].

3.8.2. Parâmetros de funções no PHP 8

O PHP 8 aprimorou bastante a declaração e a chamada de funções. O script [basics-14.php] demonstra esses novos recursos:

<?php

// parâmetros de função no PHP 8
declare(strict_types=1);

// 1 - parâmetros com valor padrão
function greeting(string $name, string $phrase = "Hello", bool $uppercase = false): string
{
    $message = "$phrase $name";
    return $uppercase ? strtoupper($message) : $message;
}

print greeting("Pierre") . "\n";
print greeting("Pierre", "Good evening") . "\n";
// 2 - argumentos nomeados (PHP 8.0): podemos pular um parâmetro e informá-los em qualquer ordem
print greeting("Pierre", uppercase: true) . "\n";
print greeting(uppercase: true, phrase: "Hi", name: "Paul") . "\n";
// as funções predefinidas também aceitam argumentos nomeados
print str_pad(string: "7", length: 3, pad_string: "0", pad_type: STR_PAD_LEFT) . "\n";

// 3 - tipo união (PHP 8.0): o parâmetro pode ser de um dos tipos listados
function double(int|float $number): int|float
{
    return 2 * $number;
}

var_dump(double(4));
var_dump(double(4.5));

// 4 - tipo anulável: ?string equivale a string|null
function length(?string $string): int
{
    // o operador ?? retorna seu operando da direita se o operando da esquerda for null
    return strlen($string ?? "");
}

print "length(\"abc\")=" . length("abc") . ", length(null)=" . length(null) . "\n";

// 5 - tipo mixed (PHP 8.0) e expressão match (PHP 8.0)
function describe(mixed $value): string
{
    // match compara com === e retorna um valor
    return match (true) {
        is_int($value), is_float($value) => "the number $value",
        is_string($value) => "the string [$value]",
        is_bool($value) => "the boolean " . ($value ? "true" : "false"),
        is_array($value) => "an array of " . count($value) . " element(s)",
        default => "a value of type " . get_debug_type($value),
    };
}

foreach ([12, 3.5, "abc", false, [1, 2], null] as $value) {
    print describe($value) . "\n";
}

// match sobre um valor
$children = 3;
$shares = match ($children) {
    0 => 0.0,
    1, 2 => $children * 0.5,
    default => 1 + ($children - 2) * 1.0,
};
print "$children child(ren) bring $shares share(s)\n";

// 6 - número variável de parâmetros (variádico) e o operador ... (spread)
function sum(int|float ...$numbers): int|float
{
    // $numbers é um array
    return array_sum($numbers);
}

print "sum()=" . sum() . "\n";
print "sum(1, 2, 3)=" . sum(1, 2, 3) . "\n";
$values = [10, 20, 30.5];
// o array é "espalhado" em parâmetros reais
print "sum(...\$values)=" . sum(...$values) . "\n";
// o operador ... também permite mesclar arrays
$all = [0, ...$values, 40];
print "all=[" . implode(",", $all) . "]\n";

Resultados:

> php basics-14.php
Hello Pierre
Good evening Pierre
HELLO PIERRE
HI PAUL
007
int(8)
float(9)
length("abc")=3, length(null)=0
the number 12
the number 3.5
the string [abc]
the boolean false
an array of 2 element(s)
a value of type null
3 child(ren) bring 2 share(s)
sum()=0
sum(1, 2, 3)=6
sum(...$values)=60.5
all=[0,10,20,30.5,40]

Comentários:

  • linha 7: os parâmetros [$phrase] e [$uppercase] têm valores padrão. Eles podem ser omitidos na chamada da função (linha 13); nesse caso, assumem seus valores padrão;
  • linha 10: o operador ternário [condition ? value1 : value2] retorna [value1] se a condição for verdadeira e [value2] caso contrário;
  • linha 16: argumentos nomeados (PHP 8.0). O parâmetro real é precedido pelo nome do parâmetro formal seguido de dois-pontos (:). Isso permite atribuir um valor ao terceiro parâmetro sem especificar o segundo, que mantém seu valor padrão;
  • linha 17: com argumentos nomeados, a ordem dos parâmetros deixa de importar. Isso melhora a legibilidade do código: [uppercase: true] é mais descritivo do que um [true] isolado;
  • linha 19: as funções predefinidas do PHP também aceitam argumentos nomeados. Seus nomes são os listados na documentação do php.net;
  • linha 22: o tipo união [int|float] (PHP 8.0) indica que o parâmetro pode ser um [int] ou um [float]. O mesmo vale para o resultado;
  • linha 31: o tipo [?string] é um tipo anulável (nullable): o parâmetro é uma string ou o valor [null]. É uma notação abreviada de [string|null]. Observação: no PHP 7, era comum escrever [string $string = null] para obter o mesmo efeito. Essa notação (“nullable implícito”) é obsoleta desde o PHP 8.4: é preciso escrever [?string $string = null];
  • Linha 34: o operador [??] que já encontramos: se [$string] for igual a [null], a string vazia é usada. Na verdade, desde o PHP 8.1, passar [null] a um parâmetro não anulável de uma função predefinida, como [strlen(null)] aqui, é obsoleto;
  • linha 40: o parâmetro do tipo [mixed] aceita qualquer valor, inclusive [null];
  • Linhas 43 a 49: a expressão [match] (PHP 8.0). Ela compara o valor entre parênteses com os valores à esquerda das setas => e retorna o valor à direita da primeira seta cuja comparação for verdadeira. Com [match (true)], as condições são escritas à esquerda: a primeira condição verdadeira prevalece. Vários valores podem ser separados por vírgulas (linha 44). [default] cobre todos os outros casos;
  • linha 48: a função [get_debug_type] (PHP 8.0) retorna o nome do tipo de um valor como ele é escrito no código: int, float, string, null ou o nome da classe de um objeto. Já [gettype] retornava nomes históricos, como integer ou double;
  • linhas 58 a 62: [match] aplicado a um valor. Aqui, a variável [$children] é comparada aos valores 0, depois 1 e depois 2; caso contrário, aplica-se o caso [default]. Ao contrário da instrução [switch], que [match] substitui na prática, a comparação é feita com [===], [match] é uma expressão que retorna um valor e não há instrução [break] com que se preocupar. Se nenhum ramo for adequado e não houver *[default]*, *[match] lança um erro *[UnhandledMatchError] ;
  • linha 66: [int|float ...$numbers] é um parâmetro variádico: a função aceita qualquer número de parâmetros reais (até nenhum), que o PHP reúne no array [$numbers]. Um parâmetro variádico é sempre o último;
  • linha 76: o operador [...] (spread) colocado antes de um array em uma chamada “espalha” o array: seus elementos se tornam os parâmetros reais da função. [sum(...$values)] equivale a [sum(10, 20, 30.5)];
  • linha 78: o mesmo operador permite inserir os elementos de um array em outro array.

3.8.3. Resultados retornados por uma função

O script [basics-15.php] é o seguinte:

<?php

// tipos no modo estrito
declare(strict_types=1);

// resultados retornados por uma função
// uma função pode retornar vários valores em um array
[$res1, $res2, $res3] = f1(10);
print "[$res1,$res2,$res3]\n";
$res = f1(10);
for ($i = 0; $i < count($res); $i++) {
    print "f1: res[$i]=$res[$i]\n";
}
// um array associativo também pode ser "desestruturado"
["min" => $min, "max" => $max] = minMax([4, -2, 17, 8]);
print "minMax: [min=$min,max=$max]\n";

// uma função pode retornar um objeto
$res = f2(10);
print "f2: [$res->res1,$res->res2,$res->res3]\n";
// que tipo de objeto?
print "kind of object: ";
var_dump($res);

// fazemos o mesmo com a função f3
$res = f3(10);
print "f3: [$res->res1,$res->res2,$res->res3]\n";
// que tipo de objeto?
print "kind of object: ";
var_dump($res);

// uma função pode retornar um objeto ou null
$res = f4(10);
// o operador nullsafe ?-> retorna null em vez de causar um erro se $res for null
print "f4(10): res1=" . ($res?->res1 ?? "none") . "\n";
$res = f4(-10);
print "f4(-10): res1=" . ($res?->res1 ?? "none") . "\n";

// fim
exit;

// função f1
function f1(int $value): array
{
    // retorna um array ($value+1,$value+2,$value+3)
    return [$value + 1, $value + 2, $value + 3];
}

// função minMax
function minMax(array $numbers): array
{
    // retorna um array associativo
    return ["min" => min($numbers), "max" => max($numbers)];
}

// função f2
function f2(int $value): object
{
    // retorna um objeto ($value+1,$value+2,$value+3)
    // obtido transformando um array associativo em objeto
    return (object) ["res1" => $value + 1, "res2" => $value + 2, "res3" => $value + 3];
}

// função f3 - faz o mesmo que a função f2
function f3(int $value): object
{
    // retorna um objeto ($value+1,$value+2,$value+3)
    $res = new stdClass();
    $res->res1 = $value + 1;
    $res->res2 = $value + 2;
    $res->res3 = $value + 3;
    // retorna o objeto
    return $res;
}

// função f4 - retorna um objeto se $value for positivo, null caso contrário
function f4(int $value): ?object
{
    return $value >= 0 ? f3($value) : null;
}

Resultados:

> php basics-15.php
[11,12,13]
f1: res[0]=11
f1: res[1]=12
f1: res[2]=13
minMax: [min=-2,max=17]
f2: [11,12,13]
kind of object: object(stdClass)#1 (3) {
  ["res1"]=>
  int(11)
  ["res2"]=>
  int(12)
  ["res3"]=>
  int(13)
}
f3: [11,12,13]
kind of object: object(stdClass)#2 (3) {
  ["res1"]=>
  int(11)
  ["res2"]=>
  int(12)
  ["res3"]=>
  int(13)
}
f4(10): res1=11
f4(-10): res1=none

Comentários:

  • O programa anterior mostra que uma função PHP pode retornar um conjunto de resultados em vez de um só, na forma de um array ou de um objeto. O conceito de objeto é explicado em um capítulo posterior;
  • linhas 43 a 47: a função [f1] retorna vários valores na forma de um array ([array]);
  • linha 8: o array retornado é desempacotado em três variáveis;
  • linha 15: a desestruturação também funciona com um array associativo: para cada variável, especifica-se a chave do valor a ser recuperado. A função [minMax] retorna um dicionário (linha 53). As funções predefinidas [min] e [max] retornam o menor e o maior elemento de um array;
  • linhas 57 a 62: a função [f2] retorna vários valores na forma de um objeto ([object]). Ela faz isso convertendo um array associativo em objeto com o operador [(object)]: cada chave do array se torna uma propriedade do objeto;
  • Linhas 65 a 74: a função [f3] faz o mesmo que a função [f2], mas cria explicitamente um objeto do tipo [stdClass] (linha 68) e depois adiciona propriedades a ele. O atributo A de um objeto O é denotado por [$O->A];
  • linha 23: a função [var_dump] dá acesso ao tipo e ao conteúdo do objeto. Nos resultados, vemos que o objeto é do tipo [stdClass], que sua propriedade [res1] é do tipo inteiro e tem o valor 11, etc. O número #1 ou #2 que segue o tipo é um número interno do objeto;
  • linha 77: o tipo de resultado [?object] indica que a função [f4] retorna um objeto ou [null];
  • Linhas 35 a 37: o operador nullsafe [?->] (PHP 8.0). Se [$res] for igual a [null], a expressão [$res?->res1] é igual a [null] em vez de causar um erro; o operador [??] então substitui [null] por “none”. Aqui, o operador [??] bastaria sozinho, pois ele não sinaliza a ausência da propriedade. O operador [?->] será particularmente útil com objetos e seus métodos: [$client?->getAddress()?->getCity()].

Observação: o curso de PHP 7 continha uma função que escrevia [$res->res1 = ...] sem ter criado o objeto [$res]. O PHP 7 então criava, por padrão, um objeto [stdClass] com um simples aviso. A partir do PHP 8.0, isso é um erro fatal (Attempt to assign property on null): um objeto deve sempre ser criado antes de ser usado.

3.8.4. Funções também são valores

No PHP, uma função pode ser armazenada em uma variável, passada como parâmetro a outra função ou retornada como resultado. O script [basics-17.php] demonstra as diferentes maneiras de escrever e usar essas funções:

<?php

// funções também são valores
declare(strict_types=1);

$numbers = [4, -2, 17, 8, -5];

// 1 - uma função anônima atribuída a uma variável
$square = function (int $x): int {
    return $x * $x;
};
print "square(5)=" . $square(5) . "\n";

// 2 - uma função anônima passada como parâmetro a uma função predefinida
// array_map aplica a função a cada elemento do array
$squares = array_map($square, $numbers);
print "squares=[" . implode(",", $squares) . "]\n";

// 3 - uma função anônima que usa uma variável externa: a palavra-chave use
$threshold = 5;
$large = array_filter($numbers, function (int $x) use ($threshold): bool {
    return $x > $threshold;
});
print "numbers > $threshold: [" . implode(",", $large) . "]\n";

// 4 - a arrow function (PHP 7.4): uma única expressão, variáveis externas capturadas automaticamente
$positives = array_filter($numbers, fn(int $x): bool => $x >= 0);
print "positives=[" . implode(",", $positives) . "]\n";
// ordenação com uma função de comparação: o operador <=> retorna -1, 0 ou 1
$sorted = $numbers;
usort($sorted, fn(int $a, int $b): int => $b <=> $a);
print "descending sort=[" . implode(",", $sorted) . "]\n";

// 5 - busca em um array (PHP 8.4)
print "first negative: " . array_find($numbers, fn(int $x): bool => $x < 0) . "\n";
print "at least one > 10: " . var_export(array_any($numbers, fn(int $x): bool => $x > 10), true) . "\n";
print "all > -10: " . var_export(array_all($numbers, fn(int $x): bool => $x > -10), true) . "\n";

// 6 - a sintaxe de callable de primeira classe (PHP 8.1): functionName(...)
$uppercase = strtoupper(...);
print $uppercase("hello") . "\n";
$names = ["dupont", "durand", "martin"];
print "names=[" . implode(",", array_map(ucfirst(...), $names)) . "]\n";

// 7 - o operador pipe |> (PHP 8.5): o resultado à esquerda é passado à função à direita
$result = "  Hello everybody out there  "
    |> trim(...)
    |> strtolower(...)
    |> (fn(string $s): string => str_replace(" ", "-", $s));
print "result=[$result]\n";
// equivalente sem o operador pipe
$result = str_replace(" ", "-", strtolower(trim("  Hello everybody out there  ")));
print "result=[$result]\n";

Resultados:

> php basics-17.php
square(5)=25
squares=[16,4,289,64,25]
numbers > 5: [17,8]
positives=[4,17,8]
descending sort=[17,8,4,-2,-5]
first negative: -2
at least one > 10: true
all > -10: true
HELLO
names=[Dupont,Durand,Martin]
result=[hello-everybody-out-there]
result=[hello-everybody-out-there]

Comentários:

  • linhas 9 a 11: uma função anônima (sem nome) é atribuída à variável [$square]. Observe o ponto e vírgula no final: trata-se de uma atribuição;
  • linha 12: a função é chamada por meio da variável;
  • linha 16: a função predefinida [array_map] aplica a função passada como primeiro parâmetro a cada elemento do array passado como segundo parâmetro e retorna o array de resultados;
  • linhas 21 a 23: a função predefinida [array_filter] retorna os elementos do array para os quais a função passada como segundo parâmetro retorna [true]. Uma função anônima não enxerga as variáveis do código ao redor: a palavra-chave [use ($threshold)] dá a ela acesso à variável [$threshold]. Observe que [array_filter] mantém as chaves dos elementos selecionados; isso não tem efeito aqui porque [implode] usa apenas os valores;
  • Linha 27: uma função de seta (PHP 7.4): [fn(parameters) => expression]. Ela contém apenas uma expressão, cujo valor é o resultado da função. Ela tem automaticamente acesso de leitura às variáveis do código ao redor: não há necessidade de [use]. É a maneira mais concisa de escrever pequenas funções passadas como parâmetros;
  • Linha 31: a função [usort] ordena um array usando uma função de comparação que recebe dois elementos, [$a] e [$b], e retorna um número negativo, zero ou um número positivo, conforme [$a] deva ser colocado antes, na mesma posição ou depois de [$b]. O operador [<=>] (“spaceship”) retorna exatamente -1, 0 ou 1. Ao escrever [$b <=> $a] em vez de [$a <=> $b], obtemos uma ordenação decrescente. Observe que [usort] modifica o array que lhe é passado (passagem por referência): por isso, ordenamos uma cópia ([$sorted]) do array [$numbers];
  • Linha 35: as funções [array_find], [array_any] e [array_all] foram introduzidas no PHP 8.4. [array_find] retorna o primeiro elemento para o qual a função retorna [true] (ou [null] se não houver nenhum), [array_any] retorna [true] se pelo menos um elemento satisfizer a condição e [array_all] se todos a satisfizerem;
  • linha 40: sintaxe de callable de primeira classe (PHP 8.1): [functionName(...)], com três pontos entre os parênteses, não chama a função, mas retorna a própria função como um objeto [Closure]. Ela pode então ser usada como uma função anônima;
  • Linha 43: a função predefinida [ucfirst] (primeira letra maiúscula) é passada a [array_map];
  • Linhas 46 a 49: o operador pipe [|>] (PHP 8.5). A expressão [value |> function] chama a função tendo o valor como único parâmetro. As chamadas são encadeadas da esquerda para a direita, na ordem em que são lidas: os espaços no início e no fim são removidos com [trim], o texto é convertido em minúsculas com [strtolower] e depois os espaços são substituídos por hifens. Uma função de seta usada com [|>] deve ser colocada entre parênteses;
  • linha 52: a mesma coisa sem o operador pipe. As funções são aninhadas e lidas de dentro para fora, na ordem inversa da execução.

3.9. Arquivos de texto

O script [basics-16.php] é o seguinte:

<?php

// respeito estrito ao tipo dos parâmetros das funções
declare(strict_types=1);

// processamento sequencial de um arquivo de texto
// trata-se de um conjunto de linhas no formato login:pwd:uid:gid:info:dir:shell
// cada linha é colocada em um dicionário na forma login => [uid, gid, info, dir, shell]
// definimos o nome do arquivo
$INFO = "info.txt";
// abrimos o arquivo para criação
$file = fopen($INFO, "w");
if ($file === false) {
    print "Error opening the file $INFO for writing\n";
    exit;
}
// geramos um conteúdo arbitrário
for ($i = 0; $i < 100; $i++) {
    fputs($file, "login$i:pwd$i:uid$i:gid$i:info$i:dir$i:shell$i\n");
}
// fechamos o arquivo
fclose($file);

// processamos o arquivo - fgets mantém a marca de fim de linha
// isso evita obter uma string vazia ao ler uma linha em branco
// abrimos o arquivo para leitura
$file = fopen($INFO, "r");
if ($file === false) {
    print "Error opening the file $INFO for reading\n";
    exit;
}

// o dicionário de informações
$dict = [];
// as linhas têm menos de 1000 caracteres
// a leitura da linha para na marca de fim de linha
// ou na marca de fim de arquivo
while (($line = fgets($file, 1000)) !== false) {
    // removemos a marca de fim de linha, se existir
    $line = cutNewLineChar($line);
    // colocamos a linha em um array
    $info = explode(":", $line);
    // recuperamos o login
    $login = array_shift($info);
    // ignoramos a senha (pwd)
    array_shift($info);
    // criamos uma entrada no dicionário
    $dict[$login] = $info;
}
// fechamos o arquivo
fclose($file);

// uso do dicionário
displayInfo($dict, "login10");
displayInfo($dict, "X");

// outra forma de ler um arquivo de texto: a função file
$lines = file($INFO, FILE_IGNORE_NEW_LINES);
print "the file $INFO has " . count($lines) . " lines, the last one is [" . array_last($lines) . "]\n";

// fim
exit;

// --------------------------------------------------------------------------
function displayInfo(array $dict, string $key): void
{
    // exibe o valor associado a key no dicionário $dict, se existir
    if (isset($dict[$key])) {
        // o valor existe - é um array?
        $value = $dict[$key];
        if (is_array($value)) {
            print "[$key," . implode(":", $value) . "]\n";
        } else {
            // $value não é um array
            print "[$key,$value]\n";
        }
    } else {
        // $key não é uma chave do dicionário $dict
        print "the key [$key] does not exist\n";
    }
}

// --------------------------------------------------------------------------
function cutNewLineChar(string $line): string
{
    // removemos a marca de fim de linha de $line, se existir
    // (\n no Unix, \r\n no Windows)
    return rtrim($line, "\r\n");
}

O arquivo [info.txt] criado pelo script:

1
2
3
4
5
6
login0:pwd0:uid0:gid0:info0:dir0:shell0
login1:pwd1:uid1:gid1:info1:dir1:shell1
login2:pwd2:uid2:gid2:info2:dir2:shell2
…
login98:pwd98:uid98:gid98:info98:dir98:shell98
login99:pwd99:uid99:gid99:info99:dir99:shell99

Os resultados:

1
2
3
4
> php basics-16.php
[login10,uid10:gid10:info10:dir10:shell10]
the key [X] does not exist
the file info.txt has 100 lines, the last one is [login99:pwd99:uid99:gid99:info99:dir99:shell99]

Comentários:

  • Linha 12: [fopen(file_name, "w")] abre o arquivo [file_name] em modo de escrita (w=write). Se o arquivo não existir, ele é criado. Se existir, seu conteúdo é apagado. O arquivo é criado no diretório atual, aquele a partir do qual o script foi executado. Se a criação falhar, [fopen] emite um aviso e retorna o valor [false];
  • linha 13: o resultado de [fopen] é testado por comparação estrita com [false];
  • linha 19: [fputs($file, $string)] escreve [$string] no arquivo [$file]. Aqui, a string termina com o marcador de fim de linha [\n];
  • linha 22: [fclose($file)] fecha o arquivo [$file];
  • linha 27: [fopen(file_name, "r")] abre o arquivo [file_name] em modo de leitura (r=read). Se a abertura do arquivo falhar (por exemplo, se o arquivo não existir), [fopen] retorna o valor [false];
  • linha 34: o dicionário é inicializado vazio antes de ser preenchido. O PHP criaria o array na primeira atribuição de [$dict[$login] = ...], mas, se o arquivo estivesse vazio, a variável não existiria e seu uso provocaria um aviso;
  • linha 38: [fgets($file, 1000)] lê a próxima linha do arquivo, limitada a 1.000 caracteres. A operação [while (($line = fgets($file, 1000)) !== false) {...}] consiste em duas operações sucessivas: 1) [$line = fgets(...)] e 2) [while ($line !== false)]. Depois que o último caractere do arquivo foi lido, a função [fgets] retorna o valor [false], e o laço [while] é interrompido. Aqui, a função [fgets] tenta ler até 1.000 caracteres, mas para assim que encontra um caractere de fim de linha. Como todas as linhas aqui têm menos de 1.000 caracteres, [fgets] lê uma linha de texto, incluindo o caractere de fim de linha. O curso de PHP 7 escrevia [while ($line = fgets($file, 1000))]: o laço seria interrompido prematuramente diante de uma última linha reduzida a "0", sem caractere de fim de linha, pois a string "0" é convertida em [false]. A comparação estrita [!== false] evita essa armadilha;
  • linha 40: a função [cutNewLineChar] remove quaisquer caracteres de fim de linha;
  • linha 44: a função [array_shift($array)] remove o primeiro elemento de [$array] e o retorna como resultado;
  • linha 46: aqui, ignoramos o resultado retornado por [array_shift];
  • Linha 58: outra maneira de ler um arquivo de texto. A função [file] retorna um array contendo todas as linhas do arquivo. Com a opção [FILE_IGNORE_NEW_LINES], os caracteres de fim de linha são removidos. Isso é mais simples do que o laço com [fgets], mas o arquivo inteiro é carregado na memória: para um arquivo muito grande, ainda é preferível ler linha a linha;
  • linha 71: a função [is_array($variable)] retorna [true] se [$variable] for um array e [false] caso contrário;
  • linha 84: o caractere de fim de linha é a string "\r\n" em sistemas Windows e "\n" em sistemas Unix. A função [rtrim($string, $characters)] remove todos os caracteres presentes em [$characters](neste caso, \r e \n) do final de [$string]. Sem o segundo parâmetro, [rtrim] remove todos os “espaços” (espaços em branco, tabulações, quebras de linha etc.); a função [trim] faz o mesmo nas duas extremidades da string.

3.10. Codificação/decodificação de JSON

A pasta [scripts-console/json] contém os scripts desta seção:

1
2
3
4
5
json
├── family.json
├── json-01.php
├── json-02.php
└── json-03.php

A codificação/decodificação JSON (JavaScript Object Notation) é algo que usaremos intensamente no exercício que serve de fio condutor deste documento. Os scripts [json-01.php, json-02.php, json-03.php] explicam o que você precisa saber para o restante do documento.

O script [json-01.php] é o seguinte:

<?php

declare(strict_types=1);

$array1 = ["lastName" => "séléné", "firstName" => "bénédicte", "age" => 34];
// codificação JSON do array array1 com caracteres Unicode escapados
print "JSON encoding of the array array1 with escaped Unicode characters\n";
$json1 = json_encode($array1);
print "json1=$json1\n";
// codificação JSON do array array1 com caracteres Unicode não escapados
print "JSON encoding of the array array1 with unescaped Unicode characters\n";
$json2 = json_encode($array1, JSON_UNESCAPED_UNICODE);
print "json2=$json2\n";
// decodificação JSON para um array associativo
print "JSON decoding of json2 into an associative array\n";
$array2 = json_decode($json2, true);
var_dump($array2);
foreach ($array2 as $key => $value) {
    print "$key:$value\n";
}
// decodificação JSON para um objeto
print "JSON decoding of json2 into a stdClass object\n";
$object2 = json_decode($json2);
var_dump($object2);
print "firstName=$object2->firstName\n";
print "lastName=$object2->lastName\n";
print "age=$object2->age\n";

Resultados:

> php json-01.php
JSON encoding of the array array1 with escaped Unicode characters
json1={"lastName":"s\u00e9l\u00e9n\u00e9","firstName":"b\u00e9n\u00e9dicte","age":34}
JSON encoding of the array array1 with unescaped Unicode characters
json2={"lastName":"séléné","firstName":"bénédicte","age":34}
JSON decoding of json2 into an associative array
array(3) {
  ["lastName"]=>
  string(9) "séléné"
  ["firstName"]=>
  string(11) "bénédicte"
  ["age"]=>
  int(34)
}
lastName:séléné
firstName:bénédicte
age:34
JSON decoding of json2 into a stdClass object
object(stdClass)#1 (3) {
  ["lastName"]=>
  string(9) "séléné"
  ["firstName"]=>
  string(11) "bénédicte"
  ["age"]=>
  int(34)
}
firstName=bénédicte
lastName=séléné
age=34

Comentários:

  • linha 8: a função [json_encode] converte seu parâmetro em string JSON. Na string resultante, o caractere acentuado “é” foi substituído por seu código Unicode, que começa com \u;
  • linha 12: repetimos o mesmo processo, desta vez especificando que os caracteres Unicode devem ser preservados como estão. A string JSON resultante é muito mais legível;
  • Linhas 16 a 20: realizamos a operação inversa. Convertemos a string JSON em um array associativo: esse é o papel do segundo parâmetro, [true], de [json_decode]. Os resultados mostram que de fato obtivemos um array associativo;
  • Linhas 23 a 27: sem o parâmetro [true], [json_decode] converte a string JSON em um objeto do tipo [stdClass]. O atributo A de um objeto O é denotado por [$O->A].

Arrays de vários níveis podem ser codificados em JSON, como mostra o script a seguir, [json-02.php]:

<?php

declare(strict_types=1);

$array = [
    "lastName" => "séléné", "firstName" => "bénédicte", "age" => 34,
    "husband" => ["lastName" => "icariù", "firstName" => "ignacio", "age" => 35],
    "children" => [
        ["firstName" => "angèle", "age" => 8],
        ["firstName" => "andré", "age" => 2],
    ],
];
// codificação JSON do array multinível
print "JSON encoding of a multi-level array\n";
$json = json_encode($array, JSON_UNESCAPED_UNICODE);
print "json=$json\n";
// a mesma codificação, apresentada de forma legível
print "JSON encoding with the JSON_PRETTY_PRINT option\n";
print json_encode($array["husband"], JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT) . "\n";

Resultados:

1
2
3
4
5
6
7
8
9
> php json-02.php
JSON encoding of a multi-level array
json={"lastName":"séléné","firstName":"bénédicte","age":34,"husband":{"lastName":"icariù","firstName":"ignacio","age":35},"children":[{"firstName":"angèle","age":8},{"firstName":"andré","age":2}]}
JSON encoding with the JSON_PRETTY_PRINT option
{
    "lastName": "icariù",
    "firstName": "ignacio",
    "age": 35
}

Comentários:

Na string JSON:

  • os arrays não associativos (listas) são delimitados por colchetes [] ;
  • os arrays associativos são delimitados por chaves {} .

Linha 19: as opções de [json_encode] são combinadas com o operador | (OU binário). A opção [JSON_PRETTY_PRINT] produz uma string JSON indentada em várias linhas, o que a torna mais legível.

O script [json-03.php] demonstra como processar o seguinte arquivo JSON [family.json]:

{
    "wife": {
        "lastName": "séléné",
        "firstName": "bénédicte",
        "age": 34
    },
    "husband": {
        "lastName": "icariù",
        "firstName": "ignacio",
        "age": 35
    },
    "children": [
        {
            "firstName": "angèle",
            "age": 8
        },
        {
            "firstName": "andré",
            "age": 2
        }
    ]
}

O script [json-03.php] é o seguinte:

<?php

declare(strict_types=1);

// leitura do arquivo JSON
$json = file_get_contents("family.json");
// o conteúdo lido é um JSON válido? (PHP 8.3)
if ($json === false || !json_validate($json)) {
    print "The file [family.json] is missing or does not contain valid JSON\n";
    exit;
}
// decodificação JSON para um objeto
$family1 = json_decode($json);
print "----family1\n";
var_dump($family1);
// decodificação JSON para um array associativo
print "----family2\n";
$family2 = json_decode($json, true);
var_dump($family2);

Comentários:

  • linha 6: a função [file_get_contents] lê o conteúdo do arquivo chamado [family.json] e o armazena na variável [$json]. Ela retorna [false] se a operação de leitura falhar;
  • Linha 8: a função [json_validate] (PHP 8.3) retorna [true] se a string passada como parâmetro for um JSON válido. Anteriormente, era necessário decodificar a string e depois chamar a função [json_last_error];
  • linhas 13 a 19: a string é então decodificada em um objeto e depois em um array associativo.

Resultados:

> php json-03.php
----family1
object(stdClass)#2 (3) {
  ["wife"]=>
  object(stdClass)#1 (3) {
    ["lastName"]=>
    string(9) "séléné"
    ["firstName"]=>
    string(11) "bénédicte"
    ["age"]=>
    int(34)
  }
  ["husband"]=>
  object(stdClass)#3 (3) {
    ["lastName"]=>
    string(7) "icariù"
    ["firstName"]=>
    string(7) "ignacio"
    ["age"]=>
    int(35)
  }
  ["children"]=>
  array(2) {
    [0]=>
    object(stdClass)#4 (2) {
      ["firstName"]=>
      string(7) "angèle"
      ["age"]=>
      int(8)
    }
    [1]=>
    object(stdClass)#5 (2) {
      ["firstName"]=>
      string(6) "andré"
      ["age"]=>
      int(2)
    }
  }
}
----family2
array(3) {
  ["wife"]=>
  array(3) {
    ["lastName"]=>
    string(9) "séléné"
    ["firstName"]=>
    string(11) "bénédicte"
    ["age"]=>
    int(34)
  }
  ["husband"]=>
  array(3) {
    ["lastName"]=>
    string(7) "icariù"
    ["firstName"]=>
    string(7) "ignacio"
    ["age"]=>
    int(35)
  }
  ["children"]=>
  array(2) {
    [0]=>
    array(2) {
      ["firstName"]=>
      string(7) "angèle"
      ["age"]=>
      int(8)
    }
    [1]=>
    array(2) {
      ["firstName"]=>
      string(6) "andré"
      ["age"]=>
      int(2)
    }
  }
}
  • A primeira parte dos resultados mostra o objeto resultante da decodificação do arquivo JSON [family.json]: os objetos JSON se tornaram objetos [stdClass] e a lista JSON de filhos se tornou um array PHP;
  • a segunda parte mostra o array associativo resultante da mesma decodificação: todos os objetos JSON se tornaram arrays associativos.