Merge pull request #18 from tattersoftware/release

Prep for Release

Author: MGatner

README.md

@@ -1,23 +1,25 @@
 # Tatter\Alerts
 Lightweight user alerts for CodeIgniter 4
 
-[![](https://github.com/tattersoftware/codeigniter4-alerts/workflows/PHPUnit/badge.svg)](https://github.com/tattersoftware/codeigniter4-alerts/actions?query=workflow%3A%22PHPUnit)
-[![](https://github.com/tattersoftware/codeigniter4-alerts/workflows/PHPStan/badge.svg)](https://github.com/tattersoftware/codeigniter4-alerts/actions?query=workflow%3A%22PHPStan)
+[![](https://github.com/tattersoftware/codeigniter4-alerts/workflows/PHPUnit/badge.svg)](https://github.com/tattersoftware/codeigniter4-alerts/actions/workflows/test.yml)
+[![](https://github.com/tattersoftware/codeigniter4-alerts/workflows/PHPStan/badge.svg)](https://github.com/tattersoftware/codeigniter4-alerts/actions/workflows/analyze.yml)
+[![](https://github.com/tattersoftware/codeigniter4-alerts/workflows/Deptrac/badge.svg)](https://github.com/tattersoftware/codeigniter4-alerts/actions/workflows/inspect.yml)
 [![Coverage Status](https://coveralls.io/repos/github/tattersoftware/codeigniter4-alerts/badge.svg?branch=develop)](https://coveralls.io/github/tattersoftware/codeigniter4-alerts?branch=develop)
 
 ![Screenshot](https://github.com/tattersoftware/codeigniter4-alerts/blob/master/img/screenshot2.png)
 
 ## Quick Start
 
-1. Run: `> composer require tatter/alerts`
-2. Load the helper: `helper('alerts');`
-2. Set an alert: `alert('success', "You did it!")`
-3. Add in head tag (optional): `<?= service('alerts')->css(); ?>`
-4. Add after banner/menu: `<?= service('alerts')->display(); ?>`
+1. Install with Composer: `> composer require tatter/alerts`
+2. Enable the `alerts` filter in **app/Config/Filters.php**
+3. Add the `{alerts}` token to your View Layouts
+4. Load the helper: `helper('alerts');`
+4. Set an alert with a class and message: `alert('success', 'You did it!')`
 
 ## Features
 
-Provides out-of-the-box user alerts for CodeIgniter 4
+Provides integrated user alerts for CodeIgniter 4 with a variety of built-in templates
+and custom template support.
 
 ## Installation
 
@@ -30,27 +32,141 @@ composer require tatter/alerts
 Or, install manually by downloading the source files and adding the directory to
 `app/Config/Autoload.php`.
 
-> Note: The default display template expects [Bootstrap](https://getbootstrap.com) but is
-easily changed.
+> Note: The default display template expects [Bootstrap](https://getbootstrap.com) (not included)
 
 ## Configuration (optional)
 
 The library's default behavior can be changed using its config file. Copy
 **examples/Alerts.php** to **app/Config/Alerts.php** and follow the instructions in the
 comments. If no config file is found the library will use its defaults.
 
-### Styling
+The Config file consists of two properties.
 
-By default alerts will be displayed with classes for Bootstrap (not included).
-However, styles can be set to use other frameworks (or you may use your own) by changing
-the `$template` property in the Config file.
+### Templates
+
+The `$template` property sets the path to the View file which will be used to format your
+alerts. The default template has HTML tags and classes designed for use with
+[Bootstrap 4 Alerts](https://getbootstrap.com/docs/4.6/components/alerts/), but the library
+includes additional templates for you to choose:
+* `Tatter\Alerts\Views\Foundation`: Compatible with the Foundation CSS Framework
+* `Tatter\Alerts\Views\Vanilla`: A framework-free implementation, with classes available for your own CSS styling
+
+And of course you can add your own. The view file will be passed an array of tuples named
+`$alerts`, with each tuple in the format `[string $class, string $content]`. Your view file
+should unpack each tuple:
+```php
+foreach ($alerst as $alert) {
+    [$class, $content] = $alert;
+```
+... then output the alert `$content` wrapped in some appropriate HTML tags with whatever
+styling or classes you like based on `$class`.
+
+> Note: This library *does not include* assets for Bootstrap or Foundation. Check out
+> [Tatter\Frontend](https://github.com/tattersoftware/codeigniter4-frontend) for an integrated solution.
+
+### Classes
+
+The `$classes` property is a mapping of Session keys to their CSS classes. This lets you
+control which Session keys are deemed "alerts" and how to designate them to your view
+template. The default list is a generous guess at common keys used by the framework and
+modules, with the addition of the Bootstrap alert classes, but in most cases you will want
+to slim this down or replace it altogether with your own.
+
+*See **Warnings** below for some caveats to consider when auto-populating Session keys into displayable content.*
+
+## Filter
+
+In order to use the `AlertsFilter` you must add apply it to your target routes. The filter
+only applies when the token is present so it is safe to apply it globally in **app/Config/Filters.php**.
+See [Controller Filters](https://codeigniter.com/user_guide/incoming/filters.html) for more info.
+
+> Note: The alias is predefined for you as "alerts", and only the `after()` method is relevant.
+
+## Token
+
+The token is the following string: `{alerts}`. Place this in your View layout where you want
+the alerts to appear. For example:
+```php
+<body>
+    <aside>
+    {alerts}
+    </aside>
+    <main class="wrapper">
+    ...
+```
 
 ## Usage
 
-If installed correctly CodeIgniter 4 will detect and autoload the library, service, helper,
-and config. Initialize the helper if you want the convenience wrapper function:
-`helper('alerts');`
+If installed correctly CodeIgniter 4 will detect and autoload the library, filter, helper,
+and config. The filter will gather any alerts from the Session keys defined in your Config,
+pass them through your View template for formatting, and place them into your Response body
+wherever you have placed your token - you just need to set the alerts!
+
+Alerts can be set directly in the Session, ideally as flashdata (so they are not repeated):
+```php
+session()->setFlashdata('success', 'Your account has been updated.');
+```
+
+Many times your alerts will be handled during redirect, so you can take advantage of
+the framework's `RedirectResponse` class method `with()` to apply the flashdata directly:
+```php
+if (! $fruit = $this->getPost('fruit')) {
+    return redirect()->back()->with('error', 'You must select a fruit!');
+}
+```
+
+### Alerts Helper
+
+This library also includes a helper function, which has the added benefit of merging values
+and checking for collision. Initialize the helper to us the convenience wrapper function:
+```php
+helper(['alerts']);
+alert('error', 'You must accept the terms of service to continue.');
+```
+
+The helper adds a few features (like collision detection and alert merging) but may throw
+exceptions in some circumstances - read the **Collision** section below.
+
+## Warnings
+
+The premise of this library is to take data from `$_SESSION` and display it to visitors of
+your site. There are a few precautions mentioned here, but in general: use strong security
+practices and good sense any time you are moving data between the backend and public views.
+
+### Security
+
+Ideally `$_SESSION` should not contain critical information like passwords or credit card
+numbers. You should also not use distinguishable identifiers as Session keys, and this goes
+for `Alerts` as well. Keep the keys you use basic, and consider pairing down the Config
+file's to only those values your app and modules need.
+
+For example, say you add a payment library to your project and some developer was using
+the following code to test credit card submission and forgot to remove it:
+```php
+$_SESSION['debug'] = (string) $user->getCreditCard();
+```
+
+Since "debug" is a valid `Alerts` key this credit card number will now become a alert
+displayed visually on the user's browser window! 
+
+### Collision
+
+Another concern is Session collision. Starting with an example this time:
+```php
+/** @var Notice $notice */
+$notice = model(NoticeModel::class)->first();
+session('notice', $notice);
+...
+
+// Later that same day...
+alert('notice', 'Site statistics are currently being updated, expect longer load times.');
+```
+
+We have just tried to set an alert for a Session key that already exists and contains
+something that is not another alert! There are a few ways that this can play out, but
+ultimately this was a mistake and you should take care to avoid it.
 
-Then use the helper function `alert($class, $text)` to set an alert for the user's next
-view. Use class methods `$alerts->css()` and `$alerts->display()` to retrieve the styling
-and HTML for the alerts.
+To clarify the example:
+1. `AlertsFilter` will quietly ignore Session data that is not a string or an array of strings, so there is no problem with `session('notice', $notice);`.
+2. Using the Alerts Helper to set your alert includes the additional layer of collision protection, but will cause the `alert()` function to throw an exception.
+3. Setting Session keys yourself is a fine solution, but you must handle checks for existing keys or risk overwriting data.

UPGRADING.md

@@ -5,9 +5,9 @@
 
 > Note: This is a complete refactor! Please be sure to read the docs carefully before upgrading.
 
-* All handling is now routed through `AlertsFilter` - read the docs on setting up the Filter
+* All handling is now routed through `AlertsFilter` - read the docs on how to enable the Filter and add the token to your layouts
 * Related, the service, exceptions, and language files have been removed
-* Alerts no longer use session prefixes but are matched to the Config `$classes` - beware of session collision
+* `Alerts` no longer uses session prefixes but matches to the Config `$classes` - beware of session collision
 * The view templates no longer include a wrapper; if you would like consistent behavior then put your token in an `<aside>` tag:
 ```html
     <aside id="alerts-wrapper">

src/Config/Alerts.php

@@ -21,19 +21,25 @@ class Alerts extends BaseConfig
      * @var array<string,string>
      */
     public $classes = [
+        // Bootstrap classes
         'primary'   => 'primary',
-        'message'   => 'primary',
         'secondary' => 'secondary',
-        'notice'    => 'secondary',
         'success'   => 'success',
         'danger'    => 'danger',
+        'warning'   => 'warning',
+        'info'      => 'info',
+
+        // Additional log levels
+        'message'   => 'primary',
+        'notice'    => 'secondary',
         'error'     => 'danger',
-        'errors'    => 'danger',
         'critical'  => 'danger',
         'emergency' => 'danger',
-        'warning'   => 'warning',
         'alert'     => 'warning',
-        'info'      => 'info',
         'debug'     => 'info',
+
+        // Common framework keys
+        'messages' => 'primary',
+        'errors'   => 'danger',
     ];
 }

src/Config/Filters.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Tatter\Alerts\Config;
+
+use Config\Filters;
+use Tatter\Alerts\Filters\AlertsFilter;
+
+/**
+ * @var Filters $filters
+ */
+$filters->aliases['alerts'] = AlertsFilter::class;

src/Helpers/alerts_helper.php

@@ -21,7 +21,7 @@ function alert(string $key, $content): void
 
         // If no key exists the set and quit
         if (! $session->has($key)) {
-            $session->set($key, $content);
+            $session->setFlashdata($key, $content);
 
             return;
         }
@@ -31,12 +31,13 @@ function alert(string $key, $content): void
 
         if (is_array($value)) {
             $session->push($key, $content);
+            $session->markAsFlashdata($key);
 
             return;
         }
 
         if (is_string($value)) {
-            $session->set($key, array_merge([$value], $content));
+            $session->setFlashdata($key, array_merge([$value], $content));
 
             return;
         }