PHPackages                             wizory/llock - 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. wizory/llock

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

wizory/llock
============

Laravel Shared Locking Plugin

1.0.8(6y ago)11.4k1[2 issues](https://github.com/wizory/llock/issues)PHPPHP >= 7.2CI failing

Since May 29Pushed 3y ago1 watchersCompare

[ Source](https://github.com/wizory/llock)[ Packagist](https://packagist.org/packages/wizory/llock)[ RSS](/packages/wizory-llock/feed)WikiDiscussions master Synced yesterday

READMEChangelogDependencies (9)Versions (12)Used By (0)

Laravel Lock Plugin (llock)
===========================

[](#laravel-lock-plugin-llock)

*\[insert Llama picture here\]*

This plugin adds a set of artisan commands to set and free shared named locks. The current primary use-case is with [Laravel forge](http://forge.laravel.com) when using multiple load-balanced servers.

The locking provided via this plugin enables the following:

#### Serial web instance deployment

[](#serial-web-instance-deployment)

Using the `--wait` mode allows each web instance to deploy sequentially based on who has the lock. The lock is freed as each deploy completes so the next can obtain it. This keeps at least one instance up and serving traffic at all times.

#### Same scheduled task on all instances (without redundant runs)

[](#same-scheduled-task-on-all-instances-without-redundant-runs)

The scheduled task run can be configured on all web instances, but only the one who obtains the lock will execute the task. This allows a more fault-tolerant setup since any web instance(s) can be lost and the scheduled task(s) will continue to run (but it won't run multiple times when more than one instance is "up").

Setup / Installation
--------------------

[](#setup--installation)

This plugin is intended to work with an existing Laravel 5.1 LTS (Long-term Support) site/app. Steps to add the plugin follow.

### add github repository to `composer.json`

[](#add-github-repository-to-composerjson)

This allows composer to retrieve the package dependencies directly from github. This step will become unnecessary once the plugin is officially "released".

Update your `composer.json` file with a new `repositories` element (typically placed just before the `require` block):

```
"repositories": [
  {
    "type": "vcs",
    "url": "git@github.com:wizory/llock.git"
  }
],
```

### add plugin dependency to `composer.json`

[](#add-plugin-dependency-to-composerjson)

Now add the plugin dependency to the existing `require` block:

```
"require": {
  ...,
  "wizory/llock": "dev-master"
},
```

The version specified for `wizory/llock` in the `require` section references the `master` branch of the repository.

Upon release, the example will be updated to point to a release version.

### update composer

[](#update-composer)

Now run `composer update` to fetch llock and its dependencies.

### register llock service provider

[](#register-llock-service-provider)

Add the following line to `config/app.php` in the providers array:

```
Wizory\Llock\LlockServiceProvider::class,

```

### run installer

[](#run-installer)

This command will install an example config and migration(s) necessary for the plugin to function:

```
php artisan llock:install

```

The newly added files should be committed to your project.

**NOTE:** This command will run migrations. If you have any outstanding migrations pending they should be resolved prior to running install.

Usage
-----

[](#usage)

At this point you should be able to run `php artisan llock:status` and get some output. You can pass `-h` to any command to get usage details also.

### `php artisan llock:status`

[](#php-artisan-llockstatus)

Shows the status of any current locks.

### `php artisan llock:set `

[](#php-artisan-llockset-name)

Sets a lock named ``. Passing `--wait` will wait a configurable amount of time to obtain the named lock if it already exists with the same name. The plugin will retry periodically to obtain the lock (also configurable).

The return code of this command is 0 (true) if a lock was obtained and 1 (false) otherwise. A return code of 2 (also false) indicates an error (e.g. database connection).

### `php artisan llock:free `

[](#php-artisan-llockfree-name)

Frees the lock named ``.

The return code of this command is 0 whether the lock was freed or not, and 2 in case of error.

Examples
--------

[](#examples)

### Ensuring sequential deployment across multiple site instances

[](#ensuring-sequential-deployment-across-multiple-site-instances)

Add something like this to your deployment script/code:

```
LOCKNAME=mysite

php artisan llock:set --wait ${LOCKNAME}  # command will not return until a lock is obtained or the timeout is reached

# deploy steps here....

php artisan llock:free ${LOCKNAME}
```

This example mostly assumes a "happy path". You may want to detect the return code and fail (before deploy) on timeout or other error.

### Ensuring scheduled tasks only run once across a set of multiple site instances

[](#ensuring-scheduled-tasks-only-run-once-across-a-set-of-multiple-site-instances)

Use something like this for your CRON/scheduler entry:

```
php artisan llock:set mysite && php artisan schedule:run; php artisan llock:free mysite

# or the mostly equivalent

if php artisan llock:set mysite; then php artisan run; fi; php artisan llock:free mysite
```

Again, this example doesn't explicitly handle the variety of error cases that can arise. The (handy) one-liner can get messy so you might want to call an intermediate script from your scheduler.

Updating
--------

[](#updating)

To update to new versions of llock, use the following steps:

```
composer update wizory/llock
php artisan llock:install

```

Commit any new/changed files afterwards.

Security
--------

[](#security)

There is an assumption of trust here as any "client" could free a lock created by any other. This is not a useful implementation for locking in an untrusted environment.

DRAFT CONTENT BELOW
===================

[](#draft-content-below)

The documentation, etc. below is all Work In Progress (WIP) and will be revised, organized, and moved to the above section as it takes shape.

---

### Running Tests

[](#running-tests)

1. once you've setup the above, login to your vagrant machine, cd to the site directory and run:

```
vendor/bin/phpunit

```

Use the `--colors` flag if you want color output.

You should see lots of tests run and pass. :)

### Roadmap

[](#roadmap)

As Laravel udates the LTS designation to newer versions, this plugin will be updated to work with them if any breaking changes are introduced.

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

[](#contributing)

**`TODO:`** Provide further instructions for dev setup and contributing.

**NOTE:** For local development on the llock package itself, use the following (changing the relative path to the llock package as-needed):

```
"repositories": [
    {
        "type": "path",
        "url": "../llock"
    }
],
"require": {
  ...,
  "wizory/llock": "*@dev"
},
```

###  Health Score

26

—

LowBetter than 41% of packages

Maintenance0

Infrequent updates — may be unmaintained

Popularity17

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity65

Established project with proven stability

 Bus Factor1

Top contributor holds 93.1% 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 ~220 days

Recently: every ~395 days

Total

10

Last Release

1336d ago

Major Versions

1.0.8 → 2.0.0-rc.12022-11-01

PHP version history (4 changes)1.0.0PHP >=5.5.9

1.0.6PHP 7.1.\*

1.0.7PHP 7.2.\*

1.0.8PHP >= 7.2

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/587350?v=4)[Josh Guice](/maintainers/jguice)[@jguice](https://github.com/jguice)

---

Top Contributors

[![jguice](https://avatars.githubusercontent.com/u/587350?v=4)](https://github.com/jguice "jguice (27 commits)")[![stevenquinn](https://avatars.githubusercontent.com/u/5179321?v=4)](https://github.com/stevenquinn "stevenquinn (2 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/wizory-llock/health.svg)

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

###  Alternatives

[markwalet/nova-modal-response

A Laravel Nova asset for Modal responses on an action.

17818.7k](/packages/markwalet-nova-modal-response)[crumbls/layup

A visual page builder plugin for Filament 5 — Divi-style grid layouts with extensible widgets.

591.7k1](/packages/crumbls-layup)[tomshaw/electricgrid

A feature-rich Livewire package designed for projects that require dynamic, interactive data tables.

119.2k](/packages/tomshaw-electricgrid)

PHPackages © 2026

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