Le respect du **planning** d'affichage d'une alerte puisée en base de données...

CHANGELOG

=========

4.0.0

-----

- Le respect du **planning** d'affichage d'une alerte puisée en base de données devient incontournable (cf. [README.md](README.md#ruptures-de-compatibilité).

3.2.0

-----

- FlashMessengerContainer : possibilité de recevoir une liste de messages pour une même sévérité.

  - `severity` : Sévérité de l'alerte ({@see Alerte::SEVERITY_INFO} par défaut)

  - `duration` : Durée d'apparition de l'alerte avant sa disparition, en ms (0 = durée infinie), SI SUPPORTÉE par le mode d'affichage choisi ultérieurement

Une alerte stockée en bdd peut avoir une période d'affichage (appelée de façon un peu ambitieuse "planning"), càd une date de début 

et une date de fin d'affichage, qui pourra être respectée ou non lors de la demande d'affichage.

Le module fournit l'aide de vue `alertes()` (cf. `UnicaenAlerte\View\Helper\AlerteViewHelper`).

Remarques :

- La prise en compte de la période d'affichage n'est possible que pour les alertes puisées en bdd.

### Alertes en base de données

#### Planning

Une alerte stockée en bdd peut avoir un **planning** d'affichage (table `unicaen_alerte_alerte_planning`), 

càd une ou plusieurs périodes précises (date de début, date de fin) pendant lesquelles doit s'afficher l'alerte.

Si aucun planning n'est spécifié, l'alerte sera prise en compte systématiquement.

Exemples d'utilisation

----------------------

### Affichage d'alertes puisées dans la bdd

```php

// Affichage de toutes les alertes puisées en bdd, sous forme de Toasts Bootstrap, à condition que leur planning d'affichage inclue la date du jour :

echo $this->alertes()->addAlertesFromDatabase(true)->renderAsBootstrapToasts();

// Idem, sous forme d'Alerts Bootstrap classiques :

echo $this->alertes()->addAlertesFromDatabase(true)->renderAsBootstrapAlerts();

// Idem, sous forme de Modals Bootstrap chaînées :

echo $this->alertes()->addAlertesFromDatabase(true)->renderAsBootstrapModals();

// Idem, sous forme d'alertes Javascript :

echo $this->alertes()->addAlertesFromDatabase(true)->renderAsJavascriptAlerts();

// Affichage d'une alerte puisée en bdd identifiée par son code, sous forme d'un Toast Bootstrap, à condition que son planning d'affichage inclue la date du jour :

echo $this->alertes()->addAlerteFromDatabase('ALERTE_MAINTENANCE', true)->renderAsBootstrapToasts();

// Affichage d'une alerte puisée en bdd identifiée par son code, sous forme d'un Toast Bootstrap, quelque soit son planning d'affichage :

echo $this->alertes()->addAlerteFromDatabase('ALERTE_FERMETURE_ESTIVALE')->renderAsBootstrapToasts();

// Affichage sous forme de Toasts Bootstrap de *toutes* les alertes puisées en bdd :

//   - n'ayant aucun planning d'affichage particulier *ou* ayant au moins un planning incluant la date du jour :

echo $this->alertes()->addAlertesFromDatabase()->renderAsBootstrapToasts();

// Idem, mais sous forme d'Alerts Bootstrap classiques :

echo $this->alertes()->addAlertesFromDatabase()->renderAsBootstrapAlerts();

// Idem, mais sous forme de Modals Bootstrap chaînées :

echo $this->alertes()->addAlertesFromDatabase()->renderAsBootstrapModals();

// Idem, mais sous forme d'alertes Javascript :

echo $this->alertes()->addAlertesFromDatabase()->renderAsJavascriptAlerts();

```

### Affichage d'alertes issues du FlashMessenger

echo $this->alertes()

    ->addAlerteNew("Quelque chose s'est mal passé !!", "Votre attention, svp !", 'danger')

    ->addAlerteNew("Youpi !!", "Félicitations", 'success', 3000) // disparition automatique au bout de 3s

    ->addAlerteFromDatabase('ALERTE_MAINTENANCE')

    ->addAlerteFromDatabase('ALERTE_FERMETURE_ESTIVALE', false) // pas de respect de la période d'affichage

    ->addAlertesFromDatabase()

    ->addAlertesFromFlashMessenger()

    ->renderAsBootstrapToasts();

```

    ->addAlerteNew("Quelque chose s'est mal passé !!", "Votre attention, svp !", 'danger')

    ->addAlerteNew("Youpi !!", "Félicitations", 'success', 3000);

$alertesHelper->getDatabaseContainer()

    ->withCodeAndMatchingPlanning('ALERTE_MAINTENANCE')

    ->withCodeAndMatchingPlanning('ALERTE_FERMETURE_ESTIVALE', false);

    ->withCodes(['ALERTE_MAINTENANCE', 'ALERTE_FERMETURE_ESTIVALE']);

echo $alertesHelper

    ->addAlertesFromDatabase()

    ->addAlertesFromFlashMessenger()

```

Ruptures de compatibilité

-------------------------

### Version 4.0.0

- Contrairement aux versions précédentes, le respect du **planning** d'affichage d'une alerte puisée en base de données 

  est incontournable :

  - soit l'alerte possède un planning, auquel cas il doit inclure la date du jour pour que l'alerte soit prise en compte,

  - soit elle n'en possède aucun, auquel cas l'alerte est systématiquement prise en compte.

  Les méthodes du genre `xxxMatchingPlanning()` (et les arguments `$matchingPlanning`) ont donc disparu,

  il vous faudra rechercher leurs usages dans votre retoucher votre code, navré. 

Installation

------------

### PHP

### Composer

Votre `composer.json` doit déclarer le repository Unicaen :

```yaml

    "repositories": [

        {

            "type": "composer",

            "url": "https://packagist.unicaen.fr"

        },

    ],

```

Pour installer la bibliothèque :

```bash

composer require unicaen/alerte

```

N'oubliez pas d'activer le module dans `config/application.config.php`.

N'oubliez pas d'activer le module dans `config/application.config.php`, en ajoutant `'UnicaenAlerte'` dans la liste.

### Base de données

namespace UnicaenAlerte\Container\Database;

use Doctrine\ORM\Query\Expr\Join;

use UnicaenAlerte\Container\FilterableContainerInterface;

use UnicaenAlerte\Container\FilterableContainerTrait;

use UnicaenAlerte\Entity\Db\Alerte;

    public function fetchAlertes(): array

    {

        $qb = $this->alerteRepository->createQueryBuilder('a')

            ->addSelect('p') // seuls les plannings (éventuels) incluant la date du jour nous intéressent

            ->leftJoin('a.plannings', 'p', Join::WITH, 'current_timestamp() between p.startDate and p.endDate');

            ->leftJoin('a.plannings', 'p')->addSelect('p');

        $ors = [];

        foreach ($this->withCodesAndMatchingPlanning as $code => $matchingPlanning) {

            // le code de l'alerte doit matcher

        foreach ($this->withCodes as $code) {

            $param = uniqid(':code_');

            $expr = "a.code = $param";

            $qb->setParameter($param, $code);

            if ($matchingPlanning) {

                // et en plus, un planning doit exister

                $expr = $qb->expr()->andX($expr, 'p.id is not null');

            }

            $ors[] = $expr;

            $ors[] = "a.code = $param";

        }

        if ($ors) {

            $qb->andWhere($qb->expr()->orX(...$ors));

        }

        // filtre global portant sur toutes les alertes.

        if ($this->withMatchingPlanning) {

            $qb->andWhere('p.id is not null');

        }

        // si un planning existe, il doit être respecté

        $qb->andWhere('p.id is null OR current_timestamp() between p.startDate and p.endDate');

        /** @var Alerte[] $alertes */

        $alertes = $qb->getQuery()->getResult();

     * @param string[] $codes

     */

    public function withCodes(array $codes): static;

    /**

     * Sélection précise des alertes par leur code,

     * en précisant si les alertes doivent avoir un planning qui inclue la date du jour.

     *

     * @param string[] $codes

     * @param bool $matchingPlanning L'alerte doit-elle avoir un planning qui inclue la date du jour pour être retenue ?

     */

    public function withCodesAndMatchingPlanning(array $codes, bool $matchingPlanning = true): static;

    /**

     * Sélection précise d'une alerte par son code.

     *

     * @param string $code

     */

    public function withCode(string $code): static;

    /**

     * Sélection précise d'une alerte par son code,

     * en précisant si l'alerte doit avoir un planning qui inclue la date du jour.

     *

     * @param string $code

     * @param bool $matchingPlanning L'alerte doit-elle avoir un planning qui inclue la date du jour pour être retenue ?

     */

    public function withCodeAndMatchingPlanning(string $code, bool $matchingPlanning = true): static;

    /**

     * Permet de ne sélectionner que les alertes ayant un planning qui inclue la date du jour.

     *

     * @param bool $matchingPlanning L'alerte doit-elle avoir un planning qui inclue la date du jour pour être retenue ?

     */

    public function withMatchingPlanning(bool $matchingPlanning = true): static;

}

 No newline at end of file

trait FilterableContainerTrait

{

    /**

     * Sélection précise des alertes par leur code,

     * en précisant pour chacune si elle doit avoir un planning qui inclue la date du jour pour être retenue.

     *

     * @var bool[] $code => $withMatchingPlanning

     */

    protected array $withCodesAndMatchingPlanning = [];

    /**

     * Spécifie *globalement* si les alertes doivent avoir un planning qui inclue la date du jour pour être retenues.

     * Sélection précise des alertes par leur code.

     *

     * @var bool

     * @var string[]

     */

    protected bool $withMatchingPlanning = false;

    protected array $withCodes = [];

    /**

     * Sélection précise des alertes par leur code.

     * @param string[] $codes Codes uniques des alertes

     */

    public function withCodes(array $codes): static

    {

        return $this->withCodesAndMatchingPlanning($codes, false);

    }

    /**

     * Sélection précise des alertes par leur code,

     * en précisant si les alertes doivent avoir un planning qui inclue la date du jour.

     *

     * @param string[] $codes Codes uniques des alertes

     * @param bool $matchingPlanning L'alerte doit-elle avoir un planning qui inclue la date du jour pour être retenue ?

     * @return static

     */

    public function withCodesAndMatchingPlanning(array $codes, bool $matchingPlanning = true): static

    {

        foreach ($codes as $code) {

            $this->withCodeAndMatchingPlanning($code, $matchingPlanning);

            $this->withCodes[$code] = $code;

        }

        return $this;

    }

    /**

     * Sélection précise d'une alerte par son code.

     *

     * @param string $code Code unique de l'alerte

     * @return static

     */

    public function withCode(string $code): static

    {

        return $this->withCodeAndMatchingPlanning($code, false);

    }

    /**

     * Sélection précise d'une alerte par son code,

     * en précisant si l'alerte doit avoir un planning qui inclue la date du jour.

     *

     * @param string $code Code unique de l'alerte

     * @param bool $matchingPlanning L'alerte doit-elle avoir un planning qui inclue la date du jour pour être retenue ?

     * @return static

     */

    public function withCodeAndMatchingPlanning(string $code, bool $matchingPlanning = true): static

    {

        $this->withCodesAndMatchingPlanning[$code] = $matchingPlanning;

        $this->alertes = null;

        $this->withMatchingPlanning = false;

        return $this;

    }

    /**

     * Permet de ne sélectionner que les alertes ayant un planning qui inclue la date du jour.

     *

     * @param bool $matchingPlanning L'alerte doit-elle avoir un planning qui inclue la date du jour pour être retenue ?

     * @return static

     */

    public function withMatchingPlanning(bool $matchingPlanning = true): static

    {

        $this->withMatchingPlanning = $matchingPlanning;

        $this->alertes = null;

        return $this;

    }

}

 No newline at end of file