Skip to content

Tag reference

@throws

PHP has no native syntax at all for declaring what exceptions a function might throw, so @throws is the only way to document it. Listing the \Throwable types a function can raise lets callers know what is worth catching, and lets a static analyzer flag a catch block that can never be reached or a thrown type that was never declared.

Grammar

"@phpstan-throws" <Type> [ <Description> ]
"@throws" <Type> [ <Description> ]
"@throw" <Type> [ <Description> ]

Examples

Documenting the exceptions raised by a single method, each with its own tag.
/**
* @throws NotFoundException If the user does not exist.
* @throws AccessDeniedException If the current user lacks
* permission.
*/
function fetchUser(int $id): User
{
// ...
}

Names by platform

phpstan
@phpstan-throws
standard
@throws@throw

Parsing a @throws tag produces a tag exposing $type — the parsed TypeNode naming the thrown type — plus the $name and $description every tag has.

abstract class TypedTag extends Tag
{
public readonly TypeNode $type;
public function __construct(
string $name,
protected readonly TypeReference $statement,
?DescriptionInterface $description = null,
) {
parent::__construct($name, $description);
}
}
final class ThrowsTag extends TypedTag {}

The misspelling @throw is also recognized — a fairly common typo that this component also recognizes and parses into the same kind of tag as @throws.

Defined by the PSR-19 draft §5.15 and phpDocumentor’s own @throws reference.