README

De Craft 3-editie van de Watchdog-connector. Ze doet hetzelfde als de editie voor Craft 4 en 5: de Watchdog-server kan instellingen opvragen, een testmail versturen, formulieren oplijsten, een testinzending doen en mails opvragen die niet verstuurd konden worden.

Voor de server is er geen verschil. Handle (watchdog), route (/actions/watchdog/api/<actie>), headers, omgevingsvariabele (WATCHDOG_KEY), tabelnamen en de koppelpagina ({cp}/watchdog/pair) zijn dezelfde. Het HTTP-contract is API.md van de Craft 4/5-editie (map craft-plugin); de afwijkingen staan onderaan dit document.

Welke editie voor welke site

Er zijn twee Composer-pakketten. Installeer er nooit twee op dezelfde site.

Site	Pakket
Craft 3 (vanaf 3.7)	`moqo/craft3-watchdog` (dit pakket)
Craft 4 en 5	`moqo/craft-watchdog`

Beide pakketten gebruiken dezelfde namespace en dezelfde plugin-handle; Composer weigert daarom de combinatie (conflict in composer.json). Bij een upgrade van een site naar Craft 4 verwijder je dit pakket en installeer je moqo/craft-watchdog. Een sleutel in .env blijft dan gewoon werken. Koppelingen via het controlepaneel moet je na die overstap opnieuw maken: de Craft 4/5-editie heeft een migratie die de tabel watchdog_pairings opnieuw aanmaakt.

Vereisten

Craft CMS 3.7 of hoger (getest op 3.9.15)
PHP 7.2.5 of hoger: de ondergrens van Craft 3.7 zelf. De code gebruikt niets dat nieuwer is.
Optioneel: Formie 1, Freeform 3 (de enige Freeform-versie die op Craft 3 draait)

Formie en Freeform zijn niet nodig. Zonder formulierplugin werken info, mail-test en failures gewoon; forms geeft een lege lijst en submit antwoordt met 422.

Installatie

Het pakket is privé en staat niet op Packagist. Voeg de bron toe aan composer.json van de site, via de git-repository:

"repositories": [
    { "type": "vcs", "url": "git@github.com:<organisatie>/craft3-watchdog.git" }
]

of, voor lokaal ontwikkelen, via een map op schijf:

"repositories": [
    { "type": "path", "url": "../Watchdog/craft-plugin-craft3" }
]

Daarna:

composer require moqo/craft3-watchdog && php craft plugin/install watchdog

De installatie maakt de tabellen watchdog_failures en watchdog_pairings aan. php craft plugin/uninstall watchdog verwijdert ze weer, samen met alle koppelingen.

Koppelen met Watchdog

Precies zoals bij de Craft 4/5-editie. Beide manieren kunnen naast elkaar bestaan.

Via het controlepaneel. Klik in de Watchdog-app op Verbinden met Craft. De app toont een controlecode en opent {site}/admin/watchdog/pair. Log in als beheerder, controleer dat dezelfde code op de pagina staat en klik op Koppelen. De plugin maakt een sleutel aan en geeft die één keer, rechtstreeks, aan de Watchdog-server; in de database staat alleen de hash. Koppelingen bekijken en intrekken kan onder Instellingen → Plugins → Watchdog-connector, ook op productie waar allowAdminChanges uit staat. Keur alleen goed als je de koppeling net zelf startte en de code klopt.

Met een sleutel in .env. Zet een sleutel van minstens 32 tekens in .env:

WATCHDOG_KEY=<lange willekeurige tekst>

en geef dezelfde sleutel in bij de site in de Watchdog-app. De instelling van de plugin verwijst standaard naar $WATCHDOG_KEY; overschrijven kan in config/watchdog.php ('apiKey' => ...).

Zolang er geen geldige sleutel is en ook geen koppeling via het controlepaneel, antwoordt de plugin op alles met 503. Een ontbrekende of foute sleutel geeft 401.

Wat verschilt van de Craft 4/5-editie

Mail: SwiftMailer in plaats van Symfony Mailer

