Mailchimp API 3.0 PHP

جدول المحتويات

• Mailchimp API 3.0 PHP
  • تثبيت
  • إنشاء مثيل
  • OAuth
  • بناء الطلب
    • يحصل
    • بريد
    • التصحيح والوضع
    • يمسح
  • التعامل مع الاستجابة
  • عمليات الاسترجاعات
  • مخطط الطريقة (*باستثناء الأفعال)
  • ويكي - انظر لمزيد من الوثائق المتعمقة

Mailchimp API 3.0 PHP

هذه مكتبة PHP للتفاعل مع الإصدار 3.0 من واجهة برمجة تطبيقات MailChimp

تفترض هذه المكتبة فهمًا أساسيًا لتطبيق MailChimp والوظائف المرتبطة به.

تثبيت

لتشغيل الملحن:

composer require jhut89/mailchimp3php

وبدلاً من ذلك، يمكنك إضافة سطر مطلوب إلى مشروعك composer.json للحزمة jhut89/mailchimp3php .

ثم قم بتشغيل composer update وأضف أداة التحميل التلقائي للملحن إلى مشروعك باستخدام:

 require " vendor/autoload.php " ;

يمكنك بعد ذلك استخدام عبارة الاستخدام لسحب فئة Mailchimp:

 use MailchimpAPI  Mailchimp ;

إنشاء مثيل

 $ mailchimp = new Mailchimp ( ' 123abc123abc123abc123abc-us0 ' );

لإنشاء مثيل، ستحتاج إلى مثيل جديد لفئة Mailchimp مع مفتاح API الخاص بحساب MailChimp الخاص بك باعتباره الوسيط الوحيد.

OAuth

إذا كنت تستخدم OAuth للحصول على رمز وصول، فيمكن لهذه المكتبة التعامل مع "المصافحة" نيابةً عنك.

يجب عليك أولاً إرسال المستخدم إلى تطبيقاتك authorize_uri . يمكنك الحصول على عنوان url هذا عن طريق استدعاء Mailchimp::getAuthUrl() بشكل ثابت:

 $ client_id =   ' 12345676543 ' ;
$ redirect_url =  ' https://www.some-domain.com/callback_file.php ' ;

Mailchimp:: getAuthUrl ( $ client_id , $ redirect_url );

اختياريًا، إذا كنت بحاجة إلى تمرير معلومات الحالة مع طلبك حتى يمكن توجيه استجابة رد الاتصال بشكل صحيح، فيمكنك تضمين معلمة الحالة:

 $ client_id =   ' 12345676543 ' ;
$ redirect_url =  ' https://www.some-domain.com/callback_file.php ' ;

// state information encoded into a string to be included in the URL, for example data encoded in a JWT token
$ state = ' eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c ' ; 

Mailchimp:: getAuthUrl ( $ client_id , $ redirect_url , $ state );

ومن هناك، سيقوم المستخدم بإدخال اسم المستخدم وكلمة المرور الخاصة به للموافقة على طلبك وسيتم إعادة توجيهه إلى redirect_uri الذي قمت بتعيينه مع code .

باستخدام هذا code يمكنك الآن طلب رمز وصول من mailchimp. لهذا ستحتاج إلى استدعاء الأسلوب Mailchimp::oauthExchange() بشكل ثابت مثل هذا:

 $ code = ' abc123abc123abc123abc123 ' ;
$ client_id =   ' 12345676543 ' ;
$ client_secret =  ' 789xyz789xyz789xyz789xyz ' ;
$ redirect_url =  ' https://www.some-domain.com/callback_file.php ' ;

Mailchimp:: oauthExchange ( $ code , $ client_id , $ client_secret , $ redirect_url );

إذا نجحت عملية المصافحة، فستُرجع هذه الطريقة سلسلة تحتوي على مفتاح API الخاص بك مثل هذا: 123abc123abc123abc123abc123abc-us0 . يمكن الآن استخدام مفتاح API هذا لإنشاء مثيل لفئة Mailchimp الخاصة بك كما فعلنا أعلاه.

بناء الطلب

