Apaleo Bundle Laravel Package

Product Decisions This Supports

• Build vs. buy for apaleo/PMS connectivity. This bundle is the thin integration layer over apaleo-php ^0.1 — it does not add product features, it removes glue code. That makes it a buy-and-absorb decision: adopt the SDK + bundle rather than hand-rolling HTTP plumbing against the apaleo API.
• Hospitality/PMS feature scoping. Anything touching reservations, availability, rates, or folios via apaleo can now be estimated as "wire the autowired ApaleoClient into a service," not "build an API client." Useful for sizing roadmap items in discovery before committing engineering time.
• Infrastructure spend on horizontal scaling. The shared token cache (cache.app by default, or any PSR-6 pool such as Redis) is an explicit multi-server decision. If the product runs more than one app server, Redis becomes a dependency of the integration — a small but real infra/ops line item to budget.
• Reliability and SLA posture. The bundle sets a 10 s timeout and retries 5xx/transport errors for GET/HEAD only, and surfaces 429 as ApaleoRateLimitException instead of sleeping. That last choice is a deliberate product-level stance: backoff and retry budgeting are pushed to our queue/job layer, so any feature that bulk-reads from apaleo needs an explicit throttling story. Get this into the acceptance criteria, not the post-launch incident review.
• Environments and demo/migration paths. Optional base_uri enables sandbox targeting; FrameworkBundle being optional with an in-memory token cache makes CLI tools and one-off scripts trivial. Supports staging/demo environments without extra configuration work.
• Observability requirements. The dedicated apaleo.http_client shows up in the Symfony profiler and is tunable via framework.http_client, which lowers the cost of debugging partner-integration issues during pilots.

When to Consider This Package

Adopt when all of the following hold:

• The application is Symfony 8 on PHP 8.4+. These are hard, non-negotiable requirements — not a "nice to have."
• apaleo is the system of record for the property/hospitality domain and we intend to call it from application code rather than via an iPaaS or middleware.
• We want credential handling, token caching, and retry/timeout behavior standardized rather than reimplemented per service.
• We are comfortable pinning to a pre-1.0 dependency (v0.1.0) and accepting that minor-version bumps may break us.

Look elsewhere — or plan to wrap rather than adopt — when:

• The stack is Laravel. This is a Symfony bundle; it provides a Bundle class and config/bundles.php registration. Laravel teams should depend on apaleo-php directly and write a small service provider plus a cache-backed token store. Do not let the "PHP package" framing create a false expectation of drop-in Laravel support.
• The fleet is on PHP 8.3 or Symfony 6/7. The PHP 8.4 + Symfony 8 floor likely forces a platform upgrade whose cost dwarfs the integration savings — sequence the upgrade decision separately.
• We need vendor-backed support, a deprecation policy, or an SLA. v0.1.0 with a single maintainer means we own the risk; budget for forking or vendoring if apaleo becomes business-critical.
• apaleo access is needed from only one or two call sites, or only as a batch/ETL job — the bundle's value is proportional to how many services need a configured client.
• We require a middleware layer anyway (multi-vendor PMS abstraction, channel manager, etc.). Wrapping a 0.1 bundle inside our own abstraction adds a layer with little payoff.

How to Pitch It (Stakeholders)

To executives: We evaluated a first public release of oleksyuk/apaleo-bundle, a Symfony integration for the apaleo property-management API. It is a small, focused piece of plumbing — it handles credentials, access-token caching, timeouts, and retry behavior so our engineers don't rebuild that per project. The product-level value is estimate compression on apaleo-backed features and a standardized, observable way to talk to the partner API. Two caveats drive the recommendation: it is v0.1.0 (pre-stable, single maintainer, no support guarantee) and it requires PHP 8.4 and Symfony 8, which is narrower than our current fleet. Recommendation: treat it as an accelerator for Symfony 8 work only, pin the version, and keep our own thin interface in front of it so a fork or replacement stays cheap.

To engineering: No breaking changes to react to — this is the initial release. What matters is the contract it establishes: ApaleoClient is autowired from APALEO_CLIENT_ID/APALEO_CLIENT_SECRET with an optional sandbox base_uri; a dedicated apaleo.http_client enforces a 10 s timeout and retries only GET/HEAD on 5xx/transport errors; 429 is raised as ApaleoRateLimitException rather than silently slept on, so your job and queue code owns backoff; and the token cache defaults to cache.app but should be pointed at Redis (token_cache) for any multi-server deployment. FrameworkBundle is optional and falls back to an in-memory token cache — fine for CLI, wrong for production. Requirements are PHP 8.4+ and Symfony 8, so verify platform readiness before anyone writes an estimate that assumes this is available.

Bottom line for the roadmap: include it as an enabler on the next Symfony 8 + apaleo initiative, not as a standalone line item; revisit the maturity call once a 1.0 or a second maintainer appears.