feca-mailshots-plugin/results/phase1_phase2_implementation_verification_2026-04-21.md

Phase 1 & 2 Implementation Verification (2026-04-21)

Scope implemented

• Phase 1 infrastructure skeleton

  • Service container and plugin bootstrap wiring.
  • DB router with explicit members/mailshots database separation.
  • WordPress facade interfaces and production adapter.
  • Fixture harness (tests/fixture/wp_shim.php, bootstrap.php, router.php).
  • Structured error and logging primitives.

• Phase 2 data source pipeline

  • DSL lexer/parser.
  • Semantic validator (source checks, filter-source rules, join-path validation, missing-email warning).
  • Parameterized SQL compiler.
  • Source metadata provider (built-ins + custom table metadata via information schema).
  • mailshot_queries repository and application service.
  • Data Sources admin page + API operations (list, fields, validate, preview, save, delete).

Validation commands and outcomes

1. find feca_mailshots_plugin/src tests -name '*.php' -print0 | xargs -0 -n1 php -l

• Result: pass (no syntax errors).

2. php tests/unit/test_dsl_pipeline.php

• Result: pass.
• Verifies parser/validator/compiler happy path and key invalid-path checks.

3. php tests/unit/test_preview_shape.php

• Result: pass.
• Verifies deterministic expected-field contract derivation.

4. php tests/fixture/test_api_smoke.php

• Result: pass.
• Verifies fixture bootstrap + WP shim + admin menu/page registration path.

Notes

• Fixture smoke test intentionally avoids remote DB calls in sandboxed execution.
• API operations that execute SQL (preview, list, save, delete) require DB connectivity at runtime.

Extended Phase 2 DB-access validation (2026-04-21)

5. php tests/integration/test_phase2_db_access.php

• Result: pass.
• Environment: tunnelled MySQL on 127.0.0.1:13306.
• Verified:
  • Live DB read-path preview via MEMBERS_REMOTE_MYSQL_DB (source discovered dynamically from information_schema).
  • Live DB write-path create/read/delete via MAILSHOTS_REMOTE_MYSQL_DB.mailshot_queries.
  • Test artefact cleanup confirmed (temporary data source row deleted in finally).

Fix discovered by DB test

• mailshot_queries repository insert SQL used unquoted sql column name, which fails on MySQL.
• Fixed by quoting as `sql` in:
  • feca_mailshots_plugin/src/Repository/MailshotQueryRepository.php

Phase 3 implementation and validation (2026-04-21)

Implemented

• Mailshot CRUD service/repository and admin API/page.
• Attachment CRUD + binary file handling service/repository and admin API/page.
• PDF asset CRUD + binary file handling service/repository and admin API/page.
• Last-run repository operations (listForMailshot, clearForMailshot, create).
• Token insertion helper generation from selected datasource expected fields.
• Fixture user-test pages under tests/fixture/.
• Fixture runner script scripts/run_fixture_server.sh (start/stop/status/restart).

Validation

1. php tests/integration/test_phase3_db_access.php

• Result: pass.
• Verified end-to-end on tunnelled DB:
  • datasource creation for test,
  • attachment create/delete,
  • pdf asset create/delete,
  • mailshot create/delete with datasource validation,
  • token helper output generation,
  • last-run insert/list/clear behavior.
• Cleanup: test artefacts removed in finally block.

2. php tests/fixture/test_api_smoke.php

• Result: pass.
• Verified fixture bootstrap and menu/page registration with shared plugin wiring.

3. bash -n scripts/run_fixture_server.sh

• Result: pass.
• Script shell syntax validated.

Phase 4 implementation and validation (2026-04-21)

Implemented

• Twig template rendering pipeline service for Subject, Message, PDFAttachment.
• SMTP sender abstraction with concrete SMTP client implementation.
• IMAP sent-copy abstraction with concrete imap_append implementation.
• Mail credentials provider backed by WordPress options (feca_mailshots_mail_credentials).
• MailshotRunService with:
  • renderTest (no send),
  • sendTest (validation + SMTP + IMAP warning semantics),
  • runMailshot (clear last run + send loop + counters + per-recipient last_run rows),
  • retryFailed,
  • retryRecipient,
  • MAILSHOT_TEST_TO_DEFAULT default exposure.
• Admin pages/endpoints added for:
  • Credentials,
  • Mailshot Test API,
  • Run Mailshot API.

Validation

1. php tests/integration/test_phase4_run_flow.php

• Result: pass.
• Verified:
  • render-test behavior,
  • blank test-email validation,
  • test-send path through injected SMTP/IMAP transports,
  • run-mailshot counters and last-run row persistence,
  • retry-failed endpoint behavior.

2. Existing regression checks

• php tests/unit/test_dsl_pipeline.php pass
• php tests/unit/test_preview_shape.php pass
• php tests/fixture/test_api_smoke.php pass
• php tests/integration/test_phase2_db_access.php pass
• php tests/integration/test_phase3_db_access.php pass

Runtime fix included

• Added Composer autoload loading in plugin autoload bootstrap so Twig/Dompdf classes resolve when vendor deps exist.

Phase 4 UI completion (Mailshot Test + Run Mailshot)

• Replaced placeholder pages with server-rendered WordPress admin UI for:
  • Mailshot selection,
  • Recipient selection/sample display,
  • Render Test (No Send) action,
  • Send Test Email action,
  • Run controls (Run Mailshot, Retry Failed Sends),
  • Last-run table with per-row Retry actions.
• UI actions use admin-post handlers and persist most recent action result in option-backed result panes.
• Added recipient-preview helper API in run service to support UI recipient picker.

Validation: syntax + fixture smoke + phase4 integration test all pass after UI implementation.

Change set: per-user encrypted credentials + access split + no-fallback runtime config (2026-04-21)

Implemented

1. Per-user SMTP/IMAP credential storage in MAILSHOTS_REMOTE_MYSQL_DB

• Added mailshot_credentials repository with table ensure/create and per-user upsert/load.
• Password fields are stored encrypted (smtp_password_enc, imap_password_enc) using AES-256-CBC with key material derived from WordPress salts.

2. New Profile admin page for per-user credentials

• Added Profile page under FECA Mailshots (editor-capable users).
• Credentials are saved/loaded for the current user id.
• Password inputs support blank-as-keep-existing behavior.

3. Runtime credential resolver switched to per-user DB-backed provider

• Replaced global option-based provider with PerUserMailCredentialsProvider.
• Run/test send paths now resolve credentials by current WordPress user.

4. Production DB config path made explicit (fallbacks removed)

• Bootstrap now reads DB settings from Setup page option only.
• No fallback chain to env vars in production bootstrap.
• Fixture remains explicitly env-driven via tests/fixture/bootstrap.php.

5. Access control split

• Setup page remains admin-only (manage_options).
• Operational pages/APIs use editor-level capability (edit_pages):
  • Data Sources, Mailshots, Attachments, PDF Assets,
  • Profile,
  • Mailshot Test,
  • Run Mailshot.

Validation

• php tests/fixture/test_api_smoke.php pass
• php tests/integration/test_per_user_credentials.php pass
• php tests/integration/test_phase4_run_flow.php pass
• syntax checks pass for updated files