03 — Form API : moodleform

local/foo/
└── classes/
    └── form/
        └── entry_form.php   →  classe \local_foo\form\entry_form

<?php
// Fichier : local/foo/classes/form/entry_form.php
 
namespace local_foo\form;
 
// formslib.php n'est PAS autoloadé : les classes moodleform et
// MoodleQuickForm sont des classes "legacy" définies dans ce fichier.
// Le require_once est donc obligatoire même en 2026.
defined('MOODLE_INTERNAL') || die();
 
require_once($CFG->libdir . '/formslib.php');
 
/**
 * Formulaire d'édition d'une entrée.
 *
 * @package    local_foo
 * @copyright  2026 Votre nom
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
class entry_form extends \moodleform {
 
    protected function definition() {
        // Voir section 2.
    }
}

<?php
namespace local_annonces\form;
 
defined('MOODLE_INTERNAL') || die();
 
require_once($CFG->libdir . '/formslib.php');
 
class annonce_form extends \moodleform {
 
    /**
     * Déclaration de la structure du formulaire.
     * Appelée automatiquement par le constructeur — ne l'appelez jamais vous-même.
     */
    protected function definition() {
        $mform = $this->_form;
 
        // Récupération des données injectées par la page appelante.
        $courseid   = $this->_customdata['courseid'];
        $categories = $this->_customdata['categories'];   // Tableau id => nom.
        $canpin     = $this->_customdata['canpin'];       // Booléen : capacité de l'utilisateur.
 
        // --- Section 1 : Général -------------------------------------------
        $mform->addElement('header', 'generalheader', get_string('general'));
 
        // Champ texte : titre de l'annonce.
        $mform->addElement('text', 'title', get_string('title', 'local_annonces'),
            ['size' => 60, 'maxlength' => 255]);
        $mform->setType('title', PARAM_TEXT);                          // OBLIGATOIRE (section 4).
        $mform->addRule('title', get_string('required'), 'required', null, 'client');
        $mform->addRule('title', get_string('maximumchars', '', 255), 'maxlength', 255, 'client');
 
        // Liste déroulante : catégorie.
        $mform->addElement('select', 'categoryid', get_string('category', 'local_annonces'),
            $categories);
        $mform->setType('categoryid', PARAM_INT);
        $mform->setDefault('categoryid', 0);
 
        // Case à cocher, uniquement si l'utilisateur en a la capacité.
        // La logique métier (has_capability) vit dans la PAGE, pas ici :
        // definition() ne fait que consommer le résultat via _customdata.
        if ($canpin) {
            $mform->addElement('advcheckbox', 'pinned',
                get_string('pinned', 'local_annonces'), '', [], [0, 1]);
            $mform->setType('pinned', PARAM_INT);
            $mform->addHelpButton('pinned', 'pinned', 'local_annonces');
        }
 
        // --- Section 2 : Publication ---------------------------------------
        $mform->addElement('header', 'publishheader',
            get_string('publication', 'local_annonces'));
        $mform->setExpanded('publishheader', false);   // Section repliée par défaut.
 
        // Date de publication, désactivable ("Enable" checkbox intégrée).
        $mform->addElement('date_time_selector', 'timepublished',
            get_string('timepublished', 'local_annonces'), ['optional' => true]);
 
        // --- Champs cachés et boutons ---------------------------------------
        // L'id de l'enregistrement (0 = création) et le cours, transportés
        // silencieusement entre affichage et soumission.
        $mform->addElement('hidden', 'id');
        $mform->setType('id', PARAM_INT);
 
        $mform->addElement('hidden', 'courseid', $courseid);
        $mform->setType('courseid', PARAM_INT);
 
        // Boutons Enregistrer / Annuler standardisés.
        $this->add_action_buttons(true, get_string('savechanges'));
    }
}

$mform->addElement($type, $name, $label, $options_ou_attributs, ...);

// text : champ texte simple. 4e argument = attributs HTML (string ou array).
$mform->addElement('text', 'fullname', get_string('fullname'),
    ['size' => 50, 'maxlength' => 100, 'placeholder' => get_string('fullname')]);
$mform->setType('fullname', PARAM_TEXT);
 
// textarea : zone de texte multiligne SANS mise en forme (pas d'éditeur riche).
$mform->addElement('textarea', 'notes', get_string('notes', 'local_foo'),
    ['rows' => 6, 'cols' => 60]);
$mform->setType('notes', PARAM_TEXT);
 
// passwordunmask : mot de passe avec bouton "révéler". À préférer à 'password'
// (l'élément 'password' brut existe mais l'unmask est le standard Moodle).
$mform->addElement('passwordunmask', 'apikey', get_string('apikey', 'local_foo'));
$mform->setType('apikey', PARAM_RAW_TRIMMED);   // Un secret ne doit PAS être altéré.
 
