From a29e100c16907ea41da0c331afdcd6333d6e2925 Mon Sep 17 00:00:00 2001 From: "Barry vd. Heuvel" Date: Mon, 9 Dec 2024 11:11:36 +0100 Subject: [PATCH] Add features/collectors --- docs/collectors.md | 155 +++++++++++++++++++++++++++++++++++++++++++ docs/features.md | 33 --------- docs/index.md | 3 + docs/installation.md | 50 ++++++++++---- mkdocs.yml | 1 + overrides/home.html | 6 +- 6 files changed, 199 insertions(+), 49 deletions(-) create mode 100644 docs/collectors.md diff --git a/docs/collectors.md b/docs/collectors.md new file mode 100644 index 00000000..8db899ff --- /dev/null +++ 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 + ], + ], + + +``` \ No newline at end of file diff --git a/docs/features.md b/docs/features.md index d15d63a4..6afb29fa 100644 --- 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 index 1d0eef9e..4d4e4e85 100644 --- 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. \ No newline at end of file diff --git a/docs/installation.md b/docs/installation.md index bb9b5440..25e410c2 100644 --- 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 index 794e2a3f..c84609a4 100644 --- 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 index 745d2016..5d10462e 100644 --- a/overrides/home.html +++ b/overrides/home.html @@ -42,6 +42,8 @@

{{ config.site_description }}

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.

+ {{ super() }} +
@@ -55,7 +57,6 @@

{{ config.site_description }}

View on Github - @@ -63,8 +64,5 @@

{{ config.site_description }}

{% endblock %} -{% block content %} -{{ super() }} -{% endblock %} {% block footer %}{% endblock %} \ No newline at end of file