Api Library Php5 Laravel Package

Getting Started

Install and pin. The package targets PHP 5.x and has no active maintenance, so treat the version constraint as load-bearing.

composer require onesky/api-library-php5

On a modern runtime you may need --ignore-platform-reqs, and you should run your test suite against the target PHP version before committing — see the Gotchas section for the specific PHP 7/8 breakages.

Where to look first.

1. vendor/onesky/api-library-php5/README.md — usually one usage example, no reference docs.
2. vendor/onesky/api-library-php5/src/OneSky/Api/Client.php — this is the whole library. Every public method is a thin cURL call to https://platform.api.onesky.io/1/<resource>/<action>. Reading this file once tells you more than the README.
3. OneSky dashboard → Account settings → API keys for the key/secret pair, and the project's numeric ID.

The examples below use method names that mirror the REST endpoints 1:1; confirm the exact signatures against Client.php, since the README is thin and the naming isn't perfectly consistent.

Auth model. You pass an API key and a secret to the client constructor. The library derives a dev_hash from sha1(timestamp . secret) on every request — the secret itself never goes over the wire. There is no OAuth flow, no token refresh, no session.

First use case: one-way export into CI. This is the highest-value, lowest-risk thing to do with the library. You pull translations out of OneSky and write them into your app; you never write back, so there's no way to clobber a translator's work while you're learning the API.

<?php
require __DIR__ . '/vendor/autoload.php';

use OneSky\Api\Client;

$client = new Client(
    getenv('ONESKY_API_KEY'),
    getenv('ONESKY_API_SECRET')
);

$projectId = (int) getenv('ONESKY_PROJECT_ID');

// 1. confirm the project and see which locales are enabled
$locales = array_column($client->getLocales($projectId), 'code');

// 2. pull one locale and write it to disk
$payload = $client->getTranslations($projectId, 'fr', 'json');
file_put_contents(__DIR__ . '/lang/fr.json', $payload);

Get this working end-to-end for a single locale before touching uploads. Once export is reliable, adding a push step on deploy is a small increment.

Implementation Patterns

Scheduled export job (the 80% case). Run it as an Artisan command on a schedule, not in a request. Cache the raw response per locale so a flaky API doesn't break a deploy, and fail the whole job if any single locale fails — a partially-synced language directory is worse than a stale one.

class SyncOneSky extends Command
{
    protected $signature = 'onesky:sync {locale?} {--format=json}';

    public function handle(Client $client): int
    {
        $projectId = config('services.onesky.project');
        $format    = $this->option('format');

        $locales = $this->argument('locale')
            ? [$this->argument('locale')]
            : array_column($client->getLocales($projectId), 'code');

        foreach ($locales as $locale) {
            $raw = retry(3, 500, function () use ($client, $projectId, $locale, $format) {
                return $client->getTranslations($projectId, $locale, $format);
            });

            Cache::put("onesky:{$projectId}:{$locale}:{$format}", $raw, now()->addHour());
            Storage::disk('lang')->put("{$locale}.json", $raw);
        }

        return self::SUCCESS;
    }
}

Push source strings on release, not on every commit. Upload your canonical en file once per deploy so translators see new keys immediately. Use a stable filename per file — OneSky treats a new filename as a new file and an existing filename as an update, so messages.json is right and messages-2024-06-01.json will slowly fill the project with orphaned files.

$client->uploadFile(
    $projectId,
    base_path('lang/en/messages.json'),
    'json',
    'en'
);

Separate read and write paths. Give your web app only the export path (read-only, cached, behind a scheduled job). Put uploads and order placement behind a console command or CI job. This keeps a compromised app server from being able to overwrite translation state.

Wrap it in an interface. Don't inject OneSky\Api\Client into application code. Define a narrow TranslationProvider interface (export(string $locale): string, push(string $locale, string $path): void), bind the OneSky adapter as a singleton in a service provider, and bind a fake in tests. The third-party class is not something you want in 40 constructors when you eventually replace it.

