Download the PHP package code-distortion/swap-con without Composer

SwapCon

code-distortion/swap-con is a Laravel package that gives you control over which database to use and when to change.

Example:

In fact, SwapCon lets you change broadcasting, cache, filesystem, logging and queue connections as well.

Have you ever wanted to change database connections at runtime in Laravel but found it difficult?

You may have tried some of these methods but found them limiting:

SwapCon is an alternative to these methods.

Installation

Install the package via composer:

Service provider & facade registration

SwapCon integrates with Laravel 5.5+ automatically thanks to Laravel's package auto-detection. For Laravel 5.0 - 5.4, add the following lines to config/app.php:

Config file

Use the following command to publish the config/code-distortion.swapcon.php config file:

Usage

SwapCon makes the SwapCon facade available to use.

There are two main ways to change connections. You may run a callback while swapping the default database connection (which replaces the original connection back again afterwards), or you may use a new connection moving forward.

By changing the default connection, your code will start interacting with this new connection without having to micro-manage it.

Note: The swap methods will catch and re-throw exceptions, making sure to replace the original connection back again so you don't have to. This is the safest way to alternate between connections.

You can also simply change the default database to use:

You can manage the other connection types too using these methods:

This might be all the functionality you need. Below are details on how to take SwapCon further.

Custom connections

Imagine a situation where you want to connect to a read-only replicated database in specific parts of your code. Perhaps you'd like to offload some heavy queries to free up your read/write database.

You could start by adding a second connection to configs/database.php:

And swapping to this on the fly:

However your local development environment might not have a replicated database like there is in production.

SwapCon lets you to define custom connections arbitrarily from your .env file, allowing you choose which connections to define in different environments, if at all.

Specify values for your new connections in your .env file with the format:

SWAPCON_<CONNECTION-TYPE>_<CONNECTION-NAME>_<SETTING-NAME>=value

("CONNECTION-TYPE" is one of: BROADCASTING, CACHE, DATABASE, FILESYSTEMS, LOGGING orQUEUE).

You can also choose to clone an existing connection's settings, and override specific values (like the database name or host).

eg. Below the new 'mysql-ro1' connection will take the existing 'mysql' connection settings, but override the database to connect to:

This doesn't give much extra functionality yet over adding the connection to the config file directly. However you can take it a step further with connection groups…

Connection groups

You can group several connections together using connection groups. Define groups in your .env file using the format:

SWAPCON_GROUP_<CONNECTION-TYPE>_<GROUP-NAME>=<connections>

(where "CONNECTION-TYPE" is one of: BROADCASTING, CACHE, DATABASE, FILESYSTEMS, LOGGING or QUEUE).

eg.

Now you suddenly have 3 database connections ready for read-only access, and can refer to them using the name 'mysql-ro'.

When SwapCon finds a group, it will pick a connection from it randomly. If this group is used again it will continue to use the same connection it chose before. In this example SwapCon may end up choosing the 'mysql-ro2' connection.

Note: SwapCon won't enforce the read-only-ness of a database connection.

Fallback connections

Now, if you have some of these read-only databases in production for example but not locally in your development environment, the above code will generate an exception for you because you haven't defined the 'mysql-ro' connection or group.

This is where fallback connections come in. You can specify in config/code-distortion.swapcon.php fallback connections to use when they can't be found.

Here you can specify a connection to simply reuse when needed. In this example the 'mysql' connection will continue being used unless a 'mysql-ro' connection or group exist in the current .env file.

Alternately you can choose a connection to clone when needed. If the line above is uncommented, the 'mysql' connection details will be cloned and a separate new connection will be made to that same database (unless a 'mysql-ro' connection or group exist in the current .env file).

NOTE: As a rule of thumb you should add a fallback for each connection you refer to by name in your code. This will save exceptions from occurring when the connections can't be resolved.

Altering the available connections on the fly

Sometimes you need to change connection settings from within your code. For example you may wish to do this if you have a website that connects to different databases, one for each client. Your code would need to first run to work out which client is needed, and then pick their database connection.

You can alter connections:

Alternatively you can update a connection that already exists:

Note: The purpose of this library is to help you manage connections, it doesn't help manage the tenancy choosing process. You will need to determine the tenant database to use yourself.

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

SemVer

This library uses SemVer 2.0.0 versioning. This means that changes to X indicate a breaking change: 0.0.X, 0.X.y, X.y.z. When this library changes to version 1.0.0, 2.0.0 and so forth it doesn't indicate that it's necessarily a notable release, it simply indicates that the changes were breaking.

Treeware

This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.

Contributing

Please see CONTRIBUTING for details.

Code of conduct

Please see CODE_OF_CONDUCT for details.

Security

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

Credits

• Tim Chandler

License

The MIT License (MIT). Please see License File for more information.

PHP Package Boilerplate

This package was generated using the PHP Package Boilerplate.