Laravel Sends Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: The package excels in email tracking and model association, making it ideal for applications requiring audit trails, compliance logging, or user-specific email histories (e.g., notifications, transactions, or communications). It aligns well with Laravel’s Mailable system and Eloquent ORM, reducing boilerplate for tracking sent emails.
• Extensibility: Supports custom metadata via Send::create() and integrates with Laravel’s events (MailSent), enabling hooks for analytics, retries, or third-party integrations (e.g., Mailgun/SendGrid webhooks).
• Limitation: Lacks built-in email status tracking (e.g., bounced, opened) beyond "sent," which may require additional packages (e.g., spatie/laravel-activitylog) for full lifecycle management.

Integration Feasibility

• Low Friction: Leverages Laravel’s native Mail facade and Eloquent relationships, requiring minimal configuration (publish migrations, add traits to models).
• Database Impact: Adds a sends table with foreign keys to mailables and models, which must be accounted for in schema migrations. Indexing on mailable_type/mailable_id and model_type/model_id is critical for performance.
• Dependency Risk: Relies on Laravel’s core (v10.x+) and PHP 8.1+. v2.9.0 adds PHP 8.6 support, widening the supported runtime band to PHP 8.1–8.6, which removes a forward-compatibility blocker for teams planning a PHP 8.6 upgrade. Compatibility with older Laravel versions still requires backporting or forks.

Technical Risk

• Data Consistency: Race conditions may occur if emails are sent outside Laravel’s request lifecycle (e.g., queues, cron jobs). Mitigate via database transactions or queue listeners.
• Model Association Overhead: Associating models with every email adds storage I/O and may bloat tables for high-volume senders. Consider batch processing or soft-deletes for old records.
• Testing Complexity: Requires mocking Mail facade and Send models in unit tests. Integration tests should verify relationships and query performance.
• Runtime Compatibility: Low risk. v2.9.0 is an additive compatibility release (new PHP version support) with no reported breaking changes, deprecations, or API changes, so no remediation work is implied for existing installs.

Key Questions

1. Scalability Needs: How many emails/day? Will the sends table require partitioning or archiving?
2. Model Association Strategy: Should all emails be tied to models, or only specific types (e.g., user-triggered emails)?
3. Retention Policy: How long to keep email records? Auto-purge via model observers or queued jobs?
4. Third-Party Sync: Will external systems (e.g., CRM) need to query this data? API endpoints may be required.
5. Queue Integration: How are emails dispatched (sync/queue)? Queue listeners may need to wrap Send::create().
6. Runtime Roadmap: Is a PHP 8.6 upgrade planned in the next 1–2 quarters? If so, v2.9.0 can be adopted ahead of the runtime bump to de-risk the platform upgrade.

Integration Approach

Stack Fit

• Laravel-Centric: Designed for Laravel’s ecosystem (Mailables, Eloquent, Queues). Works seamlessly with:
  • Mail Drivers: All drivers (log, mail, ses, etc.) except log (which bypasses tracking).
  • Queues: Requires Mail facade to use queues; direct SwiftMailer calls won’t trigger tracking.
  • Testing: Compatible with MailFake for unit tests.
• Non-Laravel: Not applicable to vanilla PHP or non-Laravel frameworks.

Migration Path

1. Installation:

   composer require wnx/laravel-sends
   php artisan vendor:publish --provider="Wnx\LaravelSends\LaravelSendsServiceProvider"
   php artisan migrate
   

2. Model Setup:
   • Add HasSends trait to Eloquent models:

     use Wnx\LaravelSends\HasSends;
     class User extends Model { use HasSends; }
     

   • Publish config to customize table/column names or metadata fields.
3. Mailable Integration:
   • No changes needed to existing Mailables; tracking is automatic.
   • For custom metadata:

     Send::create([
         'mailable_type' => ProductReviewMail::class,
         'model_type' => User::class,
         'model_id' => $user->id,
         'metadata' => ['review_id' => $review->id],
     ]);
     

