Comments, contact and newsletter forms, and customer reviews.
composer require pushword/conversation
Custom installations (not the default installer): see vendor/pushword/admin/install.php.
Forms are fetched by their own request, so they work on cached and static pages:
{# Fetched on load #}
<div data-live="{{ conversation('newsletter') }}"></div>
{# Fetched only when a cookie is present #}
<div data-live="{{ conversation('newsletter') }}" data-live-if="cookie:pw_auth=1"></div>
{# Fetched on click; the shorthand obfuscates the URL #}
{{ conversationFormBtn('Register', 'newsletter', 'btn btn-primary') }}
<button data-src-live="{{ conversation('newsletter') }}" class="btn btn-primary">Register</button>
<p>An invitation to <button data-src-live="..." data-target="parent">register</button></p>
{# Rendered server-side #}
{{ render(controller('Pushword\\Conversation\\Controller\\ConversationFormController::show', {type: 'newsletter', referring: 'footer'})) }}
A server-side form carries a signed action valid one day. On a page cached or generated for longer, its first post is refused and the form comes back with a fresh action: prefer data-live there.
data-live and data-src-live are handled by liveBlock() from @pushword/js-helper (already called by its app.js).
conversation(type, referring = type) builds path('pushword_conversation', {type, referring: referring~'_'~host~'/'~slug}) plus ?host= and ?locale=. When you build that URL by hand, pass locale yourself, or the form renders in the site’s default locale.
conversation() and conversationFormBtn() return an absolute URL on the site’s base_live_url, so a statically generated page (no PHP) fetches the form from the live host. That request is cross-origin: allow the static origins in conversation_possible_origins (space-separated, per site or globally under conversation:), and expect the visited host’s cookies not to reach the handler.
Any other origin gets a 403 before its posts count against the visitor’s submission limit (20 per hour per site and IPv4 address or IPv6 /64). An allowed origin gets the CORS headers on every answer, refusals included, so the page sees a 404 or a 429 instead of a network error: the form fires live-block-forbidden with {status, url, retryAfter}, where retryAfter is the 429's Retry-After header (null otherwise).
If the static host proxies /conversation/* to PHP itself, make the URL relative (per site, or globally):
conversation:
conversation_absolute_url: false # default: true
Regenerate static pages afterwards; they keep the URL they were built with.
⚠ The generated Caddyfile 301s any path ending in / to the slash-less one, dropping the query string. A homepage form’s referring ends in / (empty slug), so a relative URL gets rewritten in flight. Set false only where no homepage carries a form, or where the proxied paths are exempt from that redirect.
Every form the pushword_conversation route serves gets three checks, whether it is a built-in type or yours, built from initForm() or straight on FormType. Admin forms and imports are left alone.
homepage field. When it is filled, the form is redisplayed with conversationSubmissionRejected; nothing is saved or sent. A field of your own named homepage replaces the trap._expiration and _hash, signed with kernel.secret, valid one day. A post must use the action of a form fetched for the same host, type, referring page, locale, workflow and step. No session or cookie is involved, so it works from static pages and other domains. It stops scripts that post without fetching a form; it is not CSRF protection, since anyone can fetch a form and reuse its action until it expires. Cross-site posts are refused by the origin check above. An expired form comes back with the visitor’s input and a fresh action. Render the <form> tag with form_start() (or conversation.vars.action).ms_message) and later steps (the newsletter name) cost nothing, and a failed delivery is not refunded. A duplicate (same content and email within ten minutes) is shown as sent but not saved, and still costs one. Over the quota, the form comes back with conversationSubmissionRateLimited.framework:
rate_limiter:
conversation_submit: { limit: 5 } # sliding_window over 1 hour by default
The per-site limit on every POST above still applies. Both messages are errors on the whole form, so a template override must render form_errors(conversation); they are validator translations, overridden in your validators.<locale>.yaml.
{{ showConversation(referring[, orderBy = 'createdAt ASC', limit = 0, view]) }}
Per site, or globally under conversation::
conversation_notification_email_to: 'example@example.tld'
conversation_notification_email_from: 'example@example.tld'
conversation_notification_interval: 'P1D' # default; a PHP DateInterval
Messages with a valid author email are notified one by one. For the others, schedule Pushword\Conversation\Service\NewMessageMailNotifier::send(), which mails a summary at most once per interval.
Override any of these templates in templates/bundles/PushwordConversationBundle/conversation/:
new_message.subject.txt.twig: subject, normalized to one line after rendering.new_message.html.twig: HTML body, with Twig HTML escaping.new_message.txt.twig: plain text body.Their namespace is @PushwordConversation/conversation/. All three receive:
| Variable | Value |
|---|---|
message | Complete Message entity, including custom properties |
appName | Site name |
content | Message content decoded once with htmlspecialchars_decode; untrusted plain text |
authorName | Contact name, or ... when null |
authorEmail | Contact email; also used as Reply-To |
host | Message host |
referring | Message form/page identifier |
Keep {% autoescape false %} around subject and plain text overrides. In HTML, use {{ content|nl2br }} to preserve line breaks while escaping visitor content; never mark it raw. The default plain text keeps the translated sender and form[...] origin markers. Sites parsing notifications should preserve these markers in their overrides. Duplicate content from the same email is suppressed for ten minutes.
The batch summary continues to use notification.html.twig with appName and messages.
Before persisting a new message, opt it into delayed delivery with a positive integer number of seconds. For example, an Altimood quote form waits ten minutes:
$message->setCustomProperty('notificationDelay', 600);
$entityManager->persist($message);
$entityManager->flush();
Messages without this property, or with 0, still notify immediately. The first save sets a fixed notificationSendAfter timestamp in Doctrine; later saves of the same message do not move it. A site can copy its own configurable delay into notificationDelay before that first save; changing the site setting afterwards does not reschedule messages already queued. At delivery, templates receive the latest saved message, including any optional second-step details. After successful delivery, notificationSentAt prevents any further email for that message, even when its content changes later. This persistent state is separate from the immediate path’s ten-minute content cache.
Run pw:conversation:notify-pending every minute, from system cron or the Pushword scheduler:
pushword:
scheduled_commands:
- { command: 'pw:conversation:notify-pending', on: 'cron: * * * * *' }
Keep the scheduler worker running (messenger:consume scheduler_pushword), or install the equivalent system cron. The command itself needs no Messenger transport. It reads the durable queue from Doctrine and sends at most 100 due messages per run. A failed send remains pending for the next run; a lock prevents overlapping workers from sending the same notification. The visitor can abandon the form: delivery depends on this worker, with no HTTP sleep or later browser request required.
To integrate: update the packages, run doctrine:schema:update --force, configure the minute command, clear the caches in every environment used, restart the scheduler worker if applicable, and run the application tests before enabling delivery.
Override @PushwordConversation/conversation/conversation.html.twig, or per step {type}Step{step}.html.twig / {type}{referring}Step{step}.html.twig in the same folder.
Built-in types: newsletter, message, ms_message, multistep_message. Register yours under conversation.conversation_form (globally or per site):
conversation:
conversation_form:
my_type: App\Form\MyForm # implements ConversationFormInterface
An unregistered type falls back to App\Form\{type}.
A form declares getStepOne(), getStepTwo(), … and lets defaultStepValidator() move between them. To run your own transition (an API call before advancing), override validStepN() and use:
advanceStep() — moves to the next step and stores the workflow. The next POST is refused (“Conversation workflow not found”) unless the stored state matches its step, so never call incrementStep() alone.deleteWorkflow() — burns the token; call it before showSuccess() so the last step cannot be replayed.protected function validStepTwo(FormInterface $form): string
{
if (! $form->isValid()) {
return $this->showForm($form);
}
$this->subscribeToNewsletter($this->message);
$this->advanceStep();
return $this->showForm($this->getCurrentStep()->getForm());
}
With the Flat extension, every pw:flat:sync also syncs messages with a CSV: core fields plus one column per custom property (arrays as JSON). Dates are exported as ISO 8601 with their offset; on import (and through the API) an offset is kept to the instant, and a date without one is read in the editorial timezone.
uuid, so databases that no longer travel together (laptop and production SQLite) merge without ids colliding. Unknown uuid: new message; known: updated; messages absent from the CSV are kept and re-exported. A sync never deletes.deletedAt tombstone, hidden everywhere but kept in the database and CSV so the deletion reaches every copy. An empty deletedAt in a stale CSV never resurrects a message; to un-delete, clear the value on each side.updatedAt is older than the database’s is not applied; if its content differs, an admin notification (with email) reports the divergence. Hand-edited rows keep their exported updatedAt and apply.Storage defaults to one content/conversation.csv for every host; the host column is kept in both modes:
conversation:
flat_conversation_global: false # per host: content/<host>/conversation.csv
php bin/console pw:message:flat [host] [-f import|export|sync] # default: auto-detect
php bin/console pw:message:import path/to/conversation.csv [--host=example.com]
{{ reviews(pageOrTag = current page, limit = 10) }} {# alias: reviewList() #}
{{ reviewsCount(pageOrTag) }}
A page matches reviews tagged with its slug. Disable the review admin with conversation.review_enabled: false.
Each review carries a public reply and its author (custom properties), edited at /admin/review — the reply inline in the list, both in the form. The front renders the reply followed by — Reply from {author}.
An empty author falls back to conversation_review_default_reply_author (per site, or globally), where %siteName% is replaced by the site name; saving from the admin writes that default onto the review. With neither, the footer reads “Reply from the team”.
conversation:
conversation_review_default_reply_author: 'The %siteName% team'
Reviews are translated with DeepL, falling back to Google Cloud Translation when DeepL’s monthly limit is reached or it fails:
conversation:
translation_deepl_api_key: '%env(DEEPL_API_KEY)%'
translation_google_api_key: '%env(GOOGLE_API_KEY)%'
translation_deepl_use_free_api: true
translation_deepl_monthly_limit: 450000 # characters, 0 = unlimited
translation_google_monthly_limit: 450000
php bin/console pw:conversation:translate-reviews --locale=fr,de [--host=example.com] [--force] [--dry-run] [--delay=1]
A review without a locale gets the one the API detects. Usage is counted per service and month in the translation_usage table.
review.html.twig shows the translation for page.locale (else the request locale), or the original when there is none.
Fix a translation through the API — only the locales in the payload change, and "fr": null removes one:
curl -X PATCH -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"translations":{"fr":{"title":"Titre","content":"Contenu"}}}' \
https://example.com/api/review/42