Скачать api library - Скачать исходный код api library

Использование библиотеки Mautic API

Требования

PHP 8.0 или более новее

Установка библиотеки API

Вы можете установить библиотеку API со следующей командой:

composer require mautic/api-library

Nb Убедитесь, что вы установили клиент HTTP PSR-18, прежде чем установить этот пакет или установить его одновременно, например composer require mautic/api-library guzzlehttp/guzzle:^7.3 .

Http client

Мы отделены от любого клиента HTTP-сообщений с помощью клиента HTTP PSR-18. Это требует дополнительного пакета, обеспечивающего PSR/HTTP-клиент-внедрение. Например, для использования Guzze 7 просто требуется guzzlehttp/guzzle :

composer require guzzlehttp/guzzle:^7.3

Установленный HTTP-клиент автоматически обнаруживается с использованием PHP-HTTP/Discovery, но вы также можете предоставить свой собственный HTTP-клиент, если хотите.

 <?php

// Bootup the Composer autoloader
include __DIR__ . ' /vendor/autoload.php ' ;  

use GuzzleHttp  Client ;
use Mautic  Auth  ApiAuth ;

// Initiate an HTTP Client
$ httpClient = new Client ([
    ' timeout '  => 10 ,
]);

// Initiate the auth object
$ initAuth = new ApiAuth ( $ httpClient );
$ auth     = $ initAuth -> newAuth ( $ settings );
// etc.

Маутическая установка

API должен быть включен в Mautic. В Mautic перейдите на страницу конфигурации (расположенную в меню «Настройки»), а в настройках API включает API Mautic. Если вы собираетесь использовать базовую аутентификацию, убедитесь, что вы включите ее. Вы также можете выбрать, какой протокол OAuth использовать здесь. После сохранения конфигурации перейдите на страницу учетных данных API (расположенную в меню «Настройки») и создайте нового клиента. Введите вызов/перенаправить URI, из которого будет отправлен запрос. Нажмите «Применить», затем скопируйте идентификатор клиента и секрет клиента в приложение, которое будет использовать API.

Авторизация

Получение токена доступа

Первый шаг - получить разрешение. Mautic поддерживает OAuth 1.0A и OAuth 2, однако администратор должен решить, что включено. Таким образом, лучше всего иметь вариант конфигурации в вашем проекте для администратора, чтобы выбрать, какой метод следует использовать вашим кодом.

 <?php

// Bootup the Composer autoloader
include __DIR__ . ' /vendor/autoload.php ' ;  

use Mautic  Auth  ApiAuth ;

session_start ();

$ publicKey = '' ;
$ secretKey = '' ;
$ callback  = '' ;

// ApiAuth->newAuth() will accept an array of Auth settings
$ settings = [
    ' baseUrl '          => '' ,       // Base URL of the Mautic instance
    ' version '          => ' OAuth2 ' , // Version of the OAuth can be OAuth2 or OAuth1a. OAuth2 is the default value.
    ' clientKey '        => '' ,       // Client/Consumer key from Mautic
    ' clientSecret '     => '' ,       // Client/Consumer secret key from Mautic
    ' callback '         => '' ,       // Redirect URI/Callback URI for this script
];

/*
// If you already have the access token, et al, pass them in as well to prevent the need for reauthorization
$settings['accessToken']        = $accessToken;
$settings['accessTokenSecret']  = $accessTokenSecret; //for OAuth1.0a
$settings['accessTokenExpires'] = $accessTokenExpires; //UNIX timestamp
$settings['refreshToken']       = $refreshToken;
*/

// Initiate the auth object
$ initAuth = new ApiAuth ();
$ auth     = $ initAuth -> newAuth ( $ settings );

// Initiate process for obtaining an access token; this will redirect the user to the $authorizationUrl and/or
// set the access_tokens when the user is redirected back after granting authorization

// If the access token is expired, and a refresh token is set above, then a new access token will be requested

try {
    if ( $ auth -> validateAccessToken ()) {

        // Obtain the access token returned; call accessTokenUpdated() to catch if the token was updated via a
        // refresh token

        // $accessTokenData will have the following keys:
        // For OAuth1.0a: access_token, access_token_secret, expires
        // For OAuth2: access_token, expires, token_type, refresh_token

        if ( $ auth -> accessTokenUpdated ()) {
            $ accessTokenData = $ auth -> getAccessTokenData ();

            //store access token data however you want
        }
    }
} catch ( Exception $ e ) {
    // Do Error handling
}

Вместо этого использование основной аутентификации

Вместо того, чтобы возиться с OAuth, вы можете просто использовать вместо этого использовать Basicauth.

Вот базовая версия кода выше.

 <?php

// Bootup the Composer autoloader
include __DIR__ . ' /vendor/autoload.php ' ;  

use Mautic  Auth  ApiAuth ;

session_start ();

