DotclearWatch / Blog - Mot-clé - 2.36

[2.36] Modification des Utility et Process

Jean-Christian Denis — Sat, 18 Oct 2025 11:47:00 +0200

Depuis Dotclear 2.36 les classes de context sont accessibles directement en tant que méthodes de ces context, cela implique des changements dans leur fontionnement qui se répercutent jusque sur les thèmes et plugins.

L'arborescence de Dotclear contient un nouvel espace de nom Dotclear\Helper\Process qui embarque differentes classes utiles au fonctionnement des Utility et Process :

Dotclear\Helper\Process\AbstractProcess
Dotclear\Helper\Process\AbstractSingleton
Dotclear\Helper\Process\AbstractUtility
Dotclear\Helper\Process\TraitProcess

Utility

Normalement nul besoin de se préoccuper de cette partie, elle appartient au core de Dotclear, mais c'est toujours bon de savoir comment cela fonctionne.

Les Utility (Backend, Frontend, Upragde, Install) sont désormais des Container, leurs Process sont des services, leurs classes de second niveau sont des services et tous sont accessibles depuis des méthodes ( voir Modification des containeurs ) Les Utility étendent la classe abstraite AbstractUtility qui embarque tout ce qu'il faut pour charger leurs services. Enfin les Utility utilisent le trait TraitProcess qui embarque ce qu'il faut pour le bon déroulement du processus requis par le core.

Exemple de l'Utility Backend et de la classe de second niveau Favorites :

<?php

declare(strict_types=1);

namespace Dotclear\Core\Backend;


class Utility extends AbstractUtility
{
    // ...

    public function getDefaultServices(): array
    {
        return [
            Favorites::class   => Favorites::class,
            // ...
        ];
    }

    public function favorites(): Favorites
    {
        return $this->get(Favorites::class);
    }

    // ...
}

Accessible désormais avec :

App::backend()->favorites();

Process

Jusqu'à Dotclear 2.36 toutes les classes de second niveaux du core (les servcies des Utility) et toutes les classes des plugins et thèmes lièes à la gestion de modules devaient étendre la classe Process du core. Depuis Dotclear 2.36 les services des Utility peuvent avoir besoin d'étendre d'autres classes ce qui serait impossible tel quel. La classes abstraite Process s'est donc transformée en trait, afin de pouvoir être utilisé en plus d'autres classes.

Exemple du plugin blogroll de la distribution :

<?php

declare(strict_types=1);

namespace Dotclear\Plugin\blogroll;

use Dotclear\Helper\Process\TraitProcess;

class Backend
{
    use TraitProcess;

    public static function init(): bool
    {
        //...
    }
}

Les plugins dcProxy s'occupent de faire le lien entre les plugins / thèmes qui ne sont pas à jour et l'utilisation du trait.

Ce qu'il faut retenir et que là ou on utilisait :

<?php

declare(strict_types=1);

namespace Dotclear\Plugin\MonPlugin;

Use Dotclear\Core\Process;

class Backend extends Process
{
    //...
}

Il faut utiliser :

<?php

declare(strict_types=1);

namespace Dotclear\Plugin\MonPlugin;

use Dotclear\Helper\Process\TraitProcess;

class Backend
{
    use TraitProcess;

    //...
}

[2.36] Installation en mode CLI

Jean-Christian Denis — Sat, 18 Oct 2025 11:16:00 +0200

A partir de Dotclear 2.36, il est possible d'installer un multiblogs en ligne de commande.

Par exemple, après s'être connecté en SSH au serveur, on télécharge et on décompresse l'archive de la version 2.36 de Dotclear, puis on se place à la racine de ce répertoire. On suppose que php peut-être appelé directement. (Sinon il faudra utiliser quelque chose comme bin/php)

Dans la console SSH on peut lister les paramètres de l'installation en ligne de commande avec l'option -h, ce qui devrait donner ça :

me@srv:/var/www/html$ php admin/install/index.php -h
Command line options are:
-h => This help
-n => Disable interactive mode
--dbdriver => The database driver
--dbhost => The database host
--dbname => The database name
--dbuser => The database user
--dbpassword => The database password
--dbprefix => The database table prefix, can be empty for deault to _dc
--adminemail => The administration mail from
--ufirstname => The super administrator first name, can be empty
--ulastname => The super administrator last name, can be empty
--uemail => The super administrator email
--ulogin => The super administrator login
--upassword => The super administrator password
--adminurl => The admoin dashboard URL
--blogurl => The default blog URL

Comme on peut le voir, soit on lance l'installation en mode intercatif, c'est à dire sans option, dans quel cas une succession de questions nous seront posées, soit on utilise les options. Si une option est manquante ou ne correspond pas à une valeur attendue, le script repassera en mode interactif et posera la question correspondante à l'option.

Un début d'exemple du mode intercatif :

me@srv:/var/www/html$ php admin/install/index.php
Starting first step of Dotclear installation process.
[IN] Configure the database driver (mysqli,mysqlimb4,pgsql,pdomysql,pdomysqlmb4,pdosqlite,pdopgsql): pdosqlite
[OK] Database driver is set to "pdosqlite".
[IN] Configure the database path:
[OK] Database path is set to "/var/www/html/db/202510180930.sqlite".
[IN] Configure the database table prefix:
[OK] Database table prefix is set to "dc_".
[IN] Configure the administration mail from: plop
[KO] Invalid administration mail from.
[IN] Configure the administration mail from:
...

Il est possible de ne pas utiliser le mode intractif avec l'option -n, dès lors, il faut renseigner toutes les options et le script retournera 1 si tout s'est bien passer pendant le processus d'installation. Ce mode de fonctionnement peut être pratique lors d'installations automatiques depuis des scripts bash.

[2.36] Modification du service de base de données

Jean-Christian Denis — Tue, 02 Sep 2025 14:17:00 +0200

