At its core, PHP provides many ways to make your code extremely easy to write and maintain, but it also provides many ways to shoot yourself in the foot. Over the 7.x and 8.x releases, the core developers have added features like return types and parameter types that make it easy for our IDEs and Static Code Analysis tools to find bugs before your customers do, but they’re limited by the information that PHP can provide them.

DocBlocks can give you a way to boost your tools a little more so you can craft code that is more easily maintained and provide tools to help others understand your code so they can make future changes more easily.

What are DocBlocks?

At a very basic level, DocBlocks are a specially formatted comment in PHP that provides structured documentation for your code. They are written using a specific syntax and are placed above classes, methods, functions, properties, and other code elements. DocBlocks contain tags that describe the details of the coding, including things like the purpose, parameters, and return values.

DocBlocks start with /** and end with */. They look like a block comment that starts with a /* but that extra * is what causes your tools to treat them as a DocBlock, and they won’t work without them.

A DocBlock consists of two pieces. The first is an optional description that explains what the code does. The second is zero or more tags and annotations that provide additional information about our code.

Why are DocBlocks Important?

DocBlocks provide several benefits to your code, including:

1. Code Documentation: DocBlocks make your code self-documenting, helping other developers (and your future self) understand the purpose and usage of your code.
2. Type Hinting: DocBlocks can specify types for parameters, return values, and properties, which is especially useful in PHP, where type declarations are not always available for things like arrays and mixed types.
3. IDE Support: Modern IDEs use DocBlocks to provide autocompletion, type hints, and inline documentation, improving developer productivity.
4. Documentation: Tools like phpDocumentor can generate documentation from DocBlocks, making it easier to share and maintain documentation.
5. Code Quality: Tools like PHPStan can use DocBlocks to find bugs while we’re writing it and not in production

That can be a little abstract, so let’s look at an example.

add() Function Example

Let’s say you wrote a function that adds two numbers together.

function add($a, $b)
{
    return $a + $b;
}

I’m hoping that every developer would easily understand what’s going on here, but you’re going to add a DocBlock to this so we can communicate your intent for this function.

The first step is to add the special DocBlock comment structure to indicate that you’re creating a DocBlock.

/**
 */
function add($a, $b)
{
    return $a + $b;
}

Next, you’re going to add our description.

/**
 * Adds two numbers and returns the result.
 */
function add($a, $b)
{
    return $a + $b;
}

Then you’re going to start adding your tags. In this case, you’re going to start with the @param tag which allows you to define the type of each parameter to the function as well as an option description.

/**
 * Adds two numbers and returns the result.
 * 
 * @param int $a The first number
 * @param int $b The second number
 */
function add($a, $b)
{
    return $a + $b;
}

Next, you’re going to add the @return tag which allows us to define the return type of the function as well as an optional description.

/**
 * Adds two numbers and returns the result.
 * 
 * @param int $a The first number
 * @param int $b The second number
 * @return int The sum of the parameters
 */
function add($a, $b)
{
    return $a + $b;
}

Now when you type out the add() function PhpStorm will show us what each of the parameters is used for and you can hover over the function to see all of the documentation you added.

img1

I should point out that if you’re using a version of PHP that supports return types and parameter types (and you should all be using these versions by now) you can and should add them. PHP doesn’t look at the DocBlock for type safety but it does look at the types you define so you can find bugs sooner.

/**
 * Adds two numbers and returns the result.
 *
 * @param int $a The first number.
 * @param int $b The second number.
 * @return int The sum of $a and $b.
 */
function add(int $a, int $b): int {
    return $a + $b;
}

array Parameters/Return Values

Now that we have the basics down we can discuss one of my favorite features of DocBlocks and that’s defining the structure of our arrays.

With PHP, your code can define the fact that you’re sending an array into a function and getting an array back, but you really can’t tell without looking at the function exactly what you’re expecting the structure to be, which can slow you down.

The filterData function below expects an array as a parameter, which filters out the array and spits out a new array. The challenging part is that you can’t tell what it’s filtering on.

function filterData(array $data): array
{
    foreach ($data as $row) {
        // ...
    }
}

You can use DocBlocks to define that the parameter and return types are an array of arrays with a string key to an int, string, or boolean value.

/**
 * @param array<array<string, int|string|boolean>> $data
 * @return array<array<string, int|string|boolean>> $data
 */
function filterData(array $data): array
{
    foreach ($data as $row) {
        // ...
    }
}

This is still lacking a little detail so you can define the shape of the array using the following structure to define what the keys are and if those keys have a specific type.

/**
 * @param array<array{
 *      id: int,
 *      state_name: string,
 *      active_state: boolean
 * }> $data
 * @return array<array{
 *      id: int,
 *      state_name: string,
 *      active_state: boolean
 * }>
 */
function filterData(array $data): array
{
    foreach ($data as $row) {
        // ...
    }
}

The truly amazing part of this is that our IDE can now show you exactly what keys are in the array as you type, and static code analysis tools will let you know when you forget a key or mistype one.

img2

Dynamic Properties

One of the more challenging parts about using Laravel is that PHP doesn’t know what columns exist within the model because of Eloquent’s use of Magic Methods. DocBlocks provide the @property, @property-read, and @method tags that can be used to help fill in those gaps.

/**
 * App\Models\User
 *
 * @property int $id
 * @property-read int|null $tokens_count
 * @method static Builder<static>|User whereId($value)
 */
class User extends Model
{

}

If you are using Laravel check out the laravel-ide-helper project which can be used to generate these DocBlock entries based on the project’s database structure which will save a ton of time and accidental typos.

More

This article just breaks the surface of what we can use DocBlocks for. In addition to the tags we’ve listed in this article, there are “official” tags like @todo, @deprecated, and @var as well as package-specific tags so we really can’t go over all of them. I would suggest you look at your packages and determine if there are tags you can use to help yourself and your team.

We can also use DocBlocks to feed our source code to tools that can find bugs and generate documentation based on our code.

What You Need to Know

1. DocBlocks are a type of comment that provides structural documentation for your code
2. Helps our IDEs and Static Code Analysis tools find issues fast
3. Can be added easily