// float : nombre décimal respectant le séparateur de la locale (virgule en FR !).
// Exception à la règle : NE PAS appeler setType() sur un élément float,
// il gère lui-même la conversion locale → float PHP.
$mform->addElement('float', 'weight', get_string('weight', 'local_foo'), ['size' => 6]);
$mform->setDefault('weight', 1.0);

// select simple.
$mform->addElement('select', 'format', get_string('format'), [
    0 => get_string('formatplain', 'local_foo'),
    1 => get_string('formathtml', 'local_foo'),
]);
$mform->setType('format', PARAM_INT);
 
// select multiple : ajoutez l'attribut 'multiple'. La valeur soumise est un tableau.
$select = $mform->addElement('select', 'roles', get_string('roles'), $rolesmenu);
$select->setMultiple(true);
// Pas de setType sur un select multiple retournant un tableau d'entiers connus :
// les valeurs sont validées contre la liste d'options. Vous POUVEZ mettre PARAM_INT,
// il sera appliqué à chaque élément du tableau.
 
// autocomplete : le select moderne, avec recherche. Remplace 'select' dès que
// la liste dépasse ~15 entrées.
$options = [
    'multiple' => true,
    'noselectionstring' => get_string('allareas', 'search'),
    'placeholder' => get_string('search'),
];
$mform->addElement('autocomplete', 'userids', get_string('users'), $usersmenu, $options);
 
// autocomplete avec AJAX : les options sont chargées dynamiquement par un module
// AMD qui implémente transport() et processResults(). Idéal pour chercher parmi
// des milliers d'utilisateurs sans tout charger dans la page.
$options = [
    'multiple' => true,
    'ajax' => 'core_user/form_user_selector',   // Module AMD fournissant la recherche.
    'valuehtmlcallback' => function($userid) {
        // Rend le libellé des valeurs déjà sélectionnées (mode édition).
        $user = \core_user::get_user($userid);
        return fullname($user);
    },
];
$mform->addElement('autocomplete', 'recipients',
    get_string('recipients', 'local_foo'), [], $options);
 
// autocomplete avec tags : l'utilisateur peut saisir des valeurs libres,
// pas seulement choisir dans la liste.
$mform->addElement('autocomplete', 'keywords', get_string('keywords', 'local_foo'),
    $existingkeywords, ['multiple' => true, 'tags' => true]);

// checkbox : simple, mais ATTENTION — si décochée, le navigateur n'envoie RIEN,
// donc la clé est absente des données soumises.
$mform->addElement('checkbox', 'sendnotification', get_string('notify', 'local_foo'));
 
// advcheckbox : LA case à cocher à utiliser. Elle envoie TOUJOURS une valeur
// grâce à un champ caché jumelé : ici 0 si décochée, 1 si cochée.
$mform->addElement('advcheckbox', 'visible', get_string('visible'),
    get_string('visibledesc', 'local_foo'),   // Texte à droite de la case.
    [],                                        // Attributs HTML.
    [0, 1]);                                   // [valeur décochée, valeur cochée].
$mform->setType('visible', PARAM_INT);
$mform->setDefault('visible', 1);
 
// radio : toujours en GROUPE, sinon l'alignement et les labels sont cassés.
$radioarray = [];
$radioarray[] = $mform->createElement('radio', 'mode', '',
    get_string('modeauto', 'local_foo'), 'auto');
$radioarray[] = $mform->createElement('radio', 'mode', '',
    get_string('modemanual', 'local_foo'), 'manual');
$mform->addGroup($radioarray, 'modegroup', get_string('mode', 'local_foo'),
    ['<br>'], false);   // false = les éléments gardent leur propre nom ('mode').
$mform->setDefault('mode', 'auto');
$mform->setType('mode', PARAM_ALPHA);

// date_selector : jour/mois/année.
$mform->addElement('date_selector', 'startdate', get_string('startdate', 'local_foo'));
$mform->setDefault('startdate', time());
 
// date_time_selector : idem + heure/minute.
// 'optional' => true ajoute une case "Activer" : si décochée, la valeur soumise est 0.
$mform->addElement('date_time_selector', 'deadline',
    get_string('deadline', 'local_foo'),
    ['optional' => true, 'startyear' => 2020, 'stopyear' => 2035]);
 
// duration : un nombre + une unité (secondes/minutes/heures/jours/semaines).
// La valeur soumise est TOUJOURS en secondes.
$mform->addElement('duration', 'timelimit', get_string('timelimit', 'local_foo'),
    ['optional' => true, 'defaultunit' => MINSECS]);
$mform->setDefault('timelimit', 30 * MINSECS);

