Le conteneur principal

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

La version 2.28 de Dotclear intégre un nouveau système de conteneur pour l'application qui remplace dcCore.

Grâce aux avancées de Dotclear 2.27, cette nouvelle version 2.28 peut désormais proposer l'accès à la quasi totalité de l'application à partir d'un seul point App::. Le core, aka dcCore, passe en déprécié et ses méthodes et propriétés sont regroupées dans des classes dédiées à un ensemble de tâches de même style. Une nouvelle gestion par conteneur et services accompagnée d'un nouvelle gestion d'exception permet de proposer ces classes à tout moment sans avoir besoin de les instancier. Autre nouveauté de taille qui pourra être exploitée par la suite, ces classes deviennent remplaçables ! Ce qui devra être utilisé pour des classes d'authentification ou de connexion tiers par exemple.

Pour résumer, voici deux exemples simples de la nouvelle façon d'appeler les classes de l'ancien dcCore :

// Avant 2.28 :
dcCore::app()->auth->use_prefs;
// A partir 2.28, dcAuth fait partie du conteneur et ses propriétés deviennent des méthodes :
App::auth()->prefs();

// Avant 2.28 :
dcCore::app()->getAllBlogStatus();
// A partir de 2.28 les méthodes de l'ancien dcCore sont regroupées dans des classes à thème :
App::blogs()->getAllBlogStatus();

Voici la liste complète des classes composants ce nouveau Core de Dotclear :

Configuration

App::config(): ConfigInterface
Cette classe est une nouveauté de dotclear 2.28, elle regroupe toutes les informations de configuration de l'application.

Authentification

App::auth(): AuthInterface
~~dcCore::app()->auth~~
Anciennement dcAuth, c'est la classe de gestion de l'utilisateur.
Deux nouvelles méthodes sont disponibles :

openUserCursor(): Cursor : renvoie un Cursor sur la table des utilisateurs
openPermCursor(): Cursor : renvoie un Cursor sur la table des permissions

L'utilisation d'une classe tiers d'authentification est encore permise en 2.28, mais il faudra utiliser le nouveau système de remplacement de classe par la suite.

Comportement

App::behavior(): BehaviorInterface
~~dcCore::app()->xxxBehaviorxxx(xxx)~~
Nouvelle classe de la version 2.28, elle regroupe toutes les méthodes dépréciées de dcCore en rapport aux behaviors.
L'ancienne méthode getBehaviors() est dédoublée :

getBehavior(string $behavior): array : renvoie un groupe de behaviors,
getBehaviors(): array : renvoie tous les behaviors

Blog

App::blog(): BlogInterface
~~dcCore::app()->blog, new dcBLog()~~
Anciennement dcBlog, c'est la classe de gestion du blog courant. Cette classe subit des changements majeures dans son utilisation.
Désormais cette classe existe toujours dans l'application. Il ne faut plus tester le chargement du blog avec !is_null(dcCore::app()->blog) mais App::blog()->isDefined().
Il ne faut plus créer une nouvelle instance de dcBlog lorsqu'on veut naviguer entre deux blogs en cours de script, Il faut partir de l'instance existante et charger un autre blog dedans, puis recharger le premier si besoin. On peut mettre en id vide pour décharger un blog.
Une nouvelle méthode est donc disponible :

App::blog()->loadFromBlog(string $blog_id): BlogInterface : renvoie l'instance de Blog chargé d'un autre blog

Exemple de chargement :

// On récupère l'ID de blog courant
$old_id = App::blog()->id();
// On charge le blog qu'on souhaite modifier
App::blog()->loadFromBlog('SecondBlog');
// On le modifie
App::blog()->triggerBlog();
// On recharge le blog courant
App::blog()->loadFromBlog($old_id);

De nouvelles méthodes sont disponibles :

openBlogCursor(): Cursor : Ouvre un Cursor sur la table blog
openPostCursor(): Cursor : Ouvre un Cursor sur la table post
openCommentCursor(): Cursor : Ouvre un Cursor sur la table comment
isDefined(): bool : Vérifie si un blog est chargé dans la classe ou non