// ApiAuth->newAuth() will accept an array of Auth settings
$ settings = [
    ' userName '   => '' ,             // Create a new user       
    ' password '   => '' ,             // Make it a secure password
];

// Initiate the auth object specifying to use BasicAuth
$ initAuth = new ApiAuth ();
$ auth     = $ initAuth -> newAuth ( $ settings , ' BasicAuth ' );

// Nothing else to do ... It's ready to use.
// Just pass the auth object to the API context you are creating.

Примечание. Если учетные данные неверны, ответ на ошибку будет возвращен.

 [
    ' errors ' => [
        [
            ' code '    => 403 ,
            ' message ' => ' access_denied: OAuth2 authentication required ' ,
            ' type '    => ' access_denied ' ,
        ],
    ],
 ];

API запросы

Теперь, когда у вас есть токен доступа и объект Auth, вы можете сделать запросы API. API разбит на контексты.

Получить объект контекста

 <?php

use Mautic  MauticApi ;

// Create an api context by passing in the desired context (Contacts, Forms, Pages, etc), the $auth object from above
// and the base URL to the Mautic server (i.e. http://my-mautic-server.com/api/)

$ api        = new MauticApi ();
$ contactApi = $ api -> newApi ( ' contacts ' , $ auth , $ apiUrl );

Поддерживаемые контексты в настоящее время:

Смотрите документацию разработчика.

Получение предметов

Все вышеперечисленные контексты подтверждают следующие функции для получения элементов:

 <?php

$ response = $ contactApi -> get ( $ id );
$ contact  = $ response [ $ contactApi -> itemName ()];

// getList accepts optional parameters for filtering, limiting, and ordering
$ response      = $ contactApi -> getList ( $ filter , $ start , $ limit , $ orderBy , $ orderByDir );
$ totalContacts = $ response [ ' total ' ];
$ contact       = $ response [ $ contactApi -> listName ()];

Создание предмета

 <?php

$ fields = $ contactApi -> getFieldList ();

$ data = array ();

foreach ( $ fields as $ field ) {
    $ data [ $ field [ ' alias ' ]] = $ _POST [ $ field [ ' alias ' ]];
}

// Set the IP address the contact originated from if it is different than that of the server making the request
$ data [ ' ipAddress ' ] = $ ipAddress ;

// Create the contact
$ response = $ contactApi -> create ( $ data );
$ contact  = $ response [ $ contactApi -> itemName ()];

Редактирование предмета

 <?php

$ updatedData = [
    ' firstname ' => ' Updated Name '
];

$ response = $ contactApi -> edit ( $ contactId , $ updatedData );
$ contact  = $ response [ $ contactApi -> itemName ()];

// If you want to create a new contact in the case that $contactId no longer exists
// $response will be populated with the new contact item
$ response = $ contactApi -> edit ( $ contactId , $ updatedData , true );
$ contact  = $ response [ $ contactApi -> itemName ()];

Удаление предмета

 <?php

$ response = $ contactApi -> delete ( $ contactId );
$ contact  = $ response [ $ contactApi -> itemName ()];

Обработка ошибок

 <?php

// $response returned by an API call should be checked for errors
$ response = $ contactApi -> delete ( $ contactId );

if ( isset ( $ response [ ' errors ' ])) {
    foreach ( $ response [ ' errors ' ] as $ error ) {
        echo $ error [ ' code ' ] . " : " . $ error [ ' message ' ];
    }
}

Внося

Настройка вашей среды (автоматически)

Чтобы начать быстро, мы рекомендуем использовать DDEV, который автоматически устанавливает вещи для вас. Он клонирует https://github.com/mautic/mautic, устанавливает для вас локальный экземпляр и подключает тесты библиотеки API к этому экземпляру.

Чтобы начать, запустите ddev start ! Наш первый опыт проведет вас через установку.

Настройка вашей среды (вручную)

Если вы хотите настроить свою локальную среду вручную, убедитесь, что вы копируете /tests/local.config.php.dist to /tests/local.config.php и заполните необходимые настройки. Мы рекомендуем использовать базовый метод аутентификации, чтобы быстро встать и работать.

Модульные тесты

Настройте конфигурацию модульных тестов перед запуском модульных тестов. Тесты стреляют в реальные запросы API в экземпляр Mautic.

Убедитесь, что вы настроили свою локальную среду, используя приведенные выше шаги.
Запустите composer test , чтобы запустить тесты.

Измените эту команду для запуска конкретного теста: composer test -- --filter testCreateGetAndDelete tests/Api/NotesTest.php

Измените эту команду, чтобы запустить все тесты в одном классе: composer test -- --filter test tests/Api/NotesTest.php

Участники

Спасибо этим замечательным людям (ключ эмодзи):

_{Здена Кузмани}	_{Длопес-Акалам}	_Mollux	_{Мартина Шольц}	_{Джон Линхарт} ?	_{Маринус Ван Велзен}	_{Пьер Аммелут} ?
_{Мартин Воремаэ} ️