بمجرد إنشاء مثيل لفئة Mailchimp ، يمكنك البدء في إنشاء الطلبات. يتم إنشاء الطلبات عن طريق أساليب "التسلسل" إلى مثيل $mailchimp . في معظم الحالات، تنتهي هذه "السلسلة" بفعل HTTP الخاص بطلبك.

يحصل

مثال على كيفية استرداد مجموعة القائمة:

 $ mailchimp
    -> lists ()
    -> get ();

يمكن استرداد المثيل عن طريق إعطاء معرف فريد للمثيل الذي تريده كوسيطة للطريقة المناسبة. على سبيل المثال، إذا أردت استرداد نسخة قائمة من المثال أعلاه، فسأقوم ببساطة بتمرير list_id ، باعتباره الوسيط الوحيد للأسلوب lists() . مثله:

 $ mailchimp
    -> lists ( ' 1a2b3c4d ' )
    -> get ();

تعتمد الطرق المتاحة لكل موضع في السلسلة على ما ترجعه الطريقة السابقة. على سبيل المثال، إذا أردت استرداد المشتركين من قائمة في حسابي سأقوم بما يلي:

 $ mailchimp
    -> lists ( ' 1a2b3c4d ' )
    -> members ()
    -> get ();

لاحظ أنني قدمت list_id إلى طريقة lists() ، حيث لن تكون هناك طريقة لاسترداد قائمة المشتركين من مجموعة قوائم. ومع ذلك، فإن الطلب أعلاه سيعيد 10 حالات مشتركين فقط من مجموعة الأعضاء. وذلك لأن واجهة برمجة التطبيقات الخاصة بـ MailChimp تستخدم ترقيم الصفحات (الموثق هنا) والذي يكون count=10 offset=0 . تسمح لك هذه المكتبة بتغيير معلمات سلسلة الاستعلام عن طريق تمريرها كوسيطة إلى أسلوب GET() . نقوم بذلك من خلال توفير مجموعة من أزواج القيمة الرئيسية حيث تكون المفاتيح هي معلمة الاستعلام التي ترغب في توفيرها/تعديلها وقيمتها هي قيمة المعلمة. على سبيل المثال، إذا أردت استرداد الـ 100 مشترك الثاني من قائمتي، فيمكنني:

 $ mailchimp
    -> lists ( ' 1a2b3c4d ' )
    -> members ()
    -> get ([
        " count " => " 100 " , 
        " offset " => " 100 "
    ]);

سيكون هذا معادلاً لتقديم طلب الحصول على:

 Https://us0.api.mailchimp.com/3.0/lists/1a2b3c4d/members?count=100&offset=100

بالمضي قدمًا، يمكننا استرداد عضو قائمة واحد عن طريق إعطاء members_hash (تجزئة md5 لعنوان صغير) إلى الأسلوب members() . مثله:

 $ mailchimp
    -> lists ( ' 1a2b3c4d ' )
    -> members ( ' 8bdbf060209f35b52087992a3cbdf4d7 ' )
    -> get ();

وبدلاً من ذلك، بدلاً من توفير تجزئة md5 كمعرف لوظيفة members() ، يمكنك توفير عنوان البريد الإلكتروني لجهة اتصال كسلسلة وستقوم هذه المكتبة بالتجزئة نيابةً عنك. مثله:

 $ mailchimp
    -> lists ( ' 1a2b3c4d ' )
    -> members ( ' [email protected] ' )
    -> get ();

يمكنك القراءة عن طلبات GET بعمق هنا: https://github.com/Jhut89/Mailchimp-API-3.0-PHP/wiki/Get-Requests

بريد

على الرغم من أن القدرة على استرداد البيانات من حسابك أمر رائع، إلا أننا نحتاج أيضًا إلى أن نكون قادرين على نشر بيانات جديدة. يمكن القيام بذلك عن طريق استدعاء طريقة POST() في نهاية السلسلة. كمثال، سيبدو اشتراك عنوان في القائمة كما يلي:

 $ post_params = [
    ' email_address ' => ' [email protected] ' , 
    ' status ' => ' subscribed '
];

$ mailchimp
    -> lists ( ' 1a2b3c4d ' )
    -> members ()
    -> post ( $ post_params );

