Apaleo Bundle Laravel Package

Technical Evaluation

Architecture fit

• apaleo-bundle is a Symfony bundle, not a Laravel package. Laravel does not host bundles — there is no config/bundles.php, no FrameworkBundle config tree, no autowiring container compilation. The bundle cannot be dropped into a Laravel app as shipped.
• The reusable asset for us is the underlying SDK, apaleo-php ^0.1, which is framework-agnostic. The bundle is best treated as a reference architecture: its decisions (dedicated PSR-18 HTTP client, PSR-6 token pool, ApaleoRateLimitException taxonomy, 10 s timeout, GET/HEAD-only retries) are a de facto spec we should mirror in a Laravel service provider.
• Net: the release is informative, not directly adoptable. It raises our confidence in apaleo-php as the integration layer while confirming we must build the Laravel glue ourselves.

Integration feasibility

• Direct composer require oleksyuk/apaleo-bundle in a Laravel app will likely fail dependency resolution: the bundle requires Symfony 8 and PHP 8.4+, while current Laravel releases pin Symfony components to the 7.x line. The "FrameworkBundle optional" note reduces runtime coupling but does not fix composer version constraints — this needs verification of the actual require vs require-dev split before we rule it out definitively.
• Feasible path is a thin Laravel adapter over apaleo-php: singleton binding for ApaleoClient, config/apaleo.php, env-driven credentials, and a cache-backed token store. This is small, well-understood work — roughly a few days for a competent Laravel developer.
• The bundle's token-cache abstraction is the piece we most want to reproduce: shared cache across app servers is mandatory for us, and doing it wrong means one token request per worker per request.

Technical risk

