Nouvelle page

Migration vers Fat Free Framework (F3)

Ce que nous avons mis en place, pourquoi, et comment ça fonctionne — expliqué simplement.

Le contexte — d'où on part, où on va

Le site Erasmus+ a démarré en PHP pur : chaque page était un fichier PHP séparé (articles.php, contacts.php…). Simple à démarrer, mais difficile à faire évoluer sur le long terme.

On a décidé de migrer vers une architecture plus structurée, avec un framework léger. En bonus, on en a profité pour avoir de vraies URLs lisibles.

URLs moches :
erasmus.thymon.fr/article.php?id=corogna-2024

URLs propres :
erasmus.thymon.fr/article/corogna-2024

Ce changement nécessitait un point d'entrée unique : toutes les requêtes passent désormais par index.php, qui distribue le travail selon l'URL demandée. C'est ce que fait F3.

Le patron MVC — Modèle · Vue · Contrôleur

MVC est une façon d'organiser son code en 3 rôles bien séparés, pour ne pas tout mélanger dans un seul fichier.

Le Modèle = la cuisine. Il sait où sont les données et comment les lire (les fichiers JSON des articles).
La Vue = le menu et la salle. Elle s'occupe uniquement de l'apparence (les fichiers HTML).
Le Contrôleur = le serveur. Il prend la commande (l'URL), va chercher les données, et les envoie à la bonne vue.

Avantage concret : si demain tu veux changer la mise en page de la liste des articles, tu touches seulement articles.html. Si tu veux changer comment les données sont filtrées, tu touches seulement ArticleController.php. Les deux ne se mélangent pas.

Fat Free Framework (F3) — le chef d'orchestre

F3 est un micro-framework PHP. "Framework" = boîte à outils qui donne une structure. "Micro" = il reste très léger, sans des dizaines de fichiers de configuration.

Son rôle principal dans notre projet : le routage. Il lit l'URL demandée et appelle le bon contrôleur.

// Dans index.php — on dit à F3 : "si quelqu'un va sur /articles,
// appelle la méthode liste() dans ArticleController"
$f3->route('GET /articles', 'ArticleController->liste');
$f3->route('GET /article/@slug', 'ArticleController->detail');
// @slug = la partie variable de l'URL (ex: "corogna-2024")

F3 s'occupe aussi du moteur de templates : il lit les fichiers .html des vues, remplace les {{ @variables }} par les vraies valeurs, et produit le HTML final envoyé au navigateur.

Les grands frameworks (Laravel, Symfony) sont très puissants mais ont une courbe d'apprentissage importante et beaucoup de "magie" cachée. F3 fait exactement ce dont on a besoin, sans surplus. Un seul fichier PHP de 200 Ko, aucune configuration complexe.

Composer — le gestionnaire de librairies

Composer est le gestionnaire de paquets PHP. C'est l'équivalent de ce qu'est l'App Store pour ton téléphone : il télécharge et installe des librairies que d'autres développeurs ont créées.

Tu écris dans un fichier composer.json : "j'ai besoin de F3 et de la librairie pour manipuler des vidéos". Composer va sur internet, télécharge tout ça, et le place dans un dossier vendor/. Plus besoin de le faire manuellement.

On a installé deux librairies pour notre projet :

Le dossier vendor/ est exclu de Git (dans .gitignore) car il peut être recréé à tout moment avec la commande composer install.

Les URLs propres — comment ça fonctionne

Pour que toutes les URLs passent par index.php, on utilise un fichier .htaccess à la racine du site. C'est un fichier de configuration Apache qui dit : "si le fichier ou dossier demandé n'existe pas physiquement, envoie la requête vers index.php".

# .htaccess — la règle clé
RewriteEngine On
# Si ce n'est pas un vrai fichier ET pas un vrai dossier...
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
# ...redirige vers index.php
RewriteRule .* index.php [L,QSA]

Quand quelqu'un va sur /article/corogna-2024 :

Avec les URLs propres, les chemins d'images relatifs cassent. Sur la page /article/corogna-2024, une image uploads/photo.jpg est interprétée par le navigateur comme /article/uploads/photo.jpg → introuvable. Il faut toujours utiliser des chemins absolus commençant par / : /uploads/photo.jpg.

Les templates F3 — séparer le HTML du PHP

Dans l'ancien site, le PHP et le HTML étaient mélangés dans le même fichier. Avec F3, le contrôleur prépare les données, puis les "envoie" à un fichier HTML pur. Ce fichier HTML utilise une syntaxe spéciale pour afficher les données.

Syntaxe principale :

<!-- Afficher une variable (avec protection HTML automatique) -->
{{ @article.titre }}

<!-- Afficher du HTML pré-généré sans l'échapper -->
{{ @contenu_html | raw }}

<!-- Condition if/else -->
<check if="{{ @article.photo }}">
  <true><img src="{{ @article.photo }}" /></true>
  <false><div>Pas de photo</div></false>
</check>

<!-- Boucle foreach -->
<repeat group="{{ @articles }}" value="{{ @a }}">
  <h2>{{ @a.titre }}</h2>
</repeat>

F3 compile ces templates en PHP dans un dossier tmp/. Il ne recompile que si le fichier HTML source a changé — c'est plus rapide. Quand on modifie un template, on peut vider le cache en supprimant les fichiers tmp/*.php.

Le template HTML est comme un formulaire avec des cases vides. Le contrôleur PHP remplit les cases avec les vraies données. F3 est le mécanisme qui fait la liaison entre les deux.

Structure du projet — qui fait quoi

Les layouts — le "moule" des pages

Un layout est le cadre commun à plusieurs pages. Au lieu de recopier la navbar et le footer dans chaque page, on les met une seule fois dans le layout.

On a deux layouts :

PHP 8.4 — pièges rencontrés et leçons apprises

On tourne sur PHP 8.4, la version la plus récente. Cette version est plus stricte que les anciennes : certaines choses qui "passaient" avant provoquent maintenant des erreurs.

Piège n°1 — Variable non définie = erreur fatale

Si un template F3 essaie d'afficher {{ @ma_variable }} et que cette variable n'a pas été définie, PHP 8.4 lance une erreur. En mode debug F3 (DEBUG=3), ça se traduit par une page blanche avec le code HTTP 500.

Solution : dans BaseController.php, on initialise toutes les variables optionnelles à une valeur vide par défaut :

// Dans BaseController::render()
$f3->set('page_description', ''); // ← valeur vide par défaut
$f3->set('extra_head',       '');
$f3->set('extra_scripts',   '');

Piège n°2 — Clé de tableau manquante

Accéder à $tableau['ma_cle'] quand la clé n'existe pas → "Undefined array key". Par exemple, les types de modalités "groupe" et "enseignants-personnels" n'avaient pas de clé conditions, mais le template essayait d'y accéder.

Solution : toujours s'assurer que toutes les clés existent, même avec une valeur vide :

// Bien : la clé 'conditions' existe toujours (tableau vide si pas de conditions)
'groupe' => [
    'intro'      => "...",
    'items'      => [...],
    'conditions' => [], // ← vide mais présent
]

Comment diagnostiquer les erreurs :

On a une méthode efficace pour trouver les bugs rapidement :

Lexique — les termes à retenir