README

A Laravel package for automated, encrypted database and storage backups with secure remote delivery. Supports Artisan commands, HTTP API triggers, queue offloading, and AES-256 ZIP encryption out of the box.

Features

• Database backups — mysqldump with --single-transaction and --quick for consistent, low-memory dumps
• Storage backups — Archives storage/app/public into password-protected ZIP (AES-256)
• Pluggable ZIP strategy — CLI 7z (recommended) with PHP ZipArchive fallback
• Chunked uploads — Large backup files split into configurable chunks (default 20 MB) for reliable transfer
• Token-based authentication — X-Notifier-Token header validated with constant-time comparison
• Queue support — Offload backup jobs to any Laravel queue driver to avoid HTTP timeout limits
• Remote API trigger — Rate-limited REST endpoint to trigger backups from an external scheduler
• Exclusion lists — Ignore specific database tables and storage files/directories
• Configurable routing — Custom route prefix, or disable routes entirely
• Comprehensive logging — Dedicated configurable logging channel with automatic fallback
• Automatic cleanup — Temporary backup files removed after successful upload

Requirements

• PHP ^8.4
• Laravel ^12.2
• mysqldump binary for database backups
• 7z (p7zip-full) recommended for storage backups, or PHP zip extension as fallback

Installation

1. Install via Composer

composer require devuni/notifier-package

2. Publish the configuration

php artisan vendor:publish --tag="notifier-config"

This copies config/notifier.php into your application's config/ directory.

3. Configure environment variables

Run the interactive installer to write the required values to your .env:

php artisan notifier:install

4. Verify your setup

php artisan notifier:check

This command validates your environment variables, database connectivity, storage access, system tools (mysqldump, 7z), logging channel, and backup URL reachability.

Configuration

After publishing, edit config/notifier.php or set values via environment variables.

Environment Variables

# Required
NOTIFIER_BACKUP_CODE=your-secret-token       # Authentication token (must match the central notifier)
NOTIFIER_URL=https://your-backup-server.com  # Endpoint that receives backup uploads
NOTIFIER_BACKUP_PASSWORD=your-zip-password   # AES-256 ZIP encryption password

# Optional
NOTIFIER_LOGGING_CHANNEL=backup              # Laravel logging channel (default: backup)
NOTIFIER_ROUTES_ENABLED=true                 # Enable/disable the API route (default: true)
NOTIFIER_ROUTE_PREFIX=api/notifier           # API route prefix (default: api/notifier)
NOTIFIER_ZIP_STRATEGY=auto                   # ZIP strategy: auto, cli, php (default: auto)
NOTIFIER_CHUNK_SIZE=20971520                 # Upload chunk size in bytes (default: 20 MB)
NOTIFIER_QUEUE_CONNECTION=sync               # Queue driver for API-triggered backups (default: sync)

All Configuration Options

Artisan Commands

notifier:install

Interactive wizard that writes the three required environment variables to your .env file.

php artisan notifier:install

# Overwrite existing values
php artisan notifier:install --force

notifier:check

Validates the full environment and system requirements. Checks:

• NOTIFIER_BACKUP_CODE, NOTIFIER_URL, NOTIFIER_BACKUP_PASSWORD are set
• Database connection is healthy
• storage/app/public is accessible
• mysqldump is available on $PATH
• ZIP tool is available (7z or PHP zip extension)
• Logging channel is configured
• Queue connection is set up
• Backup URL is reachable over HTTPS

php artisan notifier:check

notifier:database-backup

Creates a mysqldump of the application database and uploads it to the central notifier.

php artisan notifier:database-backup

notifier:storage-backup

Archives storage/app/public into an encrypted ZIP and uploads it to the central notifier.

php artisan notifier:storage-backup

API Endpoint

The package registers a single POST endpoint for triggering backups remotely (e.g. from a central scheduler):

POST /{route_prefix}/backup

Authentication: X-Notifier-Token header — must match NOTIFIER_BACKUP_CODE.
Rate limit: 10 requests per 60 seconds.

Request

Examples

# Trigger a database backup
curl -X POST https://your-app.com/api/notifier/backup \
  -H "X-Notifier-Token: your-secret-token" \
  -d "type=backup_database"

# Trigger a storage backup
curl -X POST https://your-app.com/api/notifier/backup \
  -H "X-Notifier-Token: your-secret-token" \
  -d "type=backup_storage"

Response

Success (synchronous):

{
    "success": true,
    "message": "Database backup completed successfully.",
    "backup_type": "database",
    "duration_seconds": 12.34,
    "timestamp": "2025-01-15T10:30:45+00:00"
}

Success (queued):

{
    "success": true,
    "message": "Backup job dispatched to queue.",
    "backup_type": "storage",
    "queued": true,
    "timestamp": "2025-01-15T10:30:45+00:00"
}

Error:

{
    "success": false,
    "message": "Database backup failed.",
    "backup_type": "database",
    "error": "mysqldump: command not found",
    "timestamp": "2025-01-15T10:30:45+00:00"
}

ZIP Strategy

Storage backups use AES-256 encryption regardless of the strategy chosen.

Install 7z for best performance on Linux servers:

sudo apt install p7zip-full

Queue Support

By default, API-triggered backups run synchronously inside the HTTP request. For large backups this may hit PHP's max_execution_time. Set NOTIFIER_QUEUE_CONNECTION to any async queue driver to offload backup jobs:

NOTIFIER_QUEUE_CONNECTION=database   # requires php artisan queue:table
NOTIFIER_QUEUE_CONNECTION=redis      # requires phpredis or predis

Note: Artisan commands (notifier:database-backup, notifier:storage-backup) always run synchronously and are not affected by this setting.

Programmatic Usage

The services can be resolved from the container or injected directly:

use Devuni\Notifier\Services\NotifierDatabaseService;
use Devuni\Notifier\Services\NotifierStorageService;

$db = app(NotifierDatabaseService::class);
$storage = app(NotifierStorageService::class);

// Database backup
$path = $db->createDatabaseBackup();
$db->sendDatabaseBackup($path);

// Storage backup
$path = $storage->createStorageBackup();
$storage->sendStorageBackup($path);

Testing

This package uses Pest for testing.

composer test            # Run all tests
composer test-unit       # Unit tests only
composer test-feature    # Feature tests only
composer test-coverage   # Tests with coverage report

Test Structure

tests/
├── Unit/
│   ├── Commands/         # Artisan command tests
│   ├── Controllers/      # API controller tests
│   ├── Services/         # Service class tests
│   └── NotifierServiceProviderTest.php
└── Feature/
    ├── BackupWorkflowTest.php
    ├── NotifierPackageTest.php
    └── PackageInstallationTest.php

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Ludwig Tomas
• All Contributors

License

The MIT License (MIT). Please see License File for more information.