Laravel Waitlist Laravel Package

Technical Evaluation

TPM recommendation: Treat v0.2.0 as a capability-expanding but integration-breaking release. Suitable for greenfield Laravel 13 waitlist use; for existing v0.1.x integrations, plan a controlled upgrade rather than a routine composer update.

Architecture fit. Laravel-native package covering the waitlist domain: lists/projects, double opt-in, tokenized unsubscribe, policies, events, artisan commands, mail/view scaffolding. v0.2.0 adds public count/position, reconfirmation and lapse retention, CSV import, in-app time-trap spam protection, and a publishable-key resolver. Good fit if the product needs consent-aware waitlist behavior without building the state machine. Coupling to Laravel 13 conventions (attributes, form requests, container bindings) raises the minimum platform floor.

Integration feasibility. Medium. Greenfield: composer install, migrations, config, optional waitlist:install --mail, and JS client. Existing: audit custom code for removed spam methods, renamed link generators, policy method change, enum cases, model factory attribute, and mail route semantics. Import provides a migration path from existing lists, but consent provenance must be validated before importing confirmed addresses without mail.

Technical risk. Medium-high. Breaking changes in a 0.x package mean it is not API-stable. Migration risks: MySQL/MariaDB widen_waitlist_wordings_table shrinks project to 100 characters and fails if longer data exists; publishing all migrations duplicates the first five; route cache must be rebuilt. Runtime risks: exhaustive match over enums breaks on new cases; GET/POST mail link split changes integration semantics; older JS clients do not read count/position/challenge/answer_by, and the release note says to leave reconfirm_after_days unset and not bind TimeTrapSpamProtector on pages using older clients. New public endpoints are opt-in, privacy-conscious (position by token, rounded counts), but still need rate limiting and WAF review. Reconfirmation adds a lapsed state and mail volume; import of confirmed addresses without mail is compliance-sensitive.

Key questions.

• Are we on Laravel 13, and does the package composer constraint allow it?
• Do we extend package models, override ListPolicy, bind a custom LinkGenerator, or use Waitlist::verifySpamUsing() / spamProtector()?
• Do any waitlist_wordings.project values exceed 100 characters?
• Which @taldres/laravel-waitlist JS client version is deployed, and which pages use count/position/challenge/answer_by?
• Do we need import and reconfirmation at launch, and who signs off on imported consent provenance?
• Do we cache routes, and what is the runbook for route:cache after deploy?
• What rate limits/WAF rules apply to GET /waitlist/count and the position endpoint?
• Are we prepared to handle new enum cases in exhaustive matches and static analysis?

Integration Approach

Stack fit. Good for Laravel 13 apps using Eloquent, policies, queued mail, and artisan commands. Optional browser pages require @taldres/laravel-waitlist 0.2.0+ for new fields. If frontend cannot upgrade immediately, defer public count/position and reconfirmation, or avoid binding TimeTrapSpamProtector on affected pages per release guidance.

Migration path.

• Greenfield: install package, publish migrations, configure lists/projects, run waitlist:install --mail, bind SpamProtector explicitly (TimeTrapSpamProtector or ClosureSpamProtector), wire JS client 0.2.0+, enable public endpoints per list.
• Existing v0.1.x: branch, update composer, publish migrations (delete duplicate copies of first five), run migrate, run route:cache. Replace verifySpamUsing() / spamProtector() with container binding; rename ConfirmationUrlGenerator / DefaultConfirmationUrlGenerator bindings to LinkGenerator / DefaultLinkGenerator; change ListPolicy::doubleOptIn to doubleOptIn(); add factories for extended models; update enum matches; update mail templates/integrations expecting GET-only links to use POST for confirm.store / unsubscribe.store. Audit project name length before the widen migration.

Compatibility. JS client 0.2.0+ required for count, position, challenge, and answer_by. Route URLs and answers stay, but HTTP method semantics change: GET reports, POST acts. MySQL/MariaDB project column shrink is a data-compatibility risk. 0.x breaking changes mean downstream customizations are the main compatibility risk. Test mail client prefetch behavior; GET no longer acts, which is intended but may surprise custom integrations. Confirm queue and scheduler compatibility for ReconfirmationRequested.

Sequencing.

1. Inventory customizations, Laravel version, JS client version, and project name lengths.
2. Upgrade staging; run migrations; rebuild route cache; run static analysis and tests.
3. Update breaking-change code paths; upgrade JS client to 0.2.0+.
4. Bind spam protector deliberately; test TimeTrapSpamProtector if chosen.
5. Pilot import with a small CSV; validate EntryImported consent timestamps.
6. Enable reconfirmation and public endpoints per list behind flags; schedule waitlist:prune --isolated.
7. Load-test public endpoints; deploy with rollback plan and migration backups.

Operational Impact

Maintenance. 0.x package; budget for minor-version breaking changes. Assign ownership for package upgrades, custom bindings, mail templates, and JS client. Keep overrides thin. Track release notes; contribution guide and templates help upstream but do not remove internal maintenance. New surfaces (public endpoints, reconfirmation job, import, spam protector) add test cases.

Support. Docs, skills, Boost guideline, and referrals example improve onboarding. Support must understand new subscription states (lapsed), reconfirmation emails, import consent provenance, and public count/position behavior. Provide runbooks for waitlist:import, waitlist:prune --isolated, waitlist:rekey --isolated, waitlist:wording --isolated, and the mail link GET/POST changes. FAQ for “why is count null below ten” and “why does position require token”.

Scaling. Count is cached for one minute and rounded down to ten; position is by token; both are opt-in per list and off without double opt-in — good privacy and scaling defaults. Public endpoints still need rate limiting/CDN/WAF. Import may be heavy; batch large CSVs and avoid peak. Reconfirmation increases mail volume; ensure queue workers and mail provider capacity. Use --isolated on scheduled prune/rekey/wording to avoid overlapping runs. MySQL/MariaDB widen migration may lock or rebuild the wordings table; schedule appropriately.

Failure modes.

• Migration fails on project names >100 characters; publish-all duplicates first-five migrations.
• Stale route cache after deploy.
• UnhandledMatchError from new enum cases.
• Old JS client silently ignores new fields; enabling reconfirmation/TimeTrapSpamProtector on those pages may break UX per release note.
• Spam protection absent if SpamProtector is not bound; TimeTrapSpamProtector is not default.
• Email scanners no longer trigger confirm/unsubscribe because GET only reports; custom integrations using GET will fail.
• Import without mail can create confirmed subscriptions without fresh consent; compliance risk.
• Reconfirmation is off by default; if enabled, lapsed transitions and mail failures need monitoring.
• Public endpoints scraped or abused if unthrottled.

Ramp-up. Laravel team: 1–3 days for greenfield; 1–2 sprints for an existing customized integration. Frontend: JS client upgrade and page QA. Ops/support: runbooks and monitoring for new commands/states. Legal/compliance: review import consent and reconfirmation policy before enabling. Overall leverage is high for consent-aware waitlist features, but only with deliberate upgrade and feature-flag rollout.