Laravel Float Sdk Laravel Package

Technical Evaluation

Architecture fit

The package is a thin, Laravel-native read client over the Float.com API v3 — not an integration platform. It provides:

• A container-bound FloatClient (named to dodge PHP's float reserved word) injectable into controllers, jobs, and services.
• Seven read-only resource groups: users(), projects(), projectTasks(), clients(), allocations(), timeOff(), publicHolidays().
• Typed query-parameter value objects (GetUsersParams, GetProjectsParams, GetAllocationsParams, etc.) covering pagination (page, perPage default 50, sort), sparse fieldsets (fields), and relationship expansion (expand).
• Config via two env vars (FLOAT_API_TOKEN, FLOAT_USER_AGENT) plus a publishable float-sdk-config file.

It fits a specific posture: Float remains the system of record for resourcing, and we build delivery-ops surfaces (utilization/capacity dashboards, allocation-vs-time-off conflict views, client and project rollups, holiday-aware scheduling) on top of it. It does not fit any requirement to push data into Float (create allocations, log time, submit expenses) or to react to Float events — there is no write surface and no webhook support documented. Those are separate scopes, and a roadmap item that depends on them should not be planned against this package.

The underlying HTTP layer is Saloon (introduced in 0.0.1), which is a meaningful architectural positive: if we need an endpoint the package doesn't expose, we can add a Saloon request class rather than re-architecting, and the connector/auth pattern is one our team already encounters in Laravel codebases.

Integration feasibility

Genuinely low effort on the happy path. composer require, two env vars, optional vendor:publish, then constructor injection. A developer can produce a working "list active projects with client expanded" call in under an hour. Rough order of magnitude for a first read-only integration: days, not weeks — and most of that is deciding what to build with the data, not wiring the client.

The honest framing for a build-vs-buy discussion: a competent Laravel developer could hand-roll this same read wrapper against Float v3 in roughly comparable effort. The package's value is not owning the plumbing and inheriting upstream fixes (e.g., the 1.0.1 correction to single-allocation response parsing), not unlocking a capability we couldn't otherwise reach. That is a real but small decision.

Technical risk

• Adoption signal is effectively zero. 4 stars, 0 dependents. There is no meaningful population of production users to infer stability from. The 1.0.1 fix to the single-allocation response shape is a concrete reminder that response-shape handling in this SDK is still being corrected post-1.0.
• Single-maintainer concentration. Effectively one primary author (Niels Vanpachtenbeke) plus occasional contributors. Spatie's org backing raises the floor somewhat, but bus factor is 1 for endpoint coverage.
• Explicitly partial coverage. The README states this is "not a full implementation." Any endpoint outside the seven groups is our code to write.
• Metadata anomaly to verify. Release metadata shows a 2026-10-02 date and a 2.1.0 "Add support for Laravel 13" release. Confirm actual Packagist state and installed version during diligence rather than trusting the feed — future-dated artifacts are a signal to check the source.
• Low intrinsic risk to adopt anyway. MIT license, small surface area, Saloon underneath, no database migrations, no service-provider magic beyond container binding. Worst case is vendor-and-fork, which is cheap here.

Key questions

1. Which roadmap items need Float data, and does every required endpoint exist in the seven documented groups? Enumerate them before committing.
2. Do any of those items require writing to Float or reacting to changes? If yes, scope separately now — this package will not carry it.
3. What are Float API v3's rate limits, and where does the token live? A single API token in .env is fine for one app; it becomes a governance question if multiple services share it.
4. Who owns this dependency if the internal dashboard needs a new endpoint — do we PR upstream, or add Saloon requests in-house?
5. Is Float contractually stable as our resourcing system of record for the planning horizon, or is this a two-quarter bridge?

Integration Approach

Stack fit

Near-perfect for a Laravel-first team. Composer install, .env configuration, container-resolved client, Laravel-idiomatic parameter objects. No queue, cache, or database assumptions imposed — we choose those. The FloatClient injection pattern composes cleanly with the layers we already use: a service class per domain (capacity, utilization) wrapping the client, controllers or Livewire/Inertia pages consuming the services, scheduled commands for snapshot jobs.

The package does not impose a persistence model. That is the right call for an SDK and the right call for us: we should treat Float as the source of truth and decide deliberately whether to cache responses, persist daily snapshots for trend analysis, or query live each time.

Migration path

There is no migration in the data sense — nothing to move off. The migration is code-level, and it only applies if we already have bespoke Float HTTP calls:

1. Inventory existing Float API usage (grep for float.com, any existing Saloon connectors, any Http:: calls to the Float host).
2. Map each existing call to a package resource method or parameter object.
3. Replace incrementally behind existing service interfaces so call sites don't churn.
4. Delete the old connector only after parity is confirmed in staging with real tokens.

If we have no existing Float integration, this is a greenfield adoption — even simpler.

Compatibility

• Requires Laravel (package tracks framework majors; 2.1.0 reportedly adds Laravel 13). Confirm our Laravel/PHP versions against the installed release's composer.json constraints before planning an upgrade window.
• PHP version constraints are not stated in the supplied docs — verify on Packagist. This is a gate, not a detail.
• No known conflicts: no facades, no global helpers, no migration publishing, no route registration. It coexists with other Spatie packages and other Saloon connectors.

Sequencing

1. Spike (1–2 days). Install in a scratch branch, hit each of the seven resource groups against a sandbox or read-only Float token, confirm response shapes and pagination behavior. Explicitly test single-resource gets (the 1.0.1 bug class) rather than only all().
2. Coverage audit. Produce a requirement-to-endpoint matrix for the first roadmap item. This is the go/no-go artifact.
3. First vertical slice. One read-only surface with a real consumer — a utilization dashboard for a single team, or an allocation/time-off conflict view — shipped behind auth.
4. Establish the extension pattern. Before the second consumer, decide and document how we add missing endpoints (upstream PR vs. local Saloon requests). Do this once, early; it prevents divergent in-house patterns.
5. Scale out to remaining consumers, adding caching or snapshot persistence only where read volume or trend requirements justify it.

Operational Impact

Maintenance

Low baseline, with a real tail risk. The package itself needs nothing — no migrations, no config drift, no scheduled tasks. Maintenance cost is concentrated in two places: keeping composer.json constraints current as we move Laravel majors, and filling endpoint gaps as consumers expand. Budget a modest ongoing allocation (a few days per year) plus incremental effort per new endpoint, not a dedicated owner.

The version surface is small and semver-respecting (0.0.x → 1.0.0 → 2.x with a framework-support release), which is a good sign for predictable upgrades. Pin to a caret range and let Renovate/Dependabot surface updates.

Support

No commercial support. Spatie's OSS is community-maintained via GitHub issues and PRs; response times are best-effort. The pragmatic position: we support it ourselves. Keep the fork-or-vendor option warm — MIT license, one composer package, small codebase. If upstream goes quiet and we need an endpoint, we add a Saloon request locally. This is not a "we're blocked" scenario; it's a "we now own 200 lines" scenario.

Document internally: where the token lives, who rotates it, which endpoints we depend on, and where our extensions live. That document is the actual support contract.

Scaling

Two dimensions to plan for:

• Request volume. Default perPage is 50, and the SDK does not appear to auto-iterate pages. Any bulk operation — pulling a year of allocations across all projects, or a full user roster — becomes a manual pagination loop. Naive implementations will produce N sequential round-trips and slow page loads. Wrap bulk reads in queued jobs, cache results with a sensible TTL, and honor Float's rate limits (verify the concrete numbers against Float's docs; they are not in this README).
• Consumer count. The client is stateless and cheap to resolve; horizontal scaling is a non-issue at the PHP layer. The bottleneck is always Float's API and our own call discipline.

