Fitbit Interface Bundle Laravel Package

Getting Started

This bundle is a thin Symfony wrapper around Fitbit's OAuth 2.0 + REST API, targeting the Symfony 2.3–3.x era. Because the project is archived and effectively undocumented beyond its README, budget time to read the source before wiring it in.

1. Install and pin. Add nibynool/fitbit-interface-bundle to composer.json and commit the lock file. Since the repo is archived, there will be no patch releases — treat the resolved version as frozen.
2. Register the bundle. On Symfony 2/3 add it to app/AppKernel.php (new Nibynool\FitbitInterfaceBundle\FitbitInterfaceBundle()). On Symfony 4+ bundle registration is gone and this package will almost certainly not boot — confirm compatibility before committing to it.
3. Read three files first, in this order:
   • README.md — the only usage hint you'll get.
   • DependencyInjection/Configuration.php — the authoritative list of config keys (consumer key/secret, redirect URI, scopes, token storage).
   • Resources/config/services.yml — the service IDs you'll inject (typically a Fitbit client plus an auth/token service).
4. Configure credentials under the bundle's root key (e.g. fitbit_interface:) in config.yml, sourcing the consumer key/secret from parameters.yml / environment variables rather than hardcoding them.
5. Import the bundle's routing if it ships an OAuth callback controller (Resources/config/routing.yml), or plan to write your own callback action.
6. First use case: authenticate a single test user, then fetch their profile or today's activity summary and dump it from a controller. That single round-trip exercises config, the OAuth handshake, token persistence, and the API client — if that works, everything else is repetition.

Expect to spend the first hour reverse-engineering the service graph; there is no getting-started guide.

Implementation Patterns

Inject the client, don't instantiate it. Register the bundle's client service as a constructor dependency of your own FitbitService/repository class. This gives you one seam to mock in tests and one place to add caching, retries, and logging.

Own the OAuth lifecycle explicitly. The bundle will hand you an authorization URL and expect a callback route. Persist access + refresh tokens yourself (Doctrine entity keyed by user) — do not rely on session storage for anything beyond the initial handshake, or users get logged out and tokens are lost. Implement a "get valid token" method that refreshes when expires_at is near and re-persists; call it before every API request rather than assuming the token is fresh.

Wrap API calls behind intent-named methods. Instead of scattering $client->get('activities/...') across controllers, expose getDailySteps(User $user, \DateTime $day), getSleepLog(...), etc. Fitbit's endpoints have fiddly path/date formatting and response envelopes; centralizing them saves you from fixing the same bug in five places.

Synchronize via console commands, not web requests. Fitbit enforces per-user rate limits (historically ~150 requests/hour), so a synchronous "import my last year of data" web action will fail. Write a Symfony command that iterates users, paces requests, and writes to your own tables; schedule with cron or a scheduler bundle. This also decouples your UI from Fitbit's latency and outages.

Cache aggressively. Store raw responses (or a normalized projection) with a TTL keyed by user + endpoint + date. Historical days never change, so cache them indefinitely; only today's data needs a short TTL.

Normalize units and dates at the boundary. Fitbit returns distances in the user's unit preference and dates as YYYY-MM-DD strings in the user's timezone. Convert to your domain's canonical units/timezone as soon as the response lands, so downstream code never sees Fitbit-shaped data.

Testing. Mock your own wrapper (or the bundle's client service) rather than the HTTP layer. Keep one integration test against a recorded fixture set so you notice when the archived client drifts from Fitbit's current API.

Gotchas and Tips

• The package is archived with 1 star and zero dependents. There is no security patching and no maintainer response. Before adopting, consider calling the Fitbit REST API directly with Guzzle + league/oauth2-client — you'd trade a few hours of setup for a supported dependency and far better docs. If you must use this bundle, isolate it behind your own service so it's replaceable.
• Symfony version lock-in. Bundle-style registration and Resources/config conventions mean this realistically targets Symfony ≤3.4. On modern Symfony you'll be fighting the container, not the Fitbit API.
• OAuth scope and redirect URI mismatches are the top cause of "it just 401s." The redirect URI registered in your Fitbit app dashboard must match the configured value character for character, including trailing slash and scheme. Scopes requested at auth time must include everything any later call touches — you cannot silently add scopes without re-consent.
• Tokens expire and refresh tokens rotate. If you cache the client object across requests without refreshing, you'll see intermittent 401s that disappear on redeploy (because the session reset). Log token expiry timestamps.
• Config keys are undocumented. When a setting appears ignored, check DependencyInjection/Configuration.php for the real key name and whether the extension aliases it under a parameters key. Typos in YAML config fail silently in Symfony 2-era bundles more often than you'd like.
• Rate limiting looks like an auth bug. Fitbit returns 429s that clients sometimes surface as generic failures. Inspect the raw status code and Fitbit-Rate-Limit-Remaining headers; add exponential backoff in your command loop.
• Debugging: enable the Symfony profiler and log outgoing HTTP at the Guzzle handler level, but redact Authorization headers. When responses are empty, log the raw JSON body — the bundle may swallow error payloads into generic exceptions.
• Extension points are limited but real: override the bundle's service definitions in your app's services.yml (same ID, your class), decorate the client service, or replace the token storage implementation. Prefer decoration over editing vendor code, since you can never expect an upstream fix.
• Date/timezone bugs are endemic. Fitbit resolves "today" against the user's profile timezone, not your server's. Always pass explicit dates and never trust now().
• Fork it internally if you plan to keep it. With an archived upstream, vendoring the package or maintaining a private fork is the only sustainable path; at minimum, write a smoke test that hits the live API weekly so you learn about breakage from Fitbit before your users do.