DotclearWatch / Blog - Mot-clé - config

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())) { }.

Les modes DEBUG et DEV

Jean-Christian Denis — Thu, 05 Oct 2023 23:42:00 +0200

Pour aider les développeurs de thèmes et de plugins, Dotclear est doté de deux modes spéciaux. Il est important de savoir quels comportements de Dotclear changent avec l'utilisation de ces modes.

DEV

Le mode DEV est utilisé si la constante DC_DEV est définie à true dans le fichier config.php, on vérifie ensuite sa valeur en utilisant le retour de la méthode App::config()->devMode(): bool. Ce mode est désactivé par défaut sur les versions de distribution stable de Dotclear et activé sur les versions -dev.

Fichier minifié
En mode DEV les fichiers minifiés ne seront pas cherchés et donc pas retournés lors de la demande au serveur de fichiers lancée avec ?pf=, ?vf= cela afin de faciliter la lecture (visuelle) des fichiers sources.

Suffixe de fichier
En mode DEV les demandes faites au serveur de fichiers seront affublées d'un suffixe sous forme d'une chaîne de caractères aléatoires, pour prévenir tout problème de cache.

Module et version du core
En mode DEV les modules des dépôts seront retournés même si leur version minimum de Dotclear ne correspond pas. Attention cette différence peu apporter de la confusion dans le retour de mise à jour de dépôts tiers et dépôts officiels de modules.

Module et erreur
En mode DEV certaines exceptions lancées par des modules (plugins ou thèmes) pourront être accompagnées d'un message plus détaillé (mais comportant des informations plus sensibles).

Déprécié
En mode DEV, l'utilisation de méthode dépréciée sera enregistrée dans les logs Dotclear. (La table log de la base de données Dotclear) A noter que la fonction de log des dépréciés est munie d'une limite d'enregistrement, les plus anciens seront automatiquement effacés.

Git
En mode DEV, les modules appartenant à un dépôt GIT auront une présentation différente dans la liste des modules.

Admin (backend)
En mode DEV, un bandeau rétractable sera présent en haut de la page d'administration, il affichera différentes informations sur le temps de chargement de la page, l'utilisation mémoire et les variables globales et l'autoloader.
Les liens vers des fichiers css et js seront affublés d'un suffixe sous forme de numéro de version pour forcer leur rechargement et ainsi prévenir d'éventuels problèmes de cache.

DEBUG

Le mode DEBUG est utilisé si la constante DC_DEBUG est définie à true dans le fichier config.php, on vérifie ensuite sa valeur en utilisant le retour de la méthode App::config()->debugMode(): bool. Ce mode est désactivé par défaut sur les versions de distribution stable de Dotclear et activé sur les versions -dev.

Exception
En mode DEBUG, les exceptions attrapées par l'application seront accompagnées de leur trace, c'est à dire le déroulement du script jusqu'à l'exception. Le message retourné peut être également plus explicite et retourner plus d'informations utiles mais sensibles.

Fichier minifié
En mode DEBUG les fichiers minifiés ne seront pas cherchés et donc pas retournés lors de la demande au serveur de fichiers lancée avec ?pf=, ?vf=.

Suffixe de fichier
En mode DEBUG les demandes faites au serveur de fichiers seront affublées d'un suffixe sous forme de numéro de version de dotclear, pour prévenir tout problème de cache.

Module et version du core
En mode DEBUG les modules des dépôts seront retournés même si leur version minimum de Dotclear ne correspond pas.

Module et recherche
En mode DEBUG la liste des modules de dépôts aura une colonne supplémentaire, lors de recherche, affichant le score de pertinence de recherche obtenu.

Git
En mode DEBUG, les modules appartenant à un dépôt GIT auront une présentation différente dans la liste des modules.

Admin (backend)
En mode DEBUG, les liens vers des fichiers css et js seront affublés d'un suffixe sous forme de numéro de version pour forcer leur rechargement et ainsi prévenir d'éventuels problèmes de cache.

jQuery
En mode DEBUG, les options de jQuery migrate seront activées.

Console
En mode DEBUG, la variable JS dotclear.debug passe également à true et permet entre autre de logger les retours d'erreurs des appels REST.

Conclusion

Ces deux modes tentent d'apporter de l'aide au développement sous Dotclear en modifiant le comportement de certaines fonctions, mais dévoilent également un peu plus d'informations qui peuvent être sensibles. Il est fortement conseillé de ne pas activer ces modes sur une installation en production.

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

Fichier Config d'un module

Jean-Christian Denis — Sun, 16 Jul 2023 14:03:00 +0100

Le fichier Config.php, placé dans le dossier src du module, simplifie la gestion de sa configuration.

Le fichier Config.php fait partie du processus reconnu par le gestionnaire de modules, il est donc automatiquement pris en compte dans l'administration si il existe.

Il est placé dans le sous dossier src du module,
Il contient une classe du nom de Config,
Il est dans l'espace de nom PHP Dotclear\Plugin\monPlugin ou Dotclear\Theme\monTheme,
La classe doit étendre la classe Process,
Les 3 méthodes init() et process() et render() sont utilisées,

Cette classe simplifie la gestion de la configuration d'un module dans le sens où la partie construction de la page est déjà effectuée par le gestionnaire de modules. Seul le traitement des valeurs et le contenu du formulaire sont à la charge de la classe Config. Un lien vers cette page sera ajouté à la liste de plugins ou sur les thèmes de la page de gestion d'apparence du blog. Un lien sera également ajouté en bas de page principale de gestion du plugin si elle existe.

Exemple complet du fichier config du thème customCSS de la distribution :

<?php
namespace Dotclear\Theme\customCSS;

use dcCore;
use Dotclear\Core\Backend\Notices;
use Dotclear\Core\Process;
use Dotclear\Helper\File\Path;
use Dotclear\Helper\Html\Html;
use Dotclear\Helper\L10n;
use Exception;
use form;

class Config extends Process
{
    public static function init(): bool
    {
        if (My::checkContext(My::CONFIG)) {
            My::l10n('main');
            dcCore::app()->admin->css_file = Path::real(dcCore::app()->blog->public_path) . '/custom_style.css';

            if (!is_file(dcCore::app()->admin->css_file) && !is_writable(dirname(dcCore::app()->admin->css_file))) {
                throw new Exception(
                    sprintf(
                        __('File %s does not exist and directory %s is not writable.'),
                        dcCore::app()->admin->css_file,
                        dirname(dcCore::app()->admin->css_file)
                    )
                );
            }
            self::status(true);
        }

        return self::status();
    }

    public static function process(): bool
    {
        if (!self::status()) {
            return false;
        }

        if (isset($_POST['css'])) {
            @$fp = fopen(dcCore::app()->admin->css_file, 'wb');
            fwrite($fp, $_POST['css']);
            fclose($fp);

            Notices::message(__('Style sheet upgraded.'), true, true);
        }

        return true;
    }

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

        $css_content = is_file(dcCore::app()->admin->css_file) ? file_get_contents(dcCore::app()->admin->css_file) : '';

        echo
        '<p class="area"><label>' . __('Style sheet:') . '</label> ' .
        form::textarea('css', 60, 20, Html::escapeHTML($css_content)) . '</p>';
    }
}

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