README.md

Add comments to SQL queries made by Laravel

This package can add comments to queries performed by Laravel. These comments will use the sqlcommenter format, which is understood by various tools and services, such as PlanetScale's Query Insights.

Here's what a query looks like by default:

select * from users

Using this package, comments like this one will be added.

select * from "users"/*controller='UsersController',action='index'*/;

The comments allow you easily pinpoint the source of the query in your codebase.

Support us

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

Installation

You can install the package via composer:

composer require spatie/laravel-sql-commenter

Optionally, you can publish the config file with:

php artisan vendor:publish --tag="sql-commenter-config"

This is the content of the published config file:

return [
    /*
     * When set to true, comments will be added to all your queries
     */
    'enabled' => true,

    /*
     * These classes add comments to an executed query.
     */
    'commenters' => [
        Spatie\SqlCommenter\Commenters\ControllerCommenter::class => ['includeNamespace' => false],
        Spatie\SqlCommenter\Commenters\RouteCommenter::class,
        Spatie\SqlCommenter\Commenters\JobCommenter::class => ['includeNamespace' => false],
        Spatie\SqlCommenter\Commenters\FileCommenter::class => [
            'backtraceLimit' => 20, 
            'excludePathSegments' => [],
            'useRelativePath' => false,
        ],
        Spatie\SqlCommenter\Commenters\CurrentUserCommenter::class,
        // Spatie\SqlCommenter\Commenters\FrameworkVersionCommenter::class,
        // Spatie\SqlCommenter\Commenters\DbDriverCommenter::class,
    ],

    /*
     * If you need fine-grained control over the logging, you can extend
     * the SqlCommenter class and specify your custom class here
     */
    'commenter_class' => Spatie\SqlCommenter\SqlCommenter::class,
];

Usage

With the package installed, comments are automatically added. By publishing the config file, you can choose which things are added to the comments.

Adding arbitrary comments

If you want to add other arbitrary comments to the SqlComment, you can use the addComment method. The given comment will be added to the next performed query.

use Spatie\SqlCommenter\SqlCommenter;

app(SqlCommenter::class)->addComment('foo', 'bar');

// select * from "users"/*foo='bar'*/;

Dynamically enabling and disabling adding comments

You can dynamically enable and disable query logging.

Let's assume that you only want to add comments for a certain part in your code base. First, you would need to set the value of the enabled key in the sql-commenter config file to false. This will stop the package from adding comments to all queries. Right before the part where you want to add comments, call SqlCommenter::enable() and at the end call SqlCommenter::disable()

use \Spatie\SqlCommenter\SqlCommenter;

// queries performed here won't have comments

SqlCommenter::enable();

// queries performed here will have comments

SqlCommenter::disable();

// queries performed here won't have comments

Adding you own commentator

If you want to add a comment to all performed queries, you can create your own Commentator class. It should implement the Spatie\SqlCommenter\Commenters\Commenter interface. The comments function should return a single or an array of Spatie\SqlCommenter\Comment.

Here's an example:

namespace App\Support\SqlCommenters;

use Illuminate\Database\Connection;
use Spatie\SqlCommenter\Comment;

class MyCustomCommenter implements Commenter
{
    /** @return Comment|array<Comment>|null */
    public function comments(string $query, Connection $connection): Comment|array|null
    {
        return new Comment('my-custom-key',  'my-custom-value');
    }
}

Testing

composer test

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Rias Van der Veken
• Freek Van der Herten
• All Contributors

License

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