Les propriétés publiques de la classe passent en déprécié, il faut désormais utiliser les méthodes idoines :

dcCore::app()->blog->id : App::blog()->id(): string
dcCore::app()->blog->uid : App::blog()->uid(): string
dcCore::app()->blog->name : App::blog()->name(): string
dcCore::app()->blog->desc : App::blog()->desc(): string
dcCore::app()->blog->url : App::blog()->url(): string
dcCore::app()->blog->host : App::blog()->host(): string
dcCore::app()->blog->creadt : App::blog()->creadt(): int
dcCore::app()->blog->upddt : App::blog()->upddt(): int
dcCore::app()->blog->status : App::blog()->status(): int
dcCore::app()->blog->settings : App::blog()->settings(): BlogSettingsInterface
dcCore::app()->blog->themes_path : App::blog()->themesPath(): string
dcCore::app()->blog->pblic_path : App::blog()->publicPath(): string

Paramètres de blog

App::blogSettings(): BlogSettingsInterface
~~dcCore::app()->blog->settings, new dcSettings();~~
Anciennement dcSettings, c'est la classe de gestion des paramètres de blog. Cette classe subit également un changement majeur dans son utilisation. Pour créer une nouvelle instance de BlogSettings, il faut utiliser une nouvelle méthode de la classe qui renverra une instance prête à l'emploie :

App::blogSettings()->createFromBlog(?string $blog_id): BlogSettingsInterface : renvoie une nouvelle instance de BlogSettings.

On peut également utiliser App::blog()->settings()->createFromBlog(?string $blog_id).
Ses méthodes en xxxNamespace() passent en déprécié, il faut utiliser leurs méthodes associées xxxWorkspace().

Espace de paramètres de blog

App::blogWorspace(), App::blog()->settings()->get(xxx), App::blog()->settings()->addWorspace(xxx)
Comme la classe précédente une nouvelle méthode fait son apparition pour créer une nouvelle instance de BlogWorkspace :

App::blogWorkspace()->createFromBlog(?string $blog_id, string $workspace, ?MetaRecord $rs = null): BlogWorkspaceInterface : renvoie une nouvelle instance de BlogWorkspace.

Une nouvelle méthode est disponible :

openBlogWorkspaceCursor(): Cursor : renvoie un Cursor sur la table des espaces de paramètres de blog

La méthode dumpNamespace() passe en déprécié, il faut utiliser dumpWorkspace().

Blogs

App:blogs()
~~dcCore::app()->xxxBlogsxxx()~~
Nouvelle classe de la version 2.28, elle regroupe toutes les tâches en rapport à la gestion des blogs.
Changement par rapport à la version 2.27, la méthode getBlog() renverra toujours une instance de Blog. Ceci est dû au changement de comportement de la classe Blog.

Cache

App:cache()
~~dcCore::app()->emptyTemplatesCache(), dcCore::app()->cache~~
Nouvelle classe de la version 2.28, Elle inclue une méthode de l'ancien core :

emptyTemplatesCache(): void : vide le cache des templates

Et une nouvelle méthode pour le cache des dépôts de modules :

emptyModulesStoreCache(): void : vide le cache des dépôts tiers

Elle remplace également la gestion des fichiers et timestamps utilisés pour le cache coté public et qui était dans un simple tableau dcCore::app()->cache :

resetFiles(): void : Raz de la litses des fichiers
addFile(string $file): void : Ajoute un fichier
addFiles(array $files): void : Ajoute plusieurs fichiers
getFiles(): array : Renvoie la liste des fichiers
function resetTimes(): void : Raz des timestamps
addTime(int $time): void : Ajoute un timestamp
addTimes(array $times): void : Ajoute plusieurs timestamps
getTimes(): array : Renvoie la listes des timestamps

Catégories