// header : ouvre une SECTION repliable. Tous les éléments suivants y appartiennent
// jusqu'au prochain header.
$mform->addElement('header', 'advancedheader', get_string('advanced'));
$mform->setExpanded('advancedheader', false);          // Repliée par défaut.
// setExpanded('...', true, true) : 3e argument = l'utilisateur ne peut pas
// l'avoir déjà repliée lui-même (ignore la préférence utilisateur).
 
// static : un couple label + texte non éditable. Pratique pour afficher une
// information contextuelle dans l'alignement du formulaire.
$mform->addElement('static', 'currentowner', get_string('owner', 'local_foo'),
    fullname($owner));
 
// html : du HTML brut, pleine largeur, hors grille label/champ.
// À utiliser avec parcimonie (et via le renderer/les templates si possible).
$mform->addElement('html', \html_writer::div(
    get_string('warningbanner', 'local_foo'), 'alert alert-warning'));
 
// hidden : champ caché. TOUJOURS suivi d'un setType (c'est une entrée
// utilisateur comme une autre : un attaquant peut modifier sa valeur !).
$mform->addElement('hidden', 'returnurl', $returnurl);
$mform->setType('returnurl', PARAM_LOCALURL);

// Boutons individuels (rarement utilisés seuls — préférez add_action_buttons).
$mform->addElement('submit', 'submitbutton', get_string('savechanges'));
$mform->addElement('cancel', 'cancelbutton', get_string('cancel'));
$mform->addElement('button', 'previewbutton', get_string('preview'));  // Bouton JS pur.
 
// Un bouton submit qui NE déclenche PAS la validation ni get_data :
// utile pour les boutons "recharger une partie du formulaire".
$mform->registerNoSubmitButton('reloadoptions');
$mform->addElement('submit', 'reloadoptions', get_string('reload', 'local_foo'));
 
// addGroup : aligne plusieurs éléments sur UNE ligne, sous UN label.
$group = [];
$group[] = $mform->createElement('text', 'quantity', '', ['size' => 4]);
$group[] = $mform->createElement('select', 'unit', '', [
    'kg' => 'kg', 'g' => 'g', 'l' => 'l',
]);
$mform->addGroup($group, 'quantitygroup', get_string('quantity', 'local_foo'),
    ' ', false);   // Séparateur ' ', false = noms non préfixés par le nom du groupe.
$mform->setType('quantity', PARAM_INT);
 
// add_action_buttons : LE standard. Génère "Enregistrer" + "Annuler" dans une
// barre collante en bas de page (Moodle 4/5). Toujours en DERNIER dans definition().
$this->add_action_buttons(true, get_string('savechanges'));
// add_action_buttons(false) : bouton Enregistrer seul, sans Annuler.

// editor : éditeur riche (TinyMCE) avec fichiers embarqués.
$mform->addElement('editor', 'message_editor', get_string('message', 'local_foo'),
    null, $editoroptions);
$mform->setType('message_editor', PARAM_RAW);   // Cas légitime de PARAM_RAW !
 
// filepicker : UN fichier, sans gestion (typiquement pour un import ponctuel).
$mform->addElement('filepicker', 'importfile', get_string('file'), null,
    ['maxbytes' => $CFG->maxbytes, 'accepted_types' => ['.csv']]);
 
// filemanager : PLUSIEURS fichiers persistants, avec dossiers.
$mform->addElement('filemanager', 'attachments_filemanager',
    get_string('attachments', 'local_foo'), null,
    ['subdirs' => 0, 'maxbytes' => $CFG->maxbytes, 'maxfiles' => 10,
     'accepted_types' => ['document', 'image']]);

// course : sélecteur de cours avec recherche AJAX intégrée (autocomplete spécialisé).
$mform->addElement('course', 'targetcourse', get_string('course'),
    ['multiple' => false, 'includefrontpage' => false,
     'requiredcapabilities' => ['moodle/course:update']]);
 
// tags : intégration avec la Tag API du noyau (suggestions de tags standards).
$mform->addElement('tags', 'tags', get_string('tags'),
    ['itemtype' => 'annonce', 'component' => 'local_annonces']);
 
// recaptcha : le captcha configuré au niveau du site (clés dans l'admin).
// À n'afficher que si signup_captcha_enabled() / configuration présente.
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) {
    $mform->addElement('recaptcha', 'recaptcha_element', get_string('security_question', 'auth'));
    $mform->addHelpButton('recaptcha_element', 'recaptcha', 'auth');
}
// Dans validation() : $this->_form->getElement('recaptcha_element')->verify(...)
// via $errors — voir le formulaire de signup du noyau (login/signup_form.php).

Did you remember to call setType() for 'title'? Defaulting to PARAM_RAW cleaning.

