Deutsche Version

Back to overview

Newsletter Management: Technical details

This documentation always describes the latest published version.

This page describes the structure and internals of the plugin for integrators and developers: how signup and sending flow, the layout, the tables and the most important design decisions.

Architecture

Signups go through exactly one entry point, the NewsletterSubscriptionManager. Whether it is the storefront form, the registration checkbox or the Shop API, all call the same methods to subscribe, confirm, update and unsubscribe. The footer teaser does not call the manager itself; it hands over to the form on /newsletter via GET. There is no second business logic for the API.

graph TD
    A["Storefront: form, registration"] --> M["NewsletterSubscriptionManager"]
    B["Shop API: processors and provider"] --> M
    M --> E{"PRE_SUBSCRIBE event"}
    E -->|"rejected"| R["Rejected: flash or 422"]
    E -->|"allowed"| P["Save subscription"]
    P --> ML["NewsletterMailer: confirmation, welcome, already subscribed"]
    P --> S["Sync of the customer newsletter flag"]
    P --> T["Tracking: consent and deletion"]

Sending runs separately, driven by cron:

graph LR
    C["Cron: mmd:newsletter:send"] --> SV["NewsletterSendingService"]
    SV --> D["Claim deliveries"]
    D --> MS["NewsletterMailSender"]
    MS --> RE["NewsletterRenderer"]
    RE --> TH["Theme of the channel"]
    RE --> LT["NewsletterLinkTracker"]
    MS --> TR["Symfony Mailer"]
    ADM["Admin: send, schedule, cancel"] --> SV

Plugin structure

sylius-newsletter-management/
├── assets/            admin and shop assets
├── config/
│   ├── config.yaml
│   ├── mailer.yaml    e-mail codes of the three subscriber mails
│   ├── services.php   all services in one file
│   ├── grids/         admin grids
│   ├── routes/        admin.yaml, shop.yaml
│   └── twig_hooks/    admin.yaml, shop.yaml
├── src/
│   ├── Api/           Shop API: processors, provider, query extension
│   ├── Command/       setup, send, subscription:purge, tracking:purge
│   ├── Controller/    storefront, dashboard, preview, sending, tracking, export
│   ├── DependencyInjection/
│   ├── Entity/        entities, interfaces and enums
│   ├── Event/         PRE_SUBSCRIBE
│   ├── EventListener/ customer checkbox, delete guard
│   ├── Factory/
│   ├── Form/          form types and models
│   ├── Mailer/        subscriber mails
│   ├── Manager/       NewsletterSubscriptionManager
│   ├── Menu/          admin menu
│   ├── Migrations/    11 Doctrine migrations
│   ├── Newsletter/    placeholders, renderer, text generator, theme, URLs
│   ├── Repository/
│   ├── Sender/        newsletter sending per recipient
│   ├── Sending/       sending orchestration
│   ├── Settings/      per-channel settings, privacy link, consent text
│   ├── Statistics/    numbers for the dashboard and newsletter detail
│   ├── Sync/          sync with the customer newsletter flag
│   ├── Tracking/      link tracker, recorder, signer
│   └── Twig/          Twig extension
├── templates/         admin, emails, shop
├── tests/             Unit, Integration, Functional, TestApplication
└── translations/      messages, flashes, validators (de, en)

Entities and tables

All tables carry the prefix mmd_sylius_newsletter_management_.

There are also three join tables: ..._subscription_category (the categories of a subscription), ..._newsletter_category (a newsletter's audience) and ..._category_channel (the channels a category is offered in; empty = all).

erDiagram
    SUBSCRIPTION }o--o{ CATEGORY : "chooses"
    NEWSLETTER }o--o{ CATEGORY : "audience"
    CATEGORY ||--o{ CATEGORY_TRANSLATION : "translated by"
    NEWSLETTER ||--o{ DELIVERY : "delivery log"
    SUBSCRIPTION |o--o{ DELIVERY : "receives"
    NEWSLETTER ||--o{ LINK : "tracks"
    NEWSLETTER ||--o{ TRACKING_HIT : "counts"
    NEWSLETTER ||--o{ TRACKING_EVENT : "records"
    SUBSCRIPTION ||--o{ TRACKING_EVENT : "triggers"

Enums (PHP backed enums, no tables of their own):

Migrations

The plugin ships 11 migrations. They are applied with bin/console mmd:newsletter-management:setup (see Installation).

Design decisions

• One entry point for subscriptions. The NewsletterSubscriptionManager is the only place that subscribes, confirms, updates and unsubscribes. Storefront and Shop API differ only in how they take input and produce output. Before it saves or sends anything, it dispatches the PRE_SUBSCRIBE event (see Extending).
• Cron instead of Messenger. Sending is a console command. A worker for an async queue is infrastructure the plugin cannot assume in someone else's shop, and an unrouted Messenger message would run inside the admin request. A run can safely overlap with another.
• Recipients are fixed at the start. There is exactly one delivery per newsletter and address (unique key). Nobody gets the same newsletter twice, whatever runs concurrently.
• Atomic claiming. Every delivery is claimed before sending. A claim that is never finished goes back to waiting after 15 minutes, and a failed send is tried up to three times.
• Counters without database-specific features. The recorder increments counters portably: first an UPDATE, an INSERT when it hit zero rows, and another UPDATE if a concurrent request created the row in between. There is no ON DUPLICATE KEY.
• Signed tracking URLs. TrackingSigner builds an HMAC-SHA256 over kernel.secret and uses the first 32 characters. It is meant to stop probing, not to authenticate. Links carry only a code (the first 16 characters of the URL's SHA-256); the target lives in the database.
• A foreign key that protects the log. A delivery log row's reference to the subscription is set to SET NULL, not CASCADE. If a subscription is deleted, the log and its address stay. Tracking events, in contrast, hang off the subscription with CASCADE and disappear with it. The subscription's references to channel and customer are SET NULL as well.
• Placeholders instead of Twig. Placeholders are a fixed list filled in by plain string substitution. That does not hand authors the whole Twig runtime.
• The channel's theme. A decorator of the Sylius theme context switches to the newsletter channel's theme for the duration of one render and restores it afterwards. Otherwise the cron job, which has no request, would render the bare Sylius layout.

Tests

Development

Development happens exclusively inside the container (PHP 8.3, MySQL 8.4, nginx). A local PHP is not intended.

These commands are for developing the plugin itself. You do not need them to run it in your shop.