Hop between databases with ease whilst developing locally on Laravel.
Imagine: A colleague asks you to check their PR out. But you're working on a new feature yourself and your local database is *just* right. You've got it tuned with the right models, the right data - losing it would just be an inconvenience too far...
So now imagine: A colleague asks you to check their PR out. You jump onto their branch, set up your database - migrate it, seed it, wipe it, whatever - and review their work. Then, you return to your feature and pick up where you left off - with your database still intact.
Enter Hopper. It's as simple as:
php artisan hop awesome_new_featureNow, you're on a database called awesome_new_feature.
With Git, it's even simpler:
php artisan hopNow, you're on a database for the current branch!
And you can always hop back to your default database with:
php artisan hop --dNow, you're on the default database as configured by your Laravel settings.
You can install the package via composer:
composer require nedwors/hopper --devHopper comes with a config file for you to publish to config/hopper.php:
php artisan hop:publishYou don't need to publish the config file to use Hopper, but it is recommended. But no pressure. Honest... See configuration to see whether you want to for your project.
Commands:
Configuration:
This is the core command when using Hopper. There are 3 ways it can be used:
- Use a database for the current Git branch
- Use a specific database
- Use the default database
This option is where Hopper really shines. Simply checkout a branch, hop, and you're on a new database. Checkout your previous branch, hop, and you're back to where you started.
To use Hopper this way, simply hop without arguments:
git checkout -b updates
php artisan hopNow, when using your app, it will be connected to the updates database.
Your default Git branch aliases to your default database. So, imagine main is your default branch. When you run this:
git checkout main
php artisan hopYou won't move to the a database called main. Instead, you'll be moved to your default database - simple!
But don't worry, you're not forced to use the current Git branch. You can also specify a name at any point, or manually use the default branch.
To use a specific database, simply pass the name of the database to use:
php artisan hop foobarNow, when using your app, it will be connected to the foobar database.
To use the default database, pass the --d option to the command:
php artisan hop --dNow, your app simply uses the default database as is set up in Laravel.
Hopper steps aside when the default database is used; it doesn't touch your database connection. This is useful for team members who might not want to use Hopper themselves. They can rest assured that Hopper isn't interfering with their setup.
When it is the first time using a database, Hopper will create it ready to use. Likely, you'll want to migrate and setup up this database. Hopper provides a clean way to run Post Creation Steps - see how you can set these up.
See the database that you are currently using:
php artisan hop test
php artisan hop:current
// Currently using testDelete the given database:
php artisan hop:delete test
// Deleted testWhen a database is deleted, you will be moved back to your default database.
As stated in setup, you don't need to publish the hopper config file to use Hopper. The config file is as so:
'default-branch' => env('HOPPER_DEFAULT_BRANCH', 'main'),
'connections' => [
'sqlite' => [
'driver' => Sqlite::class,
'database-path' => 'hopper/'
],
'mysql' => [
'driver' => MySql::class,
'database-prefix' => 'hopper_'
],
],
'boot-checks' => [
Environment::class
],
'post-creation-steps' => [
'migrate:fresh'
]We'd encourage to checkout all the options described below to see if you want to publish it or not.
You should define here the name of the default git branch in your project:
...
'default-branch' => env('HOPPER_DEFAULT_BRANCH', 'main')
...Now, every time you hop on this branch without arguments, your default database will be used automatically - rather than a database called main.
You'll see that there is a HOPPER_DEFAULT_BRANCH .env variable available too - this means you can alter this value without publishing the config file.
Currently, Hopper has built in support for sqlite and mysql database connections. Hopper will automatically use whichever connection you are using.
These and future drivers are exposed and configured in the config file - which means you can add your own even if Hopper doesn't yet support it natively! See the supported connections in hopper.php:
...
'connections' => [
'sqlite' => [
'driver' => Sqlite::class,
'database-path' => 'hopper/'
],
'mysql' => [
'driver' => MySql::class,
'database-prefix' => 'hopper_'
],
]
...Hopper stores all Sqlite databases within a relative directory in the database directory of your application. You can configure the name of the directory in the config file:
...
'connections' => [
'sqlite' => [
'driver' => Sqlite::class,
'database-path' => 'hopper/'
],
]
...So, as you might expect, all temporary databases created by Hopper will be stored in database/hopper/. So for example, running this command...
php artisan hop test...will create a sqlite database at database/hopper/test.sqlite.
The
hopperdirectory will be created by Hopper if it doesn't already exist
All database names passed to hopper when using Sqlite will be sanitized. Slashes will be automatically converted to dashes for the Sqlite connection. So for instance,
hop this/databasewill create a database calledthis-database.sqlite
It's probably worth adding your chosen directory to your
.gitignorewhen using thesqliteconnection!
Hopper creates all MySql databases on your configured MySql connection. All databases created will have a prefix applied to their name so you can easily identify them as needed. You can configure the prefix in the config file:
...
'connections' => [
'sqlite' => [
'driver' => MySql::class,
'database-prefix' => 'hopper_'
],
]
...So for example, running this command...
php artisan hop test...will create a MySql database called hopper_test.
All database names passed to hopper when using MySql will be sanitized. Dashes will be automatically converted to underscores for the MySql connection. So for instance,
hop this-databasewill create a database calledhopper_this_database
Hopper makes it nice and easy to add your own connection for a database type this is supported by Laravel but not by Hopper.
To add your own connection, create a class that implements the Connection interface. You can refer to the existing connections to see how to build your new implementation. When you are ready to implement it, add it to the connections array:
...
'connections' => [
...
'newconnection' => [
'driver' => NewConnection::class
],
...
]
...Hopper exposes the checks it runs prior to wiring up your database connection. This way, you can alter the existing checks and/or add your own if needed. They are found in the hopper.php config file:
...
'boot-checks' => [
Environment::class
]
...The included Environment check ensures the app environment is local. To add your own, ensure your class either implements the BootCheck interface or exposes a check() method which returns a boolean. Then, pop the class name in this array and you're all set.
It is super simple to configure the steps you want to run after creating a new database.
The steps can be found in the hopper.php config file:
...
'post-creation-steps' => [
'migrate:fresh --seed'
]
...All strings included in this array must refer to an Artisan command in your app.
Closures can also be defined:
...
'post-creation-steps' => [
'migrate:fresh',
fn() => app(SpecificDatabaseSeeder::class)->run()
]
...All steps are run in order of declaration, so ensure you
migrateyour database before any seeders!
Please see CHANGELOG for more information what has changed recently.
Please see CONTRIBUTING for details.
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
The MIT License (MIT). Please see License File for more information.
This package was generated using the Laravel Package Boilerplate.