Sylius Mailchimp Plugin

Overview

This plugin has three main purposes:

1. Push your customers (as members/subscribers) to Mailchimp
2. Push your orders to Mailchimp utilizing their ecommerce features
3. Allow your customers to sign up for newsletters both in the checkout, but also using a form on your page

It does all this in a memory saving and performance optimized way.

Installation

1. Install dependencies

This plugin uses the Doctrine ORM Batcher bundle. Install that first by following the instructions on that page.

2. Require plugin with composer:

$ composer require setono/sylius-mailchimp-plugin

3. Import configuration:

# config/packages/setono_sylius_mailchimp.yaml
imports:
    - { resource: "@SetonoSyliusMailchimpPlugin/Resources/config/app/config.yaml" }
        
setono_sylius_mailchimp:
    api_key: '%env(MAILCHIMP_API_KEY)%'

Remember to update your .env and .env.local files:

# .env

###> setono/sylius-mailchimp-plugin ###
MAILCHIMP_API_KEY=
###< setono/sylius-mailchimp-plugin ###

# .env.local

###> setono/sylius-mailchimp-plugin ###
MAILCHIMP_API_KEY=INSERT YOUR API KEY HERE
###< setono/sylius-mailchimp-plugin ###

4. Import routing:

# config/routes/setono_sylius_mailchimp.yaml
setono_sylius_mailchimp:
    resource: "@SetonoSyliusMailchimpPlugin/Resources/config/routing.yaml"

5. Add plugin class to your bundles.php:

$bundles = [
    // ...
    
    // Notice that the Mailchimp plugin has to be added before the SyliusGridBundle
    Setono\SyliusMailchimpPlugin\SetonoSyliusMailchimpPlugin::class => ['all' => true],
    Sylius\Bundle\GridBundle\SyliusGridBundle::class => ['all' => true],
    Setono\DoctrineORMBatcherBundle\SetonoDoctrineORMBatcherBundle::class => ['all' => true],
    
    // ...
];

Make sure you add the plugin before SyliusGridBundle. Otherwise you'll get exception like You have requested a non-existent parameter "setono_sylius_mailchimp.model.audience.class".

6. Override core classes

Override Customer resource

<?php
// src/Entity/Customer/Customer.php

declare(strict_types=1);

namespace App\Entity\Customer;

use Sylius\Component\Core\Model\Customer as BaseCustomer;
use Setono\SyliusMailchimpPlugin\Model\CustomerInterface as SetonoSyliusMailchimpPluginCustomerInterface;
use Setono\SyliusMailchimpPlugin\Model\CustomerTrait as SetonoSyliusMailchimpPluginCustomerTrait;
use Doctrine\ORM\Mapping as ORM;
    
/**
 * @ORM\Entity
 * @ORM\Table(name="sylius_customer")
 */
class Customer extends BaseCustomer implements SetonoSyliusMailchimpPluginCustomerInterface
{
    use SetonoSyliusMailchimpPluginCustomerTrait;
}

Override Order resource

<?php
// src/Entity/Order/Order.php

declare(strict_types=1);

namespace App\Entity\Order;

use Sylius\Component\Core\Model\Order as BaseOrder;
use Setono\SyliusMailchimpPlugin\Model\OrderInterface as SetonoSyliusMailchimpPluginOrderInterface;
use Setono\SyliusMailchimpPlugin\Model\OrderTrait as SetonoSyliusMailchimpPluginOrderTrait;
use Doctrine\ORM\Mapping as ORM;

/**
 * @ORM\Entity
 * @ORM\Table(name="sylius_order")
 */
class Order extends BaseOrder implements SetonoSyliusMailchimpPluginOrderInterface
{
    use SetonoSyliusMailchimpPluginOrderTrait;
}

Override Channel resource

<?php
// src/Entity/Channel/Channel.php

declare(strict_types=1);

namespace App\Entity\Channel;

use Sylius\Component\Core\Model\Channel as BaseChannel;
use Setono\SyliusMailchimpPlugin\Model\ChannelInterface as SetonoSyliusMailchimpPluginChannelInterface;
use Setono\SyliusMailchimpPlugin\Model\ChannelTrait as SetonoSyliusMailchimpPluginChannelTrait;
use Doctrine\ORM\Mapping as ORM;

/**
 * @ORM\Entity
 * @ORM\Table(name="sylius_channel")
 */
class Channel extends BaseChannel implements SetonoSyliusMailchimpPluginChannelInterface
{
    use SetonoSyliusMailchimpPluginChannelTrait;
}

Create CustomerRepository.php

<?php
// src/Doctrine/ORM/CustomerRepository.php

declare(strict_types=1);

namespace App\Doctrine\ORM;

