Подписки и крон
Прочитайте эту страницу, даже если подписок не продаёте. Магазин висит восемью задачами на кроне сайта, и у трёх из них молчание стоит денег.
Подписка — это заказ
Отдельной сущности «подписка» нет, и это намеренно: так каждая подписка получает список заказов, карточку, счёт, чек и ленту истории даром — вместо параллельного недоделанного мира рядом с ними.
Подписка — заказ, несущий четыре дополнительных вещи:
| Колонка | Что в ней |
|---|---|
period | длина оплаченного отрезка; 0 — разовая покупка |
starts_at / expires_at | когда доступ начинается и когда кончается |
auto_renew | покупатель попросил списывать дальше |
recurrent_token | привязка карты у шлюза. Карточных данных здесь не хранится |
Доступ выдаёт и снимает сайт, слушая события ниже. Компонент ведёт сроки и деньги; что такое «доступ» — ресурс, группа, файл — знает только сайт.
Расписания внутри компонента нет
Это самая важная фраза на странице. Точки входа внутри компонента нет ни одной — ни скрипта, ни процессора, ни маршрута. pbShop отдаёт методы, а зовёт их крон сайта.
Магазин, владелец которого не прописал строку в crontab, получает магазин, который молча не продлевает. Компонент этого не исправит ничем — ровно поэтому и существует следующий раздел.
0 3 * * * /usr/bin/php /путь/к/сайту/core/App/cron/subscriptions.php$pbs = modx()->services->get('pbshop');
$pbs->fiscal()->poll(); // раз в несколько минут
$pbs->orders()->expire(); // раз в сутки
$pbs->orders()->dueForRenewal(); // раз в сутки, дальше renew() на каждый
$pbs->stock()->releaseStale(); // по обстоятельствам
$pbs->stockAlerts()->notifyRestocked(); // по обстоятельствам
$pbs->cart()->purge(); // раз в месяц
$pbs->compare()->purge(); // раз в месяц
// Накладные — своим классом: у магазина без доставки службы в контейнере нет.
(new \Boshnik\PbShop\Services\WaybillService())->dueForTracking();Восемь задач
| Задача | Метод | Зачем | Критичная |
|---|---|---|---|
fiscal.poll | fiscal()->poll() | добирает чеки, про которые касса не ответила | ● |
orders.renew | orders()->dueForRenewal() | отбирает подписки под списание | ● |
orders.expire | orders()->expire() | помечает те, у которых срок вышел | ● |
stock_alerts.notify | stockAlerts()->notifyRestocked() | письма «товар поступил» | |
stock.release_stale | stock()->releaseStale() | возвращает резерв брошенных заказов | |
waybills.track | WaybillService::dueForTracking() | отбирает посылки под опрос перевозчика | |
cart.purge | cart()->purge() | уборка гостевых корзин | |
compare.purge | compare()->purge() | уборка гостевых сравнений |
«Критичная» — про цену молчания, а не про важность. Тишина у кассы и у автосписания — это деньги и налоговая: заказы идут, чеки не выбиваются, подписки не продлеваются. Неснятый доступ — та же выручка с другой стороны: оказанная и неоплаченная услуга. Тишина у очистки корзин — мусор в таблице.
Проверить, что крон вообще зовут
Каждая задача оставляет отметку сама: когда звали, сколько обработала и чем кончилась. Настройки → Прогоны крона в менеджере.
Отметку ставят сами методы служб, поэтому править скрипт сайта ради неё не надо — он уже их зовёт. Это было решающим условием: всё, что требует правки скрипта сайта, на уже поставленных магазинах не появилось бы никогда, потому что этот скрипт не обновляется вместе с пакетом.
Задача, у которой стоит «Последний запуск: никогда», не запускалась ни разу — то есть строки под неё в crontab нет. Отметка на задачу, а не одна на магазин, и читать её надо именно так: расписания расходятся на три порядка, и «крон был вчера» (вчера звали очистку корзин) ничего не говорит о кассе.
«Отобрано» — это не «сделано»
Отметка у подписок и у опроса перевозчика подписана отобрано, а не обработано, и разница не косметическая. Эти два метода отдают строки, а списывает и опрашивает цикл в скрипте сайта — чем кончился каждый вызов, компоненту не видно. «Отобрано 3» не значит «продлено 3».
Если молчание задевает деньги или налоговую, на страницах магазина появляется баннер. Красным он загорается только когда работа действительно ждёт: порога «молчит шесть часов» нет намеренно, расписание задаёт crontab, которого компонент не видит. На свежей установке баннер жёлтый — это не поломка, а напоминание, что крон ещё не прописан.
Автопродление
dueForRenewal() отдаёт заказы, чей expires_at попал в окно продления; окно по умолчанию — три дня. Дальше renew() на каждый.
foreach ($pbs->orders()->dueForRenewal() as $order) {
$pbs->orders()->renew($order);
}renew() возвращает null и не делает ничего, пока не выполнены все три условия:
- стоит
auto_renew— покупатель просил; recurrent_tokenнепустой — шлюз отдал привязку;- драйвер способа отвечает
supportsRecurring().
Из десяти драйверов коробки это умеют пять: maib, monobank, wayforpay, fondy и stripe. Подписка, проданная через LiqPay или PayPal, сама не спишется, и это свойство шлюза, а не пробел здесь — см. Что где лежит.
Удачное списание заводит новый заказ, продолжающий от прежнего срока, а не от сегодня: продление за два дня до конца не отнимает у покупателя эти два дня. Отказ помечает платёж неудачным и подписку не трогает; заказ остаётся в отборе, так что следующий прогон попробует снова.
Ни эскалации, ни письма ни об одном из этих событий
Компонент не ограничивает число попыток, не понижает тариф, не приостанавливает подписку и не отправляет писем ни о предстоящем списании, ни о неудачном, ни об удачном продлении. Письма «карта не прошла» нет, пока вы его не напишете.
Повесьте свой слушатель на pbShopPaymentFail и решите политику там. Это стоит продумать до запуска, а не узнать от покупателя, который тихо перестал платить три месяца назад.
Повторный колбэк второго периода не накидывает: продление идемпотентно по строке платежа.
Истечение
expire() находит оплаченные заказы, у которых expires_at в прошлом и отметки ещё нет, ставит expired_at и бросает pbShopOrderExpire по одному разу на заказ. Возвращает, сколько пометил.
Статус заказа он не меняет и сам ничего не снимает. Снятие — дело сайта, в слушателе:
// core/App/config/pbshop.php
return [
'listeners' => [
\Boshnik\PbShop\Events\Dispatcher::ORDER_EXPIRE => [
App\Listeners\RevokeAccess::class,
],
],
];Отметка ставится до броска события, поэтому упавший слушатель не заставляет событие повторяться на каждом прогоне крона до конца времён.
Льготного периода нет
В поставке есть две настройки, pbshop_renew_days_before и pbshop_grace_days, с подписями и описаниями на четырёх языках — и их не читает ничто. Сверено по коду 24.10.2026.
То есть: окно продления равно трём дням, и правка настройки его не сдвинет; доступ не живёт после окончания ни одного дня, что бы вы ни вписали в льготный период. Нужно и то и другое — передавайте окно явно, dueForRenewal($days) принимает аргумент, а льготный период реализуйте в своём слушателе ORDER_EXPIRE, отложив снятие сами.
Обе мёртвые настройки записаны как дефект; здесь они описаны мёртвыми, а не опущены, потому что настройка с переведённым описанием выглядит как работающая функция.
Отказ от продления
Покупатель выключает автопродление сам: POST /pay/orders/{id}/cancel, кнопка в кабинете и на странице заказа. Бросается pbShopOrderCancel. Следующее списание это останавливает; текущий оплаченный период не обрывает — он идёт до expires_at, как и оплачен.
Менеджер переключает auto_renew в форме заказа. Покупателю строка «Автопродление» показывается только когда списание и правда состоится.
События
| Событие | Когда бросается |
|---|---|
pbShopOrderPaid | по заказу пришли деньги |
pbShopOrderExtend | оплаченный отрезок продлён |
pbShopOrderExpire | срок вышел — снимайте доступ здесь |
pbShopOrderCancel | автопродление выключено |
pbShopPaymentSuccess / pbShopPaymentFail | само списание |
Слушатель — класс с методом handle(array $params, string $event) либо любой callable. Исключение в одном оплату не роняет: оно пишется в лог, остальные отрабатывают. Подробности — в разделе разработчику.