From 7240a85f4972af3eccfe578e094f63b589785310 Mon Sep 17 00:00:00 2001 From: alexmerlin Date: Tue, 9 Apr 2024 17:16:25 +0300 Subject: [PATCH] Issue #22: Added documentation for v1. Signed-off-by: alexmerlin --- .github/workflows/continuous-integration.yml | 11 ++++ .github/workflows/cs-tests.yml | 47 -------------- .github/workflows/docs-build.yml | 16 +++++ .github/workflows/static-analysis.yml | 47 -------------- .github/workflows/unit-tests.yml | 48 --------------- .gitignore | 3 + OSSMETADATA | 2 +- README.md | 65 ++++++++++---------- SECURITY.md | 39 ++++++++++++ docs/book/index.md | 1 + docs/book/v1/installation.md | 5 ++ docs/book/v1/overview.md | 3 + docs/book/v1/setup.md | 38 ++++++++++++ docs/book/v1/usage.md | 21 +++++++ docs/book/v1/usage/debug-doctrine-queries.md | 13 ++++ docs/book/v1/usage/debug-exceptions.md | 5 ++ docs/book/v1/usage/logging-messages.md | 25 ++++++++ docs/book/v1/usage/measure-durations.md | 19 ++++++ mkdocs.yml | 24 ++++++++ 19 files changed, 257 insertions(+), 175 deletions(-) create mode 100644 .github/workflows/continuous-integration.yml delete mode 100644 .github/workflows/cs-tests.yml create mode 100644 .github/workflows/docs-build.yml delete mode 100644 .github/workflows/static-analysis.yml delete mode 100644 .github/workflows/unit-tests.yml create mode 100644 SECURITY.md create mode 100644 docs/book/index.md create mode 100644 docs/book/v1/installation.md create mode 100644 docs/book/v1/overview.md create mode 100644 docs/book/v1/setup.md create mode 100644 docs/book/v1/usage.md create mode 100644 docs/book/v1/usage/debug-doctrine-queries.md create mode 100644 docs/book/v1/usage/debug-exceptions.md create mode 100644 docs/book/v1/usage/logging-messages.md create mode 100644 docs/book/v1/usage/measure-durations.md create mode 100644 mkdocs.yml diff --git a/.github/workflows/continuous-integration.yml b/.github/workflows/continuous-integration.yml new file mode 100644 index 0000000..26c5802 --- /dev/null +++ b/.github/workflows/continuous-integration.yml @@ -0,0 +1,11 @@ +name: "Continuous Integration" + +on: + pull_request: + push: + branches: + tags: + +jobs: + ci: + uses: laminas/workflow-continuous-integration/.github/workflows/continuous-integration.yml@1.x diff --git a/.github/workflows/cs-tests.yml b/.github/workflows/cs-tests.yml deleted file mode 100644 index e8bbade..0000000 --- a/.github/workflows/cs-tests.yml +++ /dev/null @@ -1,47 +0,0 @@ -on: - - push - -name: Run phpcs checks - -jobs: - mutation: - name: PHP ${{ matrix.php }}-${{ matrix.os }} - - runs-on: ${{ matrix.os }} - - strategy: - matrix: - os: - - ubuntu-latest - - php: - - "8.1" - - "8.2" - - "8.3" - - steps: - - name: Checkout - uses: actions/checkout@v3 - - - name: Install PHP - uses: shivammathur/setup-php@v2 - with: - php-version: "${{ matrix.php }}" - tools: composer:v2, cs2pr - coverage: none - - - name: Determine composer cache directory - run: echo "COMPOSER_CACHE_DIR=$(composer config cache-dir)" >> $GITHUB_ENV - - - name: Cache dependencies installed with composer - uses: actions/cache@v3 - with: - path: ${{ env.COMPOSER_CACHE_DIR }} - key: php${{ matrix.php }}-composer-${{ hashFiles('**/composer.json') }} - restore-keys: | - php${{ matrix.php }}-composer- - - name: Install dependencies with composer - run: composer install --prefer-dist --no-interaction --no-progress --optimize-autoloader --ansi - - - name: Run phpcs checks - run: vendor/bin/phpcs diff --git a/.github/workflows/docs-build.yml b/.github/workflows/docs-build.yml new file mode 100644 index 0000000..1a7aa24 --- /dev/null +++ b/.github/workflows/docs-build.yml @@ -0,0 +1,16 @@ +name: docs-build + +on: + release: + types: [published] + workflow_dispatch: + +jobs: + build-deploy: + runs-on: ubuntu-latest + steps: + - name: Build Docs + uses: dotkernel/documentation-theme/github-actions/docs@main + env: + DEPLOY_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/static-analysis.yml b/.github/workflows/static-analysis.yml deleted file mode 100644 index 6f7452d..0000000 --- a/.github/workflows/static-analysis.yml +++ /dev/null @@ -1,47 +0,0 @@ -on: - - push - -name: Run static analysis - -jobs: - mutation: - name: PHP ${{ matrix.php }}-${{ matrix.os }} - - runs-on: ${{ matrix.os }} - - strategy: - matrix: - os: - - ubuntu-latest - - php: - - "8.1" - - "8.2" - - "8.3" - - steps: - - name: Checkout - uses: actions/checkout@v3 - - - name: Install PHP - uses: shivammathur/setup-php@v2 - with: - php-version: "${{ matrix.php }}" - tools: composer:v2, cs2pr - coverage: none - - - name: Determine composer cache directory - run: echo "COMPOSER_CACHE_DIR=$(composer config cache-dir)" >> $GITHUB_ENV - - - name: Cache dependencies installed with composer - uses: actions/cache@v3 - with: - path: ${{ env.COMPOSER_CACHE_DIR }} - key: php${{ matrix.php }}-composer-${{ hashFiles('**/composer.json') }} - restore-keys: | - php${{ matrix.php }}-composer- - - name: Install dependencies with composer - run: composer install --prefer-dist --no-interaction --no-progress --optimize-autoloader --ansi - - - name: Run static analysis - run: vendor/bin/psalm --no-cache --output-format=github --show-info=false --threads=4 diff --git a/.github/workflows/unit-tests.yml b/.github/workflows/unit-tests.yml deleted file mode 100644 index 7f5f333..0000000 --- a/.github/workflows/unit-tests.yml +++ /dev/null @@ -1,48 +0,0 @@ -on: - - push - -name: Run PHPUnit tests - -jobs: - mutation: - name: PHP ${{ matrix.php }}-${{ matrix.os }} - - runs-on: ${{ matrix.os }} - - strategy: - matrix: - os: - - ubuntu-latest - - php: - - "8.1" - - "8.2" - - "8.3" - - steps: - - name: Checkout - uses: actions/checkout@v3 - - - name: Install PHP - uses: shivammathur/setup-php@v2 - with: - php-version: "${{ matrix.php }}" - tools: composer:v2, cs2pr - coverage: none - - - name: Determine composer cache directory - run: echo "COMPOSER_CACHE_DIR=$(composer config cache-dir)" >> $GITHUB_ENV - - - name: Cache dependencies installed with composer - uses: actions/cache@v3 - with: - path: ${{ env.COMPOSER_CACHE_DIR }} - key: php${{ matrix.php }}-composer-${{ hashFiles('**/composer.json') }} - restore-keys: | - php${{ matrix.php }}-composer- - - - name: Install dependencies with composer - run: composer install --prefer-dist --no-interaction --no-progress --optimize-autoloader --ansi - - - name: Run PHPUnit tests - run: vendor/bin/phpunit --colors=always diff --git a/.gitignore b/.gitignore index 178a6df..3cfe20a 100644 --- a/.gitignore +++ b/.gitignore @@ -46,3 +46,6 @@ package-lock.json .project .buildpath .settings/ + +/documentation-theme/ +/docs/html/ diff --git a/OSSMETADATA b/OSSMETADATA index 6c7e106..b96d4a4 100644 --- a/OSSMETADATA +++ b/OSSMETADATA @@ -1 +1 @@ -osslifecycle=active \ No newline at end of file +osslifecycle=active diff --git a/README.md b/README.md index 8cd339a..084bfaf 100644 --- a/README.md +++ b/README.md @@ -15,15 +15,16 @@ DotKernel's debug bar built on top of [maximebf/php-debugbar](https://github.com [![SymfonyInsight](https://insight.symfony.com/projects/c1dc83af-a4b3-4a46-a80c-d87dff782089/big.svg)](https://insight.symfony.com/projects/c1dc83af-a4b3-4a46-a80c-d87dff782089) - ## Install + Install dot-debugbar in your application by running the following command: composer require dotkernel/dot-debugbar - ## Setup + Once installed, the following components need to be registered by adding: + * `$app->pipe(\Dot\DebugBar\Middleware\DebugBarMiddleware::class);` to `config/pipeline.php` (preferably after `ServerUrlMiddleware::class`) * `\Dot\DebugBar\ConfigProvider::class,` to `config/config.php` (preferably at the beginning of the section where the `DotKernel packages` are loaded) * `\Dot\DebugBar\Extension\DebugBarExtension::class` to `config/autoload/templates.global.php` (inside the array founder under the key `twig` => `extensions`) @@ -31,10 +32,11 @@ Once installed, the following components need to be registered by adding: Locate the library's assets directory, called `assets` and copy **its contents** to your application under `public/debugbar` directory. Locate the library's config file `config/debugbar.local.php` and clone it inside your application as: + * `config/autoload/debugbar.local.php.dist` * `config/autoload/debugbar.local.php` -By default, dot-debugbar is enabled only on the local environment, by whitelisting `127.0.0.1` in the config file, inside the array located under the `ipv4Whitelist` key. +By default, dot-debugbar is enabled only on the local environment, by whitelisting your local IP address in the config file, inside the array located under the `ipv4Whitelist` key. If you need to enable it on other environments as well, just whitelist your public IPV4 address. It can also be enabled globally, by whitelisting the string `*`. Finally, if you want to keep the whitelists but disable dot-debugbar, you can set `enabled` to **false**. @@ -44,18 +46,20 @@ For more configuration values, follow the link in the related comment block. At this step, dot-debugbar is not displayed yet. In order to display it, you need to call the following Twig functions from your base layout: + * `{{ debugBarCss()|raw }}` (needs to be placed in the head section of the layout, where the CSS files are included) * `{{ debugBarJs()|raw }}` (needs to be placed in the footer of the layout, where the JS files are included) If you plan to enable dot-debugbar on production, make sure you clear the relevant cache items by deleting: + * the config cache file: `data/cache/config-cache.php` * Twig cache directory: `data/cache/twig` Additionally, you can check if dot-debugbar is enabled for your session by calling `debugBarEnabled()` inside a template. This feature can be useful if you need to add custom logic for when dot-debugbar is enabled. - ## Usage + Other than the data being automatically collected during a session, dot-debugbar can also be used to log messages, measure durations, debug database queries and more... When you need an instance of DebugBar, locate an instance of it in your application's container using: @@ -73,61 +77,58 @@ The below examples will assume you already have an instance of DebugBar in your ### Logging messages + Results will show up in the debug bar under the `Messages` tab. Log messages (can be of any type): -```php -$this->debugBar->addMessage(1); -$this->debugBar->addMessage(true); -$this->debugBar->addMessage('foo'); -$this->debugBar->addMessage(['foo']); -$this->debugBar->addMessage(new \stdClass()); -``` + + $this->debugBar->addMessage(1); + $this->debugBar->addMessage(true); + $this->debugBar->addMessage('foo'); + $this->debugBar->addMessage(['foo']); + $this->debugBar->addMessage(new \stdClass()); Log messages and set custom label by specifying the 2nd argument (you can use any label, but `error` and `warning` use custom highlight and icons): -```php -$exception = new \Exception('something went wrong'); -$this->debugBar->addMessage($exception, 'error'); -$this->debugBar->addMessage($exception->getMessage(), 'error'); -$this->debugBar->addMessage('some warning', 'warning'); -$this->debugBar->addMessage('custom message', 'custom'); -``` + + $exception = new \Exception('something went wrong'); + $this->debugBar->addMessage($exception, 'error'); + $this->debugBar->addMessage($exception->getMessage(), 'error'); + $this->debugBar->addMessage('some warning', 'warning'); + $this->debugBar->addMessage('custom message', 'custom'); Also, clicking on a label (found on the bottom right of the debugbar) will toggle the visibility of all messages with that specific label. ### Measure durations + Results will show up in the debug bar under the `Timeline` tab. In order to measure how long does it take for a piece of code to execute, do the following: -```php -$this->debugBar->measure('long operation', function () { - // your code here -}); -``` -OR + $this->debugBar->measure('long operation', function () { + // your code here + }); -```php -$this->debugBar->startTimer('long operation', 'measuring long operation'); -// your code here -$this->debugBar->stopTimer('long operation'); -``` +OR + $this->debugBar->startTimer('long operation', 'measuring long operation'); + // your code here + $this->debugBar->stopTimer('long operation'); ### Debug Doctrine queries + Results will show up in the debug bar under the `Database` tab. By default, all queries executed in order to load a page will be logged and displayed under this tab. If you submit a form that will perform a redirect, you won't see the executed CREATE/UPDATE queries unless you stack the collected data: -```php -$this->debugBar->stackData(); -``` + + $this->debugBar->stackData(); The method needs to be called after all database operations have finished AND before emitting the redirect response. In this case, next to the `Memory usage` widget you'll see a dropdown that allows you to select between the previous page load (with the redirect) and the current one. ### Debug Exceptions + Results will show up in the debug bar under the `Exceptions` tab. By registering `Dot\DebugBar\Middleware\DebugBarMiddleware`, dot-debugbar is ready to capture Exceptions. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..c4aa91c --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,39 @@ +# Security Policy + +## Supported Versions + + +| Version | Supported | PHP Version | +|---------|--------------------|------------------------------------------------------------------------------------------------------------------------| +| 1.x | :white_check_mark: | ![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-debugbar/1.1.5) | + + +## Reporting Potential Security Issues + +If you have encountered a potential security vulnerability in this project, +please report it to us at . We will work with you to +verify the vulnerability and patch it. + +When reporting issues, please provide the following information: + +- Component(s) affected +- A description indicating how to reproduce the issue +- A summary of the security vulnerability and impact + +We request that you contact us via the email address above and give the +project contributors a chance to resolve the vulnerability and issue a new +release prior to any public exposure; this helps protect the project's +users, and provides them with a chance to upgrade and/or update in order to +protect their applications. + + +## Policy + +If we verify a reported security vulnerability, our policy is: + +- We will patch the current release branch, as well as the immediate prior minor + release branch. + +- After patching the release branches, we will immediately issue new security + fix releases for each patched release branch. + diff --git a/docs/book/index.md b/docs/book/index.md new file mode 100644 index 0000000..ae42a26 --- /dev/null +++ b/docs/book/index.md @@ -0,0 +1 @@ +../../README.md diff --git a/docs/book/v1/installation.md b/docs/book/v1/installation.md new file mode 100644 index 0000000..9331c94 --- /dev/null +++ b/docs/book/v1/installation.md @@ -0,0 +1,5 @@ +# Installation + +Install `dotkernel/dot-debugbar` by executing the following Composer command: + + composer require dotkernel/dot-debugbar diff --git a/docs/book/v1/overview.md b/docs/book/v1/overview.md new file mode 100644 index 0000000..5443a37 --- /dev/null +++ b/docs/book/v1/overview.md @@ -0,0 +1,3 @@ +# Overview + +DotKernel's debug bar built on top of [maximebf/php-debugbar](https://github.com/maximebf/php-debugbar). diff --git a/docs/book/v1/setup.md b/docs/book/v1/setup.md new file mode 100644 index 0000000..79325e0 --- /dev/null +++ b/docs/book/v1/setup.md @@ -0,0 +1,38 @@ +# Setup + +Once installed, the following components need to be registered by adding: + +* `$app->pipe(\Dot\DebugBar\Middleware\DebugBarMiddleware::class);` to `config/pipeline.php` (preferably after `ServerUrlMiddleware::class`) +* `\Dot\DebugBar\ConfigProvider::class,` to `config/config.php` (preferably at the beginning of the section where the `DotKernel packages` are loaded) +* `\Dot\DebugBar\Extension\DebugBarExtension::class` to `config/autoload/templates.global.php` (inside the array founder under the key `twig` => `extensions`) + +Locate the library's assets directory, called `assets` and copy **its contents** to your application under `public/debugbar` directory. + +Locate the library's config file `config/debugbar.local.php` and clone it inside your application as: + +* `config/autoload/debugbar.local.php.dist` +* `config/autoload/debugbar.local.php` + +By default, dot-debugbar is enabled only on the local environment, by whitelisting your local IP address in the config file, inside the array located under the `ipv4Whitelist` key. + +If you need to enable it on other environments as well, just whitelist your public IPV4 address. + +It can also be enabled globally, by whitelisting the string `*`. + +Finally, if you want to keep the whitelists but disable dot-debugbar, you can set `enabled` to **false**. + +Inside the config file, you will find additional configurations under the `javascript_renderer` key. +For more configuration values, follow the link in the related comment block. + +At this step, dot-debugbar is not displayed yet. In order to display it, you need to call the following Twig functions from your base layout: + +* `{{ debugBarCss()|raw }}` (needs to be placed in the head section of the layout, where the CSS files are included) +* `{{ debugBarJs()|raw }}` (needs to be placed in the footer of the layout, where the JS files are included) + +If you plan to enable dot-debugbar on production, make sure you clear the relevant cache items by deleting: + +* the config cache file: `data/cache/config-cache.php` +* Twig cache directory: `data/cache/twig` + +Additionally, you can check if dot-debugbar is enabled for your session by calling `debugBarEnabled()` inside a template. +This feature can be useful if you need to add custom logic for when dot-debugbar is enabled. diff --git a/docs/book/v1/usage.md b/docs/book/v1/usage.md new file mode 100644 index 0000000..5088bd2 --- /dev/null +++ b/docs/book/v1/usage.md @@ -0,0 +1,21 @@ +# Usage + +Other than the data being automatically collected during a session, dot-debugbar can also be used to log messages, measure durations, debug database queries and more... + +When you need an instance of DebugBar, locate an instance of it in your application's container using: + + $debugBar = $container->get(\Dot\DebugBar\DebugBar::class); + +then your factory can inject `$debugBar` as a dependency in your class. + +OR + +If you are using [dot-annotated-services](https://github.com/dotkernel/dot-annotated-services) inject it directly in your class's constructor. + +Once an instance of DebugBar has been injected in your code, you can access all its features. +The below examples will assume you already have an instance of DebugBar in your code, and it's callable using `$this->debugBar`: + +* [Logging messages](usage/logging-messages.md) +* [Measure durations](usage/measure-durations.md) +* [Debug Doctrine queries](usage/debug-doctrine-queries.md) +* [Debug Exceptions](usage/debug-exceptions.md) diff --git a/docs/book/v1/usage/debug-doctrine-queries.md b/docs/book/v1/usage/debug-doctrine-queries.md new file mode 100644 index 0000000..3ec9c77 --- /dev/null +++ b/docs/book/v1/usage/debug-doctrine-queries.md @@ -0,0 +1,13 @@ +# Debug Doctrine queries + +Results will show up in the debug bar under the `Database` tab. + +By default, all queries executed in order to load a page will be logged and displayed under this tab. +If you submit a form that will perform a redirect, you won't see the executed CREATE/UPDATE queries unless you stack the collected data: + +```php + $this->debugBar->stackData(); +``` + +The method needs to be called after all database operations have finished AND before emitting the redirect response. +In this case, next to the `Memory usage` widget you'll see a dropdown that allows you to select between the previous page load (with the redirect) and the current one. diff --git a/docs/book/v1/usage/debug-exceptions.md b/docs/book/v1/usage/debug-exceptions.md new file mode 100644 index 0000000..b624255 --- /dev/null +++ b/docs/book/v1/usage/debug-exceptions.md @@ -0,0 +1,5 @@ +# Debug Exceptions + +Results will show up in the debug bar under the `Exceptions` tab. + +By registering `Dot\DebugBar\Middleware\DebugBarMiddleware`, dot-debugbar is ready to capture Exceptions. diff --git a/docs/book/v1/usage/logging-messages.md b/docs/book/v1/usage/logging-messages.md new file mode 100644 index 0000000..1c33a06 --- /dev/null +++ b/docs/book/v1/usage/logging-messages.md @@ -0,0 +1,25 @@ +# Logging messages + +Results will show up in the debug bar under the `Messages` tab. + +Log messages (can be of any type): + +```php + $this->debugBar->addMessage(1); + $this->debugBar->addMessage(true); + $this->debugBar->addMessage('foo'); + $this->debugBar->addMessage(['foo']); + $this->debugBar->addMessage(new \stdClass()); +``` + +Log messages and set custom label by specifying the 2nd argument (you can use any label, but `error` and `warning` use custom highlight and icons): + +```php + $exception = new \Exception('something went wrong'); + $this->debugBar->addMessage($exception, 'error'); + $this->debugBar->addMessage($exception->getMessage(), 'error'); + $this->debugBar->addMessage('some warning', 'warning'); + $this->debugBar->addMessage('custom message', 'custom'); +``` + +Also, clicking on a label (found on the bottom right of the debugbar) will toggle the visibility of all messages with that specific label. diff --git a/docs/book/v1/usage/measure-durations.md b/docs/book/v1/usage/measure-durations.md new file mode 100644 index 0000000..bb0884a --- /dev/null +++ b/docs/book/v1/usage/measure-durations.md @@ -0,0 +1,19 @@ +# Measure durations + +Results will show up in the debug bar under the `Timeline` tab. + +In order to measure how long does it take for a piece of code to execute, do the following: + +```php + $this->debugBar->measure('long operation', function () { + // your code here + }); +``` + +OR + +```php + $this->debugBar->startTimer('long operation', 'measuring long operation'); + // your code here + $this->debugBar->stopTimer('long operation'); +``` diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..d2aba71 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,24 @@ +docs_dir: docs/book +site_dir: docs/html +extra: + project: Packages + current_version: v1 + versions: + - v1 +nav: + - Home: index.md + - v5: + - Overview: v1/overview.md + - Installation: v1/installation.md + - Setup: v1/setup.md + - Usage: + - Overview: v1/usage.md + - "Logging messages": v1/usage/logging-messages.md + - "Measure durations": v1/usage/measure-durations.md + - "Debug Doctrine queries": v1/usage/debug-doctrine-queries.md + - "Debug Exceptions": v1/usage/debug-exceptions.md +site_name: dot-annotated-services +site_description: "DotKernel's debug bar component" +repo_url: "https://github.com/dotkernel/dot-debugbar" +plugins: + - search