DotclearWatch / Blog - Mot-clé - my

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.

Les classes de module My

Jean-Christian Denis — Fri, 14 Jul 2023 10:27:00 +0100

Dotclear version 2.27 propose pour les plugins et thèmes des classes d'aide pour simplifier l'écriture du code.

Deux classes My (qui étendent une troisième commune nommé MyModule) sont disponibles, MyPlugin pour les plugins et MyTheme pour les thèmes, elle fournissent des méthodes statiques qui vont simplifier l'écriture des modules.

Inclusion

Pour les utiliser il suffit d'inclure dans le dossier src du module un fichier My.php avec le contenu suivant :

<?php
/**
 * Mettre ici les informations de licence.
 */
declare(strict_types=1);

namespace Dotclear\Plugin\monPlugin;

use Dotclear\Module\MyPlugin;

class My extends MyPlugin
{
}

A adapter pour un thème. Il possible d'ajouter ses propres méthodes à cette classe tant que ça n'interfère pas avec celles de MyPlugin, MyTheme et MyModule.

Utilisation

Ensuite il sera possible d'utiliser toutes les méthodes de MyPlugin (MyTheme) dans les classes du plugin (thème).

<?php
namespace Dotclear\Plugin\monPlugin;

use Dotclear\Core\Process;
use Dotclear\Core\Backend\Page;

// Page principale de gestion du plugin
class Manage extends Process
{
    public static function init(): bool
    {
        // On vérifie que l'utilisateur à le droit d'exercer dans ce contexte
        return self::status(My::checkContext(My::MANAGE));
    }

    public static function process(): bool
    {
        if (!empty($_POST['step'])) {
            // ...

            // On redirige la page à l'aide de My
            My::redirect(['step' => 2]);
        }
    }

    public static function render(): void
    {
        // On utilise la classe My pour trouver le nom du plugin et des fichiers
        Page::openModule(
            My::name(),
            My::cssLoad('backend')
        );
    }
}

Méthodes

My::define()

protected static function define(): dcModuleDefine

Cette méthode renvoie l'instance de définition du module.

My::checkContext()

protected static function checkContext(int $context): bool

Cette méthode permet de vérifier que l'utilisateur à le droit d'exercer dans un certain contexte, elle renvoie true si l'utilisateur à assez de droits, false sinon. Elle prend en paramètre le contexte qui doit être vérifier. La liste des contextes prédéfinis est disponible dans les constantes de la classe My :

0 : INSTALL : Install context
1 : PREPEND : Prepend context
2 : FRONTEND : Frontend context
3 : BACKEND : Backend context (usually when the connected user may access at least one functionnality of this module)
4 : MANAGE : Manage context (main page of module)
5 : CONFIG : Config context (config page of module)
6 : MENU : Menu context (adding a admin menu item)
7 : WIDGETS : Widgets context (managing blog's widgets)
8 : UNINSTALL : Uninstall context (réservé pour le plugin Uninstaller)

My::checkCustomContext()

protected static function checkCustomContext(int $context): ?bool

Cette méthode est appelée en début de la méthode précédente checkContext et peut être réécrite dans la classe My du module si on en a besoin. Elle permet d'utiliser ses propres droits, ou de modifier des droits de contexte de la méthode précédente. Si checkCustomContext() renvoie null alors les contextes de la classe précédente seront testés.
Exemple avec le fichiers My du plugin userPrefs de la distribution :

<?php
declare(strict_types=1);

namespace Dotclear\Plugin\userPref;

use dcCore;
use Dotclear\Module\MyPlugin;

class My extends MyPlugin
{
    protected static function checkCustomContext(int $context): ?bool
    {
        // allways limit to super admin
        return defined('DC_CONTEXT_ADMIN')
            && dcCore::app()->auth->isSuperAdmin();
    }
}

My::path()

public static function My::path(): string

Cette méthode renvoie le chemin du dossier du module.

My::id()

protected static function My::id(): string

Cette méthode renvoie l'identifiant du module.

My::name()

protected static function My::name(): string

Cette méthode renvoie le nom traduit du module.

My::settings()

public static function settings(): ?dcNamespace

Cette méthode renvoie l'instance de l'espace de paramètres du module. Le module doit utiliser son ID comme nom d'espace de paramètre pour pouvoir utiliser cette méthode.

My::prefs()

public static function prefs(): ?dcWorkspace

Cette méthode renvoie l'instance de l'espace de préférences du module. Le module doit utiliser son ID comme nom d'espace de préférences pour pouvoir utiliser cette méthode.

My::l10n()

public static function l10n(string $process): void

Cette méthode charge les locales du module pour un process donné (main, public, plugin, etc...).

My::fileURL()

public static function fileURL(string $resource, bool $frontend = false): string

Cette méthode retourne l'URL d'un fichier de module. Cette méthode tient compte du contexte courant (admin, public). Pour forcer le retour de l'URL public dans le contexte admin, il suffit de mettre le paramètre $frontend à true.
A noter que pour les thèmes, cette méthode renvoie toujours l'URL publique.

My::cssLoad()

public static function cssLoad(string $resource, string $media = 'screen', ?string $version = ''): string

Cette méthode retourne le code HTML pour inclure un fichier CSS $resource du module.

Si le paramètre $resource ne commence pas par un / le fichier sera cherché dans le sous dossier css du module,
Si l'extension du fichier n'est pas incluse à $resource, elle sera ajoutée,
Le type de $media peut-être précisé, par défaut ce sera screen,
Un numéro de version peut-être ajouté à la fin de l'url de ressource (gestion de cache)

// Renvoie le code pour le fichier .../monPlugin/css/frontend.css
My::cssload('frontend');
// Renvoie le code pour le fichier .../monPlugin/style.css
My::cssLoad('/style.css');

My::jsLoad()

public static function jsLoad(string $resource, ?string $version = '', bool $module = false): string

Tout comme My::cssLoad() cette méthode renvoie le code HTML pour ajouter un fichier JS du module. Le paramètre $module si il est à true permet de charger $resource comme un module JS.

My::addBackendMenuItem() (plugins uniquement)

public static function addBackendMenuItem(string $menu = Menus::MENU_PLUGINS, array $params = [], string $scheme = '(&.*)?$', ?string $id = null): void

Cette méthode permet d'ajouter rapidement le module aux menus de l'administration.
Le menu est à choisir parmi ceux définis dans les constantes de Dotclear\Core\Backend\Menus et par défaut celui des plugins :

Menus::MENU_BLOG => 'Blog',
Menus::MENU_SYSTEM => 'System',
Menus::MENU_PLUGINS => 'Plugins',

Les paramètres :

$params sert à ajouter des paramètres à l'URL du menu,
$scheme permet de personnaliser la surbrillance du menu,
$id permet de spécifier un id pour l’icône de tableau de bord (Utile aux behaviors).

My::icons() (plugins uniquement)

public static function icons(string $suffix = ''): array

Cette méthode renvoie un tableau des chemins complets vers les icônes du modules.

My::manageURL() (plugins uniquement)

public static function manageUrl(array $params = [], string $separator = '&'): string

Cette méthode renvoie l'URL de la page principale de gestion du module. Des paramètres spéciaux peuvent être ajoutés avec $params, et le séparateur des paramètres peut être modifié avec le paramètre $separator.

My::redirect() (plugins uniquement)

public static function redirect(array $params = [], string $suffix = ''): void

Cette méthode effectue une redirection en prenant l'URL de base du module, à laquelle il est possible d'ajouter des paramètres $params. Le paramètre $suffix permet d'ajouter par exemple le renvoi vers un onglet spécifique.

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