Add features/collectors

barryvdh · Dec 9, 2024 · a29e100 · a29e100
1 parent d7d0309
commit a29e100
Show file tree

Hide file tree

Showing 6 changed files with 199 additions and 49 deletions.
diff --git a/docs/collectors.md b/docs/collectors.md
@@ -0,0 +1,155 @@
+---
+hide:
+  - navigation
+---
+!!! warning
+
+    Debugbar can slow the application down (because it has to gather and render data). So when experiencing slowness, try disabling some of the collectors.
+
+## Collectors
+
+This package includes some custom collectors:
+
+- 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)
+- 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
+- LogsCollector: Show the latest log entries from the storage logs. (disabled by default)
+- FilesCollector: Show the files that are included/required by PHP. (disabled by default)
+- ConfigCollector: Display the values from the config files. (disabled by default)
+- 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)
+- 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:
+
+
+```php
+
+   /*
+     |--------------------------------------------------------------------------
+     | DataCollectors
+     |--------------------------------------------------------------------------
+     |
+     | Enable/disable DataCollectors
+     |
+     */
+
+    'collectors' => [
+        'phpinfo'         => true,  // Php version
+        'messages'        => true,  // Messages
+        'time'            => true,  // Time Datalogger
+        'memory'          => true,  // Memory usage
+        'exceptions'      => true,  // Exception displayer
+        'log'             => true,  // Logs from Monolog (merged in messages if enabled)
+        'db'              => true,  // Show database (PDO) queries and bindings
+        'views'           => true,  // Views with their data
+        'route'           => true,  // Current route information
+        'auth'            => false, // Display Laravel authentication status
+        'gate'            => false,  // Display Laravel Gate checks
+        'session'         => true,  // Display session data
+        'symfony_request' => true,  // Only one can be enabled..
+        'mail'            => false,  // Catch mail messages
+        'laravel'         => false, // Laravel version and environment
+        'events'          => false, // All events fired
+        'default_request' => false, // Regular or special Symfony request logger
+        'logs'            => false, // Add the latest log messages
+        'files'           => false, // Show the included files
+        'config'          => false, // Display config settings
+        'cache'           => false, // Display cache events
+        'models'          => false,  // Display models
+        'livewire'        => true,  // Display Livewire (when available)
+        'jobs'            => false, // Display dispatched jobs
+        'pennant'         => false, // Display Pennant feature flags
+    ],
+
+    /*
+     |--------------------------------------------------------------------------
+     | Extra options
+     |--------------------------------------------------------------------------
+     |
+     | Configure some DataCollectors
+     |
+     */
+
+    'options' => [
+        'time' => [
+            'memory_usage' => false,  // Calculated by subtracting memory start and end, it may be inaccurate
+        ],
+        'messages' => [
+            'trace' => true,   // Trace the origin of the debug message
+        ],
+        'memory' => [
+            'reset_peak' => false,     // run memory_reset_peak_usage before collecting
+            'with_baseline' => false,  // Set boot memory usage as memory peak baseline
+            'precision' => 0,          // Memory rounding precision
+        ],
+        'auth' => [
+            'show_name' => true,   // Also show the users name/email in the debugbar
+            '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
+        ],
+        '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
+            ],
+        ],
+        'route' => [
+            'label' => true,  // show complete route on bar
+        ],
+        'session' => [
+            'hiddens' => [], // hides sensitive values using array paths
+        ],
+        'symfony_request' => [
+            'hiddens' => [], // hides sensitive values using array paths, example: request_request.password
+        ],
+        'events' => [
+            'data' => false, // collect events data, listeners
+        ],
+        'logs' => [
+            'file' => null,
+        ],
+        'cache' => [
+            'values' => true, // collect cache values
+        ],
+    ],
+
+
+```
diff --git a/docs/features.md b/docs/features.md
@@ -2,39 +2,6 @@
 hide:
   - navigation
 ---
-!!! warning
-
-    Debugbar can slow the application down (because it has to gather and render data). So when experiencing slowness, try disabling some of the collectors.
-
-## Collectors
-This package includes some custom collectors:
-
-- 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)
-- 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
-- LogsCollector: Show the latest log entries from the storage logs. (disabled by default)
-- FilesCollector: Show the files that are included/required by PHP. (disabled by default)
-- ConfigCollector: Display the values from the config files. (disabled by default)
-- 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)
-- MemoryCollector
-- ExceptionsCollector
-
-It also provides a facade interface (Debugbar) for easy logging Messages, Exceptions and Time.
-
-To enable or disable any of the collectors, set the configuration to `true` or `false`. Some collector have additional options in the configuration.
-
 
 ## AJAX Requests
 

