Onesky Bundle Laravel Package

Getting Started

A necessary reality check before any setup: openclassrooms/onesky-bundle is a Symfony bundle, not a Laravel package. It registers via Symfony's bundle system and ships an OpenClassroomsOneSkyBundle plus a DI extension. There is no ServiceProvider, no facade, no auto-discovery. For a Laravel developer the realistic options are:

1. Ignore the bundle, use the underlying onesky/php-sdk. This is what the bundle wraps anyway, and it is the recommended path.
2. Use the bundle only if you maintain a Symfony service alongside your Laravel app.

Minimal setup (Laravel path, recommended):

composer require onesky/php-sdk

Bind the client as a singleton in AppServiceProvider:

$this->app->singleton(\OneSky\ApiClient::class, fn () => new \OneSky\ApiClient(
    config('services.onesky.api_key'),
    config('services.onesky.api_secret'),
));

Then create one Artisan command (onesky:pull) that calls $client->translations->download($projectId) and writes the returned file(s) into lang/{locale}/.

Minimal setup (Symfony path, if you're actually on Symfony):

composer require openclassrooms/onesky-bundle

Register OpenClassrooms\Bundle\OneSkyBundle\OpenClassroomsOneSkyBundle in config/bundles.php, then:

openclassrooms_one_sky:
    api_key: '%env(ONESKY_API_KEY)%'
    api_secret: '%env(ONESKY_API_SECRET)%'
    project_id: '%env(ONESKY_PROJECT_ID)%'

First useful command: bin/console onesky:download --locale=fr_FR. If it produces non-empty output, credentials are wired correctly.

Where to look first in the repo: the Command/ and Service/ directories. They are thin and read well as a recipe for what you need to replicate.

Implementation Patterns

• Round-trip translation loop. Push source strings up → translators work in OneSky → pull completed locales down. In Symfony: onesky:upload / onesky:download. In Laravel: two Artisan commands driven by $schedule->command('onesky:pull')->hourly() and a separate push triggered by a deploy step.
• Per-locale, not bulk. Call once per locale (loop over config('app.locales')) instead of a single "download all." A failure on zh_Hans should not roll back a successful fr_FR, and you get clearer logs.
• File-format bridge. OneSky exchanges translation files as JSON, YAML, .strings, or .properties. Laravel's __() loader reads PHP arrays (resources/lang/{locale}/*.php) or JSON (resources/lang/{locale}.json). Pick JSON — it maps cleanly — and either commit it directly or transform to PHP arrays in a second step.
• Config-driven file list. Hold the set of source files you manage in one place (a config array). Do not glob at runtime: the upload must be deterministic so OneSky's project files stay in sync.
• CI integration. Add a "pull to temp dir, diff against HEAD" job. If translations moved, fail the pipeline or open a PR. This detects stale locale files before release.
• Extend, don't fork. The bundle's commands are small wrappers over the SDK. Copy the command shape into your own command and inject only the file subsets you care about (e.g. only files touched in a PR) rather than editing the vendor bundle.

Gotchas and Tips

1. No Laravel auto-discovery. Composer installs it fine, but Laravel won't boot it. Attempting to resolve its services yields Target [...] is not instantiable. Bind the SDK yourself.
2. Treat it as a reference, not a dependency. The repo shows zero stars and zero dependents on Packagist — that is a signal of low maintenance. Pin the underlying onesky/php-sdk version and expect to own the wrapper long-term.
3. Locale-code mismatch is the #1 silent failure. OneSky expects identifiers like fr-FR, zh-Hans, pt-BR; Laravel commonly uses fr_FR, zh_CN. Map these explicitly. The symptom is a successful download that produces an empty or English-only file.
4. Empty results exit 0. A pull that returns zero strings usually reports success. Assert on file size or string count before overwriting resources/lang/, or you'll blank out a locale on a transient API hiccup.
5. Config key casing. Symfony uses snake_case YAML (api_key, project_id). If you reimplement the config, mirror the bundle's DependencyInjection/Configuration.php exactly — the SDK sometimes expects camelCase internally and silently ignores the wrong key.
6. File-name sync. OneSky identifies project files by name. Push messages.json and pull messages.en.json and you'll get partial merges. Keep push and pull pointing at the same canonical names.
7. No retries baked in. The SDK uses Guzzle; the bundle adds no retry logic. Wrap calls with retry(3, 1000) or Guzzle's RetryMiddleware — OneSky's API rate-limits under bulk operations.
8. Log hygiene. The Symfony bundle logs requests in dev; if you lift that pattern into Laravel, strip the Authorization/signature header before anything hits storage/logs.
9. Testing. There's no built-in fake or mock client. Once you're on the SDK directly, use Laravel's Http::fake() (the SDK uses Guzzle, which Http::fake() intercepts) or bind a fake ApiClient interface in feature tests.
10. Escape hatch is cheap. If the bundle ever blocks you, replace it with a ~100-line OneSkyService around onesky/php-sdk. You lose almost nothing and gain a surface you can maintain.