shelfwood/php-pms-clients
PHP clients for property management system (PMS) APIs, giving Laravel and PHP applications a consistent way to connect to PMS platforms and work with property, reservation, and related data.
Architecture fit. v5.0.0 materially strengthens the case that this is a real multi-vendor client library rather than two vendor-shaped HTTP wrappers, but it does not settle the central question. Two things are now evident. First, the maintainer is tracking versioned vendor endpoints explicitly (/api/connector/v1/services/getAvailability/2024-01-22, /reservations/getAll/2023-06-06), which means the abstraction is being maintained against the vendors' actual API-version lifecycle rather than a snapshot. Second, the release embeds non-trivial domain normalization—time-unit boundaries converted to "00:00 UTC" using the enterprise timezone fetched from configuration/get—inside the package. That is a double-edged signal: it demonstrates the package is absorbing genuinely hard, hospitality-specific semantic work (which is exactly the value we would otherwise build), but it also means vendor- and domain-specific behavior is leaking through the abstraction, and correctness of that normalization is now our problem to verify. The cross-vendor contract question remains open: nothing in the notes describes a normalized Reservation/Availability/RatePlan model, and the changes described are vendor-shaped (Mews request fields, Mews response envelopes, Mews timezone semantics). Fit with our stack is unchanged and high, but the "is this an abstraction or a convenience wrapper" test still requires reading the source.
Integration feasibility. Mechanically still straightforward, and the release notes improve confidence in a few specific areas. Pagination is now handled for getAll (with Extent/Limitation alignment) rather than left to the caller, which removes real undifferentiated work. Request-shape correctness is now asserted in tests. What the notes conspicuously do not mention is the set of things that determined feasibility in the prior assessment: token lifecycle and 401 re-auth, retry/backoff, rate-limit handling, typed error mapping, and idempotency for write paths. Absence of mention is not absence of implementation, but after a major release it is reasonable to treat those as unproven and verify in the spike. The new per-client-instance cache of enterprise timezone introduces a concrete integration consideration: in long-running queue workers the cache is a correctness surface (stale timezone after a configuration change → misaligned availability windows), and in multi-property deployments "per client instance" must mean per-enterprise, not per-process, or availability queries will silently use the wrong day boundary.
Technical risk. Still high, but the composition of risk has shifted. Adoption risk is unchanged in kind—no third-party dependents means no production validation—yet a v5.0.0 with a coherent changelog, semver discipline, and a genuine breaking-change section is meaningful evidence of an actively maintained project rather than a dormant one. The dominant risks are now coupling and correctness rather than abandonment. Coupling: because endpoints are pinned to vendor versions inside the library, a Mews deprecation of 2024-01-22 forces a package major version, which forces our upgrade. We inherit the maintainer's response time as our own exposure window. Correctness: the notes state that pricing no longer sends OccupancyConfiguration "per current contract assumptions/tests"—that phrasing is a tell. It indicates behavior inferred from fixtures and reverse-engineering rather than confirmed against vendor documentation or a sandbox, so a silent behavioral divergence in production is plausible and would be hard to attribute. Reaching v5.0.0 with no external consumers also warrants a question about rewrite history and how much of the surface has been exercised against live APIs. Secondary risks persist: error-code taxonomy, credential/logging hygiene, partial-failure semantics across two vendors, and the forward-dated tag anomaly from the earlier review—which should now be re-checked, since a clean, coherently dated v5.0.0 would resolve it.
Key questions. Several prior questions are now partially answered: (5) versioning/deprecation policy is de facto answered—endpoints are pinned per API version and breaking vendor changes ship as package majors; (4) test strategy is answered at the fixture/assertion level, but not at the live-sandbox or recorded-production-traffic level; (2) pagination is confirmed handled, retries/backoff/rate limiting/idempotency remain open. Still open and now higher priority: (1) Is there an explicit cross-vendor contract, or are these two independent vendor clients sharing a namespace? (3) Is auth fully encapsulated including refresh and 401 re-auth? (6) Bus factor and willingness to accept a co-maintained fork. New questions surfaced by this release: (8) What is the upgrade/response SLA when Mews sunsets 2024-01-22—is there a stated deprecation policy with lead time? (9) How is the enterprise-timezone cache invalidated, and is it keyed per-enterprise so multi-property deployments are correct? (10) Was the removal of OccupancyConfiguration from rates/getPricing validated against a live Mews sandbox, or only against updated fixtures? (11) Does the package model partial failure when one vendor call succeeds and the other fails?
Stack fit. Unchanged recommendation, and this release strengthens the rationale: install behind our own PmsGateway port keyed to our ubiquitous language. The timezone-normalization change is the clearest illustration of why. A behavior that converts local midnight to UTC based on a cached enterprise timezone is domain-critical (it determines which night's availability you are asking about) and is now implemented in a third-party dependency we do not control. Wrapping it means we can test our domain assertions against fixtures, detect behavioral drift on upgrade, and replace the normalization if it proves wrong—without touching call sites.
Migration path. Same shape, with one adjustment. Read-only first, Mews first, second vendor later. The adjustment: because availability semantics changed in a breaking way in this very release, treat availability as the highest-attention surface rather than the safest one. Start with property metadata and rate plans (stable, low semantic content), then availability, then reservations. Do not take v5.0.0's availability path into a pilot without a specific test that asserts day-boundary correctness across a DST transition and across a non-UTC enterprise timezone.
Compatibility. Pin to an exact version—5.0.0—and re-audit transitive dependencies, since a major release is a natural moment for constraint bumps that can collide with our security patches. Two new checks specific to this release: confirm the timezone cache behaves correctly under queue workers that process jobs for multiple properties in one process (a per-process cache would be a latent cross-tenant bug), and confirm the versioned endpoint paths are configurable or at least easy to override, so a vendor sunset does not require waiting on a package release. Continue to verify framework-agnosticism (CLI and queue usability) and multi-credential/multi-property configuration support.
Sequencing.
PmsGateway interface, fixture-based, so a v5.x → v6.x upgrade produces a diff we can read rather than an incident.Maintenance. The picture improved but the conclusion is similar. Active, semver-disciplined maintenance with real breaking-change documentation lowers the probability of abandonment, but does not change the fact that we have no dependents to find bugs ahead of us and no community to absorb vendor API churn. What this release does change is the shape of the maintenance burden: it is now clearly upgrade-driven rather than bug-driven. Every Mews API version bump becomes a package major version, which becomes our project. Budget 10–20% of one engineer's time, but plan it as planned upgrade work tied to vendor deprecation calendars rather than reactive patching—and add the vendor deprecation dates for 2024-01-22 (availability) and 2023-06-06 (reservations) to our dependency-review calendar now.
Support. Unchanged: no vendor SLA, no security disclosure process we can rely on, internal ownership must be a named engineer. One refinement—because breaking changes are released as majors, our on-call needs a documented "do not auto-upgrade" policy for this dependency. Renovate/Dependabot auto-merge on a package that ships breaking vendor-semantic changes is an outage waiting to happen.
Scaling. Unchanged fundamentals: HTTP-bound, governed by PMS rate limits, queue-based outbound writes with backoff and jitter, cached reference data, no synchronous fan-out to both vendors. One addition: the per-client-instance timezone cache is a scaling-adjacent concern. Under horizontal scaling, each worker instance fetches and holds configuration/get independently, so a timezone change propagates unevenly across the fleet. Either accept the propagation window and document it, or drive timezone from our own configuration as the source of truth and validate against the vendor.
Failure modes. Prior list stands (token refresh stampedes, silent field-mapping drift, partial multi-vendor failure, rate-limit cascades, generic exception mapping, credential leakage in logs). This release adds two specific ones. Timezone cache staleness: a configuration change or a DST boundary combined with a long-lived worker produces availability queries for the wrong day—this fails silently and looks like a data problem, not an integration problem. Assumption drift: the pricing change made "per current contract assumptions/tests" means a vendor behavior we believe but have not confirmed live; if wrong, requests may succeed with subtly incorrect results rather than erroring, which is the worst failure class. Both argue for asserting on semantic outcomes in our own contract tests (which night did we ask for, did the price match the rate plan) rather than only on request shape. Per-vendor instrumentation remains mandatory.
Ramp-up. Unchanged for calling (low) versus owning (moderate-to-high), with hospitality domain literacy as the binding constraint—2–3 weeks to productivity, 6–8 weeks to independent diagnosis of vendor discrepancies. This release slightly raises the owning bar, because correct operation now requires understanding Mews API versioning cadence, enterprise timezone semantics, and availability metric envelopes—not just HTTP and Laravel. The stakeholder framing updates but does not flip: this is a credible, actively maintained head start on hard normalization work, still not a de-risked dependency. Gate the decision on the two-day spike, a source review confirming a real cross-vendor contract exists, a live-sandbox validation of the availability timezone logic, and a credible answer on how quickly we can absorb the next forced major version.
How can I help you explore Laravel packages today?