PHPackages                             procentr/file-lock-manager - 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. procentr/file-lock-manager

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

procentr/file-lock-manager
==========================

A lightweight PHP library for managing file locks. No, seriously, it works. I mean... does anyone actually use this? ;-)

v1.0(1y ago)11MITPHPPHP >=8.0

Since Apr 14Pushed 1y ago2 watchersCompare

[ Source](https://github.com/procentr/FileLockManager)[ Packagist](https://packagist.org/packages/procentr/file-lock-manager)[ RSS](/packages/procentr-file-lock-manager/feed)WikiDiscussions master Synced 1mo ago

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

FileLockManager 🚀
=================

[](#filelockmanager-)

Hey there 👋! If you've ever struggled with managing file locks in a multi-process environment, this is the library for you! **FileLockManager** lets you handle file locks in PHP with ease. It's here to make sure your files are accessed safely and without chaos happening.

What Can It Do?
---------------

[](#what-can-it-do)

Here’s why FileLockManager is pretty awesome:

- Super simple interface for file locking 🛠️
- Supports **exclusive** and **shared** locks
- Lets you try non-blocking lock attempts using `tryLock()` (quick and easy tests!)
- Provides lock timeouts via `lockWithTimeout()`
- Automatically creates the file if it doesn’t exist yet 🗂️
- Throws meaningful, human-readable exceptions (no cryptic errors!)
- Safe for both **threads** and **processes**
- Fully compatible with PHP 8.0+ ✅

Installation 🔧
--------------

[](#installation-)

Getting started is as easy as running one command. Install it with Composer:

```
composer require procentr/file-lock-manager
```

---

How to Use It
-------------

[](#how-to-use-it)

Below are some examples to help you get started. You'll see just how simple it is!

### Basic Example

[](#basic-example)

Want to lock a file so no one else can mess with it while you’re working? Use this:

```
use Procentr\FileLockManager\FileLockManager;

$lockManager = new FileLockManager('/path/to/file.txt');

// Lock the file for exclusive access 🚪🔐
$lockManager->lock();

try {
    // Do your stuff safely here
    file_put_contents('/path/to/file.txt', 'Important content!');

} finally {
    // Always unlock it, because sharing is caring ❤️
    $lockManager->unlock();
}
```

### Non-Blocking Lock

[](#non-blocking-lock)

Need to know if you can lock a file without waiting around? Use `tryLock()`:

```
use Procentr\FileLockManager\FileLockManager;

$lockManager = new FileLockManager('/path/to/file.txt');

if ($lockManager->tryLock()) {
    try {
        echo "Yay! The lock succeeded! 🎉";

    } finally {
        $lockManager->unlock();
    }
} else {
    echo "Oops... File is being used by someone else right now. 😕";
}
```

### Lock with Timeout

[](#lock-with-timeout)

Don’t wanna wait forever? Use `lockWithTimeout()` and specify how long you’re willing to wait:

```
use Procentr\FileLockManager\FileLockManager;
use Procentr\FileLockManager\Exceptions\LockException;

$lockManager = new FileLockManager('/path/to/file.txt');

try {
    // Wait for up to 5 seconds to get the lock ⏱️
    $lockManager->lockWithTimeout(LOCK_EX, 5);

    // Do whatever you need here! ✨

    $lockManager->unlock();
} catch (LockException $e) {
    echo "No luck getting the lock within the timeout! 😓: " . $e->getMessage();
}
```

### Shared Locks

[](#shared-locks)

If you just need to read a file and don’t care if others are reading too, use a **shared lock**:

```
use Procentr\FileLockManager\FileLockManager;

$lockManager = new FileLockManager('/path/to/file.txt');

// Shared lock: Everyone’s invited to read! 📖
$lockManager->lock(LOCK_SH);

try {
    $content = file_get_contents('/path/to/file.txt');
    echo "Reading content safely: $content";

} finally {
    $lockManager->unlock();
}
```

### Check If Locked

[](#check-if-locked)

Sometimes, you might just want to check if your current instance has the file locked already. Here’s how:

```
$lockManager = new FileLockManager('/path/to/file.txt');

if (!$lockManager->isLocked()) {
    echo "The file is free! Go ahead and lock it. 🟢";
}

$lockManager->lock();
if ($lockManager->isLocked()) {
    echo "File is now locked. Mission accomplished! 🔒";
}

$lockManager->unlock();
```

---

Error Handling 💡
----------------

[](#error-handling-)

What happens if something goes wrong? Don’t worry, **FileLockManager** throws clear, easy-to-understand exceptions:

### Example 1: File Not Found

[](#example-1-file-not-found)

```
try {
    $lockManager = new FileLockManager('/invalid/path/file.txt');
} catch (FileNotFoundException $e) {
    echo "Could not find or create the file: " . $e->getMessage();
}
```

### Example 2: Unlock Without Locking

[](#example-2-unlock-without-locking)

```
try {
    $lockManager = new FileLockManager('/path/to/file.txt');
    $lockManager->unlock(); // Did you forget to lock first? 🤔
} catch (UnlockException $e) {
    echo "Unlock error: " . $e->getMessage();
}
```

### Example 3: Failing to Lock

[](#example-3-failing-to-lock)

```
try {
    $lockManager->lockWithTimeout(LOCK_EX, 2);
} catch (LockException $e) {
    echo "Failed to lock the file: " . $e->getMessage();
}
```

---

### Summary ✨

[](#summary-)

FileLockManager gives you the tools to manage file locking with confidence, clarity, and ease. Stop worrying about race conditions and let this library help you focus on more exciting things in your code. Give it a try and see how simple it can be to tame file locks! 🦾

###  Health Score

27

—

LowBetter than 49% of packages

Maintenance49

Moderate activity, may be stable

Popularity3

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity42

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

Unknown

Total

1

Last Release

399d ago

### Community

Maintainers

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

---

Top Contributors

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

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/procentr-file-lock-manager/health.svg)

```
[![Health](https://phpackages.com/badges/procentr-file-lock-manager/health.svg)](https://phpackages.com/packages/procentr-file-lock-manager)
```

###  Alternatives

[knplabs/gaufrette

PHP library that provides a filesystem abstraction layer

2.5k39.8M123](/packages/knplabs-gaufrette)[superbalist/flysystem-google-storage

Flysystem adapter for Google Cloud Storage

26320.6M30](/packages/superbalist-flysystem-google-storage)[illuminate/filesystem

The Illuminate Filesystem package.

15161.6M2.6k](/packages/illuminate-filesystem)[creocoder/yii2-flysystem

The flysystem extension for the Yii framework

2931.7M62](/packages/creocoder-yii2-flysystem)[flowjs/flow-php-server

PHP library for handling chunk uploads. Works with flow.js html5 file uploads.

2451.6M15](/packages/flowjs-flow-php-server)[madnest/madzipper

Easier zip file handling for Laravel applications.

1382.3M6](/packages/madnest-madzipper)

PHPackages © 2026

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