PHPackages                             jobmetric/flyron - 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. [Utility & Helpers](/categories/utility)
4. /
5. jobmetric/flyron

ActiveLibrary[Utility & Helpers](/categories/utility)

jobmetric/flyron
================

Flyron is a PHP package for asynchronous programming using Fibers and process-based concurrency, specially designed for Laravel applications.

1.0.1(7mo ago)20[1 issues](https://github.com/jobmetric/flyron/issues)MITPHPPHP >=8.1CI passing

Since Oct 20Pushed 4mo agoCompare

[ Source](https://github.com/jobmetric/flyron)[ Packagist](https://packagist.org/packages/jobmetric/flyron)[ Docs](https://doc.jobmetric.net/package/flyron)[ GitHub Sponsors](https://github.com/sponsors/majidmohammadian)[ RSS](/packages/jobmetric-flyron/feed)WikiDiscussions master Synced 1mo ago

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

[![Contributors](https://camo.githubusercontent.com/826eeb7cf324284fae0b1cc2b2123cf4a80567001ae68d0bcdf4d4916f3c7b24/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f636f6e7472696275746f72732f6a6f626d65747269632f666c79726f6e2e7376673f7374796c653d666f722d7468652d6261646765)](https://github.com/jobmetric/flyron/graphs/contributors)[![Forks](https://camo.githubusercontent.com/b7a4830027a413d87f374e74ebb7a78977b786adaaa5178adba13cc2e3b9a006/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f666f726b732f6a6f626d65747269632f666c79726f6e2e7376673f7374796c653d666f722d7468652d6261646765266c6162656c3d466f726b)](https://github.com/jobmetric/flyron/network/members)[![Stargazers](https://camo.githubusercontent.com/93468b06e361b4886fa1b1496d08e6c4c637dc572a1f6c6edd75cc4e35e81f94/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f6a6f626d65747269632f666c79726f6e2e7376673f7374796c653d666f722d7468652d6261646765)](https://github.com/jobmetric/flyron/stargazers)[![MIT License](https://camo.githubusercontent.com/2d47fa63b1d9d254f448ecd142312bf7108cd16114db615167929b30f72534d4/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6a6f626d65747269632f666c79726f6e2e7376673f7374796c653d666f722d7468652d6261646765)](https://github.com/jobmetric/flyron/blob/master/LICENCE.md)[![LinkedIn](https://camo.githubusercontent.com/eb590f47a3fca74584d18db8dd3e985ae3d786f50cd41b7530c3af3885da233c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f2d4c696e6b6564496e2d626c75652e7376673f7374796c653d666f722d7468652d6261646765266c6f676f3d6c696e6b6564696e26636f6c6f72423d353535)](https://linkedin.com/in/majidmohammadian)

Flyron
======

[](#flyron)

Flyron is a PHP package for `asynchronous programming` using `Fibers` and `process-based` concurrency, specially designed for Laravel applications.

Install via composer
--------------------

[](#install-via-composer)

Run the following command to pull in the latest version:

```
composer require jobmetric/flyron
```

### Publish the config

[](#publish-the-config)

Copy the `config` file from `vendor/jobmetric/flyron/config/config.php` to `config` folder of your Laravel application and rename it to `flyron.php`

Run the following command to publish the package config file:

```
php artisan vendor:publish --provider="JobMetric\Flyron\FlyronServiceProvider" --tag="flyron-config"
```

You should now have a `config/flyron.php` file that allows you to configure the basics of this package.

Why Flyron? (Philosophy)
------------------------

[](#why-flyron-philosophy)

- Build `async` flows without losing code readability. Fibers + Promises keep your code straightforward while managing waiting (I/O, network, timers).
- Offload heavy or isolated work to safe background `processes` (AsyncProcess) with signed payloads, optional encryption, and PID tracking.
- Not every async need fits queues. Sometimes you want to execute a `Closure` right now, in a separate process, without defining a new Job class. Flyron covers that gap.

Key choices:

- Use `Async + Promise` for cooperative, in-process concurrency (I/O-bound, step-wise logic).
- Use `AsyncProcess` for isolated or long-running tasks (heavy CPU, independent lifecycle, separation of failure).

---

Quick Start
-----------

[](#quick-start)

```
use JobMetric\Flyron\Facades\Async;

$promise = Async::run(fn (int $x) => $x + 1, [41]);
$value = $promise->run(); // 42
```

```
use JobMetric\Flyron\Facades\AsyncProcess;

$pid = AsyncProcess::run(function () {
    file_put_contents(storage_path('app/report.txt'), 'done');
}, [], [
    'label' => 'make-report',
    'timeout' => 30,
]);
```

Important:

- Set a valid `APP_KEY` (payloads are signed). For extra security, enable `encryption` in `config/flyron.php`.
- Manage PID and payload folders via built-in console commands and scheduling.

---

Async and Promise
-----------------

[](#async-and-promise)

Async runs your callback inside a `Fiber` and returns a `Promise`. Promise supports `then`, `map`, `tap`, `recover`, `finally`, `cancel`, `withTimeout`.

```
use JobMetric\Flyron\Concurrency\Promise;

$result = Promise::from(fn () => 10)
    ->tap(fn ($v) => info('Tap: '.$v))
    ->map(fn ($v) => $v + 5)
    ->then(fn ($v) => Promise::from(fn () => $v * 2))
    ->finally(fn () => info('Done'))
    ->run(); // 30
```

Timeout and cooperative cancellation:

```
use JobMetric\Flyron\Facades\Async;
use JobMetric\Flyron\Concurrency\CancellationToken;
use RuntimeException;

$token = new CancellationToken();

$p = Async::run(function () use ($token) {
    for ($i = 0; $i < 10_000; $i++) {
        \JobMetric\Flyron\Async::checkpoint($token, 'Operation cancelled');
    }
    return 'ok';
}, [], 200, $token);

$token->cancel();

try {
    $p->run();
} catch (RuntimeException $e) {
    // timed out or cancelled
}
```

Helpers:

- `Async::delay(int $ms)` — cooperative sleep.
- `Async::checkpoint(?CancellationToken $token, string $message = 'Operation cancelled.')` — throw if cancelled.

---

Await Utilities
---------------

[](#await-utilities)

```
use JobMetric\Flyron\Concurrency\Await;
use JobMetric\Flyron\Concurrency\Promise;

$values = Await::all([
    Promise::from(fn () => 1),
    Promise::from(fn () => 2),
]); // [1, 2]

$first = Await::race([
    Promise::from(function () { usleep(10_000); return 'late'; }),
    Promise::from(fn () => 'early'),
]); // 'early'

$one = Await::any([
    Promise::from(fn () => throw new \RuntimeException('x')),
    Promise::from(fn () => 'ok'),
]); // 'ok'

$settled = Await::allSettled([
    Promise::from(fn () => 7),
    Promise::from(fn () => throw new \RuntimeException('bad')),
]);

$value = Await::until(function () {
    static $i = 0; $i++;
    return $i >= 3 ? 'ready' : null;
}, 200, 10);
```

---

AsyncProcess (Background Processes)
-----------------------------------

[](#asyncprocess-background-processes)

Run a serialized `Closure` in a separate PHP process. Payloads are `HMAC`-signed with `APP_KEY` (and can be encrypted). A PID file is written so you can list/clean/kill processes.

```
use JobMetric\Flyron\Facades\AsyncProcess;

$pid = AsyncProcess::run(function () {
    file_put_contents(storage_path('app/report.txt'), 'done');
}, [], [
    'label' => 'make-report',
    'cwd' => base_path(),
    'env' => ['MY_FLAG' => '1'],
    'timeout' => 30,         // seconds (Symfony Process)
    'idle_timeout' => null,  // optional
    'disable_output' => true,
]);
```

Options:

- `cwd`, `env`, `timeout`, `idle_timeout`, `disable_output`, `label`

Security and stability:

- Payloads are signed with `APP_KEY` (`HMAC-SHA256`). If tampered, execution fails.
- Optional encryption (`aes-256-gcm`) is supported.
- Payload path is restricted to `storage/flyron/payloads`.

Concurrency throttle:

- `flyron.process.max_concurrency` — limit concurrent background processes (`0` means unlimited)
- `flyron.process.throttle_mode` — `reject` or `wait`
- `flyron.process.throttle_wait_max_seconds`, `flyron.process.throttle_wait_interval_ms`

---

Helpers and Facades
-------------------

[](#helpers-and-facades)

- `async(callable $callback, array $args = [], ?int $timeout = null, ?CancellationToken $token = null): Promise`

    - Same as `Async::run(...)`
- `async_process(callable $callback, array $args = [], array $options = []): ?int`

    - Same as `AsyncProcess::run(...)`

Facades:

- `Async` → Fiber/Promise runtime
- `AsyncProcess` → background process launcher

---

Helper Functions (Deep Dive)
----------------------------

[](#helper-functions-deep-dive)

The package ships two global helpers (autoloaded via Composer `files`), designed for the most common use-cases with minimal ceremony.

### `async()`

[](#async)

Signature:

```
async(callable $callback, array $args = [], ?int $timeout = null, ?\JobMetric\Flyron\Concurrency\CancellationToken $token = null): \JobMetric\Flyron\Concurrency\Promise
```

Parameters:

- `callable $callback` — Your function/closure to run inside a Fiber.
- `array $args` — Positional arguments passed to the callback.
- `?int $timeout` — Optional timeout in milliseconds; best-effort cancellation.
- `?CancellationToken $token` — Optional cooperative cancellation token.

Returns:

- `Promise` — A promise you can `run()`, chain (`then`, `map`, `tap`, `recover`, `finally`), `cancel()`, or wrap with `withTimeout`.

Examples:

```
// 1) Quick compute
$p = async(fn (int $x) => $x + 1, [41]);
$result = $p->run(); // 42

// 2) With timeout + cooperative cancellation
use JobMetric\Flyron\Concurrency\CancellationToken;
$token = new CancellationToken();

$p = async(function () use ($token) {
    for ($i = 0; $i < 10_000; $i++) {
        \JobMetric\Flyron\Async::checkpoint($token);
    }
    return 'ok';
}, [], 200, $token);

$token->cancel();
try { $p->run(); } catch (\RuntimeException $e) { /* cancelled or timed out */ }

// 3) Chaining
$p = async(fn () => 10)
    ->map(fn ($v) => $v + 5)
    ->then(fn ($v) => \JobMetric\Flyron\Concurrency\Promise::from(fn () => $v * 2));
$value = $p->run(); // 30
```

Notes and pitfalls:

- `timeout` is best-effort; long CPU-bound work cannot be preempted. Use `CancellationToken` + `Async::checkpoint` in loops.
- You can compose transformations before calling `run()`. The Fiber actually starts when `run()` (or `eagerStart()`) is invoked.

### `async_process()`

[](#async_process)

Signature:

```
async_process(
    callable $callback,
    array $args = [],
    array $options = [] // ['cwd'?, 'env'?, 'timeout'?, 'idle_timeout'?, 'disable_output'?, 'label'?]
): ?int
```

Parameters:

- `callable $callback` — A closure to be serialized and executed in a separate PHP process.
- `array $args` — Arguments passed to the closure.
- `array $options` — Process options:
    - `cwd: ?string` — Working directory.
    - `env: ?array` — Extra environment variables.
    - `timeout: ?float` — Seconds (Symfony Process timeout).
    - `idle_timeout: ?float` — Seconds of inactivity before kill (optional).
    - `disable_output: ?bool` — Defaults to `true`.
    - `label: ?string` — A human-readable label stored in the PID metadata.

Returns:

- `?int` — The spawned process PID or `null` if not available on the platform.

Examples:

```
// 1) Fire-and-forget background task
$pid = async_process(function () {
    file_put_contents(storage_path('app/report.txt'), 'done');
}, [], ['label' => 'make-report', 'timeout' => 30]);

// 2) Pass args and environment
$pid = async_process(function (string $path) {
    file_put_contents($path, getenv('FLAG') ?: 'no-flag');
}, [storage_path('app/out.txt')], ['env' => ['FLAG' => 'yes']]);
```

Important:

- Payloads are signed with `APP_KEY` (`HMAC-SHA256`). If the payload gets tampered, execution is rejected.
- You can enable encryption (e.g., `aes-256-gcm`) via `config('flyron.process.encryption_enabled')`.
- Payload files live under `storage/flyron/payloads` and are cleaned by `flyron:process-clean --payloads` per TTL.
- Concurrency throttle is controlled via `config('flyron.process.max_concurrency')` and related settings.

Output handling:

- Any `echo`/buffered output produced by your closure is captured by `flyron:exec` and appended to a log file next to the payload (e.g., `.json.log`). For structured results, prefer writing to your own files or storage.

---

Console Commands
----------------

[](#console-commands)

- `php artisan flyron:process-list` — list tracked processes with status.
- `php artisan flyron:process-clean {--payloads}` — remove dead PID files; with `--payloads`, remove old payloads by TTL.
- `php artisan flyron:process-kill {pid}` — kill a Flyron-managed process (PID file must exist).
- `php artisan flyron:optimize` — clean stale PID files (maintenance).
- `php artisan flyron:exec {payload_path}` — internal; used by AsyncProcess.

---

Configuration (Highlights)
--------------------------

[](#configuration-highlights)

```
return [
  'php_path' => env('FLYRON_PHP_PATH', PHP_BINARY),
  'artisan_path' => env('FLYRON_ARTISAN_PATH', base_path('artisan')),

  'schedule' => [
    'enabled' => env('FLYRON_SCHEDULE_ENABLED', true),
    'environments' => env('FLYRON_SCHEDULE_ENVIRONMENTS') ? explode(',', env('FLYRON_SCHEDULE_ENVIRONMENTS')) : [],
    'process_clean' => [
      'enabled' => env('FLYRON_SCHEDULE_PROCESS_CLEAN', true),
      'frequency' => env('FLYRON_SCHEDULE_PROCESS_CLEAN_FREQUENCY', 'hourly'),
      'payloads' => env('FLYRON_SCHEDULE_PROCESS_CLEAN_PAYLOADS', true),
    ],
    'process_optimize' => [
      'enabled' => env('FLYRON_SCHEDULE_PROCESS_OPTIMIZE', false),
      'frequency' => env('FLYRON_SCHEDULE_PROCESS_OPTIMIZE_FREQUENCY', 'weekly'),
    ],
  ],

  'process' => [
    'encryption_enabled' => env('FLYRON_PROCESS_ENCRYPTION', false),
    'encryption_cipher' => env('FLYRON_PROCESS_CIPHER', 'aes-256-gcm'),
    'payload_ttl_seconds' => env('FLYRON_PROCESS_PAYLOAD_TTL', 86400),
    'max_concurrency' => env('FLYRON_PROCESS_MAX_CONCURRENCY', 0),
    'throttle_mode' => env('FLYRON_PROCESS_THROTTLE_MODE', 'reject'),
    'throttle_wait_max_seconds' => env('FLYRON_PROCESS_THROTTLE_WAIT_MAX', 30),
    'throttle_wait_interval_ms' => env('FLYRON_PROCESS_THROTTLE_WAIT_INTERVAL', 200),
  ],
];
```

Scheduling:

- You can enable periodic `process-clean` and `optimize` with flexible frequencies (method strings like `daily`, `hourlyAt:15`, or a raw cron expression).

---

Best Practices
--------------

[](#best-practices)

- Offload CPU-heavy work to `AsyncProcess` or queues. Use `Promise/Fiber` for I/O-bound or step-wise operations.
- Use `Async::checkpoint($token)` inside long loops to make cancellation responsive.
- Ensure a valid `APP_KEY`; in production, consider enabling payload encryption.
- Schedule `flyron:process-clean` to keep PID/payload folders tidy.

---

Testing
-------

[](#testing)

This package includes unit and feature tests covering: `Promise/Await/Async`, Traits, Facades, Helpers, ServiceProvider (bindings and scheduling), and Console Commands.

Run tests:

```
php vendor/bin/phpunit
```

---

Contributing
------------

[](#contributing)

Thank you for considering contributing to Flyron! See the [CONTRIBUTING.md](https://github.com/jobmetric/flyron/blob/master/CONTRIBUTING.md) for details.

License
-------

[](#license)

The MIT License (MIT). Please see [License File](https://github.com/jobmetric/flyron/blob/master/LICENCE.md) for more information.

###  Health Score

31

—

LowBetter than 68% of packages

Maintenance61

Regular maintenance activity

Popularity3

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 88.6% 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 ~0 days

Total

2

Last Release

210d ago

### Community

Maintainers

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

---

Top Contributors

[![MajidMohammadian](https://avatars.githubusercontent.com/u/2099965?v=4)](https://github.com/MajidMohammadian "MajidMohammadian (39 commits)")[![Bagheri-Matin](https://avatars.githubusercontent.com/u/239607447?v=4)](https://github.com/Bagheri-Matin "Bagheri-Matin (5 commits)")

---

Tags

asynchronousconcurrencylaravelpackageprocessjobmetricfiberflyron

### Embed Badge

![Health badge](/badges/jobmetric-flyron/health.svg)

```
[![Health](https://phpackages.com/badges/jobmetric-flyron/health.svg)](https://phpackages.com/packages/jobmetric-flyron)
```

PHPackages © 2026

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