PHPackages spatie/laravel-sql-commenter - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Database & ORM](/categories/database) 4. / 5. spatie/laravel-sql-commenter ActiveLibrary[Database & ORM](/categories/database) spatie/laravel-sql-commenter ============================ Add comments to SQL queries made by Laravel 2.2.0(2mo ago)1931.4M↑31.8%12[1 PRs](https://github.com/spatie/laravel-sql-commenter/pulls)1MITPHPPHP ^8.4CI passing Since Jul 2Pushed 1mo ago3 watchersCompare [ Source](https://github.com/spatie/laravel-sql-commenter)[ Packagist](https://packagist.org/packages/spatie/laravel-sql-commenter)[ Docs](https://github.com/spatie/laravel-sql-commenter)[ RSS](/packages/spatie-laravel-sql-commenter/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (10)Dependencies (25)Versions (19)Used By (1) Add comments to SQL queries made by Laravel =========================================== [](#add-comments-to-sql-queries-made-by-laravel) [![Latest Version on Packagist](https://camo.githubusercontent.com/efc281c85f394b2cb3c1c937bc1b000ebd8562d92f48748e7e6a68c8352bd1a5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7370617469652f6c61726176656c2d73716c2d636f6d6d656e7465722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spatie/laravel-sql-commenter)[![GitHub Tests Action Status](https://camo.githubusercontent.com/e2dd576fa1080d47fd0a7b9b30c94637b3da44c13115c8846e0f45f6d6dda43a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f776f726b666c6f772f7374617475732f7370617469652f6c61726176656c2d73716c2d636f6d6d656e7465722f72756e2d74657374733f6c6162656c3d7465737473)](https://github.com/spatie/laravel-sql-commenter/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/0c676bf12ce51a058ad46cb6f95fd257e4d340dcad49f889a2de0d2089e2f6fd/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f776f726b666c6f772f7374617475732f7370617469652f6c61726176656c2d73716c2d636f6d6d656e7465722f436865636b253230262532306669782532307374796c696e673f6c6162656c3d636f64652532307374796c65)](https://github.com/spatie/laravel-sql-commenter/actions?query=workflow%3A%22Check+%26+fix+styling%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/8590f17a4147a05fff60c99ca7188c33e11ec39d014d2e43abeb52a912e181bd/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7370617469652f6c61726176656c2d73716c2d636f6d6d656e7465722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spatie/laravel-sql-commenter) This package can add comments to queries performed by Laravel. These comments will use the [sqlcommenter](https://google.github.io/sqlcommenter/) format, which is understood by various tools and services, such as [PlanetScale's Query Insights](https://docs.planetscale.com/concepts/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 ---------- [](#support-us) [![](https://camo.githubusercontent.com/b3f5de7569b818a88f10bd822efd26dc89ca1c034ddc71f8956c71d592587af8/68747470733a2f2f6769746875622d6164732e73332e65752d63656e7472616c2d312e616d617a6f6e6177732e636f6d2f6c61726176656c2d73716c2d636f6d6d656e7465722e6a70673f743d31)](https://spatie.be/github-ad-click/laravel-sql-commenter) We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us). 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](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards). Installation ------------ [](#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 ----- [](#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 [](#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 [](#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 [](#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|null */ public function comments(string $query, Connection $connection): Comment|array|null { return new Comment('my-custom-key', 'my-custom-value'); } } ``` Testing ------- [](#testing) ``` composer test ``` Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. Contributing ------------ [](#contributing) Please see [CONTRIBUTING](https://github.com/riasvdv/.github/blob/main/CONTRIBUTING.md) for details. Security Vulnerabilities ------------------------ [](#security-vulnerabilities) Please review [our security policy](../../security/policy) on how to report security vulnerabilities. Credits ------- [](#credits) - [Rias Van der Veken](https://github.com/riasvdv) - [Freek Van der Herten](https://github.com/freekmurze) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 65 — FairBetter than 99% of packages Maintenance88 Actively maintained with recent releases Popularity57 Moderate usage in the ecosystem Community24 Small or concentrated contributor base Maturity74 Established project with proven stability Bus Factor1 Top contributor holds 55% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~103 days Recently: every ~242 days Total 14 Last Release 73d ago Major Versions 0.0.3 → 1.0.02022-07-02 1.4.0 → 2.0.02024-03-14 PHP version history (2 changes)0.0.1PHP ^8.1 2.2.0PHP ^8.4 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/7535935?v=4)[Spatie](/maintainers/spatie)[@spatie](https://github.com/spatie) --- Top Contributors [![freekmurze](https://avatars.githubusercontent.com/u/483853?v=4)](https://github.com/freekmurze "freekmurze (88 commits)")[![riasvdv](https://avatars.githubusercontent.com/u/3626559?v=4)](https://github.com/riasvdv "riasvdv (30 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (17 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (10 commits)")[![laravel-shift](https://avatars.githubusercontent.com/u/15991828?v=4)](https://github.com/laravel-shift "laravel-shift (3 commits)")[![Nielsvanpach](https://avatars.githubusercontent.com/u/10651054?v=4)](https://github.com/Nielsvanpach "Nielsvanpach (3 commits)")[![vigneshgurusamy](https://avatars.githubusercontent.com/u/6076800?v=4)](https://github.com/vigneshgurusamy "vigneshgurusamy (2 commits)")[![AlexVanderbist](https://avatars.githubusercontent.com/u/6287961?v=4)](https://github.com/AlexVanderbist "AlexVanderbist (2 commits)")[![shuvroroy](https://avatars.githubusercontent.com/u/21066418?v=4)](https://github.com/shuvroroy "shuvroroy (2 commits)")[![jholloman](https://avatars.githubusercontent.com/u/1514824?v=4)](https://github.com/jholloman "jholloman (1 commits)")[![alexthekiwi](https://avatars.githubusercontent.com/u/38124722?v=4)](https://github.com/alexthekiwi "alexthekiwi (1 commits)")[![peresmishnyk](https://avatars.githubusercontent.com/u/1893866?v=4)](https://github.com/peresmishnyk "peresmishnyk (1 commits)") --- Tags laravelperformancephpsqlspatielaravelsqlcommentersql-commenter ### Code Quality TestsPest ### Embed Badge ![Health badge](/badges/spatie-laravel-sql-commenter/health.svg) ``` [![Health](https://phpackages.com/badges/spatie-laravel-sql-commenter/health.svg)](https://phpackages.com/packages/spatie-laravel-sql-commenter) ``` ### Alternatives [spatie/laravel-backup A Laravel package to backup your application 6.0k21.8M191](/packages/spatie-laravel-backup)[spatie/laravel-model-flags Add flags to Eloquent models 4301.1M1](/packages/spatie-laravel-model-flags)[spatie/laravel-deleted-models Automatically copy deleted records to a separate table 409109.8k4](/packages/spatie-laravel-deleted-models)[dyrynda/laravel-model-uuid This package allows you to easily work with UUIDs in your Laravel models. 4802.8M8](/packages/dyrynda-laravel-model-uuid)[clickbar/laravel-magellan This package provides functionality for working with the postgis extension in Laravel. 423715.4k1](/packages/clickbar-laravel-magellan)[wnx/laravel-backup-restore A package to restore database backups made with spatie/laravel-backup. 203330.1k2](/packages/wnx-laravel-backup-restore) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)