BlueGit

projects-timfalken-com verhalenboek

Files

verhalenboek
README.md

Verhalenboek

Een verhalenboek: elke kalenderdag heeft een titel en precies drie verhalen. Lezers zien wat ze al gelezen hebben. Een beheerder vult het boek, met de hand of via een API-sleutel. Inloggen gaat via auth.timfalken.com.

De applicatie staat in web/. Lokaal:

php -S 127.0.0.1:8080 -t web web/router.php

Open http://127.0.0.1:8080. Je bent automatisch test_user_1 en daarmee beheerder. Onder Instellingen wissel je naar test_user_2, een gewone lezer.

Publieke URL

Microchess staat op https://projects.timfalken.com/microchess omdat die map de FTP-map onder de site projects.timfalken.com is. Hier is de CI-variabele projectftp gelijk aan $timftproot/verhaaltjesboek. Dezelfde afleiding geeft:

https://projects.timfalken.com/verhaaltjesboek

Wat Tim moet instellen

Deploy naar master zet de code op de server, maar raakt data/ niet aan. Daarin blijven de database, sessies en het geheim staan. Bij de eerste paginabezoek maakt de app data/config.php aan als dat bestand er nog niet is. Een bestaand bestand wordt nooit overschreven.

1. Zet de code op master (de pipeline test eerst, en uploadt daarna alleen bij een groene master). 2. Open eenmaal https://projects.timfalken.com/verhaaltjesboek zodat data/config.php ontstaat. Het bestand staat op de server in de FTP-map verhaaltjesboek/data/config.php (projectftp + /data/config.php). 3. Registreer bij https://auth.timfalken.com/admin het callback-pad op het domein projects.timfalken.com:

  • client_id: projects.timfalken.com (het domein van de publieke URL, hetzelfde domein als microchess)
  • callback-pad: /verhaaltjesboek/callback.php
  • Voeg alleen dat pad toe. Genereer het clientgeheim niet opnieuw als microchess hetzelfde domein al gebruikt: een nieuw geheim maakt de andere site stuk. Kopieer het bestaande geheim.

4. Vul op de server data/config.php in. Dit bestand wordt niet gecommit en niet geüpload. Laat key_secret staan: die maakt de app zelf aan (64 hexadecimale tekens) en versleutelt daarmee API-sleutels, zodat een beheerder ze later opnieuw kan tonen. Ontbreekt hij, dan vult de app hem één keer aan zonder de andere velden te wissen.

<?php
return [
    'base_url' => 'https://projects.timfalken.com/verhaaltjesboek',
    'client_id' => 'projects.timfalken.com',
    'client_secret' => 'het-geheim-uit-admin',
    'key_secret' => 'blijft-de-gegenereerde-waarde',
];

Lege velden voor URL en client vallen terug op VERHALENBOEK_BASE_URL, VERHALENBOEK_CLIENT_ID en VERHALENBOEK_CLIENT_SECRET. Een ingevuld veld wint van de omgeving. base_url mag een submap bevatten en heeft geen slash aan het eind. key_secret komt niet uit de omgeving.

5. Log als eerste zelf in. Die eerste gebruiker wordt beheerder. Iedereen daarna is lezer. Het account-id en de gebruikersnaam komen uit /api/me. E-mail wordt niet gelezen en niet opgeslagen. Onder Beheer zie je alle gebruikers. Daar maak je iemand anders beheerder, of haal je die rol weer weg. Je kunt je eigen beheerdersrol niet uitzetten, zodat er altijd minstens één beheerder blijft. 6. Maak onderaan Beheer een API-sleutel voor de schrijver-agent. De volledige sleutel (vb_…) verschijnt meteen, en daarna opnieuw als je op die sleutel tikt. Alleen een ingelogde beheerder ziet dat; de lijst en de export tonen alleen het voorvoegsel. Een oud adres #/sleutels komt op diezelfde Beheer-pagina uit.

De OAuth-flow is dezelfde als bij microchess: state, code wisselen op de server via POST /oauth/token, daarna GET /api/me, verlengen via POST /api/session/extend, en afmelden via POST /api/logout. Het bearer-token van het account blijft in de PHP-sessie en komt niet in JavaScript.

