Construtor PHP: __construct e promoção de propriedades

Um construtor PHP é um método chamado __construct(). O PHP o chama automaticamente quando você escreve new ClassName(...), e os argumentos entre parênteses viram os parâmetros dele, então o objeto já começa com os valores definidos.

<?php
class User
{
    public string $name;
    public int $age;

    public function __construct(string $name, int $age)
    {
        $this->name = $name;
        $this->age = $age;
    }
}

$ada = new User('Ada', 36);
echo "{$ada->name} is {$ada->age}\n";

Sem construtor, você criaria um objeto vazio e definiria cada propriedade depois, e nada impediria você de esquecer uma. Com um construtor, new User() sem argumentos é um ArgumentCountError.

Promoção de propriedades no construtor

Declarar uma propriedade, listá-la como parâmetro e atribuir $this->name = $name repete cada nome três vezes. Desde o PHP 8.0, uma palavra-chave de visibilidade na frente de um parâmetro do construtor faz as três coisas de uma vez:

<?php
class User
{
    public function __construct(
        public string $name,
        public int $age,
        private string $email = '',
    ) {}

    public function contact(): string
    {
        return $this->email !== '' ? $this->email : 'no email';
    }
}

$u = new User('Grace', 45, 'grace@example.com');
echo $u->name, ', ', $u->age, ', ', $u->contact(), "\n";

$v = new User('Linus', 28);
echo $v->name, ', ', $v->contact(), "\n";

Um parâmetro promovido também pode ser readonly (public readonly string $id), que é o jeito mais curto de escrever um objeto de valor imutável. Você pode misturar parâmetros promovidos e normais, e o corpo do construtor ainda pode conter código que roda depois que as propriedades promovidas foram atribuídas.

Valores padrão e argumentos nomeados

Parâmetros do construtor aceitam padrões como em qualquer função. Parâmetros com padrão vêm depois dos obrigatórios. Com argumentos nomeados (PHP 8.0), quem chama pode ir direto à opção que quer em vez de repetir todos os padrões antes dela:

<?php
class Button
{
    public function __construct(
        public string $label,
        public string $color = 'blue',
        public string $size = 'medium',
        public bool $disabled = false,
    ) {}

    public function render(): string
    {
        $attr = $this->disabled ? ' disabled' : '';
        return "<button class=\"{$this->color} {$this->size}\"{$attr}>{$this->label}</button>";
    }
}

echo (new Button('Save'))->render(), "\n";
echo (new Button('Delete', 'red'))->render(), "\n";
echo (new Button('Wait', disabled: true))->render(), "\n";

Rode: a saída contém HTML, então a aba Page mostra os três botões renderizados, e a aba Output mostra as tags que o PHP imprimiu. Repare nos parênteses em (new Button('Save'))->render(): desde o PHP 8.4 eles são opcionais, mas o PHP 8.3 precisa deles.

Validar argumentos no construtor

Um construtor não pode retornar false ou um código de erro: o que ele retornar é ignorado. Para recusar uma entrada inválida, lance uma exceção. O objeto então nunca é criado, e o resto do programa pode confiar em cada Temperature que recebe.

<?php
class Temperature
{
    public function __construct(public readonly float $celsius)
    {
        if ($celsius < -273.15) {
            throw new InvalidArgumentException("Below absolute zero: $celsius");
        }
    }

    public function fahrenheit(): float
    {
        return $this->celsius * 9 / 5 + 32;
    }
}

echo (new Temperature(21.5))->fahrenheit(), "\n";

try {
    $t = new Temperature(-300);
} catch (InvalidArgumentException $e) {
    echo 'Rejected: ', $e->getMessage(), "\n";
}

A página sobre try catch explica em mais detalhe como capturar essas exceções.

Vários construtores com métodos de fábrica estáticos

O PHP não tem sobrecarga de construtores: uma classe, um __construct. Quando um objeto pode ser montado a partir de entradas diferentes (uma string de data, um array, um timestamp), adicione métodos estáticos com nome que preparam os argumentos e chamam new static(...). Tornar o construtor private obriga todo mundo a passar pelas fábricas.

<?php
class Color
{
    private function __construct(
        public readonly int $r,
        public readonly int $g,
        public readonly int $b,
    ) {}

    public static function fromRgb(int $r, int $g, int $b): static
    {
        return new static($r, $g, $b);
    }

    public static function fromHex(string $hex): static
    {
        [$r, $g, $b] = sscanf(ltrim($hex, '#'), '%02x%02x%02x');
        return new static($r, $g, $b);
    }

    public function css(): string
    {
        return "rgb({$this->r}, {$this->g}, {$this->b})";
    }
}

echo Color::fromRgb(255, 128, 0)->css(), "\n";
echo Color::fromHex('#1e90ff')->css(), "\n";

new Color(1, 2, 3) de fora da classe agora lança um Error ("Call to private Color::__construct() from global scope"). A página sobre static explica por que se usa new static aqui em vez de new self.

Chamar o construtor da classe pai com parent::__construct

Quando uma classe filha define o próprio construtor, o construtor da classe pai não roda sozinho. Chame-o com parent::__construct(...), normalmente primeiro, para que as propriedades da classe pai estejam definidas antes de a filha adicionar as suas:

<?php
class Vehicle
{
    public function __construct(
        protected string $brand,
        protected int $wheels = 4,
    ) {}

    public function describe(): string
    {
        return "{$this->brand} with {$this->wheels} wheels";
    }
}

class Truck extends Vehicle
{
    public function __construct(string $brand, private int $capacityKg)
    {
        parent::__construct($brand, 6);
    }

    public function describe(): string
    {
        return parent::describe() . ", carries {$this->capacityKg} kg";
    }
}

echo (new Vehicle('Fiat'))->describe(), "\n";
echo (new Truck('Volvo', 18000))->describe(), "\n";

Se a filha não tem construtor nenhum, o PHP usa o da classe pai, e new Truck('Volvo') passaria os argumentos direto para Vehicle::__construct. Mais sobre isso em herança.

Esquecer o parent::__construct

Esse erro não gera nenhuma mensagem na linha em que acontece. O construtor da filha roda, as propriedades tipadas da classe pai ficam não inicializadas, e o programa falha depois, onde quer que aconteça a primeira leitura:

<?php
class Model
{
    protected array $attributes;

    public function __construct()
    {
        $this->attributes = ['created' => '2026-03-14'];
    }

    public function get(string $key): mixed
    {
        return array_key_exists($key, $this->attributes) ? $this->attributes[$key] : null;
    }
}

class Post extends Model
{
    public function __construct(public string $title)
    {
        // parent::__construct() is missing
    }
}

$post = new Post('Hello');
try {
    echo $post->get('created'), "\n";
} catch (Error $e) {
    echo $e->getMessage(), "\n";
}

Adicione parent::__construct(); como primeira linha de Post::__construct e rode de novo: ele imprime a data. Um método relacionado, __destruct(), roda quando a última referência a um objeto desaparece ou o script termina. Ele raramente é necessário no código do dia a dia, porque o PHP fecha arquivos e libera memória sozinho no fim de cada requisição.