api library
3.1.0
يمكنك تثبيت مكتبة API مع الأمر التالي:
composer require mautic/api-library NB تأكد من تثبيت عميل HTTP PSR-18 قبل تثبيت هذه الحزمة أو تثبيت واحدة في نفس الوقت على سبيل المثال composer require mautic/api-library guzzlehttp/guzzle:^7.3 .
لقد تم فصلنا عن أي عميل مراسلة HTTP بمساعدة عميل PSR-18 HTTP. يتطلب هذا حزمة إضافية توفر تنفيذ PSR/HTTP-Client. لاستخدام Guzzle 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 تتيح واجهة برمجة تطبيقات Mautic. إذا كنت تنوي استخدام المصادقة الأساسية ، فتأكد من تمكينها. يمكنك أيضًا اختيار بروتوكول OAuth الذي يجب استخدامه هنا. بعد حفظ التكوين ، انتقل إلى صفحة بيانات اعتماد API (الموجودة في قائمة الإعدادات) وإنشاء عميل جديد. أدخل رد الاتصال/إعادة توجيه URI الذي سيتم إرسال الطلب منه. انقر فوق تطبيق ، ثم انسخ معرف العميل وسرية العميل إلى التطبيق الذي سيستخدم واجهة برمجة التطبيقات.
الخطوة الأولى هي الحصول على إذن. يدعم 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 بدلاً من ذلك.
فيما يلي نسخة 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 ' ,
],
],
];الآن بعد أن حصلت على رمز الوصول وكائن 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 الذي يضع الأمور تلقائيًا لك. إنه clones https://github.com/mautic/mautic ، يقوم بإعداد مثيل محلي لك ، ويقوم بتوصيل اختبارات مكتبة API بهذه المثيل.
للبدء ، تشغيل ddev start ! تجربتنا الأولى ستوجهك خلال الإعداد.
إذا كنت ترغب في إعداد بيئتك المحلية يدويًا ، فتأكد من نسخ /tests/local.config.php.dist إلى /tests/local.config.php ، وملء الإعدادات المطلوبة. نوصي باستخدام طريقة المصادقة الأساسية للاستعداد والتشغيل بسرعة.
قم بتكوين Config Enters Config قبل تشغيل اختبارات الوحدة. اختبارات النار تطلب API Real API إلى مثيل mautic.
composer test لتشغيل الاختبارات. تعديل هذا الأمر لتشغيل اختبار محدد: composer test -- --filter testCreateGetAndDelete tests/Api/NotesTest.php
قم بتعديل هذا الأمر لتشغيل جميع الاختبارات في فئة واحدة: composer test -- --filter test tests/Api/NotesTest.php
شكراً لهؤلاء الأشخاص الرائعين (مفتاح الرموز التعبيرية):
Zdeno Kuzmany | Dlopez-akalam | مولوكس | مارتينا شولز | جون لينهارت ؟ | مارينوس فان فيلزن | بيير أميلوت ؟ |
مارتن فوريما |
يتبع هذا المشروع مواصفات جميع المساهمين. مساهمات من أي نوع ترحيب!