App::categories(), App::blog()->categories()
~~dcCore::app()->blog->categories, new dcCategories()~~
Anciennement dcCategories, c'est la classe de gestion des catégories d'un blog. Elle inclut désormais la classe NestedTree.
Comme vu sur de précédentes classes une nouvelle méthode fait son apparition pour créer une nouvelle instance de Categories :

App::blog()->categories()->createFromBlog(string $blog_id): CategoriesInterface : renvoie une nouvelle instance de Categories.

Une nouvelle méthode est disponible :

openCategoryCursor(): Cursor : renvoie un Cursor sur la table des catégories

Toutes les propriétés de la classe passent en protected.

Connexion

App::con()
~~dcCore::app()->con~~
Nouvelle classe de la version 2.28, elle permet le lien entre l'ancien chargement de gestionnaire de base de donnée et le nouveau système de chargement des classes du Core. L'utilisation d'une classe tiers de connexion est encore permise en 2.28, mais il faudra utiliser le nouveau système remplacement de classe par la suite.
Elle inclut désormais le préfixe des tables disponibles en faisant App::con()->prefix().

Déprécié

App:deprecated()
Cette classe est disponible dans le Core ou en version statique. Elle permet de loguer en mode DEV d'éventuelles méthodes dépréciées.

Erreur

App::error()
~~dcCore::app()->error~~
C'est la classe de gestion d'erreur non bloquante du Core.
Sa méthode toHTML() passe en dépréciée, il faut utiliser votre propre parser à la place.

Filtre

App::filter()
~~dcCore::app()->wiki, dcCore::app()->xxxWikiXxx(), dcCore::app()->HTMLfilter()~~
Nouvelle classe de la version 2.28, elle regroupe toutes les méthodes et propriétés dédiées à la syntaxe wiki et HTML de texte.

Formateur

App:formater()
~~dcCore::app()->xxxFormaterXxx()~~-
Nouvelle classe de la version 2.28 elle regroupe toutes les méthodes de gestion des formateurs de texte.

Langue

App::lang()
~~dcCore::app()->lang~~
Nouvelle classe de la version 2.28, elle s'occupe de la langue courante.
Deux méthodes sont disponibles :

getLang(): string : renvoie le code de la langue courante
setLang(string $lang): void : enregistre le code de la langue courante.

Lexique

App::lexical()
~~dcUtils::xxxlexicalxxx()~~
Nouvelle classe de la version 2.28, elle regroupe toutes les méthodes en rapport au champs lexical d'une langue.

Log

App::log()
~~dcCore::app()->log~~
Anciennement dcLog, cette classe s'occupe de la gestion de log.
Une nouvelle méthode est disponible :

openLogCursor(): Cursor : Ouvre un Cursor sur la table de log

L'ancienne méthode getTable() passe en dépréciée, il faut utiliser la constante de classe disponible sur App::log()::LOG_TABLE_NAME.

Média

App::media()
~~dcCore::app()->media~~
Anciennement dcMedia, cette classe s'occupe de la gestion des média et comme vu précédemment, il ne faut plus créer une instance de dcMedia mais toujours utiliser celle du Core.
Pour définir le type de media, auparavant dans son constructeur, il faut utiliser la nouvelle méthode :

setFilterMimeType(string $type): void : définit le type de media

Ses propriétés publiques deviennent dépréciées, il faut par exemple utiliser la méthode :

getThumbnailFilePattern(string $type = ''): string : renvoie la définition d'un pattern.

D'autres nouvelles méthodes sont disponibles :

openMediaCursor(): Cursor : ouvre un Cursor sur la table des média
postMedia(): PostMediaInterface : retourne l'instance de PostMedia

Métadonnée

App::meta()
~~dcCore::app()->meta~~
Anciennement dcMeta, cette classe gère les métadonnées de dotclear.
Une nouvelle méthode est disponible :

openMetaCursor(): Cursor : ouvre un Cursor sur la table des métadonnées

Nonce

