Определите, где хранится запись
В этом примере основная запись хранится в БД приложения. Календарь показывает её специалисту, но не заменяет таблицу бронирований. У записи есть booking_id, клиент, специалист, начало и конец в UTC, исходный часовой пояс, статус и версия. В учебной таблице bookings рядом хранятся event_id, etag и состояние синхронизации; calendar_id единого календаря задан в окружении. В многокалендарном приложении вынесите связь в отдельную таблицу и сохраняйте calendar_id для каждой записи.
Защита от двух клиентов на один слот должна работать в транзакции БД: ограничение на занятие слота или блокировка расписания. Проверка свободного времени и последующий events.insert не образуют единую транзакцию. Если специалист ведёт другие события в том же календаре, учитывайте их как занятость и повторно проверяйте перед подтверждением; полностью устранить гонку с ручной правкой только чтением календаря нельзя.
Для старта удобнее отдельный календарь консультаций. Запись и постановку операции синхронизации сохраняйте одной транзакцией. Пока worker не получил подтверждение, показывайте «Запись принята, календарь обновляется». Если добавление в календарь обязательно для подтверждения услуги, используйте промежуточный статус и уведомляйте клиента только после успеха.
Выбор времени и конкурентные бронирования подробнее разобраны в руководстве по записи через Telegram-бота. Здесь сосредоточимся на интеграции с календарём.
Подготовьте отдельный PHP-проект
Ниже рабочее ядро интеграции для одного специалиста и одного календаря. PHP 8.3+, cURL, PDO SQLite и sodium. В Telegram у вас уже должен быть сценарий подтверждения записи: в той же транзакции сохраните данные связи и sync_state=pending, как делает booking.php, затем разрешите отдельному worker синхронизацию. Не запускайте shell-команду из webhook и не держите бизнес-транзакцию открытой во время запроса Google. Команды CLI не заменяют выбор слота, проверку владельца и защиту от пересечений бронирования.
public/oauth-callback.php common.php values.php schema.sql init.php google-token.php oauth-start.php calendar.php booking.php sync.php sync-bookings.php
APP_DB=/private/calendar-demo.sqlite GOOGLE_CLIENT_ID=YOUR_WEB_CLIENT_ID GOOGLE_CLIENT_SECRET=YOUR_CLIENT_SECRET GOOGLE_REDIRECT_URI=https://example.com/oauth-callback.php GOOGLE_CALENDAR_ID=YOUR_CALENDAR_ID OAUTH_STATE_PATH=/private/google-oauth-state.json GOOGLE_TOKEN_PATH=/private/google-refresh.enc TOKEN_KEY_HEX=RANDOM_HEX_64
Создайте закрытый каталог /private, доступный процессам приложения, и задайте реальные переменные окружения. TOKEN_KEY_HEX — случайный 32-байтный ключ в hex, который хранится отдельно от файла токена, например в секретах окружения. Не подставляйте в него Telegram-токен. Обычный PHP сам не читает .env.
values.php проверяет типы на границе JSON и БД. Некорректные данные прерывают операцию; они не должны превращаться в ложный успешный результат.
<?php
declare(strict_types=1);
/**
* @return array<string,mixed>
*/
function objectValue(mixed $value): array
{
if (!is_array($value)) {
throw new InvalidArgumentException('Expected object');
}
$result = [];
foreach ($value as $key => $item) {
if (!is_string($key)) {
throw new InvalidArgumentException('Expected object keys');
}
$result[$key] = $item;
}
return $result;
}
function stringValue(mixed $value): string
{
if (!is_string($value)) {
throw new InvalidArgumentException('Expected string');
}
return $value;
}
function intValue(mixed $value): int
{
if (!is_int($value) && !is_string($value)) {
throw new InvalidArgumentException('Expected integer');
}
$integer = filter_var($value, FILTER_VALIDATE_INT);
if ($integer === false) {
throw new InvalidArgumentException('Invalid integer');
}
return $integer;
}
<?php
declare(strict_types=1);
require_once __DIR__.'/values.php';
function envRequired(string $name): string
{
$value = getenv($name);
if ($value === false || $value === '') {
throw new RuntimeException('Missing environment: '.$name);
}
return $value;
}
/**
* @param array<string, mixed>|null $data
*
* @param list<string> $headers
*
* @return array{status:int, body:array<string, mixed>}
*/
function jsonHttp(string $method, string $url, ?array $data = null, array $headers = []): array
{
if ($method === '') {
throw new InvalidArgumentException('Empty HTTP method');
}
$curl = curl_init($url);
if ($curl === false) {
throw new RuntimeException('Cannot initialize HTTP client');
}
curl_setopt_array($curl, [
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 40,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_HTTPHEADER => ['Accept: application/json', 'Content-Type: application/json', ...$headers],
]);
if ($data !== null) {
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE));
}
$raw = curl_exec($curl);
$status = (int) curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
if (!is_string($raw)) {
throw new RuntimeException('Transport result unknown');
}
if ($status === 204) {
return ['status' => 204, 'body' => []];
}
$body = objectValue(json_decode($raw, true, 64, JSON_THROW_ON_ERROR));
return ['status' => $status, 'body' => $body];
}
function database(): PDO
{
$db = new PDO('sqlite:'.envRequired('APP_DB'), null, null, [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
$db->exec('PRAGMA busy_timeout=5000');
return $db;
}
CREATE TABLE IF NOT EXISTS bookings (
id TEXT PRIMARY KEY,
event_id TEXT NOT NULL UNIQUE,
starts_at TEXT NOT NULL,
ends_at TEXT NOT NULL,
zone TEXT NOT NULL,
state TEXT NOT NULL DEFAULT 'active',
version INTEGER NOT NULL DEFAULT 1,
synced_version INTEGER NOT NULL DEFAULT 0,
etag TEXT,
sync_state TEXT NOT NULL DEFAULT 'pending'
);
CREATE TABLE IF NOT EXISTS calendar_snapshot (event_id TEXT PRIMARY KEY, body TEXT NOT NULL);
CREATE TABLE IF NOT EXISTS calendar_cursor (id INTEGER PRIMARY KEY CHECK(id=1), token TEXT NOT NULL);
<?php
declare(strict_types=1);
require __DIR__.'/common.php';
$sql = file_get_contents(__DIR__.'/schema.sql');
if ($sql === false) {
throw new RuntimeException('Schema missing');
}
database()->exec($sql);
echo "Database ready\n";
Настройте доступ Google
Включите Calendar API в Google Cloud, настройте OAuth consent screen и OAuth-клиент веб-приложения с точным HTTPS redirect URI. В нашем варианте календарь подключает специалист через свой Google-аккаунт. Бот-клиент не должен получать токены Google и самостоятельно выбирать произвольный calendar_id.
Для чтения и изменения событий используйте scope https://www.googleapis.com/auth/calendar.events. Он не заменяет права на сам календарь: у подключённого аккаунта должна быть возможность изменять события в выбранном календаре. В примере calendar_id вводится из настроек нужного календаря; если добавляете выбор через calendarList, отдельно подберите минимальный scope для списка. Создание события и требования доступа.
OAuth state привяжите к сессии того сотрудника, который начал подключение, и проверяйте при возврате. Для фоновой работы запросите offline-доступ; refresh token храните зашифрованным на сервере, access token обновляйте по сроку действия. Ответ Calendar API 401 переводит запись в reconnect_required. Ошибка обновления токена, включая invalid_grant, останавливает проход до обработки записей: сотруднику нужно повторить подключение и затем вернуть разобранные записи в pending. Не зацикливайте задания с invalid_grant. Серверный OAuth-поток Google.
Service account подходит лишь при явно предоставленном доступе к целевому календарю и разрешающей политике организации. Сам факт создания сервисного аккаунта не даёт ему календарь сотрудника. Для приглашения гостей действуют дополнительные ограничения, включая domain-wide delegation для service account; в этом примере гостей и рассылку email не добавляем.
Для воспроизводимой настройки используем однократное подключение, которое запускается сотрудником из CLI. oauth-start.php создаёт случайный state с десятиминутным сроком и печатает URL согласия. Открыть его должен владелец выбранного календаря. Публичного маршрута «подключить любой аккаунт» здесь нет.
<?php
declare(strict_types=1);
require __DIR__.'/common.php';
umask(0077);
$state = bin2hex(random_bytes(32));
if (file_put_contents(envRequired('OAUTH_STATE_PATH'), json_encode(['state' => $state,'expires' => time() + 600], JSON_THROW_ON_ERROR), LOCK_EX) === false) {
throw new RuntimeException('Cannot persist OAuth state');
}
echo 'https://accounts.google.com/o/oauth2/v2/auth?'.http_build_query([
'client_id' => envRequired('GOOGLE_CLIENT_ID'),'redirect_uri' => envRequired('GOOGLE_REDIRECT_URI'),
'response_type' => 'code','scope' => 'https://www.googleapis.com/auth/calendar.events',
'access_type' => 'offline','prompt' => 'consent','state' => $state,
]).PHP_EOL;
<?php
declare(strict_types=1);
/**
* @param array<string,string> $fields
* @return array<string,mixed>
*/
function googleTokenRequest(array $fields): array
{
$curl = curl_init('https://oauth2.googleapis.com/token');
if ($curl === false) {
throw new RuntimeException('Cannot initialize cURL');
}
curl_setopt_array($curl, [CURLOPT_POST => true,CURLOPT_POSTFIELDS => http_build_query($fields),
CURLOPT_HTTPHEADER => ['Content-Type: application/x-www-form-urlencoded'],
CURLOPT_RETURNTRANSFER => true,CURLOPT_CONNECTTIMEOUT => 5,CURLOPT_TIMEOUT => 20]);
$raw = curl_exec($curl);
$status = (int)curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
if (!is_string($raw)) {
throw new RuntimeException('OAuth network error');
}
$result = json_decode($raw, true, 32, JSON_THROW_ON_ERROR);
if ($status !== 200 || !is_array($result)) {
throw new RuntimeException('OAuth failed; reconnect may be required');
}
return objectValue($result);
}
function accessToken(): string
{
$raw = file_get_contents(envRequired('GOOGLE_TOKEN_PATH'));
$encrypted = is_string($raw) ? base64_decode($raw, true) : false;
if (!is_string($encrypted) || strlen($encrypted) <= SODIUM_CRYPTO_SECRETBOX_NONCEBYTES) {
throw new RuntimeException('Connect Google first');
}
$nonce = substr($encrypted, 0, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
$refresh = sodium_crypto_secretbox_open(substr($encrypted, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES), $nonce, sodium_hex2bin(envRequired('TOKEN_KEY_HEX')));
if ($refresh === false) {
throw new RuntimeException('Cannot decrypt Google token');
}
$result = googleTokenRequest(['client_id' => envRequired('GOOGLE_CLIENT_ID'),
'client_secret' => envRequired('GOOGLE_CLIENT_SECRET'),
'refresh_token' => $refresh,'grant_type' => 'refresh_token']);
if (!is_string($result['access_token'] ?? null)) {
throw new RuntimeException('Missing access token');
}
return $result['access_token'];
}
<?php
declare(strict_types=1);
require dirname(__DIR__).'/common.php';
require dirname(__DIR__).'/google-token.php';
header('Cache-Control: no-store');
header('Referrer-Policy: no-referrer');
try {
$state = $_GET['state'] ?? null;
$code = $_GET['code'] ?? null;
if (!is_string($state) || !is_string($code)) {
throw new RuntimeException('Missing OAuth result');
}
$file = fopen(envRequired('OAUTH_STATE_PATH'), 'r+');
if ($file === false || !flock($file, LOCK_EX)) {
throw new RuntimeException('OAuth session unavailable');
}
$saved = json_decode(stream_get_contents($file), true, 16, JSON_THROW_ON_ERROR);
if (!is_array($saved) || !is_string($saved['state'] ?? null) || !is_int($saved['expires'] ?? null)
|| $saved['expires'] < time() || !hash_equals($saved['state'], $state)) {
throw new RuntimeException('Invalid OAuth state');
}
ftruncate($file, 0);
fflush($file);
flock($file, LOCK_UN);
fclose($file);
$result = googleTokenRequest(['client_id' => envRequired('GOOGLE_CLIENT_ID'),
'client_secret' => envRequired('GOOGLE_CLIENT_SECRET'),'redirect_uri' => envRequired('GOOGLE_REDIRECT_URI'),
'code' => $code,'grant_type' => 'authorization_code']);
$token = $result['refresh_token'] ?? null;
if (!is_string($token) || $token === '') {
throw new RuntimeException('Refresh token not returned');
}
$key = sodium_hex2bin(envRequired('TOKEN_KEY_HEX'));
if (strlen($key) !== SODIUM_CRYPTO_SECRETBOX_KEYBYTES) {
throw new RuntimeException('Invalid encryption key');
}
$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
$encrypted = base64_encode($nonce.sodium_crypto_secretbox($token, $nonce, $key));
umask(0077);
$path = envRequired('GOOGLE_TOKEN_PATH');
if (file_put_contents($path.'.tmp', $encrypted, LOCK_EX) === false || !rename($path.'.tmp', $path)) {
throw new RuntimeException('Cannot persist token');
}
echo 'Календарь подключён. Можно закрыть страницу.';
} catch (Throwable) {
http_response_code(400);
echo 'Подключение не завершено. Начните его заново с сервера.';
}
php init.php php oauth-start.php
Добавьте GOOGLE_REDIRECT_URI в разрешённые redirect URI OAuth-клиента, затем откройте выведенный URL. Callback должен показать «Календарь подключён», а вне public появится зашифрованный refresh token. Его содержимое не выводится в браузер или консоль. При отказе пользователя или отсутствии refresh token начните подключение заново, не затирая существующий файл токена пустой строкой.
accessToken получает краткоживущий токен для одного прохода worker. Для большого потока сохраняйте срок действия и переиспользуйте access token, чтобы не обновлять его перед каждой операцией. В многопользовательском сервисе замените одноразовый файл state на запись, связанную с авторизованным сотрудником и календарём; один общий токен для разных организаций недопустим.
Сохраните время без двусмысленности
Перед подтверждением бот показывает дату, время и зону: «20 ноября, 15:00–15:30, Москва (Europe/Moscow)». В БД сохраните UTC и IANA-имя зоны. Число +03:00 описывает смещение на конкретную дату; оно не заменяет Europe/Moscow или Europe/Berlin для будущих преобразований.
В JSON события используйте dateTime в RFC 3339 со смещением и согласованный timeZone. Для дня целиком применяются другие поля — date; не используйте их для консультации на полчаса. При переводе локального времени в зоне с летним временем обрабатывайте несуществующий и двусмысленный час явно: предложите другой слот или уточните смещение.
{
"id": "7bf51ce780714d4e9060aa6e8c683a31",
"summary": "Консультация · B-1042",
"start": {"dateTime":"2026-11-20T15:00:00+03:00","timeZone":"Europe/Moscow"},
"end": {"dateTime":"2026-11-20T15:30:00+03:00","timeZone":"Europe/Moscow"},
"extendedProperties": {"private":{"booking_id":"B-1042"}}
}
В рабочем приложении сервер строит этот объект из подтверждённой записи. Не копируйте демонстрационный id для всех клиентов. Заголовок с номером записи достаточен: телефон, подробный запрос и медицинские сведения не стоит добавлять в календарь по умолчанию.
Назначьте стабильный ID до первого запроса
Назначьте случайный ID один раз до обращения к Google. В booking.php это bin2hex(random_bytes(16)): 128 случайных битов в виде 32 hex-символов. Ещё один допустимый вариант — UUID без дефисов. Такой hex-ID укладывается в допустимый алфавит. Google принимает собственный id длиной 5–1024 символа из 0–9 и a–v; он уникален в календаре и отличается от iCalUID. Параметр id.
В учебной таблице id — первичный ключ, event_id — уникальный. Для отдельной таблицы связи наложите уникальность на booking_id и на пару calendar_id/event_id. Worker должен последовательно обрабатывать операции одной записи. При повторе сохраняйте event_id: новый случайный ID на каждой попытке как раз создаст дубликаты. При удалении и новом самостоятельном бронировании создаётся новая связь.
Стабильный ID помогает восстановиться после потерянного ответа, но не заменяет блокировку заданий: документация Google предупреждает об особенностях обнаружения коллизий в распределённой системе. Не отправляйте параллельные insert для одной записи и не используйте совпадение названия как ключ уникальности.
Создайте событие и восстановитесь после повтора
CalendarClient получает HTTP-транспорт аргументом: в работе передаём jsonHttp, а в локальных проверках — функцию с подготовленными ответами. Сначала читается event_id из БД; при отсутствии события выполняется insert. Конфликт 409 проверяется повторным чтением того же ID.
<?php
declare(strict_types=1);
final class CalendarError extends RuntimeException
{
public function __construct(public readonly int $status)
{
parent::__construct('Calendar HTTP '.$status);
}
}
final class CalendarClient
{
/**
* @param Closure(string,string,?array<string,mixed>,list<string>):array{status:int,body:array<string,mixed>} $http
*/
public function __construct(private readonly string $token, private readonly string $calendarId, private readonly Closure $http)
{
}
/**
* @param array<string,mixed>|null $data
* @return array<string,mixed>
*/
private function request(string $method, string $suffix, ?array $data = null, ?string $etag = null): array
{
$headers = ['Authorization: Bearer '.$this->token];
if ($etag !== null) {
$headers[] = 'If-Match: '.$etag;
}
$result = ($this->http)($method, 'https://www.googleapis.com/calendar/v3/calendars/'.rawurlencode($this->calendarId).'/events'.$suffix, $data, $headers);
if ($result['status'] < 200 || $result['status'] >= 300) {
throw new CalendarError($result['status']);
}
return $result['body'];
}
/**
* @return array<string,mixed>
*/
public function get(string $id): array
{
return $this->request('GET', '/'.rawurlencode($id));
}
/**
* @param array<string,mixed> $event
* @return array<string,mixed>
*/
public function ensure(array $event): array
{
$id = stringValue($event['id']);
try {
return $this->owned($this->get($id), $event);
} catch (CalendarError $error) {
if ($error->status !== 404) {
throw $error;
}
}
try {
return $this->request('POST', '', $event);
} catch (CalendarError $error) {
if ($error->status !== 409) {
throw $error;
}
return $this->owned($this->get($id), $event);
}
}
/**
* @param array<string,mixed> $found
* @param array<string,mixed> $expected
* @return array<string,mixed>
*/
private function owned(array $found, array $expected): array
{
if (($found['status'] ?? '') === 'cancelled' ||
self::bookingId($found) !== self::bookingId($expected)) {
throw new RuntimeException('Event ownership conflict');
}
return $found;
}
/**
* @param array<string,mixed> $event
* @return array<string,mixed>
*/
public function move(string $id, array $event, string $etag): array
{
return $this->request('PATCH', '/'.rawurlencode($id), ['start' => $event['start'],'end' => $event['end']], $etag);
}
/**
* @param array<string,mixed> $event
*/
public static function bookingId(array $event): string
{
$properties = objectValue($event['extendedProperties'] ?? []);
$private = objectValue($properties['private'] ?? []);
return stringValue($private['booking_id'] ?? null);
}
public function cancel(string $id, string $etag): void
{
$this->request('DELETE', '/'.rawurlencode($id), null, $etag);
}
/**
* @return array<string,mixed>
*/
public function changes(?string $syncToken, ?string $pageToken): array
{
$query = ['showDeleted' => 'true','maxResults' => 100];
if ($syncToken !== null) {
$query['syncToken'] = $syncToken;
}
if ($pageToken !== null) {
$query['pageToken'] = $pageToken;
}
return $this->request('GET', '?'.http_build_query($query));
}
}
Ответ Google остаётся отдельным от локального состояния бронирования. ensure не перезаписывает существующее событие: он проверяет booking_id и возвращает найденное. Перенос выполняется только отдельным move с If-Match. DELETE с кодом 204 не пытается декодировать пустой ответ как JSON.
Идентификатор календаря URL-кодируется как один сегмент. Не используйте входной URL пользователя вместо базового адреса API: это превратит интеграцию в произвольный сетевой клиент. Сам calendar_id берётся из подтверждённой серверной настройки.
<?php
declare(strict_types=1);
require __DIR__.'/common.php';
$action = $argv[1] ?? '';
$id = $argv[2] ?? '';
if (!in_array($action, ['create','move','cancel'], true) || !preg_match('/^[A-Z0-9-]{1,40}$/D', $id)) {
throw new RuntimeException('Usage: php booking.php create|move|cancel B-1042 [START END ZONE]');
}
$lock = fopen(envRequired('APP_DB').'.calendar.lock', 'c');
if ($lock === false || !flock($lock, LOCK_EX | LOCK_NB)) {
throw new RuntimeException('Calendar busy; retry later');
}
$db = database();
if ($action === 'cancel') {
$db->prepare("UPDATE bookings SET state='cancelled',version=version+1,sync_state='pending' WHERE id=? AND state='active'")->execute([$id]);
} else {
$zone = new DateTimeZone($argv[5] ?? 'Europe/Moscow');
$dates = [];
foreach ([$argv[3] ?? '',$argv[4] ?? ''] as $raw) {
$date = DateTimeImmutable::createFromFormat(DateTimeInterface::ATOM, $raw);
if (!$date || $date->format(DateTimeInterface::ATOM) !== $raw || $date->getOffset() !== $zone->getOffset($date)) {
throw new RuntimeException('Use valid RFC3339 timestamps with the selected zone offset');
}
$dates[] = $date;
}
if ($dates[1] <= $dates[0]) {
throw new RuntimeException('End must follow start');
}
$start = $dates[0]->setTimezone(new DateTimeZone('UTC'))->format(DateTimeInterface::ATOM);
$end = $dates[1]->setTimezone(new DateTimeZone('UTC'))->format(DateTimeInterface::ATOM);
if ($action === 'create') {
$db->prepare('INSERT INTO bookings(id,event_id,starts_at,ends_at,zone) VALUES(?,?,?,?,?)')
->execute([$id,bin2hex(random_bytes(16)),$start,$end,$zone->getName()]);
} else {
$query = $db->prepare("UPDATE bookings SET starts_at=?,ends_at=?,zone=?,version=version+1,sync_state='pending' WHERE id=? AND state='active'");
$query->execute([$start,$end,$zone->getName(),$id]);
if ($query->rowCount() !== 1) {
throw new RuntimeException('Active booking not found');
}
}
}
echo "Saved locally; run sync-bookings.php\n";
php booking.php create B-1042 "2026-11-20T15:00:00+03:00" "2026-11-20T15:30:00+03:00" Europe/Moscow php sync-bookings.php php booking.php move B-1042 "2026-11-20T16:00:00+03:00" "2026-11-20T16:30:00+03:00" Europe/Moscow php sync-bookings.php
booking.php создаёт случайный ID один раз и сохраняет время в UTC. Команда move увеличивает версию, но сохраняет event_id. В приложении бронирования используйте такую же запись изменения вместе с бизнес-транзакцией. CLI здесь служит безопасной точкой проверки самого календаря и не проверяет занятость слота.
<?php
declare(strict_types=1);
require_once __DIR__.'/calendar.php';
/**
* @param array<string,mixed> $row
* @return array<string,mixed>
*/
function eventBody(array $row): array
{
$zone = new DateTimeZone(stringValue($row['zone']));
return ['id' => $row['event_id'],'summary' => 'Консультация · '.stringValue($row['id']),
'start' => ['dateTime' => (new DateTimeImmutable(stringValue($row['starts_at'])))->setTimezone($zone)->format(DateTimeInterface::ATOM),'timeZone' => $row['zone']],
'end' => ['dateTime' => (new DateTimeImmutable(stringValue($row['ends_at'])))->setTimezone($zone)->format(DateTimeInterface::ATOM),'timeZone' => $row['zone']],
'extendedProperties' => ['private' => ['booking_id' => $row['id']]]];
}
function syncBookings(PDO $db, CalendarClient $calendar): void
{
$pending = $db->query("SELECT * FROM bookings WHERE sync_state IN ('pending','unknown') ORDER BY id");
if ($pending === false) {
throw new RuntimeException('Cannot read bookings');
}
$pending->setFetchMode(PDO::FETCH_ASSOC);
foreach ($pending as $data) {
$row = objectValue($data);
$id = stringValue($row['event_id']);
$state = 'unknown';
$etag = $row['etag'] === null ? null : stringValue($row['etag']);
try {
$expected = eventBody($row);
if ($row['state'] === 'cancelled') {
// Не вызываем ensure: отменённая запись не должна создавать событие.
$found = $calendar->get($id);
if (CalendarClient::bookingId($found) !== $row['id']) {
throw new RuntimeException('Owner mismatch');
}
if ($etag !== null && $found['etag'] !== $etag) {
throw new RuntimeException('Manual change');
}
$calendar->cancel($id, stringValue($found['etag']));
} else {
$found = $calendar->ensure($expected);
$matches = strtotime(stringValue(objectValue($found['start'] ?? [])['dateTime'] ?? '')) === strtotime(stringValue($row['starts_at']))
&& strtotime(stringValue(objectValue($found['end'] ?? [])['dateTime'] ?? '')) === strtotime(stringValue($row['ends_at']));
if (!$matches) {
if ($etag === null || $found['etag'] !== $etag) {
throw new RuntimeException('Manual change');
}
$found = $calendar->move($id, $expected, $etag);
}
$etag = stringValue($found['etag']);
}
$state = 'synced';
} catch (CalendarError $error) {
$state = match ($error->status) {
401 => 'reconnect_required', 403,404,410,412 => 'review', default => 'unknown',
};
} catch (RuntimeException $error) {
// Сетевой сбой и конфликт не смешиваем для автоматического повтора.
$state = $error->getMessage() === 'Transport result unknown' ? 'unknown' : 'review';
}
$q = $db->prepare('UPDATE bookings SET sync_state=?,etag=?,synced_version=CASE WHEN ?=? THEN version ELSE synced_version END WHERE id=? AND version=?');
$q->execute([$state,$etag,$state,'synced',$row['id'],$row['version']]);
}
}
function pullChanges(PDO $db, CalendarClient $calendar): void
{
$cursor = $db->query('SELECT token FROM calendar_cursor WHERE id=1');
if ($cursor === false) {
throw new RuntimeException('Cannot read sync cursor');
}
$token = $cursor->fetchColumn();
$page = null;
$db->beginTransaction();
try {
do {
$result = $calendar->changes(is_string($token) ? $token : null, $page);
if (!is_array($result['items'] ?? null)) {
throw new RuntimeException('Invalid event list');
}
foreach ($result['items'] as $event) {
if (!is_array($event)) {
throw new RuntimeException('Invalid event');
}
if (!is_string($event['id'] ?? null)) {
continue;
}
$db->prepare('INSERT INTO calendar_snapshot(event_id,body) VALUES(?,?) ON CONFLICT(event_id) DO UPDATE SET body=excluded.body')
->execute([$event['id'],json_encode($event, JSON_THROW_ON_ERROR)]);
// Сверка помечает конфликт; не перезаписывает бизнес-запись.
$db->prepare("UPDATE bookings SET sync_state='review' WHERE event_id=? AND sync_state='synced' AND state='active' AND (etag<>? OR ?='cancelled')")
->execute([$event['id'],$event['etag'] ?? '',$event['status'] ?? '']);
}
$page = isset($result['nextPageToken']) ? stringValue($result['nextPageToken']) : null;
} while ($page !== null);
if (!is_string($result['nextSyncToken'] ?? null)) {
throw new RuntimeException('Missing sync token');
}
$db->prepare('INSERT INTO calendar_cursor(id,token) VALUES(1,?) ON CONFLICT(id) DO UPDATE SET token=excluded.token')->execute([$result['nextSyncToken']]);
$db->commit();
} catch (Throwable $error) {
$db->rollBack();
if ($error instanceof CalendarError && $error->status === 410) {
$db->beginTransaction();
$db->exec('DELETE FROM calendar_cursor; DELETE FROM calendar_snapshot');
$db->commit(); // Следующий проход начнёт полную синхронизацию.
}
throw $error;
}
}
<?php
declare(strict_types=1);
require __DIR__.'/common.php';
require __DIR__.'/google-token.php';
require __DIR__.'/sync.php';
$lock = fopen(envRequired('APP_DB').'.calendar.lock', 'c');
if ($lock === false || !flock($lock, LOCK_EX | LOCK_NB)) {
exit(0);
}
$calendar = new CalendarClient(accessToken(), envRequired('GOOGLE_CALENDAR_ID'), Closure::fromCallable('jsonHttp'));
$db = database();
if (($argv[1] ?? '') === 'pull') {
pullChanges($db, $calendar);
} else {
syncBookings($db, $calendar);
}
echo "Synchronization finished; inspect sync_state\n";
syncBookings берёт pending/unknown и записывает synced только после подтверждённой операции. Потерянный ответ insert восстанавливается чтением того же ID. Потерянный ответ PATCH тоже можно распознать: если фактическое время уже совпало с желаемым, повторная правка не требуется. Если время отличается и etag изменился, нужна сверка, а не перезапись.
Все CLI-операции используют один lock-файл. В приложении с несколькими серверами замените его блокировкой общей БД или очередью по booking_id. Нельзя оставить файловую блокировку только на одном узле и считать, что она защищает обработчики на остальных. Ошибку получения OAuth-токена worker не превращает в успешную синхронизацию: локальные записи остаются для разбора.
Переносите и отменяйте существующее событие
При переносе сначала проверьте нового владельца операции и доступность слота, затем сохраните новую версию бронирования и задание. Worker читает актуальную версию и вызывает move с тем же event_id. Старая задача с прежней версией должна завершиться без отправки устаревшего времени.
Перед изменением перечитайте событие. If-Match с его etag защищает от незаметной перезаписи ручной правки; HTTP 412 означает конфликт. Прочитайте новую версию и примените выбранное правило: в нашем примере спорные переносы передаются специалисту. Бесконечный повтор со старым etag не поможет. Условное изменение ресурса.
Для отмены пометьте бронирование отменённым, затем вызовите cancel с актуальным etag. Успешный DELETE не содержит JSON; модуль учитывает 204. После потерянного ответа проверьте именно связанное событие. 404 или 410 можно трактовать как уже отсутствующее событие только после проверки доступа к правильному календарю и его идентификатора, а не при любой ошибке Google.
Сохраните связь и статус отмены: удаление строки связи сразу после DELETE делает поздние задания опасными. Worker больше не должен воссоздавать отменённую запись через ensure. Уведомление клиенту привязывайте к версии операции, чтобы перенос и отмена не породили несколько одинаковых сообщений.
php booking.php cancel B-1042 php sync-bookings.php
SELECT id,event_id,state,version,synced_version,sync_state,etag FROM bookings;
В коде отмена при 404/410 оставляет review: такой ответ может означать не только удалённое событие, но и проблему доступа. Убедитесь, что нужный календарь доступен и связанного события действительно нет, затем отметьте эту отмену синхронизированной вручную. Для автоматизации этого решения потребуется дополнительная проверка календаря, а не расширение списка «успешных» ошибок.
При 412 состояние также review. Покажите специалисту локальное и календарное время. Он должен выбрать, сохранить ручной перенос или применить бронь; после решения обновите etag и версию. В примере нет автоматической кнопки, которая стирает чужую правку, — конфликт остаётся заметным в БД.
Как учитывать изменения со стороны Google Calendar
Для первого запуска достаточно фонового чтения изменений; push можно добавить позже. Выполните events.list до конца пагинации, сохраните события и nextSyncToken последней страницы. Затем передавайте syncToken в следующие запросы. Не меняйте набор фильтров между страницами и проходами; совместимость параметров описана в events.list.
Обрабатывайте отменённые события и сохраняйте новый sync token только после надёжного применения всех страниц. При 410 токен устарел: пересоздайте локальный снимок календаря полной синхронизацией. Не удаляйте бронирования приложения вместе со снимком. Порядок incremental sync.
Сопоставляйте событие по calendar_id/event_id. extendedProperties.private.booking_id помогает диагностике, но не даёт внешнему событию права изменять чужую запись. Для событий без существующей связи максимум обновляйте занятость специалиста, не создавайте задним числом клиентскую бронь.
Выберите правила владения полями. В нашем примере изменение описания не меняет бронь; ручное изменение активного связанного события переводит запись в review для сверки специалистом. Учебный вариант консервативен: он реагирует на смену etag, в том числе после правки описания. Собственная подтверждённая отмена не создаёт такой конфликт. Пока конфликт не разрешён, бот не должен подтверждать клиенту новое время. Автоматическое принятие ручного переноса возможно лишь после той же проверки слота, что выполняется при записи.
events.watch отправляет уведомление об изменении без тела события: после него всё равно нужен sync. Проверяйте X-Goog-Channel-ID, X-Goog-Resource-ID и собственный непредсказуемый Channel-Token, сводите повторные уведомления в одну задачу. Канал наблюдения истекает и требует обновления; фоновая сверка полезна и при push. Push-уведомления Google Calendar.
php sync-bookings.php pull
Функция pullChanges уже входит в sync.php. Она сохраняет каждую страницу в снимок и переносит курсор только после успешного полного прохода. При 410 очищается лишь снимок и курсор; таблица bookings остаётся. Повтор команды начинает полную синхронизацию. Для небольшого учебного календаря используется одна транзакция; для большого календаря загружайте страницы во временный снимок и атомарно переключайте готовую версию, чтобы не удерживать блокировку БД во время сети.
Изменение связанного события переводит synced в review. Чужие события остаются в снимке и не получают права создавать или менять брони. Запускайте pull после исходящей синхронизации и периодически по расписанию. В период ручного конфликта не отправляйте клиенту новое подтверждение времени автоматически.
Проверьте интеграцию на отдельном календаре
Одна запись создаёт событие в правильном календаре; повтор задания возвращает тот же id.
Смоделируйте успешный insert с потерянным ответом. Повтор должен прочитать событие, а не создать новый ID.
Перенос меняет время существующего события. Старое задание после переноса не возвращает прежний слот.
Ручная правка между GET и PATCH приводит к 412 и разбору конфликта, а не к молчаливой потере правки.
Отмена выдерживает повтор, поздняя задача создания не воскрешает удалённую встречу.
Проверьте две зоны, переход летнего времени и отображение даты в Telegram.
Проверьте отзыв OAuth-доступа, несколько страниц sync, отменённое событие и восстановление после 410.
BotGate в этой схеме используется для Telegram-уведомлений. Google OAuth, события и синхронизация выполняются вашим сервером непосредственно через Calendar API. Напоминания лучше вынести в отдельный процесс, привязанный к актуальной версии записи; пример есть в руководстве по напоминаниям.
Первый полный проход: создайте B-1042, синхронизируйте, проверьте один event_id в Google, перенесите запись, повторите синхронизацию, затем отмените. В календаре не должно появляться второе событие при переносе. Отдельно вручную сдвиньте событие перед очередным move и проверьте переход в review.
Внешние приглашения участникам и Google Meet сюда не добавлены: в событии нет attendees и conferenceData. Это сохраняет тест без неожиданных email. Если добавляете гостей, сначала разберите sendUpdates и правила доступа календаря; Telegram-уведомление о записи и приглашение Google — разные каналы.