diff --git a/docs/index.md b/docs/index.md
@@ -5,3 +5,6 @@ hide:
   - navigation
   - toc 
 ---
+
+
+It also provides a facade interface (Debugbar) for easy logging Messages, Exceptions and Time.
diff --git a/docs/installation.md b/docs/installation.md
@@ -1,5 +1,6 @@
 # Installation
 
+## Install with composer
 !!! danger
 
     Use the DebugBar only in development. Do not use Debugbar on publicly accessible websites, as it will leak information from stored requests (by design).
@@ -13,10 +14,45 @@ composer require barryvdh/laravel-debugbar --dev
 
 Laravel uses Package Auto-Discovery, so doesn't require you to manually add the ServiceProvider.
 
-The Debugbar will be enabled when `APP_DEBUG` is `true`.
-
 > If you use a catch-all/fallback route, make sure you load the Debugbar ServiceProvider before your own App ServiceProviders.
 
+
+## Enable
+By default, Debugbar will be enabled when `APP_DEBUG` is `true`.
+
+
+The profiler is enabled by default, if you have APP_DEBUG=true. You can override that in the config (`debugbar.enabled`) or by setting `DEBUGBAR_ENABLED` in your `.env`. See more options in `config/debugbar.php`
+
+```php
+    /*
+     |--------------------------------------------------------------------------
+     | Debugbar Settings
+     |--------------------------------------------------------------------------
+     |
+     | Debugbar is enabled by default, when debug is set to true in app.php.
+     | You can override the value by setting enable to true or false instead of null.
+     |
+     | You can provide an array of URI's that must be ignored (eg. 'api/*')
+     |
+     */
+
+    'enabled' => env('DEBUGBAR_ENABLED', null),
+    'hide_empty_tabs' => false, // Hide tabs until they have content
+    'except' => [
+        'telescope*',
+        'horizon*',
+    ],
+
+```
+
+### Publish config
+
+```shell
+php artisan vendor:publish --provider="Barryvdh\Debugbar\ServiceProvider"
+```
+
+## Non-default installs
+
 ### Without auto-discovery
 
 If you don't use auto-discovery, add the ServiceProvider to the providers list. For Laravel 11 or newer, add the ServiceProvider in bootstrap/providers.php. For Laravel 10 or older, add the ServiceProvider in config/app.php.
@@ -35,16 +71,6 @@ public function register(): void
 }
 ```
 
-The profiler is enabled by default, if you have APP_DEBUG=true. You can override that in the config (`debugbar.enabled`) or by setting `DEBUGBAR_ENABLED` in your `.env`. See more options in `config/debugbar.php`
-You can also set in your config if you want to include/exclude the vendor files also (FontAwesome, Highlight.js and jQuery). If you already use them in your site, set it to false.
-You can also only display the js or css vendors, by setting it to 'js' or 'css'. (Highlight.js requires both css + js, so set to `true` for syntax highlighting)
-
-### Publish config
-
-```shell
-php artisan vendor:publish --provider="Barryvdh\Debugbar\ServiceProvider"
-```
-
 ### With Octane
 
 Make sure to add LaravelDebugbar to your flush list in `config/octane.php`.

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -12,6 +12,7 @@ nav:
       - Install: installation.md
       - Usage: usage.md
   - Features: features.md
+  - Collectors: collectors.md
 
 theme:
   name: material

diff --git a/overrides/home.html b/overrides/home.html
@@ -42,6 +42,8 @@ <h1>{{ config.site_description }}</h1>
                 Laravel Debugbar is a package that integrates PHP Debug Bar with Laravel. It includes a ServiceProvider to register the debugbar and attach it to the output. You can publish assets and configure it through Laravel.
             </p>
 
+            {{ super() }}
+
             <div class="mdx-hero__image">
                 <img src="img/preview.png" alt="" width="1133" height="287" draggable="false">
             </div>
@@ -55,16 +57,12 @@ <h1>{{ config.site_description }}</h1>
                     View on Github
                 </a>
 
-
             </div>
         </div>
     </div>
 </section>
 
 {% endblock %}
 
-{% block content %}
-{{ super() }}
-{% endblock %}
 
 {% block footer %}{% endblock %}
-Original file line number
+Diff line change
@@ Expand Up / @@ -5,3 +5,6 @@ hide: @@
       - navigation
       - toc
     ---
+    It also provides a facade interface (Debugbar) for easy logging Messages, Exceptions and Time.