DotclearWatch / Blog - Mot-clé - déprécié

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.

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.

Obsolescence programmée

Jean-Christian Denis — Sat, 15 Jul 2023 10:45:00 +0100

Terme employé par le grand chef de Dotclear, il résume bien une des interrogations du moment.

Suite à une discussion sur le salon Slack de la team Dotclear, puis transformé en ticket, puis en billet, la question de la gestion des dépréciés présents dans le code de Dotclear est posée. En découle également celle de la montée en version PHP.

Pourquoi se poser la question ?

La devise Dotclear fait des blogs et il le fait bien se traduit par ça marche, pourquoi changer, pourquoi modifier du code qui fonctionne ? La réalité est plus compliquée.
Historiquement Dotclear ne court pas après les dernières nouveautés techno, et ses utilisateurs encore moins. La hype ne fait pas partie du langage Dotclear, même si les développeurs de plugins et thèmes aiment utiliser les avancées des langages de programmation.
Le code arrive à un tournant de sa vie, qui rend compliqué la balance entre rester compatible avec des vieux thèmes, plugins, installations, et aller de l'avant avec de nouvelles fonctionnalités souvent apportées par une nouvelle versions de PHP. Et il y a de plus en plus de dépréciés dans le code et ça commence à faire beaucoup de code mort à charger, à entretenir, et ça peut bloquer l'utilisation de nouvelles fonctions plus puissantes, plus rapides.
Dotclear pourrait simplement supprimer les dépréciés, passer à PHP 8.3-beta et vous n'auriez qu'à suivre. Mais ça laisserait sur le carreau une multitude de thèmes et plugins pas à jour et qui ne le seront pas avant des lustres, et aussi des installations en PHP 7.4 qui ne peuvent pas être mises à jour, peu importe la raison, hébergeur à la traîne, utilisateur débutant, etc...
D'après les derniers chiffres (07/2023) données par les statistiques Wordpress, plus de 75% des installations ont une version inférieure à PHP 8.0 dont 50% sont en PHP 7.4. Dotclear n'a pas d'outils de suivi d'installation mais ces valeurs devrait être assez proches de la réalité, difficile alors d'imposer une version trop avancée et pourtant chez PHP la version 7.4 est déjà passé en Unsupported ! Alors quoi les internets sont à la traine, PHP va trop vite ? Que faire...

Une conclusion ?

Pas de réponse évidente, pas de direction toute tracée. Comme souvent tout est dans un équilibre entre les avantages et les inconvénients mais où se situe-t-il ?

Si vous souhaitez participer à cette discussion, les deux liens en début d'article sont faits pour vous.

Les dépréciés

Jean-Christian Denis — Wed, 12 Jul 2023 19:54:00 +0100

La version 2.27 de Dotclear apporte son lot de dépréciés. Et leur nombre augmente par rapport aux dernières versions.

Autoloader

dcCore::autoload() => Autoloader::me()
Il faut désormais appeler directement Autoloader::me()

Erreur

_ _error() => new Dotclear\Fault()
Il faut utiliser la classe dédiée Fault avec soit le constructeur new Dotclear\Fault() ou bien la forme statique Dotclear\Fault::throw()

Déconnection

logout=1 => process=Logout
La déconnection a maintenant une URL dédiée. Pour l'appeler, il faut utiliser le gestionnaire d'URL dcCore::app()->admin->url->redirect('admin.logout') qui donnera dans l'URL &process=Logout
Astuces : Si un plugin ou un thème bloque l'accès à l'admin, il est possible de simplement ajouter à la fin de l'URL de votre navigateur ?process=Logout et vous pourrez vous reconnecter en mode sans échec.

Variable $init de process

dcNsProcess::$init => Process::status()
Introduite en 2.26 cette variable posait des problèmes, elle a été remplacé par la méthode Dotclear\Core\Process::status() qui sert à la fois en lecture et en écriture.

Ajout de menu

