DotclearWatch / Blog - Mot-clé - 2.28

Sortie de Dotclear 2.28

Jean-Christian Denis — Wed, 15 Nov 2023 18:25:00 +0100

Ce mercredi 15 Novembre 2023 sort la version 2.28 du moteur de blogs Dotclear.

Comme dit dans le billet d'annonce officielle et dans la description de version sur ce blog, cette version finit la transition du moteur vers les espaces de noms PHP et passe les prérequis vers PHP 8.1 minimum. A noter que d'après les premiers essais, elle supporte très bien PHP 8.2 et 8.3.
Cette mise à jour chamboule encore beaucoup le code et il est fortement conseillé de la faire en mode sans échec.

Prévisions de la 2.28

Jean-Christian Denis — Fri, 13 Oct 2023 08:01:00 +0200

Un mois avant la sortie de Dotclear 2.28 prévue autour du 13 novembre 2023.

une série de billets pour se familiariser avec les nombreuses avancées apportées par cette version est disponible sur dotclear.watch.
Il reste un mois (ou plus) avant la sortie de la version stable, certaines informations distillées dans ces billets peuvent encore évoluer d'ici là, ils seront donc mis à jour en temps réel si besoin.

Les exceptions de premier niveau

Jean-Christian Denis — Fri, 13 Oct 2023 08:00:00 +0200

La version 2.28 apporte une nouvelle gestion des exceptions et erreurs de premier niveau,

Après quelques balbutiements en version 2.27, une première avancée dans la gestion et la reconnaissance plus fine des erreurs bloquantes de l'application est introduite en version 2.28. Avec l'ajout d'une classe spéciale au gestionnaire d'erreur PHP, la majorité des erreurs générées par la racine de l'application ou de son cœur est désormais interceptée par des classes d'exception renvoyant un code et un message unique. Tous ces codes et messages sont regroupés dans un énumérateur. Les exceptions sont si possible traitées suivant différents paramètres (mode debug, mode CLI...) puis renvoyées à l'utilisateur.

Fault class in debug mode

Liste d'erreurs :

susceptible de changer dans les versions à venir

503 : AppException : Site temporarily unavailable
400 : BadRequestException : Bad Request
570 : BlogException : Blog handling error
551 : ConfigException : Application configuration error
409 : ConflictException : Conflict
553 : ContextException : Application context error
560 : DatabaseException : Database connection error
404 : NotFoundException : Not Found
412 : PreconditionException : Precondition Failed
552 : ProcessException : Application process error
561 : SessionException : Session handling error
571 : TemplateException : Template handling error
401 : UnauthorizedException : Unauthorized
500 : InternalServerException : Internal Server Error

Deux grandes catégories sont présentes avec :

4xx : Erreur client
5xx : Erreur serveur

Traitement

Les exceptions et erreurs interceptées par l'application sont alors envoyées à la classe Fault pour traitement et affichage à l'utilisateur. Il est possible d'intervenir avant l'affichage en définissant dans la constante DC_ERRORFILE un fichier à appeler, ce fichier php aura accès à toute la classe Fault.
Si la plateforme à déjà déclaré un gestionnaire d'exception à PHP, il sera alors utilisé.

Incompatibilité

Les méthodes de la classe Fault introduites en version 2.27 sont déjà obsolètes et tout simplement supprimées.

Le contenu de ce document a été écrit suivant le code de la version 2.28 de Dotclear.

Les dépréciés

Jean-Christian Denis — Fri, 13 Oct 2023 08:00:00 +0200

La version 2.28 de Dotclear apporte son lot de dépréciés.

Core

Toutes les méthodes de la classe principale du cœur de Dotclear (dcCore) passent en dépréciées, une page spéciale est dédiée à ces dépréciés.

Constantes

Les constantes suivantes sont dépréciées, il faut utiliser le système de service du Core :

DC_AUTH_CLASS => doit remplacer le service AuthInterface::class
DC_DBHANDLER_CLASS => doit remplacer le service ConnectionInterface::class
DC_DBSCHEMA_CLASS => doit faire partie de la classe de Connection, et être fourni par App::con()->schema()

Pour les autres constantes, il faut utiliser la nouvelle classe de configuration.

Blog

