Avvio rapido: registrare il primo servizio e rileggerlo

Il percorso più breve da «il plugin è installato» a «un servizio proprio è nel registro e viene trovato da un altro punto». Tre passi, circa quindici minuti. Questa pagina è rivolta a chi sviluppa plugin propri.

Prerequisiti

wkcore è installato e attivato nel gestore delle estensioni.
Un plugin proprio con un componente di azione (action.php), oppure un punto in cui aggiungerlo.
PHP 8.2 o successivo.
Per il passo 3 (la verifica): potete modificare conf/local.php.

Passo 1: agganciare l'evento di registrazione

WKCORE_REGISTER_SERVICES è l'unico momento in cui il registro si aspetta di essere scritto.

use dokuwiki\Extension\ActionPlugin;
use dokuwiki\Extension\Event;
use dokuwiki\Extension\EventHandler;
 
class action_plugin_mioplugin extends ActionPlugin
{
    public function register(EventHandler $controller)
    {
        $controller->register_hook('WKCORE_REGISTER_SERVICES', 'BEFORE', $this, 'onRegisterServices');
    }
 
    public function onRegisterServices(Event $event)
    {
        $registry = $event->data;
        $registry->register('mioplugin.saluto', new Saluto());
    }
}

Scegliere un identificatore che inizi con il prefisso del proprio plugin. Gli identificatori sono uno spazio piatto senza controllo delle collisioni; il prefisso è l'unica cosa che tiene distinti due plugin.

Se il servizio è costoso da costruire o serve di rado, registrare invece una factory. Viene eseguita alla prima get() e mai più:

$registry->registerFactory('mioplugin.rapporto', static function () {
    return new RapportoCostoso();
});

Passo 2: consumarlo da un altro punto

Tramite il caricatore di plugin di DokuWiki — non importando le classi di wkcore:

$core = plugin_load('helper', 'wkcore');
if (is_object($core) && method_exists($core, 'get')) {
    $saluto = $core->get('mioplugin.saluto');
    if ($saluto !== null) {
        echo $saluto->saluta();
    }
}

Le due verifiche sono consuetudine di casa e si guadagnano il posto: il vostro plugin continua a caricarsi quando wkcore manca e continua a funzionare quando un servizio atteso non è mai stato registrato. Nessuna delle due situazioni giustifica un'interruzione.

Passo 3: guardare che cosa è registrato

La vista diagnostica è disattivata finché l'impostazione allowdebug di DokuWiki non è attiva — segnala allora soltanto wkcore diagnostics require $conf['allowdebug'] = 1. Impostare in conf/local.php:

$conf['allowdebug'] = 1;

e togliere di nuovo la riga dopo la verifica. La vista espone gli interni dell'installazione.

Aprire poi /doku.php?do=wkcore_diag.

Verifica del risultato

La vista elenca ogni identificatore registrato, se sia un valore o una factory e, per le factory, se in questa richiesta siano già state risolte.

mioplugin.saluto vi compare come valore.
mioplugin.rapporto vi compare come factory non ancora risolta. Chiamare get('mioplugin.rapporto') una volta e ricaricare: ora è risolta.

È esattamente a questo che serve la vista. Un identificatore scritto male non è un errore da nessuna parte — è un null restituito da get(). Qui vedete come si chiama davvero.

Passo successivo

wkstorage — il primo servizio che consumerete con ogni probabilità.
wkcore (in tedesco) — la pagina del pacchetto: tutti i metodi del registro, i tre eventi e la loro stabilità.