| @@ -242,8 +242,16 @@ | ||
| 242 | 242 | ``` |
| 243 | 243 | |
| 244 | 244 | The adapter plans one action per side effect (`planActions()`), executes the claimed ones and returns a `FollowUpResult` per action (`execute()`), and releases resources once everything is done (`onSettled()`). Return `FollowUpResult::unknown()` whenever you cannot tell whether a side effect happened. |
| 245 | 245 | |
| 246 | +**Global adapters (since 5.8.0).** An adapter that applies to every form — a webhook, a CRM sync — implements `GlobalFollowUpAdapterInterface` instead and is registered the same way. Its actions are added to the plan of every opt-in whose form has an adapter, stored under its own `getIntegration()` name, and get the same status, retry and admin view. Rules: | |
| 247 | + | |
| 248 | +- every action id starts with `<getIntegration()>:` (e.g. `webhooks:42`); other ids are dropped when planning | |
| 249 | +- `execute()` and `onSettled()` receive only the adapter's own actions; the form adapter always executes first | |
| 250 | +- a failing `planActions()` or `execute()` affects only the adapter's own actions | |
| 251 | +- if the add-on is deactivated later, its open actions are recorded as `failed_permanent` with code `adapter_missing`; a manual retry runs them once it is back | |
| 252 | +- nothing runs after an opt-out, as for every other action | |
| 253 | + | |
| 246 | 254 | ### `f12_doi_follow_up_backoff` (filter) |
| 247 | 255 | |
| 248 | 256 | Delays in seconds between automatic retries of actions that demonstrably did not run (e.g. the internal request never reached the server). The number of entries is the maximum number of automatic retries. Default `[60, 300, 1800]`; `[]` disables automatic retries. A manual retry from the admin starts a fresh budget: the schedule applies again from its first entry. |
| 249 | 257 | |
| @@ -323,8 +331,10 @@ | ||
| 323 | 331 | | `f12_cf7_doubleoptin_enable_error_notification` | `$enable` (bool) | `bool` | Return `false` to not load the frontend error toast at all (default: `true`, since 4.2.0) | |
| 324 | 332 | | `f12_cf7_doubleoptin_error_message` | `$message` (string), `$error` (OptInError), `$formId` (int) | `string` | Customize the error message per error code (since 4.2.0) | |
| 325 | 333 | | `f12_cf7_doubleoptin_validate_recipient` | `$valid` (bool), `$recipient`, `$formData` | `bool\|string` | Validate recipient email; return error string to reject | |
| 326 | 334 | | `f12_cf7_doubleoptin_send_default_mail` | `$send` (bool), `$formId` | `bool` | Whether to send the original form mail after confirmation | |
| 335 | +| `f12_doi_submit_notice_data` | `$notice` (array: `masked`, `lines`, `inbox`, `actions`), `$context` (array: `form_id`, `optin_id`, `integration`) | `array` | The hint shown after a CF7 double opt-in submission. Add `lines`, or `actions`: links (`type` `link`, `url` must be https) or buttons (`id`, `label`, optional `wait` in seconds and scalar `data`). A button fires the DOM event `f12-doi-notice-action` on the form with `{ id, data, button, form }`. `$context` stays on the server; sign your own token into `data` if your script needs to refer back to the opt-in (since 5.8.0) | | |
| 336 | +| `f12_doi_form_field_texts` | `$texts` (array: field name => plain text), `$formId` (int\|string), `$integration` (string) | `array` | The text a visitor reads next to a field, typically a consent checkbox. The form settings compare it with the stored consent text and offer to take it over. Contact Form 7 fills it from `[acceptance]…[/acceptance]`; a form integration can implement `FieldTextProviderInterface` instead of using the filter (since 5.9.0) | | |
| 327 | 337 | | `f12_doi_enforce_consent_gate` | `$enforce` (bool), `$formId` (int), `$integration` (string) | `bool` | Return `false` to accept a submission whose configured acceptance field was not confirmed. The opt-in is then stored with a consent text nobody agreed to, so this is an escape hatch for an unforeseen edge case, not a setting (since 5.4.0) | |
| 328 | 338 | |
| 329 | 339 | ### Mail Filters |
| 330 | 340 | |
| @@ -330,8 +340,9 @@ | ||
| 330 | 340 | |
| 331 | 341 | | Filter | Parameters | Return | Description | |
| 332 | 342 | |--------|-----------|--------|-------------| |
| 333 | 343 | | `f12_cf7_doubleoptin_body` | `$body` (string) | `string` | Modify the opt-in confirmation email body | |
| 344 | +| `f12_doi_mail_headers` | `$headers` (string[] header lines), `$optInId` (int), `$kind` (`confirmation`, `resend` or `reminder`) | `string[]` | Add or change headers of the double opt-in's own mails — whichever integration sends them. Other mails of the same request are not passed through. Line breaks inside a line are removed. Without a callback the mail is left exactly as built (since 5.8.0) | | |
| 334 | 345 | | `f12-cf7-doubleoptin-cf7-args` | `$args` (array) | `array` | Modify mail arguments (subject, body, headers, attachments) | |
| 335 | 346 | | `f12_cf7_doubleoptin_files_mail_1` | `$include` (bool), `$optIn` | `bool` | Include file attachments in the first confirmation mail | |
| 336 | 347 | | `f12_cf7_doubleoptin_files_mail_2` | `$include` (bool), `$optIn` | `bool` | Include file attachments in the second confirmation mail | |
| 337 | 348 | | `f12_cf7_doubleoptin_allowed_mime_types` | `$mimeTypes` (array) | `array` | Modify allowed MIME types for file uploads | |
| @@ -537,8 +548,39 @@ | ||
| 537 | 548 | | `getRowsDeleted()` | `int` | Number of records deleted | |
| 538 | 549 | | `getThreshold()` | `DateTimeImmutable` | The cutoff date | |
| 539 | 550 | |
| 540 | 551 | **WordPress hook:** `f12_cf7_doubleoptin_expired` |
| 552 | + | |
| 553 | +#### `OptInOptedOutEvent` | |
| 554 | + | |
| 555 | +Dispatched when a confirmed consent is withdrawn (since 5.8.0). The core | |
| 556 | +never withdraws a consent itself: the Opt-Out add-on (1.5.0 or later) fires | |
| 557 | +this once per opt-in that actually changed. Listen here instead of depending | |
| 558 | +on the Opt-Out add-on. | |
| 559 | + | |
| 560 | +| Method | Return | Description | | |
| 561 | +|--------|--------|-------------| | |
| 562 | +| `getOptInId()` | `int` | The opt-in ID | | |
| 563 | +| `getHash()` | `string` | The opt-in hash | | |
| 564 | +| `getEmail()` | `string` | The subscriber email | | |
| 565 | +| `getFormId()` | `int` | The form the consent was given in | | |
| 566 | +| `getSource()` | `string` | `'link'` (opt-out link), `'bulk'` (all consents of one address) or `'one-click'` (mailbox unsubscribe button) | | |
| 567 | + | |
| 568 | +**WordPress hook:** `f12_doi_optin_opted_out` (receives the event object) | |
| 569 | + | |
| 570 | +#### `OptInReOptedInEvent` | |
| 571 | + | |
| 572 | +Dispatched when a withdrawn consent is given again from the subscriber's | |
| 573 | +list in the Opt-Out add-on (since 5.8.0). | |
| 574 | + | |
| 575 | +| Method | Return | Description | | |
| 576 | +|--------|--------|-------------| | |
| 577 | +| `getOptInId()` | `int` | The opt-in ID | | |
| 578 | +| `getHash()` | `string` | The opt-in hash | | |
| 579 | +| `getEmail()` | `string` | The subscriber email | | |
| 580 | +| `getFormId()` | `int` | The form ID | | |
| 581 | + | |
| 582 | +**WordPress hook:** `f12_doi_optin_reopted_in` (receives the event object) | |
| 541 | 583 | |
| 542 | 584 | --- |
| 543 | 585 | |
| 544 | 586 | ### Form Events |
