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.
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.
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,
];
With the package installed, comments are automatically added. By publishing the config file, you can choose which things are added to the 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;
SqlCommenter::addComment('foo', 'bar');
// select * from "users"/*foo='bar'*/;
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
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');
}
}
composer test
Please see CHANGELOG for more information on what has changed recently.
Please see CONTRIBUTING for details.
Please review our security policy on how to report security vulnerabilities.
The MIT License (MIT). Please see License File for more information.