PHPackages                             flytachi/file-store - 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. [File & Storage](/categories/file-storage)
4. /
5. flytachi/file-store

ActiveLibrary[File & Storage](/categories/file-storage)

flytachi/file-store
===================

File Store library

v2.0.0(1mo ago)11.0k↓65%2MITPHPPHP >=8.3

Since Jul 1Pushed 1mo agoCompare

[ Source](https://github.com/Flytachi/file-store)[ Packagist](https://packagist.org/packages/flytachi/file-store)[ RSS](/packages/flytachi-file-store/feed)WikiDiscussions master Synced 2d ago

READMEChangelogDependencies (3)Versions (8)Used By (2)

File Store
==========

[](#file-store)

[![Latest Version on Packagist](https://camo.githubusercontent.com/ce1713ffbc133df121a2517666d8e96e626d1aa410493e3d059863a6b75cc8b8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f666c7974616368692f66696c652d73746f72652e737667)](https://packagist.org/packages/flytachi/file-store)[![Software License](https://camo.githubusercontent.com/074b89bca64d3edc93a1db6c7e3b1636b874540ba91d66367c0e5e354c56d0ea/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e737667)](LICENSE)

A small, dependency-free key/value file store for PHP — atomic writes, optional TTL, optional HMAC-hashed filenames, and group-shared file permissions for multi-process setups (PHP-FPM + Nginx, queue workers, cron).

---

Requirements
------------

[](#requirements)

- PHP >= 8.3
- ext-mbstring

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

[](#installation)

```
composer require flytachi/file-store
```

---

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

[](#quick-start)

```
use Flytachi\FileStore\FileStorage;

$store = new FileStorage(
    rootPath:   '/var/app',
    folderName: 'cache/jobs',
);

// Write a value
$store->write('job:42', ['status' => 'queued', 'attempts' => 0]);

// Write with TTL — expires after 1 hour
$store->write('session:abc', $payload, expireAtTimestamp: time() + 3600);

// Read
$job = $store->read('job:42');         // mixed|null

// Check presence (also checks TTL)
if ($store->has('session:abc')) { /* ... */ }

// Delete
$store->del('job:42');

// Enumerate / wipe
$store->keys();     // array of filenames in the store
$store->clear();    // unlink all entries

// Bulk-evict expired entries + crashed-writer tmp files (run from cron)
$store->gc();       // returns count of deleted files
```

---

Constructor
-----------

[](#constructor)

```
new FileStorage(
    string $rootPath,                  // existing, writable directory
    string $folderName,                // subdirectory inside rootPath (created if missing)
    bool   $isHash    = true,          // hash keys → HMAC filenames; off = raw key as filename
    string $hmacType  = 'sha256',      // any hash_hmac() algo
    int    $dirMode   = 0770,          // permissions for the storage directory
    int    $fileMode  = 0660,          // permissions for written files
);
```

`$dirMode` / `$fileMode` are applied **after** `mkdir` / `file_put_contents` via explicit `chmod()` calls — so the resulting permissions are exactly what you asked for, regardless of the process umask. See [docs/03-permissions.md](docs/03-permissions.md) for the full story.

---

Features at a Glance
--------------------

[](#features-at-a-glance)

FeatureHow it works**Atomic write**Writes go to `*.tmp.`, then `rename()` into place. Readers never see a half-written file.**TTL**A `#^e:\n` prefix line; expired entries are unlinked on first access.**HMAC filenames**When `isHash=true`, the key is run through `hash_hmac($hmacType, $key, dirKey)` — directory listings reveal no key contents.**Path-traversal guard**When `isHash=false`, raw keys are validated — `/`, `\`, `\0`, `.`, `..`, and empty strings are rejected.**Group-writable mode**Default `0770/0660` lets PHP-FPM and Nginx (or any two processes in the same group) share the store.**Single dependency**Only `ext-mbstring` for `mb_check_encoding` / `mb_convert_encoding` in directory-key normalisation.---

When to Use This
----------------

[](#when-to-use-this)

- **Job payloads** shared between a web process and a worker
- **Per-key caches** that need TTL and group-shared writability
- **Lightweight session/blob storage** without pulling in Redis/Memcached
- Any case where SQLite is too heavy and APCu is too local

For high-throughput hot caches or multi-host deployments, reach for something network-aware (Redis, Memcached) — this is a single-host, filesystem-backed store.

---

Documentation
-------------

[](#documentation)

FileTopic[00-overview.md](docs/00-overview.md)Architecture, file layout, lifecycle of an entry[01-quick-start.md](docs/01-quick-start.md)Minimal setup, common patterns[02-api-reference.md](docs/02-api-reference.md)Every public method, every parameter[03-permissions.md](docs/03-permissions.md)`dirMode` / `fileMode`, umask, multi-user setups[04-concurrency.md](docs/04-concurrency.md)Atomic write, locking, race-conditions[05-security.md](docs/05-security.md)HMAC hashing, path traversal, `unserialize` notes[06-exceptions.md](docs/06-exceptions.md)`FileStorageException` — when it's thrown---

License
-------

[](#license)

MIT License. See [LICENSE](LICENSE).

###  Health Score

48

—

FairBetter than 93% of packages

Maintenance90

Actively maintained with recent releases

Popularity20

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity57

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 ~52 days

Recently: every ~47 days

Total

7

Last Release

52d ago

Major Versions

1.0.5 → v2.0.02026-05-13

### Community

Maintainers

![](https://www.gravatar.com/avatar/861b81dd97c8ddfa919522d2a4e17626120bd3e3d7464857cc03784676bc74a8?d=identicon)[Flytachi](/maintainers/Flytachi)

---

Top Contributors

[![Flytachi](https://avatars.githubusercontent.com/u/68924300?v=4)](https://github.com/Flytachi "Flytachi (8 commits)")

---

Tags

storefile storeextra store

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/flytachi-file-store/health.svg)

```
[![Health](https://phpackages.com/badges/flytachi-file-store/health.svg)](https://phpackages.com/packages/flytachi-file-store)
```

PHPackages © 2026

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