$mform->setType('title', PARAM_TEXT);        // Un titre : jamais de HTML dedans.
$mform->setType('id', PARAM_INT);            // Un id : entier, point final.
$mform->setType('email', PARAM_EMAIL);       // Rejeté (vidé) si invalide.
$mform->setType('message_editor', PARAM_RAW); // L'éditeur produit du HTML : légitime.

// Signature : addRule($element, $message, $type, $format, $validation)
//   $validation : 'client' (JS + re-vérifié serveur) ou 'server' (défaut, serveur seul).
 
$mform->addRule('title', get_string('required'), 'required', null, 'client');
$mform->addRule('title', get_string('maximumchars', '', 255), 'maxlength', 255, 'client');
$mform->addRule('quantity', get_string('err_numeric', 'form'), 'numeric', null, 'client');
$mform->addRule('email', get_string('invalidemail'), 'email', null, 'client');
$mform->addRule('code', get_string('err_alphanumeric', 'form'), 'alphanumeric', null, 'client');
$mform->addRule('slug', get_string('invalidslug', 'local_foo'), 'regex',
    '/^[a-z0-9\-]+$/', 'client');
$mform->addRule('attempts', get_string('err_nonzero', 'form'), 'nonzero', null, 'server');

$mform->setDefault('visible', 1);              // Valeur initiale si set_data ne fournit rien.
$mform->setDefault('startdate', time());
$mform->setConstant('courseid', $courseid);    // Force la valeur, IGNORE ce qui est soumis.

$mform->addHelpButton('pinned', 'pinned', 'local_annonces');

$string['pinned'] = 'Pin this announcement';
$string['pinned_help'] = 'A pinned announcement always appears at the top of the list,
regardless of its publication date.';

// Signature : disabledIf($element, $dependenton, $condition, $value)
// hideIf a la même signature (Moodle 3.4+) mais CACHE au lieu de griser.
 
// Griser 'deadline' si la case 'hasdeadline' n'est pas cochée.
$mform->disabledIf('deadline', 'hasdeadline', 'notchecked');
 
// Cacher 'notifymessage' tant que 'sendnotification' n'est pas cochée.
$mform->hideIf('notifymessage', 'sendnotification', 'notchecked');
 
// Tous les opérateurs disponibles :
$mform->hideIf('a', 'mode', 'eq', 'auto');          // mode == 'auto'
$mform->hideIf('b', 'mode', 'neq', 'manual');       // mode != 'manual'
$mform->hideIf('c', 'confirm', 'checked');          // case cochée
$mform->hideIf('d', 'confirm', 'notchecked');       // case décochée
$mform->hideIf('e', 'categoryid', 'in', [2, 5, 9]); // valeur parmi la liste
$mform->hideIf('f', 'userids', 'noitemselected');   // autocomplete vide
 
// Fonctionne aussi sur un GROUPE entier ou une valeur de groupe :
$mform->hideIf('quantitygroup', 'mode', 'eq', 'auto');

// freeze : affiche la valeur en lecture seule (le champ n'est plus éditable).
// hardFreeze (défaut de freeze) : la valeur n'est même plus soumise.
if (!$caneditcategory) {
    $mform->freeze('categoryid');
}
 
// setAdvanced : le champ est masqué derrière le lien "Afficher plus…"
// de sa section. Pour les options pointues que 95% des utilisateurs ignorent.
$mform->setAdvanced('customcss', true);

/**
 * Validation serveur personnalisée.
 *
 * @param array $data  Données soumises, DÉJÀ nettoyées par setType (tableau, pas objet !).
 * @param array $files Fichiers soumis.
 * @return array Tableau nomduchamp => message d'erreur. Vide = formulaire valide.
 */
public function validation($data, $files) {
    global $DB;
 
    // TOUJOURS commencer par la validation du parent (règles addRule serveur, etc.).
    $errors = parent::validation($data, $files);
 
    // 1. Unicité en base de données : pas deux annonces avec le même titre
    //    dans le même cours (en excluant l'enregistrement en cours d'édition).
    $params = ['title' => $data['title'], 'courseid' => $data['courseid']];
    $existing = $DB->get_record('local_annonces', $params, 'id', IGNORE_MULTIPLE);
    if ($existing && (int) $existing->id !== (int) $data['id']) {
        $errors['title'] = get_string('errduplicatetitle', 'local_annonces');
    }
 
    // 2. Cohérence de dates : la date limite doit suivre la publication.
    //    Rappel : un date_time_selector 'optional' décoché vaut 0.
    if (!empty($data['deadline']) && !empty($data['timepublished'])
            && $data['deadline'] <= $data['timepublished']) {
        // L'erreur s'affiche sous le champ fautif.
        $errors['deadline'] = get_string('errdeadlinebeforepublish', 'local_annonces');
    }
 
    // 3. Validation croisée : le mode 'manual' exige au moins un destinataire.
    if ($data['mode'] === 'manual' && empty($data['recipients'])) {
        $errors['recipients'] = get_string('errnorecipients', 'local_annonces');
    }
 
    // 4. Règle métier avec paramètre dans le message :
    //    get_string accepte un 3e argument injecté dans {$a}.
    $max = get_config('local_annonces', 'maxpinned');
    if (!empty($data['pinned'])) {
        $count = $DB->count_records('local_annonces',
            ['courseid' => $data['courseid'], 'pinned' => 1]);
        if ($count >= $max) {
            $errors['pinned'] = get_string('errtoomanypinned', 'local_annonces', $max);
        }
    }
 
    return $errors;
}

