billy210504 / mongodb-commenter

v1.0.0 2026-10-27 09:18 UTC

Requires

• php: ^8.4
• illuminate/contracts: ^11.0||^12.0||^13.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.14
• nunomaduro/collision: ^8.8
• orchestra/testbench: ^11.0.0||^10.0.0||^9.0.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-arch: ^4.0
• pestphp/pest-plugin-laravel: ^4.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0
• spatie/laravel-ray: ^1.35

MIT

• Billy

• laravel
• Billy
• mongodb-commenter

Published on Packagist.org on 2026-10-27 09:20 UTC

README

MongoDB Commenter automatically attaches SQLCommenter-style contextual metadata (such as controller, action, route, user, artisan command, and application name) to your MongoDB Eloquent queries in Laravel.

This allows database administrators and monitoring tools (like MongoDB Atlas Profiler, DataDog, and APM) to trace queries back to the exact code location and user context that triggered them.

Features

• ⚡ Seamless Integration: Simply add the HasComments trait to your MongoDB Eloquent models.
• 🏷️ Contextual Metadata: Automatically captures controller, action, route, user, command, and app_name.
• 🔀 Invokable & Closure Support: Accurately labels invokable controllers (__invoke) and closures.
• 🎯 Configurable Tags: Toggle specific metadata on or off via configuration or .env variables.
• 📋 Deterministic Order: Query comments are sorted alphabetically following the SQLCommenter specification.

Installation

You can install the package via Composer:

composer require billy210504/mongodb-commenter

Publish and set up the configuration file using the install command:

php artisan mongodb-commenter:install

Or publish the config file directly:

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

Configuration

The published configuration file is located at config/mongodb-commenter.php:

return [
    /*
    |--------------------------------------------------------------------------
    | Enable/Disable MongoDB Query Commenter
    |--------------------------------------------------------------------------
    */
    'enabled' => env('MONGO_COMMENTER_ENABLED', true),

    /*
    |--------------------------------------------------------------------------
    | Custom Application Name (Optional)
    |--------------------------------------------------------------------------
    | If null, it will default to config('app.name').
    */
    'app_name' => env('MONGO_COMMENTER_APP_NAME', null),

    /*
    |--------------------------------------------------------------------------
    | Included Comment Metadata Tags
    |--------------------------------------------------------------------------
    */
    'include_app_name' => env('MONGO_COMMENTER_INCLUDE_APP_NAME', true),
    'include_controller' => env('MONGO_COMMENTER_CONTROLLER', true),
    'include_route' => env('MONGO_COMMENTER_ROUTE', true),
    'include_user' => env('MONGO_COMMENTER_USER', true),
    'include_command' => env('MONGO_COMMENTER_COMMAND', true),
];

Usage

1. Attach HasComments to Your MongoDB Models

Add the HasComments trait to any of your MongoDB Eloquent models:

namespace App\Models;

use Billy\MongodbCommenter\Traits\HasComments;
use MongoDB\Laravel\Eloquent\Model;

class Product extends Model
{
    use HasComments;

    protected $connection = 'mongodb';
    protected $collection = 'products';

    protected $fillable = [
        'name',
        'price',
        'stock',
    ];
}

2. Output Query Comment Examples

A. Web / API Request

When running a query inside an HTTP request (e.g. GET /api/products handled by ProductController@index):

$products = Product::where('stock', '>', 0)->get();

The MongoDB query will execute with the following comment attached:

action='index',app_name='Laravel',controller='ProductController',route='products.index',user='10482'

B. Artisan Console Command

When executing queries inside an Artisan command (e.g. php artisan sync:products):

$products = Product::all();

The MongoDB query comment will look like:

app_name='Laravel',command='sync:products'

Testing

Run the test suite using Pest:

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

• Billy
• Syahreza-Ferdian
• All Contributors

License

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