Dans Dotclear 2.36 le Container principal est encore plus soyeux avec uniquement de vraies classes comme services, cela entraîne certaines modifications.

Avant la version 2.36 de Dotclear, l'accès à la base de données se faisait par l'appel App::con(); mais d'un point de vu technique cet appel passait par une fonction intermediaire directement dans la pile de services du Container principal, fonctionnel mais pas vraiment joli et surtout trop strict et rigide. C'est pourquoi la version 2.36 de Dotclear introduit un nouveau service du core nommé db() qui fait le lien entre Dotclear et les drivers de base de données. De ce fait, l'appel qui se faisait par App::con() devient App::db()->con(), plus long et donc moins sexy, mais cela va permettre de travailler et d'améliorer les drivers de base de données beaucoup plus facilement.

//App::con()->openCursor('xyz');
App::db()->con()->openCursor('xyz);

Bien entendu l'écriture App::con() est dépréciée mais reste fonctionnelle encore pour quelques siècles.

Ce changement a permis dès la version 2.36 de proposer d'autres drivers de base de données et d'améliorer le processus d'installation.

Le nouveau service App::db()

Le coeur de l'application Dotclear embarque donc un nouveau service qui va permettre de faire le lien entre les drivers de base de données et le reste de Dotclear.

Il est identifié comme suit dans le container :

Identifiant du service : Dotclear\Core\DatabaseInterface
Classe par défaut : Dotclear\Core\Database
Methode du service : App::db()

Son interface montre ses méthodes :

App::db()->con() : l'accès à la base de données
App::db()->newCon() : Une instance isolé de l'accès à une base de données
App::db()->structure() : l'accès à la gestion de structure de base de données
App::db()->combo() : liste des drivers utilisables (sert dans le process d'installation Dotclear)

interface DatabaseInterface
{
    /**
     * Get dabatase connection handler instance.
     *
     * This connection instance uses parameters from config service.
     */
    public function con(): ConnectionInterface;

    /**
     * Get new dabatase connection handler instance.
     *
     * @param   string  $driver         Driver name
     * @param   string  $host           Database hostname
     * @param   string  $database       Database name
     * @param   string  $user           User ID
     * @param   string  $password       Password
     * @param   bool    $persistent     Persistent connection
     * @param   string  $prefix         Database tables prefix
     */
    public function newCon(
        string $driver, 
        string $host, 
        string $database, 
        string $user = '', 
        string $password = '', 
        bool $persistent = false, 
        string $prefix = ''
    ): ConnectionInterface;

    /**
     * Get database structure handler.
     *
     * The handler uses current connexion.
     * Each call to this method MUST return a new instance.
     *
     * @return  Structure   The database structure handler
     */
    public function structure(): Structure;

    /**
     * Get combo of available database drivers.
     *
     * @return  array<string, string>   The drivers name/driver pairs
     */
    public function combo(): array;
}

Cette classe est récente et va surement évoluer dans les versions à venir.

Le gestionnaire de connexion App::db()->con()

Une fois le driver choisi et inscrit dans le fichier de configuration de Dotclear, ses méthodes sont accessibles depuis l'application dans App::db()->con().
Un driver est généralement constitué d'une classe principale qui étend une classe d'abstraction qui étend elle même une interface. Le driver fournit également une classe de gestion de Schema. Toutes ces classes sont disponibles à divers endroits de Dotclear :

Les classes d'abstraction sont dans Dotclear\Database,
Les interfaces dans Dotclear\Interface\Database
Les drivers dans Dotclear\Schema\Database
Les drivers sont ajoutés à un container dédié
Les drivers vérifient l'installation avant d'être proposés

Une nouvelle méthode fait sont appartition dans le gestionnaire de connexion (driver), afin de tester que les conditions requises à son utilisation sont présentes. Sa définition est visible dans l'interface :

/**
 * Check driver requirements.
 *
 * This method MUST throw a DatabaseException if driver can not be used.
 * This method does NOT say a SGBD is installed but only PHP supports it.
 *
 * @since   2.36
 *
 * @throws  \Dotclear\Exception\DatabaseException   if condition does not meet driver requirements
 */
public static function precondition(): void;

Les drivers PDO

PDO est une extension de PHP signifiant PHP Data Objects, c'est une interface d'abstraction de l'accès à des bases de données, en d'autre termes cela doit simplifier l'accès à differents types de base de données depuis une application comme Dotclear. Jusqu'à la version 2.36 Dotclear n'utilisait PDO que pour la connexion à des bases de donnée Sqlite, depuis la version 2.36 il est possible de se connecter à des bases Mysql et PostgreSql à travers les drivers PDO. Les drivers de Dotclear utilisant PDO ne sont pour l'instant que des passerelles de connexion, toutes les fonctionnalités de PDO ne sont pas exploitées, Dotclear ayant déjà son propre système de préparation de requêtes.

Par défaut sur les sytèmes Linux, PHP embarque l'extension PDO avec le pilote pour Sqlite, si ce n'est pas le cas, le site de PHP fournira un peu d'aide à l'installation plus complète de PDO.

Le cas Sqlite

Le driver Sqlite de Dotclear était déjà basé sur PDO, il a simplement été renommé pour correspondre aux autres drivers. Il n'y a rien besoin de modifier, Dotclear se charge de comprendre que si vous avez définie le driver à "sqlite" cela veut dire qu'il faut utiliser "pdosqlite".

Les drivers livrés avec Dotclear

mysqli : Mysql avec les fonctions mysqli_* de PHP
mysqlimb4 : Idem avec le support utf8-mb4
pgsql : PostgreSql avec les classes PgSql de PHP
pdosqlite : Sqlite sous PDO
pdomysql : Mysql sous PDO
pdomysqlmb4 : Mysql sous PDO avec support utf8-mb4
pdopgsql : PostgreSql sous PDO

Lors de l'installation de Dotclear tous les drivers ayant un support dans la version installée de PHP seront proposés pour définir la connexion à la base de données.

Utiliser un driver PDO sur une installation existante

Si votre système embarque les composants PDO pour votre base de données, il est possible de passer sur les drivers PDO simplement en mettant à jour le fichier config.php, il faut remplacer la définiton de DC_DBDRIVER par le nouveau driver. Et l'inverse est également vrai. Voici les equivalents :

mysqli <=> pdomysql
mysqlimb4 <=> pdomysqlmb4
sqlite <=> pdosqlite
pgsql <=> pdopgsql

// define('DC_DBDRIVER', 'mysqli');
define('DC_DBDRIVER', 'pdomysql');

Auncune recommandation ici, rien ne vous oblige aujourd'hui à changer, ce ne sont que des drivers qui permettent le lien entre Dotclear et votre base de données et ils sont tous maintenus pour le moment.

Créer un driver

Pour l'exemple on va prendre un driver utilisant PDO. L'extension PDO de PHP n'est pas magique, chaque type de base de données à ses propres lois et chaque type est diffèrent. Néanmoins Dotclear propose un classe d'abstraction pour simplifier la création d'un driver de base de données utilisant PDO. Par exemple, si vous souhaiter commencer un driver pour MsSql voici ce à quoi ça pourrait ressembler.

On ajoute notre service au container des drivers de base de données et on crée notre classe de service :

<php

namespace /MySpace/PdoMsSql;

use Dotclear\Database\AbstractPdoHandler;
use Dotclear\Helper\Container\Container;
use Dotclear\Helper\Conttainer\Factories;

Factories::addService('database', 'pdomssql', PdoMsSql::class);

class PdoMsSql extends AbstractPdoHandler
{
    public const HANDLER_NAME   = 'MsSql (PDO)';
    public const HANDLER_DRIVER = 'pdomssql';
    public const HANDLER_SYNTAX = 'mssql';
    public const HANDLER_PDO    = 'sqlsrv';

    // ...
}

Il faut ensuite modifier toutes les methodes qui demandent un ajustement par rapport au language MsSql et lui adjoindre un classe de Schema. Bon courage.

Il y aurait beaucoup à dire sur cette partie mais ce serait bien trop long. Les très rares personnes qui souhaiteraient créer leur propre driver de base de données sont sans aucun doute assez callées pour comprendre le code de Dotclear.

[2.36] Modification des conteneurs

Jean-Christian Denis — Tue, 02 Sep 2025 09:33:00 +0200

Avec les corrections des divers bugs du coeur de Dotclear 2.36, la classe de Container a été améliorée.

Le gestionnaire de service (Container) embarqué dans Dotclear ne permettait pas de passer à ses services le container lui-même, c'est désormais possible depuis Dotclear 2.36. Une autre limite du container était qu'on ne pouvait pas récupèrer d'instance d'une service pour un usage isolé sans propager les intercations à tout le container. Pour faire simple si on modifiait les paramètres d'un service, cela modifiait ce service pour tout le script. Il est désomrais possible de créer des instances de service à usage ponctuel.

L'appel d'un service avec le paramètre NULL permet d'avoir une instance isolée de ce service. Les valeurs TRUE et FALSE de ce paramètre ont toujours les mêmes fonction qu'avant.

Voici un exemple complet montrant le passage du container au service et l'utilisation du paramétre NULL à la récupération du service :

<?php 

use Dotclear\Helper\Container\Container;
use Dotclear\Helper\Conttainer\Factories;

// Class du service
class MonService
{
    protected int $nb = 0;

    // On passe le container directement au service
    public function __construct(
        protected MonContainer $container
    ) {

    }

    // On met en mémoire du service un nombre
    public function nombre(int $nb): void
    {
        $this->nb = $nb;
    }

    // On lance un calcul en utilisant une methode du container
    public function calcul(): string
    {
        $somme = $this->container->ajoute($this->nb);

        return 'resultat : ' . $somme . "\n";
    }
}

// Class du container
class MonContainer extends Container
{
    public const CONTAINER_ID = 'moncontainer';

    public function __construct()
    {
        parent::__construct(Factories::getFactory(static::CONTAINER_ID));
    }

    // Methode qui fait une addition
    public function ajoute(int $nb): int
    {
        return $nb + $nb;
    }
}

// On ajoute le service au container
Factories::addService('moncontainer', 'monservice', MonService::class);

// On crée l'instance du container
$container = new MonContainer();

// On récupère une instance du service depuis le container
$a = $container->get('monservice');

// On lui donne un nombre
$a->nombre(2);

// On fait une première fois le calcul
echo $a->calcul(); // resultat : 4

// On donne un autre nombre à notre instance du sevice
$a->nombre(3);

// On calcul, le résultat prend en compte le dernier nombre soumis
echo $a->calcul(); // resultat : 6

// On recupère une instance du service depuis le container
$b = $container->get('monservice');

// Même sans soumettre de nombre, 
// on voit que le calcul se fait sur la même instance de service que précédement.
echo $b->calcul(); // resultat : 6

// On vérifie, et effectivement les deux instances a et b sont en réalité la même
echo $a->calcul(); // resultat : 6

// On récupère une nouvelle instance avec le parametre null
$c = $container->get('monservice', null);

// On donne à cette instance un nombre
$c->nombre(4);

// Le calcul prend bien en compte ce nombre
echo $c->calcul(); // resultat : 8

// On refait le calcul sur l'instance précédente, elle a bien gardé en mémoire le nombre précèdent
echo $b->calcul(); // resultat : 6

// Ce sont bien cette fois deux instances distinctes

// On récupère une instance du service depuis le container
$d = $container->get('monsevrice');

// On fait un calcul sans donner de nombre
echo $d->calcul(); // resultat: 6

// on voit que $c avec le paremetre null n'a pas d'influence sur les autres instances

Attention aux effets de bords, les objets partagés dans ces instances peuvent être modifiés dans une instance et renvoyer un résultat inattendu dans une autre instance !

A noter que tous les constructeurs des classes de premier niveau de Dotclear, celles qui sont disponibles dans le container principal, utilisables depuis App::xxx() ont désormais le container comme paramètre.
Par exemple classe Auth est passée de ça :

class Auth
{
    // ...
    /**
     * Constructs a new instance.
     *
     *@param   BlogInterface               $blog           The blog instance
     * @param   BlogsInterface              $blogs          The blogs handler
     * @param   ConfigInterface             $config         The configuration instance
     * @param   DatabaseInterface           $db             The database handler instance
     * @param   SessionInterface            $session        The session handler
     * @param   UserPreferencesInterface    $user_prefs     The user preferences instance
     * @param   UsersInterface              $users          The users handler
     */
    public function __construct(
        protected BlogInterface $blog,
        protected BlogsInterface $blogs,
        protected ConfigInterface $config,
        protected DatabaseInterface $db,
        protected SessionInterface $session,
        public UserpreferencesInterface $user_prefs,
        protected UsersInterface $users
    ) {
        // ...
    }
    // ...
}

à ça :

class Auth
{
    // ...
    /**
     * Constructs a new instance.
     *
     * @param   Core    $core   The core container
     */
    public function __construct(
        protected Core $core
    ) {
        // ...
    }
    // ...
}

Certains y veront le grand retour de $core, mais il n'en est rien, car cela n'est effectif que dans les classes de premier niveau, associées au container.

Appel aux classes de context

Les instances de classes appartenant aux contextes (Utility) telles que Frontend, Backend, Upgrade et Install sont désormais disponibles comme méthodes du contexte. Il n'est plus nécessaire de déclarer l'utilisation des classes comme \Dotclear\Core\Backend\Favorites::class pour les utiliser, car elles sont maintenant directement disponibles dans l'objet du contexte, ce qui donnera pour l'exemple App::backend()->favorites();

Voici une liste des classes de second niveau pour le Backend :

Dotclear\Core\Backend\Action::class => App::backend()->action(), (nouvelle classe, voir plus bas)
Dotclear\Core\Backend\Auth::class => App::backend()->auth(), (nouvelle classe, voir plus bas)
Dotclear\Core\Backend\Combos::class => App::backend()->combos(),
Dotclear\Core\Backend\Favorites::class => App::backend()->favorites(),
Dotclear\Core\Backend\Filter::class => App::backend()->filter(), (nouvelle classe, voir plus bas)
Dotclear\Core\Backend\Helper::class => App::backend()->helper(),
Dotclear\Core\Backend\Listing::class => App::backend()->listing(), (nouvelle classe, voir plus bas)
Dotclear\Core\Backend\MediaPage::class => App::backend()->mediaPage(),
Dotclear\Core\Backend\Menus::class => App::backend()->menus(),
Dotclear\Core\Backend\ModulesList::class => App::backend()->modulesList(),
Dotclear\Core\Backend\Notices::class => App::backend()->notices-),
Dotclear\Core\Backend\Page::class => App::backend()->page(),
Dotclear\Core\Backend\Resources::class => App::backend()->resources(),
Dotclear\Core\Backend\ThemeConfig::class => App::backend()->themeConfig(),
Dotclear\Core\Backend\ThemesList::class => App::backend()->themesList(),
Dotclear\Core\Backend\Url::class => App::backend()->url(),
Dotclear\Core\Backend\UserPref::class => App::backend()->userPref(),

Les nouvelles classes de Backend utiles aux listes que sont Action, Filter et Listing fournissent les instances des objets suivant :

Dotclear\Core\Backend\Action\ActionsBlogs => App::backend()->action()->blogs(...)
Dotclear\Core\Backend\Action\ActionsComments => App::backend()->action()->comments(...)
Dotclear\Core\Backend\Action\ActionsPosts => App::backend()->action()->posts(...)
Dotclear\Core\Backend\Filter\FilterBlogs => App::backend()->filter()->blogs(...)
Dotclear\Core\Backend\Filter\FilterComments => App::backend()->filter()->comments(...)
Dotclear\Core\Backend\Filter\FilterMedia => App::backend()->filter()->media(...)
Dotclear\Core\Backend\Filter\FilterPosts => App::backend()->filter()->posts(...)
Dotclear\Core\Backend\Filter\FilterUsers => App::backend()->filter()->users(...)
Dotclear\Core\Backend\Listing\ListingBlogs => App::backend()->listing()->blogs(...)
Dotclear\Core\Backend\Listing\ListingCommnets => App::backend()->listing()->comments(...)
Dotclear\Core\Backend\Listing\ListingMedia => App::backend()->listing()->media(...)
Dotclear\Core\Backend\Listing\ListingPosts => App::backend()->listing()->posts(...)
Dotclear\Core\Backend\Listing\ListingPostsMini => App::backend()->listing()->postsMini(...)
Dotclear\Core\Backend\Listing\ListingUsers => App::backend()->listing()->users(...)
Dotclear\Core\Backend\Listing\Pager => App::backend()->listing()->pager(...)

Une autre nouvelle classe fournit les instances des objets nécessaires aux connections tierces :

Dotclear\Core\Backend\Auth\Otp => App::backend()->auth()->otp(...)
Dotclear\Core\Backend\Auth\WebAuthn => App::backend()->auth()->webauthn(...)
Dotclear\Core\Backend\Auth\OAuth2Client => App::backend()->auth()->oauth2(...)

Voici une liste des classes de second niveau pour le Frontend :

Doclear\Core\Frontend\Ctx::class => App::frontend()->context(),
Doclear\Core\Frontend\Tpl::class => App::frontend()->template(),
Doclear\Core\Frontend\XmlRpc::class => App::frontend()->xmlrpc(),

Les plugins et thèmes, en pouvant accèder directement depuis le contexte à ces objets, ne devraient plus avoir à déclarer des classes appartenant aux Backend ou Frontend hormis lors de la création de liste pour étendre une classe.
.

[2.36] Modification du service de session

Jean-Christian Denis — Tue, 02 Sep 2025 09:29:00 +0200

Avec l'arrivé de la gestion des sessions coté publique, Dotclear 2.36 modifie le fonctionnement des sessions.

Le mécanisme de session de Dotclear dans ces versions inférieures à 2.36 était très stricte et écrit en dur là ou il y en avait besoin. La version 2.36 introduit des outils de connexions variés et la possibilité d'utilser des sessions coté publique, ce qui a obligé la team à revoir le fonctionnement des sessions. Pas de révoluton, les classes de sessions n'ont quasi pas été modifié, mais des changements qui peuvent porter à consequence.

Backend

Précedement, les sessions coté admin (backend) n'existait que lorsqu'on en avait besoin, c'est à dire lorsque l'utilisateur était connu. On pouvait donc faire simplement un test d'existence de session pour diverses routines. Mais depuis la version 2.36, les sessions sont toujours démarrées et existantes. Elle peuvent donc être vide et sans valeur de test.

Frontend

Coté publique, les sessions fournies par Dotclear n'existaient tout simplement pas avant la version 2.36. Depuis si un plugin veut utiliser des sessions coté publique, une simple ligne de code suffira à la démarrer.

App::session()->start();

Et si plusieurs plugins utilisent des sessions coté publique, chacun ajoutera cette ligne de code. Pas de soucis à l'appeler plusieurs fois, elle teste qu'elle a déjà été appelé. Ce nouveau système de session commune coté publique risque de poser problème avec de vieux plugins pas à jour utilisant leurs propres sessions, ce qui provoquera des erreurs assez fatales ! Un bien pour un mal, car avec la 2.36 on met tout le monde d'accord.

A noter que si un plugin utilise App::session()->destroy(); il détruira la session pour tous les autres plugins en même temps, ce n'est peut-être pas le comportement souhaité par les autres plugins !

Sans me faire de pub (qui risque plutôt de m'apporter des problèmes) un plugin FrontendSession propose de gérer les sessions coté publique avec tous les points d'entrée nécessaire à d'autres plugins. Widget, formulaire de login, menu utilisateur, page de gestion des options publique de l'utilisateur, etc...

Accès aux valeurs

Dans les versions précédentes de Dotclear, l'accès aux valeurs de session se faisait classiquement par $_SESSION, mais cela change. Le service de session contient trois nouvelles méthodes pour lire, écrire et effacer ces valeurs.

Leurs définition est très simple :

interface SessionInterface
{
    // ...

    /**
     * Set a value to session.
     *
     * @param   string  $key    The key
     * @param   mixed   $value  The value
     */
    public function set(string $key, mixed $value): void;

    /**
     * Get a value from session.
     *
     * @param   string  $key    The key
     *
     * @return  mixed   The value or null if not set
     */
    public function get(string $key): mixed;

    /**
     * Unset values from session.
     *
     * @param   string  $keys   The keys
     */
    public function unset(...$keys): void;
}

Le plugin n'a plus qu'à lire et écrire des valeurs de session avec par exemple :

if (App::session()->get('ma_valeur') == '' && !empty($__POST['mon_formulaire'])) {
    App::session()->set('ma_valeur', '1');
}
if (!empty($_POST['reset'])) {
    App::sesssion()->unset('ma_valeur');
}

La valeur sera automatiquement enregistrée en session à la fin du script, le plugin n'a pas à gérer cette partie non plus. Et l'ancienne écriture avec $_SESSION est encore valable mais pas récommander.

Configuration

Précédement la configuration du gestionnaire de session se faisait à sa construction. Une méthode désormais présente pour configurer le service avant de démarrer une session. Cela permet d'avoir un seul service App::session() qui peut être configurer suivant si on est en frontend ou backend.

Elle est définie dans son interface comme suit :

Interface SessionInterface
{
    //...

    /**
     * Configure session cookie.
     *
     * This MUST be done before session starts.
     *
     * @param   string          $cookie_name    Cookie name
     * @param   null|string     $cookie_path    Cookie path
     * @param   null|string     $cookie_domain  Cookie domain
     * @param   bool            $cookie_secure  Cookie secure
     * @param   null|string     $ttl            The ttl
     *
     * @throws  Dotclear\Exception\SessionException     if session is already configured
     */
    public function configure(
        string $cookie_name, 
        ?string $cookie_path = null, 
        ?string $cookie_domain = null, 
        bool $cookie_secure = false, 
        ?string $ttl = null
    ): void;
}

Mais pas besoin de retenir cette mécanique, les "Utility" (backend, frontend, upgrade) gère cette méthode et prépare le service avant l'appel aux plugins et thèmes.

[2.36] Modification du service de configuration

Jean-Christian Denis — Tue, 02 Sep 2025 09:26:00 +0200

Avec l'arrivé des authentifications exotiques, de nouvelles directives sont disponibles dans la configuration de Dotclear 2.36

Dotclear 2.36 propose une librairie oAuth2 client qui permet l'authentification depuis des applications tierces, cette librairie a besoin d'un fichier de configuration commun à toute la plateforme multiblogs. Ce fichier suit des régles strictes, il doit se nommer oauth2.php et être présent dans le même répertoire que le config.php.

Dans diffèrentes parties de Dotclear ou même de plugins, il y aura besoin de connaitre le chemin de ce fichier, on peut alors simplement récupérer son chemin complet comme suit :

$path = App::config()->oauth2Path();

Dans diffèrentes parties de Dotclear ou même de plugins, il y aura besoin de savoir si ce fichier existe, on peut alors tester simplement comme suit :

$exists = App::config()->hasOauth2();

oAuth2 n'est pas la seule nouvelle librairie d'authentification tiers, il y a également Webauthn (clé de sécurité) et OTP (Mot de passe à usage unique). Il est possible de désactiver toutes ces authentifiactions exotiques depuis le fichier de configuration de Dotclear, il suffit d'ajouter la définition suivante :

define('DC_AUTH_PASSWORD_ONLY', true);

Pour les plugins, li est possible de connaitre l'état de cette directive afin de désactiver certaines de leurs fonctions avec :

$limited = App:config()->authPasswordOnly();

[2.36] Modification des composants HTML

Jean-Christian Denis — Wed, 20 Aug 2025 00:33:00 +0200

Un nouvel attribut download fait son apparition dans les composants HTML.

Le composant Link se dote d'un nouvel attribut qui va permettre d'indiquer au navigateur que la cible peut être téléchargée.

echo (new Link)
    ->href('/public/DotclearWatch_logo.png')
    ->text('Télécharger le logo')
    ->download(true)
    ->render();

echo (new Link)
    ->href('/public/DotclearWatch_logo.png')
    ->text('Télécharger le logo')
    ->download('logo.svg')
    ->render();

La valeur de l'attribue peut être :

Un booleen pour que la balise ait ou non l'attribue download
Un nom de fichier qui sera proposé lors du téléchargement

La plupart des navigateurs supporte cette attribut. Mais attention il risque d'être sans effet si le lien pointe vers une origine distante car il suit la régle de Same-Origin Policy.

[2.36] Gestion de jeton utilisateur

Jean-Christian Denis — Tue, 19 Aug 2025 15:26:00 +0200

Avec l'arrivée des connexions exotiques sur la version 2.36, Dotclear embarque une nouvelle table dans la base de données accompagnée de sa classe de gestion.

Les jetons d'accés des utilisateurs à des services tiers doivent pouvoir être gérés par utilisateur mais également par service, les tables existantes de Dotclear ne proposaient pas de solution adéquate. Une nouvelle table credential et sa classe App::credential() sont donc disponibles depuis Dotclear 2.36.

Préambule

La classe de gestion de jeton est très classique de ce qui se fait dans Dotclear.
La classe est toujours disponible directement dans Dotclear.
Si un utilisateur est supprimé, ses jetons seront également supprimés (cascade)
Si un blog est supprimé les jetons qui lui sont liés seront également supprimés (cascade)

Attention : Les données sont cryptées avant d'être enregistrées dans la base de données, si vous perdez la "Master Key" de votre installation, toutes ces données seront illisibles et donc perdues.

Schéma de la table


$structure->credential
            ->field('user_id', 'varchar', 32, false)
            ->field('blog_id', 'varchar', 32, true, null)
            ->field('credential_dt', 'timestamp', 0, false, 'now()')
            ->field('credential_type', 'varchar', 32, false)
            ->field('credential_value', 'varchar', 255, false, "''")
            ->field('credential_data', 'text', 0, true, null)

            ->unique('uk_credential', 'credential_type', 'user_id', 'blog_id', 'credential_value')


$structure->credential
            ->index('idx_credential_user_id', 'btree', 'user_id');
$structure->credential
            ->index('idx_credential_blog_id', 'btree', 'blog_id');
$structure->credential
            ->reference('fk_credential_user', 'user_id', 'user', 'user_id', 'cascade', 'cascade')
$structure->credential
            ->reference('fk_credential_blog', 'blog_id', 'blog', 'blog_id', 'cascade', 'cascade');

Définition de son interface


namespace Dotclear\Interface\Core;

use ArrayObject;
use Dotclear\Database\Cursor;
use Dotclear\Database\MetaRecord;

/**
 * @brief   User credentials handler interface.
 *
 * Use this class to store user credential
 * for third party applications.
 *
 * @author  Jean-Christian Paul Denis
 * @since   2.36
 */
interface CredentialInterface
{
    /**
     * Credential table name.
     *
     * @var    string  CREDENTIAL_TABLE_NAME
     */
    public const CREDENTIAL_TABLE_NAME = 'credential';

    /**
     * Open a credential database table cursor.
     *
     * @return  Cursor  The credential database table cursor
     */
    public function openCredentialCursor(): Cursor;

    /**
     * Get credentials.
     *
     * @param      array<string, mixed>|ArrayObject<string, mixed>  $params      The parameters
     *
     * @return     MetaRecord  The users.
     */
    public function getCredentials(array|ArrayObject $params = []): MetaRecord;

    /**
     * Set user credential.
     *
     * @param     string     $user_id     The user ID
     * @param     Cursor     $cur         The credential Cursor
     */
    public function setCredential(string $user_id, Cursor $cur): void;

    /**
     * Delete credentials.
     *
     * If <var>$global</var> is set to False, current blog is selected.
     *
     * @param   string          $credential_type    The credential type
     * @param   string          $credential_value   The credential value
     * @param   null|string     $user_id            The user_id (or null for all users)
     * @param   bool            $global             True for global or false for current blog
     */
    public function delCredentials(string $credential_type, string $credential_value = '', ?string $user_id = null, bool $global = true): void;

    /**
     * Encrypt data.
     *
     * This is used to protect sensible data in database.
     * Data encryption is linked to Dotclear's master key.
     *
     * @param   ArrayObject<string, mixed>|array<string, mixed>     $data   The credential data to encode
     *
     * @return  string  The encoded credential data
     */
    public function encryptData(array|ArrayObject $data): string;

    /**
     * Decrypt data.
     *
     * Decode data encoded with self::encreyptData()
     *
     * @param   string  $data   The encoded credential data
     *
     * @return  array<string, mixed> The decoded credential data
     */
    public function decryptData(string $data): array;
}

Recherche de jetons

Les paramètres de recherche de la méthode getCredentials() sont :

user_id : optionnel : l'utilisateur du jeton
blog_id : optionnel : la blog courant (si ommit ce sera global)
credential_type : optionnel : généralement le nom du service associé au jeton (si ommit ce sera "webauthn")
credential_value : optionnel : une valeur mise en avant du jeton
order : optionnel : parametre de trie
limit : optionnel : limite de nombre de résultats

Les données du champs credential_data sont cryptées lors de l'enregistrement d'un champs, pour les décrypter il faut utiliser la méthode $rs->getAllData(); de l'enregistrement retourné.

$rs = App::credential()->getCredentials([
    'credential_type' => 'plop',
    'user_id' => App::auth()->userID(),
]);
if (!$rs->isEmpty()) {
    // tableau complet du jeton
    $data = $rs->getAllData();
    // ou
    $un_morceau_de_jeton = $rs->getData('un_morceau_de_jeton');
}

Ajout de jeton

L'ajout du jeton se fait à la manière de Dotclear, en ouvrant un curseur et en y incluant les informations qu'on désire.

$cur = App::credential()->openCredentialCursor();
$cur->setField('blog_id', App::blog()->id());
$cur->setField('credential_type', 'mon_service');
$cur->setField('credential_value', 'XYZEFFRE1234');
$cur->setField('credential_data', new ArrayObject($mon_tableau_du_jeton));
App::credential()->setCredential((string) App::auth()->userID(), $cur);

On remarque que pour le champs credential_data on crée un objet, cela permet de le manipuler dans la classe credential et de pouvoir le crypter lors de l'enregistrement dans la base de données.

Supression de jeton

Le suppression de jetons se fait en empilant les critères suivant :

credential_type : obligatoire.
credential_value : obligatoire, si ommit on cherche une valuer vide
user_id : optionnel
global : si vrai on recherche une valeur null de blog, si faux on recherche le blog courant

App::credential()->delCredentials(
    'mon_service',
    'une_clé',
    null,
    false
);

Dans cet exemple on supprimer le jeton de valeur 'une_clé' de type 'mon_service' sur le blog courant et peu importe l'utilisateur.

Conclusion

Rien d'extraordinaire sur cette classe, il suffit juste de réspecter les quelques recommandations présenteés ici.

[2.36] Authentification à deux facteurs

Jean-Christian Denis — Tue, 19 Aug 2025 14:46:00 +0200

La version 2.36 de Dotclear possède une librairie OTP (One Time Password) qui sera utiliser pour l'authentification à deux facteurs (2fa) à l'aide d'outils tels que Google Authenticator.

Il n'y a aucune configuration pour l'authentification à deux facteurs et le protocole TOTP sera le seul proposé. Une classe unique compose la librairie de gestion OTP (One Time Password) proposant les deux facettes de ce protocole qui sont par temps TOTP ou par compteur HOTP. Une seconde classe vient surcharger celle-ci pour coller à la partie backend de Dotclear qui utilise TOTP.

Dans le premier onglet des préférences utilisateur une partie est dédiée à l'Authentification à deux facteurs. Si l'utilisateur n'a pas encore vérifié un code alors l'authentification pour cette utilisateur est désactivé.

Il faut scanner avec son téléphone mobile (par exemple) le QR code, cela va ouvrir l'application d'authentification et propser un code qu'il faudra renseigner dans le formulaire pour activer le 2FA (Authentification à deux facteurs). Si aucune application d'authentification n'est présente sur le téléphone il faut en installer une, Microsoft Authenticator, Google Authenticator, etc...

Si un code est vérifié, l'authentification à deux facteurs lui sera demander uniquement lors de la phase d'authentification par login et mot de passe (pas pour les éventuelles autres méhodes).

Si l'utilisateur à perdu le générateur de code sur sont téléphone mobile, il est alors obligé de suivre la procédure de perte de mot de passe de Dotclear qui désactivera l'authentification à deux facteurs. Il peut également desactiver cette authentification dans les préferences utilisateur. Il peut également y générer une nouveau secret qu'il faudra alors à nouveau scanner dans son application.

[2.36] Gestion de session

Jean-Christian Denis — Tue, 19 Aug 2025 14:38:00 +0200

La version 2.36 de Dotclear modifie le fonctionnement des sessions.

Backend

Précedement, les sessions coté admin (backend) n'existait que lorsqu'on en avait besoin, c'est à dire lorsque l'utilisateur était connu. On pouvait donc faire simplement un test d'existence de session pour diveses routines. Mais depuis la version 2.36, les sessions sont toujours démarrées et existantes. Et peuvent donc être vide et sans valeur de test.

Frontend

Coté publique, les sessions fournies par Dotclear n'existait tout simplement pas avant la version 2.36. Depuis si un plugin veut utiliser des sessions coté publique, une simple ligne de code suffira à la démarrer.

App::session()->start();

Et si plusieurs plugins utilisent de session coté publique, chacun ajoutera cette ligne de code. Pas de soucis à l'appeler plusiseurs fois, elle teste qu'elle a déjà été appelé. Ce nouveau systeme de session commune coté publique risque de poser problème avec de vieux plugins pas à jour utilisant leurs propres sessions, ce qui provoquera des erreurs assez fatales ! Un bien pour un mal, car avec la 2.36 on met tout le monde d'accord.

Sans me faire de pub (qui risque plutôt de m'apporter des problèmes) un plugin FrontendSession propose de gérer les sessions coté publique avec tous les points d'entrée nécessaire à d'autres plugins. Widget, formulaire de login, menu utilisateur, page de gestion des options publique de l'utilisateur, etc...

[2.36] Mode dévelopement pour l'éditeur de thème

Jean-Christian Denis — Tue, 19 Aug 2025 11:34:00 +0200

Dotclear 2.35 introduisait une nouvelle gestion de surcharge de thèmes, et dans le version 2.36 une option de mode de dévelopement fait son appartition dans l'éditeur de thème.

Le nouveau behavior themeEditorDevMode, si il retourne vrai, permet de modifier sur place les fichiers d'un thème dans l'éditeur de thème.

Il suffit de l'activer en appelant le beharvior comme suit :

App::behavior()->addBehavior('themeEditorDevMode', fn(): bool => true);

Un message apparaitra lors de la modification d'un thème.

Le plugin tidyAdmin dans sa version pour Dotclear 2.36 propose une option pour faire cela depuis l'interface utilisateur.

[2.36] Connexion par clé de sécurité

Jean-Christian Denis — Tue, 19 Aug 2025 11:24:00 +0200

La version 2.36 de Dotclear introduit une librairie webauthn permettant d'utiliser des clés de sécurité pour s'authentifier à la partie administration.

Le protocole webauthn fait partie de l'API Credential Management des navigateurs web., il est donc lié à ce que va embarquer le navigateur de l'utilisateur, mais la plupart d'entre eux supportent très bien ce protocole. Le principe consiste à enregistrer dans les préférences utilisateur de Dotclear un mateirel physique comme une clé USB (passkey) ou une application comme 1Password, puis utiliser ce materiel par la suite pour s'identifier sur Dotclear sans rentrer de login ni mot de passe. A noter que cette fonction nécessite l'activation de javascript et du service Rest de Dotclear.

Exemple avec une clé de sécurité physique.

On commence par enregistrer notre clé, pour cela dans le premier onglet des préférences utilisateur du tableau de bord de Dotclear, vous trouverez un encart nommé Clés d'authentification, l'appuie sur le bouton Enregistrer une nouvelle clé lancera la procédure.

Suivant le navigateur, ses extensions et votre matriel, il va vous proposer divers choix, pour l'exemple on choisie Clé de sécurité.

Comme on va se servir de la clé pour nous authentifier il va nous avertir de tout cela.

Puis, toujours parce qu'on utilise la clé pour s'authentifier, il demande de valider avec le code PIN de la clé.

Ensuite c'est une clé physique avec validation de présence, il faut donc appyuer sur la clé pour montrer qu'on est présent vers la clé.

Enfin dernière étape qu'il ne faut surtout pas manquer, c'est la validation finale qui confirme qu'on a bien suivi la procédure et qui ensuite va enregistrer la clé dans Dotclear.

Tout cela peut paraitre long, mais si tout se passe bien on ne devrait avoir à la faire qu'une fois pour toute.
Voila notre clé est enregistré, on peut tester de s'authentifier à la page de login de Dotclear.

Un appuie sur le bouton Se connecter avec une clé d'accès lancera la procédure.

On choisi le type de clé, dans notre exemple nous avons enregistré une Clé de sécurité.

Comme il s'agit d'authentification, il nous est demandé le code PIN de la clé.

Et comme il s'agit du clé avec validation de présence, il faut alors toucher la clé.

Une fois fait, on devrait voir apparaitre automatiquement le tableau de bord de Dotclear !

Exemple avec l'extension de navigateur 1password

L'exetnsion 1password s'intègre dans le navigateur et agit comme une clé de sécurité, à ceci prêt que la procédure est encore plus rapide.

On recommence la procedure depuis le premier onlget des préférences utilisateur, et on appuie sur Enregistrer une nouvelle clé.

Un encart dans le coin du navigateur nous invite à enregistrer 1password comme clé. (On peut également choisir d'utiliser une autre clé de sécurite en clqiuant sur la petite clé en haut à droite.)

On enregistre, et c'est tout ! L'extension sera notre clé d'authentification.

Maintenant on teste de s'authentifier à la partie administration, un appui sur le bouton Se connecter avec un clé d'accès lancera la procédure.

Et l'extension va automatiquement nous proposer de nous authentifier.

On appuie sur connexion et on devrait voir apparaitre le tableau de bord de Dotclear ! Rapide.

Autres

Il existe d'autres materiels et d'autres logiciels, par exemple utiliser son téléphone en bluetooth comme clé d'accès. Le choix est vaste, chacun prendre la solution qui lui convient.

2.36

Jean-Christian Denis — Tue, 19 Aug 2025 11:00:00 +0200

La prochaine version de Dotclear apportera une touche de modernité dés la page d'authentification.

Nouveau format de billet de présentation pour cette version 2.36 qui va détailler chaque changements techniques.
Ce billet évoluera jusqu'a la sortie de la 2.36.

Résumé

Cette version modifie le fonctionnement des sessions coté admin (backend) et coté public (frontend) ce qui lui permet de proposer de nouveaux outils comme l'authentification par des applications et materiels tiers et la gestion d'utilisteur coté public. A noter l'arrivé de nouveaux supports de drivers de base de données basé sur PDO. Et bien plus encore, avec la correction de bugs et le renforcement des Tests Unitaires.

Nouveautés

Nouveau mode dévelopement pour l'éditeur de thème
Nouvel attribue download du composant Link
Nouvelle gestion de jeton utilisateur
Nouvelle authentification à deux facteurs OTP
Nouvelle connexion par clé de sécurité Webauhtn
Nouvelle connexion par application tierce oAuth2
Nouvelles directives de configuration
Nouveau service d'accès à la base de données
Nouveaux drivers de base de données basés sur PDO
Nouveau mode d'installation en CLI
Nouvelle classe de description de média MediaFile
Nouveau behavior adminPageHTMLBody

Changements

Modification de la gestion de session
Modification de l'appel à la connexion à la base de donnée
Modification des Utility et Process
Modification des contructeurs de classes de premier niveau
Modification de l'appel aux services d'un container
Passage des tests unitaires existants de Atoum ver PHPUnit
La classe File ne supporte plus les propriétés dynamiques

Dépréciés

Voir le détail des changements ci-dessus
Pas de nouveaux dépréciés dans cette version

Retirés

La méthode App::media()::flvplayer() dépréciée depuis Dotclear 2.15 est définitivement retirée en 2.36.
La méthode App::media()::getFSDir() est retirée en 2.36
La méthode ThemeConfig::cleanCss() est retiré en 2.36
Suppression de l'utilisation de iconv() remplacé par mb_convert_encoding(). (Voir Text::toUTF8() )
Supression de l'ancienne méthode dcCore::app()->spamFilters (Voir le behavior AntispamInitFilters)

...