App::nonce()
Nouvelle classe de la version 2.28, elle regroupe les méthodes en rapport à la validation de formulaires.
L'ancienne méthode formNonce() est dédoublée :

getFormNonce(): string : renvoie le contenu HTML
formNonce(): Hidden : renvoie l'élément de Form de type Hidden

Notification

App::notice()
~~dcCore::app()->notices~~
Anciennement dcNotices, cette classe gère en base les notices.
Une nouvelle méthode est disponible :

openNoticeCursor(): Cursor : ouvre un Cursor sur la table des notifications

Media de billets

App:postMedia(), App::media()->postMedia()
~~dcCore::app()->postmedia~~
Anciennement dcPostMedia, cette classe gère les media de billets.
Une nouvelle méthode est disponible :

openPostMediaCursor(): Cursor : ouvre un Cursor sur la table des media de billets

Les constantes des noms des tables de media et post media sont disponibles dans cette classe :

App::postMedia()::MEDIA_TABLE_NAME
App::postMedia()::POST_MEDIA_TABLE_NAME

A noter que lorsqu'un blog est chargé dans la classe Blog via App::blog()->loadFromBlog(), il est également chargé dans l'instance de la classe PostMedia.

Type de billets

App::postTypes()
~~dcCore::app()->getPostxxxURL(), dcCore::app()->xxxPostType()~~
Nouvelle classe de la version 2.28, elle regroupe les méthodes en relation aux types de billets.
Les anciennes méthodes sont toujours utilisables mais il est recommandé d'utiliser l'autre nouvelle classe de définition d'un type de billet PostType. (cf billet sur dcCore déprécié)

Service REST

App::rest()
~~dcCore::app()->xxxRestXxx()~~
Nouvelle classe de la version 2.28, elle regroupe les méthodes relatives au service REST.

Session

App::session()
Nouvelle classe de la version 2.28, elle adapte l'ancienne classe de gestion de session à la nouvelle gestion de classe de Core.
Une nouvelle méthode est disponible pour créer simplement une nouvelle session à partir d'un nom de cookie (pratique pour les plugins et thèmes) :

App::session()->createFromCookieName(string $cookie_name): SessionInterface

Rétroliens

App::trackback()
Anciennement dcTrackback, cette classe gère les rétroliens et pingback.
Une nouvelle méthode est disponible :

openTrackbackCursor(): Cursor : ouvre un Cursor sur la table des rétroliens

Préférences utilisateur

App::userPrerefences()
Anciennement dcPrefs, cette classe gère les préférences utilisateur. Elle est disponible pour l'utilisateur en cours dans App::auth()->prefs(). Comme nombre de classes de Core, cette classe est toujours disponible et instanciée dans App::userPreferences(), pour avoir une nouvelle instance il faut donc utiliser sa méthode :

createFromUser(string $user_id, ?string $user_workspace = null): UserPreferencesInterface : Créé une nouvelle instance des préférences utilisateur

Espace de préférences utilisateur

App::userWorkspace(), App::auth()->perfs()->get(xxx), App::auth()->prefs()->addWorspace(xxx)
Comme la classe précédente une nouvelle méthode fait son apparition pour créer une nouvelle instance de UserWorkspace :

createFromUser(?string $user_id, string $workspace, ?MetaRecord $rs = null): UserWorkspaceInterface : renvoie une nouvelle instance de UserWorkspace.

Une nouvelle méthode est disponible :

openUserWorkspaceCursor(): Cursor : renvoie un Cursor sur la table des espaces de préférences utilisateur

Utilisateurs

App::users()
Nouvelle classe de la version 2.28, elle regroupe toutes les méthodes relatives aux utilisateurs.

Versions

App::version()
~~dcCore::app()->xxxVersionXxx()~~
Nouvelle classe de la version 2.28, elle gère les version de module (et core) en base.
Une nouvelle méthode est disponible :

openVersionCursor(): Cursor : ouvre un Cursor sur la table des versions

Autres

De plugs certaines classes plus spéciales sont accessibles depuis App::xxx() :

