Doc Blocks
Don’t use docblocks for methods and functions that can be fully type hinted (unless you need a description).
Only add a description when it provides more context than the method signature itself (Visual noise is real). Use full sentences for descriptions.
Good example: reveal what your arrays and collections contain:
PHP
// GOOD
final class Foo
{
/** @var list<string> */
private array $urls;
/** @var \Illuminate\Support\Collection<int, \App\Models\User> */
private Collection $users;
}
// BAD
final class Foo
{
private array $urls;
private Collection $users;
}
Make inheritance explicit using the @inheritDoc tag
Because inheritance is implicit, it may happen that it is not necessary to include a PHPDoc for an element. To avoid any confusion, please always use the @inheritDoc tag for classes and methods.
Don’t use @inheritDoc for class properties, instead copy the docblock from the parent class or interface.
PHP
// GOOD
final class Tag extends BaseTag
{
/** @var list<string> The attributes that are mass assignable. */
protected $fillable = [
'name',
];
}
// BAD
final class Tag extends BaseTag
{
/** @inheritDoc */
protected $fillable = [
'name',
];
}
Describe traversable types
Lists / Ordered maps
PHP
/** @return Type[] */
/** @return array<int, Type> */
/** @return array<TKey, TValue> */
/** @return Collection<TKey, TValue> */
Key-value store You may know it as a structure / dictionary / hash / map / hashmap, what is the same.
PHP
/** @return array{foo: string, bar: int} */
/** @return array{optional?: string, bar: int} */