Toues les propriétés public de la classe dcBlog (devenu Blog et accessible par App:blog() ) sont désormais dépréciées et ont une nouvelle méthode associée. (voir la partie Blog de l'article sur le conteneur principale.)

Utils

Toute la classe dcUtils et ses méthodes passent en dépréciées. La version 2.28 ajoute ces derniers dépréciés :

dcUtils::ADMIN_LOCALE => App::lexical()::ADMIN_LOCALE
dcUtils::PUBLIC_LOCALE => App::lexical()::PUBLIC_LOCALE
dcUtils::CUSTOM_LOCALE => App::lexical()::CUSTOM_LOCALE
dcUtils::path() => Path::reduce()
dcUtils::getUserCN() => App::users()->getUserCN()
dcUtils::cleanIds() => App::blogs()->cleanIds()
dcUtils::versionsCompare() => App::plugins()->versionsCompare()
dcUtils::cssLoad() => App::plugins()->cssLoad()
dcUtils::jsLoad() => App::plugins()->jsLoad()
dcUtils::jsJson() => Html::jsJson()
dcUtils::lexicalSort() => App::lexical()->lexicalSort()
dcUtils::lexicalArraySort() => App::lexical()->lexicalArraySort()
dcUtils::lexicalKeySort() => App::lexical()->lexicalKeySort()
dcUtils::setLexicalLang() => App::lexical()->setLexicalLang()
dcUtils::removeDiacritics() => Text::removeDiacritics()

Autres

Quelques changements de noms de méthodes et passages de propriétés à méthodes

App::release(xxx) => App:config()->release(xxx) ou App:config()->yyy()
dcCore::app()->blog()->settings->addNamespace() => App::blog()->settings()->addWorspace()
dcCore::app()->blog()->settings->renNamespace() => App::blog()->settings()->renWorkspace()
dcCore::app()->blog()->settings->delNamespace() => App::blog()->settings()->delWorkspace()
dcCore::app()->blog()->settings->dumpNamespaces() => App::blog()->settings()->dumpWorkspaces()
dcCore::app()->blog()->settings->xxx->dumpNamespace() => App::blog()->settings()->get('xxx')->dumpWorkspace()
dcCore::app()->error->toHTML() => utiliser son propre parser
dcCore::app()->notices->delNotices() => App::notice()->delNotice() ou App::notice()->delSessionNotices()
dcCore::app()->media->root => App::media()->getRoot()
dcCore::app()->media->root_url => App::media()->getRootUrl()
dcCore::app()->media->dir => App::media()->getDirs() ou App::media()->getFiles()
dcCore::app()->media->thumb_tp => App::media()->getThumbnailFilePattern()
dcCore::app()->media->thumb_tp_alpha => App::media()->getThumbnailFilePattern('alpha')
dcCore::app()->media->thumb_tp_webp => App::media()->getThumbnailFilePattern('webp')
dcCore::app()->media->thumb_sizes => App::media()->getThumbnailCombo()
dcCore::app()->log->getTable() => App::log()::LOG_TABLE_NAME
dcCore::app()->widgets => Widgets::$widgets
dcCore::app()->ctx => App::frontend()->context()
dcCore::app()->tpl => App::frontend()->template()
dcCore::app()->adminurl => App::backend()->url()
dcCore::app()->favs => App::backend()->favorites()
dcCore::app()->menu => App::backend()->menus()
dcCore::app()->resources => App::backend()->resources()

Déplacement

Voir les nombreuses classes déplacées.

Le contenu de ce document a été écrit suivant le code de la version 2.28 de Dotclear.

Permissions de modules

Jean-Christian Denis — Fri, 13 Oct 2023 08:00:00 +0200

Dans la version 2.28 de Dotclear, la classe My d'aide aux modules peut gérer complètement leurs permissions.

Depuis quelques versions de Dotclear une aide au développement des modules (plugins et thèmes) est disponible, elle est depuis bien utilisée par les modules de la distribution et par nombre de modules tiers. La version 2.28, complète la classe My en lui ajoutant une nouvelle constante de contexte appelée MODULE. Celle-ci va permettre de supprimer la difficulté d'utiliser des classes dans le fichier _define.php en déplaçant la partie permissions de ce fichier.
Pour déplacer ces permissions et s'affranchir d'appels de classe hasardeux, il suffit d'indiquer dans le fichier _define.php du module qu'on déporte la gestion de permissions, puis dans le fichier My de vérifier ces permissions.

Premier exemple

Exemple du fichier \_define.php du plugin attachments de la distribution :

<?php
use Dotclear\App;

$this->registerModule(
    // ...
    [
        // On indiquait la nécessité des droits usage, content admin ou pages pour utiliser ce plugin
        'permissions' => App::auth()->makePermissions([
            App::auth()::PERMISSION_USAGE,
            App::auth()::PERMISSION_CONTENT_ADMIN,
            initPages::PERMISSION_PAGES,
        ]),
        // ...
    ]
);

Qui deviendra simplement :

<?php
$this->registerModule(
    // ...
    [
        'requires'    => [['pages']],
        // On indique qu'on délègue à la class My la gestion des droits
        'permissions' => 'My',
        // ...
    ]
);

Plus de problème d'appel de classe potentiellement inexistante ici, puisqu'on va tester la disponibilité de module requis avec la directive requires avant de vouloir utiliser sa classe. Mais il faut bien tester les droits qu'on a enlevés, pour cela on va ajouter une règle dans le fichier \src\My.php du module :

<?php
declare(strict_types=1);

namespace Dotclear\Plugin\attachments;

use Dotclear\App;
use Dotclear\Module\MyPlugin;
use Dotclear\Plugin\pages\Pages;

class My extends MyPlugin
{
   // On va gérer des droits particuliers
    public static function checkCustomContext(int $context): ?bool
    {
       // On recherche le contexte de droit
        return match($context) {
            // On utilise le nouveau contexte de droit global pour autoriser un utilisateur avec les droits sur les billets et les pages
            // Attention ici le test demande si on est côté admin avec des droits ou côté public sans besoin de droits !
            self::MODULE => !App::task()->checkContext('BACKEND')
                || (
                    App::blog()->isDefined()
                    && App::auth()->check(App::auth()->makePermissions([
                        App::auth()::PERMISSION_USAGE,
                        App::auth()::PERMISSION_CONTENT_ADMIN,
                        Pages::PERMISSION_PAGES,
                    ]), App::blog()->id())
                ),

            // Pour tous les autres contextes, on laisse les droits par défaut
            default => null,
        };
    }
}

On voit ici que du fait de cette nouvelle gestion, les constantes de module comme les permissions ou les noms de tables de bases de données n'ont plus besoin d'être dans un fichier spécial à la racine du module puisque dorénavant on teste ces permissions après le chargement des modules et donc on a accès à toutes les classes des modules pour les tests. Les constantes de permissions et de tables des modules de la distribution ont donc été déplacés dans leurs classes principales, c'est le cas de Antispam, Blogroll et Pages.

Second exemple

Exemple du fichier \_define.php du plugin tags de la distribution :

<?php
use Dotclear\App;

$this->registerModule(
    // ...
    [
        'permissions' => 'App::auth()->makePermissions([
                    App::auth()::PERMISSION_USAGE,
                    App::auth()::PERMISSION_CONTENT_ADMIN,
                ])',
        // ...
    ]
);

Qui deviendra simplement :

<?php
$this->registerModule(
    // ...
    [
        'permissions' => 'My',
        // ...
    ]
);

Quand au fichier \src\My.php du module, il ne changera pas puisqu'on vérifiait déjà ces droits :

<?php
declare(strict_types=1);

namespace Dotclear\Plugin\tags;

use Dotclear\App;
use Dotclear\Module\MyPlugin;

