Operador de coalescência nula PHP: ?? e ??=

?? retorna o valor da esquerda se ele existir e não for null, senão o valor da direita: $name = $_GET['name'] ?? 'Guest';. Ao contrário de ler a chave diretamente, ele nunca avisa quando a variável ou a chave do array está ausente.

<?php
$name = $_GET["name"] ?? "Guest";
$lang = $_GET["lang"] ?? "en";

echo "<p>Hello, " . htmlspecialchars($name) . " (language: " . htmlspecialchars($lang) . ")</p>";
echo '<p><a href="?name=Ada">?name=Ada</a> | <a href="?name=Linus&lang=fi">?name=Linus&amp;lang=fi</a> | <a href="?">no query</a></p>';

Na primeira execução não há query string, então os dois padrões são usados. Clique num link da aba Page e o script roda de novo com $_GET preenchido. Ler $_GET["name"] sem ?? nessa primeira execução imprimiria Warning: Undefined array key "name" numa configuração normal do PHP. Mais sobre dados da requisição na página sobre $_GET e$_POST.

?? é uma verificação isset() abreviada

$a ?? $b significa exatamente isset($a) ? $a : $b. Funciona com variáveis, chaves de array em qualquer profundidade e propriedades de objetos, e para na primeira peça ausente sem reclamar.

<?php
$config = [
    "db" => ["host" => "localhost", "port" => null],
];

// The long way
$host = isset($config["db"]["host"]) ? $config["db"]["host"] : "127.0.0.1";

// The same with ??
$host = $config["db"]["host"] ?? "127.0.0.1";
$port = $config["db"]["port"] ?? 3306;        // null, so default
$user = $config["db"]["user"] ?? "root";      // missing key
$cache = $config["cache"]["ttl"] ?? 60;       // missing parent key too
$debug = $undefinedVariable ?? false;         // missing variable

var_dump($host, $port, $user, $cache, $debug);

A verificação é a mesma que o isset faz, então uma chave que existe com o valor null também recebe o padrão.

Encadear ?? para tentar várias fontes

?? é associativo à direita e você pode encadear quantos quiser. O PHP retorna o primeiro operando que está definido e não é null.

<?php
$fromQuery = null;
$fromCookie = null;
$fromProfile = "fr";

$lang = $fromQuery ?? $fromCookie ?? $fromProfile ?? "en";
echo $lang, "\n";

$settings = ["theme" => null];
$theme = $settings["theme"] ?? $settings["defaultTheme"] ?? "light";
echo $theme, "\n";

??= só atribui quando é null

$a ??= $b guarda $b em $a só quando $a não está definido ou é null. É o jeito mais curto de preencher padrões ou de calcular algo uma vez e reutilizar.

<?php
$options = ["color" => "red", "size" => null];

$options["color"] ??= "blue";   // already set, unchanged
$options["size"] ??= "M";       // null, so assigned
$options["qty"] ??= 1;          // missing, so assigned
print_r($options);

// Compute once, reuse afterwards
function slowSquare(int $n): int {
    echo "computing $n\n";
    return $n * $n;
}
$cache = [];
foreach ([4, 4, 7, 4] as $n) {
    $cache[$n] ??= slowSquare($n);
    echo "$n squared is {$cache[$n]}\n";
}

O lado direito do ??= só é avaliado quando a atribuição acontece, e é por isso que computing 4 aparece uma vez.

?? ou ?: (ternário curto)

?? testa null. ?: testa se o valor é verdadeiro. Com valores como 0, "" e "0" eles dão respostas diferentes:

<?php
$inputs = ["qty" => "0", "note" => "", "coupon" => null];

foreach (["qty", "note", "coupon", "missing"] as $key) {
    $viaCoalesce = $inputs[$key] ?? "default";
    $viaElvis = ($inputs[$key] ?? null) ?: "default";
    printf("%-8s ?? => %-10s ?: => %s\n",
        $key, var_export($viaCoalesce, true), var_export($viaElvis, true));
}

Uma quantidade "0" é uma entrada válida: ?? a mantém, ?: a substitui. ?: sozinho avisaria sobre a chave ausente, e é por isso que o bloco o envolve como ($inputs[$key] ?? null) ?: .... A página sobre o operador ternário explica o ?: em si.

O operador nullsafe ?->

?-> é a versão para objetos da mesma ideia, adicionada no PHP 8. Se o objeto à esquerda for null, a cadeia inteira para e retorna null em vez de lançar um Error como Call to a member function getAddress() on null. Coloque ?? no fim para ter um padrão.

<?php
class Address {
    public function __construct(public string $city) {}
}

class User {
    public function __construct(public ?Address $address = null) {}
    public function getAddress(): ?Address { return $this->address; }
}

function findUser(int $id): ?User {
    return match ($id) {
        1 => new User(new Address("Paris")),
        2 => new User(),
        default => null,
    };
}

foreach ([1, 2, 3] as $id) {
    $city = findUser($id)?->getAddress()?->city ?? "unknown";
    echo "user $id: $city\n";
}

O usuário 2 existe, mas não tem endereço, e o usuário 3 nem existe. Os dois chegam ao padrão ?? "unknown" sem erro.

Erro comum: ?? tem precedência baixa

?? tem ligação mais fraca que . e os operadores aritméticos. Então em "Count: " . $count ?? 0, o PHP primeiro monta a string "Count: " . $count, que nunca é null, e o padrão nunca é usado.

<?php
$count = null;

echo "Count: " . $count ?? 0, "\n";     // the ?? applies to the whole string
echo "Count: " . ($count ?? 0), "\n";   // what was meant

Coloque a expressão com ?? entre parênteses sempre que ela estiver dentro de uma expressão maior.