Bugloos Test Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require mralirezaeb/bugloos-test
   

   Add to config/app.php under providers:

   MrAlirezaEB\Bugloos\BugloosServiceProvider::class,
   

2. Publish Config

   php artisan vendor:publish --provider="MrAlirezaEB\Bugloos\BugloosServiceProvider" --tag="config"
   

   Configure config/bugloos.php (default values provided).

3. First Use Case Generate a dynamic paginated list in a controller:

   use MrAlirezaEB\Bugloos\Facades\Bugloos;
   
   public function index()
   {
       $list = Bugloos::make('posts')
           ->paginate(10)
           ->orderBy('created_at', 'desc')
           ->get();
   
       return view('posts.index', compact('list'));
   }
   

4. Blade Integration Use the @bugloos directive in views:

   @bugloos('posts', ['paginate' => 10, 'orderBy' => 'created_at desc'])
   

Implementation Patterns

Core Workflows

1. Dynamic List Generation

   // Basic usage
   $dynamicList = Bugloos::make('users')
       ->where('active', true)
       ->paginate(15)
       ->with(['posts' => function($query) {
           $query->where('published', true);
       }]);
   
   // Chaining methods
   Bugloos::make('products')
       ->search('query')
       ->filter(['category' => 'electronics'])
       ->sort('price', 'asc')
       ->limit(20);
   

2. API Integration

   // Fetch from external API
   Bugloos::make('external_data')
       ->fromApi('https://api.example.com/data')
       ->transform(function($item) {
           return collect($item)->only(['id', 'name', 'value']);
       });
   

3. Caching Strategies

   // Cache for 5 minutes
   Bugloos::make('recent_posts')
       ->cache(5)
       ->get();
   
   // Cache with custom key
   Bugloos::make('featured_products')
       ->cache(10, 'featured_products_cache_key');
   

4. View Composition

   // Pass to view with metadata
   $data = Bugloos::make('articles')
       ->paginate(8)
       ->withMetadata()
       ->get();
   
   return view('articles.index', $data);
   

Integration Tips

• Eloquent Models: Works seamlessly with Eloquent queries. Use Bugloos::make(new App\Models\Post) for model-specific lists.
• Livewire/Alpine: Combine with frontend frameworks for reactive pagination:

  Bugloos::make('comments')
      ->livewire()
      ->paginate(5);
  

• Testing: Mock the facade in tests:

  $this->mock(Bugloos::class)->shouldReceive('make')->andReturnSelf();
  

Gotchas and Tips

Pitfalls

1. Over-Eager Loading

   • Issue: N+1 queries when using with() without limits.
   • Fix: Always constrain relationships:

     ->with(['comments' => function($query) {
         $query->limit(3);
     }])
     

2. Cache Invalidation

   • Issue: Stale cached data if underlying data changes.
   • Fix: Use cacheFor() with versioned keys or implement manual invalidation:

     Bugloos::make('posts')->cacheFor(30, 'posts_v' . $lastUpdatedAt);
     

3. API Rate Limits

   • Issue: External API calls may hit rate limits.
   • Fix: Implement retry logic or use local caching:

     ->fromApi('url')->retry(3, 1000);
     

4. Pagination Conflicts

   • Issue: Conflicts with Laravel’s default pagination.
   • Fix: Explicitly set pagination driver:

     ->paginate(10, 'custom_driver');
     

Debugging

• Query Logging: Enable debug mode in config:

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

• DD() Shortcut: Use ->debug() to dump the query builder:

  Bugloos::make('users')->debug()->get();
  

Extension Points

1. Custom Query Builders Override the default query builder in config:

   'query_builder' => MrAlirezaEB\Bugloos\QueryBuilders\CustomQueryBuilder::class,
   

2. Macros Extend functionality via facade macros:

   Bugloos::macro('customMethod', function() {
       return $this->where('status', 'active')->orderBy('priority');
   });
   

3. Event Hooks Listen for list generation events:

   Bugloos::listen('beforeGenerate', function($query, $listName) {
       // Modify query or log
   });
   

4. Service Provider Overrides Bind custom implementations in AppServiceProvider:

   $this->app->bind('bugloos', function($app) {
       return new CustomBugloosManager();
   });