Download the PHP package ramadan/custom-fresh without Composer

Custom Fresh

Custom Fresh offers fine-grained control over migrations within your Laravel project, enabling you to select which tables will not be dropped when refreshing the database.

[!TIP] Always consider upgrading the package to the latest version, which is the most stable release.

• Installation
• Usage
  • Refreshing migrations
  • Glob patterns
  • Drop only some tables
  • Keep tables without migrations
  • Except
  • Presets
  • Pending alters
  • Related tables
  • Multiple connections
  • Dry run
  • List tables
  • Seeding
  • Views and types
  • Replace migrate:fresh
  • Configuration
  • Events
• Credits
• Support me

Installation

Install the package by using Composer:

(Optional) publish the config file:

Usage

After installing the package, you will see a new fresh:custom command.

[!NOTE] Since v1.2.0, the package scans your migration files more accurately, including nested folders, custom --path locations, and package migration paths registered through Laravel.

Refreshing migrations

You can exclude specific tables while refreshing the database inside your project:

The same can be expressed with the --keep option (which can be combined with the positional argument):

When nothing is passed and the config is empty, an interactive picker lists the discovered tables.

[!IMPORTANT] Do not forget always to use the -h of the command to check out all supported options.

Glob patterns

Anything containing *, ?, or […] is expanded with fnmatch against the database tables, so you can preserve whole groups at once:

Drop only some tables

You can invert the default and drop just a few tables, while everything else is preserved:

The --drop option can be combined with --keep or --preset. Explicit --drop always wins.

Keep tables without migrations

You can preserve tables that have no migration file (common for Laravel 11+ sessions, cache, or jobs):

The same list can be set in keep_without_migrations inside the config.

Except

You can temporarily drop a table that is otherwise always kept:

Presets

You can group tables in the config and apply them by name:

Pending alters

By default, new alter migrations that touch a kept table still run, so add_phone_to_users_table is applied even when users is preserved.

Use --freeze-schema to mark every migration for kept tables as already run:

Related tables

Keeping a child table also preserves the parent tables it references, and keeping a parent also preserves its children:

Pass --drop-referenced to refresh child tables of a kept parent:

Multiple connections

Pass --database= to target a non-default connection. The connection is also forwarded to the migrate command:

Per-connection overrides can be set under the connections key in the config.

Dry run

Use --explain to preview exactly what would happen without dropping a single table:

It prints the resolved connection, the tables that would be preserved, the tables that would be dropped, the migration rows that would be re-inserted, and any pending alters that will still run.

The same plan can be printed as JSON:

List tables

Use --list to inspect the tables the scanner sees and the migration files that touch them:

The same can be expressed as JSON with --json:

Seeding

Use --seed to re-run DatabaseSeeder after migrate. If you preserved tables with unique columns, that often inserts duplicates.

Use --seed-fresh to seed only the dropped tables, through the table_seeders map in the config:

Views and types

Pass --drop-views and --drop-types to match Laravel's migrate:fresh when leftover views or PostgreSQL types would break the next run:

The --drop-types option is supported on PostgreSQL only.

Replace migrate:fresh

Set replace_migrate_fresh to true in the config. Then php artisan migrate:fresh delegates to fresh:custom whenever always_keep, patterns, or keep_without_migrations is set. Otherwise Laravel's original command still runs.

Configuration

Publishing the config (see above) gives you config/custom-fresh.php:

• always_keep — tables that are preserved on every run, even if you don't list them on the command line.
• patterns — glob patterns expanded against the database on every run.
• keep_without_migrations — tables preserved even when they have no migration file.
• presets — named groups applied with --preset=.
• table_seeders — dropped-table seeders used by --seed-fresh.
• connections — extra lists merged when --database= matches the key.
• confirm_in — environments where the command must ask for confirmation. Use --force to bypass.
• replace_migrate_fresh — let migrate:fresh honor the lists above.

Events

Three events are dispatched during a run, perfect for backups, audit logs, or Slack notifications:

• Ramadan\CustomFresh\Events\RefreshingDatabase — fired before any destructive work, with the resolved preserve list and migration rows.
• Ramadan\CustomFresh\Events\TablesDropped — fired right after the drop step, with both the preserved and dropped tables.
• Ramadan\CustomFresh\Events\DatabaseRefreshed — fired after the underlying migrate finishes successfully.

Credits

• Mahmoud Ramadan
• Contributors

Support me

• PayPal

License

The MIT License (MIT).