For dashboards read on every page load, plan for a cache or a scheduled snapshot table from the start rather than retrofitting it after the first latency complaint.

Failure modes

• Token expiry or rotation. Hard failure across all consumers simultaneously, surfacing as 401s. Mitigate with a single well-documented secret, rotation runbook, and a health check that alerts before users notice.
• Float API outage or degradation. Every read-backed surface breaks. Decide per surface: fail visibly with a clear "resourcing data unavailable" state, or serve last-known-good from cache. Do not let an unhandled exception take out an otherwise-functional admin page.
• Rate limiting (429). Most likely under bulk pagination loops. Needs backoff and, ideally, a queue in front of any wide read.
• Upstream response-shape drift. Float v3 changes or SDK parsing gaps can silently produce malformed/empty objects — the 1.0.1 allocation fix is exactly this class of bug. Add contract tests asserting the fields we actually consume, and validate at the boundary rather than trusting the SDK to shape-check for us.
• Uncovered endpoint gap discovered late. If a roadmap item turns out to need an unwrapped endpoint, the cost is a Saloon request plus a PR-or-fork decision — days, not a re-plan. Worth stating explicitly so nobody treats coverage gaps as existential.

Ramp-up

Hours for a Laravel developer already comfortable with dependency injection and Saloon; a day or two for someone unfamiliar with Saloon to read the request/connector pattern. The README is complete enough to work from for the seven covered groups, and the parameter objects are self-documenting at the call site. Onboarding risk is low, and the knowledge is transferable — what the team learns here applies to every other Saloon-based integration in the codebase.

The real ramp-up cost is domain, not technical: someone needs to understand Float's data model (how allocations, project tasks, and time off actually relate) before any capacity or utilization surface is worth building. Budget for that, not for learning the SDK.