README

mailchimp-bundle

This bundle will help you synchronise your project's newsletter subscribers into MailChimp.

You can synchronize all your subscribers at once with a Symfony command : new users will be added to MailChimp, existing users will be updated and user no longer in your project will be deleted from MailChimp.

You can also synchronize subscribe / unsubscribe one at a time with events.

Optionnaly, it also help you to synchronize your list merge tags.

Setup
Configuration
Usage

Setup

Add bundle to your project:

composer require betacie/mailchimp-bundle

Add Betacie\MailChimpBundle\BetacieMailChimpBundle to your AppKernel.php:

$bundles = [
    // ...
    new Betacie\MailChimpBundle\BetacieMailChimpBundle(),
];

Configuration

You need to add the list in MailChimp's backend first.

For each list you must define a configuration in your config.yml:

betacie_mailchimp:
    api_key: YOURMAILCHIMPAPIKEY
    lists:
        list1:
            # optional language option, used only in full synchronization
            mc_language: 'fr'

            # optional merge tags you want to synchronize
            merge_tags:
                -
                    tag: FIRSTTAG
                    name: My first tag
                    options: {"field_type":"radio", "choices": ["foo", "bar"]}
                -
                    tag: SECONDTAG
                    name: My second tag
                    
            # provider used in full synchronization
            subscriber_providers: 'yourapp.provider1'

        list2:
            subscriber_providers: 'yourapp.provider2'

Where listX is the name of your MailChimp lists, and yourapp.providerX is the key of your provider's service that will provide the subscribers that need to be synchronized in MailChimp. The key mc_language is optional and will set this language for all subscribers in this list, see the list of accepted language codes.

Defining lists and providers is necessary only if you use full synchronization with the command.

Usage

Synchronize merge tags

Merge tags (or merge vars) are values you can add to your subscribers (for example the firstsname or birthdate of your user). You can then use these tags in your newsletters or create segments out of them.

To learn more about merge tags, please see this guide on MailChimp.

To synchronize you need to create your lists in MailChimp backend first. Then you need to add them in your config.yml as shown in the above configuration. The options you can provide are the same as the one found in MailChimp API.

You can then synchronize the tags using the app/console betacie:mailchimp:synchronize-merge-tags command. Note that every tag that are present in MailChimp but are not defined in your configuration will be deleted along with associated values.

Full synchronization with command

You can synchronize all subscribers of your project at once by calling the Symfony command app/console betacie:mailchimp:synchronize-subscribers. It will first fetch all the subscribers already present in MailChimp and unsubscribe any subscribers that are not in your projet (they might have been deleted on the project side), it will then send all your subscribers to MailChimp, new subscribers will be added and existing subscribers will be updated.

After configuring your lists in config.yml, you need to create at least one Providerthat will be used by the Symfony command. Your provider should be accessible via a service key (the same you reference in subscriber_providers in the configuration above):

services:
    yourapp_mailchimp_subscriber_provider:
        class: YourApp\App\Newsletter\SubscriberProvider
        arguments: [@yourapp_user_repository]

It should implement Betacie\MailChimpBundle\Provider\ProviderInterface and return an array of Betacie\MailChimpBundle\Subscriber\Subscriber objects. The first argument of the Subscriber object is its e-mail, the second argument is an array of merge tags values you need to add in MailChimp's backend in your list settings under List fields and *|MERGE|* tags (see this guide on MailChimp to add merge tags in your list).

<?php

namespace YourApp\App\Newsletter;

use Betacie\MailchimpBundle\Provider\ProviderInterface;
use Betacie\MailchimpBundle\Subscriber\Subscriber;
use YourApp\Model\User\UserRepository;
use YourApp\Model\User\User;

class SubscriberProvider implements ProviderInterface
{
    // these tags should match the one you added in MailChimp's backend
    const TAG_NICKNAME =           'NICKNAME';
    const TAG_GENDER =             'GENDER';
    const TAG_BIRTHDATE =          'BIRTHDATE';
    const TAG_LAST_ACTIVITY_DATE = 'LASTACTIVI';
    const TAG_REGISTRATION_DATE =  'REGISTRATI';
    const TAG_CITY =               'CITY';

    protected $userRepository;

    public function __construct(UserRepository $userRepository)
    {
        $this->userRepository = $userRepository;
    }

    public function getSubscribers()
    {
        $users = $this->userRepository->findSubscribers();

        $subscribers = array_map(function(User $user) {
            $subscriber = new Subscriber($user->getEmail(), [
                self::TAG_NICKNAME => $user->getNickname(),
                self::TAG_GENDER => $user->getGender(),
                self::TAG_BIRTHDATE => $user->getBirthdate() ? $user->getBirthdate()->format('Y-m-d') : null,
                self::TAG_CITY => $user->getCity(),
                self::TAG_LAST_ACTIVITY_DATE => $user->getLastActivityDate() ? $user->getLastActivityDate()->format('Y-m-d') : null,
                self::TAG_REGISTRATION_DATE => $user->getRegistrationDate() ? $user->getRegistrationDate()->format('Y-m-d') : null,
                // you don't need to specify "mc_language" tag if you added it in your config
                // you can also use all MailChimp configuration tags here as well
            ]);

            return $subscriber;
        }, $users);

        return $subscribers;
    }
}

Unit synchronization with events

If you want realtime synchronization, you can dispatch custom events on your controllers (or anywhere). The subscribe event can be used both for adding a new subscriber or updating an existing one.

Here is an example of a subscribe event dispatch:

<?php

use Betacie\MailchimpBundle\Event\SubscriberEvent;
use Betacie\MailchimpBundle\Subscriber\Subscriber;

// ...

public function newUser(User $user)
{
    // ...
	
    $subscriber = new Subscriber($user->getEmail(), [
		'FIRSTNAME' => $user->getFirstname(),
		'mc_language' => 'fr',
		// Important note : mc_language defined in config.yml will not be used, be sure to set it here if needed
		// as well as any other MailChimp tag you need.
	]);

	$this->container->get('event_dispatcher')->dispatch(
        SubscriberEvent::EVENT_SUBSCRIBE,
        new SubscriberEvent('your_list_name', $subscriber)
    );
}

If you want to tell MailChimp that an existing subscriber has changed its e-mail, you can do it by adding the new-email option to the merge tags:

<?php

use Betacie\MailchimpBundle\Event\SubscriberEvent;
use Betacie\MailchimpBundle\Subscriber\Subscriber;

// ...

public function changedEmail($previousMail, $newEmail)
{
    // ...
	
    $subscriber = new Subscriber($previousEmail, [
		 'new-email' => $newEmail
    ]);

    $this->container->get('event_dispatcher')->dispatch(
        SubscriberEvent::EVENT_SUBSCRIBE,
        new SubscriberEvent('your_list_name', $subscriber)
    );
}

Unsubscribe is simpler, you only need the email, all merge tags will be ignored:

<?php

use Betacie\MailchimpBundle\Event\SubscriberEvent;
use Betacie\MailchimpBundle\Subscriber\Subscriber;

// ...

public function deletedUser(User $user)
{
    // ...
	
    $subscriber = new Subscriber($user->getEmail());

    $this->container->get('event_dispatcher')->dispatch(
        SubscriberEvent::EVENT_UNSUBSCRIBE,
        new SubscriberEvent('your_list_name', $subscriber)
    );
}

betacie / mailchimp-bundle

Maintainers

Details