Laravel Float Sdk Laravel Package

Product Decisions This Supports

• Build vs. buy on a thin integration layer. This is a small, honest decision, not an architectural one. The package wraps Float's v3 REST API in a Laravel service-container-bound FloatClient with publishable config and typed query-parameter objects (GetUsersParams, GetProjectsParams, GetAllocationsParams, etc.). Realistic saving is 2–5 engineering days versus hand-rolling the same calls with Saloon or plain HTTP. The win is not owning the plumbing and its tests — not unlocking a capability you couldn't otherwise build.
• Read-oriented roadmap items against Float as system of record. The documented surface — users(), projects(), projectTasks(), clients(), allocations(), timeOff(), publicHolidays() — supports concrete features you can put on a roadmap today:
  • Utilization and capacity dashboards (allocations joined to users and project tasks).
  • Allocation-vs-time-off conflict views and holiday-aware scheduling (timeOff() + publicHolidays()).
  • Client/project rollups inside an internal admin panel (clients() with expand: ['projects']).
  • Delivery-ops alerting (over-allocation, unstaffed projects) built on scheduled reads.
• "Don't rip out Float yet." If Float is where the business plans resourcing, this lets you layer delivery-ops and client-facing surfaces on top without a migration business case. That argument holds only while the endpoints you need are already covered — check the list above against your requirements before committing.
• Scoping discipline on the write path. The README states plainly that this is not a full implementation of the Float API. Nothing documented covers creating or updating allocations, logging time, expense submission, webhooks, or event-driven sync. If a roadmap item depends on pushing data into Float or reacting to Float changes in real time, this package does not deliver it — budget that separately and don't let it hide inside an "integration" line item.
• Framework lifecycle planning (low weight). Releases track Laravel versions (2.1.0 adds Laravel 13), so adoption doesn't create a "we're blocked on the Laravel upgrade" conversation next quarter. Marginal, but it's one fewer thing on the maintenance ledger.
• Where it does not help: migration off Float, data warehouse extraction at scale (no bulk export story documented), or anything requiring guarantees Float's API doesn't offer. Pagination exists (page, perPage, default 50) but you own the loop and the rate-limit handling around it.

When to Consider This Package

Adopt when all of the following hold:

• You are on Laravel/PHP and already pay for Float. Setup is genuinely trivial: composer require, two .env variables (FLOAT_API_TOKEN, FLOAT_USER_AGENT), and an optional vendor:publish for config. No onboarding cost worth a meeting.
• Your need is read-only and maps onto the seven resource groups listed above. Validate the endpoint list against your requirements first — this is the single most important gate.
• You want the integration to be someone else's maintenance problem. Spatie maintains it, it's MIT-licensed, has a changelog, tagged releases, and a test suite (composer test).
• Float is a system of record you're keeping, not a system you're exiting.
• The blast radius of the dependency failing is small. It's a read path — if it breaks, dashboards go stale; nothing corrupts.

Look elsewhere — or plan to fork — when any of these apply:

• You need to write to Float or react to Float events. Absent from the documented surface. Build it yourself or wait for a PR to land upstream.
• You need guarantees this package doesn't signal. It has 4 GitHub stars and 0 dependents — essentially no production track record you can point at. That's not disqualifying for a thin SDK, but it means you are the load-bearing adopter. Read the source and the test suite before shipping to production; the whole library is small enough to audit in an afternoon, which is also its safety net.
• You don't need the missing endpoints but need them soon. The README explicitly invites PRs and acknowledges partial coverage. Treat upstream contribution as part of your plan, not as an unlikely edge case — or vendor/fork it so an upstream stall can't block your roadmap.
• You're not on Laravel. The value here is the container binding, config publishing, and Eloquent-era ergonomics. In another framework, call Float's REST API directly; you'd be paying for a wrapper you can't use.
• You need SLAs, support contracts, or a vendor relationship. This is community open source. There is no one to escalate to.

How to Pitch It (Stakeholders)

For executives — one paragraph: Float stays as our resourcing system of record. This is a small, free, MIT-licensed connector that lets our Laravel apps read resourcing data out of Float — who's allocated to what, who's on leave, which clients and projects are live — so we can build utilization dashboards, staffing-conflict alerts, and client reporting without a migration project or new vendor spend. Cost is a few engineering days; the alternative is the same work done by hand. It's deliberately narrow: it reads, it doesn't write, so it can't damage the data in Float. Risk is low and reversible — if it disappoints, we delete a package.

For engineering — the practical version:

• Laravel service-container-bound FloatClient, injectable, config in .env plus a publishable float-sdk-config. No bespoke HTTP layer to write, test, or maintain.
• Typed query-parameter value objects instead of hand-built query strings, with pagination (page, perPage), sort, fields projection, and expand for relationships. Projection and expand are the levers for keeping response sizes and API calls sane.
• Read-only against Float API v3. No writes, no webhooks — plan those as separate work if product asks for them.
• Small enough to audit fully before merge; Spatie-maintained with tagged releases, a changelog, and a test suite. Releases track Laravel versions, so it won't gate an upgrade.
• Two caveats to state up front, not discover later: coverage is explicitly partial (contributions welcome, and we may need to make some), and adoption is essentially zero (4 stars, 0 dependents) — so we own the fallback. Mitigation: wrap calls behind our own thin gateway interface so the SDK is swappable and our domain code doesn't import Spatie\FloatSdk types directly.
• Ask: a timeboxed spike — wire up one real read path (allocations for a date range) end to end, including pagination and error handling, then decide. If the spike is clean, the rest of the roadmap items are variations on the same call.