Getting Started

Minimal Steps to First Use

Install the Package Since this is a Symfony bundle, Laravel integration requires a bridge or wrapper. Start by installing the package in a separate Composer package or within a Symfony-compatible environment (e.g., a micro-service):
```
composer require bpolnet/langley-bundle
```
Configure Symfony Bundle (if using Symfony) Add the bundle to config/bundles.php:
```
return [
    Bpolnet\LangleyBundle\LangleyBundle::class => ['all' => true],
];
```
For Laravel, skip this and proceed to Option 2 below.

Laravel Integration: Option 1 (Wrapper Class) Create a Laravel service provider to wrap the Symfony bundle:

php artisan make:provider LangleyServiceProvider

// app/Providers/LangleyServiceProvider.php
namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Bpolnet\LangleyBundle\Service\LangleyClient as SymfonyLangleyClient;

class LangleyServiceProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->singleton('langley', function ($app) {
            // Initialize Symfony bundle (if possible) or mock its behavior
            return new class {
                public function getCustomer($id) {
                    // Example: Use Laravel HTTP client instead
                    return \Http::withHeaders([
                        'Authorization' => 'Bearer ' . config('services.langley.token'),
                    ])->get("https://api.langley.pl/customers/{$id}");
                }
            };
        });
    }
}

First Use Case: Fetch a Customer Inject the wrapped service into a controller:

use Illuminate\Support\Facades\Http;

class CustomerController extends Controller
{
    public function show($id)
    {
        // Direct API call (recommended for Laravel)
        $customer = Http::withHeaders([
            'Authorization' => 'Bearer ' . config('services.langley.token'),
        ])->get("https://api.langley.pl/customers/{$id}");

        return response()->json($customer->json());
    }
}

Configure API Credentials Add to .env:

LANGLEY_API_TOKEN=your_token_here
LANGLEY_API_URL=https://api.langley.pl

Implementation Patterns

Workflow: Order Synchronization

Initialize the Client Use Laravel’s HTTP client for direct API calls (recommended):

use Illuminate\Support\Facades\Http;

$client = Http::withHeaders([
    'Authorization' => 'Bearer ' . config('services.langley.token'),
    'Accept' => 'application/json',
]);

Fetch Paginated Orders

$orders = collect([]);
$page = 1;
$perPage = 50;

do {
    $response = $client->get("/orders?page={$page}&per_page={$perPage}");
    $orders->push(...$response->json()['data']);
    $page++;
} while ($response->json()['next_page']);

return $orders;

Process Orders with Eloquent

foreach ($orders as $order) {
    \App\Models\Order::updateOrCreate(
        ['external_id' => $order['id']],
        [
            'amount' => $order['total_amount'],
            'status' => $order['status'],
            'customer_id' => $order['customer_id'],
        ]
    );
}

Handle Webhooks Create a controller to validate and process Langley webhooks:

use Illuminate\Http\Request;

class LangleyWebhookController extends Controller
{
    public function handle(Request $request)
    {
        $payload = $request->json()->all();
        $signature = $request->header('X-Langley-Signature');

        // Validate signature (example: HMAC)
        $expectedSignature = hash_hmac(
            'sha256',
            $request->getContent(),
            config('services.langley.webhook_secret')
        );

        if (!hash_equals($expectedSignature, $signature)) {
            abort(403, 'Invalid signature');
        }

        // Process webhook (e.g., update order status)
        $this->processWebhook($payload);
    }

    protected function processWebhook(array $payload)
    {
        // Logic to handle order updates, payments, etc.
    }
}

Integration Tips

Use Laravel Queues for Async Processing Offload order processing to a queue:

dispatch(new SyncOrdersJob($orders));

Define the job:

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;

class SyncOrdersJob implements ShouldQueue
{
    use Queueable;

    public function handle()
    {
        // Process orders...
    }
}

Leverage Laravel Events Trigger events for order updates:

event(new OrderSynced($order));

Listen for events in a service:

public function boot()
{
    event(OrderSynced::class, function ($event) {
        // Send notification, update analytics, etc.
    });
}

Cache API Responses Use Laravel’s cache:

$customer = cache()->remember("langley_customer_{$id}", now()->addHours(1), function () use ($id) {
    return Http::get("https://api.langley.pl/customers/{$id}")->json();
});

Rate Limiting Implement exponential backoff for API calls:

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;

$response = Http::timeout(30)->retry(3, 100)->get('/orders');

Gotchas and Tips

Pitfalls

Symfony Dependency Hell
- The bundle assumes Symfony’s DI container. Avoid direct dependency injection in Laravel.
- Fix: Use a wrapper class or mock the bundle’s services.
Undocumented API Endpoints
- Langley.pl’s API may change without notice. The bundle lacks tests or examples.
- Fix: Always check the Langley.pl API docs for updates.
Webhook Validation
- Webhook signatures may not be handled by the bundle. Manual validation is required.
- Fix: Implement HMAC or JWT validation as shown in the workflow section.
Pagination Quirks
- The bundle may not handle pagination consistently. Langley.pl’s API uses page/per_page, but some endpoints may differ.
- Fix: Inspect the API response structure and adjust queries dynamically.

Error Handling Gaps

The bundle may not throw Laravel-friendly exceptions (e.g., HttpException).

Fix: Catch Symfony exceptions and convert them:

try {
    $customer = $this->langley->getCustomer($id);
} catch (\Symfony\Component\HttpKernel\Exception\HttpException $e) {
    throw new \Illuminate\Http\Client\ConnectionException(
        $e->getMessage(),
        $e->getCode(),
        $e
    );
}

Debugging Tips

Log API Requests/Responses Use Laravel’s logging:

\Log::debug('Langley API Request', [
    'url' => $request->url(),
    'headers' => $request->headers(),
    'payload' => $request->json(),
]);

Symfony Debug Dump If debugging the bundle directly, use Symfony’s dump():
```
use Symfony\Component\VarDumper\VarDumper;

VarDumper::dump($customer);
```

Test with Postman Validate API endpoints independently before integrating the bundle:

curl -X GET "https://api.langley.pl/customers/123" \
     -H "Authorization: Bearer YOUR_TOKEN"

Extension Points

Custom HTTP Client Replace the bundle’s HTTP client with Laravel’s:

// Override the bundle's HTTP client (if possible)
$this->app->bind(\Bpolnet\LangleyBundle\Client\HttpClient::class, function ($app) {
    return new class {
        public function request($method, $url, array $options = []) {
            return Http::withOptions($options)->{$method}($url);
        }
    };
});

Add Middleware Attach Laravel middleware to API calls:

$response = Http::withOptions([
    'middleware' => [
        \App\Http\Middleware\LogApiRequests::class,
    ],
])->get('/orders');

Extend Models Add Langley-specific methods to Eloquent models:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Order extends Model

Langley Bundle Laravel Package