angkor/binary-wrapper

Base abstraction for Laravel packages that wrap Go/Rust CLI binaries

v1.0.0 2026-03-17 10:43 UTC

Requires

• php: ^8.3
• illuminate/contracts: ^11.0|^12.0
• illuminate/process: ^11.0|^12.0
• illuminate/support: ^11.0|^12.0

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.17
• mockery/mockery: ^1.6
• orchestra/testbench: ^9.4|^10.0
• pestphp/pest: ^3.0
• pestphp/pest-plugin-arch: ^3.0
• pestphp/pest-plugin-laravel: ^3.0
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0

MIT

• Angkorian

README

Base abstraction for Laravel packages that wrap Go/Rust CLI binaries.

Overview

This package provides the scaffolding to build Laravel packages around external CLI binaries (Go, Rust, etc.). It handles binary resolution, process execution, error handling, config publishing, and includes a ready-to-use Thumbhash implementation as a reference.

Requirements

• PHP 8.3+
• Laravel 11 or 12

Installation

composer require angkor/binary-wrapper

Usage

Building your own binary wrapper

1. Extend BinaryWrapper

use Angkor\BinaryWrapper\BinaryWrapper;

class MyTool extends BinaryWrapper
{
    protected function defaultBinary(): string
    {
        return 'mytool'; // fallback binary name on PATH
    }

    public function process(string $input): string
    {
        return trim($this->run(['--flag', $input])->output());
    }
}

2. Extend BinaryServiceProvider

use Angkor\BinaryWrapper\BinaryServiceProvider;

class MyToolServiceProvider extends BinaryServiceProvider
{
    protected function wrapperClass(): string
    {
        return MyTool::class;
    }

    protected function configKey(): string
    {
        return 'mytool';
    }

    protected function configPath(): string
    {
        return __DIR__ . '/../config/mytool.php';
    }
}

3. Create a config file (config/mytool.php)

return [
    'binary_path' => env('MYTOOL_BINARY_PATH', '/usr/local/bin/mytool'),
];

The service provider will automatically:

• Merge config from your package
• Bind MyTool in the container, injecting binary_path from config
• Publish config and register the binary:check command when running in console

Publish config

php artisan vendor:publish --tag=mytool-config

Check binary accessibility

php artisan binary:check "App\MyTool"

Thumbhash

This package ships with a Thumbhash implementation that wraps the go-thumbhash CLI binary.

Setup

Register the service provider in config/app.php (auto-discovered via composer.json):

Angkor\BinaryWrapper\Thumbhash\ThumbhashServiceProvider::class,

Set the binary path in your .env:

THUMBHASH_BINARY_PATH=/usr/local/bin/thumbhash

Or publish and edit the config:

php artisan vendor:publish --tag=thumbhash-config

API

use Angkor\BinaryWrapper\Thumbhash\Facades\Thumbhash;

// Encode an image to a base64 thumbhash string
$hash = Thumbhash::encode('/path/to/image.jpg');

// Decode a thumbhash back to a PNG
Thumbhash::decode($hash, '/path/to/output.png');
Thumbhash::decode($hash, '/path/to/output.png', size: 32);

// Convert image to raw RGBA data
$dataPath = Thumbhash::toRawData('/path/to/image.jpg');
$dataPath = Thumbhash::toRawData('/path/to/image.jpg', '/path/to/output.data');

Exceptions

Exception	Thrown when
BinaryNotFoundException	Binary file does not exist at resolved path
ProcessFailedException	Binary exits with a non-zero status code

Testing

composer test
composer analyse
composer format

License

MIT