<?php
// Fichier : local/annonces/edit.php
 
require_once(__DIR__ . '/../../config.php');   // Bootstrap Moodle (chapitre 01).
 
use local_annonces\form\annonce_form;
 
// --- 1. Paramètres d'entrée, contexte, sécurité -----------------------------
$courseid = required_param('courseid', PARAM_INT);
$id       = optional_param('id', 0, PARAM_INT);   // 0 = création.
 
$course  = get_course($courseid);
require_login($course);                            // Authentification + inscription.
$context = context_course::instance($courseid);
require_capability('local/annonces:manage', $context);
 
$returnurl = new moodle_url('/local/annonces/index.php', ['courseid' => $courseid]);
$pageurl   = new moodle_url('/local/annonces/edit.php',
    ['courseid' => $courseid, 'id' => $id]);
 
$PAGE->set_url($pageurl);
$PAGE->set_context($context);
$PAGE->set_title(get_string('editannonce', 'local_annonces'));
$PAGE->set_heading($course->fullname);
 
// --- 2. Préparer les customdata et instancier le formulaire -----------------
$categories = local_annonces_get_categories_menu($courseid);
$canpin     = has_capability('local/annonces:pin', $context);
 
// 1er argument : l'URL d'action (null = la page courante, le cas usuel).
// 2e argument : les customdata consommées par definition().
$mform = new annonce_form($pageurl, [
    'courseid'   => $courseid,
    'categories' => $categories,
    'canpin'     => $canpin,
]);
 
// --- 3. Les trois branches du cycle de vie ----------------------------------
if ($mform->is_cancelled()) {
    // (a) Bouton Annuler cliqué : on repart SANS RIEN TRAITER.
    //     Nota : is_cancelled() ne vérifie ni sesskey ni validation — normal,
    //     on ne touche à aucune donnée.
    redirect($returnurl);
 
} else if ($data = $mform->get_data()) {
    // (b) Formulaire soumis ET valide. get_data() garantit à ce stade :
    //     - le sesskey a été vérifié (protection CSRF) ;
    //     - chaque champ est nettoyé selon son setType ;
    //     - toutes les règles addRule + validation() sont passées.
    //     $data est un OBJET stdClass.
 
    if (empty($data->id)) {
        // Création.
        $data->timecreated  = time();
        $data->timemodified = time();
        $data->usercreated  = $USER->id;
        $data->id = $DB->insert_record('local_annonces', $data);
        $message = get_string('annoncecreated', 'local_annonces');
    } else {
        // Mise à jour : re-vérifier que l'enregistrement cible existe et
        // appartient bien au cours (le hidden 'id' est falsifiable !).
        $DB->get_record('local_annonces',
            ['id' => $data->id, 'courseid' => $courseid], '*', MUST_EXIST);
        $data->timemodified = time();
        $DB->update_record('local_annonces', $data);
        $message = get_string('annonceupdated', 'local_annonces');
    }
 
    // TOUJOURS rediriger après un POST réussi (pattern Post/Redirect/Get) :
    // c'est la protection contre le double-submit par rafraîchissement (F5).
    redirect($returnurl, $message, null, \core\output\notification::NOTIFY_SUCCESS);
}
 
// --- 4. Pré-remplissage en mode édition --------------------------------------
if ($id) {
    $entry = $DB->get_record('local_annonces',
        ['id' => $id, 'courseid' => $courseid], '*', MUST_EXIST);
    // set_data mappe chaque propriété de l'objet sur l'élément du même nom.
    $mform->set_data($entry);
}
// (En création, les setDefault de definition() s'appliquent.)
 
