@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.

"@param-out" <Type> <Variable> [ <Description> ]

Parsing a @param-out tag produces a TypedVariableTag instance exposing:

$type — the documented TypeNode the 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 TypeNode $type {
        get => $this->statement->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.

05 July 2026