Documentation

Everything you need to set up zero-knowledge encrypted backups for your PHP application. Install, configure, and start backing up in under a minute.

Overview

Calm Backup provides encrypted, automated backups for PHP applications. Your data is encrypted on your server using a key only you possess, then uploaded to Calm Backup's storage. We never see your unencrypted data.

Works with any PHP application. Laravel gets artisan commands as a bonus.

Requirements

PHP 8.2+
ext-openssl, ext-curl
Composer
Laravel 10–13 (optional)
A Calm Backup account (sign up)

Installation

Install the package via Composer:

composer require calmbackup/backup

Any PHP app

Run the init wizard to generate your encryption key and validate your API key:

vendor/bin/calmbackup init

Laravel

The package uses Laravel's auto-discovery. Run the install command to generate your encryption key and validate your API key:

php artisan backup:install

Configuration

The install/init wizard sets up your .env file automatically. You can also configure these values manually. Both keys are available from your Calm Backup dashboard.

CALMBACKUP_API_KEY=your-api-key
CALMBACKUP_ENCRYPTION_KEY=your-encryption-key

Environment variables

Variable	Required	Description
`CALMBACKUP_API_KEY`	Yes	Your project API key from the Calm Backup dashboard.
`CALMBACKUP_ENCRYPTION_KEY`	Yes	Your encryption key. Generated locally by the install/init wizard. Never sent to our servers.

Laravel: publish the config file

php artisan vendor:publish --tag=calmbackup-config

This publishes config/backup.php where you can configure directories to back up, local retention, and more.

// config/backup.php (Laravel)
return [
    'api_key' => env('CALMBACKUP_API_KEY'),
    'encryption_key' => env('CALMBACKUP_ENCRYPTION_KEY'),
    'database' => null, // Auto-detected from Laravel config
    'directories' => [
        // storage_path('app/public'),
    ],
    'local_path' => storage_path('app/private/backups'),
    'local_retention_days' => 7,
];

Non-Laravel apps

Non-Laravel apps use calmbackup.php in the project root, generated by the init wizard.

Usage

Scheduled backups

Laravel: The package automatically registers a daily scheduled backup. Make sure Laravel's scheduler is running:

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

Non-Laravel: Add a cron entry to run backups directly:

0 2 * * * cd /path-to-your-project && vendor/bin/calmbackup run >> /dev/null 2>&1

On-demand backup

Run a backup manually at any time:

# Laravel
php artisan backup:run

# Any PHP app
vendor/bin/calmbackup run

List backups

# Laravel
php artisan backup:list

# Any PHP app
vendor/bin/calmbackup list-backups

Restore a backup

# Laravel
php artisan backup:restore

# Any PHP app
vendor/bin/calmbackup restore

Check status

# Laravel
php artisan backup:status

# Any PHP app
vendor/bin/calmbackup status

API Reference

Most users never interact with the API directly. The package handles all API communication. All endpoints require a Authorization: Bearer YOUR_API_KEY header.

Get presigned upload URL

POST /api/v1/upload-url

Returns a presigned URL for uploading an encrypted backup file.

Confirm upload completed

POST /api/v1/backups/{id}/confirm

Confirms that the backup file was successfully uploaded.

List backups

GET /api/v1/backups

Returns a list of all backups for the project.

Get backup + download URL

GET /api/v1/backups/{id}

Returns backup details and a presigned download URL.

Delete backup

DELETE /api/v1/backups/{id}

Permanently deletes a backup.

Account info

GET /api/v1/account

Returns account details and usage information.

Quick reference

Package

calmbackup/backup

PHP

8.2+

Artisan commands

backup:run, backup:list, backup:restore, backup:status

CLI commands

vendor/bin/calmbackup run, list-backups, restore, status

Encryption

Client-side, zero-knowledge

Databases

MySQL, PostgreSQL, SQLite