PHPackages reinanhs/sqlcommenter-hyperf - 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. [Logging & Monitoring](/categories/logging) 4. / 5. reinanhs/sqlcommenter-hyperf ActiveLibrary[Logging & Monitoring](/categories/logging) reinanhs/sqlcommenter-hyperf ============================ SQLCommenter implementation for Hyperf. SQLCommenter is a set of tools that augments SQL Statements with comments containing information about the code that caused its execution. These information can be action, controller, framework, db\_driver and opentelemetry traceparent. v1.0.2(1y ago)348Apache-2.0PHPPHP >=8.1 Since Jun 11Pushed 1y agoCompare [ Source](https://github.com/ReinanHS/sqlcommenter-hyperf)[ Packagist](https://packagist.org/packages/reinanhs/sqlcommenter-hyperf)[ Docs](https://github.com/reinanhs/sqlcommenter-hyperf)[ RSS](/packages/reinanhs-sqlcommenter-hyperf/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (6)Dependencies (8)Versions (8)Used By (0) English | [Português](./README-PT.md) | [中文](./README-CN.md) [![Sqlcommenter Logo](https://camo.githubusercontent.com/33f0daa5ecc9cd2bd065d06b8c59dad6d1cb81b333ae0c4b6a7e466c35a2fea3/68747470733a2f2f692e696d6775722e636f6d2f706b6379594c552e706e67)](https://google.github.io/sqlcommenter/) [![Stable Version](https://camo.githubusercontent.com/0bc855306a74b3cb3b93770b626fc9907ff232d4a969da9de60fc66c69f11c1e/68747470733a2f2f706f7365722e707567782e6f72672f7265696e616e68732f73716c636f6d6d656e7465722d6879706572662f762f737461626c65)](https://github.com/reinanhs/sqlcommenter-hyperf/releases) [![Php Version](https://camo.githubusercontent.com/c3a80c86d7355ce233d937cc6ce506d4f9b1f34a91fb4b52d2d725a3bef932d0/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d2533453d382e312d627269676874677265656e2e7376673f6d61784167653d32353932303030)](https://www.php.net) [![Total Downloads](https://camo.githubusercontent.com/83c230e8cbf954cd754c01a9ae685709581c177f702811b68cfea9c2ac112515/68747470733a2f2f706f7365722e707567782e6f72672f7265696e616e68732f73716c636f6d6d656e7465722d6879706572662f646f776e6c6f616473)](https://packagist.org/packages/reinanhs/sqlcommenter-hyperf) [![Sqlcommenter License](https://camo.githubusercontent.com/7c4d46c9a65e084646963e27f8896fe64cd9cff70a782bb05fe9798c1143c1f6/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f7265696e616e68732f73716c636f6d6d656e7465722d6879706572662e7376673f6d61784167653d32353932303030)](https://github.com/reinanhs/sqlcommenter-hyperf/blob/main/LICENSE) Introduction ------------ [](#introduction) Sqlcommenter Hyperf is a library designed to automatically add comments to SQL queries executed by the [Hyperf](https://github.com/hyperf/hyperf) framework. These comments use the [sqlcommenter](https://google.github.io/sqlcommenter/) format, which is understood by various database tools and services, providing enhanced insights and traceability for your application's database interactions. Installation ------------ [](#installation) You can install the library via Composer: ``` composer require reinanhs/sqlcommenter-hyperf ``` Add component configuration: ``` php bin/hyperf.php vendor:publish reinanhs/sqlcommenter-hyperf ``` Sample ------ [](#sample) See an example of a simple query being executed: ``` select * from users ``` Using this package, comments like this will be added: ``` select * from users /*framework='Hyperf', application='hyperf-skeleton', controller='UserController', action='index', route='%%2Fapi%%2Ftest', db_driver='mysql', traceparent='00-1cd60708968a61e942b5dacc2d4a5473-7534abe7ed36ce35-01'*/ ``` By examining the above SQL statement and its comment in `/*...*/`, we can correlate and identify the fields in the SQL query to our source code in Hyperf: > Table 1: Information about the description of each type of comment ORIGINAL FIELDINTERPRETATION**framework**='Hyperf'The word “Hyperf” represents the framework that generated the query.**application**='hyperf-skeleton'The name of the project where the code was run.**controller**='UserController'Controller name in `app/Controller`.**action**='index'Name of the method that was called called by the controller.**route**='%%2Fapi%%2Ftest'The route used during the query call.**db\_driver**='mysql'The name of the Hyperf database engine.**traceparent**='00-1cd60708968a61e942b5dacc2d4a5473-7534abe7ed36ce35-01'The [W3C TraceContext Traceparent](https://www.w3.org/TR/trace-context/#traceparent-field) field of the OpenTelemetry trace.Various tools and services can interpret these comments, helping to correlate user code with SQL statements generated by the ORM, and can be examined in the database server logs. This provides better observability into your application state up to the database server. Here is an example of how this information appears within [Google Cloud SQL](https://cloud.google.com/sql/docs/postgres/using-query-insights): [![SQLcommenter example on GCP](.github/assets/cloud-sql-query-insights-view-1.png)](.github/assets/cloud-sql-query-insights-view-1.png) The image above illustrates how sqlcommenter information is mapped within Google Cloud. In this context, sqlcommenter is being used to add tags in Query Insights, making it easier to identify which part of the application code is causing performance problems. By clicking on one of these tags you will be able to view detailed information about the queries. See the example below: [![SQLcommenter example on GCP](.github/assets/cloud-sql-query-insights-view-2.png)](.github/assets/cloud-sql-query-insights-view-2.png) In addition to **Cloud SQL**, several other tools also support *sqlcommenter*. One example is the [Planetscale Query Insights](https://planetscale.com/docs/concepts/query-insights). Trace ----- [](#trace) By using the sqlcommenter-hyperf library, you can link Cloud SQL Query trace information with your Hyperf project. By synchronizing your information, you will achieve a much more detailed level of traceability than what is provided by Hyperf by default. Below is a comparison between two images showing the trace information of the standard SQL in Hyperf and the trace from Cloud SQL Query: The image below exemplifies the standard SQL trace in Hyperf: [![Standard SQL trace in Hyperf](.github/assets/standard-sql-trace-in-hyperf.png)](.github/assets/standard-sql-trace-in-hyperf.png) The image below exemplifies the Cloud SQL trace associated with a request in Hyperf: [![Cloud SQL trace in Hyperf](.github/assets/cloud-sql-trace-in-hyperf.png)](.github/assets/cloud-sql-trace-in-hyperf.png) A tip when using the sqlcommenter-hyperf library is to disable the default SQL trace in Hyperf, as you will get more detailed information through the Cloud SQL Query trace in GCP. Config ------ [](#config) When you install the library in your project, it will be automatically enabled through the default settings. Therefore, to use this library, you only need to have it installed in your project. However, if you want to disable some comments, you can do so through the settings. It is also worth mentioning that you can completely disable the execution of this library in a specific environment through the settings. With the settings below, you can enable or disable the comments generated by this library. By default, all comments are enabled. You will find this configuration in the `config/autoload/sqlcommenter.php` file: ``` 'enable' => env('SQLCOMMENTER_ENABLE', true), 'include' => [ 'framework' => env('SQLCOMMENTER_ENABLE_FRAMEWORK', true), 'controller' => env('SQLCOMMENTER_ENABLE_CONTROLLER', true), 'action' => env('SQLCOMMENTER_ENABLE_ACTION', true), 'route' => env('SQLCOMMENTER_ENABLE_ROUTE', true), 'application' => env('SQLCOMMENTER_ENABLE_APPLICATION', true), 'db_driver' => env('SQLCOMMENTER_ENABLE_DB_DRIVER', true), ], ``` See below for a detailed explanation of each of the settings: SettingTypeDefaultDescription`enable`Boolean`true`Controls whether SQLCommenter is enabled or disabled. Set to `true` to enable SQLCommenter and add comments to SQL queries.`include.framework`Boolean`true`Includes the name of the framework used in the SQL comments.`include.controller`Boolean`true`Includes the name of the controller responsible for the action that generated the SQL query.`include.action`Boolean`true`Includes the name of the action or method within the controller that generated the SQL query.`include.route`Boolean`true`Includes the route associated with the request that generated the SQL query.`include.application`Boolean`true`Includes the name of the application in the SQL comments.`include.db_driver`Boolean`true`Includes the name of the database driver used to execute the SQL query.Features -------- [](#features) - Automatically adds sqlcommenter-compatible comments to SQL queries. - Provides better traceability and insights into database interactions. - Easy integration with the Hyperf framework. - Supports multiple database drivers. Performance ----------- [](#performance) Using the Sqlcommenter Hyperf library may introduce a small performance impact due to the addition of comments to SQL queries. However, the benefits in terms of traceability, ease of debugging, and integration with monitoring tools generally outweigh this impact. To demonstrate the effectiveness of the Sqlcommenter Hyperf library, we will conduct two distinct tests. The measurement will be performed in a controlled Google Cloud Run environment with the following configurations: - CPU always allocated - Minimum number of instances: 1 - Maximum number of instances: 1 - Memory per instance: 1GB - Number of vCPUs per instance: 1vCPU - Maximum concurrent requests per instance: 1000 See below the project that was used as experiment: - [sample-sqlcommenter-hyperf-poc](https://github.com/ReinanHS/sample-sqlcommenter-hyperf-poc) ### Average execution time test of the code block: [](#average-execution-time-test-of-the-code-block) In this test, we will measure the average execution time of the SqlCommenterAspect code block that adds SQL comments. After collecting 10,000 execution time records for this operation, we calculated the average execution time, which was approximately **0.103 milliseconds (ms)**. This value indicates that inserting SQL comments into queries is an extremely fast operation, adding negligible overhead to the total query execution time. - [Complete documentation regarding the average execution time test of the code block](https://github.com/ReinanHS/sqlcommenter-hyperf/wiki/Performance#performance-analysis-of-the-code-block-in-the-library) ### Request latency performance test [](#request-latency-performance-test) In this test, we will use K6 to make multiple requests and compare the performance with the library enabled and disabled. See the results of this experiment below: [![Performance with Configuration Enabled vs Disabled](.github/assets/performance-configuration-chart.png)](.github/assets/performance-configuration-chart.png) When analyzing the above image, we can see that initially, the response times are very similar for both configurations. However, as CPU consumption increases and we approach the limit of 1 vCPU, the disabled configuration (False) starts to perform slightly better. By examining the CPU utilization graphs, we observed that at around 400 VUs, CPU usage was approximately 98% for both configurations. When the library is not competing intensely for CPU usage, it manages to maintain very good performance, close to that of the disabled configuration. This suggests that under high-demand conditions, the disabled configuration can handle the load slightly better, resulting in a marginal increase in the number of requests served per second. If you want to check the detailed information about the test, it is recommended to click the link below: - [Complete documentation regarding the request latency performance test](https://github.com/ReinanHS/sqlcommenter-hyperf/wiki/Performance#request-latency-performance-test) Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information about what has changed recently. Contributing ------------ [](#contributing) Do you want to be part of this project? Read [how to contribute](CONTRIBUTING.md). Security Vulnerabilities ------------------------ [](#security-vulnerabilities) Please review [our security policy](https://github.com/reinanhs/sqlcommenter-hyperf/security/policy) on how to report security vulnerabilities. ### License [](#license) This project is under license. See the [LICENSE](LICENSE) file for more details. ### Health Score 29 — LowBetter than 59% of packages Maintenance33 Infrequent updates — may be unmaintained Popularity13 Limited adoption so far Community6 Small or concentrated contributor base Maturity54 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% 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 ~7 days Total 6 Last Release 670d ago Major Versions v0.2.2 → v1.0.02024-07-13 ### Community Maintainers ![](https://www.gravatar.com/avatar/865f82155fc78f89cd36eae5d5a51551e94ef09c19997076424d46c21040b2b5?d=identicon)[ReinanHS](/maintainers/ReinanHS) --- Top Contributors [![ReinanHS](https://avatars.githubusercontent.com/u/28494067?v=4)](https://github.com/ReinanHS "ReinanHS (27 commits)") --- Tags hyperfopentelemetryphpsqlcommenterphphyperfsqlcommenter ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/reinanhs-sqlcommenter-hyperf/health.svg) ``` [![Health](https://phpackages.com/badges/reinanhs-sqlcommenter-hyperf/health.svg)](https://phpackages.com/packages/reinanhs-sqlcommenter-hyperf) ``` ### Alternatives [friendsofhyperf/sentry The sentry component for Hyperf. 1864.6k](/packages/friendsofhyperf-sentry) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)