class My extends MyPlugin
{
    public static function checkCustomContext(int $context): ?bool
    {
        return match ($context) {
            // On indique que la page de gestion et le menu sont autorisés à un utilisateur ayant les droits usage ou content admin
            // On n'a pas eu besoin de changer quoi que ce soit ici
            self::MANAGE, self::MENU => App::task()->checkContext('BACKEND')
                && App::blog()->isDefined()
                && App::auth()->check(App::auth()->makePermissions([
                    App::auth()::PERMISSION_USAGE,
                    App::auth()::PERMISSION_CONTENT_ADMIN,
                ]), App::blog()->id()),

            default => null,
        };
    }
}

Un petit tour dans les fichiers My des plugins de la distribution donnera un bon aperçu des différents cas possibles.

Le contenu de ce document a été écrit suivant le code de la version 2.28 de Dotclear.

Configuration de l'application

Jean-Christian Denis — Fri, 13 Oct 2023 08:00:00 +0200

La version 2.28 de Dotclear ajoute une nouvelle classe de visualisation de sa configuration..

Auparavant il fallait chercher les différentes ressources de configuration de Dotclear un peu partout, dans les fichier index, dans le fichier de config, dans des constantes, etc. Depuis la version 2.28, toutes ces informations sont accessibles depuis une seule classe et ses méthodes. Cette classe n'est pas modifiable, n'est pas remplaçable, aucune de ses propriétés n'est accessible. Elle va récupérer toutes les informations, notamment depuis le fichier config.php (qui ne change pas), les traiter et les proposer via ses méthodes avec un typage de retour strict et défini. Elle va également faire les premières vérifications de ces valeurs.
Il n'est plus utile de lire les constantes de Dotclear, toutes les constantes de la version 2.27 existent toujours mais ont leurs méthodes associées en 2.28 dans App::config(), de part ce fait ces valeurs existent toujours et ont un type fixe ce qui facilite leurs utilisations.

Liste des informations disponibles :

startTime(): float; ~~DC_START_TIME~~
cliMode(): bool; ~~CLI_MODE~~
debugMode(): bool; ~~DC_DEBUG~~
devMode(): bool; ~~DC_DEV~~
errorFile(): string; ~~DC_ERRORFILE~~
blogId(): string; ~~DC_BLOG_ID~~
dotclearRoot(): string; ~~DC_ROOT~~
dotclearVersion(): string; ~~DC_VERSION~~
dotclearName(): string; ~~DC_NAME~~
hasConfig(): bool;
configPath(): string; ~~DC_RC_PATH~~
digestsRoot(): string; ~~DC_DIGESTS~~
l10nRoot(): string; ~~DC_L10N_ROOT~~
l10nUpdateUrl(): string; ~~DC_L10N_UPDATE_URL~~
distributedPlugins(): string; ~~DC_DISTRIB_PLUGINS~~
distributedThemes(): string; ~~DC_DISTRIB_THEMES~~
defaultTheme(): string; ~~DC_DEFAULT_THEME~~
defaultTplset(): string; ~~DC_DEFAULT_TPLSET~~
defaultJQuery(): string; ~~DC_DEFAULT_JQUERY~~
minRequiredPhp(): string;
minRequiredMysql(): string;
minRequiredPgsql(): string;
nextRequiredPhp(): string; ~~DC_NEXT_REQUIRED_PHP~~
vendorName(): string; ~~DC_VENDOR_NAME~~
xmlrpcUrl(): string; ~~DC_XMLRPC_URL~~
sessionTtl(): ?string; ~~DC_SESSION_TTL~~
sessionName(): string; ~~DC_SESSION_NAME~~
adminSsl(): bool; ~~DC_ADMIN_SSL~~
adminUrl(): string; ~~DC_ADMIN_URL~~
adminMailfrom(): string; ~~DC_ADMIN_MAILFROM~~
dbDriver(): string; ~~DC_DBDRIVER~~
dbHost(): string; ~~DC_DBHOST~~
dbUser(): string; ~~DC_DBUSER~~
dbPassword(): string; ~~DC_DBPASSWORD~~
dbName(): string; ~~DC_DBNAME~~
dbPrefix(): string; ~~DC_DBPREFIX~~
dbPersist(): bool; ~~DC_DBPERSIST~~
masterKey(): string; ~~DC_MASTER_KEY~~
cryptAlgo(): string; ~~DC_CRYPT_ALGO~~
coreUpdateUrl(): string; ~~DC_UPDATE_URL~~
coreUpdateCanal(): string; ~~DC_UPDATE_VERSION~~
coreNotUpdate(): bool; ~~DC_NOT_UPDATE~~
allowMultiModules(): bool; ~~DC_ALLOW_MULTI_MODULES~~
storeNotUpdate(): bool; ~~DC_STORE_NOT_UPDATE~~
allowRepositories(): bool; ~~DC_ALLOW_REPOSITORIES~~
allowRestServices(): bool; ~~DC_REST_SERVICES~~
cacheRoot(): string; ~~DC_TPL_CACHE~~
varRoot(): string; ~~DC_VAR~~
backupRoot(): string; ~~DC_BACKUP_PATH~~
coreUpgrade(): string; ~~DC_UPGRADE~~
pluginsRoot(): string; ~~DC_PLUGINS_ROOT~~
maxUploadSize(): int; ~~DC_MAX_UPLOAD_SIZE~~
queryTimeout(): int; ~~DC_QUERY_TIMEOUT~~
showHiddenDirs(): bool; ~~DC_SHOW_HIDDEN_DIRS~~
httpScheme443(): bool; ~~DC_FORCE_SCHEME_443~~
httpReverseProxy(): bool; ~~DC_REVERSE_PROXY~~
checkAddBlocker(): bool; ~~DC_ADBLOCKER_CHECK~~
cspReportFile(): string; ~~DC_CSP_LOGFILE~~

Pour en savoir plus sur la signification de ces méthodes, il est recommandé de lire le contenu du fichier src/Interface/ConfigInterface.php. (Visible sur le dépôt git.)
Pour accéder à une de ces valeurs, il suffit de faire App::config()->cacheRoot();.

Attention

