Tag reference
@param-out
The @param-out tag documents the type held by a by-reference parameter
(&$arg) after the function or method has returned. A reference parameter’s
own @param describes what it accepts on the way in, but PHP
lets a function overwrite a reference with a completely different, usually
more specific, value on the way out — the classic example being a parameter
that accepts ?string but is guaranteed to hold a non-null string once
the call succeeds. Without a separate tag for the outgoing type, callers and
analyzers are stuck assuming the same type applies in both directions.
Grammar
"@param-out" <Type> <Variable> [ <Description> ]"@phpstan-param-out" <Type> <Variable> [ <Description> ]"@psalm-param-out" <Type> <Variable> [ <Description> ]Examples
/** * @param string|null $error * @param-out string $error */function tryParse(string $input, ?string &$error): bool/** * @param list<int> $matches * @param-out non-empty-list<int> $matches Populated only when the * function returns true. */function findAll(string $pattern, array &$matches): boolNames by platform
- phpstan
@phpstan-param-out- psalm
@psalm-param-out- standard
@param-out
Parsing a @param-out tag produces a ParamOutTag instance (a
TypedVariableTag) exposing:
$type— the documentedTypeNodethe reference holds after the call.$variable— the parameter’s name, without the leading$.
final class ParamOutTag extends TypedVariableTag{ // Own constructor adds nothing; both // properties below are inherited from // TypedVariableTag (and its parent TypedTag):
public readonly TypeNode $type;
public readonly string $variable;}This is the same shape as @param, but describes the outgoing value of a reference parameter rather than the incoming one.
@param-out originated in Psalm and was later adopted by PHPStan; the
bare spelling works in both. See
PHPStan’s coverage
and
Psalm’s @param-out.