Laravel Webcore Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require stentle-hackers/laravel-webcore
   

   Ensure your Laravel version is 5.3+ (compatibility is strict).

2. Publish Config

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

   This generates a .env file with STENTLE_API_KEY and STENTLE_API_URL placeholders. Configure these in your .env:

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

3. First API Call Use the Stentle facade to interact with the API:

   use Stentle\Facades\Stentle;
   
   // Example: Fetch a product
   $product = Stentle::product()->find(123);
   

4. Key Classes

   • Stentle::product() → Product API methods.
   • Stentle::cart() → Cart operations.
   • Stentle::order() → Order management.
   • Stentle::customer() → Customer data.

Implementation Patterns

Common Workflows

1. Product Management

   • Fetching Products

     $products = Stentle::product()->all(['limit' => 10]);
     

   • Creating/Updating

     $product = Stentle::product()->create([
         'name' => 'Laptop',
         'price' => 999.99,
         'sku' => 'LP-1000'
     ]);
     

2. Cart Operations

   • Add to Cart

     Stentle::cart()->add(123, 2); // Product ID, quantity
     

   • Checkout

     $order = Stentle::cart()->checkout(['customer_id' => 456]);
     

3. Order Processing

   • Fetch Orders

     $orders = Stentle::order()->all(['status' => 'completed']);
     

   • Update Order Status

     Stentle::order()->update(789, ['status' => 'shipped']);
     

4. Customer Data

   • Fetch Customer

     $customer = Stentle::customer()->find(456);
     

   • Update Profile

     Stentle::customer()->update(456, ['email' => 'new@example.com']);
     

Integration Tips

• Laravel Eloquent Sync Use the package alongside Eloquent for hybrid data management:

  // Sync Stentle products with local DB
  $stentleProducts = Stentle::product()->all();
  Product::upsert($stentleProducts, ['sku'], ['name', 'price']);
  

• API Rate Limiting The package handles retries for failed requests (configurable in config/webcore.php):

  'retry_limit' => 3,
  'retry_delay' => 100, // ms
  

• Webhooks Stentle supports webhooks for real-time updates (e.g., order status changes). Configure in config/webcore.php:

  'webhook_secret' => 'your_webhook_secret',
  'webhook_url' => route('stentle.webhook'),
  

  Then create a route/controller to handle incoming payloads:

  Route::post('/stentle/webhook', 'StentleWebhookController@handle');
  

Gotchas and Tips

Pitfalls

1. Deprecated Laravel Version

   • The package is only tested for Laravel 5.3. Upgrading may break functionality.
   • Workaround: Use a Dockerized Laravel 5.3 environment or fork the package for modern Laravel.

2. API Key Leaks

   • The .env file is not auto-generated by the vendor:publish command. Ensure STENTLE_API_KEY is never committed to version control.
   • Tip: Use Laravel’s environment variables and .env.example templates.

3. Rate Limits

   • Stentle’s API may throttle requests. Monitor responses for 429 Too Many Requests.
   • Tip: Implement exponential backoff in your application layer if the package’s retry logic is insufficient.

4. Webhook Verification

   • Stentle webhooks require a Stentle-Signature header for validation. The package does not include this by default.
   • Fix: Manually verify signatures in your webhook endpoint:

     $payload = file_get_contents('php://input');
     $signature = $_SERVER['HTTP_STENTLE_SIGNATURE'];
     $secret = config('webcore.webhook_secret');
     if (!hash_equals($signature, hash_hmac('sha256', $payload, $secret))) {
         abort(401, 'Invalid signature');
     }
     

Debugging

• Enable API Logging Add this to config/webcore.php to log all API requests/responses:

  'debug' => true,
  'log_file' => storage_path('logs/stentle.log'),
  

• Common Errors

  Error	Cause	Solution
  ClientException	Invalid API key or endpoint	Verify .env and Stentle dashboard
  ConnectionException	API URL misconfigured	Check STENTLE_API_URL
  ValidationException	Missing/invalid payload fields	Review Stentle API docs for required fields
  RateLimitExceededException	Too many requests	Implement backoff or upgrade plan

Extension Points

1. Custom API Endpoints The package uses Guzzle under the hood. Extend it by creating a custom service:

   use Stentle\WebCore\Client;
   
   class CustomStentleClient extends Client
   {
       public function customEndpoint($method, $endpoint, $data = [])
       {
           return $this->request($method, $endpoint, $data);
       }
   }
   

   Register it in AppServiceProvider:

   $this->app->singleton('stentle.custom', function () {
       return new CustomStentleClient(config('webcore'));
   });
   

2. Middleware for API Calls Add middleware to modify requests/responses globally. Example:

   // In AppServiceProvider
   $this->app['stentle']->getClient()->getEmitter()->attach(
       new class extends Middleware {
           public function handle($request, Closure $next)
           {
               // Add custom headers
               $request->setHeader('X-Custom-Header', 'value');
               return $next($request);
           }
       }
   );
   

3. Testing Mock the Stentle client in tests:

   $mock = Mockery::mock('overload:Stentle\WebCore\Client');
   $mock->shouldReceive('request')->andReturn(['data' => 'mocked']);