Cowegis Core Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require cowegis/cowegis-core
   

   Ensure cowegis/cowegis-core is added to providers in config/app.php:

   Cowegis\Core\CowegisServiceProvider::class,
   

2. Publish Config

   php artisan vendor:publish --provider="Cowegis\Core\CowegisServiceProvider" --tag="config"
   

   Review config/cowegis.php for core settings (e.g., API endpoints, default drivers).

3. First Use Case: Basic Query Inject the facade or service into a controller/console command:

   use Cowegis\Facades\Cowegis;
   
   public function search()
   {
       $results = Cowegis::query('search_term')->limit(10)->get();
       return response()->json($results);
   }
   

4. Documentation Check for README.md or docs/ folder in the package. If sparse, inspect:

   • src/Cowegis/ for core classes.
   • tests/ for usage examples.

Implementation Patterns

Core Workflows

1. Querying Data Chain methods for flexibility:

   $results = Cowegis::query('term')
       ->filter(['category' => 'tech'])
       ->sortBy('relevance')
       ->limit(5)
       ->get();
   

2. Driver Abstraction Switch implementations via config (config/cowegis.php):

   'driver' => env('COWEGIS_DRIVER', 'local'), // e.g., 'local', 'remote_api', 'database'
   

   Extend drivers by implementing Cowegis\Core\Contracts\DriverInterface.

3. Event Listeners Listen for query events (if supported):

   Cowegis::listen(function ($query) {
       Log::info('Query executed:', $query->toArray());
   });
   

4. Caching Responses Leverage Laravel’s cache or package-specific caching:

   $cachedResults = Cowegis::remember('search_term', 3600)->get();
   

Integration Tips

• API Endpoints: Use Route::middleware('cowegis.throttle') for rate-limiting.
• Jobs: Offload heavy queries to queues:

  dispatch(new CowegisQueryJob('term', $userId));
  

• Blade Directives: Create custom directives for frontend integration:

  Blade::directive('cowegis', function ($term) {
      return "<?php echo Cowegis::quickSearch($term); ?>";
  });
  

Gotchas and Tips

Pitfalls

1. Driver Mismatches

   • Ensure the configured driver (config/cowegis.php) matches your environment (e.g., local vs. remote_api).
   • Fix: Test each driver in isolation; log unsupported methods.

2. Rate Limiting

   • Some drivers (e.g., remote APIs) may throttle requests. Use middleware:

     Cowegis::setRateLimiter(new \Cowegis\Core\RateLimiters\ExponentialBackoff());
     

3. Data Sanitization

   • Input terms may contain malicious payloads. Sanitize before querying:

     $term = Cowegis::sanitize('user_input');
     

4. Deprecated Methods

   • Check for @deprecated tags in the codebase. Example:

     // Avoid:
     Cowegis::oldMethod(); // Deprecated since v1.2
     // Use:
     Cowegis::newMethod();
     

Debugging

• Enable Logging Set COWEGIS_DEBUG=true in .env to log queries and errors to storage/logs/cowegis.log.
• Query Dumping Use Cowegis::enableQueryLogging() to inspect raw queries in Tinker:

  php artisan tinker
  Cowegis::query('test')->dump();
  

Extension Points

1. Custom Drivers Implement DriverInterface and bind in CowegisServiceProvider:

   $this->app->bind(
       \Cowegis\Core\Contracts\DriverInterface::class,
       \App\Services\CustomCowegisDriver::class
   );
   

2. Query Macros Extend the query builder:

   Cowegis::macro('customMethod', function ($param) {
       return $this->filter(['custom' => $param]);
   });
   

3. Middleware Add custom logic to all queries:

   Cowegis::extend(function ($query) {
       $query->setUserId(auth()->id());
   });
   

4. Testing Mock drivers in tests:

   $this->app->instance(
       \Cowegis\Core\Contracts\DriverInterface::class,
       MockDriver::class
   );