Ikentoo Bridge Bundle Laravel Package

Getting Started

• Install with composer require maillotf/ikentoo-bridge-bundle. Note this pulls in Symfony components, so check for conflicts with your Laravel version before committing.
• This is a Symfony bundle, not a Laravel package. There is no package auto-discovery, no config/ikentoo.php publish step, and no facade. Expect to wire it up by hand.
• Register the bundle's service in a Laravel ServiceProvider (or bind it lazily):

// app/Providers/IkentooServiceProvider.php
public function register(): void
{
    $this->app->singleton(IkentooService::class, function () {
        return new IkentooService([
            'protocol' => config('services.ikentoo.protocol', 'https'),
            'host'     => config('services.ikentoo.host'),
            'port'     => config('services.ikentoo.port', '443'),
            'token'    => config('services.ikentoo.token'),
        ]);
    });
}

• Put credentials in config/services.php (env-backed), not in a YAML file. The README's framework.yaml/services.yaml snippets are Symfony-only and will not load in Laravel.
• First use case: pull a range of receipt transactions for a given order/terminal ID and return as JSON, exactly as in the README example but with a Laravel controller signature:

public function test(IkentooService $is)
{
    $from = new \DateTime('2020-01-09');
    $to   = new \DateTime('2020-10-09');

    return response()->json(
        $is->financial->getReceiptTransactionsRange("101163659689986", $from, $to, ['staff'], 1000)
    );
}

• Where to look first: the IkentooService class and its public properties (financial, orderAndPayment, …). Those are your real API surface — the README only documents two methods.

Implementation Patterns

• Treat the service as a low-level client. Wrap it in your own repository/action classes so financial->… and orderAndPayment->… calls don't leak into controllers. This is also where you'll add caching, retries, and logging.
• Inject, don't instantiate. Type-hint IkentooService in constructors and let the container resolve your singleton binding. This keeps you swappable in tests.
• Queue the heavy calls. getReceiptTransactionsRange with a large date window and limit = 1000 is a slow, paginated HTTP call. Dispatch to a job and persist results rather than calling it in a request cycle.
• Cache static-ish data. Menus (loadMenu) change infrequently — Cache::remember() them keyed by menu ID and invalidate on a schedule.
• Normalize IDs. Ikentoo identifiers are large numeric strings ("101163659689986"). Keep them as strings end to end; never cast to int (32-bit overflow on some PHP builds, and precision loss in JSON).
• DTO mapping. Map raw responses into your own DTOs/JsonResource before returning from controllers, so a package update doesn't reshape your public API.
• Multi-tenant pattern. If you serve multiple venues, register a scoped/factory binding that builds an IkentooService per token, rather than a global singleton.

Gotchas and Tips

• The README examples don't compile. loadMenu(...) is missing a trailing semicolon, and $is->financial->… relies on magic/typed sub-services the docs never enumerate. Read the source for the actual method signatures.
• No documented error handling. There's nothing on timeouts, retries, 4xx/5xx, or rate limits. Wrap calls in try/catch, surface a domain exception, and consider a retry policy. Assume the underlying HTTP client may throw Guzzle exceptions.
• Token-only auth, no refresh flow. The token appears static. There is no documented rotation or refresh — plan for token expiry as an operational concern, and log auth failures distinctly from other errors.
• Config wiring is the #1 failure mode. If you port the README's YAML verbatim into a Laravel app, nothing happens. The service will either fail to construct or use empty defaults (127.0.0.1:80). Validate config at boot and fail fast if token/host are blank.
• Symfony dependency footprint. composer require may pull Symfony HTTP client/config components. Check composer why for conflicts and pin versions if your app already ships Symfony packages.
• Debugging: log the fully-qualified host/protocol/port (never the token) at boot, and log outgoing request paths + status on failure. Most "empty result" reports are wrong IDs, a too-narrow date range, or a trailing-slash/host port mismatch.
• Extension points: the cleanest customization is Laravel-side — decorate the injected IkentooService with your own class implementing the same calls, and bind that. Avoid editing vendor code, since a patch release will overwrite it.
• DTO note: the two documented calls are read-heavy financial/menu operations. If you need write operations (orders, payments), verify they exist in this release before designing around them — the notes only show read paths.