netig/f3-simple-blog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Less home code more F3

Browse Source
This commit is contained in:
julien
2026-03-30 00:00:03 +02:00
parent d71cf304a9
commit fac7f60190
30 changed files with 818 additions and 1552 deletions
Download Patch File Download Diff File Expand all files Collapse all files

260
README.md
View File

@@ -1,102 +1,88 @@
# F3 Simple Blog
Blog simple avec Fat-Free Framework et SQLite.
Blog simple construit autour de deux objectifs :
- **simplicité conceptuelle** ;
- **fidélité à Fat-Free Framework**.
Le rendu visuel est volontairement soigné, mais le backend reste petit et lisible :
- **3 contrôleurs** : `SiteController`, `AuthController`, `AdminController`
- **1 contrôleur de base** : `Controller`
- **3 modèles** : `Post`, `Media`, `User`
- **1 service dédié** : `MarkdownService`
- **1 bootstrap F3**
- **2 scripts CLI** : installation et création d'admin
## Structure
```text
project/
├── config.local.ini # Surcharges locales (gitignored)
├── app/
│ ├── config.ini # Configuration F3 (globals + routes)
│ ├── bootstrap.php # Initialisation (config, DB, session, erreurs)
│ ├── bootstrap.php
│ ├── config.ini
│ ├── helpers.php
│ ├── Controllers/
│ ├── Helpers/ # Fonctions utilitaires ciblées
│ ├── Models/ # DB\SQL\Mapper (Post, Media, User)
│ ├── Services/ # MarkdownService
│ ├── Models/
│ ├── Services/
│ └── Views/
├── db/
│ └── app.sqlite # Base SQLite persistante
├── logs/
│ └── php-error.log # Log PHP configuré au runtime
├── public/
│ ├── assets/ # Assets statiques servis directement
│ └── uploads/
│ └── media/ # Images publiées (JPG conservé, PNG/WebP normalisés en PNG)
│ ├── assets/
│ └── uploads/media/
├── docker/
├── scripts/
│ ├── bootstrap.php # Autoload + bootstrap partagé par les scripts CLI
│ ├── install.php # Initialisation idempotente de la base
│ └── create-admin.php # Création d'un compte admin en CLI
└── tmp/ # Runtime temporaire, recréable sans perte métier
└── uploads/ # Transit Web::receive(), nettoyé après chaque upload
│ ├── bootstrap.php
│ ├── install.php
│ └── create-admin.php
└── tmp/uploads/
```
## Fonctionnalités F3 utilisées
## Ce qui est utilisé côté F3
- **Routage nommé** — `config.ini [routes]`, filtre `alias` dans les templates, `reroute('@route')` dans les contrôleurs.
- **Cache HTTP** — TTL par contrôleur via `expire()`, forcé à `0` quand un utilisateur est connecté.
- **Assets statiques** — servis directement depuis `public/assets/`, laissés au serveur HTTP / reverse proxy.
- **Upload** — `Web::receive()` avec contrôle de taille, puis validation MIME/dimensions côté modèle.
- **Images** — normalisation des médias via `Image`, lecture/écriture via `Base::read()` / `Base::write()`.
- **Markdown** — `Markdown::instance()->convert()` suivi d'un assainissement DOM strict (liste blanche de balises, attributs et protocoles) et de la résolution locale des images média.
- **Slugs** — `Web::instance()->slug()`.
- **Session / CSRF** — `$f3->set('JAR', …)`, `new Session(null, 'CSRF')` pour s'appuyer sur la génération native F3, puis persistance d'un jeton unique en session pour qu'il reste valide entre le GET du formulaire et le POST suivant ; validation centralisée via `verifyCsrf()`.
- **ORM** — `DB\SQL\Mapper` : `paginate()`, `copyfrom()`, `cast()`, `find()`.
- **Erreurs** — gestion personnalisée en production via `ONERROR` + fallback HTML minimal sur erreur fatale.
- routes dans `config.ini`
- `DB\SQL\Mapper` pour les trois tables
- `Auth` pour la connexion
- `Session` pour la session et le jeton CSRF de base
- `Template` pour le rendu et le filtre `date_fr`
- `Web::receive()` pour l’upload
- `Markdown` pour le rendu des articles
- `Web::slug()` pour les slugs
## Prérequis
## Choix de simplicité
- pas de namespaces ;
- pas de couche repository ;
- pas de système de migrations ;
- pas de container DI ;
- pas de logique de proxy avancée ;
- un seul contrôleur admin pour les articles et la médiathèque ;
- pas d’image de couverture dédiée : la première image du corps sert de vignette de carte.
## Choix éditorial simplifié
Les articles n'ont plus de champ “image de couverture”. Les images vivent uniquement dans le Markdown, et la première image rendue dans `body_html` est réutilisée comme vignette dans les cartes d’article. Cela réduit le nombre de champs, supprime un cas métier entier, et garde un rendu visuel cohérent.
## Simplifications supplémentaires
- **zéro HTML brut** : le HTML saisi dans le Markdown est neutralisé avant le passage dans le parseur Markdown ; seuls les éléments générés par Markdown puis validés par le sanitizer sont rendus ;
- **images stockées brutes** : l’upload accepte uniquement JPG et PNG, vérifie que le fichier est bien une image, puis le stocke tel quel sans réencodage ni transformation ; la dépendance à GD est supprimée.
## Pré-requis
### Développement local
- PHP 8.3+
- Composer
- Extensions PHP : `pdo_sqlite`, `gd`, `mbstring`, `intl`, `dom`
- extensions : `pdo_sqlite`, `mbstring`, `intl`, `dom`
### Déploiement Docker
- Docker
- Docker Compose
## Configuration
Les paramètres par défaut sont dans `app/config.ini`. Pour surcharger localement ou en production :
```bash
cp config.local.ini.example config.local.ini
```
Réglages minimums conseillés en production :
```ini
[globals]
app.env=prod
app.timezone=Europe/Paris
```
### Proxies de confiance
L'application ne délègue pas la sécurité des cookies à Apache : elle détermine le schéma de la requête pour marquer la session en `Secure`.
La valeur par défaut couvre les cas les plus courants :
- `127.0.0.1,::1` — Caddy sur le même hôte ;
- `172.16.0.0/12` — réseaux Docker IPv4 standard, y compris un Caddy conteneurisé sur le même réseau.
Si ton proxy tourne sur un autre sous-réseau, surcharge `app.trusted_proxies` dans `config.local.ini`.
```ini
[globals]
app.trusted_proxies=127.0.0.1,::1,172.16.0.0/12
# ou, avec une liste F3 : app.trusted_proxies[]=10.0.0.42
```
Seuls ces proxies sont autorisés à influencer `X-Forwarded-Proto` / `Forwarded`.
### À propos du CSRF F3
F3 sait générer un jeton via `new Session(null, 'CSRF')`, mais ce jeton est produit à l'instanciation de la requête. Le projet s'en sert donc comme source native F3, puis le persiste explicitement en session pour garder un jeton stable entre l'affichage d'un formulaire et sa soumission.
## Développement local
## Démarrage local
```bash
composer install
@@ -111,111 +97,69 @@ Créer un compte admin :
```bash
php scripts/create-admin.php admin
# mot de passe : 10 caractères minimum
```
`scripts/install.php` peut être relancé sans danger : il crée les tables si elles n'existent pas.
## Configuration
## Déploiement avec Docker
Le fichier `app/config.ini` contient les valeurs par défaut. Tu peux les surcharger dans `config.local.ini`.
Exemple minimal en production :
```ini
[globals]
app.env=prod
app.timezone=Europe/Paris
```
### Important sur le mode prod
Par défaut, `app/config.ini` laisse `app.env=dev`. Pour un vrai déploiement, il faut donc fournir un `config.local.ini` avec `app.env=prod`, sinon l’application gardera un comportement de développement.
## Déploiement Docker derrière Caddy
Le projet est cohérent pour un déploiement simple :
- Apache sert `public/` dans le conteneur ;
- `compose.yaml` expose l’application sur `127.0.0.1:8888` par défaut ;
- Caddy termine TLS et reverse-proxy vers cette cible ;
- SQLite, les logs et les uploads sont montés sur des volumes hôtes.
Exemple :
```bash
cp config.local.ini.example config.local.ini
# édite config.local.ini (app.env=prod, app.timezone, trusted proxies si besoin)
# édite config.local.ini : app.env=prod
docker compose up -d --build
```
Le déploiement Docker est cohérent avec le projet :
Le `Caddyfile.example` donne une base de reverse proxy. Le point important est de **n’exposer publiquement que Caddy**. L’application Apache/PHP ne doit pas être accessible directement depuis Internet.
- l'image embarque les extensions réellement utilisées (`pdo_sqlite`, `gd`, `mbstring`, `intl`, `dom`) ;
- `scripts/install.php` s'exécute au démarrage pour initialiser SQLite de façon idempotente ;
- seuls les répertoires métier/persistants sont montés (`db/`, `logs/`, `public/uploads/media/`) ;
- `tmp/` reste dans le conteneur et sert uniquement au runtime F3 (transit d'upload, fichiers temporaires).
### Volumes persistants à sauvegarder
Le fichier `config.local.ini` est monté en lecture seule. Si le fichier hôte n'existe pas, Docker peut créer un répertoire à la place ; l'entrypoint le supprime et l'application retombe sur les valeurs par défaut de `app/config.ini`.
Pour sauvegarder le blog, il faut au minimum conserver :
Le service écoute sur `http://127.0.0.1:8888`.
- `db/app.sqlite`
- `public/uploads/media/`
Créer un compte admin :
Les logs peuvent aussi être conservés si tu veux garder l’historique d’erreurs.
```bash
docker compose exec app php scripts/create-admin.php admin
# mot de passe : 10 caractères minimum
```
## Contrat Markdown
## Cache public
Le projet assume un Markdown simple :
Les pages publiques restent cacheables pour un visiteur anonyme :
- titres, listes, citations, code, liens et images Markdown ;
- pas de HTML brut auteur ;
- les images du contenu utilisent la syntaxe `media:nom-de-fichier.ext` ;
- les images externes ne sont pas rendues ;
- avec le parseur Markdown de F3, laisse une ligne vide entre deux blocs pour un rendu fiable.
- `/` : TTL de 300 s ;
- `/posts/@slug` : TTL de 3600 s.
## Limite volontaire : pas de migrations
Quand un utilisateur est connecté, le rendu est forcé en non-cacheable avec `expire(0)` pour ne pas servir du contenu admin via un cache intermédiaire.
`scripts/install.php` crée les tables si elles n’existent pas. En revanche, il ne gère pas les évolutions de schéma. Si le modèle de données change dans le futur, il faudra soit repartir d’une base propre, soit appliquer une migration manuelle.
Les assets statiques (`public/assets/`) sont servis directement ; leur éventuel cache HTTP relève du serveur web ou du reverse proxy.
## Nettoyage de confort appliqué
## Médias et limites d'upload
- Formats acceptés à l'entrée : JPG, PNG, WebP.
- Taille max du fichier reçu : 10 Mo.
- Dimensions max : 8000 × 8000 px, 40 mégapixels.
- Sortie publiée : JPG pour les sources JPEG, PNG pour les sources PNG/WebP.
- Texte alternatif initial dérivé du nom de fichier d'origine.
La médiathèque admin est paginée et le picker dans l'éditeur charge seulement les 60 images les plus récentes.
## Reverse proxy Caddy
### Caddy sur le même hôte
```caddy
blog.example.com {
encode zstd gzip
reverse_proxy 127.0.0.1:8888
}
```
### Caddy dans Docker
Si Caddy tourne aussi dans Docker, place-le sur le même réseau que `app` et cible directement le service :
```caddy
blog.example.com {
encode zstd gzip
reverse_proxy app:80
}
```
Dans la plupart des cas, la valeur par défaut de `app.trusted_proxies` suffit aussi pour ce mode ; surcharge-la seulement si ton réseau Docker utilise un autre sous-réseau.
Comme F3 lit aussi `X-Forwarded-For` pour déterminer `IP`, le conteneur applicatif ne doit pas être exposé directement à Internet : Caddy doit rester l'unique point d'entrée public et réécrire les en-têtes `X-Forwarded-*`.
Le fichier `Caddyfile.example` fournit en plus un jeu d'en-têtes de sécurité minimal.
## Répartition des responsabilités avec Caddy
Le projet n'essaie pas de dupliquer ce que le reverse proxy gère naturellement :
- **Caddy** — TLS, compression, en-têtes de sécurité, terminaison HTTPS, reverse proxy.
- **Application / PHP-F3** — sessions, CSRF, cookies, validation métier, rendu HTML et cache HTTP des pages dynamiques.
## Données à sauvegarder
- `db/` — base SQLite.
- `public/uploads/media/` — images.
- `logs/` — optionnel, utile pour diagnostic.
## Mise à jour
```bash
docker compose up -d --build
```
## Logs
- PHP : `logs/php-error.log`.
- Apache / conteneur : `docker compose logs -f app`.
## Notes
- Les dates sont stockées en UTC (`gmdate`) puis formatées côté affichage avec le fuseau configuré.
- Le pipeline Markdown n'autorise que les éléments utiles au rendu éditorial et remappe systématiquement les images vers la médiathèque locale.
- suppression d'une méthode utilitaire inutilisée dans `Media` ;
- suppression d'un paramètre mort dans `Post::usesMedia()` ;
- simplification de l'upload temporaire côté admin ;
- détection `secure` des cookies un peu plus tolérante (`HTTPS`, `REQUEST_SCHEME`, `X-Forwarded-Proto`) sans réintroduire une grosse logique proxy.