Skip to content

5. As classes

Vocabulário: uma classe (palavra-chave [class]) é um tipo do PHP. Uma variável desse tipo é chamada de objeto. Um objeto é uma instância de uma classe.

É neste capítulo que a evolução do PHP entre as versões 7 e 8 é mais evidente. O PHP 8 introduziu uma série de recursos que tornam a escrita de classes mais concisa e mais segura: atributos tipados, promoção de parâmetros do construtor, atributos somente leitura ([readonly]), enumerações ([enum]), property hooks e visibilidade assimétrica (PHP 8.4), clonagem com modificação (PHP 8.5)... Apresentamos esses conceitos por meio de exemplos, seguindo a progressão do curso de PHP 7: começamos pela classe mais básica e avançamos até uma classe escrita segundo as boas práticas atuais.

5.1. A estrutura de diretórios dos scripts

Os scripts deste capítulo estão na pasta [scripts-console/classes]:

php8-oct-2026/scripts-console/classes
├── json
│   ├── json-01.php
│   ├── json-02.php
│   ├── json-03.php
│   ├── json-04.php
│   ├── Person.php
│   ├── Person2.php
│   ├── Person3.php
│   └── Person4.php
├── classes-01.php
├── classes-02.php
├── ...
├── classes-26.php
├── Gender.php
├── Person.php
├── Student.php
└── Teacher.php

Como nos capítulos anteriores, um script de console é executado em um terminal do [VS Code] aberto na pasta do script, com o comando [php script-name.php].

5.2. Qualquer variável pode se tornar um objeto com atributos?

No PHP 7, era possível escrever [$obj1->attr1 = "one";] em uma variável inexistente [$obj1]: o PHP então criava silenciosamente (com um simples aviso) um objeto do tipo [stdClass] com o atributo [attr1]. Isso não é mais possível no PHP 8. O script [classes-01.php] é o seguinte:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// no PHP 8, uma variável inexistente não se torna mais magicamente um objeto
try {
    $obj0->attr1 = "one";
} catch (\Error $e) {
    print "Error: " . $e->getMessage() . "\n";
}
// um objeto genérico deve ser criado explicitamente
$obj1 = new \stdClass();
// um objeto [stdClass] pode receber atributos criados dinamicamente
$obj1->attr1 = "one";
$obj1->attr2 = 100;
// exibe o objeto
print "object1=[$obj1->attr1,$obj1->attr2]\n";
// modifica o objeto
$obj1->attr2 += 100;
// exibe o objeto
print "object1=[$obj1->attr1,$obj1->attr2]\n";
// copia o valor de object1 (endereço do objeto apontado) para object2
// as duas variáveis são então diferentes, mas apontam para o mesmo objeto
$obj2 = $obj1;
// modifica obj2
$obj2->attr2 = 0;
// exibe os dois objetos
print "object1=[$obj1->attr1,$obj1->attr2]\n";
print "object2=[$obj2->attr1,$obj2->attr2]\n";
// altera o objeto apontado por obj1
$obj1 = new \stdClass();
print "obj1:\n";
print_r($obj1);
print "obj2:\n";
print_r($obj2);
// atribui a referência (o endereço) de object2 a object3
// $obj2 e $obj3 passam a ser uma única e mesma variável
$obj3 = &$obj2;
print "obj2:\n";
print_r($obj2);
print "obj3:\n";
print_r($obj3);
// modifica obj3
$obj3->attr2 = 10;
// exibe os dois objetos
print "object2=[$obj2->attr1,$obj2->attr2]\n";
print "object3=[$obj3->attr1,$obj3->attr2]\n";
// altera o objeto apontado por obj2
$obj2 = new \stdClass();
$obj2->attr3 = "two";
$obj2->attr4 = 20;
// exibe os dois objetos $obj2 e $obj3
print "obj2:\n";
print_r($obj2);
print "obj3:\n";
print_r($obj3);

// um objeto é um dicionário?
try {
    print count($obj3) . "\n";
} catch (\TypeError $e) {
    print "Error: " . $e->getMessage() . "\n";
}
// o número de atributos é obtido com [get_object_vars]
print "number of attributes: " . count(get_object_vars($obj3)) . "\n";
// um objeto pode ser percorrido com [foreach]
foreach ($obj3 as $attribute => $value) {
    print "obj3[$attribute]=$value\n";
}
// um array associativo pode ser transformado em objeto [stdClass] e vice-versa
$obj4 = (object) ["name" => "Langevin", "age" => 48];
print "obj4=[$obj4->name,$obj4->age]\n";
print_r((array) $obj4);
// fim
exit;

Resultados:

> php classes-01.php
Error: Attempt to assign property "attr1" on null
object1=[one,100]
object1=[one,200]
object1=[one,0]
object2=[one,0]
obj1:
stdClass Object
(
)
obj2:
stdClass Object
(
    [attr1] => one
    [attr2] => 0
)
obj2:
stdClass Object
(
    [attr1] => one
    [attr2] => 0
)
obj3:
stdClass Object
(
    [attr1] => one
    [attr2] => 0
)
object2=[one,10]
object3=[one,10]
obj2:
stdClass Object
(
    [attr3] => two
    [attr4] => 20
)
obj3:
stdClass Object
(
    [attr3] => two
    [attr4] => 20
)
Error: count(): Argument #1 ($value) must be of type Countable|array, stdClass given
number of attributes: 2
obj3[attr3]=two
obj3[attr4]=20
obj4=[Langevin,48]
Array
(
    [name] => Langevin
    [age] => 48
)

Comentários

  • Linhas 7 a 9: no PHP 8, a variável [$obj0] não existe, e a operação [$obj0->attr1 = "one"] lança um erro do tipo [\Error] (linha 2 dos resultados) em vez de criar um objeto. Examinaremos a estrutura [try / catch] no capítulo sobre exceções. Por enquanto, basta saber que ela permite capturar o erro e continuar a execução do script;
  • linha 13: um objeto genérico deve ser criado explicitamente com o operador [new]. A classe predefinida [stdClass] é uma classe vazia;
  • Linhas 15 e 16: a notação [$obj->attr] designa o atributo [attr] do objeto [$obj]. Se ele não existir, é criado; isso é chamado de atributo dinâmico. A classe [stdClass] foi concebida para esse fim: é possível adicionar a ela quantos atributos se quiser;
  • Linha 25: a expressão [$obj2 = $obj1], quando [$obj1] é um objeto, é uma cópia de referências: [$obj2] e [$obj1] são referências (endereços) para o mesmo objeto. O próprio objeto pode ser modificado por qualquer uma das referências;
  • Linhas 27 a 30: têm o objetivo de mostrar que [$obj1] e [$obj2] são duas variáveis diferentes que apontam para o mesmo objeto. [$obj2 = $obj1] copiou o valor de [$obj1] para a variável [$obj2] (operação 1 abaixo). O valor de [$obj1] é o endereço de um objeto. Assim, [$obj1] e [$obj2] apontam para o mesmo objeto. Quando se manipula uma variável [$obj] que aponta para um objeto, o PHP manipula o objeto apontado. Como mostra o diagrama abaixo, podemos modificar o objeto referenciado tanto por meio de [$obj1] quanto por meio de [$obj2]. Isso é ilustrado nas linhas 5 e 6 dos resultados;

Image

  • linha 39: a expressão [$obj3 = &$obj2] faz com que [$obj2] e [$obj3] fiquem no mesmo endereço [1 below]. Pode-se dizer que as duas variáveis são aliases da mesma posição de memória. Ambas apontam para um objeto, o Objeto A abaixo: [2];
  • Linha 50: a operação [$obj2 = new \stdClass()] cria um novo objeto, o Objeto B [3 below], e o endereço desse novo objeto é atribuído à variável [$obj2] [4]. Como [$obj2] e [$obj3] são dois aliases da mesma posição de memória, [$obj3] também aponta para o novo Objeto B. Isso é mostrado nas linhas 31 a 42 dos resultados;

Image

  • Linha 61: um objeto é um dicionário? No PHP 7, a função [count] aceitava um objeto (com um aviso) e retornava 1, o que não fazia sentido. No PHP 8, ela lança um erro [TypeError]: [count] aceita apenas arrays ou objetos que implementam a interface [Countable] (linha 43 dos resultados);
  • linha 66: a função [get_object_vars] retorna os atributos de um objeto como um array associativo. O número de elementos do array é igual ao número de atributos do objeto;
  • Linhas 68 e 69: um objeto pode ser percorrido com [foreach], assim como um dicionário. As chaves são os nomes dos atributos, e os valores são os valores desses mesmos atributos. Assim, um objeto tem semelhanças com um dicionário, mas não é um. No PHP 7, essa iteração era feita com a função [each], que desde então foi removida;
  • linhas 72 a 74: o operador de conversão [(object)] converte um array associativo em um objeto [stdClass], e o operador [(array)] faz a operação inversa.

5.3. Uma classe Person sem atributos declarados

No PHP 7, uma classe podia usar atributos que não havia declarado: bastava escrever [$p->firstName = "Paul";] para criar o atributo [firstName] no objeto [$p], como se faz com [stdClass]. Esses atributos dinâmicos em objetos de uma classe comum são obsoletos desde o PHP 8.2: cada vez que um atributo desse tipo é criado, a mensagem “Deprecated: Creation of dynamic property Person::$firstName is deprecated” é exibida. Eles serão removidos em uma versão futura do PHP. O motivo é simples: um erro de digitação no nome de um atributo ([$p->firstNam = "Paul"]) criaria silenciosamente um novo atributo em vez de relatar o erro.