Là où souvent il fallait tester la présence d'une valeur, par exemple :
if (defined('DC_DEFAULT_TPLSET')) { $tpl = DC_DEFAULT_TPLSET; }
Désormais cette valeur existe toujours, on peut éventuellement tester si elle est vide :
if (!empty(App::config()->defaultTplset())) { }.

dcCore déprécié

Jean-Christian Denis — Fri, 13 Oct 2023 08:00:00 +0200

Dans la version 2.28 de Dotclear, la classe historique du moteur de blog, alias dcCore, passe en dépréciée.

La classe dcCore, le cœur de Dotclear n'est plus. Cette classe, avec toutes ses propriétés et méthodes, passe en déprécié au profit d'un nouveau système utilisant un simple conteneur de classe.

Resources

dcCore::app()->resources => App::backend()->resources()

Le tableau des ressources d'aide de l'interface d'administration est remplacé par une nouvelle classe \Dotclear\Core\Backend\Resources et se déplace vers le Backend. Pour ajouter une ressource depuis un thème ou plugin, cela se fait toujours depuis le fichiers locales/xx/resources.php mais on doit désormais utiliser une méthode de la nouvelle classe qui est instanciée dans App::backend()->resources().
Exemple du plugin aboutConfig de la distribution :

// Avant :
// if (!isset(dcCore::app()->resources['help']['aboutConfig'])) {
//    dcCore::app()->resources['help']['aboutConfig'] = __DIR__ . '/help/help.html';
//}
// à remplacer par :
\Dotclear\App::backend()->resources()->set('help', 'aboutConfig', __DIR__ . '/help/help.html');

Lang

dcCore::app()->lang => App::lang()->getLang()
dcCore::app()->lang = 'en' => App::lang()->setlang('en')

Behavior

Toutes les méthodes en rapport à la gestion des behaviors sont désormais dans une instance de classe Behavior.

dcCore::app()->addBehavior() => App::behavior()->addBehavior()
dcCore::app()->addBehaviors() => App::behavior()->addBehaviors()
dcCore::app()->hasBehavior() => App::behavior()->hasBehavior()
dcCore::app()->getBehaviors() => App::behavior()->getBehaviors()
dcCore::app()->getBehaviors(xxx) => App::behavior()->getBehavior(xxx)
dcCore::app()->callBehavior() => App::behavior()->callBehavior()

La méthode getBehaviors est scindée en deux pour obtenir un typage de retour de méthode plus propre. Les anciens alias en ou disparaissent.

Nonce

Toutes les méthodes en rapport à la gestion en base de Nonce sont désormais dans une instance de classe Nonce.

dcCore::app()->getNonce() => App::nonce()->getNonce()
dcCore::app()->checkNonce() => App::nonce()->checkNonce()
dcCore::app()->formNonce(true) => App::nonce()->getFormNonce()
dcCore::app()->formNonce(false) => App::nonce()->formNonce()

Cette dernière méthode est scindée en deux avec d'un coté le renvoi de l'élément Form\Hidden et de l'autre le renvoi du code HTML.

Version

Toutes les méthodes en rapport à la gestion des versions en base sont désormais dans une instance de classe Nonce.

dcCore::app()->getVersion() => App::version()->getVersion()
dcCore::app()->getVersions() => App::version()->getVersions()
dcCore::app()->setVersion() => App::version()->setVersion()
dcCore::app()->testVersion() => App::version()->compareVersion()
dcCore::app()->newVersion() => App::version()->newerVersion()
dcCore::app()->delVersion() => App::version()->unsetVersion()

Formater

Toutes les méthodes en rapport à la gestion des formateurs sont désormais dans une instance de classe Formater.

dcCore::app()->addEditorFormater() => App::formater()->addEditorFormater()
dcCore::app()->addFormater() => App::formater()->addEditorFormater('dcLegacyEditor', ...)
dcCore::app()->addFormaterName() => App::formater()->addFormaterName()
dcCore::app()->getFormaterName() => App::formater()->getFormaterName()
dcCore::app()->getEditors() => App::formater()->getEditors()
dcCore::app()->getFormaters() => App::formater()->getFormaters()
dcCore::app()->getFormaters(xxx) => App::formater()->getFormater(xxx)
dcCore::app()->callEditorFormater() => App::formater()->callEditorFormater()
dcCore::app()->callFormater() => App::formater()->callEditorFormater('dcLegacyEditor', ...)

La méthode getFormaters est scindée en deux pour retourner soit un formateur soit tous.
Les méthodes spécifiques à dcLegacyEditor, qui sont addFormater et callFormater, sont supprimées au profit des génériques addEditorFormater et callEditorFormater auxquelles il faudra indiquer le formateur dcLegacyEditor.

Wiki et HTML filter

Toutes les méthodes en rapport aux filtres wiki et HTML sont désormais dans un instance de classe Filter. De même pour la propriété wiki.

dcCore::app()->wiki => App::filter()->wiki()
dcCore::app()->wiki2xhtml => App::filter()->wiki()
dcCore::app()->wikiTransform() => App::filter()->wikiTransform()
dcCore::app()->initWikiPost() => App::filter()->initWikiPost()
dcCore::app()->initWikiSimpleComment() => App::filter()->initWikiSimpleComment()
dcCore::app()->initWikiComment() => App::filter()->initWikiComment()
dcCore::app()->wikiPostLink() => App::filter()->wikiPostLink()
dcCore::app()->HTMLfilter() => App::filter()->HTMLfilter()

Une modification bloquante a été introduite en utilisant l'état non initialisé des propriétés de classe, il ne faut plus tester si wiki est une instance de WikiToHtml mais si il existe, cela donne :

//avant :
//if (dcCore::app()->wiki instanceof WikiToHtml) { }

// Après :
if (isset(App::filter()->wiki)) { }

Ce cas se retrouve sur plusieurs autres appels, PHP vous indiquera que vous faites appel à une propriété non initialisée, il faudra alors utiliser isset().

Post types

Toutes les méthodes en rapport à la gestion des types de posts sont désormais dans une instance de classe PostTypes. Et un type de post n'est plus un tableau mais une classe de description PostType.

