README

Composer-пакет для Google Business Profile REST API. Требуется PHP 8.1 или новее. Пакет можно подключить к Laravel или к приложению без фреймворка.

Клиент покрывает семь API v1, методы My Business v4.9 для отзывов, публикаций, меню и медиа, загрузку файлов через Media v1 и канал Business Information v1alpha. В v4.9 также доступны задокументированные методы пакетного чтения карточек и работы со списком услуг. Для обычного управления карточками и услугами используйте Business Information v1.

Установка

Выполните в корне вашего проекта.

composer require kith-web-studio/google-business-profile-php

OAuth и чтение отзывов

Для реальных запросов включите нужные API в одобренном проекте Google Cloud. OAuth-токен должен принадлежать пользователю с правами на нужные карточки. В приложении храните токены отдельно для каждого подключённого аккаунта.

use Google\Client as GoogleClient;
use GoogleBusinessProfile\Client;

// $token — результат обмена кода OAuth, сохранённый приложением.
$google = new GoogleClient();
$google->setClientId($clientId);
$google->setClientSecret($clientSecret);
$google->addScope(Client::SCOPE);
$google->setAccessToken($token);

// Для фоновых запросов сохраните исходный refresh_token при подключении.
$sdk = Client::fromGoogleClient($google);

$accounts = $sdk->accountManagement()->accountsList();

foreach ($accounts['accounts'] ?? [] as $account) {
    $locations = $sdk->businessInformation()->accountsLocationsList($account['name'], [
        'readMask' => 'name,title',
        'pageSize' => 10,
    ]);

    foreach ($locations['locations'] ?? [] as $location) {
        $reviews = $sdk->myBusiness()->reviewsList(
            $account['name'] . '/' . $location['name'],
            ['pageSize' => 10],
        );
        // Используйте $reviews['reviews'] и $reviews['nextPageToken'].
    }
}

SDK добавляет OAuth-токен к запросам и использует Google PHP Client для обновления токена при наличии refresh_token. Реализация OAuth callback и сохранение токенов принадлежат приложению. После обновления текущий токен можно получить через $google->getAccessToken(). При первичной авторизации для фоновой работы используйте setAccessType('offline'). Сохраните прежний refresh_token, если при повторной авторизации Google вернул только access token. OAuth для Business Profile

Приём уведомлений Cloud Pub/Sub

GoogleBusinessProfile\PubSub\PushReceiver принимает заголовок Authorization и сырое тело HTTP-запроса от аутентифицированной push-подписки с JSON-обёрткой. Для проверки подписи используется OpenSSL. Укажите ожидаемые audience, адрес сервисного аккаунта доставки и полное имя подписки. Метод receive() возвращает тип события, ID сообщения, имя подписки, данные и атрибуты. Аутентификация Pub/Sub

GoogleBusinessProfile\PubSub\PullReceiver забирает пачку из pull-подписки с помощью pull(). У каждого сообщения есть notification() для декодирования и deliveryAttempt, если Google прислал номер попытки. После успешной обработки передайте сообщение в acknowledge(). Метод modifyAckDeadline() меняет срок подтверждения конкретного сообщения. Нулевой срок означает NACK. Для подключения из среды с Application Default Credentials используйте fromApplicationDefaultCredentials(). Получение сообщений через pull

Событие NEW_REVIEW запускает загрузку отзыва через SDK. Доступны примеры на чистом PHP с HTTP-обработчиком и CLI-скриптом и примеры для Laravel с маршрутом и командой Artisan.

Интеграция с помощью ИИ-агента

Инструкции по использованию и проверке SDK собраны в AGENTS.md. Если агент работает в репозитории приложения, попросите его открыть AGENTS.md в каталоге установленного Composer-пакета.

Параметры и ошибки

Передавайте полные имена ресурсов Google, например locations/456 для v1 и accounts/123/locations/456 для отзывов v4.
Передавайте поля JSON как массив или объект. Ответы возвращаются как массивы. При пустом теле возвращается [].
Для пагинации передавайте nextPageToken из ответа в pageToken следующего запроса.
Повторяющиеся параметры задавайте списком. Вложенные параметры запроса задавайте ключами с точкой, например dailyRange.startDate.year.
HTTP-ошибки Guzzle содержат исходный статус и тело ответа Google. Повторы запросов, включая обработку квот и операций записи, задаёт приложение.
Канал businessInformationAlpha() работает с реальными карточками. Google описывает его как предварительную версию. Версии API

Для загрузки файла получите resourceName через myBusiness()->mediaStartUpload($location), передайте открытый поток или байты в mediaUpload()->upload($resourceName, $data), затем вызовите myBusiness()->mediaCreate($location, $body) с этим значением в dataRef.resourceName. Загрузка медиа

Локальная проверка

Из каталога SDK выполните composer install и composer test. Проверка использует подставные HTTP-ответы и не требует доступа к Google Business Profile. Для тестов приложения можно передать собственный клиент Guzzle в new Client($http).

Для обновления методов по опубликованным схемам выполните python tools/generate.py (Python 3.10+), просмотрите изменения в API.md и запустите проверку. Методы v4.9 сверяются с архивной схемой и актуальной документацией Google.

kith-web-studio / google-business-profile-php

Package info

Security

Statistics