$this->app->singleton(Client::class, fn () => new Client(
    config('services.onesky.key'),
    config('services.onesky.secret')
));

$this->app->bind(TranslationProvider::class, OneSkyProvider::class);

Integrate at the loader level. If you're on Laravel, the cleanest seam is a custom translation Loader that reads from the cache the sync job populates. Overriding Translator directly tends to fight the framework; a FileLoader subclass that falls through to the synced JSON is less invasive.

Ordering translations. Place an order for a locale and then stop. Configure a OneSky webhook to hit your app when the order completes rather than polling getOrder in a loop — polling burns rate limit and adds latency for no benefit. If you must poll, back off from 30s to 10m and cap it.

Queue every call. No OneSky call belongs in a synchronous HTTP request. Latency is unpredictable and a hung API will exhaust your PHP-FPM workers.

One project per app, not per environment. Use separate files or string tags to separate staging from production strings; separate projects fragment the translator's memory and your glossary.

Gotchas and Tips

PHP 5-era code on PHP 7.4/8.x. The usual suspects: each(), create_function(), dynamic property assignment (deprecated in 8.2, fatal without #[AllowDynamicProperties]), and utf8_encode/utf8_decode (removed in 8.4). Most of these are in the request-building path, so you'll find out on the first call rather than at autoload time. Fork, patch, and pin to your fork via a VCS repository entry in composer.json — don't patch vendor/.

No retries, no timeouts. The client is raw cURL. A slow OneSky response hangs the process indefinitely. Wrap every call in your own retry with a timeout (Http::timeout-style semantics don't apply here — you'll need to set CURLOPT_TIMEOUT, which means the client either needs a constructor option or you need to subclass it). This is the single most important thing to fix before production.

dev_hash and clock skew. The signature is timestamp-based. A container whose clock has drifted more than a few minutes gets a 401, and the error body says nothing about time. If auth fails on a machine that "definitely has the right key," check date first. Keep NTP on in your container images.

Pagination is silent. projects/list and similar list endpoints accept page and per_page and return pagination metadata. A naive call gets page one only. If you have more than a couple dozen locales or projects, assert on the meta block rather than trusting the array length.

Uploads can delete translations. Pushing a source file whose keys have been removed will drop those keys and their translations unless you pass the "keep all strings" flag. Always upload with it set when you're pushing incremental source changes; only do a full replacement when you actually intend to.

BOMs become phantom keys. A UTF-8 BOM at the head of your source file turns the first key into \uFEFFfirst_key and it will never match. Strip BOMs in CI.

Failure mode is inconsistent. Some methods throw, some return ['meta' => ['status' => 4xx]] as a plain array. Audit Client.php endpoint by endpoint and normalize to exceptions in your adapter on day one, otherwise half your error handling will silently do nothing.

Secrets and project IDs. Key and secret go in env vars only. The project ID isn't secret, but don't hardcode it per-branch in config/ — read it from env so a misconfigured staging deploy can't write into production's translation memory.

Debugging. Log the full request URL and the meta block from the response on every failure; OneSky support will ask for the timestamp when you report an auth issue. For a fast local loop, subclass the client and point the base URL at a local request-echo server to see exactly what's being sent.

Extension points. Adding a missing endpoint is genuinely a five-line method — copy an existing one, change the path and params. Do it in a subclass in your own namespace, not in vendor/. A logging or retry decorator implementing the same public surface as Client is the cleanest way to add cross-cutting behaviour.

Long-term view. With 19 stars and no recent activity, treat this as a reference implementation of the auth scheme rather than a dependency you can rely on for years. The OneSky REST API itself is stable. If you find yourself needing typed responses, PSR-18 transport, or proper error classes, reimplementing the five or six endpoints you actually use against Guzzle is a day's work and removes the package from your risk register.