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.0.0(1mo ago)013—0%MITPHPPHP ^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 1mo ago

READMEChangelogDependencies (12)Versions (2)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

39

—

LowBetter than 86% of packages

Maintenance89

Actively maintained with recent releases

Popularity8

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity48

Maturing project, gaining track record

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

Unknown

Total

1

Last Release

54d ago

### Community

Maintainers

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

###  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

[illuminate/console

The Illuminate Console package.

12944.1M5.1k](/packages/illuminate-console)[laravel-zero/framework

The Laravel Zero Framework.

3371.4M368](/packages/laravel-zero-framework)[worksome/envy

Automatically keep your .env files in sync.

6871.8M](/packages/worksome-envy)[bestmomo/nice-artisan

Web interface for Laravel Artisan

215149.3k](/packages/bestmomo-nice-artisan)[mwguerra/web-terminal

A web-based terminal component for Filament/Laravel with command whitelisting and multiple connection types

251.1k](/packages/mwguerra-web-terminal)[innoge/laravel-rclone

A sleek PHP wrapper around rclone with Laravel-style fluent API syntax

174.1k](/packages/innoge-laravel-rclone)

PHPackages © 2026

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