Method Documentation in PHP

In PHP, documenting methods (functions within classes) is very important for understanding their usage, purpose, parameters, return values, and any other relevant information. The most common way to document methods in PHP is by using PHPDoc, which is a standardized format for documenting PHP code. PHPDoc uses special tags to provide information about the method.

Let’s see below example code:

<?php
/**
 * Class MySimpleClass
 */
class MySimpleClass {
    /**
     * Adds two numbers together.
     *
     * This method takes two numbers as input and returns their sum.
     *
     * @param int $num1 The first number.
     * @param int $num2 The second number.
     * @return int The sum of the two numbers.
     */
    public function addNumbers($num1, $num2) {
        return $num1 + $num2;
    }
}
?>

Let’s break down the PHPDoc comments used in the above example of a simple PHP class called MySimpleClass:

• /** indicates starting of a PHPDoc comment block.
• * is used for each line within the comment block.
• @param is used to describe each parameter of the method  which need to be passed. It includes the parameter type and a description.
• @return describes the return value type of the method, including its type and a description.

Example code 2:

This one is a scenario. Here’s a PHPDoc block for a method that takes an array as the first parameter, an integer as the second parameter, and returns an array of integers:

/**
 * Calculates the product of each element in the input array with the given integer.
 *
 * This method multiplies each element in the input array by the provided integer
 * and returns an array containing the products.
 *
 * @param array $inputArray The input array containing integers.
 * @param int $multiplier The integer to multiply each element in the input array.
 * @return array An array containing the products of each element in the input array multiplied by the multiplier.
 */
public function multiplyArrayElements(array $inputArray, int $multiplier): array {
    $resultArray = [];

    foreach ($inputArray as $element) {
        $resultArray[] = $element * $multiplier;
    }

    return $resultArray;
}

Let’s break down the PHPDoc comments used in the above example of a simple PHP method called multiplyArrayElements():

• /** indicates starting of a PHPDoc comment block.
• * is used for each line within the comment block.
• First three or four lines explains what this method does.
• @param (first one) is used to describe first parameter of the method  which need to be passed also be type Array.
• @param (second one) is used to describe second parameter of the method  which need to be passed also be type Integer.
• @return describes the return value type of the method, including its type and a description. In this case an Array.

Here are some common PHPDoc tags used to document methods:

• @param: Describes a parameter of the method.
• @return: Describes the return value of the method.
• @throws: Describes exceptions that the method may throw.
• @var: Describes the type of a variable.
• @see: Refers to other elements in the code, such as classes, methods, or variables.

Example 3 (with @var, @throws and @see):

Lets see another example with @var, @throws and @see

Here’s another example of a PHPDoc block for a method that performs a specific operation on an array and throws an exception if certain conditions are not met. It also includes @var and @see tags:

/**
 * Removes duplicate elements from the input array and returns a new array.
 *
 * This method removes duplicate elements from the input array while preserving the keys.
 * If the input array is not an array or is empty, it throws an InvalidArgumentException.
 *
 * @param array $inputArray The input array to remove duplicates from.
 * @return array An array containing unique elements from the input array.
 *
 * @throws InvalidArgumentException If the input is not an array or is empty.
 *
 * @var int $elementCount Total number of elements in the input array.
 * @see array_unique() PHP function for removing duplicate elements from an array.
 */
public function removeDuplicates(array $inputArray): array {
    $elementCount = count($inputArray);

    if ($elementCount === 0) {
        throw new InvalidArgumentException("Input array cannot be empty.");
    }

    return array_values(array_unique($inputArray));
}

Using PHPDoc comments makes our code more readable and understandable, especially for other developers who might work with your code in the future. Additionally, various tools and IDEs can parse PHPDoc comments to provide documentation popups and autocompletion, making the development experience smooth and fast.

That’s all for today. See you in next one.

Check Out More Resources:

Articles:
Website: https://laravelplug.com/
YouTube Channel: https://www.youtube.com/channel/UCnTxncHQcBSNs4RCuhWgF-A?sub_confirmation=1
WordPress Playlist: https://www.youtube.com/watch?v=8VvXzFAFwQU&list=PLVoVZqAh8dTLHZ51egvEU7dsOrRCSIMWx
Tools Playlist: https://www.youtube.com/watch?v=gTQoUn3BQkM&list=PLVoVZqAh8dTK-DWHBGWOEEvzvPQrgFne-

WordPress Tutorials: https://laravelplug.com/category/wordpress/
Laravel Tutorials: https://laravelplug.com/category/laravel/
PHP Tutorials: https://laravelplug.com/category/php/
SQL Tutorials: https://laravelplug.com/category/sql/
Various Tips: https://laravelplug.com/category/tips/
Useful Tools: https://laravelplug.com/category/tools/

Socials:

Twitter: https://twitter.com/LaravelPlug
Pinterest: https://www.pinterest.com/LaravelPlugCom/
Facebook: https://www.facebook.com/groups/1020759861842360
Mail: info@laravelplug.com

#PHP #DocBloc #PHPDock

That’s All. Feel free to knock me. Thanks.