dcCore::app()->getPostAdminURL() => App::postTypes()->get(type)->adminUrl()
dcCore::app()->getPostPublicURL() => App::postTypes()->get(type)->publicUrl()
dcCore::app()->setPostType() => App::postTypes()->set(new PostType())
dcCore::app()->getPostTypes() => App::postTypes()->dump()

De plus, une nouvelle méthode est ajoutée pour tester si un type de post existe: App::postTypes()->exists(type).

Exemple du plugin pages de la distribution :

// Dans la méthode process() du fichier src/Prepend.php
App::postTypes()->set(new PostType(
    'page',
    '',
    App::url()->getURLFor('pages', '%s'),
    'Pages'
));
// Dans la méthode process() du fichier src/Backend.php
App::postTypes()->set(new PostType(
    'page',
    urldecode(My::manageUrl(['p' => 'pages', 'act' => 'page', 'id' => '%d'], '&')),
    App::url()->getURLFor('pages', '%s'),
    'Pages'
));

On remarque ici qu'on déclare deux fois le type de post, une fois dans le Prepend SANS la définition d'url admin car elle n'est pas encore accessible. Et une fois dans le fichier Backend AVEC la définition de l'url admin.

Blogs

Toutes les méthodes en rapport aux blogs sont désormais dans une instance de classe Blogs.

dcCore::app()->getAllBlogStatus() => App::blogs()->getAllBlogStatus()
dcCore::app()->getBlogStatus() => App::postTypes()s->getBlogStatus()
dcCore::app()->getBlogPermissions() => App::postTypes()->getBlogPermissions()
dcCore::app()->getBlog() => App::postTypes()->getBlog()
dcCore::app()->getBlogs() => App::postTypes()->getBlogs()
dcCore::app()->addBlog() => App::postTypes()->addBlog()
dcCore::app()->updBlog() => App::postTypes()->updBlog()
dcCore::app()->delBlog() => App::postTypes()->delBlog()
dcCore::app()->blogExists() => App::postTypes()->blogExists()
dcCore::app()->countBlogPosts() => App::postTypes()->countBlogPosts()

Users

Toutes les méthodes en rapport aux utilisateurs sont désormais dans une instance de classe Users.

dcCore::app()->getUser() => App::users()->getUser()
dcCore::app()->getUsers() => App::users()->getUsers()
dcCore::app()->addUser() => App::users()->addUser()
dcCore::app()->updUser() => App::users()->updUser()
dcCore::app()->delUser() => App::users()->delUser()
dcCore::app()->userExists() => App::users()->userExists()
dcCore::app()->getUserPermissions() => App::users()->getUserPermissions()
dcCore::app()->setUserPermissions() => App::users()->setUserPermissions()
dcCore::app()->setUserBlogPermissions() => App::users()->setUserBlogPermissions()
dcCore::app()->setUserDefaultBlog() => App::users()s->setUserDefaultBlog()
dcCore::app()->removeUsersDefaultBlogs() => App::users()->removeUsersDefaultBlogs()
dcCore::app()->userDefaults() => App::users()->userDefaults()

Cache

dcCore::app()->emptyTemplatesCache() => App::cache()->emptyTemplatesCache()
dcCore::app()->cache => App::cache()->xxx()

Autres

dcCore::app()::SESSION_TABLE_NAME => App::session()::SESSION_TABLE_NAME
dcCore::app()::VERSION_TABLE_NAME => App::version()::VERSION_TABLE_NAME
dcCore::app()->con() => App::con()
dcCore::app()->prefix => App::con()->prefix()
dcCore::app()->blog => App::blog()
dcCore::app()->auth => App::auth()
dcCore::app()->session => App::session()
dcCore::app()->url => App::url()
dcCore::app()->rest => App::rest()
dcCore::app()->wiki => App::filter()->wiki
dcCore::app()->plugins => App:plugins()
dcCore::app()->themes => App::themes()
dcCore::app()->media => App::media()
dcCore::app()->postmedia App::postMedia() App::media()->postMedia()
dcCore::app()->meta => App::meta()
dcCore::app()->error => App::error()
dcCore::app()->notices => App::notice()
dcCore::app()->log => App:log()
dcCore::app()->admin => App::backend()
dcCore::app()->adminurl => App::backend()->url()
dcCore::app()->favs => App::backend()->favorites()
dcCore::app()->menu => App::backend()->menus()
dcCore::app()->public => App::frontend()
dcCore::app()->tpl => App:frontend()->template()
dcCore::app()->ctx => App::frontend()->context()
dcCore::app()->spamfilters => Use AntispamInitFilters behavior
dcCore::app()->killAdminSession() => App::backend()->killAdminSession()
dcCore::app()->getAllBlogStatus() => App::blogs()->getAllBlogStatus()
dcCore::app()->getBlogStatus() => App::blogs()->getBlogStatus()
dcCore::app()->blogDefaults() => \Dotclear\Core\Install\Utils::blogDefault()
dcCore::app()->enableRestServer() => App::rest()->enableRestServer()
dcCore::app()->serveRestRequests() => App::rest()->serveRestRequests()

L'ancienne écriture des appels décrits dans cette page reste valable encore pour quelques versions en tant que dépréciée.

Le contenu de ce document a été écrit suivant le code de la version 2.28 de Dotclear.

Déplacement de classes

Jean-Christian Denis — Fri, 13 Oct 2023 08:00:00 +0200

La version 2.28 de Dotclear continuant la transition vers les espaces de noms PHP, la plupart des classes restantes dans le répertoire inc a été déplacée vers le dossier src.

Voici la liste des classes changeant de nom dans cette version.

Frontend :

    'dcTemplate'    => 'Dotclear\Core\Frontend\Tpl',
    'dcUrlHandlers' => 'Dotclear\Core\Frontend\Url',
    'context'       => 'Dotclear\Core\Frontend\Ctx',

    'rsExtPostPublic'    => 'Dotclear\Schema\Extension\PostPublic',
    'rsExtCommentPublic' => 'Dotclear\Schema\Extension\CommentPublic',

