PHP: полный мануал с примерами, функциями и ООП

Пауза нужна текущему процессу: что делает sleep

Поставщик разрешает ограниченное число запросов. Иногда программе нужно подождать перед следующим действием. sleep принимает число секунд и блокирует текущий процесс: следующая строка выполнится после ожидания. Сам по себе sleep не знает лимита поставщика.

Что уже пригодится. циклы, HTTP-клиент

sleep(1) — ждать примерно секунду; usleep(100000) — примерно 100 миллисекунд. Это не таймер браузера и не запуск параллельной работы.

<?php
declare(strict_types=1);

echo "Перед паузой\n";
$seconds = 0;
sleep($seconds);
echo "После паузы\n";

Перед паузой
После паузы

Следующая ступень. После этого рассматриваем Retry-After, повторные попытки и несколько работников. Долгое ожидание в запросе веб-страницы занимает рабочий процесс; для таких задач нужна очередь.

Почему пауза иногда необходима

Поставщик разрешает два запроса в секунду. Импорт из тысячи товаров без ограничения частоты быстро получает 429 и может быть заблокирован. Пауза между запросами помогает одному последовательному CLI-скрипту соблюдать простой темп. sleep принимает секунды, usleep — микросекунды, time_nanosleep — секунды и наносекунды. Более мелкая единица не обещает такую же точность планировщика: фактическая пауза может быть длиннее.

Сон приостанавливает текущий поток выполнения. Пока HTTP-обработчик спит, PHP-FPM-воркер занят; при удерживаемой сессии или транзакции заняты также блокировки. Поэтому длительную рассылку или импорт не запускают прямо из формы. Форма создаёт задание и показывает его состояние, а CLI-воркер выполняет работу. Для длинной задержки лучше записать available_at и освободить воркер, чем держать его спящим час.

Пауза каждого из десяти процессов по 500 мс не ограничит их суммарный поток двумя запросами в секунду. Общая квота требует координации: очередь с нужной параллельностью либо атомарный распределённый лимитер. Лимиты бывают по аккаунту, токену, endpoint и IP; читайте контракт провайдера. Не выдумывайте универсальную частоту для всех API.

Повтор ограничен числом попыток и временем

<?php
declare(strict_types=1);

function fetchWithRetry(callable $send, callable $wait): string {
    $spent = 0;
    for ($attempt=0; $attempt<3; $attempt++) {
        $response = $send();
        if ($response['status'] === 200) return $response['body'];
        if (!in_array($response['status'],[429,503],true) || $attempt === 2) {
            throw new RuntimeException('retry-stopped');
        }
        $seconds = $response['retryAfter'] ?? (2 ** $attempt);
        if (!is_int($seconds) || $seconds < 0 || $seconds > 10 || $spent+$seconds > 10) {
            throw new RuntimeException('retry-budget');
        }
        $wait($seconds);
        $spent += $seconds;
    }
    throw new LogicException('Unreachable');
}
$responses = [['status'=>429,'retryAfter'=>2],['status'=>503],['status'=>200,'body'=>'ready']];
$send = static function () use (&$responses): array { return array_shift($responses); };
$wait = static function (int $seconds): void { echo "wait:$seconds
"; };
echo fetchWithRetry($send,$wait)."
";

wait:2
wait:2
ready

Retry-After, jitter и неопределённый результат

Retry-After бывает количеством секунд или HTTP-датой. Число нужно проверять как неотрицательное целое с разумным пределом; дату разбирают по HTTP-формату и сравнивают с текущим временем UTC. Если сервер требует ждать дольше допустимого бюджета задачи, её откладывают, а не уменьшают паузу и немедленно снова нагружают сервис. При отсутствии заголовка обычно выбирают экспоненциальную задержку с верхним пределом.

Jitter добавляет случайность, чтобы тысячи клиентов не проснулись одновременно. Он должен сохранять смысл минимальной задержки, указанной сервером. Для воспроизводимого теста генератор случайности и часы передают зависимостями. Нельзя ждать точного числа миллисекунд в тесте: проверяют выбранную политику, верхние границы и количество попыток.

Безопасность повтора зависит от операции. GET обычно можно повторять, если он действительно только читает. POST создания платежа после таймаута имеет неизвестный результат: сервер мог выполнить операцию, а ответ потерялся. Для него нужен ключ идемпотентности и протокол получения состояния. Не повторяйте 400/401/403 как временный сбой, если документация явно не говорит обратного.

<?php
declare(strict_types=1);

function delaySeconds(int $attempt, ?int $retryAfter, int $jitter): int {
    if ($attempt < 0 || $attempt > 6 || $jitter < 0 || $jitter > 2) {
        throw new InvalidArgumentException('invalid-policy-input');
    }
    if ($retryAfter !== null) {
        if ($retryAfter < 0 || $retryAfter > 60) throw new DomainException('defer-job');
        return $retryAfter + $jitter;
    }
    return min(30, 2 ** $attempt) + $jitter;
}
echo delaySeconds(0,null,1)."
";
echo delaySeconds(2,10,2)."
";
try { delaySeconds(2,3600,0); } catch (DomainException $e) { echo $e->getMessage()."
"; }

2
12
defer-job

Тонкости функций ожидания

sleep возвращает 0 при полном ожидании; при прерывании семантика возвращаемого значения зависит от платформы. usleep не возвращает полезного результата, и большие интервалы удобнее выражать sleep или планировщиком. time_nanosleep может вернуть true, false либо массив оставшегося времени при прерывании сигналом. Надёжный воркер должен уметь корректно завершаться по сигналу, а не превращать любое прерывание в бесконечный сон.

Для измерения длительности используйте монотонный hrtime, а для даты следующего задания — календарное время. Системные часы могут корректироваться, поэтому вычисление длительности как time_end-time_start иногда ведёт себя неожиданно. Не используйте busy-wait с пустым циклом: он тратит CPU, хотя никакой полезной работы не происходит.

Медленное место здесь намеренное: ожидание защищает внешний сервис. Оптимизация не означает убрать sleep и получить больше 429. Полезные показатели — число успешных операций, задержка очереди, доля повторов и соблюдение квоты. Если одному импорту мешают другие, нужна координация общего лимита, а не случайное увеличение паузы в каждой копии скрипта.

Общий лимитер и честное состояние задания

Token bucket позволяет небольшие всплески в пределах ёмкости, а leaky bucket задаёт более ровный темп. Выбор зависит от правил провайдера: средняя скорость не всегда заменяет жёсткий лимит каждого окна. При нескольких воркерах изменение счётчика и выдача разрешения должны быть атомарными. Обычные get/set в Redis без согласованного алгоритма оставляют гонку так же, как SELECT перед INSERT.

Состояние задания хранит номер попытки, последнее безопасное описание ошибки, время следующего запуска и срок окончательного отказа. Если сервис попросил ждать час, интерфейс должен показать отложенную обработку, а не крутить бесконечный спиннер. Отмена задания прекращает будущие попытки, но не способна отменить уже принятый внешний запрос; это отдельная операция по контракту API.

Разделяйте лимит скорости и ограничение параллельности. Десять медленных запросов могут укладываться в секундную квоту, но занять все соединения. Маленькая очередь и ограниченный пул защищают память и воркеры. Метрики успешных операций, возраста очереди и доли 429 помогают понять, где узкое место: в квоте партнёра или в собственной обработке.

Практика: проверьте решение, а не только успешный путь

Нужно отправить 20 000 уведомлений с лимитом 5/с. Почему sleep(1) внутри веб-запроса после каждого пятого сообщения плохой проект?