Leesstatus

Een dag wordt gelezen zodra de dagpagina opent, niet pas onderaan. Korte verhalen passen vaak op één scherm, dus "onderaan" is dan hetzelfde als openen, of het gebeurt juist nooit. Opnieuw openen houdt de dag gelezen. Per ongeluk geopend? Houd de dag in het overzicht ingedrukt (telefoon) of klik met de rechtermuisknop (desktop) en kies ongelezen. Het standaardmenu en tekstselectie blijven tijdens die handeling uit.

Verderlezen opent de vroegste ongelezen dag van het hele boek, ook als die buiten de week valt die je nu ziet. Het aantal ongelezen dagen is hetzelfde totaal, zodat het klopt met die knop. Standaard volgen kleuren het systeem; het lettertype is een serif. Licht, donker, serif, schreefloos en rond worden per gebruiker op de server bewaard.

RSS-feed

Lezers kunnen de verhalen volgen in een feedlezer (Atom). De feed staat standaard uit. Een beheerder zet hem aan onder Beheer → RSS-feed. Zolang hij uit staat, ziet niemand de feed-instelling, staat er geen autodiscovery-link in de pagina en geeft elk feed-adres 404.

Staat hij aan, dan maakt elke lezer onder Instellingen → RSS-feed een eigen geheim adres: https://projects.timfalken.com/verhaaltjesboek/feed.php?token=vbf_…. Er is één adres per lezer. Vernieuwen maakt een nieuw adres en maakt het oude ongeldig; Intrekken zet het uit. Het adres staat versleuteld in de database (net als API-sleutels), zodat de lezer het opnieuw kan kopiëren. De ingelogde eigenaar krijgt ook een <link rel="alternate" type="application/atom+xml"> in de HTML-head.

  • Eén item per dag, nieuwste eerst, de laatste 60 dagen tot en met vandaag (Europe/Amsterdam). Toekomstige dagen komen pas op hun datum in de feed.
  • Het item bevat de dagtitel en alle verhalen van die dag als HTML (titel per verhaal, alinea's), en linkt naar #/dag/JJJJ-MM-DD.
  • De wiki zit nooit in de feed. Een feed lezen zet geen dag op gelezen en maakt geen sessie.
  • Headers: Content-Type: application/atom+xml, Cache-Control: private, no-cache, X-Robots-Tag: noindex, nofollow, Referrer-Policy: no-referrer, en een ETag (304 bij If-None-Match). Een onbekende, ingetrokken of vernieuwde sleutel, of een uitgezette feed, geeft 404.
  • De service worker cachet feed.php nooit.

API (ingelogde sessie): GET/POST/DELETE /api.php/me/feed (tonen, maken of vernieuwen, intrekken; 404 als de feed uit staat), en voor een beheerder GET/PUT /api.php/settings/feed met {"enabled": true}. API-sleutels (Bearer) kunnen de feed niet aan- of uitzetten.

De tabellen app_settings en feed_tokens ontstaan vanzelf bij de eerste request (CREATE TABLE IF NOT EXISTS); bestaande data blijft staan.

Weekoverzicht

Het overzicht toont één kalenderweek, maandag tot en met zondag. Dagen zonder verhaal blijven weg. Zonder #/week/JJJJ-MM-DD — ook bij het openen zonder hash, en bij de geïnstalleerde app waarvan start_url /verhaaltjesboek/ is — opent het overzicht de week waarin de vroegste ongelezen dag valt. Dat is de vroegste datum met een dagrecord en zonder rij in reads voor deze lezer; een dagrecord zonder verhalen telt mee. Zijn alle dagen gelezen, dan blijft het de week van de laatst gelezen dag. Zonder dagen is het de huidige kalenderweek. Een gekozen #/week/JJJJ-MM-DD of een dagpagina blijft die route. Vorige week en Volgende week staan boven de lijst, met het bereik erbij, bijvoorbeeld 5–11 oktober 2026. Een knop staat er alleen als die aangrenzende kalenderweek minstens één dagrecord heeft, ook als die dag onvolledig is. Een lege week ertussen verbergt de knop; hij springt niet naar een latere week met dagen. Via #/week/JJJJ-MM-DD blijft een lege week wel bereikbaar.

Op de dagpagina blijven Vorige dag en Volgende dag de aangrenzende geschreven dagen. Die knoppen springen niet naar een andere week.

Rechtsonder op een dagkaart staan tot vijf kleine rondjes: vrienden die díe dag gelezen hebben. De lijst komt uit GET /api/friends op auth.timfalken.com (id, username, avatar_url). De app haalt die lijst server-side op met het bearer-token uit de sessie, dezelfde weg als /api/me. Het token komt niet in JavaScript. De browser toont alleen de foto; avatar_url mag een pad /avatar/{id}?v=… zijn of de absolute URL op https://auth.timfalken.com. Een ander adres wordt genegeerd. Zonder foto komt de eerste letter van de naam in een neutraal rondje.

Een vriend telt voor een dag als het account auth:{id} een rij in reads heeft voor die dag. Iemand die dit boek nog nooit opende, heeft geen rij en blijft weg. De eigen lezer staat er niet bij. Meer dan vijf vrienden: de vijf met de recentste leeshandeling (read_at), en bij een gelijk moment op naam en daarna op id. Lukt de vriendenlijst niet, dan blijven de kaarten gewoon staan, gelezen of ongelezen. Lokaal is er geen auth-lijst; elk ander account in deze database telt dan als vriend, zonder foto.

API

Schrijven kan met een Bearer-sleutel of, in de browser, als beheerder. Een volledige dag heeft precies drie verhalen, elk met een titel en minstens één alinea. De volgorde in de lijst is plek 1, 2 en 3.

GET /api.php/days/latest is de nieuwste datum die nog een dagrecord heeft, ook als daar een verhaal uit verwijderd is (complete is dan false). Ontbreekt er nog niets, dan is het antwoord 404.

GET /api.php/days/gaps geeft, tussen de eerste en de laatste dag:

  • missing: kalenderdagen zonder dagrecord (verwijderd of nooit geschreven)
  • incomplete: dagen die bestaan maar geen drie verhalen meer hebben, met missingPositions

Een onvolledige dag staat niet óók in missing. Staat een datum in missing, maak hem met POST. Staat hij in incomplete, vul de plek of vervang de dag met PUT en precies drie verhalen.

curl -sS -X POST \
  -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"date":"2026-10-05","title":"De herfstwind","stories":[
    {"title":"Ochtend","paragraphs":["De wind stond al vroeg aan de deur."]},
    {"title":"Middag","paragraphs":["Op het plein joeg een krant zichzelf achterna."]},
    {"title":"Avond","paragraphs":["Het licht in de keuken bleef aan."]}
  ]}' \
  'https://projects.timfalken.com/verhaaltjesboek/api.php/days'

curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
  'https://projects.timfalken.com/verhaaltjesboek/api.php/days/latest'

curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
  'https://projects.timfalken.com/verhaaltjesboek/api.php/days/gaps'
MethodePadBetekenis
GET/daysDagen, oudste eerst. Een ingelogde lezer ziet ook read. Daarnaast lastRead, week (maandag–zondag, met previous, next, label, hasPrevious en hasNext) en weekDays. previous en next blijven de maandag van de buurweek. hasPrevious en hasNext zijn waar als die buurweek minstens één dagrecord heeft. ?week=JJJJ-MM-DD kiest een week. Zonder die parameter is het, voor een ingelogde lezer, de week van de vroegste ongelezen dag; zijn alle dagen gelezen, dan de week van lastRead; zonder dagen de week van ?today= of vandaag. Een API-sleutel heeft geen leesstatus: dan de week van de nieuwste dag, anders van ?today= of vandaag.
GET/days/latestNieuwste geschreven datum.
GET/days/gapsGaten en onvolledige dagen.
GET/days/JJJJ-MM-DDDag, verhalen, previous en next.
POST/daysNieuwe dag met precies drie verhalen. 201, of 409 als de datum bezet is.
PUT/days/JJJJ-MM-DDTitel en/of vervanging door precies drie verhalen.
DELETE/days/JJJJ-MM-DDDag weg.
POST/days/JJJJ-MM-DD/storiesVerhaal erbij zolang er minder dan drie zijn.
PUT/days/JJJJ-MM-DD/stories/1Plek 1, 2 of 3 bijwerken.
DELETE/days/JJJJ-MM-DD/stories/2Eén verhaal weg; de andere plekken blijven.
POST / DELETE/days/JJJJ-MM-DD/readAlleen een ingelogde lezer.
GET/friend-readsAlleen een ingelogde lezer, niet met een API-sleutel. Per datum tot vijf vrienden die die dag lazen: id, name, avatar_url. Recentste leeshandeling eerst.
PUT/me/settingstheme: system, light of dark. font: serif, sans of rounded.
GET/me/exportEigen gegevens als JSON.

