Laravel Webcore Laravel Package

Getting Started

First Steps

1. Installation Add the package via Composer:

   composer require stentle/laravel-webcore
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Stentle\LaravelWebCore\WebCoreServiceProvider"
   

2. Configuration Locate .env or config/webcore.php and set:

   STENTLE_API_KEY=your_api_key_here
   STENTLE_API_URL=https://api.stentle.com/v1
   

   Verify the config file exists at config/webcore.php.

3. First Use Case: Fetching Products Use the Product facade to retrieve a list of products:

   use Stentle\LaravelWebCore\Facades\Product;
   
   $products = Product::all();
   dd($products);
   

   Or fetch a single product by ID:

   $product = Product::find(123);
   dd($product);
   

Implementation Patterns

Common Workflows

1. CRUD Operations The package follows Laravel conventions for API interactions:

   // Create
   $product = Product::create([
       'name' => 'Test Product',
       'price' => 9.99,
       'sku' => 'SKU123'
   ]);
   
   // Update
   $product->update(['price' => 12.99]);
   
   // Delete
   $product->delete();
   

2. Querying with Filters Use fluent methods for filtering:

   $activeProducts = Product::where('active', true)
       ->where('price', '>', 10)
       ->get();
   

3. Handling Relationships Fetch products with related categories:

   $product = Product::with('category')->find(123);
   

4. Webhooks & Events Listen for Stentle API events (e.g., product.created):

   use Stentle\LaravelWebCore\Events\ProductCreated;
   
   event(new ProductCreated($product));
   

5. Integration with Laravel Ecosystem

   • Eloquent Models: Extend Stentle\LaravelWebCore\Models\Product for custom logic.
   • Jobs: Dispatch API-heavy tasks to queues:

     dispatch(new SyncProductsJob());
     

Integration Tips

• API Rate Limiting: Cache responses aggressively:

  $products = Cache::remember('stentle_products', now()->addHours(1), function () {
      return Product::all();
  });
  

• Error Handling: Wrap API calls in try-catch:

  try {
      $product = Product::find(123);
  } catch (\Stentle\LaravelWebCore\Exceptions\ApiException $e) {
      Log::error($e->getMessage());
      abort(500, 'Failed to fetch product.');
  }
  

• Testing: Use Http::fake() to mock API responses:

  Http::fake([
      'api.stentle.com/*' => Http::response(['data' => []], 200),
  ]);
  

Gotchas and Tips

Pitfalls

1. Deprecated Laravel Version The package targets Laravel 5.3—ensure compatibility or use a wrapper for newer versions. Workaround: Use a compatibility layer like laravel-shift/laravel-53-compatibility.

2. Missing Documentation

   • The package lacks detailed method docs. Inspect src/Stentle/LaravelWebCore/Facades/ for available methods.
   • Example: Check Product::search() for custom queries.

3. API Key Leaks Never hardcode STENTLE_API_KEY in config files. Use environment variables strictly.

4. Rate Limits Stentle’s API may throttle requests. Implement exponential backoff:

   use Symfony\Component\HttpClient\RetryableHttpClient;
   
   $client = new RetryableHttpClient(
       new Client(),
       ['max_retries' => 3, 'delay' => 100]
   );
   

Debugging Tips

• Enable Debug Mode:

  STENTLE_DEBUG=true
  

  Logs API requests/responses to storage/logs/laravel-webcore.log.

• Inspect Raw Responses:

  $response = Product::find(123, ['debug' => true]);
  dd($response->raw());
  

Extension Points

1. Custom API Endpoints Extend the Stentle\LaravelWebCore\Http\Client class to add new routes:

   namespace App\Services;
   
   use Stentle\LaravelWebCore\Http\Client;
   
   class CustomClient extends Client {
       public function customEndpoint($data) {
           return $this->post('/custom', $data);
       }
   }
   

2. Model Observers Hook into Stentle events for real-time sync:

   Product::observe(ProductObserver::class);
   
   // app/Observers/ProductObserver.php
   class ProductObserver {
       public function saved($product) {
           // Sync to external system
       }
   }
   

3. Middleware for Auth Add custom auth logic to app/Http/Middleware/StentleAuth.php:

   public function handle($request, Closure $next) {
       if (!auth()->check()) {
           return response()->json(['error' => 'Unauthorized'], 401);
       }
       return $next($request);
   }
   

   Register in app/Http/Kernel.php:

   protected $routeMiddleware = [
       'stentle.auth' => \App\Http\Middleware\StentleAuth::class,
   ];