Skip to content

PHP Documentary Comments (PHPDoc)#

PHPDoc is a standard way of documenting and annotating the PHP code. It is a well-known format of block comments prefixed with ` function foo($a) { ... } 

In this case it would be placed right above the function declaration in the PHP code. The editor would provide a short description whenever it provides `foo` code completion, and it would treat the function as it accepts one argument of type array of integers, and returning a value of type integer.

## Generate PHPDoc

The PHP Editor automatically generates corresponding PHPDoc stub upon typing `
function a_dummy_function() { ... }

Example of a function that won't be listed in IntelliSense.

Type Annotations#

There are several PHPDoc tags that may be used to annotate the function parameters, function return value, property type, constant type, or a variable type. The standard PHPDoc tags are the following:

  • @param: specifies the parameter type and description in the form: @param (type) ($name) (description).
  • @return: provides information about the return value in the form: @return (type) (description).
  • @var: allows to annotate properties, constants, class constants: @var (type) (description).
  • @global: annotates global variables within the current scope: @global (type) ($name) (description).

In order to annotate a local variable, the @var tag is used:

    $x = do_something();

The annotation can be placed on a single line as well:

Or the variable name can be omitted completely if it can be inferred from the statement below it:

    $x = do_something(); // <-- the editor will know that $x will be MyClass.

Generics#

The editor understands generic type annotations (also known as templates).

The class/function with template type arguments is annotated with @template PHPDoc tag, optionaly specifying the template type constrain:

templated class annotation

Notice, the tooltip for class MyClass shows the template arguments as well. The type constrain Traversable is used whenever the type U is not bound (whenever the editor does not know the actual assigned type), so it can provide code analytics and code completion.

In order to use the template type arguments, specify them as any other type within PHPDoc.

php generic instance

Notice, the editor will substitute T with ArrayObject and U with string. This results in working code completion, and the editor will properly provides completion after foo() which is expected to return either ArrayObject or array<string>.

Psalm/PHPStan#

The 3rd party code linters like Psalm or PHPStan introduce extended PHPDoc type annotations. Those are supported by the PHP Tools Editor as well.

Types can be specified in various forms including:

  • callable(mixed...):(Option<T>)
  • array<int, mixed>
  • array-key
  • non-empty-string
  • class-string
  • class-string<T>

PHPDoc tags may be prefixed with @psalm- or @phpstan-. Such tags are handled as well.

The editor respects those annotations but may not take the full advantage of them (yet).

Class Annotations#

There are several PHPDoc tag specific to class/interface declartion.

  • @extends allows to describe the base class name including its generic type arguments. Example: @extends ArrayObject<int, MyUser>
  • @implements allows to describe an implemented interface with its generic type arguments. Example: @implements Iterable<int>
  • @use is used above a trait use to describe its generic type arguments.
  • @method declares a method in case the class provides dynamic methods through magic __call() function. This information is used by the code completion to provide this additional method in the list.
  • @property similarly to @method allows to define a dynamic property.
  • @mixin tells the editor to include members of another type (aka mixin) into this class.

Code Validation#

The PHPDoc is validated for valid type names, valid tag names, and common typos.

phpdoc typo suggestion

For the quick fixes there are same rules as for the PHP code; invalid type names may get completed namespace. In case the type name is ambiguous or needs to get fully qualified, the \ prefix may get inserted by the code completion or by the quick fix.

Formatting#

The PHPDoc comment block is formatted according to the statement below which it corresponds with. The block is formatted according to standards, indented.

See Also#