Getting Started

Minimal Setup

Installation

composer require spatie/nova-backup-tool

Publish the configuration file:

php artisan vendor:publish --provider="Spatie\NovaBackupTool\NovaBackupToolServiceProvider" --tag="nova-backup-tool-config"

Register the Tool Add the tool to your Nova toolset in app/Providers/NovaServiceProvider.php:

public function tools()
{
    return [
        // ...
        new \Spatie\NovaBackupTool\NovaBackupTool,
    ];
}

First Backup
- Navigate to the Backups tool in Nova.
- Click "Create Backup" to generate your first backup using the underlying spatie/laravel-backup package.
- Verify the backup appears in the list with metadata (e.g., size, creation time).

Where to Look First

Configuration: config/nova-backup-tool.php – Define backup storage (e.g., S3, local disk), retention policies, and excluded directories.
Nova Tool UI: The tool provides a clean interface for listing, downloading, and deleting backups without CLI access.
Underlying Package: For advanced customization, refer to spatie/laravel-backup docs (e.g., adding databases, files, or custom commands).

First Use Case: Scheduled Backups with Retention

Configure config/nova-backup-tool.php to auto-backup daily:

'schedule' => [
    'command' => 'backup:run',
    'expression' => '0 3 * * *', // Runs at 3 AM daily
],

Set retention to keep backups for 30 days:

'retention' => [
    'keep_backups_for_days' => 30,
],

Run the scheduler:
```
php artisan schedule:run
```
Monitor backups via the Nova tool.

Implementation Patterns

Workflows

1. Backup Management

List Backups: View all backups with filters (e.g., by date, size).
Create On-Demand: Trigger backups manually via the Nova UI.
Download/Restore: Download backups directly from Nova (useful for off-site storage).
Delete: Remove old backups via the UI or retention policies.

2. Integration with Nova

Tool Access Control: Use Nova’s built-in authorization to restrict backup access to specific roles:

public function authorizedToAccessNova(Request $request)
{
    return $request->user()->can('manage backups');
}

Customize UI: Extend the tool’s views (e.g., add backup status badges) by publishing and overriding templates:
```
php artisan vendor:publish --tag="nova-backup-tool-views"
```

3. Storage Backends

Local Storage: Defaults to storage/backups (configured in config/nova-backup-tool.php).
Cloud Storage: Use S3, Dropbox, or FTP by configuring spatie/laravel-backup:
```
'storage' => [
    'disk' => 's3',
    'bucket' => 'my-backups',
],
```

4. Custom Backup Contents

Leverage spatie/laravel-backup to include/exclude items:

// config/backup.php
'sources' => [
    \Spatie\Backup\Tasks\DatabaseTask::class,
    \Spatie\Backup\Tasks\FilesTask::class => [
        'directories' => [storage_path('app/public')],
    ],
],

Integration Tips

Event Listeners Hook into backup events (e.g., BackupStarted, BackupCompleted) to log or notify:

use Spatie\Backup\Events\BackupCompleted;

BackupCompleted::listen(function (BackupCompleted $event) {
    Log::info('Backup completed', ['backup_name' => $event->backup->name]);
});

Nova Actions Add custom actions to backups (e.g., "Verify Backup"):

use Laravel\Nova\Actions\Action;

class VerifyBackup extends Action
{
    public function handle(NovaRequest $request, $backup)
    {
        // Logic to verify backup integrity
        return Action::message('Backup verified successfully.');
    }
}

API Access Expose backup endpoints via Nova’s API for programmatic access:

Route::get('/api/backups', function () {
    return \Spatie\NovaBackupTool\Backup::all();
});

Gotchas and Tips

Pitfalls

Storage Permissions
- Ensure the backup storage directory (e.g., storage/backups) is writable:
```
chmod -R 755 storage/backups
```
- For cloud storage, verify IAM roles/credentials are correctly configured in .env.
Scheduler Conflicts
- If using schedule:run, ensure the cron job runs frequently enough (e.g., every 5 minutes) to trigger the backup command:
```
* * * * * cd /path-to-project && php artisan schedule:run >> /dev/null 2>&1
```
Large Backups
- Avoid backing up massive databases/files without testing. Monitor disk space and adjust max_execution_time in php.ini if needed.
Nova Caching
- Clear Nova’s view cache after publishing custom views:
```
php artisan nova:cache-reset
```

Debugging

Backup Failures
- Check storage/logs/laravel.log for errors during backup execution.
- Enable verbose logging in config/backup.php:
```
'logging' => 'verbose',
```
Tool Not Showing
- Verify the tool is registered in NovaServiceProvider and the user has permissions.
- Check for JavaScript errors in Nova’s browser console (e.g., missing CSRF token).
Storage Issues
- Test cloud storage connections manually:
```
php artisan backup:test
```

Tips

Exclude Sensitive Data Use .env to exclude directories (e.g., storage/logs):
```
BACKUP_EXCLUDE_DIRECTORIES=storage/logs,storage/debug-bar
```
Compress Backups Enable compression in config/backup.php to reduce storage usage:
```
'compression' => true,
```
Backup Verification Add a BackupTask to verify backups post-creation:
```
'tasks' => [
    \Spatie\Backup\Tasks\VerifyTask::class,
],
```
Multi-Environment Configs Use environment-specific configs (e.g., config/backup-local.php) and load them conditionally:
```
$backupConfig = config('backup-' . app()->environment);
```
Nova Tool Icons Customize the tool icon by overriding the icon property in your NovaBackupTool instance:
```
new \Spatie\NovaBackupTool\NovaBackupTool(['icon' => 'heroicon-o-cloud-arrow-up']),
```

Backup Notifications Integrate with Laravel Notifications to alert teams when backups complete:

BackupCompleted::listen(function () {
    Notification::route('mail', 'admin@example.com')
                ->notify(new BackupCompletedNotification());
});

Testing Backups Use spatie/laravel-backup's testing utilities to mock backups in PHPUnit:
```
$this->artisan('backup:run')->expectsOutput('Backup completed');
```

Nova Backup Tool Laravel Package