// --- 5. Affichage -------------------------------------------------------------
// On n'arrive ici QUE si : premier affichage, OU soumission invalide
// (le formulaire se réaffiche alors avec les erreurs et les valeurs saisies).
echo $OUTPUT->header();
echo $OUTPUT->heading(get_string(empty($id) ? 'addannonce' : 'editannonce', 'local_annonces'));
$mform->display();
echo $OUTPUT->footer();

} else if ($data = $mform->get_data()) {
    // Traitement normal…
}
// Si no_submit_button_pressed(), on retombe ici et le formulaire
// se réaffiche, reconstruit avec ses nouvelles répétitions.
$mform->display();

ÉDITION (avant set_data)                    ENREGISTREMENT (après get_data)
─────────────────────────                   ────────────────────────────────
fichiers zone finale                        fichiers zone brouillon
   │  file_prepare_standard_*                  │  file_postupdate_standard_*
   ▼                                           ▼
copiés en zone brouillon                    déplacés en zone finale
+ URLs réécrites (@@PLUGINFILE@@ → draft)   + URLs réécrites (draft → @@PLUGINFILE@@)

// ---- Dans definition() ------------------------------------------------------
$editoroptions = $this->_customdata['editoroptions'];
 
$mform->addElement('editor', 'intro_editor', get_string('description'),
    null, $editoroptions);
$mform->setType('intro_editor', PARAM_RAW);   // Légitime : c'est du HTML.
$mform->addRule('intro_editor', get_string('required'), 'required', null, 'client');

// ---- Dans la page edit.php ---------------------------------------------------
 
// Options d'éditeur : à définir UNE FOIS et réutiliser partout (préparation,
// post-traitement, et affichage des fichiers). Toute incohérence = fichiers perdus.
$editoroptions = [
    'maxfiles'  => EDITOR_UNLIMITED_FILES,  // Fichiers embarqués (images…) autorisés.
    'maxbytes'  => $CFG->maxbytes,
    'trusttext' => false,
    'subdirs'   => false,
    'context'   => $context,                // Le contexte de la zone de fichiers finale.
];
 
$mform = new annonce_form($pageurl, [
    'courseid' => $courseid,
    'editoroptions' => $editoroptions,
    // ...
]);
 
if ($mform->is_cancelled()) {
    redirect($returnurl);
 
} else if ($data = $mform->get_data()) {
    if (empty($data->id)) {
        // CRÉATION : problème d'œuf et de poule — les fichiers de la zone finale
        // sont rangés par itemid = id de l'enregistrement… qui n'existe pas encore.
        // Solution standard : insérer d'abord avec un contenu vide, puis post-traiter.
        $data->intro = '';
        $data->introformat = FORMAT_HTML;
        $data->id = $DB->insert_record('local_annonces', $data);
    }
 
    // Déplace les fichiers du brouillon vers la zone finale
    // (composant 'local_annonces', filearea 'intro', itemid = id de l'enregistrement)
    // et transforme $data->intro_editor (array text/format/itemid) en
    // $data->intro (string) + $data->introformat (int), URLs réécrites en @@PLUGINFILE@@.
    $data = file_postupdate_standard_editor($data, 'intro', $editoroptions,
        $context, 'local_annonces', 'intro', $data->id);
 
    $DB->update_record('local_annonces', $data);
    redirect($returnurl, get_string('changessaved'), null,
        \core\output\notification::NOTIFY_SUCCESS);
}
 
// Pré-remplissage en mode édition (ET en création, avec un objet vierge !).
if ($id) {
    $entry = $DB->get_record('local_annonces', ['id' => $id], '*', MUST_EXIST);
} else {
    $entry = new stdClass();
    $entry->id = null;
    $entry->intro = '';
    $entry->introformat = FORMAT_HTML;
}
 
// Copie les fichiers de la zone finale vers un brouillon et fabrique
// $entry->intro_editor = ['text' => ..., 'format' => ..., 'itemid' => $draftid].
$entry = file_prepare_standard_editor($entry, 'intro', $editoroptions,
    $context, 'local_annonces', 'intro', $entry->id);
 
$mform->set_data($entry);
$mform->display();

// ---- definition() ----
$filemanageroptions = ['subdirs' => 0, 'maxbytes' => $CFG->maxbytes,
    'maxfiles' => 10, 'accepted_types' => ['document', 'image']];
$mform->addElement('filemanager', 'attachments_filemanager',
    get_string('attachments', 'local_annonces'), null, $filemanageroptions);
 
// ---- edit.php, avant set_data ----
$entry = file_prepare_standard_filemanager($entry, 'attachments',
    $filemanageroptions, $context, 'local_annonces', 'attachments', $entry->id);
$mform->set_data($entry);
 
// ---- edit.php, après get_data (et insert si création) ----
$data = file_postupdate_standard_filemanager($data, 'attachments',
    $filemanageroptions, $context, 'local_annonces', 'attachments', $data->id);

