Database Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require orchestra/database
   

   Register the package in config/app.php under providers:

   Orchestra\Database\DatabaseServiceProvider::class,
   Orchestra\Database\SearchServiceProvider::class,
   Orchestra\Database\ConsoleServiceProvider::class,
   Orchestra\Database\CachableQueryServiceProvider::class,
   

2. First Use Case: Enable caching for Eloquent queries via the remember() and rememberForever() macros:

   use Orchestra\Database\Eloquent\Builder;
   
   $users = Builder::where('active', 1)->remember(60)->get();
   

Where to Look First

• Documentation: Check the GitHub README for core features.
• Service Providers: Review Orchestra\Database\DatabaseServiceProvider for database extensions.
• Cache Decorator: Explore Orchestra\Database\CacheDecorator for caching query results.
• Migration Commands: Use orchestra:migrate or orchestra:migration:refresh for advanced migration workflows.

Implementation Patterns

Core Workflows

1. Caching Queries:

   // Cache results for 10 minutes
   $activeUsers = User::where('status', 'active')->remember(600)->get();
   
   // Cache indefinitely
   $admins = User::role('admin')->rememberForever()->get();
   

2. Cache Decorator:

   // Cache plucked results
   $userNames = User::pluck('name')->remember(3600);
   
   // Cache lists (e.g., for dropdowns)
   $userEmails = User::lists('email', 'id')->remember(3600);
   

3. Migration Commands:

   # Run migrations from a specific path
   php artisan orchestra:migrate --path=database/migrations/custom
   
   # Refresh migrations with realpath support
   php artisan orchestra:migration:refresh --realpath
   

4. Search Service Provider: Integrate with Laravel Scout or custom search logic via Orchestra\Database\SearchServiceProvider.

Integration Tips

• Extend Eloquent: Use CachableQueryServiceProvider to add remember() to all Eloquent queries globally.

  // config/orchestra/database.php
  'cachable' => [
      'enabled' => true,
      'default_ttl' => 60, // Default TTL in seconds
  ],
  

• Custom Cache Keys: Override cache keys for specific queries:

  $users = User::where('active', 1)->remember(60, 'active_users_cache_key')->get();
  

• Fallback Logic: Leverage the CacheDecorator fallback to database when cache fails:

  $data = Cache::remember('key', 60, function () {
      return User::where('active', 1)->get();
  });
  

Gotchas and Tips

Pitfalls

1. Cache Invalidation:

   • Manually invalidate caches when data changes:

     Cache::forget('active_users_cache_key');
     

   • Avoid long TTLs for frequently updated data.

2. Performance Overhead:

   • Excessive caching can slow down writes. Monitor cache hit/miss ratios.
   • Use rememberForever() sparingly; it bypasses cache invalidation entirely.

3. Service Provider Conflicts:

   • Ensure all required providers (DatabaseServiceProvider, CachableQueryServiceProvider, etc.) are registered.
   • Avoid duplicate registrations in config/app.php.

4. Deprecated Methods:

   • MigrationServiceProvider and CacheDecorator::lists() are deprecated. Use lists() from CacheDecorator or Eloquent’s pluck().

Debugging

1. Cache Issues:

   • Check cache driver logs (e.g., Redis/APCu) for errors.
   • Verify TTL values aren’t too aggressive:

     Cache::getStore()->get('key'); // Inspect raw cache
     

2. Query Caching:

   • Disable caching temporarily to isolate issues:

     $users = User::where('active', 1)->remember(0)->get(); // Disables caching
     

3. Migration Errors:

   • Use --verbose for detailed output:

     php artisan orchestra:migrate --verbose
     

   • Check for file permission issues in database/migrations/.

Extension Points

1. Custom Cache Drivers: Extend Orchestra\Database\CacheDecorator to support non-standard cache backends:

   Cache::extend('custom', function () {
       return new CustomCacheStore();
   });
   

2. Macro Overrides: Override remember() behavior globally:

   Builder::macro('remember', function ($seconds, $key = null) {
       // Custom logic here
       return $this->macro('cache', $seconds, $key);
   });
   

3. Search Integration: Extend Orchestra\Database\SearchServiceProvider for custom search logic:

   Search::extend('custom', function () {
       return new CustomSearchEngine();
   });
   

Performance Tips

1. Prefix Global Functions: The package prefixes global functions (e.g., \Cache::remember()) to avoid lookup overhead. Ensure your IDE is configured to recognize these.

2. Static Methods: Prefer static methods (e.g., CacheDecorator::pluck()) over instance methods for micro-optimizations.

3. Batch Caching: Cache collections of related data in bulk:

   $users = User::with('posts')->remember(3600)->get();