Skip to main content

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.

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 *. 
/**
 * 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.
/**
 * @param int $timeout Connection timeout in seconds.
 */
  • @return: Defines the type and description of the value returned by a function or method.
/**
 * @return array<string, mixed> The parsed configuration array.
 */
  • @var: Documents the type of a class property or a local variable.
/**
 * @var PDO The active database connection instance.
 */
private PDO $connection;
  • @throws: Indicates the specific exception types that the element might throw during execution.
/**
 * @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<int, string>, Collection<User>).

​
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. 
$reflection = new ReflectionFunction('processIdentifier');
$docBlock = $reflection->getDocComment();

// $docBlock now contains the raw string of the /** ... */ comment
Master PHP with Deep Grasping Methodology!Learn More