Skip to content

Commit

Permalink
Merge pull request #112 from Laravel-Backpack/v4
Browse files Browse the repository at this point in the history 
BackupManage v4 Release
  • Loading branch information
@tabacitu
tabacitu committed Apr 6, 2022
2 parents b016401 + a45608d commit 091d611
Show file tree
Hide file tree
Showing 10 changed files with 362 additions and 259 deletions.
129 changes: 44 additions & 85 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ An admin interface for [spatie/laravel-backup](https://github.com/spatie/laravel
> ### Security updates and breaking changes
> Please **[subscribe to the Backpack Newsletter](http://backpackforlaravel.com/newsletter)** so you can find out about any security updates, breaking changes or major features. We send an email 2 times/year, max.
![Backpack\BackupManager screenshot](https://user-images.githubusercontent.com/1032474/150080754-97dca93f-3cac-452b-9bcf-cc51becd3055.png)
![Backpack\BackupManager screenshot](https://user-images.githubusercontent.com/1032474/161931994-dc044bb2-a459-4863-9262-ed91f3e5e35b.gif)


## Install
Expand All @@ -25,124 +25,83 @@ An admin interface for [spatie/laravel-backup](https://github.com/spatie/laravel
# Install the package
composer require backpack/backupmanager

# Add a sidebar_content item for it
php artisan backpack:add-sidebar-content "<li class='nav-item'><a class='nav-link' href='{{ backpack_url('backup') }}'><i class='nav-icon la la-hdd-o'></i> Backups</a></li>"
```

You will notice that two configuration files are created. You should check [spatie documentations on how to configura your backup system](https://spatie.be/docs/laravel-backup/v8/installation-and-setup) in `config/backup.php`

As far as `config/backpack/backupmanager.php` it configures how the `Backup` button works: `--only-files, --only-db` etc.
# Publish the backup and backupmanager configs and lang files:
php artisan vendor:publish --provider="Backpack\BackupManager\BackupManagerServiceProvider" --tag=backup-config --tag=lang

3) [optional] You can add backup flags for when the backup process is run from the user interface. In your `config/backup.php` under the `backup` key you can add the `backpack_flags` array below:

```php
'backup' => [

/* --------------------------------------
* Backpack\BackupManager Command Flags
* --------------------------------------
* These flags will be attached every time a backup is triggered
* by Backpack\BackupManager. By default only notifications are disabled.
*
* https://docs.spatie.be/laravel-backup/v4/taking-backups/overview
* --only-to-disk=name-of-your-disk
* --only-db
* --only-files
* --disable-notifications
*/
'backpack_flags' => [
'--disable-notifications'=> true,
],

// ...
],
# [optional] Add a sidebar_content item for it
php artisan backpack:add-sidebar-content "<li class='nav-item'><a class='nav-link' href='{{ backpack_url('backup') }}'><i class='nav-icon la la-hdd-o'></i> Backups</a></li>"
```

4) [optional] Modify your backup options in ```config/backup.php``` (which is `spatie/laravel-backup`'s config file), then run ```php artisan backup:run``` to make sure it's still working.

5) [optional] Instruct Laravel to run the backups automatically in your console kernel:

```php
// app/Console/Kernel.php

protected function schedule(Schedule $schedule)
{
$schedule->command('backup:clean')->daily()->at('04:00');
$schedule->command('backup:run')->daily()->at('05:00');
// if you are not using notifications you should add the `--disable-notifications` flag to this commands
$schedule->command('backup:clean')->daily()->at('04:00');
$schedule->command('backup:run')->daily()->at('05:00');
}
```

6) Check that it works

If the "unknown error" yellow bubble is thrown and you see the "_Backup failed because The dump process failed with exitcode 127 : Command not found._" error in the log file, either mysqldump / pg_dump is not installed or you need to specify its location.

You can do that in your `config/database.php` file, where you define your database credentials, by adding the dump variables. Example for Mac OS X's MAMP:
You can do that in your `config/database.php` file, where you define your database credentials, by adding the dump variables. Here's an example:

```php
'mysql' => [
'driver' => 'mysql',
'host' => env('DB_HOST', 'localhost'),
'database' => env('DB_DATABASE', 'forge'),
'username' => env('DB_USERNAME', 'forge'),
'password' => env('DB_PASSWORD', ''),
'charset' => 'utf8',
'collation' => 'utf8_unicode_ci',
'prefix' => '',
'strict' => false,
'engine' => null,
'dump' => [
'dump_binary_path' => '/path/to/directory/', // only the path, without `mysqldump` or `pg_dump`
// 'dump_binary_path' => '/Applications/MAMP/Library/bin/', // works for MAMP on Mac OS
// 'dump_binary_path' => '/opt/homebrew/bin/', // works for Laravel Valet on Mac OS
'use_single_transaction',
'timeout' => 60 * 5, // 5 minute timeout
// 'exclude_tables' => ['table1', 'table2'],
// 'add_extra_option' => '--optionname=optionvalue',
]
],
'driver' => 'mysql',
'host' => env('DB_HOST', 'localhost'),
'database' => env('DB_DATABASE', 'forge'),
'username' => env('DB_USERNAME', 'forge'),
'password' => env('DB_PASSWORD', ''),
'charset' => 'utf8',
'collation' => 'utf8_unicode_ci',
'prefix' => '',
'strict' => false,
'engine' => null,
'dump' => [

'dump_binary_path' => '/path/to/directory/', // only the path, without `mysqldump` or `pg_dump`
// 'dump_binary_path' => '/Applications/MAMP/Library/bin/', // works for MAMP on Mac OS
// 'dump_binary_path' => '/opt/homebrew/bin/', // works for Laravel Valet on Mac OS
'use_single_transaction',
'timeout' => 60 * 5, // 5 minute timeout
// 'exclude_tables' => ['table1', 'table2'],
// 'add_extra_option' => '--optionname=optionvalue',
]
],
```

## Usage

Point and click, baby. Point and click.
This should be a point-and-click interface where you can create and download backups at any time.

Try at **your-project-domain/admin/backup**

## Configuration & Troubleshooting

## Upgrading from 2.x to 3.x

Change your required version to ```"backpack/backupmanager": "^3.0",``` and run ```composer update```. There are no breaking changes just icons that are show using ```la la-icon``` instead of ```fa fa-icon```.


## Upgrading from 1.2.x to 1.3.x

1) change your required version to ```"backpack/backupmanager": "^1.3",``` and run ```composer update```;
2) delete the old config file (too many changes, including namechange): ```rm config/laravel-backup.php```
3) republish the config files: ```php artisan vendor:publish --provider="Backpack\BackupManager\BackupManagerServiceProvider"```
4) change your db configuration in ```config/database.php``` to use the new dump configuration (all options in one array; the example below is for MAMP on MacOS):

```
'dump' => [
'dump_binary_path' => '/Applications/MAMP/Library/bin/', // only the path, so without `mysqldump` or `pg_dump`
'use_single_transaction',
'timeout' => 60 * 5, // 5 minute timeout
// 'exclude_tables' => ['table1', 'table2'],
// 'add_extra_option' => '--optionname=optionvalue',
]
```
5) Create a backup in the interface to test it works. If it doesn't try ```php artisan backup:run``` to see what the problem is.

For additional configuration (eg. notifications):
- publish the spatie backup file `php artisan vendor:publish --provider="Spatie\Backup\BackupServiceProvider" --tag="backup-config"`
- see the [spatie/laravel-backup documentation](https://spatie.be/docs/laravel-backup/v8/installation-and-setup) on how to configure your backup system in `config/backup.php`; **it is higly recommended that you at least [configure the notifications](https://spatie.be/docs/laravel-backup/v8/sending-notifications/overview)**;
- see `config/backpack/backupmanager.php` for configurating how the backup is run from the interface; by default, it does `backup:run --disable-notifications`, but after you've configured notifications, you can remove that flag (or add others);

## Upgrading from 1.1.x to 1.2.x
**[TIP]** When you modify your options in `config/backup.php` or `config/backpack/backupmanager.php`, please run manually `php artisan backup:run` to make sure it's still working after your changes. **NOTE**: `php artisan optimize:clear` and/or `php artisan config:clear` might be needed before the `backup:run` command.

1) change your required version to ```"backpack/backupmanager": "^1.2",```;
2) the only breaking change is that the ```config/database.php``` dump variables are now inside an array. Please see the step 8 above, copy-paste the ```dump``` array from there and customize;
## Upgrading

Please see the [upgrade guides](UPGRADE_GUIDES.md) to get:
- from v3 to v4 (new!)
- from v2 to v3
- from 1.2.x to 1.3.x
- from 1.1.x to 1.2.x

## Change log

Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.
Please see the [releases page](https://github.com/Laravel-Backpack/BackupManager/releases/) for more information what has changed recently.

## Testing

Expand Down
73 changes: 73 additions & 0 deletions UPGRADE_GUIDES.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
# Upgrade Guides

## Upgrading from 3.x to 4.x

Change your required version to `"backpack/backupmanager": "^4.0"` and run `composer update backpack/backupmanager`.

We removed the overrides of spatie config from our package publishing process, from now on you can do the regular spatie backup configuration in `config/backup.php` and the customized backpack configuration in `config/backpack/backupmanager`.

**1)** Publish the new config file `php artisan vendor:publish --provider="Backpack\BackupManager\BackupManagerServiceProvider" --tag="backup-config"`. This will generate the `config/backpack/backupmanager.php` file. By default backpack uses `--disable-notifications` flag, remove it if you are using notifications.

**2)** If you have configured `backpack_flags` in `config/backup` you should now move them to the new config, under the key: `artisan_command_on_button_click`.

```php
// This command will be run when user click on the "Create a new backup" button
// You can add flags to this like --only-db --only-files --only-to-disk=name-of-disk --disable-notifications
// Details here: https://spatie.be/docs/laravel-backup/v8/taking-backups/overview
'artisan_command_on_button_click' => 'backup:run --disable-notifications',
```

**3)** If you didn't do anymore configs you can now safely remove the `config/backup.php` file and there is no need to re-publish the spatie config, **jump to step 5**.

**4)** If you are customizing other options in `config/backup.php` file make sure that your changes are compatible with the new config (it should be), otherwise save your config file in some other place, force publish the v8 spatie configuration file with `php artisan vendor:publish --force --provider="Spatie\Backup\BackupServiceProvider" --tag="backup-config"` and then re-configure what you need.

**5)** You may need to clear the cache with `php artisan optimize:clear` and/or `php artisan config:clear`.

**6)** Manually run from console the `backup:run` command to make sure it's working, use `backup:run --disable-notifications` if you are not using notifications.

**7)** If you are **scheduling your backup jobs** make sure to also use the apropriate synthax in the commands. In previous backup versions the notification exceptions would **not be reported** and your scripts would run fine even if an exception was thrown. Now **they report**, so to avoid the exceptions halting your scripts in the notification part, **you need to explicitly tell the backup script that you don't want notifications** if you didn't configure them:

```php
// app/Console/Kernel.php

protected function schedule(Schedule $schedule)
{
// this would work previously even if you didn't configured notifications,
// it would throw an exception but it was not reported, so script is not halted.
$schedule->command('backup:clean')->daily()->at('04:00');

// now if you don't use notifications you should explicitly tell that to backup
// otherwise the same exception will be thrown, but this time reported,
// halting the script execution.
$schedule->command('backup:clean --disable-notifications')->daily()->at('04:00');
}
```

## Upgrading from 2.x to 3.x

Change your required version to ```"backpack/backupmanager": "^3.0",``` and run ```composer update```. There are no breaking changes just icons that are show using ```la la-icon``` instead of ```fa fa-icon```.


## Upgrading from 1.2.x to 1.3.x

1) change your required version to ```"backpack/backupmanager": "^1.3",``` and run ```composer update```;
2) delete the old config file (too many changes, including namechange): ```rm config/laravel-backup.php```
3) republish the config files: ```php artisan vendor:publish --provider="Backpack\BackupManager\BackupManagerServiceProvider"```
4) change your db configuration in ```config/database.php``` to use the new dump configuration (all options in one array; the example below is for MAMP on MacOS):

```php
'dump' => [
'dump_binary_path' => '/Applications/MAMP/Library/bin/', // only the path, so without `mysqldump` or `pg_dump`
'use_single_transaction',
'timeout' => 60 * 5, // 5 minute timeout
// 'exclude_tables' => ['table1', 'table2'],
// 'add_extra_option' => '--optionname=optionvalue',
]
```
5) Create a backup in the interface to test it works. If it doesn't try ```php artisan backup:run``` to see what the problem is.


## Upgrading from 1.1.x to 1.2.x

1) change your required version to ```"backpack/backupmanager": "^1.2",```;
2) the only breaking change is that the ```config/database.php``` dump variables are now inside an array. Please see the step 8 above, copy-paste the ```dump``` array from there and customize;
5 changes: 4 additions & 1 deletion src/BackupManagerServiceProvider.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,8 +38,11 @@ public function boot()
// - then the stock views that come with the package, in case a published view might be missing
$this->loadViewsFrom(realpath(__DIR__.'/resources/views'), 'backupmanager');

// publish config file
$this->publishes([__DIR__.'/config/backupmanager.php' => config_path('backpack/backupmanager.php')], 'backup-config');

// publish lang files
$this->publishes([__DIR__.'/resources/lang' => resource_path('lang/vendor/backpack')], 'lang');
$this->publishes([__DIR__.'/resources/lang' => app()->langPath().'/vendor/backpack'], 'lang');
// publish the views
$this->publishes([__DIR__.'/resources/views' => resource_path('views/vendor/backpack/backupmanager')], 'views');
}
Expand Down
Loading

0 comments on commit 091d611

Please sign in to comment.