PHPDoc annotations

PHPDoc annotations are optional. When present, PHP autodoc uses them with native PHP types to infer types and descriptions. Projects with clear types, such as those checked with PHPStan, often need no autodoc-specific tags.

Supported tags

@deprecated

Use this tag to mark a class properties or array keys as deprecated.

/**
 * @deprecated
 */

@example

/**
 * @example 10.55
 */

@extends

Use @extends to specify generic arguments when extending a generic class. See Generic types for examples.

/**
 * @extends Response<null>
 */

@method

Use this tag to document a method that is not explicitly defined in the class, typically when using dynamic properties.

/**
 * @method bool hasPermission(string $permission)
 */

@mixin

Use this tag to specify that some property types of this class are being delegated to another class. This tag is useful when using Laravel Eloquent API Resources and dynamically accessing the underlying Model propeties with $this->.

/**
 * @mixin User
 */

@param

/**
 * @param {type} $parameterName
 */

@phpstan-type

Visit PHPStan Local type aliases for more info.

/**
 * @phpstan-type TypeAlias {type}
 */

@phpstan-import-type

Visit PHPStan Local type aliases for more info.

/**
 * @phpstan-import-type TypeAlias from DefiningClass
 */

@property

You may specify property type using PHPDoc just above the property definition with @var, however in case you have dynamic properties, you might want to describe the properties in a PHPDoc above class definition using @property.

/**
 * @property {type} $propertyName Description of the property.
 */

@property-description

This tag can be used instead of @property when you want only to define property description without overriding data type.

/**
 * @property-description $propertyName Description of the property.
 */

@property-example

You may define property example using PHPDoc with @example just above the property definition, however in case you have dynamic properties, you may put the example in a PHPDoc above class definition using @property-example.

/**
 * @property-example $propertyName '2025-01-01'
 */

@request / @request-body

This tag can be used to describe the request body type for a route. See Requests section for more info.

/**
 * @request {type}
 */

@request-cookie

See Requests section for details.

/**
 * @request-cookie COOKIE-NAME {description: 'Description of the cookie', deprecated: true}
 */

@request-header

See Requests section for details.

/**
 * @request-header Authorization {required: true, description: 'Authorization header'}
 */

@request-query

See Requests section for details.

/**
 * @request-query filter {type: string[]}
 */

@request-url-param

See Requests section for details.

/**
 * @request-url-param id {description: 'User ID', type: int}
 */

@response

This annotation can be used in a PHPDoc comment to indicate the response type for the route. If the @response tag is present, @return tag will be ignored. This can be useful when there are some manipulations done with the return value and the actual response body is different. If this is a common issue in your project, we recommend using custom extensions.

/**
 * @response {type}
 */

@return

/**
 * @return {type}
 */

Conditional return types are evaluated as union types in the generated documentation.

/**
 * @return (T is int ? string : array<string>)
 */

@template

See example usage in Generic types section.

/**
 * @template T
 */

/**
 * @template TClass of SomeClass
 */

@template-covariant

/**
 * @template-covariant T
 */

@template-contravariant

/**
 * @template-contravariant T
 */

@var

/**
 * @var {type}
 */

/**
 * @var {type} $varName Description of the variable.
 */

@autodoc

Use this tag in your TypeScript code to auto-generate TypeScript types from your PHP code. See TypeScript section for more info.

/**
 * @autodoc App\Enums\SomeEnum
 */

/**
 * @autodoc GET /api/user
 */

@autodoc-ignore

Use this tag prevent enum cases or array keys from appearing in the generated documentation.

/**
 * @autodoc-ignore
 */

Reading descriptions

PHP autodoc reads descriptions for types from text in PHPDoc comments.

/**
 * Description of the next variable.
 */
$theNextVariable = null;

Above class methods or closures that are entrypoints for routes, the first paragraph of the PHPDoc comment is parsed as the operation title (the exported summary), and the rest as the description. How the title and route path are shown in the sidebar is a viewer setting — see ui.sidebar.routes.

/**
 * Title of the operation
 * 
 * Description...
 */
public function create()