PHPackages                             jtmcc/atomic-deployments - 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. jtmcc/atomic-deployments

ActiveLibrary

jtmcc/atomic-deployments
========================

Local zero downtime deployments for Laravel applications

v1.0.0(1y ago)615.7k↓27.8%2MITPHPPHP ^8.3CI passing

Since Jan 20Pushed 1y ago2 watchersCompare

[ Source](https://github.com/J-T-McC/laravel-atomic-deployments)[ Packagist](https://packagist.org/packages/jtmcc/atomic-deployments)[ RSS](/packages/jtmcc-atomic-deployments/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (8)Dependencies (6)Versions (15)Used By (0)

Atomic Deployment Package for Laravel Framework
===============================================

[](#atomic-deployment-package-for-laravel-framework)

[![run-tests](https://github.com/J-T-McC/laravel-atomic-deployments/workflows/run-tests/badge.svg)](https://github.com/J-T-McC/laravel-atomic-deployments/workflows/run-tests/badge.svg)[![StyleCI](https://camo.githubusercontent.com/f7340ff04bc2b3b43ae4682c6c0faab27e69c8c2fbfb163e6aaf7881609d8e0a/68747470733a2f2f6769746875622e7374796c6563692e696f2f7265706f732f3333303331303937392f736869656c643f6272616e63683d6d61696e)](https://github.styleci.io/repos/330310979?branch=main)[![License: MIT](https://camo.githubusercontent.com/1a2e0606685ce00663bf829868f794fd3fc9c86f8d80cae324734129e0723a58/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d627269676874677265656e2e737667)](https://opensource.org/licenses/MIT)

The purpose of this package is to introduce local zero-downtime deployments into a laravel application.

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

[](#requirements)

- Laravel >= 11.x+
- PHP >= 8.3

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

[](#installation)

```
composer require jtmcc/atomic-deployments

php artisan migrate

php artisan vendor:publish --tag=atm-config
```

Configuration
-------------

[](#configuration)

#### .env

[](#env)

There are three required environment variables:

1. **ATM\_DEPLOYMENT\_LINK**: The symbolic link you will use with your web server, artisan schedules, ...etc
2. **ATM\_BUILD**: The project build folder where you will run composer, any build related logic, update your env
3. **ATM\_DEPLOYMENTS**: The root folder that builds will be deployed to and linked

```
ATM_DEPLOYMENT_LINK="/var/www/production-site"
ATM_BUILD="/var/www/build-project"
ATM_DEPLOYMENTS="/var/www/deployments"
```

#### config( ...)

[](#config-)

```
return [

    /**
     * Symbolic link to the current deployed build
     * This path will be used for schedules and setting your web root.
     */
    'deployment-link' => env('ATM_DEPLOYMENT_LINK'),

    /**
     * The primary build folder
     * This folder is where all deployments ran and ultimately copied to a deployment directory.
     */
    'build-path' => env('ATM_BUILD'),

    /**
     * Production build directory
     * Builds are copied here and linked for deployment
     * Ensure this directory has the required permissions to allow php and your webserver to run your application here.
     */
    'deployments-path' => env('ATM_DEPLOYMENTS'),

    /**
     * Max number of build directories allowed
     * Once limit is hit, old deployments will be removed automatically after a successful build.
     */
    'build-limit' => 10,

    /**
     * Logic used when creating a deployment directory.
     *
     * Default => git - uses hash for current HEAD
     * Options: [ git, datetime, rand ]
     *
     * If your build does not use git, use rand.
     */
    'directory-naming' => 'git',

    /**
     * Deployment class used.
     *
     * Add custom deployments by implementing @see \JTMcC\AtomicDeployments\Interfaces\DeploymentInterface
     * and adding your class to this config property
     */
    'deployment-class' => \JTMcC\AtomicDeployments\Services\Deployment::class,

    /**
     * Migrate files|folders from the outgoing production build to your new release using a relative path and pattern.
     *
     * @see https://www.php.net/manual/en/function.glob.php
     */
    'migrate' => [
        //        'storage/framework/sessions/*',
    ],

];
```

By default, this package will restrict your project to 10 deployment builds. Once you hit the limit defined in the config, older deployments will be automatically deleted. Be aware of the size of your project and adjust to meet your needs.

You might find yourself in a situation where you need to migrate files that don't exist in your build project from your current deployment folder to your new deployment folder. These files/folders can be specified in the migrate config array, and they will be copied from the outgoing deployment into the new deployment when you run the deploy command.

Once you have configured your env and have deployed a build, you can update your webserver to start routing traffic to your 'deployment-link' location.

```
# nginx example
root /var/www/production-site/public;

#crontab logic example
php /var/www/production-site/artisan schedule:run
```

Commands
--------

[](#commands)

### atomic-deployments:deploy

[](#atomic-deploymentsdeploy)

#### *options*

[](#options)

- --hash= : Specify a previous deployments commit hash/deploy-dir to deploy
- --directory= : Define your deploy folder name. Defaults to current HEAD hash
- --dry-run : Test and log deployment steps

#### *examples*

[](#examples)

Do a dry run to get some feedback on the steps that will be taken

```
php artisan atomic-deployments:deploy --dry-run
```

Deploy current build using the current branch git hash for deployment folder

```
php artisan atomic-deployments:deploy
```

Deploy current build using a custom directory name

```
php artisan atomic-deployments:deploy --directory=deployment_folder
```

Revert linked project back to a previous build

```
php artisan atomic-deployments:deploy ---hash=abc1234
```

### atomic-deployments:list

[](#atomic-deploymentslist)

Prints a table to the console of the currently available builds

#### *examples*

[](#examples-1)

```
php artisan atomic-deployments:list
```

Events
------

[](#events)

- DeploymentSuccessful
- DeploymentFailed

Laravel Forge Example
---------------------

[](#laravel-forge-example)

Here is a basic configuration for use with Forge

#### *Deploy Script*

[](#deploy-script)

```
cd /home/forge/your-application.com
git pull origin main
$FORGE_COMPOSER install --no-interaction --prefer-dist --optimize-autoloader --no-dev --no-progress

( flock -w 10 9 || exit 1
    echo 'Restarting FPM...'; sudo -S service $FORGE_PHP_FPM reload ) 9>/tmp/fpmlock

if [ -f artisan ]; then
    $FORGE_PHP artisan migrate --force
    $FORGE_PHP artisan optimize:clear
    $FORGE_PHP artisan atomic-deployments:deploy
fi
```

#### *.env*

[](#env-1)

Build project .env

```
ATM_DEPLOYMENT_LINK="/home/forge/your-application.com-link"
ATM_BUILD="/home/forge/your-application.com"
ATM_DEPLOYMENTS="/home/forge/deployments/your-application.com"
```

#### *nginx config*

[](#nginx-config)

```
root /home/forge/your-application.com-link/public;
```

#### *schedule command*

[](#schedule-command)

```
php8.0 /home/forge/your-application.com-link/artisan schedule:run
```

If your application is isolated, you must ensure that your deployments folder has the appropriate permissions to serve your application for that user.

License
-------

[](#license)

MIT

###  Health Score

44

—

FairBetter than 92% of packages

Maintenance42

Moderate activity, may be stable

Popularity31

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity76

Established project with proven stability

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

Recently: every ~369 days

Total

8

Last Release

466d ago

Major Versions

v0.4.1 → v1.0.02025-02-06

PHP version history (2 changes)v0.0.1PHP ^7.4|^8.0

v1.0.0PHP ^8.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/73d0ea4ea29db1a282a4c71e5d5af7aedd30b9261bc9862043dc25d41af9d5ea?d=identicon)[J-T-McC](/maintainers/J-T-McC)

---

Top Contributors

[![J-T-McC](https://avatars.githubusercontent.com/u/48730964?v=4)](https://github.com/J-T-McC "J-T-McC (44 commits)")

---

Tags

atomic-deploymentslaravellaravel-applicationslaravel-frameworklaravel-packagezero-downtime

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/jtmcc-atomic-deployments/health.svg)

```
[![Health](https://phpackages.com/badges/jtmcc-atomic-deployments/health.svg)](https://phpackages.com/packages/jtmcc-atomic-deployments)
```

PHPackages © 2026

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