contenthash = 6a204bd89f3c8348afd5c77c717a097a44e95e34

moodledata/
└── filedir/
    └── 6a/
        └── 20/
            └── 6a204bd89f3c8348afd5c77c717a097a44e95e34   ← le contenu brut, sans extension

# Un fichier déposé dans une activité « Dossier » (mod_folder) :
contextid = 812 (contexte du module folder), component = 'mod_folder',
filearea = 'content', itemid = 0, filepath = '/', filename = 'sujet-tp3.pdf'

# Une image dans la description (intro) d'un devoir :
contextid = 950, component = 'mod_assign',
filearea = 'intro', itemid = 0, filepath = '/', filename = 'schema.png'

# Un fichier en cours d'édition dans un formulaire (brouillon) :
contextid = 5 (contexte UTILISATEUR de celui qui édite), component = 'user',
filearea = 'draft', itemid = 947210043 (draftid aléatoire), filepath = '/', filename = 'schema.png'

# Une image dans le résumé d'un cours :
contextid = 133 (contexte du cours), component = 'course',
filearea = 'summary', itemid = 0, filepath = '/', filename = 'banniere.jpg'

# Fichier de soumission d'un étudiant dans un devoir :
contextid = 950, component = 'assignsubmission_file',
filearea = 'submission_files', itemid = 42 (id de la soumission), filepath = '/', filename = 'devoir.docx'

-- Extrait simplifié de la structure de mdl_files
id            BIGINT   -- clé primaire
contenthash   CHAR(40) -- SHA-1 du contenu → localise le blob dans filedir
pathnamehash  CHAR(40) -- SHA-1 de "/contextid/component/filearea/itemid/filepath/filename"
                       -- → index UNIQUE, permet de retrouver UN fichier en une requête