• Pre-1.0 (v0.1.0) with no stated BC policy. Breaking changes to namespace, config keys, or the token-cache contract are likely and should be assumed.
• Aggressive platform floors: PHP 8.4+ and Symfony 8. Both are very new. If our fleet is on PHP 8.3, apaleo-php itself may or may not be installable — must confirm.
• Retries are GET/HEAD only. Writes (POST reservation creation, folio charges) are never retried. Any write path must be idempotent on our side or we risk duplicates on transport failure.
• 429 throws instead of backing off. Rate-limit handling becomes our responsibility: job release/backoff, concurrency caps, and dead-letter behaviour. This is a real design decision, not a papercut — a naive queue worker will burn retries fast.
• 10 s timeout is a fixed default. Report-style endpoints in a PMS API frequently exceed this; timeout tuning must be exposed in our config, not hardcoded.
• Single-maintainer namespace (oleksyuk/*) with no visible support commitments.
• Unaddressed in the notes: pagination, webhooks/event delivery, idempotency keys, sandbox-to-production promotion, API version pinning.

Key questions

1. Is symfony/framework-bundle in require or require-dev? Determines whether the bundle can coexist with Laravel's Symfony 7.x pins at all.
2. Does apaleo-php require PHP 8.4, or only the bundle? If the SDK floor is lower we can adopt sooner.
3. Is the token cache contract a PSR-6 pool, a PSR-16 simple cache, or a bespoke interface? Drives whether we can bridge Laravel's cache directly or need an adapter.
4. Can the HTTP client be swapped for one carrying our standard middleware (correlation IDs, tracing, structured logging)?
5. What is the exception hierarchy beyond ApaleoRateLimitException — do transport vs 4xx vs 5xx map to distinct types we can branch on?
6. Does apaleo-php expose pagination and rate-limit headers (X-RateLimit-Remaining, Retry-After) so we can implement backoff correctly?
7. What is the maintainer's release cadence and BC intent between 0.1 and 1.0?

Integration Approach

Stack fit

• Target stack: Laravel (latest LTS-ish), PHP 8.4, Redis for cache and queues, Horizon for worker supervision.
• Do not install apaleo-bundle. Install apaleo-php only and build App\Apaleo\ApaleoServiceProvider:
  • Bind ApaleoClient as a singleton constructed from config('apaleo').
  • Publish config/apaleo.php reading APALEO_CLIENT_ID, APALEO_CLIENT_SECRET, APALEO_BASE_URI, APALEO_TIMEOUT, APALEO_TOKEN_CACHE_STORE.
  • Register a token store backed by a named Laravel cache store (apaleo-tokens, Redis) with a TTL slightly shorter than the token's stated expiry — mirroring the bundle's token_cache option.
  • Provide a dedicated Guzzle client instance so it can be tuned independently of the default Http client, exactly as the bundle's apaleo.http_client does.
• All calls go through queued jobs; no synchronous apaleo calls in request/response cycles.

Migration path

• Greenfield — no existing apaleo integration, so there is no cutover risk. Sequence: sandbox-only adoption → internal read-only workloads (properties, rates, availability) → write paths (reservations, folios) behind feature flags → production credentials.
• Keep the base URI and credentials environment-scoped so sandbox and production are the same code path.

Compatibility

• Verify PHP 8.4 availability in our runtime images before committing; if we're on 8.3, this whole evaluation defers until the platform upgrade, regardless of the bundle.
• PSR-6 bridging: if the SDK wants a PSR-6 pool, symfony/cache is already in the Laravel dependency graph in most installations, or use a small CacheItemPoolInterface adapter over Illuminate\Contracts\Cache\Repository. Prefer the adapter — fewer moving parts than adding a cache library.
• Pin apaleo-php to an exact version (0.1.x) and treat upgrades as planned work, not composer update drift.

Sequencing

1. Spike (days): install apaleo-php in a scratch Laravel app on PHP 8.4, authenticate against sandbox, confirm client constructability and token caching.
2. Adapter: service provider, config file, token store, dedicated HTTP client, exception mapping to application-level types.
3. Read paths: queued sync jobs for properties/rates; land data in our own tables so downstream features are not coupled to apaleo availability.
4. Write paths: reservation/folio operations with idempotency keys and explicit duplicate detection; no automatic retries.
5. Operational hardening: rate-limit backoff strategy, Horizon queue isolation (apaleo queue, low concurrency), dashboards on 429/5xx rates and p95 latency, alerting on token-refresh failures.

Operational Impact

Maintenance

• Low code volume, moderate ongoing attention. We own the provider and the exception mapping; every apaleo-php bump is a review item.
• Pre-1.0 status means we should budget for at least one breaking change before 1.0 lands, and pin exact versions to make those breaks visible rather than silent.
• We are effectively maintaining a small integration layer that upstream may eventually ship for Laravel. Revisit adoption if a first-party Laravel package appears.

Support

• No vendor SLA, single maintainer, GitHub-issues support only. Escalation path is "read the code."
• Mitigation: keep the adapter thin enough that replacing apaleo-php with hand-written HTTP calls is a contained effort (days, not weeks). Do not let apaleo-specific types leak into domain code — map to our own DTOs at the boundary.

Scaling

• Token cache in Redis is the key scaling lever: without a shared pool, N workers produce N token requests and we invite 429s from our own side.
• Rate limits are the binding constraint, not throughput. Set a low, dedicated worker concurrency for the apaleo queue and use a rate limiter so 429s are exceptions rather than the steady state.
• HTTP connection reuse within a worker is fine; do not share a client instance across forked processes.
• Read-heavy sync workloads scale horizontally. Write workloads scale by queue partitioning (per-property), not by adding workers.

Failure modes

• 429 thrown, not retried by the client → job failure if unhandled. Must implement release-with-backoff honouring Retry-After, plus a circuit breaker so a sustained limit doesn't thrash the queue.
• 5xx on writes not retried → ambiguous outcome. Job retry can duplicate a reservation. Requires idempotency keys or a reconciliation read before retry.
• 10 s timeout on slow report endpoints → spurious failures under normal load. Expose and tune per-operation.
• Token cache cold/evicted → thundering herd of token requests on deploy or Redis flap. Add a short lock around refresh.
• Sandbox/production credential mix-up → silent writes to the wrong tenant. Validate base URI against an allowlist at boot.
• Upstream API change without SDK release → opaque 4xx errors. Log full request ID / correlation ID from responses; this is the only reliable debugging handle.

Ramp-up

• One backend developer, roughly one to two weeks to first production read path including the spike; add a week for write paths and idempotency.
• Requires familiarity with: PSR-18/PSR-17 HTTP abstractions, PSR-6 caching, Laravel service providers and queue semantics, and apaleo's hospitality domain model (properties, rate plans, reservations) — the domain is the underrated part of the ramp, not the code.
• Recommend a short written integration note capturing the bundle's design decisions we adopted, so the next developer doesn't rediscover them.
• Overall recommendation: proceed with an SDK-only integration; do not adopt the bundle. Track apaleo-bundle purely as design input and as an early signal of upstream direction.