Prontuno Laravel Laravel Package

Technical Evaluation

Architecture fit. This is a thin, idiomatic Laravel integration — service provider + facade auto-discovery, a publishable config file, a route middleware alias, and a mail transport registered through Laravel's mail manager. It adds no database tables or migrations, so it is essentially stateless and imposes no schema or persistence decisions on the host application. That is the right shape for a vendor SDK and keeps the blast radius small: you can adopt the mail transport without adopting the API resources, and vice versa.

The strongest architectural signal is that the package sits on top of a framework-agnostic client (prontuno/prontuno-php) and on Laravel's own HTTP client. That means the Laravel layer is a convenience shell rather than a load-bearing abstraction — if the integration lags a Laravel release, a team can drop to the underlying SDK or raw HTTP without re-architecting.

Integration feasibility. High for greenfield or Laravel 12 apps; gated otherwise. Two hard constraints:

• PHP 8.3+ and Laravel 12 or 13 only. Laravel 11 and earlier are excluded, as are PHP 8.1/8.2. For most established applications this makes the package's real prerequisite "upgrade Laravel first," which is a materially larger project than the integration itself. This is the single biggest adoption gate and should be confirmed before any evaluation spend.
• Laravel 13 support claimed at v0.1.0 — worth verifying that the version is actually available and tested against, since a pre-1.0 package claiming support for an unreleased major is a compatibility-risk smell rather than a guarantee.

Everything else is conventional. Http::fake() working in application tests removes the usual "we need a sandbox tenant before we can write tests" blocker, and env-driven configuration with a publishable config file matches Laravel conventions (php artisan vendor:publish --tag=prontuno-config).

Technical risk. Moderate, concentrated in three places:

1. Mail is a high-blast-radius subsystem. Swapping MAIL_MAILER touches password resets, receipts, invites, and alerting simultaneously. A transport defect is a user-facing outage, not a degraded feature.
2. Idempotency depends on Message-ID stability. The package uses each message's Message-ID as the idempotency key, so retries are safe only if the identifier is generated once and preserved across attempt boundaries. If a retry path re-renders the message, dedupe silently fails and you get duplicate email — which is worse than a failure for transactional mail. This needs explicit verification, not inference from release notes.
3. Pre-1.0 surface. v0.1.0 with no stated stability policy means breaking changes should be expected. Pin versions deliberately.

Webhook verification is well-scoped (HMAC over the raw body, 300s default tolerance, typed WebhookEvent, named secrets for multiple endpoints). The residual gap is that a timestamp tolerance bounds replay, it does not prevent it — dedupe on an event identifier is still an application responsibility.

Key questions.

• Is Laravel 13 released and in the tested support matrix, and what is the package's versioning/stability commitment to 1.0?
• Is Message-ID generated once per send and preserved across transport retries?
• Does the transport honor Mail::alwaysTo/alwaysFrom, the failover mailer, and MessageSending/MessageSent events?
• Are webhook events at-least-once, and is there a stable event ID to dedupe on? Is ordering guaranteed?
• Does the webhook middleware accept two active secrets simultaneously (needed for zero-downtime secret rotation)?
• Are config:cache and env()-at-runtime handled correctly, and is the client safe as a container singleton under Octane and queue workers?
• Documented rate limits, batch size ceilings, attachment size limits, and per-endpoint quotas?
• What is the vendor's support SLA, DPA/data-retention posture, and email body retention policy?

Integration Approach

Stack fit. Strong for a Laravel 12/13 shop already comfortable with facades, middleware aliases, and Http::fake(). The two-key split (sending vs. management) is good least-privilege design and should be mirrored in how secrets are stored — the management key belongs only in the services that mutate domains, suppressions, webhooks, and API keys, not in the web tier by default. usingApiKey() returning a new client supports multi-tenant use, but it also means per-tenant clients must never be captured into long-lived singletons or Octane-resident state.

Migration path. Do not flip the default mailer first. Sequence it:

1. Gate check (half a day): confirm PHP/Laravel versions resolve with composer require. If the app is on Laravel 11 or PHP 8.2, stop — this is an upgrade project, not an integration.
2. Staging spike (1–2 days): send one Mailable via Mail::mailer('prontuno'), verify headers, attachments, inline images, and that Http::fake() covers the failure paths in tests.
3. Canary (1–2 weeks): register Prontuno as a non-default mailer and route one low-stakes stream (e.g., a single notification type) through it. Keep the incumbent provider live. Consider wrapping both in Laravel's failover mailer so a Prontuno outage degrades instead of blocking.
4. Promote critical transactional mail only after delivery, bounce, and duplicate-rate parity against the incumbent.
5. Webhooks last, and behind a queue. The middleware should verify, hand the typed event to a job, and return 200 quickly; dedupe on the event ID in storage before processing.
6. Management resources (domains, suppressions, key rotation) are genuinely optional for v1 — they replace API calls you can also make by hand or in a small artisan command. Defer them.

Compatibility and sequencing notes. Pin to ~0.1.0 and re-evaluate at each minor. Treat webhook secret rotation and API key rotation as runbook items from day one, not follow-ups. If you maintain multiple Laravel versions across services, expect the package's narrow support matrix to fragment your adoption.

Operational Impact

Maintenance. Single-vendor, MIT-licensed, pre-1.0. Expect churn. The mitigations are real but modest: the license permits forking, the API is HTTP/JSON, and the agnostic PHP SDK plus Laravel's HTTP client give you a credible escape hatch. Still, plan for a dependency that needs a human to read changelogs each release rather than one that runs unattended for a year. Assign an owner.

Support. Vendor support terms are undocumented in the release notes — no SLA, no escalation path, no status page reference. For a subsystem that gates password resets, that is a gap. Interim mitigation: wrap sends so a transport exception is captured with the request ID the ApiException exposes (that field is genuinely useful for vendor escalation), and keep a second mailer configured as fallback.

Scaling. Stateless and cheap to scale horizontally; throughput is bounded by queue workers and vendor rate limits, not by the package. Two sizing traps: (a) total send latency is attempts × timeout + backoff, capped by a 60s Retry-After — this must stay comfortably inside your queue retry_after and job timeout, or you get double-sends from the queue re-dispatching a job the transport is still retrying; (b) lazy() iterates every page and belongs in a job or console command, never a request cycle. Inline attachments are held in memory during send — set an explicit ceiling.

Failure modes.

• Vendor outage → mail queue backs up, time-sensitive mail (resets, OTPs) stalls. Needs failover mailer and queue-depth alerting, not just error logs.
• Duplicate sends → idempotency key instability or queue/transport retry interaction. Highest-severity, lowest-visibility failure; instrument duplicate detection before canary.
• Webhook endpoint down → vendor retries produce a burst on recovery. Handler must be fast, idempotent, and rate-tolerant.
• Rotation events (webhook secrets, API keys, SMTP credentials) → no documented dual-secret window; assume a brief cutover and rehearse it.
• 429 storms during batch sends or lazy() loops → respect Retry-After, cap concurrency, and cap batch sizes.
• Pre-1.0 breaking change on upgrade → pin and test in staging.

Ramp-up. Low. A Laravel developer is productive in under a day: facade, middleware alias, config publish, Http::fake() — all familiar idioms, and the README is referenced as covering every feature. The non-obvious parts that need explicit onboarding are the two-key model, the idempotency/Message-ID contract, webhook dedupe discipline, and the retry-budget-vs-queue-timeout math. Documentation beyond the README (upgrade guide, changelog, support matrix) is not evidenced and should be requested from the vendor before you commit critical paths.