Core :

    'dcAuth' => 'Dotclear\Core\Auth',
    'dcBlog' => 'Dotclear\Core\Blog',
    'dcCategories'   => 'Dotclear\Core\Categories',
    'dcDeprecated' => 'Dotclear\Core\Deprecated',
    'dcError'        => 'Dotclear\Core\Error',
    'dcLog'          => 'Dotclear\Core\Log',
    'dcMedia'        => 'Dotclear\Core\Media',
    'dcMeta'         => 'Dotclear\Core\Meta',
    'dcModuleDefine' => 'Dotclear\Module\ModuleDefine',
    'dcModules'      => 'Dotclear\Module\Modules',
    'dcNamespace'    => 'Dotclear\Core\BlogWorkspace',
    'dcNotices'      => 'Dotclear\Core\Notice',
    'dcPlugins'   => 'Dotclear\Module\Plugins',
    'dcPostMedia'    => 'Dotclear\Core\PostMedia',
    'dcPrefs'        => 'Dotclear\Core\UserPreferences',
    'dcRestServer'   => 'Dotclear\Core\Rest',
    'dcSettings'     => 'Dotclear\Core\BlogSettings',
    'dcStore'       => 'Dotclear\Module\Store',
    'dcStoreParser' => 'Dotclear\Module\StoreParser',
    'dcStoreReader' => 'Dotclear\Module\StoreReader',
    'dcThemes'      => 'Dotclear\Module\Themes',
    'dcTrackback'    => 'Dotclear\Core\Trackback',
    'dcUpdate' => 'Dotclear\Core\Backend\Update',
    'dcWorkspace'    => 'Dotclear\Core\UserWorkspace',
    'dcXmlRpc' => 'Dotclear\Core\Frontend\XmlRpc',

    'rsExtPost'    => 'Dotclear\Schema\Extension\Post',
    'rsExtComment' => 'Dotclear\Schema\Extension\Comment',
    'rsExtDates'   => 'Dotclear\Schema\Extension\Dates',
    'rsExtUser'    => 'Dotclear\Schema\Extension\User',
    'rsExtBlog'    => 'Dotclear\Schema\Extension\Blog',

    'dcTraitDynamicProperties' => 'Dotclear\Helper\TraitDynamicProperties',

Nouvelles classes ;

Dotclear\Core\Blogs => App::blogs()
Dotclear\Core\Cache => App::cache()
Dotclear\Core\Filter => App::filter()
Dotclear\Core\Formater => App::formater()
Dotclear\Core\Nonce => App::nonce()
Dotclear\Core\PostType => new PostType(type, admin_url, public_url, label);
Dotclear\Core\PostTypes => App::postTypes()
Dotclear\Core\Users => App::users()
Dotclear\Core\Version => App::version()

Plugins

Avec la nouvelle gestion des permissions des modules, leurs constantes se sont déplacées

initBlogroll::PERMISSION_BLOGROLL => \Dotclear\Plugin\blogroll\Blogroll::PERMISSION_BLOGROLL
initBlogroll::LINK_TABLE_NAME => \Dotclear\Plugin\blogroll\Blogroll::LINK_TABLE_NAME
initAntispam::SPAMRULE_TABLE_NAME => \Dotclear\Plugin\antispam\Antispam::SPAMRULE_TABLE_NAME
initPages::PERMISSION_PAGES => \Dotclear\Plugin\pages\Pages::PERMISSION_PAGES

En savoir plus :

Le contenu de ce document a été écrit suivant le code de la version 2.28 de Dotclear.

Remplacer une classe de premier niveau

Jean-Christian Denis — Fri, 13 Oct 2023 08:00:00 +0200

Dans cet article nous allons voir de façon très succincte comment remplacer une des classes du cœur de Dotclear en utilisant un conteneur de services.

Autant le dire tout de suite, ça ne va pas servir à tout le monde, et uniquement pour des cas bien précis, par des utilisateurs connaissant cette façon de coder.

Définition

- Mais c'est quoi un conteneur, un service, une usine ?
- C'est un patron de conception aka design pattern.
- Mais encore ?

Profitant du passage aux espaces de nom PHP, le cœur de Dotclear, appelé core ou dcCore, a disparu au profit d'un conteneur qui s'occupe uniquement de fournir les classes maitresses de Dotclear, ces classes sont définies et leur objets générés par le conteneur, appelé Core. (Original comme nom !) Tout ce petit monde suivant des règles bien précises écrites dans des interfaces.
Pour faire simple:

Un service est un ensemble de méthodes dédiées à une tâche, par exemple la gestion des behaviors, regroupées dans une classe
Le conteneur Container fournit à l'utilisateur les objets prêt à l'emploi, ici App:: avec App::unService()
L'usine Factory fournit ces classes, sans que l'utilisateur sache lesquelles sont réellement chargées.
Les interfaces xxxInterface définissent les règles que doivent suivre les classes de l'usine. exemple: BehaviorInterface

Cette technique va permettre de remplacer toutes les classes accessibles depuis App::xxx()

Déclaration

Il faut commencer par déclarer notre service, une classe dédiée \Dotclear\Helper\Container\Factories est là pour ça, on va lui dire d'ajouter notre service. Le plus simple est de lui dire depuis le fichier inc/config.php de l'installation, dans l'exemple qui suit, on veut simplement remplacer une seule méthode de la classe Error :

<?php
//... contenu du fichier inc/config.php

// Notre service n'utilise pas d'espace de nom, on le récupère directement
require_once __DIR__ . '/../MyError.php';

// On dit à la maison mère que notre service va être utilisé dans le core de Dotclear pour le service ErrorInterface::class
\Dotclear\Helper\Container\Factories::addService('core', ErrorInterface::class, MyError::class);

Voilà notre service remplace celui de Dotclear.

Service

Passons à notre service. Il doit obligatoirement suivre des règles strictes pour pouvoir être utilisé à la place d'un autre, voici le contenu de notre fichier MyError.php :

<?php
// On va reprendre la classe d'erreur et ses méthodes
use Dotclear\Core\Error;
// Pas besoin d'implémenter l'interface qui l'est déjà par la classe Error
//use Dotclear\Interface\Core\ErrorInterface;

