> ## Documentation Index > Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt > Use this file to discover all available pages before exploring further. # PHP Doc Comment A PHP Doc Comment (commonly referred to as a DocBlock or PHPDoc) is a specialized block comment used to annotate structural elements in PHP code, such as classes, interfaces, traits, methods, functions, and properties. It provides a standardized, machine-readable format for describing the signature, types, and behavioral characteristics of the associated element, which is subsequently parsed by the PHP Reflection API, static analysis tools, and IDEs. A valid DocBlock must begin with a forward slash followed by exactly two asterisks `/**` and end with an asterisk followed by a forward slash `*/`. Every line within the block must be prefixed with an asterisk `*`. ```php theme={"dark"} /** * Short summary of the structural element. * * A more detailed description that can span multiple lines. * It provides technical specifics about the element's behavior. * * @param string $identifier The unique identifier. * @return bool True on success, false on failure. */ function processIdentifier(string $identifier): bool { // ... } ``` ## Structural Components A standard DocBlock is divided into three distinct sections, separated by blank lines (lines containing only the prefix asterisk): 1. **Summary**: A single, concise line summarizing the element. It is terminated by a period or a blank line. 2. **Description**: An optional, multi-line block providing detailed technical information. Markdown is often supported within this section by modern parsers. 3. **Tags**: A collection of meta-data annotations, always prefixed with an `@` symbol, defining specific attributes like parameter types, return types, and exceptions. ## Core Tags and Syntax Tags follow a strict syntax, generally structured as `@tagName [Type] [Variable] [Description]`. * **`@param`**: Defines the expected type and description of a function or method argument. ```php theme={"dark"} /** * @param int $timeout Connection timeout in seconds. */ ``` * **`@return`**: Defines the type and description of the value returned by a function or method. ```php theme={"dark"} /** * @return array The parsed configuration array. */ ``` * **`@var`**: Documents the type of a class property or a local variable. ```php theme={"dark"} /** * @var PDO The active database connection instance. */ private PDO $connection; ``` * **`@throws`**: Indicates the specific exception types that the element might throw during execution. ```php theme={"dark"} /** * @throws InvalidArgumentException If the provided payload is malformed. */ ``` ## Type Expressions PHPDoc allows for complex type definitions that exceed PHP's native runtime type hinting capabilities. These expressions are heavily utilized by static analyzers (like PHPStan or Psalm). * **Primitives**: `int`, `float`, `string`, `bool`, `null`, `mixed`, `void`, `object`, `callable`, `resource`. * **Arrays**: Appending `[]` to a type (e.g., `int[]`, `User[]`). * **Union Types**: Separated by a pipe `|` to indicate multiple acceptable types (e.g., `string|null`, `int|float`). * **Intersection Types**: Separated by an ampersand `&` to indicate an object must satisfy multiple types (e.g., `Countable&Traversable`). * **Generics**: Using angle brackets to define the types of keys and values within collections (e.g., `array`, `Collection`). ## Reflection API Integration At runtime, PHP does not execute or enforce the contents of a DocBlock. However, the PHP engine stores these comments in memory, making them accessible via the Reflection API. Developers can programmatically extract DocBlocks using the `getDocComment()` method on reflection objects. ```php theme={"dark"} $reflection = new ReflectionFunction('processIdentifier'); $docBlock = $reflection->getDocComment(); // $docBlock now contains the raw string of the /** ... */ comment ```

Tired of Poor PHP Skills? Fix That With Deep Grasping! Learn More