Работа с документацией PHP на практике

Расширенные примеры работы с документацией PHP

Пример 1: Создание функции с PHPDoc и получение её документации через Reflection

/**
 * Генерирует случайную строку заданной длины
 *
 * @param int $length Длина строки (по умолчанию 10)
 * @param string $characters Символы для генерации (по умолчанию буквы и цифры)
 * @return string Случайная строка
 * @throws InvalidArgumentException если длина <= 0
 */
function randomString(int $length = 10, string $characters = 'abcdefghijklmnopqrstuvwxyz0123456789'): string {
    if ($length <= 0) {
        throw new InvalidArgumentException('Length must be positive');
    }
    $result = '';
    $max = strlen($characters) - 1;
    for ($i = 0; $i < $length; $i++) {
        $result .= $characters[random_int(0, $max)];
    }
    return $result;
}
// Использование ReflectionFunction
$ref = new ReflectionFunction('randomString');
echo "Документация:\n" . $ref->getDocComment() . "\n";
echo "Параметры:\n";
foreach ($ref->getParameters() as $p) {
    echo "  {$p->getName()}: {$p->getType()} " . ($p->isOptional() ? '(optional)' : '(required)') . "\n";
}
echo "Возвращаемый тип: " . $ref->getReturnType() . "\n";

Документация:
/**
 * Генерирует случайную строку заданной длины
 *
 * @param int $length Длина строки (по умолчанию 10)
 * @param string $characters Символы для генерации (по умолчанию буквы и цифры)
 * @return string Случайная строка
 * @throws InvalidArgumentException если длина <= 0
 */
Параметры:
  length: int (optional)
  characters: string (optional)
Возвращаемый тип: string

Пример 2: Генерация документации с помощью phpDocumentor

# Установка через Composer
composer require --dev phpdocumentor/phpdocumentor
# Генерация HTML-документации для директории src
vendor/bin/phpdoc -d src -t docs

Пояснение: phpdoc анализирует PHPDoc-блоки во всех файлах директории src и создаёт структурированную документацию в папке docs. В результате получается статический сайт с описанием классов, методов и функций.

Пример 3: Получение документации метода класса через ReflectionMethod

class Calculator {
    /**
     * Складывает два числа
     * @param float $a Первое число
     * @param float $b Второе число
     * @return float Сумма
     */
    public function add(float $a, float $b): float {
        return $a + $b;
    }
}
$refMethod = new ReflectionMethod('Calculator', 'add');
echo $refMethod->getDocComment();

/**
     * Складывает два числа
     * @param float $a Первое число
     * @param float $b Второе число
     * @return float Сумма
     */

Пример 4: Проверка версии PHP, в которой появилась функция

if (function_exists('array_combine')) {
    $ref = new ReflectionFunction('array_combine');
    $ext = $ref->getExtension();
    if ($ext) {
        echo "Функция array_combine доступна с версии PHP " . $ext->getVersion() . "\n";
    }
}

Функция array_combine доступна с версии PHP 5.0.0

Пример 5: Использование php.net/API (неофициальное, демонстрация парсинга)

Можно извлечь описание функции через загрузку страницы документации и регулярные выражения, но это нестабильно. Вместо этого рекомендуется использовать официальный зеркальный сервер php.net/manual/ru/ с последующей обработкой через DOMDocument. Пример:

$url = 'https://www.php.net/manual/ru/function.str-replace.php';
$html = file_get_contents($url);
$dom = new DOMDocument();
@$dom->loadHTML($html);
$xpath = new DOMXPath($dom);
$description = $xpath->query('//div[@class="refsect1 description"]/p')->item(0);
if ($description) {
    echo 'Описание: ' . $description->textContent;
}

Пояснение: скрипт загружает страницу, находит блок с классом refsect1 description и извлекает первый абзац. Этот способ зависит от структуры HTML, которая может измениться.