// on crée notre classe d'erreur qui va étendre celle par défaut.
class MyError extends Error
{
    // on remplace uniquement la méthode qui nous intéresse
    public function add(string $msg): void
    {
        // notre classe va arrêter net le script sur une erreur au lieu de renvoyer un bandeau par exemple
        exit($msg);
    }
}

Cet exemple est simple, il permet de montrer la mécanique d'utilisation de Factories, si vous souhaitez remplacer la gestion de connexion à la base de données cela va être bien plus compliqué !

Liste des classes maîtresses

Voici la liste des appels depuis l'application et des interfaces associées :

App::auth(): \Dotclear\Interface\Core\AuthInterface,
App::behavior(): \Dotclear\Interface\Core\BehaviorInterface,
App::blog(): \Dotclear\Interface\Core\BlogInterface,
App::blogSettings(): \Dotclear\Interface\Core\BlogSettingsInterface,
App::blogs(): \Dotclear\Interface\Core\BlogsInterface,
App::blogWorkspace(): \Dotclear\Interface\Core\BlogWorkspaceInterface,
App::categories(): \Dotclear\Interface\Core\CategoriesInterface,
App::cache(): \Dotclear\Interface\Core\CacheInterface,
App::con(): \Dotclear\Interface\Core\ConnectionInterface,
App::error(): \Dotclear\Interface\Core\ErrorInterface,
App::filter(): \Dotclear\Interface\Core\FilterInterface,
App::formater(): \Dotclear\Interface\Core\FormaterInterface,
App::lang(): \Dotclear\Interface\Core\LangInterface,
App::log(): \Dotclear\Interface\Core\LogInterface,
App::media(): \Dotclear\Interface\Core\MediaInterface,
App::meta(): \Dotclear\Interface\Core\MetaInterface,
App::nonce(): \Dotclear\Interface\Core\NonceInterface,
App::notice(): \Dotclear\Interface\Core\NoticeInterface,
App::plugins(): \Dotclear\Interface\Module\ModulesInterface,
App::postMedia(): \Dotclear\Interface\Core\PostMediaInterface,
App::postTypes(): \Dotclear\Interface\Core\PostTypesInterface,
App::rest(): \Dotclear\Interface\Core\RestInterface,
App::session(): \Dotclear\Interface\Core\SessionInterface,
App::themes(): \Dotclear\Interface\Module\ModulesInterface,
App::trackback(): \Dotclear\Interface\Core\TrackbackInterface,
App::url(): \Dotclear\Interface\Core\UrlInterface,
App::users(): \Dotclear\Interface\Core\UsersInterface,
App::userPreferences(): \Dotclear\Interface\Core\UserPreferencesInterface,
App::userWorkspace(): \Dotclear\Interface\Core\UserWorkspaceInterface,
App::version(): \Dotclear\Interface\Core\VersionInterface,

Le nom de l'interface sera le nom du service dans l'usine.

Le contenu de ce document a été écrit suivant le code de la version 2.28 de Dotclear.

2.28

Jean-Christian Denis — Fri, 13 Oct 2023 08:00:00 +0200

Sortie le 15 novembre 2023, cette version de Dotclear passe les prérequis de PHP de la version 7.4 à la version 8.1 minimum !

Résumé

Cette version boucle quasiment la transition vers les espaces de noms PHP avec le transfert du cœur de Dotclear et commence à en tirer partie. Le typage des variables, des propriétés de classes et méthodes devient plus strict et précis grâce au passage à PHP 8.1. La gestion du cœur de Dotclear est entièrement remaniée. Une nouvelle classe de lectures des valeurs de configuration fait son apparition. L'utilisation de My pour les modules est de plus en plus nécessaire et recommandé…

Nouveautés :

Utilisation des avancées de PHP 8.1,
Nombreuses classes Déplacées, principalement liées au Core,
Nombreuses variables, fonctions, méthodes et classes dépréciées
Passage de dcCore en déprécié,
Nouvelle classe d'accès aux valeurs de configuration
Nouvel accès aux classes de premier niveau
Système de services pour les classes de premier niveau
Nouvelles classes d'Exception de premier niveau
Permissions de modules entièrement gérées par My
Ajout du plugin Uninstaller.
Renforcement du typage des arguments et retours de méthodes.
Travail sur la documentation doxygen.
Travail sur le niveau d'erreur d'analyseurs phpstan (niveau 8!), phpunit, psalm.
Support du format media Avif

Incompatibilités :

