README

Eloquent SQL dumper

This Laravel package introduces simple service for dumping SQL with binded values.

This repository originated from my personal blog, and aims to briefly explain advantages of Laravel's Illuminate\Support\Traits\Macroable.

Features

Delivered Haru0\EloquentSqlDumper\ServiceProvider registers a dump macro on Illuminate\Database\Query\Builder which then could be then used for logging and debugging.

Although, you will be fine, I strongly discourage you from using this library on production for logging purposes. I believe it's not the proper way for this, and you should seek for dedicated logging solution.

Installation

composer require --dev haru0/eloquent-sql-dumper

This package supports package-discovery and can be used straight away after adding to the Composer's dependencies.

If your project disables package-discovery feature, it is necessary to manually register Haru0\EloquentSqlDumper\ServiceProvider. This can be done by adding this line below, inside config/app.php file.

/*
 * Package Service Providers...
 */
Haru0\EloquentSqlDumper\ServiceProvider::class,

No configuration options available.

Usage

Haru0\EloquentSqlDumper\Services\DumperService, once registered, can be basically used anywhere. It is also easily overrideable and extensible.

Example routes/web.php file:

use Illuminate\Database\Query\Builder;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Route;

Route::get('/', function () {
    $query = DB::query()
        ->from('users')
        ->where('active', true)
        ->where(function (Builder $builder) {
            $builder
                ->orWhere('email', 'like', '%gmail.com')
                ->orWhere('email', 'like', '%example.com');
        })
        ->orderByDesc('id')
        ->limit(10);

    dd($query->dump());
});

Tinker version, for REPL lovers:

Psy Shell v0.9.9 (PHP 7.3.2-3+ubuntu18.04.1+deb.sury.org+1 — cli) by Justin Hileman
>>> DB::query() \
...     ->from('users') \
...     ->where('active', true) \
...     ->where(function ($builder) { \
...         $builder \
...             ->orWhere('email', 'like', '%gmail.com') \
...             ->orWhere('email', 'like', '%example.com'); \
...     }) \
...     ->orderByDesc('id') \
...     ->limit(10) \
...     ->dump()
=> "select * from `users` where `active` = 1 and (`email` like '%gmail.com' or `email` like '%example.com') order by `id` desc limit 10"

Overriding and extending

If you need to adjust or override Haru0\EloquentSqlDumper\Services\DumperService functionality, you're welcome to either bind implementation to the contract, or register listener to the two events dispatched by the service.

Depending on your needs, one of the ways of customizing dump macro, is to write your own DumperService and bind it to the Haru0\EloquentSqlDumper\Contracts\DumperContract.

use App\Services\MyDumper;
use Haru0\EloquentSqlDumper\Contracts\DumperContract;

$this->app->bind(DumperContract::class, MyDumper::class);

Other way of customizing dump macro is to register a listener or subscriber to the Haru0\EloquentSqlDumper\Events\AfterDumpEvent and Haru0\EloquentSqlDumper\Events\BeforeDumpEvent events.

Finally, you can modify macro name (in case it collides with existing one). To do so, adjust configuration option or put ELOQUENT_SQL_DUMPER_MACRO environment variable into your .env file.

ELOQUENT_SQL_DUMPER_MACRO=foo_bar_baz

You can change that environment by overriding configuration file. Do do so, you need to publish package configuration file php artisan vendor:publish --provider=Haru0\EloquentSqlDumper\ServiceProvider.

Then, use it the same way dump was shown in the Usage chapter.

Macro name is always casted to Camel case. In this example above, your macro will be executed by $query->fooBarBaz.

Contribute

Any contribution is welcome. Fork this repository and create a pull request. Please remember to provide brief description.

Here you can find all contributors.

License

MIT