في هذه الحالة لن أقوم بتزويد members() بمعرف لأنني أريد نشره في مجموعته. لاحظ أيضًا أن بيانات النشر عبارة عن مصفوفة من أزواج القيمة الرئيسية التي تمثل المعلمات التي أرغب في تمريرها إلى واجهة برمجة تطبيقات MailChimp. تأكد من توفير كافة الحقول المطلوبة لنقطة النهاية التي تقوم بالنشر إليها. تحقق من وثائق MailChimp لمعرفة المعلمات المطلوبة. يمكن فقط إضافة المعلمات غير المطلوبة إلى بيانات المنشور، وسيتجاهل MailChimp أي معلمات غير قابلة للاستخدام. للتوضيح هنا مثال لإضافة مشترك إلى قائمة مع بعض المعلمات غير المطلوبة:

 $ merge_values = [
    " FNAME " => " John " ,
    " LNAME " => " Doe "
];

$ post_params = [
    " email_address " => " [email protected] " , 
    " status " => " subscribed " , 
    " email_type " => " html " , 
    " merge_fields " => $ merge_values
]

$ mailchimp
    -> lists ( ' 1a2b3c4d ' )
    -> members ()
    -> post ( $ post_params );

يمكنك القراءة عن طلبات POST بعمق هنا: https://github.com/Jhut89/Mailchimp-API-3.0-PHP/wiki/Post-Requests

التصحيح والوضع

تتعامل هذه المكتبة مع طلب PUT وPATCH بشكل مشابه لطلبات POST. وهذا يعني أن كلاً من PUT() و PATCH() يقبلان مجموعة من أزواج القيمة الرئيسية التي تمثل البيانات التي ترغب في تغييرها/تقديمها إلى MailChimp. على سبيل المثال، إذا كنت أقوم بتصحيح المشترك الذي اشتركنا فيه أعلاه، للحصول على اسم أول جديد، فسيبدو ذلك بهذا الشكل.

 $ mailchimp
    -> lists ( ' 1a2b3c4d ' )
    -> members ( ' a1167f5be2df7113beb69c95ebcdb2fd ' )
    -> patch ([
        " merge_fields " => [ " FNAME " => " Jane " ]
    ]);

يمكنك القراءة عن طلبات PATCH & PUT بعمق هنا: https://github.com/Jhut89/Mailchimp-API-3.0-PHP/wiki/Patch-&-Put-Requests

يمسح

يتم حذف سجل من MailChimp باستخدام طريقة DELETE() ويتم إنشاؤه بشكل مشابه لطلبات GET. إذا أردت حذف المشترك أعلاه سأفعل:

 $ mailchimp
    -> lists ( ' 1a2b3c4d ' )
    -> members ( ' a1167f5be2df7113beb69c95ebcdb2fd ' )
    -> delete ();

يمكنك القراءة عن طلبات DELETE بعمق هنا: https://github.com/Jhut89/Mailchimp-API-3.0-PHP/wiki/Delete-Requests

التعامل مع الاستجابة

التوابع المسماة لأفعال http مثل get() أو post() أو patch() أو put() أو delete() تبدأ طلبًا عبر السلك إلى واجهة برمجة تطبيقات MailChimp. عند الحصول على طلب ناجح، تقوم هذه الطرق بإرجاع مثيل MailchimpResponse . أقترح أن تتعرف على هذا الفصل نظرًا لوجود عدد من المعدلات والحروف لأجزاء مختلفة من الاستجابة.

هناك عدد من الحروف التي يمكننا استخدامها للتفاعل مع أجزاء مثيل MailchimpResponse الخاص بنا. بعض من أكثر شيوعا هي:

 $ response -> deserialize (); // returns a deserialized (to php object) resource returned by API
$ response -> getHttpCode (); // returns an integer representation of the HTTP response code
$ response -> getHeaders (); // returns response headers as an array of key => value pairs
$ response -> getBody (); // return the raw text body of the response

على سبيل المثال، إذا كنت أملك مفتاح واجهة برمجة التطبيقات (API) ولكنني أريد البريد الإلكتروني لجهة الاتصال المرتبط بحسابه:

 $ mailchimp = new Mailchimp ( ' 123abc123abc123abc123abc-us0 ' );
