PHPackages                             flyokai/amp-mate - 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. flyokai/amp-mate

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

flyokai/amp-mate
================

AMPHP helpers

v1.1.7(3w ago)051MITPHP

Since Apr 25Pushed 3w agoCompare

[ Source](https://github.com/flyokai/amp-mate)[ Packagist](https://packagist.org/packages/flyokai/amp-mate)[ RSS](/packages/flyokai-amp-mate/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (6)Versions (15)Used By (1)

flyokai/amp-mate
================

[](#flyokaiamp-mate)

> User docs → [`README.md`](README.md) · Agent quick-ref → [`CLAUDE.md`](CLAUDE.md) · Agent deep dive → [`AGENTS.md`](AGENTS.md)

> AMPHP filesystem helpers — safe wrappers, async file locking, and a bridge between AMPHP `File` objects and PHP resource handles.

Features
--------

[](#features)

- Safe / non-throwing variants of common filesystem operations
- `ampFlock()` with exponential-backoff retry, cancellation-aware
- `findAmpFileHandle()` — extracts the underlying `resource` from any AMPHP `File` driver
- All functions auto-loaded via Composer

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

[](#installation)

```
composer require flyokai/amp-mate
```

Functions
---------

[](#functions)

All live in `src/functions/filesystem.php`:

FunctionReturnsNotes`findAmpFileHandle(File)``resource|false`Works with `StatusCachingFile`, `UvFile`, `EioFile`, `BlockingFile``ampFlock($handle, int $op, ?Cancellation, float $baseLatency = 0.01, int $maxAttempts = 10)``bool` (throws `TimeoutException` on exhaust)Exponential backoff`ampOpenFile(string $path, string $mode)``File|false`Safe open`ampUnlink($file, bool $safe = true)``bool``ampFileExists(string $path)``bool``isFile && exists``ampDirExists(string $path)``bool``isDirectory && exists``ampMkdir(string $path, int $mode = 0755, bool $safe = true)``bool``ampChmod(string $path, int $mode, bool $safe = true)``bool`Quick start
-----------

[](#quick-start)

```
use Amp\File;
use function Flyokai\AmpMate\{ampOpenFile, ampFlock, findAmpFileHandle};

$file = ampOpenFile('/tmp/lock.txt', 'c+');

if ($file === false) {
    throw new RuntimeException('cannot open');
}

$handle = findAmpFileHandle($file);
ampFlock($handle, LOCK_EX);   // suspends with backoff until acquired

$file->write('hello');
flock($handle, LOCK_UN);
$file->close();
```

The `safe` pattern
------------------

[](#the-safe-pattern)

Every operation that can fail accepts a `$safe` boolean:

- `$safe = true` (default) — return `false` / `bool` on failure
- `$safe = false` — throw the underlying exception

```
ampMkdir('/tmp/foo', 0755);          // returns false on collision
ampMkdir('/tmp/foo', 0755, false);   // throws on collision
```

Gotchas
-------

[](#gotchas)

- `ampFlock()` uses `Amp\delay()` between attempts — cooperative, but if `flock` itself blocks the OS it still blocks.
- Default `$maxAttempts = 10` with exponential backoff can take up to ~10 seconds before throwing.
- `findAmpFileHandle()` returns `false` silently for unsupported driver types.

See also
--------

[](#see-also)

- [`flyokai/magento-amp-mate`](../magento-amp-mate/README.md) — async cache backend built on top of these helpers

License
-------

[](#license)

MIT

###  Health Score

34

—

LowBetter than 75% of packages

Maintenance92

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity28

Early-stage or recently created project

 Bus Factor1

Top contributor holds 83.3% 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 ~4 days

Total

11

Last Release

25d ago

Major Versions

0.1.0 → v1.1.22026-05-25

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/247743048?v=4)[flyokai](/maintainers/flyokai)[@flyokai](https://github.com/flyokai)

---

Top Contributors

[![flyokai](https://avatars.githubusercontent.com/u/247743048?v=4)](https://github.com/flyokai "flyokai (5 commits)")[![wtsergo](https://avatars.githubusercontent.com/u/305326?v=4)](https://github.com/wtsergo "wtsergo (1 commits)")

### Embed Badge

![Health badge](/badges/flyokai-amp-mate/health.svg)

```
[![Health](https://phpackages.com/badges/flyokai-amp-mate/health.svg)](https://phpackages.com/packages/flyokai-amp-mate)
```

###  Alternatives

[danog/madelineproto

Async PHP client API for the telegram MTProto protocol.

3.5k902.0k23](/packages/danog-madelineproto)[phpro/grumphp

A composer plugin that enables source code quality checks.

4.3k16.7M1.0k](/packages/phpro-grumphp)[amphp/process

A fiber-aware process manager based on Amp and Revolt.

25760.7M69](/packages/amphp-process)[amphp/parallel-functions

Parallel processing made simple.

28010.6M27](/packages/amphp-parallel-functions)[phel-lang/phel-lang

Phel is a functional programming language that compiles to PHP

5186.0k18](/packages/phel-lang-phel-lang)[chevere/workflow

Declarative workflow engine for PHP with automatic dependency resolution, sync/async job execution, and type-safe response chaining.

1732.1k2](/packages/chevere-workflow)

PHPackages © 2026

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