Deutsche Version

Back to overview

Newsletter Management: Installation and Operation

This documentation always describes the latest published version.

Installation

Composer (Packeton)

Note: The repository is private and managed through Packeton (https://packeton.markus-michalski.net). You receive the credentials after purchasing a license.

Add Packeton as a repository in your shop's composer.json:

{ "repositories": [{ "type": "composer", "url": "https://packeton.markus-michalski.net" }] }

Then install the plugin:

composer require mmd/sylius-newsletter-management-plugin

Afterwards, in exactly this order:

1. Register the bundle in config/bundles.php:

   Mmd\SyliusNewsletterManagementPlugin\MmdSyliusNewsletterManagementPlugin::class => ['all' => true],
   

2. Import the routes, for example in config/routes/mmd_newsletter_management.yaml:

   mmd_sylius_newsletter_management_admin:
       resource: "@MmdSyliusNewsletterManagementPlugin/config/routes/admin.yaml"
   
   mmd_sylius_newsletter_management_shop:
       resource: "@MmdSyliusNewsletterManagementPlugin/config/routes/shop.yaml"
   

   The admin routes are built on the sylius_admin.path_name parameter, so you do not need a prefix of your own.

3. Run the setup command:

   bin/console mmd:newsletter-management:setup
   

Grids, Twig hooks and the mail template register themselves. The plugin ships no assets you would have to install, so assets:install is not needed.

The setup command

mmd:newsletter-management:setup replaces doctrine:migrations:migrate and does the following:

• It runs only the open migrations of this plugin, nothing from your app or other plugins.
• It is idempotent: with no new migration nothing happens, so you can safely run it again after every composer update. The only source of truth is the doctrine_migration_versions table, which is why it also notices a migration that is missing after a database restore.
• It checks that the routes from step 2 are imported and prints the snippet if they are not. It never writes to config/.
• It aborts if migrations from the Sylius core are still open, telling you to run bin/console doctrine:migrations:migrate first.
• It asks for confirmation interactively. In scripts, use --no-interaction.
• Run it as the same user as your other console commands.

bin/console doctrine:migrations:migrate works as well, but it runs all open migrations of your project, not only those of this plugin.

First steps after installation

1. In the admin, go to MMKreativ Plugins → Newsletter management.
2. For every channel that should offer a newsletter, create a configuration and enable it.

A channel without an enabled configuration offers no signup: /newsletter and the Shop API answer 404, there is no footer form, and the Sylius core newsletter checkbox stays untouched.

The settings are described in detail under Configuration.

Optionally, adapt the colors of the confirmation button in the mails to your theme:

# config/packages/mmd_sylius_newsletter_management.yaml
mmd_sylius_newsletter_management:
    email:
        button_color: '#1663CC'
        button_text_color: '#ffffff'

Without this, #1abb9c (button) and #ffffff (text) apply. Both values must be hex colors.

Update

composer update mmd/sylius-newsletter-management-plugin
bin/console mmd:newsletter-management:setup
bin/console cache:clear

The setup command is idempotent and runs only new migrations.

Cron jobs

Newsletters are sent by a console command, not inside the admin request.

Without the cron job for mmd:newsletter:send no newsletter goes out: "Send now" and "Schedule" in the admin only queue the sending.

Options:

Example crontab:

* * * * * cd /path/to/shop && php bin/console mmd:newsletter:send --limit=100
15 3 * * * cd /path/to/shop && php bin/console mmd:newsletter:subscription:purge
20 3 * * * cd /path/to/shop && php bin/console mmd:newsletter:tracking:purge

Overlapping runs of mmd:newsletter:send are safe: every delivery is claimed atomically, and a claim that a crashed run never finished is released after 15 minutes. Why the plugin does not use Messenger is explained under Technical details.

You set the retention periods themselves per channel, see Configuration and Tracking and statistics.

Dedicated mailer transport

Recommended: in the channel's newsletter settings, the field Mailer transport for newsletters names a Symfony Mailer transport from framework.mailer.transports. That way bulk mail can neither exhaust the transport your shop mail (orders, password reset) uses nor damage its reputation. Empty means the default transport. The sender address must fit that transport's SPF and DKIM.

Uninstalling

Keep this order so the migrations are rolled back while the bundle is still registered:

1. Remove your own template overrides of the plugin (templates/bundles/MmdSyliusNewsletterManagementPlugin/, if present) and your own uses of its Twig functions and hooks.

2. Roll back the migrations, one version at a time, newest first. This drops all newsletter tables including the subscribers:

   bin/console doctrine:migrations:execute --down 'Mmd\SyliusNewsletterManagementPlugin\Migrations\Version20261001110000'
   bin/console doctrine:migrations:execute --down 'Mmd\SyliusNewsletterManagementPlugin\Migrations\Version20261001100000'
   bin/console doctrine:migrations:execute --down 'Mmd\SyliusNewsletterManagementPlugin\Migrations\Version20260930170000'
   bin/console doctrine:migrations:execute --down 'Mmd\SyliusNewsletterManagementPlugin\Migrations\Version20260930160000'
   bin/console doctrine:migrations:execute --down 'Mmd\SyliusNewsletterManagementPlugin\Migrations\Version20260930150000'
   bin/console doctrine:migrations:execute --down 'Mmd\SyliusNewsletterManagementPlugin\Migrations\Version20260930140000'
   bin/console doctrine:migrations:execute --down 'Mmd\SyliusNewsletterManagementPlugin\Migrations\Version20260930130000'
   bin/console doctrine:migrations:execute --down 'Mmd\SyliusNewsletterManagementPlugin\Migrations\Version20260930120000'
   bin/console doctrine:migrations:execute --down 'Mmd\SyliusNewsletterManagementPlugin\Migrations\Version20260930110000'
   bin/console doctrine:migrations:execute --down 'Mmd\SyliusNewsletterManagementPlugin\Migrations\Version20260930100000'
   bin/console doctrine:migrations:execute --down 'Mmd\SyliusNewsletterManagementPlugin\Migrations\Version20260929094744'
   

3. Remove the route import (config/routes/mmd_newsletter_management.yaml), the bundle entry in config/bundles.php and, if you created it, config/packages/mmd_sylius_newsletter_management.yaml.

4. Remove the plugin:

   composer remove mmd/sylius-newsletter-management-plugin
   

Rolling back permanently deletes subscribers, newsletters, the delivery log and tracking data. Export the subscriber list as CSV and back up the database first.