Programmatic Usage

The Stringhive facade gives you direct access to every Stringhive API operation from PHP. Useful for custom scripts, queue jobs, or anything where you need more control.

use Stringhive\Facades\Stringhive;

// or inject the client directly
public function __construct(private \Stringhive\Stringhive $stringhive) {}

push()

Push source strings from your lang directory to a hive.

$result = Stringhive::push(
    hive: 'my-app',
    langPath: null,             // defaults to lang_path()
    sourceLocale: null,         // defaults to config('app.locale')
    sync: false,                // delete strings absent from the import
    conflictStrategy: 'keep',   // 'keep' or 'clear'
    withTranslations: false,    // also push non-source locale files
    exclude: ['auth.php'],      // filenames/globs to skip
    include: ['app.php'],       // if non-empty, only matching files are pushed
);

// [
//   'source' => ['created' => 12, 'updated' => 3, 'unchanged' => 1230, 'translations_cleared' => 0],
//   'translations' => [], // populated when withTranslations: true
// ]

pull()

Export translated files from a hive and write them to disk.

$result = Stringhive::pull(
    hive: 'my-app',
    langPath: null,             // defaults to lang_path()
    locale: 'es',              // null pulls all non-source locales
    format: null,              // 'php' or 'json'; null auto-detects from existing files
    dryRun: false,
    includeSource: false,      // also pull the source locale
    sourceLocale: null,        // defaults to config('app.locale')
    exclude: ['auth.php'],
    include: ['app.php'],
);

// [
//   'files'   => ['app.php' => '<?php return [...];', ...],
//   'paths'   => ['/var/www/lang/es/app.php', ...],
//   'written' => true,
// ]

locales()

All locales available on the platform:

$locales = Stringhive::locales();
// [['code' => 'en', 'name' => 'English', 'region' => 'US', 'rtl' => false, 'is_popular' => true], ...]

hives()

List all hives your token can see:

$hives = Stringhive::hives();
// [['slug' => 'my-app', 'name' => 'My App', 'source_locale' => 'en', 'locales' => ['es', 'fr'], ...]]

hive()

Stats for a single hive, including per-locale translation progress:

$hive = Stringhive::hive('my-app');
// [
//   'slug' => 'my-app',
//   'string_count' => 1245,
//   'locales' => ['es' => ['translated' => 1200, 'approved' => 1100, ...]]
// ]

keys()

Fetch all keys registered in a hive (no pagination):

$response = Stringhive::keys('my-app');
// [
//   'total' => 150,
//   'keys'  => [
//     ['key' => 'auth.login', 'file' => 'auth.php'],
//     ...
//   ],
// ]

strings()

Fetch source strings with pagination, or filter by file:

// Paginate
$page = Stringhive::strings('my-app', page: 2, perPage: 50);
// ['data' => [...], 'meta' => ['total' => 1245, 'last_page' => 25, ...]]

// Filter by file
$strings = Stringhive::strings('my-app', file: 'auth.php');

allStrings()

Convenience method that loops all pages and returns every string at once:

$all = Stringhive::allStrings('my-app');

importStrings()

Push new or updated source strings. Nested arrays are flattened to dot notation automatically. Keys not in the payload are left untouched.

$result = Stringhive::importStrings('my-app', [
    'app.php' => ['welcome' => ['title' => 'Welcome']],
    'auth.php' => ['login' => ['email' => 'Email Address']],
]);
// ['created' => 2, 'updated' => 0, 'unchanged' => 1243, 'translations_cleared' => 0]

Control what happens to existing translations when a source value changes:

Stringhive::importStrings('my-app', $files, conflictStrategy: 'clear');

syncStrings()

Like importStrings(), but also permanently deletes strings not present in your payload (scoped per file). The payload represents the complete desired state.

$result = Stringhive::syncStrings('my-app', $files);
// ['created' => 2, 'updated' => 0, 'unchanged' => 1240, 'deleted' => 3, 'translations_cleared' => 0]

importTranslations()

Push translated strings for a specific locale:

$result = Stringhive::importTranslations('my-app', 'es', [
    'app.php' => ['welcome' => ['title' => 'Bienvenido']],
]);
// ['created' => 1, 'updated' => 0, 'skipped' => 0, 'unknown' => 0]

Existing translations are skipped by default. To overwrite them:

Stringhive::importTranslations('my-app', 'es', $files, overwriteStrategy: 'overwrite');

export()

Return file contents as a filename → string map (does not write to disk):

// One locale, JSON format
$export = Stringhive::export('my-app', locale: 'es');
// ['files' => ['app.json' => '{"welcome.title":"Bienvenido"}', ...]]

// All locales at once
$export = Stringhive::export('my-app');
// ['files' => ['en.json' => '{...}', 'es.json' => '{...}']]

// Laravel PHP array format
$export = Stringhive::export('my-app', format: 'php', locale: 'es');

Error handling

Every error maps to a typed exception:

use Stringhive\Exceptions\AuthenticationException;
use Stringhive\Exceptions\ForbiddenException;
use Stringhive\Exceptions\HiveNotFoundException;
use Stringhive\Exceptions\StringLimitException;
use Stringhive\Exceptions\ValidationException;

try {
    Stringhive::importStrings('my-app', $files);
} catch (StringLimitException $e) {
    // time to upgrade your plan
} catch (ValidationException $e) {
    $errors = $e->errors(); // ['field' => ['error message']]
} catch (HiveNotFoundException $e) {
    // slug typo?
}

Typed Resources

Prefer objects over arrays? Each response type has a readonly resource class:

use Stringhive\Resources\LocaleResource;
use Stringhive\Resources\HiveResource;
use Stringhive\Resources\SourceStringResource;
use Stringhive\Resources\TranslationStatsResource;

$locales = array_map(
    fn ($l) => LocaleResource::fromArray($l),
    Stringhive::locales()
);

$locales[0]->code;       // 'en'
$locales[0]->isPopular;  // true

$strings = array_map(
    fn ($s) => SourceStringResource::fromArray($s),
    Stringhive::allStrings('my-app')
);

$strings[0]->key;          // 'auth.login'
$strings[0]->sourceValue;  // 'Log in'
$strings[0]->isPlural;     // false
$strings[0]->file;         // 'auth.php'