Statamic Secretary Laravel Package

Getting Started

This is a 0.x Statamic 6 addon (Control Panel assets + Postmark integration), not a plain Laravel package — treat its stability guarantees accordingly.

1. composer require <vendor>/<package>:^0.1.13 — 0.1.13 is the first release whose committed CP assets are rebuilt against the secure Statamic 6.31.0 lock; do not start on 0.1.10 or earlier.
2. Confirm your app satisfies the real floor: PHP 8.2+, Laravel 11/12, statamic/cms ^6.31. Check composer.json require before anything else — the lock refresh in 0.1.12 means older Statamic 6.2x installs will conflict.
3. Publish config and assets: php artisan vendor:publish --provider="<Vendor>\<Package>\ServiceProvider" (config + public/vendor/<package> CP assets).
4. Set POSTMARK_TOKEN (and the webhook secret, if the package exposes one) in .env; add them to .env.example and your deploy secrets store in the same PR.

Where to look first, in order: composer.json (constraints), src/ServiceProvider.php (transport/mailer registration, CP nav, routes), config/*.php (transport + webhook keys), routes/ (webhook endpoint and middleware), tests/ (the shape the maintainers expect).

First use case: swap the mail transport to Postmark for one low-risk mailable (password reset or a contact form), send it, then point the Postmark webhook at the package route and replay the same delivery twice — you should get one processed event and one rejected replay. That single loop exercises the mail path, the signature check, and the v0.1.11 replay protection all at once.

Implementation Patterns

Transport via config, not code. Register Postmark in config/mail.php ('postmark' => ['transport' => 'postmark']) and let the package's service provider wire the mailer. Resist constructing the API client directly in your own services — you lose the package's error mapping and the upgrade path.

Webhook idempotency is your responsibility to store. The v0.1.11 replay protection keys off the delivery/message identity; make sure the store it checks is shared across all app servers (Redis or database cache), not file/array. In multi-node deployments a per-node cache silently defeats the protection. Pair it with your own processed_webhooks table if you need an audit trail — a cache hit proves "seen", not "handled".

Handle webhooks on the queue. Point the package route at a thin controller/job that returns 200 fast and does the work in ShouldQueue. Postmark retries on timeouts; slow synchronous handlers generate duplicate deliveries that the replay guard then has to absorb.

Asset pipeline parity with the maintainers. 0.1.13 is entirely about reproducible frontend verification. Mirror it: build CP assets in CI (npm ci && npm run build), then git diff --exit-code public/vendor/<package> so a lock bump that changes assets without a rebuild fails the build instead of blanking the Control Panel in production.

Testing patterns.

• Mail::fake() for outbound assertions; Http::fake(['api.postmarkapp.com/*' => ...]) when you need to assert payload shape (tag, metadata, stream).
• Write one test that POSTs the same signed webhook body twice and asserts the second is a no-op — this is the regression test for 0.1.11 behaviour you now depend on.
• Assert the signature failure path returns a non-2xx; a 200-on-invalid-signature is the classic silent hole.

Upgrade cadence. Stay inside ^0.1 and bump deliberately: composer update <vendor>/<package> --with-dependencies, inspect the composer.lock diff for transitive Statamic/core movement, republish CP assets (--force on the assets tag only), clear caches, then smoke-test the Control Panel. Because this package ships built assets tied to a Statamic lock, asset and lock changes are coupled — never update one without the other.

Gotchas and Tips

• Stale CP assets are the most common breakage. A lock bump without a republish gives you a blank or partially-rendering Control Panel with no PHP error. Fix: php artisan vendor:publish --tag=<package>-assets --force, then php artisan view:clear && php artisan statamic:stache:clear.
• Don't ship node_modules-built assets from a dirty tree. If you commit public/vendor/<package>, the committed output must match CI's; otherwise the maintainers' deterministic verification (and yours) becomes meaningless.
• Cache store is a correctness dependency, not an optimisation. CACHE_STORE=file in production turns replay protection into per-request roulette. Check it in your deploy checklist, not just in .env.example.
• Raw request body matters. If any middleware (or a proxy) normalises/decodes the payload before signature verification, webhooks fail intermittently and only in production. Verify against $request->getContent().
• 0.1.12 is a security floor, not a feature release. The "security lock refresh" means earlier versions carry a vulnerable dependency graph. If you're on ≤0.1.11, this is a patch-now situation rather than a scheduled bump; audit composer audit after upgrading.
• Debugging webhooks: log the inbound headers, the verification result, and the replay key at debug level behind a config flag. A silent 200 from the package makes "Postmark says delivered, app says nothing" the hardest class of bug here.
• Extension points to prefer: the published config, the package's events (listen rather than editing the webhook controller), and a custom mailer/transport subclass if you need to inject headers. Avoid class_alias-ing or extending the service provider — 0.x refactors will break it.
• Semver reality: 0.1.x allows breaking changes on minor bumps by definition. Pin 0.1.13 exactly (or ~0.1.13) if your release process can't absorb an unannounced asset or config-key change, and re-read the release notes before each bump — these notes are build-focused, but the 0.1.11 webhook behaviour change would have been easy to miss.