Les constructeurs des classes du Core ont de nouveaux arguments, les plugins instanciant eux-mêmes ces classes provoqueront un arrêt du script.
Les tests de nullité sur des propriétés ou objets du Core (principalement) ne sont plus permis (des méthodes les remplacent) et provoqueront un arrêt du script.
Des nombreuses méthodes ont vu leur typage explicitement déclaré, un arrêt du script sera provoqué par une classe qui étend une de ces classes sans avoir été mise à jour.
La classe de gestion d'erreurs fatales introduite en 2.27 n'est plus compatible, ces anciennes méthodes sont simplement supprimées . (Seule la distribution l'utilise à ce jour)

Information importante pour les développeurs :
C'est la première version nécessitant PHP 8.1 minimum, et PHP 8.2.x est supporté, et PHP 8.3.0 devrait l'être.

Les informations distillées ici sont non exhaustives et pourront être complétées à l'avenir.

Le plugin Uninstaller

Jean-Christian Denis — Tue, 22 Aug 2023 12:00:00 +0200

La prochaine version 2.28 de Dotclear embarque un nouveau plugin nommé Uninstaller.

But

Le gestionnaire de modules, incorporé au core de Dotclear et servant à la gestion des thèmes et plugins, permet d'installer des modules avec une gestion des actions liées à l'installation à travers le fichier src/Install.php et sa classe idoine, mais lorsqu'il s'agit de désinstaller des plugins ou thèmes, la seule action effectuée est la suppression des fichiers du module. À aucun moment on ne tient compte de ce que le module a pu ajouter dans les paramètres, les tables, le cache, etc...

Ce manque est désormais comblé par le plugin Uninstaller qui va permettre d'affiner la désinstallation d'un module, en proposant des outils préétablis de suppressions. Il y a deux points de départ de ces désinstallations, soit depuis le gestionnaire de plugins|thèmes avec un bouton Désinstallation qui donnera le choix au super admin de supprimer telle ou telle partie du module, soit directement lors de l'action de suppression d'un module auquel cas des actions définies par le module lui-même seront effectuées directement sans demande de confirmation.

Interface utilisateur du plugin Uninstaller

Actions

Une tâche (Cleaner) permet d'effectuer une action ciblée, les groupes et tâches prédéfinis sont les suivants :
Caches :

caches.delete : Effacer le répertoire de caches créé par le module,
caches.empty : Vider le répertoire de caches créé par le module,

Logs :

logs.delete_all : Effacer les logs créés par le module,

Plugins :

plugins.delete : Effacer les fichiers du plugins,

Preferences :

preferences.delete_global : Effacer les préférences pour les utilisateurs créées par le module,
preferences.delete_local : Effacer les préférences globales créées par le module,
preferences.delete_all : Effacer les préférences globales et utilisateurs créées par le module,
preferences.delete_related : Effacer une préférence ciblée créé par le module,

Settings :

settings.delete_global : Effacer les préférences pour les blogs créées par le module,
settings.delete_local : Effacer les préférences globales créées par le module,
settings.delete_all : Effacer les préférences globales et blogs créées par le module,
settings.delete_related : Effacer une préférence ciblée créé par le module,

Tables :

tables.delete : Supprimer une table créée par le module,
tables.empty : Vider une table créée par le module,

Themes :

themes.delete : Effacer les fichiers du thème,

Vars :

vars.delete : Effacer ou vider le sous répertoire de DC_VAR créé par le module,

Versions :

versions.delete : Supprimer le numéro de version du module ne base

Intégration

Pour utiliser les fonctions de désinstallation prédéfinis, il suffit d'ajouter un fichier src\Uninstall.php contenant sa classe idoine Uninstall dans le module. Le plugin Uninstaller saura trouver et utiliser ce fichier sans déclaration supplémentaire.
La méthode addUserAction va ajouter une action avec demande de confirmation tandis que la méthode addDirectAction ajoutera une action directe lors de la suppression d'un module. Exemple complet de fichier :

<?php
declare(strict_types=1);

namespace Dotclear\Theme\monTheme;

use Dotclear\App;
use Dotclear\Core\Process;
use Dotclear\Plugin\Uninstaller\Uninstaller;

class Uninstall extends Process
{
    public static function init(): bool
    {
        return self::status(My::checkContext(My::UNINSTALL));
    }

    public static function process(): bool
    {
        // Par sécurtié, on vérifie l'existence du plugin Uninstaller, même si c'est lui qui a dû appeler ce script
        if (!self::status() || !App::plugins()->moduleExists('Uninstaller')) {
            return false;
        }

        // On récupère l'instance singleton de Uninstaller
        Uninstaller::instance()
            // Action utilisateur pour effacer les paramètres aillant l'espace de nom du module
            ->addUserAction(
                'settings',
                'delete_all',
                My::id()
            )
            // Action utilisateur pour effacer les fichiers du module
            ->addUserAction(
                'plugins',
                'delete',
                My::id()
            )
            // Action utilisateur pour effacer le numéro de version en base du module
            ->addUserAction(
                'versions',
                'delete',
                My::id()
            )
            // Action directe pour effacer les fichiers du module
            ->addDirectAction(
                'plugins',
                'delete',
                My::id()
            )
            // Action directe pour effacer le numéro de version en base du module
            ->addDirectAction(
                'versions',
                'delete',
                My::id()
            )
        ;

        // aucune action spécifique, on retourne donc false
        return false;
    }
}

Extensions

Il est possible d'aller plus loin en ajoutant des actions spécifiques qui n'existent pas dans la livraison du plugin Uninstaller.
Pour des actions avec confirmation utilisateur on va simplement compléter la classe précédente comme suit :

<?php
declare(strict_types=1);

namespace Dotclear\Theme\monTheme;

use Dotclear\App;
use Dotclear\Core\Process;
use Dotclear\Helper\Html\Form\Para;
use Dotclear\Helper\Html\Form\Checkbox;
use Dotclear\Helper\Html\Form\Label;
use Dotclear\Plugin\Uninstaller\Uninstaller;

class Uninstall extends Process
{
    public static function init(): bool
    {
        return self::status(My::checkContext(My::UNINSTALL));
    }

    public static function process(): bool
    {
        // Par sécurtié, on vérifie l'existence du plugin Uninstaller, même si c'est lui qui a dû appeler ce script
        if (!self::status() || !App::plugins()->moduleExists('Uninstaller')) {
            return false;
        }

        // ... ici les actions prédéfinies utilisateur et directes ne sont pas affichées cf exemple ci-dessus

        if (!empty($_POST['mon_action_perso']) {

            // Ici on exécute la tâche de supprimer la choucroute

        }

        // on retourne true pour indiquer qu'on a un formulaire
        return true;
    }

    public static function render(): void
    {
        if (!self::status()) {
            return;
        }

        // On affiche le formulaire spécial
        echo (new Para())
            ->items([
                (new Checkbox('mon_action_perso', true))
                    ->value(1),
                (new Label('supprimer la choucroute', Label::OUTSIDE_LABEL_AFTER))
                    ->for('mon_action_perso')
                    ->class('classic'),
            ])
            ->render(); 
    }
}

Il est possible d'aller encore plus loin pour créer des actions spécifiques plus poussées, il faut alors créer un Cleaner et le déclarer de la même manière que ceux du plugin Uninstaller. Voir les fichiers Prepend.php pour la déclaration d'un Cleaner et le répertoire /src/Task pour des exemples de tâches.

NOTE

Pour des raisons techniques les actions directes ne sont pas effectuées sur les modules installés en double, et ce même si le bouton Désinstaller est présent.

Les informations distillées ici sont non exhaustives et pourront être complétées à l'avenir, elles ont été écrites d'après la version 2.28 de Dotclear.