Sfortunatamente, non è possibile definire tipi di array espliciti come fanno altri linguaggi di programmazione come Java:

List<User> users = new ArrayList<>();

Si spera che alcuni strumenti come PHPStan o Psalm ci aiutino ad analizzare il codice in modo statico, il che significa che non vengono eseguiti ma controllano il codice per incoerenze in base ai commenti PHP.

Esistono 3 modi diversi per definire il tipo di elementi in un array PHP:

1. Modo legacy:User[]
2. Forma elenco: array<int,mixed>&list<mixed>
3. Forma dell'oggetto:array{0:int, foo:?string, bar:mixed}

Questo è un modo alla moda per definire un elenco di elementi di un certo tipo, il problema è che diventa ambiguo e i client che utilizzano questo tipo di elenco non possono sapere se le chiavi sono numeri interi, float o stringhe.
Inoltre, gli analizzatori statici non falliranno se si tenta di ottenere un elemento per chiave con un tipo errato, in questi scenari suggerirei di utilizzare array<int,mixed>.

Alla fine, più esplicito è, meglio è.

/** @var User[] $users */
$users = [ ... ];

# Are keys autoincremental integers, random numbers, maybe strings... ?
$firstUser = $users[ ? ];

# Static analyzers won't complain if you use an incorrect type 

Usiamo le liste quando abbiamo un array di elementi con lo stesso tipo.
Per fare ciò, usiamo la sintassi del diamante per dichiarare i tipi di chiave e il valore: array<int,mixed>. C'è una scorciatoia molto utile quando la chiave è un numero intero incrementale automatico: list<mixed>.

/** @var array<string,User> $users */
$users = [
    'jesus' => new User('Jesus Valera'),
    'chema' => new User('Chema Valera'),
];

$userJesus = $users['jesus'];
$userChema = $users['chema'];

$users[0]; # ERROR: "Offset 0 does not exist on array<string, User>"

---

/** @var list<User> $users */
$users = [ ... ];

$firstUser = reset($users);
$lastUser = end($users);

Usiamo la forma dell'oggetto quando l'array non è una raccolta di oggetti ma una mappa che contiene informazioni.
Per fare ciò, usiamo la sintassi delle parentesi graffe e definiamo il nome della chiave e il tipo, possiamo dividere per virgole se ci sono più elementi: .array{foo:int, bar:string}

/** @var array{id:int, birthdate: DateTimeImmutable} */
$additionalInfo = [ ... ];

$id = $additionalInfo['id']; # int
$birthdate = $additionalInfo['birthdate']; # DateTimeImmutable

final class User
{
    /** @var list<Comment> */
    public readonly array $comments;

    /** @var array{id:int, birthdate: DateTimeImmutable} */
    public readonly array $additionalInfo;
}

Naturalmente, è possibile rappresentare qualsiasi struttura di array complessa in PHP con questi commenti PHP. Esempio:

/**
 * @var list<
 *   array{
 *     uuid?: string,
 *     content: array{name: string, foo: ?stdClass},
 *   }
 * > $array
 */
$array = [
    0 => [
        'uuid' => 'XXXX-XXX-XXX-XXXX',
        'content' => [
            'name' => 'str',
            'foo' => null,
        ],
    ],
    1 => [
        'content' => [
            'name' => 'str',
            'foo' => new stdClass(),
        ],
    ],
    // ...
];

Risorse:

• Salmo | Forme di matrice
• PHP Stan | Tipi PHPDoc