api library
3.1.0
Anda dapat menginstal pustaka API dengan perintah berikut:
composer require mautic/api-library NB Pastikan Anda telah menginstal klien PSR-18 HTTP sebelum Anda menginstal paket ini atau menginstal satu pada saat yang sama misalnya composer require mautic/api-library guzzlehttp/guzzle:^7.3 .
Kami dipisahkan dari klien pesan HTTP mana pun dengan bantuan klien HTTP PSR-18. Ini membutuhkan paket tambahan yang menyediakan implementasi PSR/http-klien. Untuk menggunakan Guzzle 7, misalnya, cukup membutuhkan guzzlehttp/guzzle :
composer require guzzlehttp/guzzle:^7.3Klien HTTP yang diinstal ditemukan secara otomatis menggunakan PHP-HTTP/Discovery, tetapi Anda juga dapat menyediakan klien HTTP Anda sendiri jika Anda suka.
<?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 harus diaktifkan di MAUTIC. Dalam Mautic, buka halaman konfigurasi (terletak di menu Pengaturan) dan di bawah Pengaturan API memungkinkan API Mautic. Jika Anda bermaksud menggunakan otentikasi dasar, pastikan Anda mengaktifkannya. Anda juga dapat memilih protokol OAuth mana yang akan digunakan di sini. Setelah menyimpan konfigurasi, buka halaman Kredensial API (terletak di menu Pengaturan) dan buat klien baru. Masukkan callback/redirect uri bahwa permintaan akan dikirim. Klik Terapkan, lalu salin ID klien dan rahasia klien ke aplikasi yang akan menggunakan API.
Langkah pertama adalah mendapatkan otorisasi. Mautic mendukung OAuth 1.0A dan OAuth 2, namun terserah administrator untuk memutuskan mana yang diaktifkan. Dengan demikian, yang terbaik adalah memiliki opsi konfigurasi dalam proyek Anda untuk administrator untuk memilih metode apa yang harus digunakan oleh kode Anda.
<?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
}Alih -alih bermain -main dengan Oauth, Anda dapat memilih untuk menggunakan BasicAuth sebagai gantinya.
Berikut adalah versi BasicAuth dari kode di atas.
<?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.Catatan: Jika kredensial salah, respons kesalahan akan dikembalikan.
[
' errors ' => [
[
' code ' => 403 ,
' message ' => ' access_denied: OAuth2 authentication required ' ,
' type ' => ' access_denied ' ,
],
],
];Sekarang Anda memiliki token akses dan objek auth, Anda dapat membuat permintaan API. API dipecah menjadi konteks.
<?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 );Konteks yang didukung saat ini:
Lihat dokumentasi pengembang.
Semua konteks di atas mendukung fungsi -fungsi berikut untuk mengambil item:
<?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 ' ];
}
}Untuk memulai dengan cepat, kami sarankan Anda menggunakan DDEV yang mengatur segalanya secara otomatis untuk Anda. Ini klon https://github.com/mautic/mautic, mengatur instance lokal untuk Anda, dan menghubungkan tes perpustakaan API ke contoh itu.
Untuk memulai, jalankan ddev start ! Pengalaman pertama kami akan memandu Anda melalui pengaturan.
Jika Anda ingin mengatur lingkungan lokal Anda secara manual, pastikan Anda menyalin /tests/local.config.php.dist ke /tests/local.config.php , dan isi pengaturan yang diperlukan. Kami merekomendasikan menggunakan metode otentikasi dasar untuk bangun dan berjalan dengan cepat.
Konfigurasikan Konfigurasi Tes Unit Sebelum menjalankan tes unit. Tes menembakkan permintaan API nyata ke contoh mautik.
composer test untuk menjalankan tes. Ubah perintah ini untuk menjalankan tes tertentu: composer test -- --filter testCreateGetAndDelete tests/Api/NotesTest.php
Ubah perintah ini untuk menjalankan semua tes dalam satu kelas: composer test -- --filter test tests/Api/NotesTest.php
Terima kasih kepada orang -orang yang luar biasa ini (Kunci Emoji):
Zdeno Kuzmany | Dlopez-Akalam | mollux | Martina Scholz | John Linhart ? | Marinus van Velzen | Pierre Ammeloot ? |
Martin Vooremäe |
Proyek ini mengikuti spesifikasi semua-kontributor. Kontribusi apa pun yang baik!
