Recently Laravel Package

Technical Evaluation

Architecture Fit

• Filament Integration: The package is tightly coupled with Filament Admin Panel (v3.x–5.x), making it ideal for projects already using Filament for admin interfaces. It extends Filament’s resource management by adding "recently viewed" functionality, which aligns well with user activity tracking and workflow optimization use cases.
• Laravel Ecosystem: Leverages Laravel’s query caching, eloquent events, and middleware for tracking, reducing custom development effort. Compatible with Laravel 10.x (implied by Filament 5.x support).
• Plugin-Based Design: Follows Filament’s plugin architecture, enabling modular adoption without monolithic changes. Can be enabled/disabled per panel or globally.

Integration Feasibility

• Low-Coupling: Uses Filament’s service container and event system (e.g., ResourceViewed) to track activity, minimizing direct model/database changes.
• Database Requirements:
  • Requires a recently_viewed table (migration provided).
  • Supports soft deletes and model-specific tracking (configurable via config/recently.php).
• UI Layer: Adds a widget (Filament’s Widget) and resource actions (e.g., "View Recently") with minimal CSS overrides (theme-aware).

Technical Risk

• Filament Version Lock: High risk if not using supported Filament versions (e.g., Filament 2.x would require backporting). Upgrade path may be non-trivial if using an unsupported version.
• Performance Overhead:
  • Tracking adds database writes on every resource view (mitigated by caching in config/recently.php).
  • Query complexity: Recent records are fetched via orderBy + limit, which could impact large datasets (test with DB::enableQueryLog).
• Customization Limits:
  • Hardcoded to Filament’s resource system; non-Filament models (e.g., API-only) require manual integration.
  • UI styling relies on Filament’s theme system; custom themes may need adjustments.

Key Questions

1. Filament Version: Is the project using Filament 3.x–5.x? If not, what’s the upgrade path?
2. Tracking Scope:
   • Should tracking apply to all resources or specific ones (e.g., only Post, User)?
   • Are there rate limits (e.g., max 100 recent items) or TTL policies?
3. Data Sensitivity:
   • Does the app handle PII? If so, ensure recently_viewed table is scoped/encrypted.
4. Caching Strategy:
   • Will recent items be cached in Redis (configurable) to reduce DB load?
5. Testing:
   • How will race conditions (e.g., concurrent views) be validated?
   • Are there unit tests for the RecentlyService and RecentlyViewed model?

Integration Approach

Stack Fit

• Primary Use Case: Filament-based admin panels where users frequently navigate between resources (e.g., CMS, SaaS dashboards).
• Laravel Stack Compatibility:
  • PHP 8.1+: Required by Filament 5.x.
  • Database: Supports MySQL, PostgreSQL, SQLite (via Eloquent).
  • Caching: Optional Redis/Memcached for recently_viewed queries.
• Alternatives Considered:
  • Manual Tracking: Higher dev effort (events + caching).
  • Third-Party: Packages like spatie/activitylog (broader but heavier).

Migration Path

1. Prerequisites:
   • Upgrade Filament to supported version (e.g., composer require filament/filament:"^5.0").
   • Set up a custom theme (if not already done) for CSS integration.
2. Installation:

   composer require awcodes/recently
   php artisan recently:install
   

   • Follow prompts to configure tracked models and widget placement.
3. Configuration:
   • Update config/recently.php for:
     • models (whitelist/blacklist).
     • max_items (default: 20).
     • cache_driver (e.g., redis).
4. Testing:
   • Verify tracking via Tinker:

     \App\Models\Post::find(1)->view(); // Simulate a view
     \RecentlyViewed::latest()->take(5)->get();
     

   • Test widget rendering in Filament panels.

Compatibility

• Filament Plugins: Works alongside other Filament plugins (e.g., filament/spatie-laravel-medialibrary) if they don’t conflict on resource events.
• Non-Filament Routes: Not supported—tracking is Filament-resource-specific.
• Legacy Code: If using old Filament 2.x, consider forking the package or building a custom solution.

Sequencing

1. Phase 1: Install and configure for one resource (e.g., Post).
2. Phase 2: Add widget to a Filament dashboard.
3. Phase 3: Optimize with caching and performance testing.
4. Phase 4: Roll out to additional resources and monitor DB impact.

Operational Impact

Maintenance

• Vendor Updates: Monitor awcodes/recently for Filament version support drops (e.g., if Filament 6.x is released).
• Dependency Bloat: Adds ~500 LOC; minimal compared to Filament’s core.
• Configuration Drift: Centralized in config/recently.php—easy to audit.

Support

• Debugging:
  • Use RecentlyViewed::query()->toSql() to inspect queries.
  • Check filament.log for event-related errors.
• Community: Low stars (43) may mean limited community support; expect self-service troubleshooting.
• Fallback: Can disable via config/recently.php without breaking core functionality.

Scaling

• Database Load:
  • High-traffic risk: Each view inserts a record. Mitigate with:
    • config/recently.max_items (e.g., 50).
    • Redis caching for queries.
  • Indexing: Ensure recently_viewed has indexes on model_type, model_id, and created_at.
• Horizontal Scaling: Stateless tracking (via events) works in load-balanced Laravel setups, but shared DB is required for consistency.

Failure Modes

Ramp-Up

• Developer Onboarding:
  • 1 hour: Install and configure for a single resource.
  • 2 hours: Customize widget placement and styling.
• QA Checklist:
  • Verify tracking works for all targeted resources.
  • Test widget pagination (if enabled).
  • Confirm cache invalidation on model updates/deletes.
• Documentation Gaps:
  • Lack of advanced customization docs (e.g., overriding RecentlyViewed model).
  • No performance benchmarks for large datasets.