Craft 3 verstuurt via SwiftMailer. De werkwijze is daardoor anders, het resultaat niet.

Mislukte mails (failures, bron mailer) worden gelezen uit het afterSend-event van de mailer. Craft 3 vangt de fout van het transport op, bewaart ze op het bericht en meldt de verzending als mislukt; de plugin neemt daar de echte foutmelding over (bv. Connection could not be established with host …). Het transport van de site wordt daarvoor niet aangeraakt.
recipient bij submit: alleen tijdens zo'n testinzending zet de plugin een eigen laag rond het SwiftMailer-transport. Die herschrijft elke mail (To vervangen, CC en BCC leeg) op het laatste punt voor ze vertrekt, en doet dat nog eens ná de SwiftMailer-plugins die op het transport geregistreerd zijn. Na de test krijgt de mailer zijn eigen transport terug.
Gebruikt de site een mailer die niet van yii\swiftmailer\Mailer afstamt, dan kan dat niet gegarandeerd worden en weigert submit met recipient met 422, zonder iets te versturen.
Een transport dat een mail weigert zonder fout te geven (alle ontvangers afgewezen) levert buiten een test de algemene melding "Verzenden mislukt; het transport gaf geen foutmelding door." op.

Formie 1

Werkt zoals Formie 2/3 in de andere editie: forms, submit (met en zonder recipient) en het log "Sent Notifications" als bron formie.
Formie 1 verwijdert zijn logregels samen met de inzending. Een mislukte melding van een testinzending die daarna verwijderd wordt (delete: true, de standaard), komt daarom uit de eigen tabel van de connector: zelfde id (formie:<nr>) en source, maar cpUrl is null. Hetzelfde gebeurt als iemand later een echte inzending verwijdert; het id blijft gelijk.

Freeform 3

Op Craft 3 draait alleen Freeform 3; Freeform 4 en 5 vragen Craft 4 of hoger.

Freeform 3 kent geen lijst van meldingen per formulier. forms[].notifications bevat de beheerdersmelding uit de formulierinstellingen en één regel per e-mailveld waaraan een melding hangt (to is dan {veldhandle}). name is de naam van het meldingssjabloon; twee meldingen met hetzelfde sjabloon hebben dus dezelfde naam. enabled is altijd true. Ontvangers die een template met dynamicNotification instelt, zijn niet uit te lezen en staan er niet bij.
submit maakt de inzending aan en voert alleen de mailstap van Freeform uit, rechtstreeks (Freeform 3 gebruikt daar geen wachtrij voor). Betalingen, CRM, mailinglijsten en webhooks worden niet aangesproken.
Veldtypes heten zoals in Freeform 3: select, radio_group, checkbox_group, multiple_select, …
Net als in de andere editie: geen eigen log, mislukte Freeform-mails staan onder mailer met form en submissionId ingevuld.

`info`

mail.encryption is ingevuld (tls / ssl) als de SMTP-instellingen van Craft 3 dat zo zeggen.
craft.devMode komt uit de algemene configuratie.

Overig

Eén installatiemigratie (schemaversie 1.0.0); de tabellen zijn gelijk aan die van de andere editie.
De eigen laag rond het transport bestaat alleen tijdens een testinzending met recipient; in de Craft 4/5-editie zit ze er permanent.

Wat een testinzending overslaat

Validatie, captcha, spamcontrole en integraties. Ontbrekende verplichte velden krijgen een herkenbare testwaarde ("Watchdog test", het adres uit recipient, …). Bestanden, datums, handtekeningen en betaalvelden blijven leeg. Met recipient worden taken die tijdens de test in de wachtrij zouden komen, tegengehouden, zodat er later niets alsnog naar de echte ontvangers gaat.

Geheimen

Geen enkel antwoord bevat het SMTP-wachtwoord, de sleutel of omgevingsvariabelen. Foutmeldingen van het transport worden ingekort (geen stack trace, geen SMTP-dialoog) en het SMTP-wachtwoord en de sleutel worden eruit verwijderd voor ze bewaard of teruggegeven worden.

moqo / craft3-watchdog

Package info

Security

Statistics