Há três exceções a essa regra:

  • a classe [stdClass], que acabamos de usar, ainda aceita atributos dinâmicos;
  • uma classe precedida pelo atributo [#[\AllowDynamicProperties]] também os aceita. Esse atributo foi concebido para facilitar a migração de código legado. Não o usaremos neste curso;
  • uma classe que define os métodos mágicos [__get] e [__set] decide por conta própria o que fazer com um atributo não declarado.

É essa terceira solução que o script [classes-02.php] apresenta:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

class Person
{
    // os atributos não são declarados um a um:
    // eles são armazenados em um array privado
    private array $attributes = [];

    // chamado ao escrever um atributo não declarado: $p->x = value
    public function __set(string $name, mixed $value): void
    {
        $this->attributes[$name] = $value;
    }

    // chamado ao ler um atributo não declarado: $p->x
    public function __get(string $name): mixed
    {
        return $this->attributes[$name] ?? null;
    }

    // chamado por isset($p->x)
    public function __isset(string $name): bool
    {
        return isset($this->attributes[$name]);
    }

    // método
    public function identity(): string
    {
        // usa atributos que não foram declarados
        return "[$this->firstName,$this->lastName,$this->age]";
    }
}

// teste
// os atributos são criados pelo método mágico [__set]
$p = new Person();
$p->firstName = "Paul";
$p->lastName = "Langevin";
$p->age = 48;
// chamada de um método
print "person=" . $p->identity() . "\n";
// isset
print "isset(\$p->age): " . var_export(isset($p->age), true) . "\n";
print "isset(\$p->address): " . var_export(isset($p->address), true) . "\n";
// fim
exit;

Resultados:

1
2
3
4
> php classes-02.php
person=[Paul,Langevin,48]
isset($p->age): true
isset($p->address): false

Comentários

  • Linhas 6 a 38: definem uma classe chamada [Person]. Uma classe é um modelo usado para criar objetos. Ela é composta de atributos e de funções chamadas métodos;
  • linha 10: o único atributo declarado para a classe é um array privado (veremos em breve o significado da palavra-chave [private]). Esse array armazenará os atributos “não declarados”;
  • linhas 13 a 16: o método mágico [__set] é chamado automaticamente pelo PHP ao escrever em um atributo que não existe (ou que não é acessível). Ele recebe o nome do atributo e o valor a ser atribuído a ele. Aqui, ele armazena esse valor no array [$attributes]. Os métodos cujos nomes começam com dois sublinhados são chamados de métodos mágicos: eles não são chamados explicitamente; é o PHP que os chama;
  • linhas 19 a 22: o método mágico [__get] é chamado ao ler um atributo que não existe. Ele retorna o valor armazenado ou [null]. O operador [??] retorna seu operando à esquerda se ele existir e não for [null]; caso contrário, retorna seu operando à direita;
  • linha 25: o método mágico [__isset] é chamado pela função [isset];
  • Linha 31: o método [identity] usa três atributos que não são declarados na classe. A palavra-chave [$this] designa o objeto ao qual o método é aplicado. Cada chamada a [$this->firstName] dispara uma chamada a [__get];
  • Linha 40: um objeto [$p] do tipo [Person] é criado. A palavra-chave [new] é usada para criar um novo objeto. A operação retorna uma referência ao objeto criado (ou seja, um endereço). Várias notações são possíveis: [new Person()], [new Person], [new person]. O nome da classe não diferencia maiúsculas de minúsculas;
  • linhas 41 a 43: os três atributos exigidos pelo método [identity] são criados no objeto [$p] pelo método [__set];
  • linha 45: o método [identity] da classe [Person] é aplicado ao objeto [$p]. No código do método [identity], [$this] referencia o mesmo objeto que [$p].

Essa técnica tem seus usos (objetos de configuração, encapsulamento de dados lidos de um arquivo), mas não é a maneira padrão de escrever uma classe. Em uma classe comum, declaram-se seus atributos.

5.4. A classe Person com atributos declarados

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

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

class Person
{
    // atributos da classe, públicos e tipados
    public string $firstName;
    public string $lastName;
    public int $age;

    // método
    public function identity(): string
    {
        return "[$this->firstName,$this->lastName,$this->age]";
    }
}

// teste
// os atributos são públicos
$p = new Person();
$p->firstName = "Paul";
$p->lastName = "Langevin";
$p->age = 48;
// chamada de um método
print "person=" . $p->identity() . "\n";
// um atributo tipado só aceita valores do seu tipo
try {
    $p->age = "forty-eight";
} catch (\TypeError $e) {
    print "Error 1: " . $e->getMessage() . "\n";
}
// um atributo tipado não inicializado não pode ser lido
$p2 = new Person();
try {
    print "person=" . $p2->identity() . "\n";
} catch (\Error $e) {
    print "Error 2: " . $e->getMessage() . "\n";
}
// fim
exit;

Resultados:

1
2
3
4
> php classes-03.php
person=[Paul,Langevin,48]
Error 1: Cannot assign string to property Person::$age of type int
Error 2: Typed property Person::$firstName must not be accessed before initialization

Comentários

  • Linhas 9 a 11: os atributos da classe são declarados explicitamente. A palavra-chave [public] significa que eles são acessíveis de fora da classe. No PHP 7, o curso usava a palavra-chave [var], herdada do PHP 4, que é sinônimo de [public] e não é mais usada hoje;
  • Cada atributo é precedido por seu tipo: [string] para nome e sobrenome, [int] para a idade. São atributos tipados, introduzidos no PHP 7.4. Os tipos possíveis são os dos parâmetros de funções: [int], [float], [string], [bool], [array], o nome de uma classe ou interface, um tipo anulável [?string], um tipo união [int|float]...;
  • linha 30: um atributo tipado aceita apenas valores do seu tipo. Qualquer outro valor causa um erro [TypeError] (linha 3 dos resultados);
  • linhas 35 a 37: um atributo tipado sem valor padrão fica no estado “não inicializado” até que lhe seja atribuído um valor. Lê-lo causa um erro (linha 4 dos resultados). Já os atributos sem tipo têm o valor padrão [null]. Esse é um dos motivos para inicializar todos os atributos de um objeto assim que ele é criado: é o papel do construtor.

5.5. A classe Person com um construtor

Os exemplos anteriores mostraram classes exóticas, como as que existiam no PHP 4. Não é recomendável seguir esses exemplos. Apresentamos agora uma classe [Person] [classes-04.php] que segue as boas práticas padrão, encontradas em todas as linguagens orientadas a objetos (Java, C# etc.):

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

class Person
{
    // atributos da classe
    private string $firstName;
    private string $lastName;
    private int $age;

    // getters e setters
    public function getFirstName(): string
    {
        return $this->firstName;
    }

    public function getLastName(): string
    {
        return $this->lastName;
    }

    public function getAge(): int
    {
        return $this->age;
    }

    public function setFirstName(string $firstName): void
    {
        $this->firstName = $firstName;
    }

    public function setLastName(string $lastName): void
    {
        $this->lastName = $lastName;
    }

    public function setAge(int $age): void
    {
        $this->age = $age;
    }

    // construtor
    public function __construct(string $firstName, string $lastName, int $age)
    {
        // passamos pelos setters
        $this->setFirstName($firstName);
        $this->setLastName($lastName);
        $this->setAge($age);
    }

    // método toString
    public function __toString(): string
    {
        return "[$this->firstName,$this->lastName,$this->age]";
    }
}

// teste
// criação de um objeto Person
$p = new Person("Paul", "Langevin", 48);
// identidade desta pessoa
print "person=$p\n";
// alteramos a idade
$p->setAge(14);
// identidade da pessoa
print "person=$p\n";
// uma classe que possui um método [__toString] implementa a interface [Stringable]
print "Stringable: " . var_export($p instanceof \Stringable, true) . "\n";
// um atributo privado não é acessível de fora da classe
try {
    print $p->lastName;
} catch (\Error $e) {
    print "Error: " . $e->getMessage() . "\n";
}
// fim
exit;

Resultados:

1
2
3
4
5
> php classes-04.php
person=[Paul,Langevin,48]
person=[Paul,Langevin,14]
Stringable: true
Error: Cannot access private property Person::$lastName

Comentários

  • Linha 4: especificamos que os tipos declarados dos parâmetros das funções devem ser estritamente respeitados. Sem essa declaração, o PHP tentaria converter um valor do tipo errado (por exemplo, a string ["48"] em um inteiro [48]);
  • Linhas 6 a 60: a classe [Person];
  • Linhas 9 a 11: os atributos privados da classe ([private]). Esses atributos só são visíveis dentro da classe. Outras palavras-chave que podem ser usadas são:
    • [public]: torna o atributo público, visível fora da classe;
    • [protected]: torna o atributo protegido, visível dentro da classe e de suas classes derivadas;
  • Como os atributos são privados, não podem ser acessados de fora da classe. Portanto, não podemos escrever [$p->lastName = "Landru"]: estamos fora da classe [Person], e o atributo [lastName] é privado. As linhas 72 a 74 verificam isso: tentar ler [$p->lastName] resulta em um erro (linha 5 dos resultados). Para inicializar os atributos privados do objeto [$p], há duas maneiras:
    • usar os métodos públicos [set] e [get] (os nomes desses métodos podem ser quaisquer) nas linhas 14 a 39. Nesse caso, escrevemos: [$p->setLastName("Landru")];
    • usar o construtor das linhas 45 a 50. Escreveríamos então: [$p = new Person("Michel", "Landru", 44)]. Essa sintaxe chama automaticamente o método da classe [Person] chamado [__construct];
  • linha 64: essa linha exibe a pessoa [$p] como uma string. Para isso, é usado o método da classe [Person] chamado [__toString] (linha 54);
  • linha 70: a partir do PHP 8.0, toda classe que define um método chamado [__toString] implementa automaticamente a interface predefinida [Stringable] (trataremos de interfaces no próximo capítulo). O operador [instanceof] verifica se um objeto é de um determinado tipo. Uma função pode, assim, declarar um parâmetro do tipo [string|Stringable]: ele então aceita uma string ou qualquer objeto que possa ser convertido em string;
  • todos os métodos da classe foram prefixados com a palavra-chave [public], que indica que o método é visível fora da classe. As outras palavras-chave que podem ser usadas são, como nos atributos e com o mesmo significado, [private] e [protected]. Sem uma palavra-chave de visibilidade explícita, o método é implicitamente [public]. As diretrizes de estilo PSR-12, que os scripts deste curso seguem, exigem que a visibilidade seja sempre especificada explicitamente.

5.6. Promoção de parâmetros do construtor

A classe anterior é prolixa: cada atributo é nomeado quatro vezes (declaração, parâmetro do construtor, atribuição no construtor, getter). Desde o PHP 8.0, a promoção de parâmetros do construtor permite declarar e inicializar um atributo diretamente na lista de parâmetros do construtor. O script [classes-22.php] demonstra isso:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

class Person
{
    // construtor com promoção de parâmetros:
    // cada parâmetro precedido por uma visibilidade torna-se um atributo da classe
    public function __construct(
        private string $firstName,
        private string $lastName,
        private int $age = 0,
    ) {
        // nada mais a fazer: os atributos já estão inicializados
    }

    // getters
    public function getFirstName(): string
    {
        return $this->firstName;
    }

    public function getLastName(): string
    {
        return $this->lastName;
    }

    public function getAge(): int
    {
        return $this->age;
    }

    // setter
    public function setAge(int $age): void
    {
        $this->age = $age;
    }

    // método toString
    public function __toString(): string
    {
        return "[$this->firstName,$this->lastName,$this->age]";
    }
}

// teste
// chamada clássica: os argumentos são passados na ordem dos parâmetros
$p1 = new Person("Paul", "Langevin", 48);
print "p1=$p1\n";
// argumentos nomeados: a ordem não importa mais
$p2 = new Person(lastName: "Lefur", age: 70, firstName: "Sylvie");
print "p2=$p2\n";
// o parâmetro [age] tem um valor padrão: pode ser omitido
$p3 = new Person(firstName: "Steve", lastName: "Boer");
print "p3=$p3\n";
// os atributos promovidos são atributos de verdade
var_dump($p3);
// fim
exit;

Resultados:

> php classes-22.php
p1=[Paul,Langevin,48]
p2=[Sylvie,Lefur,70]
p3=[Steve,Boer,0]
object(Person)#3 (3) {
  ["firstName":"Person":private]=>
  string(5) "Steve"
  ["lastName":"Person":private]=>
  string(4) "Boer"
  ["age":"Person":private]=>
  int(0)
}

Comentários

  • Linhas 10 a 14: cada parâmetro do construtor precedido por uma palavra-chave de visibilidade ([private], [protected], [public]) é “promovido”: o PHP declara um atributo com o mesmo nome e o mesmo tipo e atribui a ele o valor do parâmetro. Essas três linhas substituem as declarações e atribuições de atributos da classe anterior;
  • linha 13: um parâmetro promovido pode ter um valor padrão. A vírgula após o último parâmetro é permitida desde o PHP 8.0; ela facilita a adição de um parâmetro posteriormente;
  • linha 15: o corpo do construtor pode conter código (como validações). Aqui, não há nada a fazer;
  • linha 52: os argumentos nomeados (PHP 8.0) permitem passar argumentos em qualquer ordem, referindo-se a eles pelo nome do parâmetro. Isso torna o código mais legível, sobretudo quando uma função tem muitos parâmetros;
  • linha 55: o parâmetro [age] é omitido; ele assume seu valor padrão;
  • linha 58: a função [var_dump] mostra que os atributos promovidos são verdadeiros atributos privados da classe (linhas 5 a 12 dos resultados).

5.7. A classe Person com verificações de validade no construtor

O construtor de uma classe é o lugar apropriado para verificar se os valores de inicialização do objeto estão corretos. No entanto, um objeto também pode ser inicializado por meio de seus métodos [set] ou equivalentes. Para evitar duplicar as mesmas verificações em dois lugares diferentes, elas podem ser colocadas nos métodos [set]. Se um valor de inicialização do objeto se revelar incorreto, uma exceção será lançada. Eis um exemplo.

Primeiro, mova a definição da classe [Person] para seu próprio arquivo, [Person.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// namespace
namespace Examples;

// classe Person
class Person
{
    // atributos da classe
    private string $firstName;
    private string $lastName;
    private int $age;

    // getters e setters
    public function getFirstName(): string
    {
        return $this->firstName;
    }

    public function getLastName(): string
    {
        return $this->lastName;
    }

    public function getAge(): int
    {
        return $this->age;
    }

    public function setFirstName(string $firstName): void
    {
        // o nome não pode ser vazio
        $firstName = trim($firstName);
        if ($firstName === "") {
            throw new \Exception("The first name must not be empty");
        }
        $this->firstName = $firstName;
    }

    public function setLastName(string $lastName): void
    {
        // o sobrenome não pode ser vazio
        $lastName = trim($lastName);
        if ($lastName === "") {
            throw new \Exception("The last name must not be empty");
        }
        $this->lastName = $lastName;
    }

    public function setAge(int $age): void
    {
        // a idade deve ser válida
        if ($age < 0) {
            throw new \Exception("The age must be a positive or zero integer");
        }
        $this->age = $age;
    }

    // construtor
    public function __construct(string $firstName, string $lastName, int $age)
    {
        // passamos pelos setters
        $this->setFirstName($firstName);
        $this->setLastName($lastName);
        $this->setAge($age);
    }

    // método que atua como um segundo construtor
    public function initWithPerson(Person $p): void
    {
        // inicializa o objeto atual com uma pessoa $p
        $this->__construct($p->firstName, $p->lastName, $p->age);
    }

    // método de fábrica estático (construtor nomeado)
    public static function fromPerson(Person $p): self
    {
        // cria uma nova pessoa, cópia da pessoa $p
        return new self($p->firstName, $p->lastName, $p->age);
    }

    // método toString
    public function __toString(): string
    {
        return "[$this->firstName,$this->lastName,$this->age]";
    }
}

Comentários

  • Linha 4: especifica que os tipos dos parâmetros das funções devem ser respeitados conforme declarados;
  • Linha 7: define um namespace. O nome completo (ou qualificado) da classe [Person] é, portanto, [\Examples\Person]. Observe o caractere [\] no início do nome qualificado: isso resulta em um nome qualificado absoluto. Se esse caractere estiver ausente, o nome é um nome qualificado relativo (relativo ao namespace atual). Assim, se duas classes, A e B, pertencem ao mesmo namespace E, no código da classe A, a classe B pode ser acessada com a notação relativa B. Se a classe A faz parte do namespace E1 e a classe B faz parte do namespace E2, então, no código da classe A, a classe B pode ser acessada com a notação absoluta [\E2\B]. Definir uma classe dentro de um namespace não é obrigatório, mas é considerado uma boa prática: duas bibliotecas podem então definir, cada uma, uma classe chamada [Person] sem conflito;
  • os namespaces costumam corresponder à estrutura de diretórios dos arquivos. Assim, a classe A do namespace E1 costuma ficar em um arquivo chamado [E1/A.php]. Essa é a convenção PSR-4 usada pela ferramenta [Composer] para carregar classes automaticamente, que usaremos nos capítulos seguintes. A extensão [PHP Intelephense] do [VS Code] não exige isso. Não confunda a árvore de arquivos com um namespace: o nome totalmente qualificado de uma classe usa um namespace e nada tem a ver com a árvore de arquivos do arquivo PHP que contém a classe. Aqui, a classe [\Examples\Person] está no arquivo [scripts-console/classes/Person.php];
  • linhas 13 a 15: os três atributos privados da classe;
  • linhas 33 a 41: inicialização do atributo [firstName] e verificação do valor de inicialização;
  • linha 36: a função [trim($string)] remove os espaços no início e no fim de [$string]. Assim, [trim(" abcd ")] é a string ["abcd"], e [trim(" ")] é a string vazia.;
  • linha 37: se o nome estiver vazio, uma exceção é lançada (linha 38); caso contrário, o nome é armazenado (linha 40). Para lançar uma exceção, a classe predefinida [Exception] é usada aqui. Aqui, somos obrigados a usar seu nome absoluto, [\Exception]. Se usarmos seu nome relativo, [Exception], essa classe será procurada no namespace atual, isto é, no namespace [Examples] da classe [Person]. Assim, o interpretador PHP procurará uma classe com o nome absoluto [\Examples\Exception], que não existe;
  • linhas 63–69: o construtor usa os métodos [set] para inicializar os atributos: as validações são escritas uma única vez;
  • Os métodos das linhas 72 e 79 são descritos no parágrafo seguinte.

A classe [Person] é usada pelo seguinte script, [classes-05.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// inclusão da definição da classe Person
require_once __DIR__ . "/Person.php";
// para demonstração
print __DIR__ . "/Person.php\n";

// nome qualificado da classe Person
use Examples\Person;

// teste
// criação de um objeto Person
$p = new Person("Paul", "Langevin", 48);
// identidade desta pessoa
print "Example1, person=$p\n";
// criação de um objeto Person inválido
try {
    $p = new Person("xx", "yy", "zz");
} catch (\Exception $e1) {
    print "Example2, error: " . $e1->getMessage() . "\n";
} catch (\TypeError $e2) {
    print "Example2, error: " . $e2->getMessage() . "\n";
}
// criação de um objeto Person inválido
try {
    $p = new Person("", "yy", 10);
} catch (\Exception $e1) {
    print "Example3, error: " . $e1->getMessage() . "\n";
} catch (\TypeError $e2) {
    print "Example3, error: " . $e2->getMessage() . "\n";
}

// fim
exit;

Resultados:

1
2
3
4
5
> php classes-05.php
.../php8-oct-2026/scripts-console/classes/Person.php
Example1, person=[Paul,Langevin,48]
Example2, error: Examples\Person::__construct(): Argument #3 ($age) must be of type int, string given, called in .../php8-oct-2026/scripts-console/classes/classes-05.php on line 21
Example3, error: The first name must not be empty

Comentários

  • Linha 7: O script usará a classe [Person]. É preciso, portanto, informar ao interpretador PHP onde encontrar a definição dessa classe. Esse é o papel das instruções [include file] e [require file]. A diferença entre as duas instruções é a seguinte: se a instrução [include file] encontrar erros ao carregar [file], um erro de nível [E_WARNING] é emitido, mas a execução continua, ao passo que [require], na mesma situação, gera um erro fatal e interrompe a execução do script. Cada uma dessas duas instruções tem uma variante: [include_once] e [require_once]. Essas duas variantes permitem tratar os casos em que um mesmo arquivo é incluído várias vezes. Considere, por exemplo, um projeto composto por vários scripts PHP, alguns dos quais referenciam a classe [Person]. A execução desses scripts faria com que o arquivo [Person.php] fosse incluído várias vezes, resultando em um erro, pois uma classe não pode ser definida duas vezes. A solução é usar as variantes [_once], que garantem que o arquivo seja incluído apenas uma vez no script global do projeto;
  • A constante [__DIR__] é uma constante do PHP que designa o nome completo da pasta que contém o script em que a constante [__DIR__] aparece. A linha 9 a exibe (linha 2 dos resultados). Na máquina do leitor, o resultado será algo como [C:\laragon\www\php8-oct-2026\scripts-console\classes/Person.php]. Em um caminho de arquivo, no Windows, é possível usar [/] ou [\] indistintamente. Usar [__DIR__] torna o script independente da pasta atual no momento da execução;
  • Linha 12: O script [classes-05.php] não tem namespace. Quando o código usa o nome relativo [Person], ele é procurado no namespace raiz [\] e, portanto, não será encontrado. Há duas soluções para esse problema:
    • usar o nome completo da classe [\Examples\Person];
    • usar a instrução [use], que especifica que, no código a seguir, o nome [Person] se refere à classe [\Examples\Person]. Em uma instrução [use], o nome é sempre absoluto: o [\] inicial é desnecessário (essa é a notação recomendada). A instrução equivale a [use Examples\Person as Person;], que especifica que o alias [Person] se refere à classe [\Examples\Person];
  • a instrução [use] informa ao interpretador que a classe [Person] é, na verdade, a classe [\Examples\Person]. Isso posto, onde o interpretador encontrará o código dessa classe? A instrução [require_once] informa isso. As duas instruções têm papéis muito diferentes: [use] trabalha com nomes, [require_once] carrega um arquivo;
  • linha 16: um objeto [Person] é criado. O método [__construct] da classe [Person] será executado implicitamente aqui;
  • linha 18: exibe a pessoa [$p]. Para ser exibido, o valor da variável [$p] deve ser convertido em string. Implicitamente, o método [Person::__toString] é então executado. Esse método deve, portanto, retornar uma string;
  • vimos que o construtor da classe [Person] pode lançar uma exceção [\Exception]. Essa exceção deve, portanto, ser tratada. Consequentemente, a criação de uma pessoa deve sempre estar dentro de uma estrutura ***[try / catch] , como mostrado nas linhas 20–34. Aqui, provocamos um erro intencionalmente, passando uma idade que não é um inteiro. Nesse caso específico, o erro é lançado pelo interpretador PHP e não pelo código da classe [Person]. Isso porque a assinatura do método [Person::__construct]* é [__construct(string $firstName, string $lastName, int $age)]. Portanto, o parâmetro [age] passado ao construtor deve ser do tipo inteiro. Se não for, o interpretador PHP lança um erro do tipo [TypeError]. Além disso, os métodos [set] da classe [Person]* lançam uma exceção do tipo [\Exception]. Como o construtor que os chama não tem uma estrutura [try / catch], a exceção é propagada um nível acima, para o código que chamou o construtor, isto é, o código do script [classes-05.php]. Por fim, o script [classes-05.php]* pode receber dois tipos de erros: [\Exception] ou [\TypeError]. Por essa razão, a estrutura [try] tem duas cláusulas [catch] para tratar separadamente os dois tipos de erros. Quando o desenvolvedor tem certeza de que determinados erros não podem ocorrer, ele não usa as cláusulas [catch]** correspondentes. Aqui, elas são usadas sistematicamente apenas para fins de demonstração;
  • Linha 22: É possível escrever [Exception] ou [\Exception]. A primeira versão usa o nome relativo da classe, relativo ao namespace do script. Como o script não tem namespace, seu namespace é a raiz dos namespaces: [\]. Portanto, escrever [Exception] aqui equivale a escrever [\Exception]. É preferível usar os nomes absolutos das classes predefinidas do PHP em um script que não tem namespace próprio. Assim, se você decidir atribuir um namespace a esse script, usar os nomes absolutos das classes continua válido, ao passo que, no outro caso, mudar o namespace causará erros com os nomes relativos das classes;
  • Linha 23: Quando ocorre uma exceção, o método [Exception::getMessage] recupera a mensagem de erro da exceção. O mesmo vale para um erro do tipo [TypeError]. No método [Person::setFirstName], foi escrito [throw new \Exception("The first name must not be empty")]. Essa é a mensagem recuperada pelo método [getMessage] no exemplo 3 (linha 5 dos resultados);
  • linha 4 dos resultados: a mensagem de erro de [TypeError]. A partir do PHP 8.0, ela identifica o parâmetro problemático por seu número e nome: “Argument #3 ($age) must be of type int, string given.” As mensagens de erro do PHP 8 são mais específicas que as do PHP 7.

5.8. Adicionando um método que atua como segundo construtor

Em PHP, não é possível ter vários construtores com parâmetros diferentes que permitiriam construir um objeto de várias maneiras. Por isso, podem-se usar métodos que atuam como construtores. A classe [Person] tem dois métodos desse tipo:

    public function initWithPerson(Person $p): void
    {
        // inicializa o objeto atual com uma pessoa $p
        $this->__construct($p->firstName, $p->lastName, $p->age);
    }

    // método de fábrica estático (construtor nomeado)
    public static function fromPerson(Person $p): self
    {
        // cria uma nova pessoa, cópia da pessoa $p
        return new self($p->firstName, $p->lastName, $p->age);
    }

Comentários

  • Linhas 72–76: O método [initWithPerson] permite atribuir ao objeto atual os valores dos atributos de outro objeto [Person]. Aqui, ele chama o construtor [__construct], mas isso não é obrigatório. Ele poderia inicializar sozinho os atributos da classe [Person]. Observe que um método da classe [Person] tem acesso aos atributos privados de todos os objetos [Person], e não apenas aos de [$this];
  • linhas 79–83: O método [fromPerson] é outra maneira de fazer isso, mais comum hoje em dia. É um método estático (palavra-chave [static]): ele não se aplica a um objeto, mas à classe. Ele é chamado com a notação [Person::fromPerson($p)]. Ele cria um novo objeto com [new self(...)]: a palavra-chave [self] designa a classe em que o código está escrito, neste caso [Person]. O tipo de retorno [self] indica que o método retorna um objeto dessa classe. Esse método é chamado de construtor nomeado ou método de fábrica (factory method). Voltaremos aos métodos estáticos mais adiante.

A nova classe [Person] é usada pelo seguinte script, [classes-06.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// inclusão da definição da classe Person
require_once __DIR__ . "/Person.php";
// declaração do nome qualificado da classe Person
use Examples\Person;

// teste
// criação de um objeto Person
try {
    $p = new Person("Paul", "Langevin", 48);
} catch (\Exception $e) {
    print "error: " . $e->getMessage() . "\n";
    exit;
}
// identidade desta pessoa
print "person=$p\n";
// criação de uma segunda pessoa
try {
    $p2 = new Person("Laure", "Adeline", 67);
} catch (\Exception $e) {
    print "error: " . $e->getMessage() . "\n";
    exit;
}
// inicialização da primeira com os valores da segunda
try {
    $p->initWithPerson($p2);
} catch (\Exception $e) {
    print "error: " . $e->getMessage() . "\n";
    exit;
}
// verificação
print "person=$p\n";

// criação de uma terceira pessoa com o construtor nomeado
$p3 = Person::fromPerson($p2);
print "person=$p3\n";
// $p3 e $p2 são dois objetos diferentes que têm os mesmos valores
print "same object: " . var_export($p3 === $p2, true) . "\n";
print "same values: " . var_export($p3 == $p2, true) . "\n";
// fim
exit;

Resultados:

1
2
3
4
5
6
> php classes-06.php
person=[Paul,Langevin,48]
person=[Laure,Adeline,67]
person=[Laure,Adeline,67]
same object: false
same values: true

Comentários

  • Linha 17, linha 26, linha 33: É comum que, depois de uma exceção, seja preciso interromper a execução de um script de console se o erro encontrado for irrecuperável. Esse não é o caso de um script web: não se interrompe a execução do script, mas exibe-se uma página de erro. Se você estiver dentro de uma função, a instrução [exit] não será usada; em vez dela, será usada [return]: a execução do script não é interrompida ([exit]), mas a função é encerrada ([return]) depois que um erro foi registrado;
  • linha 39: chamada ao construtor nomeado;
  • linha 42: o operador [===] aplicado a dois objetos resulta em verdadeiro se eles forem o mesmo objeto (mesmo endereço). [$p3] e [$p2] são dois objetos distintos (linha 5 dos resultados);
  • linha 43: o operador [==], quando aplicado a dois objetos da mesma classe, resulta em verdadeiro se seus atributos tiverem os mesmos valores (linha 6 dos resultados). A função [var_export] retorna uma representação PHP de seu parâmetro, neste caso [true] ou [false].

5.9. Verificações de validade com property hooks (PHP 8.4)

A classe anterior, [Person], protege seus atributos tornando-os privados e exigindo que o código externo use os métodos [get] e [set] . O PHP 8.4 oferece outra solução: os property hooks. Um atributo público pode ser acompanhado de um hook [set] — o código executado a cada escrita do atributo — e de um hook [get] — o código executado a cada leitura do atributo. Isso preserva a simplicidade de escrever [$p->age = 49] e, ao mesmo tempo, mantém o controle sobre os valores. É o que demonstra o script [classes-23.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

class Person
{
    // atributo público com um hook [set]: a validação é feita a cada escrita
    public string $firstName {
        set(string $value) {
            $value = trim($value);
            if ($value === "") {
                throw new \InvalidArgumentException("The first name must not be empty");
            }
            $this->firstName = $value;
        }
    }

    public string $lastName {
        set(string $value) {
            $value = trim($value);
            if ($value === "") {
                throw new \InvalidArgumentException("The last name must not be empty");
            }
            $this->lastName = $value;
        }
    }

    // sem um parâmetro explícito, o valor recebido chama-se [$value]
    public int $age {
        set {
            if ($value < 0) {
                throw new \InvalidArgumentException("The age must be a positive or zero integer");
            }
            $this->age = $value;
        }
    }

    // atributo virtual: possui apenas um hook [get] e não ocupa espaço no objeto
    public string $identity {
        get => "[$this->firstName,$this->lastName,$this->age]";
    }

    // construtor: as atribuições passam pelos hooks [set]
    public function __construct(string $firstName, string $lastName, int $age)
    {
        $this->firstName = $firstName;
        $this->lastName = $lastName;
        $this->age = $age;
    }
}

// teste
$p = new Person(" Paul ", "Langevin", 48);
print "person=$p->identity\n";
// os atributos são públicos: são lidos e escritos diretamente
$p->age = 49;
print "age=$p->age\n";
// mas a escrita sempre passa pelo hook [set]
foreach (["firstName" => "  ", "age" => -4] as $attribute => $value) {
    try {
        $p->$attribute = $value;
    } catch (\InvalidArgumentException $e) {
        print "Error: " . $e->getMessage() . "\n";
    }
}
// um atributo virtual sem hook [set] não pode ser escrito
try {
    $p->identity = "?";
} catch (\Error $e) {
    print "Error: " . $e->getMessage() . "\n";
}
// o objeto permaneceu válido
print "person=$p->identity\n";
var_dump($p);

Resultados:

> php classes-23.php
person=[Paul,Langevin,48]
age=49
Error: The first name must not be empty
Error: The age must be a positive or zero integer
Error: Property Person::$identity is read-only
person=[Paul,Langevin,49]
object(Person)#1 (3) {
  ["firstName"]=>
  string(4) "Paul"
  ["lastName"]=>
  string(8) "Langevin"
  ["age"]=>
  int(49)
}

Comentários

  • linhas 9–17: O atributo público [firstName] é seguido de um bloco delimitado por chaves que contém seus hooks. Aqui, há apenas um hook, [set];
  • linha 10: O hook [set] recebe o valor a ser atribuído ao atributo. Ele o normaliza com [trim], verifica-o e lança uma exceção se estiver incorreto;
  • linha 15: Dentro de seus hooks, [$this->firstName] designa o local de memória do atributo: o valor é armazenado ali. Em todos os outros lugares, [$this->firstName] passa pelos hooks;
  • linha 13: uma exceção do tipo [\InvalidArgumentException] é lançada; essa é uma classe predefinida derivada de [\Exception] e mais específica que ela, que sinaliza um argumento inválido. Trataremos das exceções predefinidas do PHP no capítulo sobre exceções;
  • linha 31: quando o hook [set] não declara um parâmetro, o valor recebido fica disponível na variável implícita [$value], e seu tipo é o do atributo;
  • Linhas 40–42: Um atributo que tem apenas um hook, [get], e nunca referencia seu próprio local de memória é um atributo virtual: ele é calculado a cada leitura e não ocupa espaço no objeto. A notação [get => expression] é uma abreviação de um hook [get] que resulta no valor da expressão;
  • linhas 45–50: o construtor atribui os atributos; essas atribuições são feitas por meio dos hooks [set]. A validação é, portanto, realizada tanto durante a construção quanto em qualquer modificação posterior, sem usar os métodos [set];
  • linha 54: o nome [" Paul "] é limpo pelo hook [set];
  • linha 57: o atributo [age] é modificado diretamente, mas por meio de seu hook [set];
  • Linhas 60–66: Tenta-se atribuir valores inválidos. A notação [$p->$attribute] usa o conteúdo da variável [$attribute] como nome do atributo. Os hooks [set] lançam suas exceções (linhas 4–5 dos resultados);
  • linha 69: o atributo virtual [identity] não tem um hook [set]: ele é somente leitura (linha 6 dos resultados);
  • linha 75: o objeto manteve valores válidos. [var_dump] mostra apenas três atributos: o atributo virtual [identity] não existe na memória.

Os property hooks existem há muito tempo em outras linguagens (C#, Kotlin, Swift). Eles eliminam a necessidade de escrever getters e setters “por precaução”: você começa com um atributo público simples e adiciona um hook quando a validação se torna necessária, sem alterar o código que usa a classe.

5.10. Visibilidade assimétrica (PHP 8.4)

Muitas vezes, uma propriedade precisa ser legível por todos, mas modificável apenas pela própria classe. No passado, escreveríamos uma propriedade privada e um getter público. O PHP 8.4 permite definir níveis de visibilidade diferentes para a leitura e a escrita de uma propriedade: isso se chama visibilidade assimétrica. O script [classes-24.php] demonstra isso usando uma conta bancária:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

class BankAccount
{
    // visibilidade assimétrica: leitura pública, escrita privada
    public private(set) float $balance = 0.0;

    // a promoção de parâmetros também aceita visibilidade assimétrica
    public function __construct(public private(set) string $holder)
    {
    }

    // somente os métodos da classe podem modificar o saldo
    public function deposit(float $amount): void
    {
        if ($amount <= 0) {
            throw new \InvalidArgumentException("The amount must be positive");
        }
        $this->balance += $amount;
    }

    public function withdraw(float $amount): void
    {
        if ($amount <= 0 || $amount > $this->balance) {
            throw new \InvalidArgumentException("Withdrawal of $amount impossible");
        }
        $this->balance -= $amount;
    }
}

// teste
$account = new BankAccount("Paul Langevin");
$account->deposit(100);
$account->withdraw(30);
// leitura direta dos atributos, sem getter
print "{$account->holder}: {$account->balance} euros\n";
// a escrita de fora da classe é proibida
try {
    $account->balance = 1_000_000;
} catch (\Error $e) {
    print "Error: " . $e->getMessage() . "\n";
}
// a classe mantém o controle da validade do saldo
try {
    $account->withdraw(500);
} catch (\InvalidArgumentException $e) {
    print "Error: " . $e->getMessage() . "\n";
}
print "{$account->holder}: {$account->balance} euros\n";

Resultados:

1
2
3
4
5
> php classes-24.php
Paul Langevin: 70 euros
Error: Cannot modify private(set) property BankAccount::$balance from global scope
Error: Withdrawal of 500 impossible
Paul Langevin: 70 euros

Comentários

  • Linha 9: O atributo [balance] é público para leitura ([public]) e privado para escrita ([private(set)]). O código externo pode ler [$account->balance], mas apenas os métodos da classe podem modificá-lo. Também é possível escrever [protected(set)]: nesse caso, as classes derivadas podem modificar o atributo;
  • linha 12: a visibilidade assimétrica também é possível para um parâmetro promovido;
  • linhas 17–25: Os métodos [deposit] e [withdraw] são as únicas maneiras de modificar o saldo. Eles verificam a validade das operações;
  • linha 39: os atributos são lidos diretamente, sem getters. A notação [{$expression}] dentro de uma string entre aspas permite inserir uma expressão mais complexa que uma simples variável;
  • linha 42: Escrever no saldo de fora da classe causa um erro (linha 3 dos resultados). O caractere [_] pode ser usado como separador de milhares em um número literal (PHP 7.4);
  • Linha 48: O saque é rejeitado pelo método [withdraw] (linha 4 dos resultados). O saldo não mudou (linha 5).

5.11. Atributos e classes somente leitura ([readonly])

Um objeto cujo estado não pode mudar depois de criado é chamado de imutável. Objetos imutáveis simplificam muito a programação: eles podem ser compartilhados entre várias partes do código sem o receio de que alguma delas os modifique. O PHP 8.1 introduziu os atributos somente leitura (palavra-chave [readonly]): esse atributo só pode ser inicializado uma vez, de dentro da classe. O PHP 8.2 introduziu as classes somente leitura: todos os seus atributos passam a ser [readonly]. O script [classes-25.php] apresenta uma classe imutável [Person]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// classe somente leitura: todos os seus atributos são [readonly]
final readonly class Person
{
    public function __construct(
        public string $firstName,
        public string $lastName,
        public int $age,
    ) {
        if ($age < 0) {
            throw new \InvalidArgumentException("The age must be a positive or zero integer");
        }
    }

    // "modificar" um objeto imutável = criar uma cópia modificada
    public function withAge(int $age): static
    {
        // clone com modificação de atributos (PHP 8.5)
        return clone($this, ["age" => $age]);
    }

    public function __toString(): string
    {
        return "[$this->firstName,$this->lastName,$this->age]";
    }
}

// teste
$p1 = new Person("Paul", "Langevin", 48);
print "p1=$p1\n";
// um atributo [readonly] é inicializado uma vez por todas
try {
    $p1->age = 49;
} catch (\Error $e) {
    print "Error 1: " . $e->getMessage() . "\n";
}
// também não é possível adicionar atributos a uma classe [readonly]
try {
    $p1->address = "Paris";
} catch (\Error $e) {
    print "Error 2: " . $e->getMessage() . "\n";
}
// uma nova pessoa, cópia da primeira com outra idade
$p2 = $p1->withAge(49);
print "p1=$p1\n";
print "p2=$p2\n";

Resultados:

1
2
3
4
5
6
> php classes-25.php
p1=[Paul,Langevin,48]
Error 1: Cannot modify readonly property Person::$age
Error 2: Cannot create dynamic property Person::$address
p1=[Paul,Langevin,48]
p2=[Paul,Langevin,49]

Comentários

  • linha 7: a classe é declarada como [readonly]: seus três atributos promovidos são somente leitura. A palavra-chave [final], que examinaremos em breve, impede que a classe seja estendida por subclasses;
  • Linhas 10–12: Os atributos são públicos: podem ser lidos diretamente, sem getters. Não podem ser modificados: um getter não teria utilidade;
  • linha 14: O construtor verifica a validade da idade. Um objeto imutável deve ser válido na construção, já que nunca mudará;
  • linhas 20–24: “Modificar” um objeto imutável consiste em criar uma cópia modificada desse objeto. É o que faz o método [withAge]. Seu tipo de retorno, [static] (PHP 8.0), significa “um objeto da classe sobre a qual o método foi chamado”. A diferença em relação a [self] só aparece com classes derivadas: se uma classe derivada herda o método, o tipo [static] designa a classe derivada;
  • Linha 23: O operador [clone] cria uma cópia do objeto [$this]. A partir do PHP 8.5, [clone] pode ser usado como função e aceitar, como segundo parâmetro, um array de atributos a serem modificados na cópia (clone with). Antes do PHP 8.5, era preciso usar o método "mágico" [__clone] ou reconstruir o objeto com [new];
  • linha 37: Modificar um atributo [readonly] causa um erro (linha 3 dos resultados);
  • Linha 43: Uma classe [readonly] também não aceita atributos dinâmicos: isso é um erro, e não um simples aviso de descontinuação (linha 4 dos resultados);
  • linha 48: [$p2] é uma nova pessoa; [$p1] não mudou (linhas 5–6 dos resultados).

Nos próximos capítulos, usaremos com frequência classes [readonly] para representar dados (os dados fiscais do governo, os resultados de um cálculo de imposto etc.).

5.12. Um array de objetos [Person]

O exemplo a seguir, [classes-07.php], mostra que arrays de objetos são possíveis:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

require_once __DIR__ . "/Person.php";
use Examples\Person;

// teste
// criação de um array de objetos Person
// para tornar o código mais fácil de entender, a possível exceção não é tratada
$group = [new Person("Paul", "Langevin", 48), new Person("Sylvie", "Lefur", 70)];

// identidade dessas pessoas
for ($i = 0; $i < count($group); $i++) {
    print "group[$i]=$group[$i]\n";
}

// fim
exit;

Resultados:

1
2
3
> php classes-07.php
group[0]=[Paul,Langevin,48]
group[1]=[Sylvie,Lefur,70]

Comentários

  • linha 12: criação de um array de 2 pessoas;
  • linha 15: percurso do array;
  • Linha 16: [$group[$i]] é um objeto do tipo [Person]. O método [Person::__toString] é usado para exibi-lo.

5.13. Criando uma classe derivada da classe Person

Crie a seguinte classe, [Teacher], em um arquivo chamado [Teacher.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// namespace
namespace Examples;

// uma classe derivada de Person
class Teacher extends Person
{
    // atributo: disciplina lecionada
    private string $subject;

    // getter e setter
    public function getSubject(): string
    {
        return $this->subject;
    }

    public function setSubject(string $subject): void
    {
        $this->subject = $subject;
    }

    // construtor
    public function __construct(string $firstName, string $lastName, int $age, string $subject)
    {
        // atributos do pai
        parent::__construct($firstName, $lastName, $age);
        // outros atributos
        $this->setSubject($subject);
    }

    // redefinição do método __toString da classe pai
    #[\Override]
    public function __toString(): string
    {
        return "[" . parent::__toString() . ",$this->subject]";
    }
}

Comentários

  • linha 7: A classe [Teacher] também pertence ao namespace [Examples];
  • Linha 10: A classe [Teacher] é derivada ([extends]) da classe [Person]. A classe derivada [Teacher] herda os atributos e métodos de sua classe pai;
  • Linha 13: A classe [Teacher] adiciona um novo atributo, [subject], que é exclusivo dela;
  • linha 27: o construtor da classe [Teacher] recebe 4 parâmetros:
    • 3 para inicializar sua classe pai (nome, sobrenome, idade), linha 30;
    • 1 para sua própria inicialização (disciplina), linha 32;
  • linha 30: A classe derivada tem acesso aos métodos e construtores de sua classe pai por meio da palavra-chave [parent::]. Aqui, os parâmetros (nome, sobrenome, idade) são passados ao construtor da classe pai;
  • linha 36: [#[\Override]] é um atributo do PHP (PHP 8.3). Um atributo, escrito como [#[] and []], é uma informação associada a uma classe, a um método, a um parâmetro etc., que o PHP ou outras ferramentas podem usar. Esse atributo declara que o método seguinte sobrescreve um método da classe pai. Se não for o caso (por exemplo, um erro de digitação no nome do método ou um método que foi removido da classe pai), o PHP relata um erro fatal. Veremos um exemplo disso um pouco mais adiante;
  • linhas 37–40: O método [__toString] da classe derivada usa o método [__toString] da classe pai.

A classe [Teacher] é usada pelo seguinte script, [classes-08.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// inclusão da definição das duas classes
require_once __DIR__ . "/Person.php";
require_once __DIR__ . "/Teacher.php";
// declaração das duas classes usadas
use Examples\Person;
use Examples\Teacher;

// teste
// criação de um array de objetos Person e de objetos derivados
// para simplificar o exemplo, as exceções não são tratadas
$group = [new Teacher("Paul", "Langevin", 48, "English"), new Person("Sylvie", "Lefur", 70)];

// identidade dessas pessoas
for ($i = 0; $i < count($group); $i++) {
    print "group[$i]=$group[$i]\n";
}
// fim
exit;

Resultados:

1
2
3
> php classes-08.php
group[0]=[[Paul,Langevin,48],English]
group[1]=[Sylvie,Lefur,70]

Comentários

  • Linhas 7–8: Precisamos informar ao interpretador PHP onde estão localizadas as duas classes [Teacher, Person]. A ordem é importante: a classe pai [Person] deve ser definida antes de a classe [Teacher] ser definida;
  • linhas 10–11: declaração dos nomes completos das duas classes. Isso nos permitirá referenciá-las no código simplesmente por seus nomes, sem o prefixo do namespace;
  • linha 16: criamos um array contendo um objeto do tipo [Teacher] e um objeto do tipo [Person];
  • linhas 19–21: exibição dos elementos do array;
  • linha 20: O método [__toString] de cada elemento [$group[$i]] será chamado. A classe [Person] tem um método [__toString]. A classe [Teacher] tem dois: o de sua classe pai e o seu próprio. Pode-se perguntar qual deles será chamado. A execução mostra que foi chamado o da classe [Teacher]. Isso sempre acontece: quando um método é chamado em um objeto, ele é procurado na seguinte ordem: na classe do objeto, na classe pai, se houver, depois na classe pai da classe pai, e assim por diante. A busca termina assim que o método é encontrado.

5.14. Criando uma segunda classe derivada da classe Person

O exemplo a seguir cria uma classe chamada [Student] derivada da classe [Person], no arquivo [Student.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// namespace
namespace Examples;

// uma segunda classe derivada de Person
class Student extends Person
{
    // atributo: curso de estudo
    private string $course;

    // getter e setter
    public function getCourse(): string
    {
        return $this->course;
    }

    public function setCourse(string $course): void
    {
        $this->course = $course;
    }

    // construtor
    public function __construct(string $firstName, string $lastName, int $age, string $course)
    {
        // atributos do pai
        parent::__construct($firstName, $lastName, $age);
        // outros atributos
        $this->setCourse($course);
    }

    // redefinição do método __toString da classe pai
    #[\Override]
    public function __toString(): string
    {
        return "[" . parent::__toString() . ",$this->course]";
    }
}

Essa classe é usada pelo seguinte script, [classes-09.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// inclusão e declaração das classes usadas pelo script
require_once __DIR__ . "/Person.php";
require_once __DIR__ . "/Teacher.php";
require_once __DIR__ . "/Student.php";
use Examples\{Person, Teacher, Student};

// teste
// criação de um array de objetos Person e de objetos derivados
// para tornar o exemplo mais fácil de entender, as exceções não são tratadas
$group = [
    new Teacher("Paul", "Langevin", 48, "English"),
    new Person("Sylvie", "Lefur", 70),
    new Student("Steve", "Boer", 23, "iup2 quality"),
];

// identidade dessas pessoas
foreach ($group as $i => $person) {
    print "group[$i]=$person (" . $person::class . ")\n";
}
// fim
exit;

Resultados:

1
2
3
4
> php classes-09.php
group[0]=[[Paul,Langevin,48],English] (Examples\Teacher)
group[1]=[Sylvie,Lefur,70] (Examples\Person)
group[2]=[[Steve,Boer,23],iup2 quality] (Examples\Student)

Comentários

  • Linha 10: Uma única instrução [use] pode declarar várias classes do mesmo namespace, colocando-as entre chaves;
  • Linha 22: O array é percorrido com [foreach], que retorna tanto o índice [$i] quanto o elemento [$person];
  • linha 23: a notação [$object::class] (PHP 8.0) retorna o nome completo da classe do objeto. Ela substitui a função [get_class], cujo uso sem parâmetros está obsoleto desde o PHP 8.3.

5.15. Relação entre o construtor de uma classe derivada e o da classe pai

Em algumas linguagens orientadas a objetos, o construtor de uma classe derivada chama automaticamente o de sua classe pai. O código a seguir, [classes-16.php] mostra que, em PHP, não é isso que acontece:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

class Class1
{
    // construtor
    public function __construct()
    {
        print "constructor of the Class1 class\n";
    }
}

class Class2 extends Class1
{
    // construtor
    public function __construct()
    {
        // o construtor da classe pai não é chamado implicitamente
        print "constructor of the Class2 class\n";
    }
}

class Class3 extends Class1
{
    // construtor
    public function __construct()
    {
        // chamada explícita do construtor da classe pai
        parent::__construct();
        // código específico de Class3
        print "constructor of the Class3 class\n";
    }
}

class Class4 extends Class1
{
    // sem construtor: usa-se o da classe pai
}

// testes
print "test1---------\n";
new Class2();
print "test2---------\n";
new Class3();
print "test3---------\n";
new Class4();

Resultados:

1
2
3
4
5
6
7
8
> php classes-16.php
test1---------
constructor of the Class2 class
test2---------
constructor of the Class1 class
constructor of the Class3 class
test3---------
constructor of the Class1 class

Comentários

  • linhas 15–23: O construtor de [Class2] não chama o de sua classe pai; o construtor da classe pai não é executado (linha 3 dos resultados);
  • linha 31: o construtor de [Class3] chama explicitamente o de sua classe pai (linhas 5–6 dos resultados);
  • linhas 37–40: A classe [Class4] não tem construtor. Ela herda, portanto, o construtor de sua classe pai, que é executado (linha 8 dos resultados).

5.16. Sobrescrevendo um método da classe pai

Já vimos que um método da classe pai pode ser sobrescrito em uma classe filha. Assim, o método [__toString] da classe [Person] foi sobrescrito nas classes filhas [Teacher] e [Student]. O script [classes-13.php] ilustra esse conceito mais uma vez:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// classe principal
class Class1
{
    public function f(): int
    {
        return 1;
    }

    public function g(): int
    {
        return 2;
    }
}

// classe derivada
class Class2 extends Class1
{
    // redefinimos a função f da classe pai
    #[\Override]
    public function f(): int
    {
        return parent::f() + 10;
    }
}

// código
$c2 = new Class2();
print $c2->f() . "\n";
print $c2->g() . "\n";
$c1 = new Class1();
print $c1->f() . "\n";

Resultados:

1
2
3
4
> php classes-13.php
11
2
1

Comentários

  • linhas 7–18: A classe [Class1] define dois métodos, f e g;
  • linhas 21–29: A classe [Class2] estende a classe [Class1] e redefine seu método f. O atributo [#[\Override]] documenta essa redefinição;
  • linha 32: cria um objeto [$c2] do tipo [Class2];
  • linha 33: chama o método f do objeto [$c2]. Como esse método existe na classe [Class2], ele é executado. Por sua vez, ele chama o método f da classe pai usando a notação [parent::f()];
  • linha 34: chama o método g do objeto [$c2]. Como esse método não existe na classe [Class2], ele é procurado na classe pai, onde é encontrado e executado;
  • linha 35: cria um objeto [$c1] do tipo [Class1];
  • linha 36: chama o método f do objeto [$c1]. É o método f da classe [Class1] que é executado.

Vejamos agora a finalidade do atributo [#[\Override]]. No script [classes-10.php], o desenvolvedor pretendia redefinir o método f, mas usou o nome errado:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// classe principal
class Class1
{
    public function f(): int
    {
        return 1;
    }
}

// classe derivada
class Class2 extends Class1
{
    // achamos que estamos redefinindo o método f da classe pai
    // mas erramos o nome: o atributo [Override] detecta isso
    #[\Override]
    public function F2(): int
    {
        return parent::f() + 10;
    }
}

// código
$c2 = new Class2();
print $c2->f() . "\n";

Resultados:

1
2
3
4
5
> php classes-10.php

Fatal error: Class2::F2() has #[\Override] attribute, but no matching parent method exists in .../php8-oct-2026/scripts-console/classes/classes-10.php on line 21
Stack trace:
#0 {main}

Sem o atributo [#[\Override]], o método [F2] seria simplesmente um novo método de [Class2], e o script exibiria [1] sem sinalizar nenhuma anomalia: o erro passaria despercebido. Com o atributo, o PHP rejeita a classe assim que ela é carregada (linha 3 dos resultados). No restante deste curso, usaremos sistematicamente [#[\Override]] nos métodos redefinidos.

5.17. Passando um objeto como parâmetro de uma função

Considere o seguinte script [classes-14.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// classe principal
class Class1
{
    public function f(): int
    {
        return 1;
    }

    public function g(): int
    {
        return 2;
    }
}

// classe derivada
class Class2 extends Class1
{
    // redefinimos a função f da classe pai
    #[\Override]
    public function f(): int
    {
        return parent::f() + 10;
    }
}

// o parâmetro da função é do tipo Class1 ou derivado
function doSomething(Class1 $c1): void
{
    print $c1->f() + $c1->g() . "\n";
}

// código
// criamos um objeto do tipo Class2 derivado de Class1
$c2 = new Class2();
// chamamos doSomething com um objeto do tipo Class2
doSomething($c2);
// um objeto de outro tipo é rejeitado
try {
    doSomething(new \stdClass());
} catch (\TypeError $e) {
    print "Error: " . $e->getMessage() . "\n";
}

Resultados:

1
2
3
> php classes-14.php
13
Error: doSomething(): Argument #1 ($c1) must be of type Class1, stdClass given, called in .../php8-oct-2026/scripts-console/classes/classes-14.php on line 44

Comentários

  • linhas 7–18: a classe [Class1];
  • linhas 21–29: uma classe [Class2] derivada de [Class1];
  • linha 32: uma função que espera um parâmetro do tipo [Class1]. Quando o tipo esperado é uma classe, o parâmetro real pode ser um objeto do tipo esperado ou de um tipo derivado;
  • linha 41: a função [doSomething] é chamada com um parâmetro do tipo [Class2], embora o tipo esperado seja [Class1]. Isso é aceito porque [Class2] é derivada de [Class1] (linha 2 dos resultados);
  • linha 44: um objeto do tipo [stdClass] não é do tipo [Class1]: a chamada causa um erro do tipo [TypeError] (linha 3 dos resultados).

5.18. Classes abstratas

Uma classe abstrata é uma classe incompleta que não pode ser instanciada. É preciso derivá-la para que seja utilizável.

Qual é a finalidade de uma classe abstrata? Às vezes temos classes que compartilham um ou mais métodos, mas diferem em outros métodos ou atributos. Nesses casos, é desejável reunir tudo o que elas têm em comum em uma classe pai. Por enquanto, não precisamos de uma classe abstrata. Mas suponha que as classes filhas difiram apenas em um método, M: a assinatura do método seria a mesma em todas as classes filhas, mas sua implementação seria diferente. Para obrigar as classes filhas a implementar o método M:

  • declararemos a assinatura do método M na classe pai. Como a classe pai não sabe como implementá-lo, prefixamos o método com a palavra-chave [abstract]: isso significa que a implementação do método M é delegada às classes filhas;
  • como a classe pai não está totalmente implementada, ela também é declarada abstrata com a mesma palavra-chave [abstract]. Isso significa que a classe não pode mais ser instanciada. É preciso criar uma classe filha para definir a implementação do método M, de modo que o corpo da classe pai possa ser utilizado.

Eis um exemplo [classes-15.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// classe principal abstrata
abstract class Class1
{
    // método conhecido por todas as classes derivadas
    public function f(): int
    {
        return 1;
    }

    // método abstrato g - será definido pelas classes derivadas
    abstract public function g(): int;
}

// classe derivada
class Class2 extends Class1
{
    // o método g da classe pai deve ser definido
    #[\Override]
    public function g(): int
    {
        return parent::f() + 10;
    }
}

// classe derivada
class Class3 extends Class1
{
    // o método g da classe pai deve ser definido
    #[\Override]
    public function g(): int
    {
        return parent::f() + 20;
    }

    // podemos redefinir o método f da classe pai
    #[\Override]
    public function f(): int
    {
        return 2;
    }
}

// código
$c2 = new Class2();
print $c2->f() . "\n";
print $c2->g() . "\n";
$c3 = new Class3();
print $c3->f() . "\n";
print $c3->g() . "\n";
// uma classe abstrata não pode ser instanciada
try {
    new Class1();
} catch (\Error $e) {
    print "Error: " . $e->getMessage() . "\n";
}

Resultados:

1
2
3
4
5
6
> php classes-15.php
1
11
2
21
Error: Cannot instantiate abstract class Class1

Comentários

  • linhas 7–17: A classe [Class1] é abstrata porque não implementa o método g da linha 16. Ela deve, portanto, ser derivada por outra classe para ser utilizável;
  • linhas 20–28: A classe [Class2] estende a classe [Class1] e define o método g de sua classe pai. O atributo [#[\Override]] também se aplica à implementação de um método abstrato;
  • linhas 31–46: A classe [Class3] estende a classe [Class1] e define o método g de sua classe pai;
  • linhas 40–44: A classe [Class3] também redefine o método f de sua classe pai;
  • linhas 49–54: dois objetos dos tipos [Class2] e [Class3] são criados, e seus métodos f e g são chamados;
  • linha 57: Uma classe abstrata não pode ser instanciada; ocorre um erro (linha 6 dos resultados).

5.19. Classes finais

Uma classe final é uma classe que não pode ser derivada. Considere o seguinte script, [classes-11.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// namespace
namespace Examples;

// classe que não pode ser derivada
final class Class1
{
}

// classe derivada - causa um erro
class Class2 extends Class1
{
}

// código
new Class2();

Resultados:

1
2
3
4
5
> php classes-11.php

Fatal error: Class Examples\Class2 cannot extend final class Examples\Class1 in .../php8-oct-2026/scripts-console/classes/classes-11.php on line 15
Stack trace:
#0 {main}

Comentários

  • linha 10: a palavra-chave [final] faz da classe [Class1] uma classe final que não pode ser derivada;
  • linha 15: a classe [Class2] estende a classe final [Class1], o que é um erro;
  • O erro é relatado assim que o interpretador PHP carrega a definição da classe [Class2]: trata-se de um erro fatal que não pode ser interceptado por um [try / catch]. O script não é executado.

Declarar uma classe como [final] é uma boa prática quando ela não foi projetada para ser derivada; isso impede que outros desenvolvedores dependam dos detalhes internos da classe.

5.20. Métodos finais

Um método final é um método que não pode ser sobrescrito por uma subclasse. Eis um exemplo, [classes-12.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// namespace
namespace Examples;

// classe principal
class Class1
{
    // este método não pode ser redefinido em uma classe derivada
    final public function f(): int
    {
        return 1;
    }
}

// classe derivada
class Class2 extends Class1
{
    // redefinição proibida - causa um erro
    public function f(): int
    {
        return 2;
    }
}

// código
new Class2();

Resultados:

1
2
3
4
5
> php classes-12.php

Fatal error: Cannot override final method Examples\Class1::f() in .../php8-oct-2026/scripts-console/classes/classes-12.php on line 23
Stack trace:
#0 {main}

Comentários

  • linha 13: O método f da classe [Class1] é declarado final com a palavra-chave ***[final]***;
  • linha 20: a classe [Class2] estende a classe [Class1];
  • linha 23: O método f da classe pai [Class1] é redefinido. Isso causa um erro fatal, que é relatado assim que a classe [Class2] é carregada.

5.21. Métodos e atributos estáticos

Um método estático é um método associado à classe em que é definido, e não aos objetos instanciados dessa classe. Assim, se a classe C declara um método estático M, para usá-lo de fora da classe, escreveríamos:

  • [C::M] se você estiver fora da classe;
  • [self::M] se você estiver dentro da classe.

Eis um exemplo: [classes-17.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

class Class1
{
    // método estático
    public static function say(string $message): void
    {
        print "$message\n";
    }

    // método estático que usa outro método estático da classe
    public static function sayTwice(string $message): void
    {
        self::say($message);
        self::say($message);
    }
}

// teste -------------------
Class1::say("hello");
Class1::sayTwice("good morning");
// sintaxe de callable de primeira classe: [Class1::say(...)] é uma função
$speak = Class1::say(...);
$speak("hi");
// que pode ser passada a outra função
array_map($speak, ["one", "two"]);

Resultados:

1
2
3
4
5
6
7
> php classes-17.php
hello
good morning
good morning
hi
one
two

Comentários

  • linha 9: o método [say] é declarado estático com a palavra-chave [static];
  • linha 17: Dentro da classe, o método estático [say] é chamado com a notação [self::say];
  • linha 23: o método estático [say] é chamado com a notação [Class1::say];
  • linha 26: sintaxe de callable de primeira classe (PHP 8.1): escrever [(...)] no lugar dos argumentos de uma chamada não faz a chamada, mas retorna a própria função, na forma de um objeto [Closure]. A variável [$speak] passa então a conter uma função que é chamada exatamente como uma função comum (linha 27). A mesma sintaxe se aplica a funções ([strlen(...)]) e a métodos de objetos ([$p->identity(...)]);
  • linha 29: tal função pode ser passada como argumento a outra função. A função [array_map] aplica a função [$speak] a cada elemento do array (linhas 6–7 dos resultados).

Consideremos agora o seguinte código, [classes-18.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

class Class1
{
    // atributo estático
    private static int $nbObjects = 0;

    public function __construct()
    {
        print "Class1 constructor\n";
        self::$nbObjects++;
    }

    // método estático
    public static function say(): void
    {
        print self::$nbObjects . " objects of type [Class1] have been built\n";
    }
}

// teste -------------------
new Class1();
new Class1();
Class1::say();

Resultados:

1
2
3
4
> php classes-18.php
Class1 constructor
Class1 constructor
2 objects of type [Class1] have been built

Comentários

  • Linha 9: Um atributo estático é declarado para contar o número de instâncias da classe [Class1] que foram criadas. Esse não é um atributo que possa pertencer a uma instância da classe. De fato, se dois objetos, O1 e O2, são criados, nenhum dos dois conhece o outro. Ter um contador na instância não faz sentido: quando um novo objeto é criado, em qual instância o contador seria incrementado? Um atributo estático é um atributo da classe, e não um atributo de instância da classe;
  • linhas 11–15: o construtor é o lugar onde contamos os objetos criados, já que a criação de cada novo objeto dispara a execução do construtor;
  • linha 14: Observe a notação [self::$nbObjects], que indica que nos referimos a um atributo estático da classe em que o código executado reside;
  • linhas 18–21: O método estático [say] é responsável por exibir o número de objetos criados;
  • Linhas 25–27: Dois objetos são criados, e o contador de objetos é exibido.

5.22. Visibilidade entre classes pai e filha

Examinemos o seguinte script, [classes-19.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

class SomeParent
{
    // atributo
    private int $attributeOfParent = 4;

    // método
    public function doTest(): void
    {
        // quem está chamando?
        print "parent:\n";
        var_dump($this);
        // exibição do pai
        print "parent: attributeOfParent={$this->attributeOfParent}\n";
        print "parent: attributeOfChild={$this->attributeOfChild}\n";
    }
}

class SomeChild extends SomeParent
{
    // atributo
    private int $attributeOfChild = 14;

    // método
    #[\Override]
    public function doTest(): void
    {
        // exibição do filho
        print "child: attributeOfParent={$this->attributeOfParent}\n";
        print "child: attributeOfChild={$this->attributeOfChild}\n";
        // pai
        parent::doTest();
    }
}

// script principal
print "---------------------------test1\n";
(new SomeParent())->doTest();
print "---------------------------test2\n";
(new SomeChild())->doTest();

Comentários

  • Linhas 6–21: a classe [SomeParent];
  • Linhas 23–38: a classe filha [SomeChild]. Vemos que ela estende a classe [SomeParent];
  • linha 9: a classe [SomeParent] tem apenas um atributo;
  • Linhas 12–20: O método [SomeParent::doTest] foi concebido para exibir dois atributos:
    • [$attributeOfParent], que pertence à classe [SomeParent];
    • [$attributeOfChild], que pertence à classe [SomeChild];
  • Linhas 15–16: A identidade do chamador é exibida; o método será chamado de duas maneiras diferentes:
    • a partir da classe pai [SomeParent];
    • a partir da classe filha [SomeChild];
  • linhas 18–19: exibem os dois atributos;
  • linha 26: a classe [SomeChild] tem apenas um atributo;
  • linha 30: o método [SomeChild::doTest] foi concebido para exibir dois atributos:
    • [$attributeOfParent], que pertence à classe [SomeParent];
    • [$attributeOfChild], que pertence à classe [SomeChild];
  • Linhas 33–34: exibição dos dois atributos;
  • linha 36: chama o método [doTest] da classe pai, que por sua vez exibe os dois atributos;
  • linha 42: o método [SomeParent::doTest] é chamado;
  • linha 44: o método [SomeChild::doTest] é chamado.

No primeiro teste, a visibilidade dos dois atributos é [private]. Podemos, portanto, esperar que a classe filha não veja o atributo de sua classe pai. Esse atributo precisaria ter, no mínimo, a visibilidade [protected]. Mas e o atributo da classe filha? Ele é visível na classe pai?

Eis os resultados desse primeiro teste:

> php classes-19.php
---------------------------test1
parent:
object(SomeParent)#1 (1) {
  ["attributeOfParent":"SomeParent":private]=>
  int(4)
}
parent: attributeOfParent=4

Warning: Undefined property: SomeParent::$attributeOfChild in .../php8-oct-2026/scripts-console/classes/classes-19.php on line 19
parent: attributeOfChild=
---------------------------test2

Warning: Undefined property: SomeChild::$attributeOfParent in .../php8-oct-2026/scripts-console/classes/classes-19.php on line 33
child: attributeOfParent=
child: attributeOfChild=14
parent:
object(SomeChild)#1 (2) {
  ["attributeOfParent":"SomeParent":private]=>
  int(4)
  ["attributeOfChild":"SomeChild":private]=>
  int(14)
}
parent: attributeOfParent=4

Fatal error: Uncaught Error: Cannot access private property SomeChild::$attributeOfChild in .../php8-oct-2026/scripts-console/classes/classes-19.php:19
Stack trace:
#0 .../php8-oct-2026/scripts-console/classes/classes-19.php(36): SomeParent->doTest()
#1 .../php8-oct-2026/scripts-console/classes/classes-19.php(44): SomeChild->doTest()
#2 {main}
  thrown in .../php8-oct-2026/scripts-console/classes/classes-19.php on line 19

Comentários

  • linhas 2–11: resultados do primeiro teste, em que o método [SomeParent::doTest] é chamado;
  • linhas 3–7: vemos que o objeto que chama o método é do tipo [SomeParent];
  • linha 8: o atributo [$attributeOfParent] é exibido;
  • linhas 10–11: Vemos que o atributo [SomeParent::$attributeOfChild] não existe. Portanto, ele não é exibido. No PHP 8, ler um atributo inexistente dispara um aviso de nível [Warning] (era um simples [Notice] no PHP 7);
  • linhas 12–31: resultados do segundo teste, em que o método [SomeChild::doTest] é chamado;
  • linhas 14–15: Vemos que o atributo [SomeChild::$attributeOfParent] não existe. Portanto, ele não é exibido. Isso é normal: o atributo [SomeParent::$attributeOfParent] é [private] e, portanto, não é reconhecido na classe filha;
  • linha 16: o atributo [$attributeOfChild] é exibido;
  • Linhas 17–31: Estamos no método [SomeParent::doTest] chamado pela classe filha;
  • linhas 18–23: vemos que [$this] é do tipo [SomeChild] com dois atributos privados;
  • linha 24: Surpreendentemente, [$this]—que é do tipo [SomeChild]—consegue ver o atributo privado de sua classe pai, [$attributeOfParent];
  • Linhas 26–31: Igualmente surpreendente, [$this], que é do tipo [SomeChild], não consegue acessar seu atributo [$attributeOfChild]: tentar acessá-lo causa um erro fatal.

Esse resultado é muito surpreendente: embora as linhas 18–23 indiquem que [$this] é do tipo [SomeChild], esse [$this] dentro do método [SomeParent::doTest] se comporta como se fosse uma instância da classe [SomeParent] e não da classe [SomeChild]. De fato, a visibilidade é verificada em relação à classe em que o código está escrito (aqui, [SomeParent]) e não em relação à classe do objeto.

Vamos executar um novo teste com o script [classes-20.php]. O atributo [$attributeOfParent] agora tem a visibilidade [protected]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

class SomeParent
{
    // atributo
    protected int $attributeOfParent = 4;

    // método
    public function doTest(): void
    {
        // quem está chamando?
        print "parent:\n";
        var_dump($this);
        // exibição do pai
        print "parent: attributeOfParent={$this->attributeOfParent}\n";
        print "parent: attributeOfChild={$this->attributeOfChild}\n";
    }
}

class SomeChild extends SomeParent
{
    // atributo
    private int $attributeOfChild = 14;

    // método
    #[\Override]
    public function doTest(): void
    {
        // exibição do filho
        print "child: attributeOfParent={$this->attributeOfParent}\n";
        print "child: attributeOfChild={$this->attributeOfChild}\n";
        // pai
        parent::doTest();
    }
}

// script principal
print "---------------------------test1\n";
(new SomeParent())->doTest();
print "---------------------------test2\n";
(new SomeChild())->doTest();

Resultados:

> php classes-20.php
---------------------------test1
parent:
object(SomeParent)#1 (1) {
  ["attributeOfParent":protected]=>
  int(4)
}
parent: attributeOfParent=4

Warning: Undefined property: SomeParent::$attributeOfChild in .../php8-oct-2026/scripts-console/classes/classes-20.php on line 19
parent: attributeOfChild=
---------------------------test2
child: attributeOfParent=4
child: attributeOfChild=14
parent:
object(SomeChild)#1 (2) {
  ["attributeOfParent":protected]=>
  int(4)
  ["attributeOfChild":"SomeChild":private]=>
  int(14)
}
parent: attributeOfParent=4

Fatal error: Uncaught Error: Cannot access private property SomeChild::$attributeOfChild in .../php8-oct-2026/scripts-console/classes/classes-20.php:19
Stack trace:
#0 .../php8-oct-2026/scripts-console/classes/classes-20.php(36): SomeParent->doTest()
#1 .../php8-oct-2026/scripts-console/classes/classes-20.php(44): SomeChild->doTest()
#2 {main}
  thrown in .../php8-oct-2026/scripts-console/classes/classes-20.php on line 19

Comentários

  • Linha 13: A classe [SomeChild] agora consegue ver o atributo de sua classe pai, [$attributeOfParent]. Isso é normal, já que o pai agora tem escopo [protected];
  • No método [SomeParent::doTest], o objeto [$this] é do tipo [SomeChild] (linhas 16–21). Ele consegue ver o atributo de sua classe pai, [$attributeOfParent] (linha 22), mas ainda não consegue ver seu próprio atributo privado, [$attributeOfChild] (linhas 24–29).

Na terceira tentativa, [classes-21.php], o atributo [$attributeOfChild] também tem escopo [protected]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

class SomeParent
{
    // atributo
    protected int $attributeOfParent = 4;

    // método
    public function doTest(): void
    {
        // quem está chamando?
        print "parent:\n";
        var_dump($this);
        // exibição do pai
        print "parent: attributeOfParent={$this->attributeOfParent}\n";
        print "parent: attributeOfChild={$this->attributeOfChild}\n";
    }
}

class SomeChild extends SomeParent
{
    // atributo
    protected int $attributeOfChild = 14;

    // método
    #[\Override]
    public function doTest(): void
    {
        // exibição do filho
        print "child: attributeOfParent={$this->attributeOfParent}\n";
        print "child: attributeOfChild={$this->attributeOfChild}\n";
        // pai
        parent::doTest();
    }
}

// script principal
print "---------------------------test1\n";
(new SomeParent())->doTest();
print "---------------------------test2\n";
(new SomeChild())->doTest();

Os resultados da execução são os seguintes:

> php classes-21.php
---------------------------test1
parent:
object(SomeParent)#1 (1) {
  ["attributeOfParent":protected]=>
  int(4)
}
parent: attributeOfParent=4

Warning: Undefined property: SomeParent::$attributeOfChild in .../php8-oct-2026/scripts-console/classes/classes-21.php on line 19
parent: attributeOfChild=
---------------------------test2
child: attributeOfParent=4
child: attributeOfChild=14
parent:
object(SomeChild)#1 (2) {
  ["attributeOfParent":protected]=>
  int(4)
  ["attributeOfChild":protected]=>
  int(14)
}
parent: attributeOfParent=4
parent: attributeOfChild=14
  • Linha 23: Desta vez, dentro da classe pai, [$this], que é do tipo [SomeChild] (linhas 16–21), vê o atributo protegido [$attributeOfChild] de sua própria classe, [SomeChild].

O que podemos aprender com esses testes?

  • Que a instância [$this] de uma classe pai, usada em um método da classe pai, consegue ver:
    • os atributos e métodos da classe pai, independentemente de sua visibilidade;
    • não vê nenhum dos atributos ou métodos de suas classes filhas;
  • esse é o comportamento esperado;
  • que a instância [$this] de uma classe filha, usada em um método da classe filha, vê:
    • os atributos e métodos da classe pai, se tiverem, no mínimo, a visibilidade [protected]. Os de visibilidade [private] não são visíveis;
    • os atributos e métodos da classe filha, independentemente de sua visibilidade;
  • esse é o comportamento esperado;
  • a instância [$this] de uma classe filha, usada em um método da classe pai, vê:
    • os atributos e métodos da classe pai, independentemente de sua visibilidade;
    • os atributos e métodos de sua própria classe apenas se tiverem, no mínimo, a visibilidade [protected]. Os de visibilidade [private] não são visíveis;
  • Esse é um comportamento inesperado, que se explica pela regra enunciada acima: a visibilidade depende da classe em que o código está escrito.

5.23. Enumerações (PHP 8.1)

Uma pessoa tem um gênero: feminino ou masculino. Como representar essa informação? No PHP 7, usava-se uma string (["F"], ["M"]) ou constantes de classe. Na época, nada impedia que se passasse um valor incorreto (["X"], ["female"]...). O PHP 8.1 introduziu as enumerações (palavra-chave [enum]): uma enumeração é um tipo que tem apenas um número finito de valores possíveis, chamados de cases. Definimos a enumeração [Gender] no arquivo [Gender.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// namespace
namespace Examples;

// uma enumeração com valores de string (backed enum)
enum Gender: string
{
    case Female = "F";
    case Male = "M";

    // uma enumeração pode ter métodos
    public function label(): string
    {
        return match ($this) {
            Gender::Female => "Madam",
            Gender::Male => "Sir",
        };
    }
}

Comentários

  • Linha 10: a enumeração [Gender]. O tipo [string] que segue seu nome faz dela uma enumeração “com valor associado” (backed): cada case é associado a um valor escalar, neste caso uma string. Esse valor é útil para armazenar o case em um arquivo ou em um banco de dados. Sem esse tipo, trata-se de uma enumeração pura, cujos cases não têm valores associados;
  • linhas 12–13: os dois cases da enumeração e seus valores;
  • linhas 16–22: Uma enumeração pode ter métodos (assim como constantes e métodos estáticos). Dentro de um método, ***[$this]*** designa o case sobre o qual o método é chamado;
  • linhas 18–21: a expressão [match] (PHP 8.0) compara seu parâmetro com os valores de cada ramo usando o operador [===] e retorna o valor do primeiro ramo correspondente. Se nenhum ramo corresponder, um erro [UnhandledMatchError] é lançado. Aqui, todos os ramos estão definidos.

A enumeração é usada pelo script [classes-26.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

require_once __DIR__ . "/Gender.php";
use Examples\Gender;

// uma pessoa com um gênero
final readonly class Person
{
    public function __construct(
        public string $firstName,
        public string $lastName,
        public Gender $gender,
    ) {
    }

    public function __toString(): string
    {
        return "{$this->gender->label()} $this->firstName $this->lastName";
    }
}

// teste
$p1 = new Person("Paul", "Langevin", Gender::Male);
$p2 = new Person("Sylvie", "Lefur", Gender::Female);
print "$p1\n$p2\n";
// um case de enumeração tem um nome e um valor
print "name={$p2->gender->name}, value={$p2->gender->value}\n";
// os cases são objetos únicos: são comparados com ===
print "p1 is a man: " . var_export($p1->gender === Gender::Male, true) . "\n";
// a lista dos cases
foreach (Gender::cases() as $gender) {
    print "$gender->name ($gender->value): {$gender->label()}\n";
}
// de um valor (lido de um arquivo, de um banco de dados...) para um case
print "from('F'): " . Gender::from("F")->name . "\n";
print "tryFrom('X'): " . var_export(Gender::tryFrom("X"), true) . "\n";
try {
    Gender::from("X");
} catch (\ValueError $e) {
    print "Error: " . $e->getMessage() . "\n";
}
// o tipo [Gender] só aceita os cases da enumeração
try {
    new Person("Steve", "Boer", "M");
} catch (\TypeError $e) {
    print "Error: " . $e->getMessage() . "\n";
}

Resultados:

> php classes-26.php
Sir Paul Langevin
Madam Sylvie Lefur
name=Female, value=F
p1 is a man: true
Female (F): Madam
Male (M): Sir
from('F'): Female
tryFrom('X'): NULL
Error: "X" is not a valid backing value for enum Examples\Gender
Error: Person::__construct(): Argument #3 ($gender) must be of type Examples\Gender, string given, called in .../php8-oct-2026/scripts-console/classes/classes-26.php on line 47

Comentários

  • linha 15: o atributo [gender] da classe [Person] é do tipo [Gender];
  • linha 21: chamada ao método [label] da instância armazenada no atributo [gender];
  • linha 26: um case é designado pela notação [Gender::Male];
  • linha 30: cada case tem um atributo [name], seu nome, e, para uma enumeração com valor associado, um atributo [value], seu valor (linha 4 dos resultados);
  • linha 32: cada case é um objeto único: os cases são comparados com o operador [===];
  • linha 34: o método estático [cases] retorna a lista de cases da enumeração (linhas 6–7 dos resultados);
  • linha 38: o método estático [from] retorna o case associado a um valor. É o processo inverso de [value]: ["F"] é lido de um banco de dados, e o case [Gender::Female] é obtido;
  • linha 39: o método [tryFrom] retorna [null] se o valor não corresponder a nenhum case;
  • linha 41: o método [from], por outro lado, lança um erro [ValueError] (linha 10 dos resultados);
  • linha 47: o tipo [Gender] aceita apenas os cases do enum, e não seus valores: ["M"] é rejeitado (linha 11 dos resultados). Esse é todo o objetivo das enumerações: um valor incorreto é detectado imediatamente.

5.24. Codificação JSON de uma classe

Em uma classe, o método [__toString] costuma estar presente: ele deve retornar uma string que representa o objeto que o chama. Pode ser tentador fazer dessa string uma string JSON. Vamos explorar essa abordagem agora. Os scripts estão na pasta [scripts-console/classes/json]:

1
2
3
4
5
6
7
8
9
php8-oct-2026/scripts-console/classes/json
├── json-01.php
├── json-02.php
├── json-03.php
├── json-04.php
├── Person.php
├── Person2.php
├── Person3.php
└── Person4.php

Usaremos a seguinte classe [Person]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

class Person
{
    // atributos
    private ?string $lastName = null;
    private ?string $firstName = null;
    private ?int $age = null;
    private ?array $children = null;

    // setter global
    public function setFromArray(array $arrayOfAttributes): static
    {
        // inicialização de alguns atributos da classe
        foreach ($arrayOfAttributes as $attribute => $value) {
            // atributos não declarados na classe são rejeitados
            if (!property_exists($this, $attribute)) {
                throw new \InvalidArgumentException("Unknown attribute [$attribute]");
            }
            $this->$attribute = $value;
        }
        // retornamos o objeto
        return $this;
    }

    // getters
    public function getLastName(): ?string
    {
        return $this->lastName;
    }

    public function getFirstName(): ?string
    {
        return $this->firstName;
    }

    public function getAge(): ?int
    {
        return $this->age;
    }

    public function getChildren(): ?array
    {
        return $this->children;
    }


    // __toString
    public function __toString(): string
    {
        // identificamos o objeto
        var_dump($this);
        // recuperamos seus atributos
        $attributes = \get_object_vars($this);
        var_dump($attributes);
        // retornamos a string JSON dos atributos
        return \json_encode($attributes, JSON_UNESCAPED_UNICODE);
    }
}

Comentários

  • linhas 9–12: os quatro atributos da classe. São tipos anuláveis ([?string] significa [string] ou [null]) e são inicialmente definidos como [null];
  • linhas 30–45: os getters que permitem recuperar os valores desses atributos;
  • linhas 15–27: um setter global que inicializa os atributos a partir de um array associativo ***[$arrayOfAttributes],*** cujas chaves correspondem aos nomes dos atributos da classe;
  • linha 20: a função [property_exists] verifica se o atributo está declarado na classe. Sem essa verificação, uma chave desconhecida criaria um atributo dinâmico, o que está obsoleto desde o PHP 8.2;
  • Linha 23: A notação [$this->$attribute] designa o atributo cujo nome é o valor da variável [$attribute];
  • linha 15: O método retorna o objeto atual [$this]. Seu tipo de retorno é [static]: “um objeto da classe sobre a qual o método foi chamado”. Isso permite chamadas encadeadas: [(new Person())->setFromArray([...])];
  • Linhas 52–61: o método [__toString] da classe;
  • linha 57: a função PHP [get_object_vars] recupera os valores dos atributos do objeto na forma de um array associativo [['lastName'=>'lastName1', 'firstName'=>'firstName1', 'age'=>age1, 'children'=>[...]]]. Quando chamada de dentro da classe, ela também retorna os atributos privados;
  • linha 60: a string JSON desse array de atributos é retornada. A opção [JSON_UNESCAPED_UNICODE] especifica que os caracteres acentuados não devem ser convertidos em sequências [é].

Vamos examinar o script [json-01.php], que usa a classe [Person]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// classe Person
require_once __DIR__ . "/Person.php";

// instanciação do pai
$father = new Person();
// inicialização do pai
$father->setFromArray([
    "lastName" => "Bertholomé",
    "firstName" => "Dieudonné",
    "age" => 58,
]);
// instanciação e inicialização de child1
$child1 = (new Person())->setFromArray([
    "lastName" => "Bertholomé",
    "firstName" => "Sylvain",
    "age" => 17,
]);
// instanciação e inicialização de child2
$child2 = (new Person())->setFromArray([
    "lastName" => "Bertholomé",
    "firstName" => "Géraldine",
    "age" => 12,
]);
// inicialização dos filhos do pai
$father->setFromArray([
    "children" => [$child1, $child2],
]);

// exibição dos elementos do pai
$child1 = $father->getChildren()[0];
$child2 = $father->getChildren()[1];
print "------------------------child1\n";
print "child1=$child1\n";
print "------------------------child2\n";
print "child2=$child2\n";
print "------------------------father\n";
print "father=$father\n";

Comentários

  • linhas 10–16: um objeto do tipo [Person] [$father] é inicializado com o método [Person::setFromArray];
  • linhas 18–22: um objeto [Person] [$child1] é inicializado da mesma maneira;
  • linhas 24–28: inicializa-se um objeto [Person] [$child2];
  • linha 31: o atributo [children] do pai é inicializado com um array contendo os dois filhos;
  • linhas 35–36: recuperam-se os dois filhos do pai;
  • linha 38: a operação [print] tenta converter o objeto [$child1] em string. Para isso, ela usa o método [__toString] do objeto. Esperamos, portanto, ver a string JSON do objeto;
  • linha 42: fazemos o mesmo com o pai.

Os resultados são os seguintes:

> php json-01.php
------------------------child1
object(Person)#2 (4) {
  ["lastName":"Person":private]=>
  string(11) "Bertholomé"
  ["firstName":"Person":private]=>
  string(7) "Sylvain"
  ["age":"Person":private]=>
  int(17)
  ["children":"Person":private]=>
  NULL
}
array(4) {
  ["lastName"]=>
  string(11) "Bertholomé"
  ["firstName"]=>
  string(7) "Sylvain"
  ["age"]=>
  int(17)
  ["children"]=>
  NULL
}
child1={"lastName":"Bertholomé","firstName":"Sylvain","age":17,"children":null}
------------------------child2
object(Person)#3 (4) {
  ["lastName":"Person":private]=>
  string(11) "Bertholomé"
  ["firstName":"Person":private]=>
  string(10) "Géraldine"
  ["age":"Person":private]=>
  int(12)
  ["children":"Person":private]=>
  NULL
}
array(4) {
  ["lastName"]=>
  string(11) "Bertholomé"
  ["firstName"]=>
  string(10) "Géraldine"
  ["age"]=>
  int(12)
  ["children"]=>
  NULL
}
child2={"lastName":"Bertholomé","firstName":"Géraldine","age":12,"children":null}
------------------------father
object(Person)#1 (4) {
  ["lastName":"Person":private]=>
  string(11) "Bertholomé"
  ["firstName":"Person":private]=>
  string(10) "Dieudonné"
  ["age":"Person":private]=>
  int(58)
  ["children":"Person":private]=>
  array(2) {
    [0]=>
    object(Person)#2 (4) {
      ["lastName":"Person":private]=>
      string(11) "Bertholomé"
      ["firstName":"Person":private]=>
      string(7) "Sylvain"
      ["age":"Person":private]=>
      int(17)
      ["children":"Person":private]=>
      NULL
    }
    [1]=>
    object(Person)#3 (4) {
      ["lastName":"Person":private]=>
      string(11) "Bertholomé"
      ["firstName":"Person":private]=>
      string(10) "Géraldine"
      ["age":"Person":private]=>
      int(12)
      ["children":"Person":private]=>
      NULL
    }
  }
}
array(4) {
  ["lastName"]=>
  string(11) "Bertholomé"
  ["firstName"]=>
  string(10) "Dieudonné"
  ["age"]=>
  int(58)
  ["children"]=>
  array(2) {
    [0]=>
    object(Person)#2 (4) {
      ["lastName":"Person":private]=>
      string(11) "Bertholomé"
      ["firstName":"Person":private]=>
      string(7) "Sylvain"
      ["age":"Person":private]=>
      int(17)
      ["children":"Person":private]=>
      NULL
    }
    [1]=>
    object(Person)#3 (4) {
      ["lastName":"Person":private]=>
      string(11) "Bertholomé"
      ["firstName":"Person":private]=>
      string(10) "Géraldine"
      ["age":"Person":private]=>
      int(12)
      ["children":"Person":private]=>
      NULL
    }
  }
}
father={"lastName":"Bertholomé","firstName":"Dieudonné","age":58,"children":[{},{}]}

Comentários

  • linhas 3–12: o objeto [$child1];
  • Linhas 13–22: o array de atributos do objeto [$child1]. Temos todos eles;
  • linha 23: temos a string JSON do objeto [$child1];
  • linhas 24–45: o mesmo para o objeto [$child2];
  • linhas 46–113: para o pai, é um pouco diferente, já que seu atributo [children] não é [null], como era para os filhos;
  • linha 113: vemos que, na string JSON do pai, os filhos são objetos vazios [{}];
  • Linhas 80–112: Vemos que, na tabela de atributos do pai, o filho 1 permaneceu um objeto, assim como o filho 2. Em suma, a expressão [\get_object_vars($this)]—em que [$this] representa o pai—não é recursiva: se um atributo da classe [Person] for ele próprio um objeto, a expressão [\get_object_vars($this)] não tenta recuperar seu array de atributos. Além disso, a função [json_encode] codifica apenas os atributos públicos de um objeto: os filhos, cujos atributos são todos privados, tornam-se objetos JSON vazios.

Podemos melhorar isso. Modificamos a classe [Person] para a seguinte classe [Person2]:

    // __toString
    public function __toString(): string
    {
        // recuperamos os atributos do objeto
        $attributes = $this->getAttributes();
        $children = $attributes["children"];
        if ($children !== null) {
            $attributes["children"] = [$children[0]->getAttributes(), $children[1]->getAttributes()];
        }
        // retornamos a string JSON dos atributos
        return \json_encode($attributes, JSON_UNESCAPED_UNICODE);
    }

    public function getAttributes(): array
    {
        return \get_object_vars($this);
    }
}

Comentários

  • linhas 64–67: O método [getAttributes] retorna o array de atributos do objeto que o chama;
  • linhas 52–62: o método [__toString];
  • Linha 55: Recuperamos os atributos do objeto a partir do array [$attributes];
  • linha 56: Pelo exemplo anterior, sabemos que [$attributes["children"]] é um array de dois objetos do tipo [Person2];
  • Linhas 57–59: Os dois objetos são substituídos por seus arrays de atributos;
  • linha 61: resta apenas codificar em JSON o array de atributos construído.

O script [json-02.php] usa a classe [Person2] da seguinte maneira:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// classe Person2
require_once __DIR__ . "/Person2.php";

// instanciação do pai
$father = new Person2();
// inicialização do pai
$father->setFromArray([
    "lastName" => "Bertholomé",
    "firstName" => "Dieudonné",
    "age" => 58,
]);
// instanciação e inicialização de child1
$child1 = (new Person2())->setFromArray([
    "lastName" => "Bertholomé",
    "firstName" => "Sylvain",
    "age" => 17,
]);
// instanciação e inicialização de child2
$child2 = (new Person2())->setFromArray([
    "lastName" => "Bertholomé",
    "firstName" => "Géraldine",
    "age" => 12,
]);
// inicialização dos filhos do pai
$father->setFromArray([
    "children" => [$child1, $child2],
]);

// exibição do pai
print "------------------------father\n";
print "father=$father\n";

O script [json-02.php] é idêntico ao script [json-01.php], exceto que a classe [Person2] substituiu a classe [Person] e apenas o pai é exibido. Os resultados da execução são os seguintes:

1
2
3
> php json-02.php
------------------------father
father={"lastName":"Bertholomé","firstName":"Dieudonné","age":58,"children":[{"lastName":"Bertholomé","firstName":"Sylvain","age":17,"children":null},{"lastName":"Bertholomé","firstName":"Géraldine","age":12,"children":null}]}

Desta vez, os filhos são exibidos corretamente junto com o pai.

A solução anterior não é satisfatória porque os filhos podem ter filhos próprios. Isso nos leva de volta ao problema anterior. A classe [Person3] resolve esse problema da seguinte maneira:

    // __toString
    public function __toString(): string
    {
        // retornamos a string JSON dos atributos
        $attributes = [];
        $this->getRecursiveAttributes($attributes, $this, []);
        // string JSON dos atributos
        return \json_encode($attributes, JSON_UNESCAPED_UNICODE);
    }

    public function getAttributes(): array
    {
        return \get_object_vars($this);
    }

    private function getRecursiveAttributes(array &$attributes, mixed $value, array $keys): void
    {
        // análise do valor [$value]
        // $keys é um array [key1, key2, .., keyn]
        // $value=$attributes[key1][key2]...[keyn]
        // se [$value] for um objeto, usamos seu método [getAttributes]
        if (\is_object($value)) {
            // atributos do objeto [$value]
            $objectAttributes = $value->getAttributes();
            // há chaves?
            if ($keys) {
                // em [$attributes], vamos substituir $value pelo array de seus atributos
                // devemos construir o elemento $attributes[key1][key2]...[keyn]
                // em que $keys é o array [key1, key2, .., keyn]
                // pegamos a referência do array [$attributes]
                $attribute = &$attributes;
                // percorremos o array de chaves
                foreach ($keys as $key) {
                    // pegamos a referência do atributo
                    $attribute = &$attribute[$key];
                }
                // aqui $attribute e $attributes[key1][key2]...[keyn] são idênticos
                // eles compartilham o mesmo local de memória
                // o objeto [$value] é substituído por seu array de atributos:
                // devemos escrever $attributes[key1][key2]...[keyn]=$objectAttributes
                // o que equivale a $attribute = $objectAttributes
                $attribute = $objectAttributes;
            } else {
                // sem chaves - estamos no início da exploração do objeto
                // $objectAttributes representa os atributos de 1º nível da classe
                $attributes += $objectAttributes;
            }
            // talvez ainda haja objetos em [$objectAttributes]
            // exploramos os atributos de [$objectAttributes]
            $this->getRecursiveAttributes($attributes, $objectAttributes, $keys);
        } elseif (\is_array($value)) {
            // temos um array - analisamos cada um de seus elementos
            foreach ($value as $key => $element) {
                // adicionamos a chave atual ao array $keys
                $keys[] = $key;
                // analisamos $element
                $this->getRecursiveAttributes($attributes, $element, $keys);
                // removemos do array $keys a chave que acabou de ser analisada
                \array_pop($keys);
            }
        }
    }
}

Comentários

  • linha 56: desta vez, o método [__toString] recupera os atributos de sua classe e exige que isso seja feito de forma recursiva: se um atributo é um objeto ou um array de objetos, cada objeto deve ser substituído por seu array de atributos no array final de atributos da classe;
  • Linhas 66–112: O método [getRecursiveAttributes] realiza essa tarefa. Comentamos seu código. Escrever uma função recursiva costuma ser complexo. É o caso aqui. O leitor não perderá nada se não a entender: veremos em breve que o PHP oferece uma solução muito mais simples. A chamada recursiva ocorre nas linhas 100 e 107;
  • a vantagem desse código é que ele não foi escrito exclusivamente para a classe [Person3]. Ele se aplica a qualquer classe com atributos cujos valores sejam objetos de tipos diferentes, desde que as classes usadas pela classe principal tenham também, como a própria classe principal, o método [getAttributes] das linhas 61–64.

O script [json-03.php] usa a classe [Person3] da seguinte maneira:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// classe Person3
require_once __DIR__ . "/Person3.php";

// instanciação do pai
$father = new Person3();
// inicialização do pai
$father->setFromArray([
    "lastName" => "Bertholomé",
    "firstName" => "Dieudonné",
    "age" => 58,
]);
// instanciação e inicialização de child1
$child1 = (new Person3())->setFromArray([
    "lastName" => "Bertholomé",
    "firstName" => "Sylvain",
    "age" => 27,
]);
// instanciação e inicialização de child2
$child2 = (new Person3())->setFromArray([
    "lastName" => "Bertholomé",
    "firstName" => "Géraldine",
    "age" => 12,
]);
// inicialização dos filhos do pai
$father->setFromArray([
    "children" => [$child1, $child2],
]);
// instanciação e inicialização de child11
$child11 = (new Person3())->setFromArray([
    "lastName" => "Bertholomé",
    "firstName" => "Gaëtan",
    "age" => 2,
]);
// instanciação e inicialização de child12
$child12 = (new Person3())->setFromArray([
    "lastName" => "Bertholomé",
    "firstName" => "Mathilde",
    "age" => 1,
]);
// inicialização dos filhos de child1
$child1->setFromArray([
    "children" => [$child11, $child12],
]);
// exibição do pai
print "------------------------father\n";
print "father=$father\n";
  • linhas 34–47: [$child1] recebe dois filhos.

Os resultados da execução são os seguintes:

1
2
3
> php json-03.php
------------------------father
father={"lastName":"Bertholomé","firstName":"Dieudonné","age":58,"children":[{"lastName":"Bertholomé","firstName":"Sylvain","age":27,"children":[{"lastName":"Bertholomé","firstName":"Gaëtan","age":2,"children":null},{"lastName":"Bertholomé","firstName":"Mathilde","age":1,"children":null}]},{"lastName":"Bertholomé","firstName":"Géraldine","age":12,"children":null}]}

As strings JSON foram recuperadas com sucesso de todos os objetos [Person3] que compõem o pai.

5.24.1. A interface [JsonSerializable]

Há uma solução muito mais simples, fornecida pelo PHP: a interface predefinida [JsonSerializable]. Examinaremos as interfaces no próximo capítulo. Por ora, observemos apenas que uma classe que “implementa” a interface [JsonSerializable] deve definir um método [jsonSerialize(): mixed]. Quando a função [json_encode] encontra um objeto dessa classe, ela chama seu método [jsonSerialize] e codifica o valor retornado no lugar do objeto. Ela faz isso em todos os níveis da árvore de dados. A classe [Person4] usa essa interface:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// a classe implementa a interface predefinida [JsonSerializable]
class Person4 implements \JsonSerializable
{
    // construtor com promoção de parâmetros
    public function __construct(
        private string $lastName,
        private string $firstName,
        private int $age,
        // array de objetos [Person4]
        private array $children = [],
    ) {
    }

    // adiciona um filho e retorna o objeto atual para encadear as chamadas
    public function addChild(Person4 $child): static
    {
        $this->children[] = $child;
        return $this;
    }

    // método da interface [JsonSerializable]:
    // retorna o valor que [json_encode] deve codificar no lugar do objeto
    #[\Override]
    public function jsonSerialize(): mixed
    {
        return \get_object_vars($this);
    }

    // __toString: a string JSON do objeto
    public function __toString(): string
    {
        return \json_encode($this, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR);
    }
}

Comentários

  • linha 7: a classe implementa a interface [JsonSerializable];
  • linhas 10–16: Um construtor com promoção de parâmetros substitui o setter global. O array de filhos é vazio por padrão;
  • linhas 20–24: Adiciona um filho e retorna o objeto atual (tipo de retorno [static]) para permitir chamadas encadeadas;
  • linha 29: o método exigido pela interface. Seu tipo de retorno é [mixed] (PHP 8.0), que significa “qualquer tipo”. Aqui, ele retorna o array de atributos do objeto. Os filhos continuam sendo objetos [Person4]: [json_encode] chamará o método próprio deles, [jsonSerialize]. A recursão é tratada pelo PHP;
  • linha 28: o atributo [#[\Override]] também se aplica a um método imposto por uma interface;
  • linha 37: [json_encode] é chamada diretamente sobre o objeto. Três opções são combinadas com o operador [|]:
    • [JSON_UNESCAPED_UNICODE]: os caracteres acentuados são escritos como estão;
    • [JSON_PRETTY_PRINT]: A string JSON é formatada em várias linhas, com indentação;
    • [JSON_THROW_ON_ERROR] (PHP 7.3): em caso de erro, [json_encode] lança uma exceção [JsonException] em vez de retornar [false]. Isso é importante aqui: o método [__toString] deve retornar uma string e não pode retornar [false].

O script [json-04.php] usa a classe [Person4]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// classe Person4
require_once __DIR__ . "/Person4.php";

// o pai, seus filhos e seus netos
$child1 = (new Person4("Bertholomé", "Sylvain", 27))
    ->addChild(new Person4("Bertholomé", "Gaëtan", 2))
    ->addChild(new Person4("Bertholomé", "Mathilde", 1));
$father = (new Person4("Bertholomé", "Dieudonné", 58))
    ->addChild($child1)
    ->addChild(new Person4("Bertholomé", "Géraldine", 12));

// exibição do pai: [json_encode] chama [jsonSerialize] em cada objeto encontrado
print "------------------------father\n";
print "father=$father\n";
// uma string JSON compacta, sem escapar os caracteres acentuados
print "------------------------json_encode\n";
print json_encode($child1, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR) . "\n";
// decodificação: obtemos um array associativo (2º parâmetro igual a true), não um objeto [Person4]
print "------------------------json_decode\n";
$data = json_decode((string) $father, true, flags: JSON_THROW_ON_ERROR);
print "first name of the 1st grandchild: {$data['children'][0]['children'][0]['firstName']}\n";
// uma string JSON incorreta causa uma exceção [JsonException]
print "------------------------error\n";
try {
    json_decode('{"lastName": "Bertholomé"', flags: JSON_THROW_ON_ERROR);
} catch (\JsonException $e) {
    print "Error: " . $e->getMessage() . "\n";
}
// sem [JSON_THROW_ON_ERROR], o erro é silencioso
var_dump(json_decode('{"lastName": "Bertholomé"'));
print "json_last_error_msg: " . json_last_error_msg() . "\n";

Resultados:

> php json-04.php
------------------------father
father={
    "lastName": "Bertholomé",
    "firstName": "Dieudonné",
    "age": 58,
    "children": [
        {
            "lastName": "Bertholomé",
            "firstName": "Sylvain",
            "age": 27,
            "children": [
                {
                    "lastName": "Bertholomé",
                    "firstName": "Gaëtan",
                    "age": 2,
                    "children": []
                },
                {
                    "lastName": "Bertholomé",
                    "firstName": "Mathilde",
                    "age": 1,
                    "children": []
                }
            ]
        },
        {
            "lastName": "Bertholomé",
            "firstName": "Géraldine",
            "age": 12,
            "children": []
        }
    ]
}
------------------------json_encode
{"lastName":"Bertholomé","firstName":"Sylvain","age":27,"children":[{"lastName":"Bertholomé","firstName":"Gaëtan","age":2,"children":[]},{"lastName":"Bertholomé","firstName":"Mathilde","age":1,"children":[]}]}
------------------------json_decode
first name of the 1st grandchild: Gaëtan
------------------------error
Error: Syntax error
NULL
json_last_error_msg: Syntax error

Comentários

  • linhas 10–12: construção de [$child1] e de seus dois filhos por meio de chamadas encadeadas;
  • linha 19: o método [__toString] do pai produz uma string JSON formatada que contém todos os descendentes (linhas 3–34 dos resultados). Não escrevemos nenhum código recursivo;
  • linha 22: sem [JSON_PRETTY_PRINT], a string JSON é compacta (linha 36 dos resultados);
  • linha 25: a função [json_decode] realiza a operação inversa: transforma uma string JSON em um valor PHP. Com um segundo parâmetro igual a [true], os objetos JSON se tornam arrays associativos. Observe que isso retorna arrays, e não objetos [Person4]: reconstruir objetos a partir de uma string JSON exige código adicional (ou uma biblioteca como o componente [Serializer] do Symfony). O argumento nomeado [flags:] elimina a necessidade de passar o terceiro parâmetro [depth];
  • linha 30: a string JSON está incorreta (falta a chave de fechamento). Com [JSON_THROW_ON_ERROR], uma exceção [JsonException] é lançada (linha 40 dos resultados);
  • linha 35: sem [JSON_THROW_ON_ERROR], [json_decode] retorna [null] sem relatar nenhum erro (linha 41). Seria preciso então consultar a função [json_last_error_msg] para saber se ocorreu um erro. É por isso que usaremos sistematicamente a opção [JSON_THROW_ON_ERROR] no restante deste curso.