Add extra info to collectors

barryvdh · Dec 9, 2024 · 92e4915 · 92e4915
1 parent de98c24
commit 92e4915
Show file tree

Hide file tree

Showing 6 changed files with 108 additions and 29 deletions.
diff --git a/docs/collectors.md b/docs/collectors.md
@@ -10,9 +10,9 @@ hide:
 
 This package includes some custom collectors:
 
-- QueryCollector: Show all queries, including binding + timing
+- [QueryCollector](#querycollector): Show all queries, including binding + timing
 - RouteCollector: Show information about the current Route.
-- ViewCollector: Show the currently loaded views. (Optionally: display the shared data)
+- [ViewCollector](#viewcollector): Show the currently loaded views. (Optionally: display the shared data)
 - EventsCollector: Show all events
 - LaravelCollector: Show the Laravel version and Environment. (disabled by default)
 - SymfonyRequestCollector: replaces the RequestCollector with more information about the request/response
@@ -22,19 +22,22 @@ This package includes some custom collectors:
 - CacheCollector: Display all cache events. (disabled by default)
 
 Bootstraps the following collectors for Laravel:
+
 - LogCollector: Show all Log messages
 - SymfonyMailCollector for Mail
 
 And the default collectors:
+
 - PhpInfoCollector
 - MessagesCollector
-- TimeDataCollector (With Booting and Application timing)
+- [TimeDataCollector](#timeline-collector) (With Booting and Application timing)
 - MemoryCollector
 - ExceptionsCollector
 
 
 To enable or disable any of the collectors, set the configuration to `true` or `false`. Some collector have additional options in the configuration:
 
+<details><summary>debugbar.php</summary>
 
 ```php
 
@@ -75,7 +78,97 @@ To enable or disable any of the collectors, set the configuration to `true` or `
         'pennant'         => false, // Display Pennant feature flags
     ],
 
-    /*
+
+
+
+```
+
+</details>
+
+### QueryCollector
+
+The Query Collector has the following features
+ - Show the executed queries including timing
+ - Show/mark duplicate queries
+ - Show used parameters
+ - Run on-demand 'EXPLAIN' queries and link to Visual Explain  (disabled bu default)
+ - Copy the query to clipboard
+ - Show the source of the query and open in editor
+ - Visualize the duration of the queries with bottom border
+ - Add queries to the timeline (disabled by default)
+ - Limit the number of queries to avoid slowing down the Debugbar.
+ - Exclude paths (eg. for session or vendors)
+ - Show memory usage (disabled by default)
+
+![Query Collector](img/queries.png)
+
+```php
+  'options' => [
+        // ...
+        'db' => [
+            'with_params'       => true,   // Render SQL with the parameters substituted
+            'exclude_paths'     => [       // Paths to exclude entirely from the collector
+                // 'vendor/laravel/framework/src/Illuminate/Session', // Exclude sessions queries
+            ],
+            'backtrace'         => true,   // Use a backtrace to find the origin of the query in your files.
+            'backtrace_exclude_paths' => [],   // Paths to exclude from backtrace. (in addition to defaults)
+            'timeline'          => false,  // Add the queries to the timeline
+            'duration_background'  => true,   // Show shaded background on each query relative to how long it took to execute.
+            'explain' => [                 // Show EXPLAIN output on queries
+                'enabled' => false,
+            ],
+            'hints'             => false,   // Show hints for common mistakes
+            'show_copy'         => true,    // Show copy button next to the query,
+            'slow_threshold'    => false,   // Only track queries that last longer than this time in ms
+            'memory_usage'      => false,   // Show queries memory usage
+            'soft_limit'       => 100,      // After the soft limit, no parameters/backtrace are captured
+            'hard_limit'       => 500,      // After the hard limit, queries are ignored
+        ],
+        // ...
+    ],
+```
+
+### Timeline Collector
+
+![Timeline Collector](img/timeline.png)
+
+```php
+    'options' => [
+        'time' => [
+            'memory_usage' => false,  // Calculated by subtracting memory start and end, it may be inaccurate
+        ],
+    ]
+```
+
+### ViewCollector
+
+The ViewCollector shows views and has the following features:
+
+ - Show used templates and source
+ - Optionally add them to the timeline
+ - Group similar views (useful for components)
+ - Exclude folders (eg. for Filament or other vendors)
+ - Optionally show data (this can be resource heavy)
+
+![ViewCollector](img/views.png)
+
+```php
+    'options' => [
+        'views' => [
+            'timeline' => false,    // Add the views to the timeline (Experimental)
+            'data' => false,        //true for all data, 'keys' for only names, false for no parameters.
+            'group' => 50,          // Group duplicate views. Pass value to auto-group, or true/false to force
+            'exclude_paths' => [    // Add the paths which you don't want to appear in the views
+                'vendor/filament'   // Exclude Filament components by default
+            ],
+        ],
+    ]
+
+```
+## Additional options
+
+```php
+/*
      |--------------------------------------------------------------------------
      | Extra options
      |--------------------------------------------------------------------------
@@ -86,7 +179,7 @@ To enable or disable any of the collectors, set the configuration to `true` or `
 
     'options' => [
         'time' => [
-            'memory_usage' => false,  // Calculated by subtracting memory start and end, it may be inaccurate
+            // See above
         ],
         'messages' => [
             'trace' => true,   // Trace the origin of the debug message
@@ -101,35 +194,14 @@ To enable or disable any of the collectors, set the configuration to `true` or `
             'show_guards' => true, // Show the guards that are used
         ],
         'db' => [
-            'with_params'       => true,   // Render SQL with the parameters substituted
-            'exclude_paths'     => [       // Paths to exclude entirely from the collector
-                'vendor/laravel/framework/src/Illuminate/Session', // Exclude sessions queries
-            ],
-            'backtrace'         => true,   // Use a backtrace to find the origin of the query in your files.
-            'backtrace_exclude_paths' => [],   // Paths to exclude from backtrace. (in addition to defaults)
-            'timeline'          => false,  // Add the queries to the timeline
-            'duration_background'  => true,   // Show shaded background on each query relative to how long it took to execute.
-            'explain' => [                 // Show EXPLAIN output on queries
-                'enabled' => false,
-            ],
-            'hints'             => false,   // Show hints for common mistakes
-            'show_copy'         => true,    // Show copy button next to the query,
-            'slow_threshold'    => false,   // Only track queries that last longer than this time in ms
-            'memory_usage'      => false,   // Show queries memory usage
-            'soft_limit'       => 100,      // After the soft limit, no parameters/backtrace are captured
-            'hard_limit'       => 500,      // After the hard limit, queries are ignored
+            // See above        
         ],
         'mail' => [
             'timeline' => false,  // Add mails to the timeline
             'show_body' => true,
         ],
         'views' => [
-            'timeline' => false,    // Add the views to the timeline (Experimental)
-            'data' => false,        //true for all data, 'keys' for only names, false for no parameters.
-            'group' => 50,          // Group duplicate views. Pass value to auto-group, or true/false to force
-            'exclude_paths' => [    // Add the paths which you don't want to appear in the views
-                'vendor/filament'   // Exclude Filament components by default
-            ],
+            // See above
         ],
         'route' => [
             'label' => true,  // show complete route on bar
@@ -151,5 +223,4 @@ To enable or disable any of the collectors, set the configuration to `true` or `
         ],
     ],
 
-
 ```
diff --git a/docs/img/queries.png b/docs/img/queries.png
diff --git a/docs/img/timeline.png b/docs/img/timeline.png
diff --git a/docs/img/views.png b/docs/img/views.png
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -56,6 +56,7 @@ markdown_extensions:
   - pymdownx.inlinehilite
   - pymdownx.snippets
   - pymdownx.superfences
+  - pymdownx.details
   - toc:
       permalink: true
   - pymdownx.magiclink:
@@ -68,3 +69,6 @@ extra:
   analytics:
     provider: google
     property: G-KVHB3EWT91
+
+watch:
+  - overrides
diff --git a/overrides/home.html b/overrides/home.html
@@ -57,6 +57,10 @@ <h1>{{ config.site_description }}</h1>
                     View on Github
                 </a>
 
+                <div class="admonition tip">
+                    <p class="admonition-title">Live demo</p>
+                    <p>See an interactive example of the Laravel Debugbar in action below. <i>(Don't worry, this is just dummy data)</i></p>
+                </div>
             </div>
         </div>
     </div>