README

A Charcoal service provider mailchimp implementation.

Table of Contents

• Installation
  • Dependencies
• Service Provider
  • Parameters
  • Services
• Configuration
• Usage
• Development
  • API Documentation
  • Development Dependencies
  • Coding Style
• Credits
• License

Installation

The preferred (and only supported) method is with Composer:

$ composer require locomotivemtl/charcoal-contrib-mailchimp

Dependencies

Required

• PHP 5.6+: PHP 7 is recommended.

Configuration

Include the mailchimp module in the projects's config file. This will provide everything needed for charcoal-contrib-mailchimp to work properly.

{
    "modules": {
       "charcoal/mailchimp/mailchimp": {}
    }
}

Add the api key (Account > Settings > Extra > Api keys) in the config apis:

"apis": {
    "mailchimp": {
        "key": "myapikey-usXX"
    }
}

Usage

charcoal-contrib-mailchimp comes with a set of tools to help setup a newsletter subscription.

Properties

There are 2 different property types you can use to either select an audience or a signup form for a given audience.

Mailchimp List

Set your property as follow.

    "type": "string",
    "input_type": "charcoal/admin/property/input/mailchimp-list",
    "mailchimp_options": {
        "query_parameters": {
            "count": 20
        }
    }

You can customize the displayed label, the displayed title, the value and the subtext pattern. It is also possible to add query parameters (see Doc) Default as follow:

"mailchimp_options": {
    "title_pattern": "{{name}}",
    "value_pattern": "{{id}}",
    "label_pattern": "{{name}}",
    "subtext_pattern": "Web ID: {{id}}",
    "query_parameters": []
}

Mailchimp Signup Form

    "type": "string",
    "input_type": "charcoal/admin/property/input/mailchimp-form",
    "mailchimp_options": {
        [...]
    }

You can customize the displayed label, the displayed title, the value and the subtext pattern. Default as follow:

"mailchimp_options": {
    "title_pattern": "{{header.text}}",
    "value_pattern": "{{signup_form_url}}",
    "label_pattern": "{{header.text}}",
    "subtext_pattern": "Form URL: {{signup_form_url}}"
}

User subscription

class FooBar
{
    use MailchimpAwareTrait;
    [...]

    public function setDependencies(Container $container)
    {
        $this->setMailchimpListsMembers($container['mailchimp/lists/members']);
        [...]
    }
    
    public function run()
    {
        $user = [
            'email_address' => 'email@example.com',
            'status' => 'pending',
            'merge_fields' => [
                'FNAME' => 'John',
                'LNAME' => 'Doe'
            ]
        ];
        
        // Set list ID
        $listId = 'a4029db2d';
        $this->mailchimpListsMembers()->setListId($listId);
        
        // Add/Create user
        $results = $this->mailchimpListsMembers()->add($user);
        
        // Add or Update user
        $results = $this->mailchimpListsMembers()->addOrUpdate($user);
        
        // Get a user's informations
        $results = $this->mailchimpListsMembers()->get('email@example.com');        
        
        // Delete a user from a list
        $results = $this->mailchimpListsMembers()->remove('email@example.com');
    }
}

The mailchimp service is standalone and can be used directly if you know the endpoints by using the post, patch, get, put and delete methods.

// Get lists members
$this->mailchimp()->get('lists/{list_id}/members');

// Add member to list
$this->mailchimp()->post('list/{list_id}/members', [ 
    'email_address' => 'email@example.com',
    'status' => 'pending'
]);

Coding Style

The charcoal-contrib-mailchimp module follows the Charcoal coding-style:

• PSR-1
• PSR-2
• PSR-4, autoloading is therefore provided by Composer.
• phpDocumentor comments.
• phpcs.xml.dist and .editorconfig for coding standards.

Coding style validation / enforcement can be performed with composer phpcs. An auto-fixer is also available with composer phpcbf.

Credits

• Locomotive

License

Charcoal is licensed under the MIT license. See LICENSE for details.