diff --git a/.github/workflows/continous-integration.yml b/.github/workflows/continous-integration.yml new file mode 100644 index 0000000..26c5802 --- /dev/null +++ b/.github/workflows/continous-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 e73dfcf..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 update --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 e9de91d..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 update --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/README.md b/README.md index 745e5e4..9da7076 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,5 @@ # dot-flashmessenger - ![OSS Lifecycle](https://img.shields.io/osslifecycle/dotkernel/dot-flashmessenger) ![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-flashmessenger/3.4.2) @@ -9,35 +8,31 @@ [![GitHub stars](https://img.shields.io/github/stars/dotkernel/dot-flashmessenger)](https://github.com/dotkernel/dot-flashmessenger/stargazers) [![GitHub license](https://img.shields.io/github/license/dotkernel/dot-flashmessenger)](https://github.com/dotkernel/dot-flashmessenger/blob/3.0/LICENSE.md) -[![Build Static](https://github.com/dotkernel/dot-flashmessenger/actions/workflows/static-analysis.yml/badge.svg?branch=3.0)](https://github.com/dotkernel/dot-flashmessenger/actions/workflows/static-analysis.yml) +[![Build Static](https://github.com/dotkernel/dot-flashmessenger/actions/workflows/continuous-integration.yml/badge.svg?branch=3.0)](https://github.com/dotkernel/dot-flashmessenger/actions/workflows/continuous-integration.yml) [![codecov](https://codecov.io/gh/dotkernel/dot-flashmessenger/graph/badge.svg?token=B4WAT3RYKJ)](https://codecov.io/gh/dotkernel/dot-flashmessenger) [![SymfonyInsight](https://insight.symfony.com/projects/94ace687-5124-446f-a324-0ecca1b47f88/big.svg)](https://insight.symfony.com/projects/94ace687-5124-446f-a324-0ecca1b47f88) - -Flash messenger library for session messages between redirects. A flash message, or session message is a piece of text data that survives one requests(available only in the next request). +Flash messenger library for session messages between redirects. A flash message, or session message is a piece of text data that survives one requests(available only in the next request). This library accepts session data as well, not just string messages, with the same behaviour. The flash messenger is a convenient way to add data to the session and get it back on the next request without bothering with setting and clearing the data manually. ## Installation Run the following command in your project folder -```bash -$ composer require dotkernel/dot-flashmessenger -``` + + composer require dotkernel/dot-flashmessenger This will also install `laminas/laminas-session` as session handling is based on this library. Next, merge the `ConfigProvider` to your application's configuration ## Configuration -```php -return [ - 'dot_flashmessenger' => [ - 'namespace' => 'flash messeges session namespace name' - ], -]; -``` + return [ + 'dot_flashmessenger' => [ + 'namespace' => 'flash messages session namespace name' + ], + ]; Sets the session namespace to use for all flash messages and data @@ -46,75 +41,71 @@ Sets the session namespace to use for all flash messages and data If following the installation step, you'll already have a FlashMessenger service in the service manager. Just inject this service in you classes, wherever you need flash messages. -##### Getting the service in a factory -```php -$container->get(FlashMessengerInterface::class); -``` +### Getting the service in a factory + + $container->get(FlashMessengerInterface::class); + +### Using the flash messenger service -##### Using the flash messenger service To add and retrieve text messages -```php -$this->flashMessenger->addMessage('error', 'This is a error flash message'); -//on the next request you can get all messages from a namespace, or all messages from all namespaces if namespace is omitted -$this->flashMessenger->getMessages('error'); -``` + $this->flashMessenger->addMessage('error', 'This is a error flash message'); + + //on the next request you can get all messages from a namespace, or all messages from all namespaces if namespace is omitted + $this->flashMessenger->getMessages('error'); Adding general data, not just messages, has a different method for that, accepting data as key/value pairs -```php -$this->flashMessenger->addData('myData', $someData); -//next request -$this->flashMessenger->getData('myData'); -``` + $this->flashMessenger->addData('myData', $someData); + + // next request + $this->flashMessenger->getData('myData'); There are also some predefined namespaces, along with shortcuts to add a message in the predefined namespaces -```php -FlashMessengerInterface::ERROR_NAMESPACE -FlashMessengerInterface::WARNING_NAMESPACE -FlashMessengerInterface::INFO_NAMESPACE -FlashMessengerInterface::SUCCESS_NAMESPACE -``` - -```php -/** - * @param string $error - * @return void - */ -public function addError($error); -/** - * @param string $info - * @return void - */ -public function addInfo($info); -/** - * @param string $warning - * @return void - */ -public function addWarning($warning); -/** - * @param string $success - * @return void - */ -public function addSuccess($success); -``` + + FlashMessengerInterface::ERROR_NAMESPACE + FlashMessengerInterface::WARNING_NAMESPACE + FlashMessengerInterface::INFO_NAMESPACE + FlashMessengerInterface::SUCCESS_NAMESPACE + +using the methods: + + /** + * @param string $error + * @return void + */ + public function addError($error); + + /** + * @param string $info + * @return void + */ + public function addInfo($info); + + /** + * @param string $warning + * @return void + */ + public function addWarning($warning); + + /** + * @param string $success + * @return void + */ + public function addSuccess($success); ## FlashMessengerRenderer -A class that is able to parse the content of the flash messenger service in an HTML format. +A class that is able to parse the content of the flash messenger service in an HTML format. It uses the TemplateInterface to parse a partial, sending to the partial template the messages, the service and the renderer itself. There are also a twig extension provided in [dot-twigrenderer](https://github.com/dotkernel/dot-twigrenderer), for easy parsing of messages blocks. ## Registered services -```php -Dot\FlashMessenger\FlashMessengerInterface::class -``` + Dot\FlashMessenger\FlashMessengerInterface::class The flash messenger service -```php -Dot\FlashMessenger\View\RendererInterface::class -``` + Dot\FlashMessenger\View\RendererInterface::class The registered renderer class diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..062564a --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,39 @@ +# Security Policy + +## Supported Versions + + +| Version | Supported | PHP Version | +|---------|--------------------|------------------------------------------------------------------------------------------------------------------------| +| 3.x | :white_check_mark: | ![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-flashmessenger/3.4.2) | +| <= 2.x | :x: | | + + +## 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. \ No newline at end of file diff --git a/docs/book/index.md b/docs/book/index.md new file mode 100644 index 0000000..fe84005 --- /dev/null +++ b/docs/book/index.md @@ -0,0 +1 @@ +../../README.md \ No newline at end of file diff --git a/docs/book/v3/configuration.md b/docs/book/v3/configuration.md new file mode 100644 index 0000000..68dfed0 --- /dev/null +++ b/docs/book/v3/configuration.md @@ -0,0 +1,17 @@ +# Configuration + +After installation, merge the `ConfigProvider` to your application's configuration + +```php +Dot\FlashMessenger\ConfigProvider::class, +``` + +Set the session namespace to use for all flash messages and data + +```php +return [ + 'dot_flashmessenger' => [ + 'namespace' => 'flash messages session namespace name' + ], +]; +``` diff --git a/docs/book/v3/installation.md b/docs/book/v3/installation.md new file mode 100644 index 0000000..24d99a8 --- /dev/null +++ b/docs/book/v3/installation.md @@ -0,0 +1,7 @@ +# Installation + +Run the following command in your project folder + + composer require dotkernel/dot-flashmessenger + +This will also install `laminas/laminas-session` as session handling is based on this library. diff --git a/docs/book/v3/overview.md b/docs/book/v3/overview.md new file mode 100644 index 0000000..42f9fbb --- /dev/null +++ b/docs/book/v3/overview.md @@ -0,0 +1,9 @@ +# Overview + +`dot-flashmessenger` is a library for session messages, between redirects. + +A flash message, or session message is a piece of text data that survives one requests(available only in the next request). + +This library accepts session data as well, not just string messages, with the same behaviour. + +The flash messenger is a convenient way to add data to the session and get it back on the next request without bothering with setting and clearing the data manually. diff --git a/docs/book/v3/renderer.md b/docs/book/v3/renderer.md new file mode 100644 index 0000000..db7012d --- /dev/null +++ b/docs/book/v3/renderer.md @@ -0,0 +1,39 @@ +# Renderer + +A class that is able to parse the content of the flash messenger service in an HTML format. +It uses the TemplateInterface to parse a partial, sending to the partial template the messages, the service and the renderer itself. +There are also a twig extension provided in [dot-twigrenderer](https://github.com/dotkernel/dot-twigrenderer), for easy parsing of messages blocks. + +Partial template example: + +```twig +{% set classes = {'error': 'danger', 'info': 'info', 'warning': 'warning', 'success' : 'success'} %} +{% if dismissible is not defined %} + {% set dismissible = false %} +{% endif %} + +{% if messages is defined and messages is iterable %} + {% for namespace in messages|keys %} + {% if classes[namespace] is defined %} + + + {% endif %} + {% endfor %} +{% endif %} +``` diff --git a/docs/book/v3/usage.md b/docs/book/v3/usage.md new file mode 100644 index 0000000..52fdee4 --- /dev/null +++ b/docs/book/v3/usage.md @@ -0,0 +1,55 @@ +# Usage + +If following the installation step, you'll already have a FlashMessenger service in the service manager. +Just inject this service in you classes, wherever you need flash messages. + +## Using the flash messenger service + +To add and retrieve text messages + +```php +$this->flashMessenger->addMessage('error', 'This is a error flash message'); + +//on the next request you can get all messages from a namespace, or all messages from all namespaces if namespace is omitted +$this->flashMessenger->getMessages('error'); +``` + +Adding general data, not just messages, has a different method for that, accepting data as key/value pairs + +```php +$this->flashMessenger->addData('myData', $someData); + +//next request +$this->flashMessenger->getData('myData'); +``` + +There are also some predefined namespaces, along with shortcuts to add a message in the predefined namespaces + +```php +FlashMessengerInterface::ERROR_NAMESPACE +FlashMessengerInterface::WARNING_NAMESPACE +FlashMessengerInterface::INFO_NAMESPACE +FlashMessengerInterface::SUCCESS_NAMESPACE +``` + +```php +public function addError(string|array $error, string $channel = FlashMessengerInterface::DEFAULT_CHANNEL): void +{ + $this->addMessage(FlashMessengerInterface::ERROR, $error, $channel); +} + +public function addWarning(string|array $warning, string $channel = FlashMessengerInterface::DEFAULT_CHANNEL): void +{ + $this->addMessage(FlashMessengerInterface::WARNING, $warning, $channel); +} + +public function addInfo(string|array $info, string $channel = FlashMessengerInterface::DEFAULT_CHANNEL): void +{ + $this->addMessage(FlashMessengerInterface::INFO, $info, $channel); +} + +public function addSuccess(string|array $success, string $channel = FlashMessengerInterface::DEFAULT_CHANNEL): void +{ + $this->addMessage(FlashMessengerInterface::SUCCESS, $success, $channel); +} +``` diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..b917205 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,20 @@ +docs_dir: docs/book +site_dir: docs/html +extra: + project: Packages + current_version: v3 + versions: + - v3 +nav: + - Home: index.md + - v3: + - Overview: v3/overview.md + - Installation: v3/installation.md + - Configuration: v3/configuration.md + - Usage: v3/usage.md + - Renderer: v3/renderer.md +site_name: dot-flashmessenger +site_description: "DotKernel's one time session message" +repo_url: "https://github.com/dotkernel/dot-flashmessenger" +plugins: + - search