Fouten zijn {"error":"…"}. Validatie die de drie-verhalenregel raakt geeft 422. De menselijke uitleg met dezelfde voorbeelden staat op docs.php.

Een 401 (geen header, verkeerd formaat, of een onbekende/ingetrokken sleutel) zet WWW-Authenticate: Bearer en voegt how_to_authenticate toe, met dezelfde tekst in hint. Die tekst noemt het geval, de header Authorization: Bearer vb_…, Beheer op {base_url}/#/beheer, en een link naar docs.php. Een 403 omdat een lezer iets doet dat een sleutel of beheerder vereist, heeft die uitleg ook, zonder WWW-Authenticate. Sleutels zelf beheren kan alleen in de beheerderssessie, onderaan Beheer. Een 403 door een ongeldige CSRF-header blijft alleen {"error":"…"}.

curl -sS -D - -o - \
  'https://projects.timfalken.com/verhaaltjesboek/api.php/days/latest'

GET /api.php/keys/{id} geeft de volledige sleutel terug aan een ingelogde beheerder. Opzoeken bij een verzoek blijft een hash op token_hash.

Deploy

De code staat op BlueGit: https://git.timfalken.com/projects-timfalken-com/verhalenboek (publiek). GitLab (Timfa/Verhalenboek) is alleen nog een backup en deployt niet meer.

blue-ci-cd.yml draait PHP-syntax, domeintests, API-tests, een JavaScript-syntaxcheck en een echte FTP-fixture. ftp_upload wacht via needs op alle drie testjobs: faalt er één, dan is er geen deploy. Alleen een push naar master uploadt (geen MR-pipelines), en nooit tegelijk met een andere productie-deploy. ci/deploy.py spiegelt web/ met lftp en slaat data/ (database, WAL, config.php, sessies, API-sleutels) over, zowel bij upload als bij verwijderen. data/.htaccess wordt apart gezet. tests/, router.php en README.md gaan niet mee.

Geheimen

NaamWaarBeschermd
timftphost, timftpuser, timftppassword, timftprootgroep projects.timfalken.com (gedeeld door alle projecten op die site)ja
projectftpdeze repository ($timftproot/verhaaltjesboek)ja

Beschermde geheimen komen alleen mee op de beschermde branch master. MR-pipelines krijgen ze niet. Waarden van acht tekens of meer worden in joblogs vervangen door [MASKED].

Deploy-guard

ci/deploy_guard.py laat de deploy hard falen (DEPLOY GEBLOKKEERD: …) als projectftp niet gezet of leeg is, naar / of . wijst, gelijk is aan timftproot, .. bevat of buiten timftproot ligt. Zo kan een mirror --delete nooit de hele website overschrijven. $timftproot in projectftp wordt door de guard zelf ingevuld, want BlueGit-geheimen verwijzen niet naar elkaar. Zie docs/deploy-guard.md om de guard in een ander project te gebruiken.

Tests

find web -name '*.php' -not -path '*/artifacts/*' -print0 | xargs -0 -n1 php -l
php web/tests/storybook.php
python3 web/tests/startup.py
python3 web/tests/integration.py
python3 web/tests/pwa.py
python3 web/tests/feed.py
node --check web/assets/app.js
python3 ci/test_deploy.py

De API-tests draaien een kopie onder web/tests/artifacts/ en laten de echte database met rust.