// AVANT set_data : préparer le brouillon à la main.
$draftitemid = file_get_submitted_draft_itemid('attachments_filemanager');
file_prepare_draft_area($draftitemid, $context->id, 'local_annonces', 'attachments',
    $entry->id, $filemanageroptions);
$entry->attachments_filemanager = $draftitemid;
$mform->set_data($entry);
 
// APRÈS get_data : persister le brouillon.
file_save_draft_area_files($data->attachments_filemanager, $context->id,
    'local_annonces', 'attachments', $data->id, $filemanageroptions);

// Dans le traitement, deux approches :
 
// (a) Lire directement le contenu (petits fichiers) :
$content = $mform->get_file_content('importfile');
 
// (b) Obtenir un objet stored_file complet :
$files = $mform->get_draft_files('importfile');
if ($files) {
    $file = reset($files);
    $csv = $file->get_content();
    // ... traiter, puis ne RIEN sauvegarder : le brouillon sera purgé par cron.
}

protected function definition() {
    $mform = $this->_form;
 
    // 1. Le "modèle" : les éléments à répéter, créés avec createElement
    //    (PAS addElement — on ne les ajoute pas directement).
    $repeatarray = [];
    $repeatarray[] = $mform->createElement('text', 'optiontext',
        get_string('optionno', 'local_annonces', '{no}'));   // {no} → numéro de ligne.
    $repeatarray[] = $mform->createElement('float', 'optionweight',
        get_string('weight', 'local_annonces'), ['size' => 4]);
    $repeatarray[] = $mform->createElement('advcheckbox', 'optionenabled',
        get_string('enabled', 'local_annonces'));
    // Champ caché pour l'id de chaque option existante (mode édition).
    $repeatarray[] = $mform->createElement('hidden', 'optionid', 0);
 
    // 2. Nombre de répétitions initiales : les options existantes + 2 vierges,
    //    minimum 3. En édition, ce nombre vient des customdata.
    $repeatcount = max(3, $this->_customdata['optioncount'] + 2);
 
    // 3. Options par élément répété : type, défaut, règles, helpbutton,
    //    disabledif/hideif…
    $repeatoptions = [
        'optiontext' => [
            'type' => PARAM_TEXT,
            'helpbutton' => ['optiontext', 'local_annonces'],
            // Règle appliquée à CHAQUE occurrence :
            'rule' => ['maxlength', get_string('maximumchars', '', 255), 'maxlength', 255, 'client'],
        ],
        'optionweight'  => ['default' => 1.0],
        'optionenabled' => ['type' => PARAM_INT, 'default' => 1],
        'optionid'      => ['type' => PARAM_INT],
    ];
 
    // 4. La magie : génère optiontext[0], optiontext[1], …, le champ caché
    //    compteur, et le bouton no-submit "Ajouter 2 option(s)".
    $this->repeat_elements(
        $repeatarray,            // Éléments modèles.
        $repeatcount,            // Répétitions initiales.
        $repeatoptions,          // Options par élément.
        'option_repeats',        // Nom du champ caché comptant les répétitions.
        'option_add_fields',     // Nom du bouton "ajouter" (auto-enregistré no-submit).
        2,                       // Combien de lignes ajoute chaque clic.
        get_string('addmoreoptions', 'local_annonces'),   // Libellé du bouton.
        true                     // Bouton DANS la section courante (pas une nouvelle).
    );
 
    $this->add_action_buttons();
}

if ($data = $mform->get_data()) {
    foreach ($data->optiontext as $i => $text) {
        $text = trim($text);
        if ($text === '') {
            continue;   // Ligne vierge : ignorée (ou supprimée si optionid existant).
        }
        $option = (object) [
            'id'      => $data->optionid[$i],
            'text'    => $text,
            'weight'  => $data->optionweight[$i],
            'enabled' => $data->optionenabled[$i],
            'annonceid' => $annonce->id,
        ];
        if ($option->id) {
            $DB->update_record('local_annonces_options', $option);
        } else {
            unset($option->id);
            $DB->insert_record('local_annonces_options', $option);
        }
    }
    redirect($returnurl);
}

<?php
namespace local_annonces\form;
 
use context;
use context_course;
use moodle_url;
 
defined('MOODLE_INTERNAL') || die();
 
require_once($CFG->libdir . '/formslib.php');
 
/**
 * Formulaire d'annonce utilisable en modal AJAX.
 */
class annonce_dynamic_form extends \core_form\dynamic_form {
 
