Conversation

Comments, contact and newsletter forms, and customer reviews.

Install

composer require pushword/conversation

Custom installations (not the default installer): see vendor/pushword/admin/install.php.

Embed a form

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.

Absolute or relative URL

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.

Spam protection

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.

  • Honeypot: a hidden, unmapped 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.
  • Signed action: the form action carries _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).
  • Quota: 10 accepted messages per hour per IPv4 address or IPv6 /64, shared by every host and form. A message counts once, when a valid submission first gives it a valid author email, the condition for its notification, sent now or later. Form loads, invalid forms, steps without an email (the first step of 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.

Published comments

{{ showConversation(referring[, orderBy = 'createdAt ASC', limit = 0, view]) }}

Mail notifications

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.

Customize individual notifications

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:

VariableValue
messageComplete Message entity, including custom properties
appNameSite name
contentMessage content decoded once with htmlspecialchars_decode; untrusted plain text
authorNameContact name, or ... when null
authorEmailContact email; also used as Reply-To
hostMessage host
referringMessage 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.

Delay one message notification

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.

Customize

Override @PushwordConversation/conversation/conversation.html.twig, or per step {type}Step{step}.html.twig / {type}{referring}Step{step}.html.twig in the same folder.

Add a form type

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}.

Drive the steps yourself

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());
}

Flat sync

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.

  • Merge identity — rows match by 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.
  • Deletion — deleting (admin or API) sets a 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.
  • Stale rows — a row whose 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

{{ 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.

Replies

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'

Translation

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