4. Querying:
   • Use sends() relationship:

     $user->sends()->with('mailable')->get();
     

   • Filter by mailable class:

     Send::forMailClass(ProductReviewMail::class)->where('metadata->review_id', 1)->get();
     

Compatibility

• Laravel Versions: Tested on v10.x; may need adjustments for v9.x (e.g., mailable_type column naming).
• PHP Versions: Requires PHP 8.1+ (for named arguments, attributes). As of v2.9.0, PHP 8.6 is explicitly supported, giving a supported range of PHP 8.1 → 8.6.
• Database: Supports MySQL, PostgreSQL, SQLite (via Laravel migrations). Custom drivers may need schema adjustments.
• Conflicts: None identified, but ensure no other packages modify the mailables table.

Sequencing

1. Phase 1: Install, publish migrations, and test basic tracking.
2. Phase 2: Integrate model associations for critical paths (e.g., user notifications).
3. Phase 3: Add metadata/custom fields and query optimizations (indexes, caching).
4. Phase 4: Implement retention policies (e.g., Send model observer for soft-deletes).
5. Phase 5: Expose data via API or admin panel if needed.
6. Phase 0 (pre-work, optional): Upgrade to v2.9.0 before any planned PHP 8.6 runtime change, so the two changes are not coupled in a single release window and regressions can be attributed cleanly.

Operational Impact

Maintenance

• Low Overhead: Minimal maintenance if using default configurations. Custom metadata or complex queries may require occasional optimization.
• Updates: Monitor for Laravel version compatibility. Backward-compatible changes are likely due to MIT license and active development (2026 releases). v2.9.0 (PHP 8.6 support) is a low-risk, drop-in patch/minor upgrade with no migration or config changes required.
• Deprecations: Watch for Laravel core changes (e.g., Mailables API shifts). None signaled in v2.9.0.

Support

• Debugging: Logs MailSent events for troubleshooting. Common issues:
  • Missing associations if models aren’t using HasSends.
  • Performance bottlenecks in sends() queries (add indexes).
• Documentation: README is clear, but may lack advanced use cases (e.g., bulk operations). Consider internal runbooks for:
  • Querying patterns (e.g., paginating sends()).
  • Handling failed sends (extend MailSent event listener).
• Community: Limited stars (201) suggest niche adoption; rely on GitHub issues or direct support from maintainer (@stefanzweifel). Maintainer is actively merging compatibility PRs (community-contributed PHP 8.6 support, #30), a positive signal for ongoing upkeep.

Scaling

• Performance:
  • Reads: Index mailable_type, mailable_id, model_type, model_id, and created_at for common queries.
  • Writes: Batch Send::create() calls if sending emails in loops (e.g., bulk notifications).
  • Caching: Cache frequent queries (e.g., user->sends()->count()) with remember() or Redis.
• Database Growth: Monitor sends table size. Implement:
  • Archiving: Move old records to a sends_archive table via queued job.
  • Purging: Soft-delete via SendObserver or Laravel’s SoftDeletes.
• Horizontal Scaling: Stateless design means no changes needed for Laravel Horizon/queue scaling.

Failure Modes

Ramp-Up

• Developer Onboarding:
  • 1 Hour: Install and test basic tracking.
  • 2 Hours: Integrate model associations for 1–2 key use cases.
  • 4 Hours: Customize metadata and queries for production needs.
• Training Topics:
  • When to use Send::create() vs. automatic tracking.
  • Querying patterns (e.g., filtering by metadata).
  • Performance pitfalls (e.g., N+1 queries in sends()).
• Documentation Gaps:
  • Example of bulk email tracking (e.g., newsletters).
  • Testing strategies for email tracking in CI.
  • Disaster recovery for corrupted sends table.
  • Internal note on supported PHP/Laravel matrix post-v2.9.0 to guide future platform upgrades.