    /**
     * Définition classique — identique à un moodleform normal.
     * Les "customdata" arrivent ici via $this->_ajaxformdata (les args passés
     * par le JS), PAS via _customdata.
     */
    protected function definition() {
        $mform = $this->_form;
 
        $mform->addElement('hidden', 'id');
        $mform->setType('id', PARAM_INT);
        $mform->addElement('hidden', 'courseid');
        $mform->setType('courseid', PARAM_INT);
 
        $mform->addElement('text', 'title', get_string('title', 'local_annonces'));
        $mform->setType('title', PARAM_TEXT);
        $mform->addRule('title', get_string('required'), 'required', null, 'client');
 
        // PAS de add_action_buttons() : la modal fournit ses propres boutons
        // Enregistrer/Annuler.
    }
 
    /**
     * Le contexte dans lequel le formulaire opère. Sert de base aux
     * vérifications et au chargement des fichiers.
     */
    protected function get_context_for_dynamic_submission(): context {
        $courseid = $this->optional_param('courseid', null, PARAM_INT);
        return context_course::instance($courseid);
    }
 
    /**
     * Contrôle d'accès : lève une exception si l'utilisateur courant n'a pas
     * le droit d'afficher/soumettre ce formulaire. APPELÉ À CHAQUE requête AJAX.
     */
    protected function check_access_for_dynamic_submission(): void {
        require_capability('local/annonces:manage',
            $this->get_context_for_dynamic_submission());
    }
 
    /**
     * Traitement de la soumission valide (l'équivalent du bloc get_data()
     * de edit.php). La valeur retournée est transmise telle quelle au JS.
     */
    public function process_dynamic_submission() {
        global $DB;
        $data = $this->get_data();
 
        if (empty($data->id)) {
            $data->timecreated = time();
            $data->id = $DB->insert_record('local_annonces', $data);
        } else {
            $DB->update_record('local_annonces', $data);
        }
        // Retour arbitraire, sérialisé en JSON pour l'événement FORM_SUBMITTED.
        return ['id' => $data->id, 'title' => $data->title];
    }
 
    /**
     * Pré-remplissage (l'équivalent du set_data() de edit.php),
     * appelé au chargement AJAX du formulaire.
     */
    public function set_data_for_dynamic_submission(): void {
        global $DB;
        $id = $this->optional_param('id', 0, PARAM_INT);
        $data = ['id' => $id, 'courseid' => $this->optional_param('courseid', 0, PARAM_INT)];
        if ($id) {
            $entry = $DB->get_record('local_annonces', ['id' => $id], '*', MUST_EXIST);
            $data['title'] = $entry->title;
        }
        $this->set_data($data);
    }
 
    /**
     * URL de repli si le JS est indisponible (le formulaire y est affiché
     * en pleine page) — pointez vers votre edit.php classique.
     */
    protected function get_page_url_for_dynamic_submission(): moodle_url {
        return new moodle_url('/local/annonces/edit.php', [
            'courseid' => $this->optional_param('courseid', 0, PARAM_INT),
            'id' => $this->optional_param('id', 0, PARAM_INT),
        ]);
    }
}

// Fichier : local/annonces/amd/src/editmodal.js
import ModalForm from 'core_form/modalform';
import {getString} from 'core/str';
import Notification from 'core/notification';
 
export const init = (selector) => {
    document.querySelectorAll(selector).forEach((trigger) => {
        trigger.addEventListener('click', async (e) => {
            e.preventDefault();
 
            const modalForm = new ModalForm({
                // Le nom COMPLET de la classe PHP (double backslash en JS).
                formClass: 'local_annonces\\form\\annonce_dynamic_form',
                // Les args deviennent les paramètres lus par optional_param()
                // dans la classe (et _ajaxformdata dans definition()).
                args: {
                    id: trigger.dataset.id ?? 0,
                    courseid: trigger.dataset.courseid,
                },
                modalConfig: {
                    title: await getString('editannonce', 'local_annonces'),
                },
                returnFocus: trigger,   // Accessibilité : focus rendu au déclencheur.
            });
 
            // Le retour de process_dynamic_submission() arrive dans e.detail.
            modalForm.addEventListener(modalForm.events.FORM_SUBMITTED, (e) => {
                window.location.reload();   // Ou mise à jour fine du DOM avec e.detail.
            });
 
            modalForm.show();
        });
    });
};

<div class="mb-3 row fitem" data-groupname="...">
    <div class="col-md-3 col-form-label d-flex pb-0 pe-md-0">
        <label class="d-inline word-break-all" for="id_title">Titre</label>
        <div class="form-label-addon ...">
            <!-- icône aide, badge "Obligatoire" -->
        </div>
    </div>
    <div class="col-md-9 d-flex flex-wrap align-items-start felement" data-fieldtype="text">
        <input type="text" class="form-control" name="title" id="id_title" ...>
        <div class="form-control-feedback invalid-feedback" id="id_error_title"></div>
    </div>
</div>