PHPackages                             cybex/laravel-protector - 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. [Database & ORM](/categories/database)
4. /
5. cybex/laravel-protector

ActiveLibrary[Database & ORM](/categories/database)

cybex/laravel-protector
=======================

Protect Databases by generating Backups and Import those on non-productive Environments.

v3.2.1(6mo ago)59.7k—9.4%[11 issues](https://github.com/cybex-gmbh/laravel-protector/issues)MITPHPPHP ^8.1CI passing

Since Mar 12Pushed 3w ago1 watchersCompare

[ Source](https://github.com/cybex-gmbh/laravel-protector)[ Packagist](https://packagist.org/packages/cybex/laravel-protector)[ Docs](https://github.com/cybex-gmbh/laravel-protector)[ RSS](/packages/cybex-laravel-protector/feed)WikiDiscussions master Synced 2w ago

READMEChangelog (10)Dependencies (8)Versions (44)Used By (0)

Laravel Protector
=================

[](#laravel-protector)

[![Latest Version on Packagist](https://camo.githubusercontent.com/2657cb7cbe61bc88e3b84882632d204c1e57291bbd22ffbc958b5ac19473e1a6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f63796265782f6c61726176656c2d70726f746563746f722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/cybex/laravel-protector)

This package allows you to download, export and import your application's database.

Important

This package will not work if you have disabled "proc\_open" in your PHP configuration.

Table of contents
-----------------

[](#table-of-contents)

- [Introduction](#introduction)
    - [Common usage scenarios](#common-usage-scenarios)
    - [Feature set](#feature-set)
    - [Disks](#disks)
- [Database Support](#database-support)
- [Setup](#setup)
    - [General](#general)
    - [Local usage](#local-usage)
    - [Importing or storing the database of a remote server](#importing-or-storing-the-database-of-a-remote-server)
- [Usage](#usage)
    - [General information](#general-information)
    - [Export](#export)
    - [Import](#import)
    - [Importing or downloading remote databases](#importing-or-downloading-remote-databases)
- [Configuration](#configuration)
    - [Protector instances](#protector-instances)
    - [Disks](#disks-1)
    - [Dump metadata](#dump-metadata)
- [Development](#development)
    - [Testing](#testing)

Introduction
------------

[](#introduction)

### Common usage scenarios

[](#common-usage-scenarios)

- Export your local database to a file
- Developer machines can download the live server database
- A central backup server can collect backups from multiple live servers

### Feature set

[](#feature-set)

- Download and optionally import databases from a server
- Import existing database files
- Export the local database to a file
- User authentication through Laravel Sanctum tokens
- Transport encryption using Sodium
- Operates fully on Laravel disks

### Disks

[](#disks)

The Protector always operates on two local disks, which can be configured separately:

All operations that require file handling, such as creating or importing a database dump, will create a local copy on the `protector_local` disk for processing, and delete it afterwards.

See the [Configuration](#disks-1) section for more details on disk configuration.

Database Support
----------------

[](#database-support)

Protector supports the following databases:

DatabaseDriverDump toolImport toolMariaDB`mariadb``mariadb-dump``mariadb`PostgreSQL`pgsql``pg_dump``psql`MySQL is no longer officially supported, but the Protector still has capabilities to work with Laravel's `mysql` driver. If this should break in the future, feel free to submit a PR.

Note

- Source and destination databases are not validated. Make sure you run compatible software versions to prevent issues.
- Because of different dump formats, dumps will not able to be imported into a different database engine, e.g. a MariaDB dump will fail to be imported into PostgreSQL, and vice versa.

Setup
-----

[](#setup)

There are two setup scenarios, depending on your use case.

- if you only want to operate locally, the General section is sufficient
- if you want to import or download the database of a remote server, follow the additional setup

### General

[](#general)

Install the package via composer.

```
composer require cybex/laravel-protector
```

The Protector will work out of the box using the default configuration.

If you want to customize something, almost all config options can be set via environment variables. Take a look at the [ProtectorEnv](src/Enums/ProtectorEnv.php) class for all available options.

You can optionally publish the Protector config files to have more fine-grained control over config settings:

```
php artisan vendor:publish --tag=protector.config
```

See the [Configuration](#configuration) section for specific details for certain config options.

### Local usage

[](#local-usage)

There is no additional setup required for using the package locally.

See the [Usage](#usage) section for how to export your local database to a file or import existing database dumps.

### Importing or storing the database of a remote server

[](#importing-or-storing-the-database-of-a-remote-server)

This package can run on both servers and client machines of the same software repository. You set up authorized developers on the server and give them the key for their local machine.

In your User model class, add the following trait:

```
use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens;

    ...
}
```

Publish the Protector database migration and optionally modify it to work with your project.

```
php artisan vendor:publish --tag=protector.migrations
```

Publish the [Laravel Sanctum](https://laravel.com/docs/master/sanctum) migration, to make the `personal_access_tokens` table available.

```
php artisan vendor:publish --tag=sanctum-migrations
```

Run the migrations on the client and server repository.

```
php artisan migrate
```

#### On the client machine

[](#on-the-client-machine)

Run the following command to receive

- the public key to give to your server admin
- the private key to save in your .env file

```
php artisan protector:keys
```

Important

Do not give your private key to anyone and keep it protected at all times!

Your server admin will then give you the token and dump endpoint URL to save in your .env file.

```
PROTECTOR_CLIENT_AUTH_TOKEN=
PROTECTOR_CLIENT_DUMP_ENDPOINT_URL=
```

See [Usage](#usage) on how to import the remote database.

Note

Downloaded database dump files are stored unencrypted.

#### On the server

[](#on-the-server)

Make sure that the server is accessible to the client machine via HTTPS.

When one of your developers gives you their public key, you can authorize them with:

```
php artisan protector:token --publicKey=
```

You will receive the token and dump endpoint URL to give back to the developer, who has to save them in their .env file.

The developer can then download and import the server database on their own.

### Setup for collecting backups from multiple servers

[](#setup-for-collecting-backups-from-multiple-servers)

You can develop a custom client that can access and store remote server backups. The servers can be different Laravel projects that have the Protector package installed.

See the previous chapter on how to give your backup client access to all servers.

- The backup client will need an according user on each target server.
- All the backup users on the target servers will have the same public key from the client
- For each target server, the client will store the according url and token

Usage
-----

[](#usage)

### General information

[](#general-information)

Each stored dump also has a matching metadata file with the `.meta` suffix (for example `dump.sql.meta`). The metadata file stores the same metadata object that is embedded in the SQL dump footer under `meta`.

Interactive import reads metadata from these metadata files to prevent downloading the whole dump file. If a metadata file is missing, the dump can still be selected, and the import command will group it as an unknown connection.

### Export

[](#export)

To write a dump to the Protector storage folder:

```
php artisan protector:export
```

To write the dump to a different location, you can specify a custom file name and disk:

```
php artisan protector:export --file='custom_filename.sql' --disk='custom_disk'
```

For more information on the available options:

```
php artisan protector:export --help
```

You could also automate this by

- installing a cronjob on linux
- running it when you deploy to your server
- creating a Laravel Job and queueing it

### Import

[](#import)

To import a dump file interactively:

```
php artisan protector:import
```

To import a specific dump file (optionally on a specific disk):

```
php artisan protector:import --file='custom_filename.sql' --disk='custom_disk'
```

You could also automate this similar to the export command, for this you want to use the `--force` option to bypass user interaction.

For example, to import the latest dump without interaction and migrate afterwards:

```
php artisan protector:import --latest --migrate --force
```

For more information on the available options:

```
php artisan protector:import --help
```

### Importing or downloading remote databases

[](#importing-or-downloading-remote-databases)

To import a remote dump either run the command interactively or use the `--remote` option:

```
php artisan protector:import --remote
```

When used with other options, remote will serve as fallback behaviour.

Note

Importing remote dumps will not leave any files on storage disk.

If you need to store the remote dump on the storage disk:

```
php artisan protector:download
```

To store and import in one step:

```
php artisan protector:download --import
```

To store the dump on a different disk with a specific file name:

```
php artisan protector:download --file='custom_filename.sql' --disk='custom_disk'
```

If you want to delete all files on the Protector storage disk except the newly stored dump, use the `--cleanup-storage` option. The cleanup will only delete files with existing `.meta` files, and will not delete files in subdirectories of the storage disk.

```
php artisan protector:download --cleanup-storage
```

For more information on the available options:

```
php artisan protector:download --help
```

Like the import and export commands, a `--force` option is available to bypass user interaction, e.g. to automate this process.

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

[](#configuration)

### Protector instances

[](#protector-instances)

The Protector config files set initial settings for the `Protector` instance.

Generally, you should keep the `Protector` singleton instance as is. To create a new instance with different settings, use the `ProtectorConfigurator` class. For all available configuration options, take a look at the [ProtectorConfiguratorContract](src/Contracts/ProtectorConfiguratorContract.php).

For example, to configure a specific auth token and dump endpoint URL:

```
$protector = ProtectorConfigurator::setAuthToken($authToken)->setDumpEndpointUrl($dumpEndpointUrl)->makeProtector();
```

### Disks

[](#disks-1)

There are two disks, which use the `local` driver by default:

- [protector\_local](config/filesystems/local.php) is used for temporary files which are deleted after use
    - writes to `storage/app/private/protector_local` by default
- [protector\_storage](config/filesystems/storage.php) is used for storing dumps and their metadata files
    - writes to `storage/app/private/protector` by default

Important

The `protector_local` disk must be a local disk, as certain operations require a local filesystem, such as creating or importing a database dump.

All operations go through the local disk by creating a local copy first. Some commands offer a --no-copy option to skip the local copy.

If you want to override the disk configuration, add the following to your `config/filesystems.php` file:

```
'protector_local' => [
    ...
],

'protector_storage' => [
    ...
],
```

You could for example use S3 for the storage disk.

### Dump metadata

[](#dump-metadata)

Customize the metadata appended to a dump by adding providers to the `metadata.providers` array in your `config/protector/dump.php` file:

```
'providers' => [
    \Cybex\Protector\Classes\Metadata\Providers\EnvMetadataProvider::class,
    \Cybex\Protector\Classes\Metadata\Providers\GitMetadataProvider::class,
    \Path\To\Your\CustomMetadataProvider::class,
],
```

Available metadata providers:

1. `DatabaseMetadataProvider`: Will always be appended. Adds general information about the dump, such as the database connection and dumped at date.
2. `ProtectorMetadataProvider`: Adds information about the settings set on the Protector's config.
3. `EnvMetadataProvider`: Adds information based on an .env value. The default .env key used for this is `PROTECTOR_METADATA`.
4. `GitMetadataProvider`: Adds information about the Git repository, such as the current branch and revision.
5. `JsonMetadataProvider`: Adds information from a JSON file. The default file path used for this is `protector_metadata.json`.

Note

You can create your own metadata providers by implementing the `Cybex\Protector\Contracts\MetadataProvider` interface. Duplicate provider keys will be merged in the final metadata array, so choose a unique key.

Tip

An example of using the JsonMetadataProvider would be to add custom metadata from a CI/CD pipeline. For example, in a GitHub Actions workflow, you could add a step that writes Git information to `protector_metadata.json`

```
- name: Protector Metadata
  shell: bash
  run: >
    jq -n \
      --arg repo ${{ github.repository }} \
      --arg branch ${{ github.ref_name }} \
      --arg revision ${{ github.sha }} \
      --arg buildDate "$(date --iso-8601=seconds --utc)" \
      '{gitRepo: $repo, gitBranch: $branch, gitRevision: $revision, buildDate: $buildDate}' > protector_metadata.json
```

### Cleanup of Protector disks

[](#cleanup-of-protector-disks)

#### protector\_local

[](#protector_local)

Normally there should be no remnants of temporary files. In case of unexpected errors, such as when the PHP process is killed, temporary files might remain on the disk.

The Protector will automatically delete these files on every operation involving the local disk. Due to this running synchronously, performance might be impacted.

Note

Only files older than 1 day will be deleted, to prevent deleting files that are currently being processed.

To run this asynchronously instead, you can set

```
PROTECTOR_CLEANUP_LOCAL_DISK_MODE=schedule
```

This will schedule the deletion based on a cron expression defined with `PROTECTOR_CLEANUP_LOCAL_DISK_SCHEDULE`, which defaults to `0 0 * * *` (every day at midnight).

Note

You need to run the [Laravel Scheduler](https://laravel.com/docs/master/scheduling#running-the-scheduler) for this.

To manually delete all temporary files older than 1 day on the `protector_local` disk:

```
php artisan protector:cleanup-local
```

#### protector\_storage

[](#protector_storage)

Either use the dedicated command

```
php artisan protector:cleanup-storage
```

or cleanup when downloading a new dump

```
php artisan protector:download --cleanup-storage
```

Development
-----------

[](#development)

There is an example app with the Laravel Protector package installed.

The file structure in the container is as follows:

- /var/www: example app
- /var/package: Protector package

```
docker compose up -d
```

```
docker compose exec app shell
```

Make sure to run composer install in both the example app and the package to install dependencies:

```
composer install
```

Note

We disable composer security checking for this package, as vulnerabilities would block the development. The project requiring our package should be responsible for evaluating possible vulnerabilities. For more information, see the [composer documentation](https://getcomposer.org/doc/06-config.md#block-insecure).

Specific to the example app, for demo data:

```
php artisan migrate:fresh --seed
```

Note

The example app uses the same database as the Unit tests, which might pollute the DB with data. For a reproducible environment, always run the above command before executing commands in the example app.

### Testing

[](#testing)

Run tests on the MariaDB database:

```
composer test
```

Run tests on the PostgreSQL database:

```
composer test-postgres
```

Run tests on the MySQL database:

Note

Running MySQL tests on the current alpine image will not work, as the MySQL CLI command is only an alias to mariadb and does not fully support the MySQL server.

If you need to run MySQL tests, use a different image. To start up the mysql server, use `docker compose --profile mysql up -d`

```
composer test-mysql
```

To test scheduling functionalities, run the Laravel Scheduler:

```
php artisan schedule:work
```

#### Test coverage

[](#test-coverage)

To generate coverage, you need to run the tests from the package directory.

```
cd ../package
```

```
composer test
```

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

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

### Security

[](#security)

If you discover any security-related issues, please email  instead of using the issue tracker.

Credits
-------

[](#credits)

- [Web Development team at CYBEX GmbH - cybex-online.com](https://github.com/cybex-gmbh)
- [Gael Connan](https://github.com/gael-connan-cybex)
- [Jörn Heusinger](https://github.com/jheusinger)
- [Fabian Holy](https://github.com/holyfabi)
- [Oliver Matla](https://github.com/lupinitylabs)
- [Marco Szulik](https://github.com/mszulik)
- [All Contributors](https://github.com/cybex-gmbh/laravel-protector/graphs/contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

48

—

FairBetter than 94% of packages

Maintenance63

Regular maintenance activity

Popularity28

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity75

Established project with proven stability

 Bus Factor1

Top contributor holds 52.3% 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 ~89 days

Recently: every ~115 days

Total

21

Last Release

194d ago

Major Versions

v1.6.0 → v2.0.02023-02-23

v2.2.0 → v3.0.02024-03-15

PHP version history (4 changes)v1.0.0PHP ^7.2|^8.0

v1.3.0PHP ^8.0

v2.0.0PHP ^8.1

v3.0.0PHP ^8.2

### Community

Maintainers

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

---

Top Contributors

[![holyfabi](https://avatars.githubusercontent.com/u/88314661?v=4)](https://github.com/holyfabi "holyfabi (204 commits)")[![gael-connan-cybex](https://avatars.githubusercontent.com/u/69622662?v=4)](https://github.com/gael-connan-cybex "gael-connan-cybex (84 commits)")[![lupinitylabs](https://avatars.githubusercontent.com/u/17774818?v=4)](https://github.com/lupinitylabs "lupinitylabs (68 commits)")[![mszulik](https://avatars.githubusercontent.com/u/69617961?v=4)](https://github.com/mszulik "mszulik (29 commits)")[![jheusinger](https://avatars.githubusercontent.com/u/69620784?v=4)](https://github.com/jheusinger "jheusinger (5 commits)")

---

Tags

hacktoberfestlaravelencryptiondatabasebackupsynccybexprotector

###  Code Quality

TestsPHPUnit

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/cybex-laravel-protector/health.svg)

```
[![Health](https://phpackages.com/badges/cybex-laravel-protector/health.svg)](https://phpackages.com/packages/cybex-laravel-protector)
```

###  Alternatives

[unopim/unopim

UnoPim Laravel PIM

10.8k2.5k](/packages/unopim-unopim)[leantime/leantime

Open source project management system for non-project managers. Simple like Trello, powerful like Jira. Built with neurodiversity in mind.

11.3k4.0k](/packages/leantime-leantime)[bagisto/bagisto

Bagisto Laravel E-Commerce

28.0k175.2k9](/packages/bagisto-bagisto)[api-platform/laravel

API Platform support for Laravel

58190.1k21](/packages/api-platform-laravel)[fleetbase/core-api

Core Framework and Resources for Fleetbase API

1239.7k25](/packages/fleetbase-core-api)

PHPackages © 2026

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