PHPackages                             angkor/binary-wrapper - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [CLI & Console](/categories/cli)
4. /
5. angkor/binary-wrapper

ActiveLibrary[CLI & Console](/categories/cli)

angkor/binary-wrapper
=====================

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

v1.1.0(1mo ago)0159↓70.4%1MITPHPPHP ^8.3

Since Mar 17Pushed 1mo agoCompare

[ Source](https://github.com/angkordotdev/binary-wrapper)[ Packagist](https://packagist.org/packages/angkor/binary-wrapper)[ RSS](/packages/angkor-binary-wrapper/feed)WikiDiscussions main Synced 3w ago

READMEChangelog (1)Dependencies (24)Versions (3)Used By (0)

angkor/binary-wrapper
=====================

[](#angkorbinary-wrapper)

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

Overview
--------

[](#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
------------

[](#requirements)

- PHP 8.3+
- Laravel 11 or 12

Installation
------------

[](#installation)

```
composer require angkor/binary-wrapper
```

Usage
-----

[](#usage)

### Building your own binary wrapper

[](#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

[](#publish-config)

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

### Check binary accessibility

[](#check-binary-accessibility)

```
php artisan binary:check "App\MyTool"
```

Thumbhash
---------

[](#thumbhash)

This package ships with a Thumbhash implementation that wraps the [go-thumbhash](https://github.com/angkordotdev/go-thumbhash) CLI binary.

### Setup

[](#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

[](#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
----------

[](#exceptions)

ExceptionThrown when`BinaryNotFoundException`Binary file does not exist at resolved path`ProcessFailedException`Binary exits with a non-zero status codeTesting
-------

[](#testing)

```
composer test
composer analyse
composer format
```

License
-------

[](#license)

MIT

###  Health Score

43

—

FairBetter than 90% of packages

Maintenance88

Actively maintained with recent releases

Popularity15

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~40 days

Total

2

Last Release

58d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/b26c90a41092eff8e5a83d3790a63cff5eef411291844571601487148e46a0b8?d=identicon)[angkor](/maintainers/angkor)

---

Top Contributors

[![angkorean](https://avatars.githubusercontent.com/u/167671546?v=4)](https://github.com/angkorean "angkorean (1 commits)")

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/angkor-binary-wrapper/health.svg)

```
[![Health](https://phpackages.com/badges/angkor-binary-wrapper/health.svg)](https://phpackages.com/packages/angkor-binary-wrapper)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3345.1M337](/packages/psalm-plugin-laravel)[illuminate/console

The Illuminate Console package.

13045.3M6.2k](/packages/illuminate-console)[laravel/ai

The official AI SDK for Laravel.

9782.1M161](/packages/laravel-ai)[moonshine/moonshine

Laravel administration panel

1.3k239.9k75](/packages/moonshine-moonshine)[tallstackui/tallstackui

TallStackUI is a powerful suite of Blade components that elevate your workflow of Livewire applications.

721160.4k12](/packages/tallstackui-tallstackui)[illuminate/pipeline

The Illuminate Pipeline package.

9348.3M267](/packages/illuminate-pipeline)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)