Recently Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require awcodes/recently
   php artisan recently:install
   

   Follow the prompts to configure the package (e.g., model to track, panel integration).

2. First Use Case: Add the RecentlyViewed widget to a Filament panel dashboard:

   use Awcodes\Recently\Widgets\RecentlyViewed;
   
   public function getWidgets(): array
   {
       return [
           RecentlyViewed::make(),
       ];
   }
   

   This instantly displays recently viewed records for the authenticated user.

3. Where to Look First:

   • Configuration: Check config/recently.php for tracking limits, models, and panel settings.
   • Middleware: Verify app/Http/Middleware/TrackRecentlyViewed.php is registered in app/Http/Kernel.php.
   • Views: Customize the widget’s blade template in resources/views/vendor/recently/....

Implementation Patterns

Core Workflows

1. Tracking Records:

   • Automatically tracks views via middleware. Extend functionality by publishing and modifying the middleware:

     php artisan vendor:publish --tag="recently-middleware"
     

   • Manually trigger tracking for specific actions:

     use Awcodes\Recently\Facades\Recently;
     
     Recently::track($model); // e.g., after a create/update action
     

2. Widget Integration:

   • Basic Usage:

     RecentlyViewed::make()
         ->limit(5) // Override config limit
         ->query(fn ($query) => $query->where('active', true)) // Custom query
     

   • Panel-Specific Widgets:

     RecentlyViewed::make()
         ->forPanel('admin') // Restrict to a specific panel
         ->heading('Admin Recent Activity')
     

3. Data Access:

   • Retrieve recent records programmatically:

     $recent = Recently::get();
     $recent->take(3); // Paginate or limit results
     

   • Access user-specific data:

     $userRecent = Recently::forUser(auth()->user())->get();
     

4. Model-Specific Tracking:

   • Configure which models to track in config/recently.php:

     'models' => [
         App\Models\Post::class,
         App\Models\User::class,
     ],
     

   • Dynamically add models via service provider:

     Recently::trackModel(App\Models\Category::class);
     

Integration Tips

• Filament Panels: Ensure the package’s CSS is included in your custom theme (as per README instructions).
• Caching: Leverage Filament’s caching for the widget:

  RecentlyViewed::make()->cacheFor(60); // Cache for 60 seconds
  

• Authorization: Use Filament’s built-in policies to gate access to tracked records:

  RecentlyViewed::make()->authorizeResourcePolicy();
  

Gotchas and Tips

Pitfalls

1. Middleware Registration:

   • Issue: Forgetting to add TrackRecentlyViewed middleware to Kernel.php will break automatic tracking.
   • Fix: Verify the middleware is in the $middlewareGroups['web'] array.

2. Model Tracking:

   • Issue: Models not appearing in the widget despite being configured.
   • Debug: Check if the model implements Illuminate\Database\Eloquent\Model and is whitelisted in config/recently.php.
   • Fix: Ensure the model’s fillable includes the viewed_at timestamp if using custom tracking logic.

3. CSS Conflicts:

   • Issue: Widget styling not applying due to missing CSS.
   • Fix: Run php artisan vendor:publish --tag="recently-views" to publish assets and include the CSS in your theme.

4. Performance:

   • Issue: Slow queries when tracking high-volume models.
   • Fix: Add indexes to the viewed_at column and limit the number of tracked records in config/recently.php:

     'limit' => 20,
     

Debugging

• Log Tracking Events: Enable debug mode in config/recently.php:

  'debug' => env('RECENTLY_DEBUG', false),
  

  Check logs for tracking events in storage/logs/laravel.log.

• Query Inspection: Use Laravel’s query logging to inspect the recently_viewed table queries:

  DB::enableQueryLog();
  $recent = Recently::get();
  dd(DB::getQueryLog());
  

Extension Points

1. Custom Storage:

   • Override the default recently_viewed table by binding a custom repository:

     Recently::setRepository(App\Repositories\CustomRecentlyRepository::class);
     

2. Event Listeners:

   • Listen for tracking events:

     Recently::tracked(function ($model) {
         // Custom logic after a model is tracked
     });
     

3. Widget Customization:

   • Publish and extend the widget’s view:

     php artisan vendor:publish --tag="recently-views"
     

   • Override the template in resources/views/vendor/recently/widgets/recently-viewed.blade.php.

4. Panel-Specific Config:

   • Dynamically configure widgets per panel using Filament’s getWidgets() context:

     public function getWidgets(): array
     {
         return match ($this->getPanel()?->getId()) {
             'admin' => [RecentlyViewed::make()->limit(10)],
             default => [RecentlyViewed::make()->limit(5)],
         };
     }
     

Config Quirks

• Timezone Handling: The viewed_at timestamp uses the server’s timezone. Ensure consistency by setting config/app.php:

  'timezone' => 'UTC',
  

• Soft Deletes: If using soft deletes, ensure the query accounts for deleted records:

  RecentlyViewed::make()->query(fn ($query) => $query->withTrashed()),