União de Tipos no PHP 8: o que é e como usar

Nesse artigo vamos falar sobre união de tipos no PHP, ou também conhecido como union types. Recurso adicionado a linguagem na versão 8 e possui a finalidade de melhorar o uso de tipos.

A comunidade vem trabalhando para melhorar a questão de tipos na linguagem PHP há algum tempo. A versão 7.0 trouxe vários detalhes importantes, como uso de tipos primitivos em parâmetros e retornos, tipagem estrita e melhorou o tratamento de erros para tipos. A versão 7.1 trouxe a opção de definir um parâmetro como anulável e também o retorno void. A 7.4 permitiu a definição de tipos em propriedades e a 8 trouxe como principal novidade a união de tipos.

O que é união de tipos no PHP

Quando trabalhamos com tipo e principalmente quando trabalhamos tipagem estrita, os dados que enviamos para um parâmetro ou que retornamos precisam ser exatamente do tipo declarado e isso pode tornar as coisas um pouco inflexíveis.

A união de tipos permite que você declare mais de um tipo para um parâmetro ou retorno. Veja o exemplo:

function andar(int|string $velocidadeMaxima): string|float {
    return $aceleracao . ' ' . $velocidadeMaxima;
}

No exemplo acima, a função andar pode receber a velocidade máxima como sendo um inteiro ou uma string e pode retornar uma string ou um float.

Sintaxe de uso do Union Type

A Sintaxe para utilização da união de tipos no PHP é muito simples. Basta separar os tipos por pipes |, conforme o exemplo abaixo:

function nomeFuncao(
    tipo1|tipo2|tipoN $nomeparametro1, 
    tipo1|tipo2|tipoN $nomeparametro2,
): tipo1|tipo2|tipoN {
    //código da função
}

Podemos usar dentro da união de tipos no php qualquer tipo válido na linguagem, com algumas exceções que vamos ver abaixo.

Permitindo null na união de tipos

Usando definição de um único tipo no PHP podemos tornar um parâmetro ou retorno anulável usando sinal de interrogação, conforme o exemplo abaixo:

function somar(?int $num1, ?int $num2): ?int
{
    if ($num1 === null || $num2 == null) {
        return null;
    }

    return $num1 + $num2;
}

Já com uso de union type precisamos usar a palavra null:

function somar(int|float|null $num1, int|float|null $num2): int|float|null
{
    if ($num1 === null || $num2 == null) {
        return null;
    }

    return $num1 + $num2;
}

Void na união de tipos

Quando uma função ou método não possui retorno, nós podemos declarar o retorno como void:

function mostrar(string $valor): void
{
    echo $valor;
}

Porém uso de void não é permitido para a união de tipos.

function mostrar(string $valor): void|string
{
    echo $valor;
}

Se tentar usar ele apresentará o seguinte erro:

Fatal error: Void can only be used as a standalone type in xxx on line N

Mixed na união de tipos

Na versão 8.0 o PHP ganhou a anotação de tipo mixed. Esse tipo já existe na documentação da linguagem, porém não existia como tipo realmente. Ele indica que um parâmetro ou retorno pode ser de qualquer tipo válido na linguagem. Veja o exemplo:

function mostrar(mixed $valor): void
{
    echo $valor;
}

O parâmetro $valor pode ser de qualquer tipo válido, consequentemente não faz sentido usar ele junto com outros tipos no union type:

function mostrar(string|mixed $valor): void
{
    echo $valor;
}

O código acima apresentará o seguinte erro:

Fatal error: Type mixed can only be used as a standalone type in xxx on line N

Indicador false

Ao usar união de tipos no PHP (union Type), podemos usar a palavra reservada false para indicar que uma função retornará um determinado tipo ou false, veja o exemplo abaixo:

class Carro {
    protected int $velocidadeAtual = 0; 

    public function estaAndando(): int|false
    {
        if ($this->velocidadeAtual > 0) {
            return $this->velocidadeAtual;
        }

        return false;
    }
}

A palavra false não pode ser usado junto com o tipo bool e também vale ressaltar que a palavra true não pode ser usada.

Considerações Finais

O recurso de união de tipos no PHP é algo extremamente interessante, principalmente para ajudar na migração gradual de aplicações que não utilizam tipos estritos para utilização de tipos estritos. Ela também garante um nível de leitura maior para aplicações que não adotaram o uso de tipo estrito, uma vez que é possível usar union type para declarar os tipos válidos de entrada e saída sem estar preso a tipagem estrita.