Add notice about vouchers to the bulky item docs

[heimrich-hannot]

Since I stumbled over this topic this week, I propose to add a notice about adding the vouchers to tokens.

[koertho]

Sorry, was me making this PR, wrong account 😅

[Copilot]

Pull Request Overview

This PR enhances the bulky items documentation by adding guidance on how to add vouchers to tokens when using certain gateways, specifically addressing a practical requirement for the mailer gateway.

• Adds a new documentation section explaining when and how to add vouchers to tokens
• Provides a concrete PHP code example showing how to format vouchers for the mailer gateway
• Includes a minor whitespace fix at the end of the file

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Toflar]

I don't really like this addition because it's confusing to me.

Of course you need to add it as a token? Everything that can be selected by the users must be a token.
So to me, it's the other way around. You don't need to "also add it as a token". You always need to add it as a token if you want users to be able to select them. Only tokens can be selected.

But if you want to provide file type tokens (FileTokenDefinition or AnythingTokenDefinition), you also have to add the voucher IDs via stamp. The reasons for that are already documented right in that article :)

What exactly happened that you created this PR? Did you just add bulky item vouchers via stamp but no tokens? Why?

[fritzmg]

What exactly happened that you created this PR? Did you just add bulky item vouchers via stamp but no tokens? Why?

Presumably because the documentation currently says

Done. A gateway can now use those vouchers to actually ask for the bulky items when sending them. This could look for example like this:

<?php

$item = $this->getNotificationCenter()->getBulkyItemStorage()->retrieve($voucher);

if ($item instanceof FileItem) {
    $email->attach(
        $item->getContents(),
        $item->getName(),
        $item->getMimeType()
    );
}

My assumption is that this is meant as a generalized example and thus not necessarily reflect how the Mailer gateway that ships with the Notification Center does it.

[koertho]

The docs in short say: create a bulky item and add the voucher as a stamp — done.
But this is not enough, at least not for all gateways. I don't see any harm in adding a note that could have saved me an hour of debugging. For you, it might be obvious that a token also needs to be added, but for me, it wasn’t — at least not based on the current documentation.