$ account = $ mailchimp
    -> account ()
    -> get ()
    
$ contact_email = $ account
    -> deserialize ()
    ->email
    
print $ contact_email ; // outputs something like "[email protected]"

يمكنك القراءة حول كيفية التعامل مع الاستجابات بعمق هنا: https://github.com/Jhut89/Mailchimp-API-3.0-PHP/wiki/Handling-A-Response

مخطط الطريقة (*باستثناء الأفعال)

  mailchimp()                       
  |                                 
  |----account()                    
  |                                 
  |----apps()                       
  |                                 
  |----automations()                
  |    |                            
  |    |----removedSubscribers()    
  |    |----emails()                
  |         |                       
  |         |---queue()*             
  |         |---pauseAll()*         
  |         |---startAll()*        
  |                                 
  |----batches()                    
  |                                 
  |----batchWebhooks()              
  |                                 
  |----campaignFolders()            
  |                                 
  |----campaigns()                  
  |    |                            
  |    |----cancel()*                
  |    |----pause()*                 
  |    |----replicate()*             
  |    |----resume()*                
  |    |----scedule()*              
  |    |----send()*                  
  |    |----test()*                  
  |    |----unschedule()*            
  |    |----checklist()             
  |    |----feedback()              
  |    |----content()
  |
  |----connectedSites()
  |    |
  |    |----verifyScriptInstallation()*               
  |                                 
  |----conversations()              
  |    |                            
  |    |----messages()              
  |                                 
  |----ecommStores()                
  |    |                            
  |    |----customers()             
  |    |----products()              
  |    |    |                       
  |    |    |----variants()         
  |    |    |----images()           
  |    |     
  |    |----promoRules()
  |    |    |
  |    |    |----promoCodes()
  |    |                   
  |    |----orders()                
  |    |    |                       
  |    |    |----lines()            
  |    |                            
  |    |----carts()                 
  |         |                       
  |         |----lines()
  |
  |----facebookAds()            
  |                                 
  |----fileManagerFiles()           
  |                                 
  |----fileManagerFolders()
  |
  |----googleAds()
  |
  |----landingPages()
  |    |
  |    |----publish()*
  |    |----unpublish()*
  |    |----content()         
  |                                 
  |----lists()                      
  |    |                            
  |    |----batchSubscribe()*             
  |    |----webhooks()              
  |    |----signupForms()           
  |    |----mergeFields()           
  |    |----growthHistory()         
  |    |----clients()               
  |    |----activity()              
  |    |----abuseReports()          
  |    |----segments()              
  |    |    |                       
  |    |    |----batch()*            
  |    |    |----members()          
  |    |                            
  |    |----members()               
  |    |    |                       
  |    |    |---notes()             
  |    |    |---goals()             
  |    |    |---activity()
  |    |    |---tags()          
  |    |                            
  |    |----interestCategories()    
  |         |                       
  |         |----interests()        
  |    
  |----ping()
  |                             
  |----reports()                    
  |    |                            
  |    |----unsubscribes()          
  |    |----subReports()            
  |    |----sentTo()                
  |    |----locations()             
  |    |----emailActivity() 
  |    |----googleAnalytics()
  |    |----openDetails()        
  |    |----eepurl()                
  |    |----domainPerformance()     
  |    |----advice()                
  |    |----abuse()                 
  |    |----clickReports()          
  |         |                       
  |         |----members()          
  |                                 
  |----searchCampaigns()            
  |                                 
  |----searchMembers()              
  |                                 
  |----templateFolders()            
  |                                 
  |----templates()                  
  |    |                            
  |    |----defaultContent()        
  |                             
  |----verifiedDomains()
       |
       |----verify()                            

*يرجى الاطلاع على وثائق واجهة برمجة التطبيقات الخاصة بـ MailChimp للتعرف على الأفعال المناسبة في أي مكان.

** الطرق المميزة بعلامة * تقديم طلب شبكة

** يرجى مشاهدة التحديثات، ولا تتردد في طلب Fork أو Pull. قم بمراجعة Wiki للحصول على مزيد من المعلومات حول المساهمة.