dcAdminHelper::addMenuItem() => dcCore::app()->admin->menus->addItem()
Avec l'arrivée des espaces de noms PHP dans la partie administration, les menus font partie d'un objet nommé Menus et donc il faut passer par lui pour ajouter des menus avec dcCore::app()->admin->menus->addItem().
Pour les plugins il est recommandé d'utiliser la classe My et la méthode My::addBackendMenuItem()..

Constantes de menu

dcAdmin::MENU_FAVORITES => Menus::MENU_FAVORITES,
dcAdmin::MENU_BLOG => Menus::MENU_BLOG,
dcAdmin::MENU_SYSTEM => Menus::MENU_SYSTEM,
dcAdmin::MENU_PLUGINS => Menus::MENU_PLUGINS,

Ici encore suite à l'arrivée du nouvel objet Menus, les constantes associées sont déplacées dedans. Le nom complet de la classe est Dotclear\Core\Backend\Menus. Il est possible de les appeler depuis l'instance dcCore::app()->admin->menus::MENU_XXX

Les notices

dcPage::notices() => Notices::getNotices(),
dcPage::addMessageNotice() => Notices::addMessageNotice(),
dcPage::addSuccessNotice() => Notices::addSuccessNotice(),
dcPage::addWarningNotice() => Notices::addWarningNotice(),
dcPage::addErrorNotice() => Notices::addErrorNotice(),
dcPage::message() => Notices::message(),
dcPage::success() => Notices::success(),
dcPage::warning() => Notices::warning(),
dcPage::error() => Notices::error(),

Toutes les méthodes de dcPage (nouvellement Page) en rapport aux notices sont dépréciées, il faut désormais utiliser les méthodes de la classe d'origine Dotclear\Core\Backend\Notices dont les signatures restent les mêmes.

Fichiers de modules

dcPage::cssModuleLoad() => My::cssLoad(),
dcPage::jsModuleLoad() => My::jsLoad(),
dcUtils::cssModuleLoad() => My::cssLoad(),
dcUtils::jsModuleLoad() => My::jsLoad(),

Encore une fois la classe My dédiée aux modules vient prendre le relai de ces deux méthodes. La différence est que, la structure des modules devenant plus stricte, ces deux nouvelles méthodes ont uniquement besoin du nom du fichier à charger. Il n'est plus nécessaire de fournir le nom du module ni celui du sous répertoire. Pour les css les fichiers sont rangés dans le dossier css, pour les js, les fichiers sont rangés dan le dossier js. Propre.
Exemple avec un partie de la méthode process de la classe Manage d'un module :

<?php
//...
Page::openModule(
    My::name,
    // charge le fichier MonPlugin/js/backend.js
    My::jsLoad('backend') .
    // charge le fichier MonPlugin/css/style.css
    My::cssLoad('style')
);

De core à admin

dcCore::app()->adminurl => dcCore::app()->admin->url,
dcCore::app()->favs => dcCore::app()->admin->favs,
dcCore::app()->menu => dcCore::app()->admin->menus,

Comme annoté dans le code depuis quelques versions certaines instances se trouvant historiquement dans dcCore auraient dû aller dans dcCore::app()->admin, c'est chose faite en 2.27.

Points d'entrées

dotclear/inc/public/_prepend.php
dotclear/inc/admin/_prepend.php
tous les fichiers dotclear/admin/xxx.php

Tous les points d'entrée qui étaient représentés par des fichiers sont dépréciés, ils sont remplacés par un seul fichier index.php qui lance l'application Dotclear.

Coté public, ce sera l'index.php de définition du blog qui lancera l'application.
Coté admin, ce sera l'index.php de l'URL d'administration qui s'en chargera.

Cas particulier, la mise à jour en ligne de commande se déplace de dotclear/inc/dbschema/upgrade-cli.php vers dotclear/admin/upgrade/upgrade-cli.php :

user@server: /var/www/dotclear$ php admin/upgrade/upgrade-cli.php inc/config.php

Propriétés du core

Nombre de propriétés de dcCore utilisent en 2.27 l'état 'uninitialized' c'est à dire qu'il ne faut plus tester leur nullité mais leur présence, cela se traduit par exemple par :

is_null(dcCore::app()->auth) ou dcCore::app()->auth === null => isset(dcCore::app()->auth)

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