contextid     BIGINT
component     VARCHAR(100)
filearea      VARCHAR(50)
itemid        BIGINT
filepath      VARCHAR(255)
filename      VARCHAR(255)
userid        BIGINT   -- qui a déposé le fichier (nullable)
filesize      BIGINT
mimetype      VARCHAR(100)
status        BIGINT
source        TEXT     -- provenance (repository d'origine, etc.)
author        VARCHAR(255)
license       VARCHAR(255)
timecreated   BIGINT   -- timestamps Unix, comme partout dans Moodle
timemodified  BIGINT
sortorder     BIGINT
referencefileid BIGINT -- pour les fichiers "alias" pointant vers un repository externe

<?php
// Toujours commencer par obtenir le service de stockage.
$fs = get_file_storage();
 
// Contexte du module (on suppose $cm disponible, cf. chapitre pages/modules).
$context = context_module::instance($cm->id);
 
// Récupérer TOUS les fichiers d'une zone.
// Signature : get_area_files($contextid, $component, $filearea,
//                            $itemid = false, $sort = 'itemid, filepath, filename',
//                            $includedirs = true, ...)
$files = $fs->get_area_files(
    $context->id,          // le contexte propriétaire
    'mod_folder',          // le composant (frankenstyle)
    'content',             // la zone de fichiers
    0,                     // itemid ; false = tous les itemids de la zone
    'filepath, filename',  // ordre de tri SQL
    false                  // false = EXCLURE les répertoires (les lignes ".")
);
 
foreach ($files as $file) {
    // $file est un stored_file.
    echo $file->get_filepath() . $file->get_filename()
        . ' (' . display_size($file->get_filesize()) . ')' . PHP_EOL;
}

<?php
$fs = get_file_storage();
 
// Le sextuplé complet identifie un fichier de façon unique.
$file = $fs->get_file(
    $context->id,   // contextid
    'mod_folder',   // component
    'content',      // filearea
    0,              // itemid
    '/',            // filepath (toujours avec les slashs !)
    'sujet-tp3.pdf' // filename
);
 
if ($file === false) {
    // get_file renvoie false si le fichier n'existe pas — toujours tester.
    throw new moodle_exception('filenotfound', 'error');
}
 
// Variante : si vous connaissez déjà le pathnamehash (rare) :
// $file = $fs->get_file_by_hash($pathnamehash);

<?php
$fs = get_file_storage();
$context = context_module::instance($cm->id);
 
// Le "file record" : les métadonnées du futur fichier.
$filerecord = [
    'contextid' => $context->id,
    'component' => 'mod_monmodule',
    'filearea'  => 'export',
    'itemid'    => 0,
    'filepath'  => '/',
    'filename'  => 'export-notes.csv',
    // Champs optionnels utiles :
    'userid'    => $USER->id,
    'mimetype'  => 'text/csv',      // sinon deviné depuis l'extension
    'author'    => fullname($USER),
    'license'   => 'allrightsreserved',
];
 
// 1) Depuis une chaîne PHP (génération à la volée) :
$csv = "prenom;nom;note\nAda;Lovelace;20\n";
$file = $fs->create_file_from_string($filerecord, $csv);
 
// 2) Depuis un fichier temporaire sur disque (import, upload traité manuellement) :
// $file = $fs->create_file_from_pathname($filerecord, '/tmp/import.csv');
 
// 3) Depuis un autre stored_file (copie logique — le blob n'est PAS dupliqué,
//    seule une nouvelle ligne de métadonnées est créée, même contenthash) :
// $file = $fs->create_file_from_storedfile($filerecord, $sourcefile);

<?php
/** @var stored_file $file */
 
// --- Métadonnées ---
$file->get_filename();     // 'rapport.pdf'
$file->get_filepath();     // '/images/'
$file->get_filesize();     // taille en octets (int)
$file->get_mimetype();     // 'application/pdf'
$file->get_contenthash();  // le SHA-1 du contenu
$file->get_timemodified(); // timestamp Unix
$file->get_userid();       // id du déposant (peut être null)
$file->get_itemid();
$file->get_contextid();
$file->is_directory();     // true pour les lignes "."
$file->is_valid_image();   // pratique avant de générer un <img>
 
// --- Contenu ---
$content = $file->get_content();            // TOUT le contenu en mémoire — attention aux gros fichiers !
$file->copy_content_to('/tmp/travail.pdf'); // copie vers un chemin disque (streaming, sûr pour les gros fichiers)
$handle = $file->get_content_file_handle(); // ressource de flux PHP (fread/stream_copy_to_stream)
$file->copy_content_to_temp();              // copie vers un fichier temp Moodle, renvoie le chemin
 
// --- Cycle de vie ---
$file->delete();   // supprime la LIGNE de métadonnées ; le blob physique n'est
                   // purgé que plus tard, s'il n'est plus référencé par personne.
$file->rename('/nouveaudossier/', 'nouveau-nom.pdf'); // déplace/renomme (métadonnées seulement)

<?php
$fs = get_file_storage();
 
// Supprimer tous les fichiers d'une zone (ex. dans la fonction de
// désinstallation du module, ou avant de régénérer un export).
$fs->delete_area_files(
    $context->id,
    'mod_monmodule',
    'export',   // omis ou null = toutes les zones du composant dans ce contexte
    0           // omis ou false = tous les itemids
);

https://monsite/pluginfile.php/{contextid}/{component}/{filearea}/{itemid}/{filepath}{filename}

# Exemples réels :
https://monsite/pluginfile.php/812/mod_folder/content/0/sujet-tp3.pdf
https://monsite/pluginfile.php/950/mod_assign/intro/schema.png        ← pas d'itemid !
https://monsite/pluginfile.php/5/user/draft/947210043/schema.png

<?php
// Fichier : local/bibliotheque/lib.php
 
/**
 * Sert les fichiers du plugin local_bibliotheque.
 *
 * Appelée par pluginfile.php quand l'URL commence par
 * /pluginfile.php/{contextid}/local_bibliotheque/...
 *
 * @param stdClass $course        Le cours, si le contexte est dans un cours (sinon null).
 * @param stdClass $cm            Le course_module, si contexte de module (sinon null).
 * @param context  $context       Le contexte reconstruit depuis le contextid de l'URL.
 * @param string   $filearea      La zone demandée (segment de l'URL).
 * @param array    $args          Les segments RESTANTS de l'URL : [itemid?, ...dossiers, filename].
 * @param bool     $forcedownload true si ?forcedownload=1 (Content-Disposition: attachment).
 * @param array    $options       Options de service (cache, etc.).
 * @return bool false si non trouvé/non autorisé (la fonction ne "retourne" jamais en cas de succès :
 *              send_stored_file() termine le script).
 */
function local_bibliotheque_pluginfile($course, $cm, $context, $filearea,
                                       $args, $forcedownload, array $options = []) {
 
    // 1) Vérifier le NIVEAU de contexte attendu. Notre plugin ne stocke
    //    qu'au contexte système : toute autre valeur est suspecte → refus.
    if ($context->contextlevel !== CONTEXT_SYSTEM) {
        return false; // pluginfile.php enverra un 404 propre.
    }
 
    // 2) Vérifier la zone. Un attaquant peut mettre n'importe quoi dans l'URL :
    //    n'acceptez QUE les zones que vous connaissez (liste blanche).
    if ($filearea !== 'documents') {
        return false;
    }
 
    // 3) Authentification. require_login() sans cours pour un plugin système ;
    //    pour du contenu public assumé, on pourrait l'omettre — mais c'est un
    //    choix de sécurité à faire consciemment, jamais un oubli.
    require_login();
 
    // 4) Autorisation métier : la capability qui protège cette zone.
    //    C'est ICI que se joue tout le contrôle d'accès aux fichiers.
    if (!has_capability('local/bibliotheque:consulter', $context)) {
        return false;
    }
 
    // 5) Reconstruire le sextuplé depuis $args.
    //    Convention de CE plugin : l'itemid est le premier segment de l'URL.
    //    $args pour ".../documents/42/dossierA/rapport.pdf" vaut :
    //    ['42', 'dossierA', 'rapport.pdf']
    $itemid = array_shift($args);            // '42'
 
    $filename = array_pop($args);            // 'rapport.pdf' (dernier segment)
    if (empty($args)) {
        $filepath = '/';                     // pas de sous-dossier
    } else {
        $filepath = '/' . implode('/', $args) . '/'; // '/dossierA/'
    }
 
    // 6) Charger le fichier via la File API.
    $fs = get_file_storage();
    $file = $fs->get_file($context->id, 'local_bibliotheque', $filearea,
                          $itemid, $filepath, $filename);
 
    if (!$file || $file->is_directory()) {
        return false; // introuvable, ou quelqu'un demande un "répertoire".
    }
 
    // 7) Envoyer le fichier. send_stored_file() gère les en-têtes HTTP,
    //    les requêtes Range (reprise de téléchargement, streaming vidéo),
    //    le cache navigateur, X-Sendfile si configuré... puis appelle die().
    //    Paramètres : fichier, durée de cache (s), filter, forcedownload, options.
    send_stored_file($file, 86400, 0, $forcedownload, $options);
    // On n'arrive jamais ici.
}

<?php
// Fichier : mod/monmodule/lib.php
function monmodule_pluginfile($course, $cm, $context, $filearea,
                              $args, $forcedownload, array $options = []) {
    if ($context->contextlevel !== CONTEXT_MODULE) {
        return false;
    }
 
    // require_login avec cours + cm : vérifie inscription au cours,
    // visibilité de l'activité, restrictions d'accès (availability)...
    require_login($course, true, $cm);
 
    if ($filearea === 'content') {
        require_capability('mod/monmodule:view', $context);
 
        // Convention "intro-like" pour cette zone : PAS d'itemid dans l'URL,
        // il vaut toujours 0 en base.
        $filename = array_pop($args);
        $filepath = empty($args) ? '/' : '/' . implode('/', $args) . '/';
 
        $fs = get_file_storage();
        $file = $fs->get_file($context->id, 'mod_monmodule', 'content',
                              0, $filepath, $filename);
        if (!$file || $file->is_directory()) {
            send_file_not_found(); // envoie un 404 et die() — équivalent à return false,
                                   // mais utilisable au milieu d'une logique complexe.
        }
        send_stored_file($file, 86400, 0, $forcedownload, $options);
    }
 
    return false; // zone inconnue.
}

   ZONE RÉELLE                        DRAFT AREA (user/draft/{draftid})
   mod_monmodule/attachments/0        contexte utilisateur de l'éditeur
        │                                      │
        │  ① file_prepare_draft_area()         │
        ├─────────── copie ───────────────────►│
        │                                      │  ② l'utilisateur ajoute/supprime
        │                                      │     des fichiers via le filemanager
        │                                      │     (AJAX, repository upload...)
        │  ③ file_save_draft_area_files()      │
        │◄────────── synchronise ──────────────┤
        │   (ajouts copiés, suppressions       │
        │    répercutées, URLs réécrites)      │  ④ le draft devient orphelin,
        │                                      │     purgé plus tard par cron

<?php
namespace local_bibliotheque\form;
 
use moodleform;
 
class document_form extends moodleform {
    protected function definition() {
        $mform = $this->_form;
 
        $mform->addElement('text', 'titre', get_string('titre', 'local_bibliotheque'));
        $mform->setType('titre', PARAM_TEXT);
 
        // L'élément filemanager. Sa "valeur" est un draftid (un int),
        // pas les fichiers eux-mêmes !
        $mform->addElement('filemanager', 'attachments',
            get_string('fichiers', 'local_bibliotheque'), null,
            [
                'subdirs'        => 0,                 // pas de sous-dossiers
                'maxbytes'       => 10485760,           // 10 Mo par fichier
                'maxfiles'       => 5,                  // 5 fichiers max
                'accepted_types' => ['.pdf', '.docx'],  // liste blanche d'extensions
            ]);
 
        $mform->addElement('hidden', 'id');
        $mform->setType('id', PARAM_INT);
 
        $this->add_action_buttons();
    }
}

<?php
require(__DIR__ . '/../../config.php');
 
$id = required_param('id', PARAM_INT);
$context = context_system::instance();
 
require_login();
require_capability('local/bibliotheque:gerer', $context);
 
$PAGE->set_url(new moodle_url('/local/bibliotheque/edit.php', ['id' => $id]));
$PAGE->set_context($context);
 
$document = $DB->get_record('local_bibliotheque_docs', ['id' => $id], '*', MUST_EXIST);
 
// Les options du filemanager — DOIVENT être identiques dans le formulaire,
// dans prepare_draft_area et dans save_draft_area_files. Factoriser !
$fileoptions = [
    'subdirs' => 0, 'maxbytes' => 10485760,
    'maxfiles' => 5, 'accepted_types' => ['.pdf', '.docx'],
];
 
// ───────────────────────────────────────────────────────────────────
// PHASE 1 — Préparer le brouillon (avant d'afficher le formulaire).
// ───────────────────────────────────────────────────────────────────
 
// Récupère le draftid déjà associé à l'élément 'attachments' si le
// formulaire a déjà été soumis (erreur de validation → réaffichage) ;
// sinon renvoie 0 et prepare_draft_area en générera un nouveau.
// CRUCIAL pour ne pas perdre les uploads en cas d'erreur de validation.
$draftitemid = file_get_submitted_draft_itemid('attachments');
 
// Copie les fichiers de la ZONE RÉELLE vers le DRAFT de l'utilisateur.
// Signature : (&$draftitemid, $contextid, $component, $filearea, $itemid, $options)
// $draftitemid est passé PAR RÉFÉRENCE : s'il vaut 0, un nouveau draftid
// aléatoire est généré et écrit dedans.
file_prepare_draft_area(
    $draftitemid,             // in/out : le draftid
    $context->id,             // d'où viennent les fichiers réels
    'local_bibliotheque',
    'attachments',
    $document->id,            // itemid = id du document
    $fileoptions
);
 
// Injecter le draftid comme valeur par défaut de l'élément filemanager.
$document->attachments = $draftitemid;
 
$mform = new \local_bibliotheque\form\document_form();
$mform->set_data($document);
 
// ───────────────────────────────────────────────────────────────────
// PHASE 2 — Traiter la soumission.
// ───────────────────────────────────────────────────────────────────
if ($mform->is_cancelled()) {
    // Rien à nettoyer : le draft sera purgé automatiquement par cron.
    redirect(new moodle_url('/local/bibliotheque/index.php'));
 
} else if ($data = $mform->get_data()) {
    $DB->update_record('local_bibliotheque_docs', (object) [
        'id' => $data->id, 'titre' => $data->titre, 'timemodified' => time(),
    ]);
 
    // Synchroniser le DRAFT vers la ZONE RÉELLE :
    //  - les fichiers ajoutés dans le draft sont copiés dans la zone réelle ;
    //  - les fichiers supprimés du draft sont supprimés de la zone réelle ;
    //  - les fichiers inchangés sont conservés (aucun blob dupliqué).
    // Les mêmes $fileoptions font respecter maxfiles/subdirs/accepted_types
    // CÔTÉ SERVEUR (jamais confiance au client !).
    file_save_draft_area_files(
        $data->attachments,       // le draftid soumis par le formulaire
        $context->id,
        'local_bibliotheque',
        'attachments',
        $data->id,                // itemid de la zone réelle
        $fileoptions
    );
 
    redirect(new moodle_url('/local/bibliotheque/index.php'),
        get_string('changessaved'), null, \core\output\notification::NOTIFY_SUCCESS);
}
 
echo $OUTPUT->header();
$mform->display();
echo $OUTPUT->footer();

<!-- Ce qui est stocké dans la colonne intro de mdl_assign : -->
<p>Étudiez le schéma :</p>
<img src="@@PLUGINFILE@@/schema.png" alt="Architecture">
<img src="@@PLUGINFILE@@/images/detail.png" alt="Détail">

<?php
// Affichage de la description d'une instance de module avec images embarquées.
$context = context_module::instance($cm->id);
 
// 1) Réécrire @@PLUGINFILE@@ en vraies URLs pluginfile.php.
//    Signature : ($text, $file, $contextid, $component, $filearea, $itemid, $options)
//    Le 2e paramètre est le nom du script de service ('pluginfile.php' dans
//    99 % des cas ; 'draftfile.php' pour prévisualiser un brouillon).
$intro = file_rewrite_pluginfile_urls(
    $instance->intro,   // le texte brut venant de la base
    'pluginfile.php',
    $context->id,
    'mod_monmodule',
    'intro',
    null                // itemid : null → PAS d'itemid dans l'URL (convention "intro") ;
                        // passez un int pour l'inclure (convention avec itemid).
);
 
// 2) PUIS formater (filtres, nettoyage XSS...) — cf. chapitre 04.
echo format_text($intro, $instance->introformat, ['context' => $context]);
 
// Résultat rendu :
// <img src="https://monsite/pluginfile.php/950/mod_monmodule/intro/schema.png" ...>

<?php
$fs = get_file_storage();
$files = $fs->get_area_files($context->id, 'local_bibliotheque', 'attachments',
                             $document->id, 'filename', false);
 
foreach ($files as $file) {
    // Signature : make_pluginfile_url($contextid, $component, $area,
    //                                 $itemid, $pathname, $filename,
    //                                 $forcedownload = false)
    $url = moodle_url::make_pluginfile_url(
        $file->get_contextid(),
        $file->get_component(),
        $file->get_filearea(),
        $file->get_itemid(),   // passez null si votre callback n'attend pas d'itemid !
        $file->get_filepath(),
        $file->get_filename(),
        true                   // forcedownload : Content-Disposition attachment
    );
 
    echo html_writer::link($url, s($file->get_filename()));
}

<?php
// get_string('identifiant', 'composant', $donnees_optionnelles)
 
echo get_string('pluginname', 'local_bibliotheque'); // "Bibliothèque documentaire"
echo get_string('save');                  // composant omis = 'core' (alias 'moodle')
echo get_string('modulename', 'mod_quiz');
echo get_string('privacy:metadata', 'local_bibliotheque');

<?php
// Fichier : local/bibliotheque/lang/en/local_bibliotheque.php
// Le nom du fichier = frankenstyle du plugin, OBLIGATOIREMENT.
 
defined('MOODLE_INTERNAL') || die();
 
// 'pluginname' est OBLIGATOIRE pour tout plugin : c'est le nom affiché
// dans l'administration, la liste des plugins, etc.
$string['pluginname'] = 'Document library';
 
$string['titre'] = 'Title';
$string['fichiers'] = 'Attached files';
 
// Convention : 'xxx_help' est le texte du bouton d'aide (?) associé à
// l'élément de formulaire dont le label est la chaîne 'xxx'.
// $mform->addHelpButton('titre', 'titre', 'local_bibliotheque');
$string['titre_help'] = 'The title is displayed in the library index and in search results.';
 
// Convention : les chaînes 'privacy:metadata...' décrivent les données
// personnelles stockées (Privacy API / RGPD) — contrôlées par les tests.
$string['privacy:metadata'] = 'The Document library plugin does not store any personal data.';
 
// Convention : les noms de capabilities → 'nomplugin:capability'.
$string['bibliotheque:gerer'] = 'Manage library documents';
 
// Convention : les noms de tâches planifiées, d'événements, de settings...
$string['apikey'] = 'API key';
$string['apikey_desc'] = 'Key used to authenticate against the external catalogue service.';

<?php
// new lang_string : une chaîne à résolution PAResseuse. La traduction n'est
// effectuée qu'à la conversion en string (__toString). Indispensable dans
// les endroits exécutés AVANT que la langue de l'utilisateur soit connue,
// typiquement settings.php (chargé aussi par CLI/install) :
$title = new lang_string('apikey', 'local_bibliotheque');
 
// get_strings : résoudre plusieurs chaînes d'un coup (micro-optimisation
// + lisibilité) — renvoie un stdClass avec une propriété par identifiant :
$strs = get_strings(['save', 'cancel', 'delete'], 'core');
echo $strs->save;
 
// ─── À NE PAS FAIRE ───
// ❌ addslashes()/échappement manuel dans les fichiers de langue : les
//    chaînes sont du PHP normal, on échappe uniquement la syntaxe PHP
//    (apostrophe dans une chaîne à quotes simples : 'l\'utilisateur').
//    Aucun échappement HTML/SQL dans les fichiers lang.
// ❌ Concaténer des morceaux de phrases traduites : l'ordre des mots change
//    selon les langues. Utilisez les placeholders {$a} (section 7).
// ❌ Appeler get_string dans une boucle serrée sur la même clé : le string
//    manager cache déjà, mais sortez l'appel de la boucle par principe.

// En JavaScript (module AMD/ESM) — asynchrone, car chargé via AJAX + cache :
import {getString} from 'core/str';
const label = await getString('fichiers', 'local_bibliotheque');

{{! Dans un template Mustache — le helper str : }}
{{#str}} fichiers, local_bibliotheque {{/str}}

<?php
// ── Cas scalaire : {$a} tout court ──
// lang/en : $string['docscount'] = 'The library contains {$a} documents.';
echo get_string('docscount', 'local_bibliotheque', 42);
// → "The library contains 42 documents."
 
// ── Cas structuré : {$a->propriete} — objet OU tableau associatif ──
// lang/en : $string['uploadedby'] = '{$a->filename} uploaded by {$a->author} on {$a->date}';
$a = (object) [
    'filename' => $file->get_filename(),
    'author'   => fullname($uploader),
    'date'     => userdate($file->get_timecreated()),
];
echo get_string('uploadedby', 'local_bibliotheque', $a);
// → "rapport.pdf uploaded by Ada Lovelace on 8 July 2026, 10:15 AM"
 
// Un tableau associatif marche aussi :
echo get_string('uploadedby', 'local_bibliotheque',
    ['filename' => 'x.pdf', 'author' => 'Ada', 'date' => 'today']);

<?php
// ❌ DANGEREUX : $record->titre vient d'un utilisateur. S'il contient
// "<script>...", il sera rendu tel quel dans la page.
echo get_string('deleteconfirm', 'local_bibliotheque', $record->titre);
 
// ✅ CORRECT : nettoyer la donnée AVANT de l'injecter.
// format_string() pour un contenu "une ligne" saisi par un utilisateur
// (applique aussi les filtres, ex. multilangue) :
echo get_string('deleteconfirm', 'local_bibliotheque',
    format_string($record->titre, true, ['context' => $context]));
 
// Ou s() (htmlspecialchars) pour un échappement brut sans filtres :
echo get_string('deleteconfirm', 'local_bibliotheque', s($record->titre));

<?php
// Workaround 1 (le standard Moodle) : deux chaînes distinctes + un if.
// lang/en :
//   $string['numdoc']  = '{$a} document';
//   $string['numdocs'] = '{$a} documents';
$count = count($documents);
echo ($count == 1)
    ? get_string('numdoc', 'local_bibliotheque', $count)
    : get_string('numdocs', 'local_bibliotheque', $count);
 
// Workaround 2 : formulation neutre qui évite le problème.
// $string['doccount'] = 'Documents: {$a}';   → "Documents : 42"
 
// Workaround 3 (dates/durées) : le cœur fournit format_time(), get_string
// avec des unités séparées ('numdays', 'numhours'...), etc. Réutilisez-les.

<?php
// ── Lire ──
 
// Toute la config d'un plugin d'un coup : renvoie un stdClass
// (propriétés = noms de réglages). Propriété absente si jamais définie !
$config = get_config('local_bibliotheque');
if (!empty($config->apikey)) {
    $client = new api_client($config->apikey, $config->endpoint);
}
 
// Un seul réglage : renvoie la valeur, ou FALSE si non défini.
$apikey = get_config('local_bibliotheque', 'apikey');
if ($apikey === false) {
    // Réglage jamais défini — distinct de '' (défini mais vide) !
    throw new moodle_exception('apikeynotset', 'local_bibliotheque');
}
 
// ── Écrire ──
// set_config($name, $value, $plugin) — $value est TOUJOURS stocké en texte.
set_config('apikey', 'sk-abc123', 'local_bibliotheque');
set_config('maxdocs', 500, 'local_bibliotheque');   // relu comme la CHAÎNE '500'
set_config('enabled', 1, 'local_bibliotheque');      // les booléens → '1'/'0'
 
// ── Supprimer ──
unset_config('apikey', 'local_bibliotheque');   // la clé disparaît (≠ mettre '')

<?php
global $CFG;
 
// Réglages CŒUR : propriétés de l'objet global $CFG, chargé depuis la
// table config au bootstrap (+ config.php par-dessus).
echo $CFG->wwwroot;      // URL racine du site (vient de config.php)
echo $CFG->dataroot;     // chemin moodledata (config.php)
echo $CFG->maxbytes;     // taille max d'upload (table config, modifiable en admin)
echo $CFG->theme;        // thème du site
 
// Équivalence : get_config('core', 'theme') === $CFG->theme.
// ('core' et 'moodle' sont synonymes ici.)
 
// Réglages PLUGIN : JAMAIS sur $CFG → toujours get_config('frankenstyle').
$maxdocs = get_config('local_bibliotheque', 'maxdocs');

<?php
// config.php — exécuté à CHAQUE requête, avant tout.
 
// Réglage cœur forcé : simple propriété de $CFG. La valeur en base est
// ignorée et l'UI d'admin affiche le réglage grisé "Défini dans config.php".
$CFG->theme = 'boost';
$CFG->debug = E_ALL;                 // env de dev
$CFG->debugdisplay = 1;
 
// Réglages de PLUGIN forcés : via le tableau forced_plugin_settings,
// indexé par frankenstyle puis par nom de réglage.
$CFG->forced_plugin_settings = [
    'local_bibliotheque' => [
        'apikey'   => getenv('BIBLIO_API_KEY'),  // tirer de l'environnement !
        'endpoint' => 'https://catalogue.example.com/api',
    ],
    'tool_mobile' => [
        'enablesmartappbanners' => 0,
    ],
];

<?php
// Fichier : local/bibliotheque/settings.php
// Chargé quand l'arbre d'admin est construit (pages d'admin, upgrade...).
 
defined('MOODLE_INTERNAL') || die();
 
// $hassiteconfig est fourni par le chargeur : true si l'utilisateur courant
// a la capability moodle/site:config. Quand l'arbre est construit pour un
// utilisateur SANS ce droit, $settings vaut NULL → toujours garder ce if,
// sinon fatal error "Call to a member function add() on null".
if ($hassiteconfig) {
 
    // $settings est une admin_settingpage déjà créée par le cœur pour les
    // plugins 'local'. (Pour certains types, $settings est null et il faut
    // créer la page soi-même — voir 9.3.)
 
    // ── Un en-tête de section (titre + paragraphe, aucun réglage stocké) ──
    $settings->add(new admin_setting_heading(
        'local_bibliotheque/apiheading',                     // nom unique
        get_string('apiheading', 'local_bibliotheque'),      // titre
        get_string('apiheading_desc', 'local_bibliotheque')  // description
    ));
 
    // ── Champ texte ──
    // Args : nom 'plugin/reglage', libellé, description, valeur par défaut, type PARAM.
    $settings->add(new admin_setting_configtext(
        'local_bibliotheque/endpoint',
        get_string('endpoint', 'local_bibliotheque'),
        get_string('endpoint_desc', 'local_bibliotheque'),
        'https://catalogue.example.com/api',   // défaut
        PARAM_URL                              // validation/nettoyage à la sauvegarde
    ));
 
    // ── Mot de passe / secret : masqué à l'écran, bouton "révéler" ──
    $settings->add(new admin_setting_configpasswordunmask(
        'local_bibliotheque/apikey',
        get_string('apikey', 'local_bibliotheque'),
        get_string('apikey_desc', 'local_bibliotheque'),
        ''                                     // pas de défaut pour un secret
    ));
 
    // ── Case à cocher : valeurs stockées pour coché/décoché ('1'/'0') ──
    $settings->add(new admin_setting_configcheckbox(
        'local_bibliotheque/enabled',
        get_string('enabled', 'local_bibliotheque'),
        get_string('enabled_desc', 'local_bibliotheque'),
        1,        // défaut : activé
        '1', '0'  // valeurs stockées (défauts, souvent omis)
    ));
 
    // ── Liste déroulante : tableau valeur => libellé ──
    $settings->add(new admin_setting_configselect(
        'local_bibliotheque/sortmode',
        get_string('sortmode', 'local_bibliotheque'),
        get_string('sortmode_desc', 'local_bibliotheque'),
        'title',                                             // défaut
        [
            'title' => get_string('sortbytitle', 'local_bibliotheque'),
            'date'  => get_string('sortbydate', 'local_bibliotheque'),
        ]
    ));
 
    // ── Zone de texte multi-lignes (brut) ──
    $settings->add(new admin_setting_configtextarea(
        'local_bibliotheque/allowedhosts',
        get_string('allowedhosts', 'local_bibliotheque'),
        get_string('allowedhosts_desc', 'local_bibliotheque'),
        ''
    ));
 
    // ── Éditeur HTML (contenu riche, ex. message d'accueil) ──
    $settings->add(new admin_setting_confightmleditor(
        'local_bibliotheque/welcomemessage',
        get_string('welcomemessage', 'local_bibliotheque'),
        get_string('welcomemessage_desc', 'local_bibliotheque'),
        ''
    ));
 
    // ── Durée : rendue avec nombre + unité, stockée en SECONDES ──
    $settings->add(new admin_setting_configduration(
        'local_bibliotheque/cachettl',
        get_string('cachettl', 'local_bibliotheque'),
        get_string('cachettl_desc', 'local_bibliotheque'),
        3600,     // défaut : 1 h
        3600      // unité affichée par défaut : heures
    ));
 
    // ── Sélecteur de couleur ──
    $settings->add(new admin_setting_configcolourpicker(
        'local_bibliotheque/accentcolour',
        get_string('accentcolour', 'local_bibliotheque'),
        get_string('accentcolour_desc', 'local_bibliotheque'),
        '#0f6cbf'
    ));
 
    // ── Fichier stocké : dépose un fichier dans une zone du contexte système
    //    (component = frankenstyle du plugin, filearea/itemid = args).
    //    Boucle avec la Partie A : on le relit avec get_area_files() ! ──
    $settings->add(new admin_setting_configstoredfile(
        'local_bibliotheque/logo',
        get_string('logo', 'local_bibliotheque'),
        get_string('logo_desc', 'local_bibliotheque'),
        'logo',                                  // filearea
        0,                                       // itemid
        ['maxfiles' => 1, 'accepted_types' => ['web_image']]
    ));
}

<?php
// settings.php d'un plugin plus ambitieux.
defined('MOODLE_INTERNAL') || die();
 
if ($hassiteconfig) {
 
    // 1) Une CATÉGORIE à nous dans l'arborescence.
    //    add(parent, noeud) : 'localplugins' est la catégorie des plugins locaux.
    $ADMIN->add('localplugins', new admin_category(
        'local_bibliotheque_cat',                              // nom interne unique
        new lang_string('pluginname', 'local_bibliotheque')    // libellé (lazy !)
    ));
 
    // 2) Une page de réglages déclarative DANS notre catégorie.
    $page = new admin_settingpage(
        'local_bibliotheque_general',
        new lang_string('generalsettings', 'local_bibliotheque')
    );
    $page->add(new admin_setting_configtext(
        'local_bibliotheque/endpoint',
        new lang_string('endpoint', 'local_bibliotheque'),
        new lang_string('endpoint_desc', 'local_bibliotheque'),
        '', PARAM_URL
    ));
    $ADMIN->add('local_bibliotheque_cat', $page);
 
    // 3) Une page ENTIÈREMENT CUSTOM (votre propre script PHP : tableau de
    //    bord, outil d'import...) : admin_externalpage l'enregistre dans
    //    l'arbre + la recherche admin, et pointe vers votre URL.
    $ADMIN->add('local_bibliotheque_cat', new admin_externalpage(
        'local_bibliotheque_import',                           // nom interne
        new lang_string('importtool', 'local_bibliotheque'),
        new moodle_url('/local/bibliotheque/import.php'),      // votre page
        'local/bibliotheque:gerer'                             // capability requise
    ));
 
    // Quand on gère l'arbre soi-même, on neutralise la page auto-fournie
    // pour éviter un doublon vide dans le menu :
    $settings = null;
}

<?php
require(__DIR__ . '/../../config.php');
require_once($CFG->libdir . '/adminlib.php');
 
// admin_externalpage_setup fait tout le rituel : require_login, vérification
// de la capability déclarée, $PAGE->set_context/set_url, fil d'Ariane admin...
admin_externalpage_setup('local_bibliotheque_import'); // ← le nom interne déclaré
 
echo $OUTPUT->header();
echo $OUTPUT->heading(get_string('importtool', 'local_bibliotheque'));
// ... votre outil ...
echo $OUTPUT->footer();