{"id":19324877,"url":"https://github.com/spatie/laravel-sql-commenter","last_synced_at":"2025-05-15T08:00:20.685Z","repository":{"id":41435578,"uuid":"509192298","full_name":"spatie/laravel-sql-commenter","owner":"spatie","description":"Add comments to SQL queries made by Laravel","archived":false,"fork":false,"pushed_at":"2025-05-12T01:39:43.000Z","size":120,"stargazers_count":186,"open_issues_count":0,"forks_count":11,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-12T02:38:14.146Z","etag":null,"topics":["laravel","performance","php","sql"],"latest_commit_sha":null,"homepage":"https://freek.dev/2279-add-comments-to-sql-queries-made-by-laravel","language":"PHP","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spatie.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-06-30T18:30:57.000Z","updated_at":"2025-05-12T01:39:40.000Z","dependencies_parsed_at":"2024-04-29T02:37:19.189Z","dependency_job_id":"bfd3d251-ae50-4f38-99cc-48e985110b58","html_url":"https://github.com/spatie/laravel-sql-commenter","commit_stats":{"total_commits":94,"total_committers":7,"mean_commits":"13.428571428571429","dds":0.5212765957446808,"last_synced_commit":"faacbe26e2b8ea2af73b1035b2daa39cd99a6952"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":"spatie/package-skeleton-laravel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Flaravel-sql-commenter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Flaravel-sql-commenter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Flaravel-sql-commenter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Flaravel-sql-commenter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spatie","download_url":"https://codeload.github.com/spatie/laravel-sql-commenter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253665402,"owners_count":21944613,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["laravel","performance","php","sql"],"created_at":"2024-11-10T02:07:19.000Z","updated_at":"2025-05-15T08:00:18.137Z","avatar_url":"https://github.com/spatie.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Add comments to SQL queries made by Laravel\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/spatie/laravel-sql-commenter.svg?style=flat-square)](https://packagist.org/packages/spatie/laravel-sql-commenter)\n[![GitHub Tests Action Status](https://img.shields.io/github/workflow/status/spatie/laravel-sql-commenter/run-tests?label=tests)](https://github.com/spatie/laravel-sql-commenter/actions?query=workflow%3Arun-tests+branch%3Amain)\n[![GitHub Code Style Action Status](https://img.shields.io/github/workflow/status/spatie/laravel-sql-commenter/Check%20\u0026%20fix%20styling?label=code%20style)](https://github.com/spatie/laravel-sql-commenter/actions?query=workflow%3A\"Check+%26+fix+styling\"+branch%3Amain)\n[![Total Downloads](https://img.shields.io/packagist/dt/spatie/laravel-sql-commenter.svg?style=flat-square)](https://packagist.org/packages/spatie/laravel-sql-commenter)\n\nThis 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).\n\nHere's what a query looks like by default:\n\n```mysql\nselect * from users\n```\n\nUsing this package, comments like this one will be added.\n\n```mysql\nselect * from \"users\"/*controller='UsersController',action='index'*/;\n```\n\nThe comments allow you easily pinpoint the source of the query in your codebase.\n\n\n## Support us\n\n[\u003cimg src=\"https://github-ads.s3.eu-central-1.amazonaws.com/laravel-sql-commenter.jpg?t=1\" width=\"419px\" /\u003e](https://spatie.be/github-ad-click/laravel-sql-commenter)\n\nWe 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).\n\nWe 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).\n\n## Installation\n\nYou can install the package via composer:\n\n```bash\ncomposer require spatie/laravel-sql-commenter\n```\n\nOptionally, you can publish the config file with:\n\n```bash\nphp artisan vendor:publish --tag=\"sql-commenter-config\"\n```\n\nThis is the content of the published config file:\n\n```php\nreturn [\n    /*\n     * When set to true, comments will be added to all your queries\n     */\n    'enabled' =\u003e true,\n\n    /*\n     * These classes add comments to an executed query.\n     */\n    'commenters' =\u003e [\n        Spatie\\SqlCommenter\\Commenters\\ControllerCommenter::class =\u003e ['includeNamespace' =\u003e false],\n        Spatie\\SqlCommenter\\Commenters\\RouteCommenter::class,\n        Spatie\\SqlCommenter\\Commenters\\JobCommenter::class =\u003e ['includeNamespace' =\u003e false],\n        Spatie\\SqlCommenter\\Commenters\\FileCommenter::class =\u003e [\n            'backtraceLimit' =\u003e 20, \n            'excludePathSegments' =\u003e [],\n            'useRelativePath' =\u003e false,\n        ],\n        Spatie\\SqlCommenter\\Commenters\\CurrentUserCommenter::class,\n        // Spatie\\SqlCommenter\\Commenters\\FrameworkVersionCommenter::class,\n        // Spatie\\SqlCommenter\\Commenters\\DbDriverCommenter::class,\n    ],\n\n    /*\n     * If you need fine-grained control over the logging, you can extend\n     * the SqlCommenter class and specify your custom class here\n     */\n    'commenter_class' =\u003e Spatie\\SqlCommenter\\SqlCommenter::class,\n];\n```\n\n## Usage\n\nWith the package installed, comments are automatically added. By publishing the config file, you can choose which things are added to the comments.\n\n### Adding arbitrary comments\n\nIf 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.\n\n```php\nuse Spatie\\SqlCommenter\\SqlCommenter;\n\napp(SqlCommenter::class)-\u003eaddComment('foo', 'bar');\n\n// select * from \"users\"/*foo='bar'*/;\n```\n\n### Dynamically enabling and disabling adding comments\n\nYou can dynamically enable and disable query logging. \n\nLet'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()`\n\n```php\nuse \\Spatie\\SqlCommenter\\SqlCommenter;\n\n// queries performed here won't have comments\n\nSqlCommenter::enable();\n\n// queries performed here will have comments\n\nSqlCommenter::disable();\n\n// queries performed here won't have comments\n```\n\n### Adding you own commentator\n\nIf 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`.\n\nHere's an example:\n\n```php\nnamespace App\\Support\\SqlCommenters;\n\nuse Illuminate\\Database\\Connection;\nuse Spatie\\SqlCommenter\\Comment;\n\nclass MyCustomCommenter implements Commenter\n{\n    /** @return Comment|array\u003cComment\u003e|null */\n    public function comments(string $query, Connection $connection): Comment|array|null\n    {\n        return new Comment('my-custom-key',  'my-custom-value');\n    }\n}\n```\n\n## Testing\n\n```bash\ncomposer test\n```\n\n## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.\n\n## Contributing\n\nPlease see [CONTRIBUTING](https://github.com/riasvdv/.github/blob/main/CONTRIBUTING.md) for details.\n\n## Security Vulnerabilities\n\nPlease review [our security policy](../../security/policy) on how to report security vulnerabilities.\n\n## Credits\n\n- [Rias Van der Veken](https://github.com/riasvdv)\n- [Freek Van der Herten](https://github.com/freekmurze)\n- [All Contributors](../../contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspatie%2Flaravel-sql-commenter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspatie%2Flaravel-sql-commenter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspatie%2Flaravel-sql-commenter/lists"}