use Setono\SyliusMailchimpPlugin\Repository\CustomerRepositoryInterface as SetonoSyliusMailchimpPluginCustomerRepositoryInterface;
use Setono\SyliusMailchimpPlugin\Doctrine\ORM\CustomerRepositoryTrait as SetonoSyliusMailchimpPluginCustomerRepositoryTrait;
use Sylius\Bundle\CoreBundle\Doctrine\ORM\CustomerRepository as BaseCustomerRepository;

class CustomerRepository extends BaseCustomerRepository implements SetonoSyliusMailchimpPluginCustomerRepositoryInterface
{
    use SetonoSyliusMailchimpPluginCustomerRepositoryTrait;
}

Create OrderRepository.php

<?php
// src/Doctrine/ORM/OrderRepository.php

declare(strict_types=1);

namespace App\Doctrine\ORM;

use Setono\SyliusMailchimpPlugin\Repository\OrderRepositoryInterface as SetonoSyliusMailchimpPluginOrderRepositoryInterface;
use Setono\SyliusMailchimpPlugin\Doctrine\ORM\OrderRepositoryTrait as SetonoSyliusMailchimpPluginOrderRepositoryTrait;
use Sylius\Bundle\CoreBundle\Doctrine\ORM\OrderRepository as BaseOrderRepository;

class OrderRepository extends BaseOrderRepository implements SetonoSyliusMailchimpPluginOrderRepositoryInterface
{
    use SetonoSyliusMailchimpPluginOrderRepositoryTrait;
}

Add configuration

# config/packages/_sylius.yaml
sylius_channel:
    resources:
        channel:
            classes:
                model: App\Entity\Channel\Channel

sylius_customer:
    resources:
        customer:
            classes:
                model: App\Entity\Customer\Customer
                repository: App\Doctrine\ORM\CustomerRepository
                
sylius_order:
    resources:
        order:
            classes:
                model: App\Entity\Order\Order
                repository: App\Doctrine\ORM\OrderRepository

7. Update your database:

$ php bin/console doctrine:migrations:diff
$ php bin/console doctrine:migrations:migrate

8. Install assets:

$ php bin/console assets:install

Step 9: Using asynchronous transport (optional, but very recommended)

All commands in this plugin will extend the CommandInterface. Therefore, you can route all commands easily by adding this to your Messenger config:

# config/packages/messenger.yaml
framework:
    messenger:
        routing:
            # Route all command messages to the async transport
            # This presumes that you have already set up an 'async' transport
            # See docs on how to setup a transport like that: https://symfony.com/doc/current/messenger.html#transports-async-queued-messages
            'Setono\SyliusMailchimpPlugin\Message\Command\CommandInterface': async

10. Copy templates:

Copy templates located in test directory (tests/Application/templates/bundles/ link) into your templates directory, and modify to your needs

11. Clear cache:

$ php bin/console cache:clear

12. Define fixtures

# fixtures.yaml

sylius_fixtures:
    suites:
        default:
            fixtures:
                setono_mailchimp:
                    options:
                        custom:
                          - name: 'United States audience'
                            audience_id: '0598aea4e3'
                            channel: 'FASHION_WEB'
                          - name: 'Denmark audience'
                            audience_id: '0e23b9524f'
                            channel: 'DK_WEB'

Usage

The pushing of entities uses the mailchimp state machine:

When the state is pending, the entities are pushed to Mailchimp. As you can see from the image both the updating and failing of an entity is handled by the state machine.

By default, the plugin can push customers and orders to Mailchimp.

Push customers

Run the following command to push customers:

$ php bin/console setono:sylius-mailchimp:push-customers

Push orders

Run the following command to push orders:

$ php bin/console setono:sylius-mailchimp:push-orders

Insert subscription form

To insert the subscription form anywhere on your site, just do the following in twig:

{% include '@SetonoSyliusMailchimpPlugin/Shop/subscribe.html.twig' %}

You can of course also use the BlockEventListener:

<service id="app.block_event_listener.shop.subscribe_to_newsletter" class="Sylius\Bundle\UiBundle\Block\BlockEventListener">
    <argument>@SetonoSyliusMailchimpPlugin/Shop/subscribe.html.twig</argument>

    <tag name="kernel.event_listener" event="sonata.block.event.sylius.shop.layout.after_footer" method="onBlockEvent"/>
</service>

In this case - you should disable default block event listener:

setono_sylius_mailchimp:
  subscribe: false

Troubleshooting

Associating a channel to an audience

When associating an audience to a channel, if you are greeted with such message :

Verify that your channel has an address, if not define it and try to re-submit the form.

Contribution

Run composer try to setup plugin environment and try test application.

Please, run composer all before pusing changes to run all checks and tests.

Testing

Run composer tests to run all tests.