feat: Mautic add-on

[eastagiletracker]

This PR proposes a Mautic add-on that turns form submissions into Mautic contacts and adds them to segments (Fixes #20). We include this PR work along with a full history of your repo at https://eastagiletracker.com/projects/1151. You can sign in with your GitHub ID to claim ownership of the project.

What changed

Issue #20 asks for a Mautic add-on, and on current main there is none: ls forms-bridge/addons/mautic fails, and Addon::addon( 'mautic' ) returns null. This PR adds forms-bridge/addons/mautic/, built the same way as the Listmonk and Zulip add-ons, so Addon::registry() picks it up from the add-ons directory with no other wiring needed.

• Backend and credential: the template defaults set up a JSON backend for the Mautic instance URL and a Basic credential (Mautic user and password). The field description reminds the user to enable the API and HTTP basic auth in Mautic's API settings.
• Mautic_Form_Bridge: on POST /api/contacts/new it takes the segments field off the payload, creates the contact, and then calls POST /api/segments/{id}/contact/{contactId}/add for each segment. segments can be an array or a comma-separated string, and duplicates are dropped. A failed segment call, success: 0, or an errors body returned with a 2xx status is passed back as a WP_Error. Mautic returns collections as objects keyed by entity ID, so GET responses for contacts, companies, lists and fields are turned into plain lists. Without that, the template's lists[].id finger cannot read the segments.
• Mautic_Addon: ping() calls GET /api/contacts?limit=1. get_endpoints() returns the contact, company, segment and field endpoints, filtered by method. get_endpoint_schema() reads /api/fields/contact or /api/fields/company, so the mapper offers the instance's own published custom field aliases with their types and required flags, plus tags, segments, owner, ipAddress and overwriteWithBlank.
• Contacts template: an email, first name and last name form, with a multi-select of segments loaded from /api/segments and an optional tags field. A forms_bridge_template_data hook expands the selected segments into integer segments[i] custom fields, the same way the Listmonk template handles lists.

This is all new code, so no existing add-on or caller is affected.

Verification

tests/addons/test-mautic.php adds 21 tests that use the same pre_http_request interception as the Listmonk tests. They cover the Basic auth header, contact creation with no segments, with array segments and with comma-separated segments, the segments field being left alone on other endpoints, segment and contact error paths (no segment calls after a failed contact create), errors returned with a 2xx status, an unknown backend, the keyed-collection normalization against the real JSON_Finger, ping success and failure, endpoint listing, the schema built from /api/fields/contact (unpublished fields are skipped), the template data hook, template validity, and a bridge running its own custom_fields and integer mutations through submit().

Run against current main without the add-on, every test fails with Error: Class "FORMS_BRIDGE\Mautic_Form_Bridge" not found. If only the segment loop and the collection normalization are reverted while the classes stay in place, 5 behaviour tests fail and the rest still pass.

I ran the full vendor/bin/phpunit suite before and after the change on a local WordPress test install. Before: Tests: 352, Errors: 5, Failures: 3. After: Tests: 373, Errors: 5, Failures: 3. The failures are the same tests both times: the Gravity Forms tests (I stubbed the plugin locally) and three Formidable serialization tests that also fail on a clean main re-run. vendor/bin/phpcs forms-bridge/addons/mautic tests/addons/test-mautic.php is clean.

The tests use mocked API responses, not a live Mautic. To check it against a real instance: enable the API and basic auth, use the Contacts template with a segment selected, submit the form, and the contact should show up in Mautic in that segment. The logo is Mautic's own app icon from the mautic/mautic repository. I left README.md and readme.txt unchanged so you can link the add-on from your documentation when you choose.

How this was managed

This work was tracked as story https://eastagiletracker.com/projects/1151/stories/1349679 on a board imported from this repo's issues and pull requests (35 stories): https://eastagiletracker.com/projects/1151

If you'd rather not receive contributions like this, reply no-more-prs on this pull request and we won't open any further ones on your repositories.

---

Lawrence W. Sinclair
CEO / East Agile
linkedin.com/in/lwsinclair/
eastagile.com