App::backend() : Gestion de l'interface d'administration
App::frontend() : Gestion de l'interface publique
App::url() : Anciennement dcUrlHandler de dcCore::app()->url
App::task() : Uniquement utilisé par les plugins et thèmes pour tester le contexte avec App::task()->checkContext(...)

En savoir plus

dcCore déprécié

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

Lancement de l'application

Jean-Christian Denis — Wed, 12 Jul 2023 22:02:00 +0100

La version 2.27 de Dotclear introduit un changement technique de taille dans le moteur de blog.

Avec l'accentuation de l'utilisation des espaces de noms PHP dans le moteur, Dotclear peut désormais travailler autrement. Antérieurement à la version 2.27, les points d'entrées était multiples et déclarés par des fichiers bien précis placés dans des dossiers tout aussi précis. Par exemple chaque page de l'administration avait sa propre page PHP correspondante et était référencée par rapport à ce fichier. A partir de la version 2.27 un simple fichier index.php avec un contenu adéquat permet de faire tout ça. Ce fichier index.php va lancer l'application Dotclear avec les paramètres qui lui correspondent. L'application va ensuite traduire ces paramètres et lancer le processus associé. Schématiquement le déroulement du script donne :
index.php => App => Utility => Process

L'application Dotclear utilise désormais un unique point d'entrée :
Dotclear\App::bootstrap('utility','process');

Un Utility est une partie générale de Dotclear, les correspondances avec les versions antérieures sont:

admin => Backend,
public => Frontend,
upgrade CLI => Upgrade,
install => Install

Ensuite chaque Utility lance un Process qui auparavant était une page, par exemple pour la page d'accueil de l'administration des blogs on aura Backend / Home. Cela peu paraître déroutant pour celui qui pratique Dotclear depuis des années, mais la logique aidant, il est assez simple de se repérer, d'autant plus que coté code, on retrouvera ce schéma. En reprenant l'exemple de la page d'accueil de l'administration qui aura comme paramètre Utility=Backend et Process=Home, on retrouve les espaces de noms et les fichiers physiques suivants :

Utility = Backend, Class = Dotclear\Core\Backend\Utility, Fichier = src/Core/Backend/Utility.php
Process = Home, Class = Dotclear\Process\Backend\Home, Fichier = src/Process/Backend/Home.php

Partant de ce principe pour afficher la page d'accueil de l'administration de Dotclear, il faut dans le fichier index.php indiquer où se trouve l'application et la lancer avec ces deux paramètres :

<?php
// on va cherche l'application Dotclear
require_once implode(DIRECTORY_SEPARATOR, [__DIR__, '..', 'src', 'App.php']);
// on lance l'application pour afficher la page d'accueil de l'administration
Dotclear\App::bootstrap('Backend', 'Home');

Logique.

Ensuite pour naviguer, l'application va tenir compte du paramètre de requête HTTP nommé process et le substituer à celui du fichier index.php, la navigation dans l'admin devient alors possible depuis une seule page index.php.
Coté public c'est encore plus simple car il n'y a pas de process en 2.27, seul l'Utility Frontend est appelé, le gestionnaire d'URL public se chargeant de jouer avec les templates.

A noter que pour les installations existantes qui feront la mise à jour en 2.27, les deux écritures restent valables. Il n'est pas obligatoire de modifier les fichiers index.php des blogs et la partie admin accepte également l'utilisation des anciens points d'entrée.

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

DotclearWatch / Blog - Mot-clé - app

Le conteneur principal

Configuration

Authentification

Comportement

Blog

Paramètres de blog

Espace de paramètres de blog

Blogs

Cache

Catégories

Connexion

Déprécié

Erreur

Filtre

Formateur

Langue

Lexique

Log

Média

Métadonnée

Nonce

Notification

Media de billets

Type de billets

Service REST

Session

Rétroliens

Préférences utilisateur

Espace de préférences utilisateur

Utilisateurs

Versions

Autres

En savoir plus

Lancement de l'application