Laravel Harvest Sdk Laravel Package

Product Decisions This Supports

• Build vs. buy for Harvest integration work. If Harvest is already the system of record for time tracking, this package converts "build an API client" (auth, pagination, DTO mapping, error surfaces) into a composer require plus config. That's roughly a sprint of defensive plumbing you don't fund.
• Roadmap sequencing for reporting and operations features. The exposed surface — authenticated user, all users, all projects, and paginated time entries with is_running — maps directly onto the highest-value early bets:
  • Utilization and billable-hours dashboards
  • Project/capacity views that need project + user + time-entry joins
  • "Who is tracking right now" presence/status widgets (is_running, added in 1.0.1)
  • Timesheet ingestion for payroll or client-invoice reconciliation
  • A read-only Harvest mirror inside the product, so dashboards never hit Harvest live
• Scoping the MVP as read-only. Because write endpoints (start/stop timers, create/edit time entries), plus invoices, expenses, estimates, and webhooks are not implemented, this package supports "read and mirror" but not "operate Harvest from our app." That's a product-scoping fact, not an engineering detail — it constrains whether the feature can promise two-way sync.
• Cost and lock-in posture. MIT license, no per-seat or per-call fee, no vendor contract. Exit cost is low: an interface wrapper means replacing it is a class, not a refactor.
• Multi-tenant / per-customer Harvest ambitions get deferred. The env-var credential model assumes one long-lived personal access token for one account. Any roadmap item involving customers authorising their own Harvest account (OAuth, token refresh, per-tenant credentials) is not supported and should be treated as net-new work, not an extension.

When to Consider This Package

Adopt when most of these hold:

• The stack is Laravel/PHP and Harvest is already the source of truth for time.
• The near-term need is read-heavy: users, projects, time entries, utilization, sync into local tables.
• You want first-class Laravel ergonomics — container binding, facade, publishable config, typed DTOs, HTTP-fake-friendly testing — rather than hand-rolling Guzzle calls.
• The team values a maintained-by-Spatie baseline (tests, changelog, releases, Laravel 13 support) over a large community.
• You can absorb missing endpoints with a thin fallback (Http::withToken(...) mapped into the same DTOs) without changing callers.

Look elsewhere — or budget for a hand-rolled client — when:

• Write operations are on the roadmap. Starting/stopping timers, creating or editing time entries, invoices, estimates, expenses, tasks, roles. Missing methods are a scope change, not a config toggle.
• You need event-driven sync. No documented webhooks; you'll be running scheduled overlapping-window polls (a few days of lookback to catch retroactive edits) instead of reacting to changes.
• You need multi-account OAuth. Token refresh and per-tenant credentials are undocumented; you own that entirely.
• You need vendor accountability. 1 GitHub star, 0 dependents, and an explicitly partial README mean no support SLA, no deprecation notice when Harvest's API drifts, and no crowd-sourced bug surfacing.
• You're not on Laravel/PHP, or you want a single integration layer shared across services in other languages.
• You need a "give me everything" backfill. Time entries require a from date by Harvest API design — bound queries and chunk by month regardless of client.

Assessment against the package's own signal: strong provenance (Spatie, tests, changelog, recent releases) but thin adoption (1 star, 0 dependents) and a self-declared incomplete surface. Treat it as a credible accelerator for the read path, not a platform dependency.

How to Pitch It (Stakeholders)

To executives (one paragraph): Harvest is where our time data lives, and we need to surface it in-product. This is a free, MIT-licensed Laravel SDK from Spatie — a well-known PHP shop — that handles authentication, pagination, and typed response objects for the pieces we need first: users, projects, and time entries. It lets us ship a read-only utilization view in days rather than weeks, with essentially no licensing cost and low switching cost later. Two honest caveats: it does not cover writing back to Harvest (starting timers, editing entries) or invoices and expenses, and it has very little community adoption, so we would own any gaps and any breakage if Harvest changes its API. Recommendation: adopt it behind our own internal interface, ship the read-only sync first, and treat write-back and multi-tenant OAuth as separately estimated work if the roadmap demands them.

To engineering (the asks):

• Wrap it in a HarvestGateway interface on day one. Controllers and jobs must never reference Spatie\Harvest\Facades\Harvest directly — this is the single decision that keeps the incomplete surface and the low adoption from becoming our problem.
• Sync into local tables; never fan out to Harvest per page load. Use an overlapping lookback window (a few days) instead of "since last sync" to absorb retroactive edits, since webhooks aren't available.
• Consume the paginator incrementally in jobs; reserve ->collect() for short ranges and interactive use. Chunk backfills by month with one job per chunk for retry granularity.
• Cache slow-moving resources (users, projects) aggressively; never cache time entries.
• Pin real Harvest payloads as fixtures and lean on Http::preventStrayRequests() in CI. DTO hydration tests are our only warning system for upstream API drift.
• Before any roadmap commitment, grep the vendored src/ for the endpoint. A missing method is a 10-minute fallback, but it is a scope change — surface it early, not mid-sprint.