Forem: Odilon HUGONNOT

JS video player with ffmpeg HTTP streaming in PHP: state machine, watchdog, subtitles

Odilon HUGONNOT — Fri, 22 May 2026 09:00:02 +0000

The first real test of ShareBox with an actual file was an 8 GB MKV — HEVC encode, DTS audio, PGS subtitles burned from a Japanese Blu-ray. The <video src="..."> I had put in place opened, spun for two seconds, and stopped in complete silence. No error event, no console message. Just a spinner going nowhere.

ShareBox started from a simple premise — share large files without a third-party cloud. Video streaming was supposed to be one feature among others. Except real-world files are not clean H.264/AAC MP4s: there are MKVs, HEVC encodes, Dolby audio tracks, bitmap subtitles. The native browser player gives up without a word. So I built a full player: on the server side, download.php orchestrates three ffmpeg streaming modes. On the client side, a JS state machine handles mode selection, stall recovery, image subtitle burn-in, and UX. This post documents what I built — and where it cost more time than expected.

Three server-side streaming modes

The entry point is download.php?stream=MODE. Three modes are available, selected dynamically by the JS based on the detected codec.

native — X-Accel-Redirect

For files already playable by the browser (MP4 H.264 + AAC), we delegate to nginx via X-Accel-Redirect. PHP never touches the bytes, no ffmpeg, no CPU cost. HTTP byte-range works normally, seeking is instant.

remux — zero-cost repackaging

An H.264 MKV cannot be streamed natively by the browser, but the codecs are compatible. The solution: repackage on the fly into a fragmented MP4 without re-encoding.

ffmpeg -i input.mkv \
  -c:v copy -c:a aac \
  -movflags frag_keyframe+empty_moov+default_base_moof \
  -min_frag_duration 300000 \
  -f mp4 pipe:1

-c:v copy: zero video re-encoding. -c:a aac: audio is converted if needed (DTS, AC3 → AAC). The result is a fragmented MP4 piped directly into the HTTP response. CPU cost: near zero for video, a few percent for audio conversion.

The flags frag_keyframe+empty_moov+default_base_moof are critical. Without empty_moov, the browser waits for the end of the file to read the moov atom (metadata) — which blocks indefinitely on a pipe. Without frag_keyframe, fragments don't start on keyframes and seeking breaks.

A pitfall that cost me an hour: I had added -fflags +genpts and first_pts=0 to normalize timestamps. The reasoning seemed sound — some MKVs have PTS values that don't start at zero, and I wanted to avoid surprises during seeking. In practice, these options modify PTS in a way that browsers misinterpret on a fragmented stream: video and audio gradually desync after each seek. Removed, the problem disappeared immediately.

Normalizing timestamps on a fragmented pipe means "fixing" something the browser already handles fine — and introducing a desync it has no way to correct.

transcode — for incompatible codecs

Unsupported HEVC, VP9, AV1, or Dolby audio that won't pass through: we re-encode.

ffmpeg -i input.mkv \
  -c:v libx264 -preset ultrafast -crf 23 \
  -c:a aac \
  -movflags frag_keyframe+empty_moov+default_base_moof \
  -min_frag_duration 300000 \
  -f mp4 pipe:1

-preset ultrafast sacrifices compression to minimize startup latency. -crf 23 gives acceptable quality without blowing up the bitrate. The video is playable within a few seconds, not after a full encode pass.

Concurrency semaphore and clean disconnect

Each ffmpeg process consumes CPU for the entire duration of the stream. Without a limit, ten concurrent downloads mean ten ffmpeg processes fighting over CPU cores. I added a PHP semaphore (via sem_acquire) capped at 4 concurrent processes.

$sem = sem_get(ftok(__FILE__, 'f'), 4);
sem_acquire($sem);

register_shutdown_function(function () use ($sem, $proc) {
    if (is_resource($proc)) {
        proc_terminate($proc);
    }
    sem_release($sem);
});

// Streaming loop
while (!feof($stdout) && !connection_aborted()) {
    echo fread($stdout, 65536);
    flush();
}

The connection_aborted() check inside the loop is essential: when the client closes the tab, PHP detects the disconnect, exits the loop, the shutdown function kills the ffmpeg process, and releases the semaphore slot. Without this, orphan ffmpeg processes pile up until reboot.

Infrastructure adjustment: pm.max_children in PHP-FPM was bumped from 5 to 25. Each active stream monopolizes one FPM worker for its entire duration — unavoidable with synchronous streaming. With 5 workers, the 6th visitor waits in the dark.

SQLite ffprobe cache

Before choosing the streaming mode, the JS needs to know the file's codec. ffprobe answers that, but takes 2 to 12 seconds on a large file (disk access, header parsing). My first version did trial-and-error detection on the JS side: try native, wait 2 seconds, if nothing plays → try remux. In practice, 2 seconds is a long wait, and it generates false positives on slow connections. The right solution: know the codec before starting anything.

SQLite cache keyed by (path, mtime). The key includes the file's mtime to automatically invalidate the cache if the file is replaced. Cache hit: ~100ms. Cold: 2-12s (once per file, never again).

function probeVideo(string $path): array {
    $db  = new PDO('sqlite:' . PROBE_CACHE_DB);
    $key = hash('xxh64', $path . '|' . filemtime($path));

    $row = $db->query(
        "SELECT data FROM probe_cache WHERE key = " . $db->quote($key)
    )->fetch();

    if ($row) {
        return json_decode($row['data'], true);
    }

    $cmd    = 'ffprobe -v quiet -print_format json -show_streams ' . escapeshellarg($path);
    $result = json_decode(shell_exec($cmd), true);

    $db->prepare("INSERT OR REPLACE INTO probe_cache (key, data) VALUES (?, ?)")
       ->execute([$key, json_encode($result)]);

    return $result;
}

The JS state machine

The client-side player is built around a state object S that evolves as video events fire. No framework, no external state manager — just a mutable object watched by targeted event listeners.

const S = {
    step:        'native',   // mode currently being tried
    confirmed:   null,       // confirmed working mode (skip re-test on seek)
    stallCount:  0,          // watchdog retry counter
    seekPending: false,      // seek in progress (debounce)
};

Probe-driven mode selection

chooseModeFromProbe(streams) inspects the streams returned by ffprobe and picks the mode:

function chooseModeFromProbe(streams) {
    const video     = streams.find(s => s.codec_type === 'video');
    const audio     = streams.find(s => s.codec_type === 'audio');
    const vcodec    = video?.codec_name;
    const acodec    = audio?.codec_name;
    const container = currentFile.ext.toLowerCase();

    if (vcodec === 'h264' && container === 'mkv') return 'remux';
    if (vcodec === 'h264' && container === 'mp4' && acodec === 'aac') return 'native';
    if (vcodec === 'h264' && container === 'mp4') return 'transcode';

    // VP9, AV1, HEVC: try native if the browser claims support
    const probe = document.createElement('video').canPlayType(mimeFor(vcodec));
    return probe !== '' ? 'native' : 'transcode';
}

Silent HEVC hardware decode failure

Safari and Chrome on Windows sometimes claim HEVC support via canPlayType(). When hardware decoding silently fails on these browsers, it does so with extraordinary discretion: no error event, no stalled event, nothing in the console. Audio starts playing normally. The image freezes on the first frame — or worse, stays black. video.videoWidth stays at 0, and that's the only available signal.

setTimeout(() => {
    if (video.videoWidth === 0 && S.step === 'native') {
        console.warn('Silent HEVC failure → cascade to transcode');
        S.step = 'transcode';
        reloadStream();
    }
}, 1500);

A codec that "supports" a format but fails to decode silently is exactly as useful as one that doesn't support it — except it's much harder to detect.

Stall watchdog with exponential backoff

My first watchdog implementation used a fixed timeout per mode. The problem surfaced immediately on large HEVC files: ffmpeg takes several seconds to start a transcode (parsing, memory allocation, producing the first keyframe). The watchdog would lose patience and relaunch the stream. Two concurrent ffmpeg processes started up, competed for CPU cores, slowed each other down. The semaphore saturated on the third retry. The user saw a spinner forever with no explanation — while on the server side, several zombie ffmpeg processes waited for their four slots.

Exponential backoff per mode fixed that: the first retry waits 20s in transcode mode, the second 40s, capped at 120s. A legitimately slow-starting ffmpeg has time to produce its first fragments before the watchdog panics.

const BASE_TIMEOUTS = { native: 5, remux: 10, transcode: 20, burnSub: 30 };

function startWatchdog() {
    clearTimeout(stallTimer);
    const base    = BASE_TIMEOUTS[S.confirmed ?? S.step] ?? 15;
    const timeout = Math.min(base * Math.pow(2, S.stallCount), 120) * 1000;

    stallTimer = setTimeout(() => {
        S.stallCount++;
        console.warn(`Stall #${S.stallCount}, retrying from ${video.currentTime}s`);
        reloadStream(video.currentTime);
    }, timeout);
}

video.addEventListener('timeupdate', () => startWatchdog());
video.addEventListener('waiting',    () => startWatchdog());

The watchdog resets on every timeupdate (active playback). If it fires, we restart the stream from the current position. stallCount doubles the delay on each retry, capped at 120s.

Subtitles: text and image tracks

Text subtitles (SRT/ASS) via WebVTT

Text subtitles are extracted by ffmpeg as WebVTT on demand and served as plain text. On the JS side, I don't use the native <track> element: positioning is too limited and ASS rendering is non-existent. I use an absolutely-positioned <div> overlay, positioned via getBoundingClientRect with an offset for the control bar.

For files with thousands of cues, finding the active cue on each timeupdate would be O(n). I use a binary search for the initial position, then a pointer that advances linearly — O(log n) on the first seek, O(1) afterwards.

function findCueIndex(cues, time) {
    let lo = 0, hi = cues.length - 1;
    while (lo < hi) {
        const mid = (lo + hi) >> 1;
        if (cues[mid].end < time) lo = mid + 1;
        else hi = mid;
    }
    return lo;
}

let cuePtr = 0;

video.addEventListener('timeupdate', () => {
    const t = video.currentTime;
    while (cuePtr < cues.length - 1 && cues[cuePtr].end < t) cuePtr++;
    if (cues[cuePtr].start > t + 1) cuePtr = findCueIndex(cues, t);

    const cue = cues[cuePtr];
    subOverlay.textContent = (cue.start <= t && t <= cue.end) ? cue.text : '';
});

Font size is proportional to video width (2.5%, min 13px), recalculated by a ResizeObserver on the container element.

Image subtitles (PGS/VOBSUB) — burn-in

PGS (Blu-ray) and VOBSUB (DVD) subtitles are bitmap images: CSS overlay is not an option. The only solution is to burn them directly into the video via ffmpeg, which triggers a full transcode with the subtitles filter.

This cost me half a day. On my test files — extracts I had prepared myself — the subtitles filter worked flawlessly. Then I tested on real Blu-ray files: subtitles shifted, cropped, sometimes absent. The problem: PGS subtitle canvas dimensions don't always match the video dimensions. A 1080p Blu-ray MKV can carry a subtitle canvas at 1920x1080, but also at 1920x816 or any value inherited from the original mastering. A plain subtitles filter stretches or crops without warning. The fix, found after a while in a 2019 ffmpeg-user mailing list thread, is scale2ref: fit the subtitle canvas to the video resolution before the overlay.

ffmpeg -i input.mkv \
  -filter_complex \
    "[0:v][0:s:0]scale2ref[vid][sub]; \
     [sub]scale=iw:ih[sub2]; \
     [vid][sub2]overlay" \
  -c:v libx264 -preset ultrafast -crf 23 \
  -c:a aac \
  -movflags frag_keyframe+empty_moov+default_base_moof \
  -f mp4 pipe:1

On the JS side, detecting an image subtitle track sets S.step = 'burnSub' with the track index (burnSub=N in the URL). The watchdog timeout rises to 30s for this combination — transcode startup with embedded subtitles is slower than a plain transcode.

UX: controls, mode badge, fullscreen

A few UX decisions are worth explaining. The mode badge (green = REMUX, orange = TRANSCODE, grey = NATIVE) is clickable to cycle modes manually. It's primarily a debugging tool — when remux produces an audio artifact or transcode is inexplicably slow, one click lets you force the other mode without reloading the page. In practice, end users reach for it too when something isn't working.

Fullscreen is triggered on .player-card (the parent div), not on <video> directly. Calling element.requestFullscreen() on <video> causes the browser to render its own controls on top of the custom ones — on Firefox the result is particularly chaotic. On the parent div, custom controls stay visible and functional. Auto-hide kicks in after 3 seconds of mouse inactivity, with the cursor hidden. Single tap = play/pause, double tap = fullscreen, with a 250ms debounce to tell them apart. Keyboard shortcuts (Space/K, left/right arrow ±10s, F, M) map to the same actions.

One iOS detail worth its weight in debugging time: Accept-Ranges: none in PHP response headers for remux and transcode modes. Safari on iOS sends Range requests on <video> elements even when the source is a pipe. Without this header, Safari attempts a byte-range on a non-seekable stream and gets a broken response — playback dies within the first second. Volume, mute state, and playback speed are persisted in localStorage across sessions. The requestAnimationFrame throttle on timeupdate prevents stacking progress bar updates at 60 fps during active playback.

Conclusion

A video player that "actually works" on a heterogeneous file library is much more surface area than expected. Most of the code isn't in the player itself — it's in handling the edge cases: silent codec failures, bitmap subtitles, orphan processes, iOS doing byte-range on a pipe.

If I were starting over: implement the ffprobe probe and SQLite cache first, before writing a single line of JS. Having codec truth available in 100ms completely changes the mode selection logic and simplifies everything downstream. The state machine, the watchdog, the subtitle burn-in — all of it becomes predictable once you know exactly what you're dealing with before you start.

Full source code is on GitHub (ohugonnot/sharebox).

ShareBox: self-hosted file sharing with video streaming in pure PHP

Odilon HUGONNOT — Thu, 21 May 2026 09:00:03 +0000

The need was straightforward: share large files — tens of gigabytes of raw footage, project archives, training videos — without going through a third-party cloud. No Google Drive, no WeTransfer, no Dropbox. A dedicated server, files you control, links that expire when you want them to. The result: ShareBox, a self-hosted file sharing platform with integrated video streaming, written in pure PHP 8.1 with no framework.

The repo is on GitHub.

Zero runtime dependencies

The first decision — and the most consequential — was to avoid any framework. No Symfony, no Laravel. Pure PHP, native stdlib, SQLite auto-created on first boot. Composer is present, but only as a dev dependency for PHPUnit. In production, no vendor/ directory is needed.

This constraint is clarifying. Every feature must justify its real implementation cost — not outsourced to a package that does ten times what you need. Manual routing in a few dozen lines, native PHP session handling, SQLite queries via PDO: these are things you implement once and understand completely.

SQLite followed the same logic — no server to configure, no complex migrations, the database file lives next to the code and backs up with a simple cp. For a single-instance tool, it's more than enough.

The installer follows the same principle — a one-liner for Debian/Ubuntu:

curl -sSL https://raw.githubusercontent.com/ohugonnot/sharebox/main/install.sh | bash

A script that installs system dependencies, configures Apache or nginx, creates the SQLite database, and sets correct permissions. No Docker required, no registry to contact.

The real challenge: video streaming

Sharing a text file or a ZIP archive is trivial. Sharing a video and letting someone watch it directly in the browser — with seek, audio track selection, subtitles — is a different problem.

The first decision was to avoid systematic transcoding. If the file is already in a browser-compatible format (H.264/AAC in an MP4 or MKV container), we do a remux on the fly: repackage the existing streams without re-encoding. FFmpeg takes a few seconds, CPU usage is near zero, and quality is identical to the source.

Full transcoding only kicks in when necessary — typically for HEVC/x265 files, which very few browsers decode natively. In that case, FFmpeg transcodes to H.264 on the fly, with quality selection: 480p, 720p, or 1080p.

Seek in a live-transcoded stream is the trickiest part. A Range: bytes=... request on a classic HLS stream works because segments are pre-generated. Here, the stream is generated in real time — so seek means restarting FFmpeg with -ss at the right timecode, rather than seeking a byte offset in an already-generated file. The code orchestrating this in stream.php is worth reading if you're tackling a similar problem.

The integrated video player: native seek, quality selection, WebVTT subtitles.

Human-readable slugs

A UUID to identify a share is secure but unusable by humans. Getting /dl/3f7a2c1d-8b4e-4f9a-b2d6-1c5e8f3a7b2c in an email is opaque. ShareBox generates slugs from the filename:

batman-begins-2005.mkv  →  /dl/batman-begins-2005-x7k2

The 4-character random suffix is enough to avoid collisions without sacrificing readability. batman-begins-2005-x7k2 tells you immediately what it contains, is easy to copy by hand, and survives a message or URL without issues.

Slug generation normalizes the string: accent transliteration, lowercase conversion, replacement of spaces and special characters with hyphens, removal of consecutive hyphens. The result is then checked against the database for uniqueness before insertion.

Security without a framework

A framework quietly handles a lot of security concerns — often without the developer being aware of it. Without a framework, these concerns must be addressed explicitly. Four stood out as needing careful attention.

Directory traversal. When serving files from disk, you have to ensure a parameter like ../../../etc/passwd doesn't get through. The solution: realpath() on the resolved path, then verify the result is a subpath of the allowed upload directory. If the resolved path escapes the target directory, the request is rejected.

CSRF protection. The admin panel exposes destructive actions (file deletion, link revocation). Every POST form includes a CSRF token stored in session, regenerated after each sensitive action.

Session fixation. After authentication, session_regenerate_id(true) is called to invalidate the old session identifier and issue a new one. Without this, an attacker who knows the session ID of an unauthenticated visitor can reuse it after login.

Mail header injection. The email sharing form accepts a destination address. Without strict validation, an attacker can inject additional SMTP headers into the email field and hijack the outgoing message. All user inputs destined for mail headers are filtered to strip newlines before being passed to sending functions.

The admin panel: share management, expiration, password protection.

Tests: what's actually worth covering

44 PHPUnit tests, no mock framework, no external test dependency. The question wasn't "how to test everything" — it was "what breaks silently if we don't test it."

Three categories stood out as particularly valuable:

Slugs. Slug generation is a pure function with many edge cases: names with accents, multiple spaces, Unicode characters, collisions, filenames without extensions. Thorough tests on this function are worth their weight in gold — it's exactly the kind of code that looks trivial and breaks unexpectedly on real input.

Format detection. The logic deciding whether a video can be remuxed or must be transcoded relies on reading FFprobe metadata. Testing with FFprobe output fixtures for different codecs (H.264, HEVC, VP9, AV1) ensures the remux/transcode decision is correct without needing actual video files in the test suite.

Security. Directory traversal tests, header injection tests, and CSRF token validation tests are the most valuable. These are well-documented attack vectors, easy to test with known payloads, and missing an edge case has direct consequences.

Folder sharing: file browsing, one-click ZIP download.

Conclusion

The "zero runtime dependencies" philosophy isn't a stance. It's a commitment to understanding and maintaining what you build. Every line of code in ShareBox has an explicit reason to exist — no magic hidden in a third-party component whose source you've never read.

The concrete lesson from this project: PHP is capable of adaptive video streaming, seek in live transcoding, and correct security — with no framework whatsoever. The difficulty isn't in the language; it's in understanding what you're building.

The code is available at github.com/ohugonnot/sharebox.

Retro gaming guide: CSS scanlines, Orbitron and dark theme without JS

Odilon HUGONNOT — Wed, 20 May 2026 09:00:06 +0000

I needed a buying guide for portable retro consoles — the kind of page you browse from a couch on a Saturday night before caving in and ordering something on eBay. Static content, no dynamic behaviour, no API. A perfect excuse to write unbounded CSS without having to justify it to a team. The vision: a cyberpunk dark theme, scanlines that echo old CRT screens, retro-futuristic typography. And crucially, no framework, no JavaScript whatsoever.

What I learned building it is that the most visually striking effects don't come from animation libraries — they come from the right combination of CSS gradients, pseudo-elements, and well-structured custom properties. Here's how it works.

Context

The target page: retro-consoles.html. A buying guide covering around twenty portable retro consoles — Game Boy, Analogue Pocket, Miyoo Mini, Anbernic RG35XX and the rest. Each console gets its specs, its price, its pros and cons.

The technical constraint was simple: a static page hosted on the same Apache server as the CV, zero runtime dependencies. The aesthetic goal was more ambitious: recreating the visual atmosphere of a 1980s CRT screen in a modern browser. The cyan accent colour #00d4ff, chosen for its resemblance to phosphor green shifted to electric blue, sets the tone. The rest of the theme follows from that.

The scanlines effect — pure CSS

Scanlines are the most visually recognisable effect and the simplest to implement. The idea: a ::before pseudo-element fixed to the viewport, covering the entire page, with a repeating-linear-gradient that alternates transparent and semi-opaque every two pixels.

body::before {
    content: '';
    position: fixed;
    inset: 0;
    pointer-events: none;
    z-index: 9999;
    background: repeating-linear-gradient(
        to bottom,
        transparent,
        transparent 1px,
        rgba(0, 0, 0, 0.08) 1px,
        rgba(0, 0, 0, 0.08) 2px
    );
}

Three decisions here that are worth spelling out.

position: fixed, not absolute. The effect needs to overlay all content even when scrolling, like a real physical screen. fixed stays anchored to the viewport.

pointer-events: none. Without this, the pseudo-element absorbs all clicks and the page becomes unusable. A classic oversight with CSS overlays.

Opacity at 0.08 on the dark lines. That number is arbitrary but the result of several iterations. Too strong (0.2+) and the content becomes unreadable. Too weak (0.03) and the effect disappears on light backgrounds — but here the background is dark, so contrast works at low values.

Retro typography: Orbitron, Space Mono, why these choices

Type choices in a themed design account for 70% of the visual identity. Three fonts, three distinct roles:

/* Headings: Orbitron — geometric shapes, angular uppercase */
h1, h2, h3 {
    font-family: 'Orbitron', monospace;
    letter-spacing: 0.05em;
    text-transform: uppercase;
}

/* Prices, technical specs: Space Mono — monospace with personality */
.price,
.spec-value {
    font-family: 'Space Mono', monospace;
}

/* Body copy: DM Sans — readable, neutral, unobtrusive */
body {
    font-family: 'DM Sans', sans-serif;
}

Orbitron for headings: the archetypal retro-futuristic typeface, drawn with geometric shapes and right angles. Works equally well for "GAME BOY" and "ANALOGUE POCKET". The trade-off: it's unreadable at body copy sizes. A heading set in Orbitron at 14px makes you want to close the tab.

Space Mono for numerical data. A monospace designed by Colophon Foundry with more personality than Courier or Roboto Mono. Prices aligned vertically in Space Mono on a dark background recall 1980s terminal screens.

DM Sans for everything else. The rule is simple: never put a display typeface in body copy. Orbitron for 500 words of console descriptions would be cruel.

Custom properties for the entire theme

A coherent dark theme with a single accent colour is best managed through custom properties from the start. Not a single hardcoded colour anywhere in the CSS — everything goes through :root.

:root {
    /* Backgrounds */
    --bg-primary:   #0a0a0f;
    --bg-secondary: #111118;
    --bg-card:      #16161f;
    --bg-card-hover:#1c1c28;

    /* Main accent */
    --accent:       #00d4ff;
    --accent-dim:   rgba(0, 212, 255, 0.15);
    --accent-glow:  0 0 20px rgba(0, 212, 255, 0.3);

    /* Text */
    --text-primary:  #e8e8f0;
    --text-secondary:#9090a8;
    --text-muted:    #5a5a72;

    /* Borders */
    --border:        rgba(0, 212, 255, 0.2);
    --border-strong: rgba(0, 212, 255, 0.5);
}

A few details that matter. --accent-dim: a heavily attenuated version of the accent for hover backgrounds and badges. Without it, you end up recomputing rgba(0, 212, 255, X) all over the stylesheet. --accent-glow: the neon halo on featured elements, defined once as a box-shadow value.

The card hover glow then reduces to:

.console-card:hover {
    background: var(--bg-card-hover);
    border-color: var(--border-strong);
    box-shadow: var(--accent-glow);
    transform: translateY(-2px);
    transition: all 0.2s ease;
}

Responsive layout without a framework

CSS Grid with auto-fill and minmax — the only way to build a truly responsive multi-column layout without a single media query for the cards:

.consoles-grid {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
    gap: 24px;
}

With minmax(280px, 1fr), the browser calculates how many columns fit. On a 1440px screen: 4 columns. On an iPad at 768px: 2 columns. On a phone: 1 column. No manual breakpoints needed for the grid itself.

Media queries are still needed for other adjustments: reducing Orbitron font-size on mobile (geometric headline fonts are wide), switching the header from two columns to one, adjusting padding.

.page-header {
    display: grid;
    grid-template-columns: 1fr auto;
    align-items: center;
    gap: 32px;
}

@media (max-width: 768px) {
    .page-header {
        grid-template-columns: 1fr;
    }

    h1 {
        font-size: clamp(1.4rem, 5vw, 2.5rem);
    }
}

clamp() for Orbitron headings: essential. Without it, a 2.5rem h1 in Orbitron overflows the viewport on an iPhone SE.

Conclusion

This project reinforced something I knew in theory but regularly underestimate in practice: a strong visual design doesn't require JavaScript. The card hover animation, the scanlines effect, the neon glow — all of it works with transition, box-shadow, and a pseudo-element. The browser handles the rendering on the GPU, without a single requestAnimationFrame.

The real complexity wasn't technical — it was visual calibration. Finding the scanline opacity that creates atmosphere without hurting legibility. Choosing a cyan luminosity that evokes phosphor without burning eyes. These are decisions that don't get written in code; they get validated by eye.

The result: retro-consoles.html.

PicoCSS vs Bootstrap vs Tailwind: choosing your CSS framework

Odilon HUGONNOT — Tue, 19 May 2026 09:00:03 +0000

The project: TOUSPOURRIS.COM, a satirical site tracking French political corruption. The UI had to mimic the aesthetic of French Republic institutions — bleu france #000091, red #e1000f, Marianne typography. An immediately recognizable design, deliberately official for the ironic effect. This isn't a modern SaaS with rounded cards and gradients. It's an institutional pastiche.

And that aesthetic choice dictated the CSS framework choice. When the design is precise and identity-driven, the framework is no longer a neutral accelerator — it can become an obstacle. I evaluated the three usual suspects: Bootstrap, Tailwind, PicoCSS. Here's why two were ruled out and the third won.

The problem with Bootstrap

Bootstrap imposes its components. Buttons with border-radius: 0.375rem, colors in variables but an entire color system to override, navbar with preconfigured behaviors. For a generic design — admin dashboard, SaaS landing page — it's perfect: the defaults are the right ones.

For a French Republic institutional design, it's the opposite. You spend your time undoing what Bootstrap did. !important everywhere, CSS variables rewritten. You end up with Bootstrap-0 — Bootstrap stripped of its defaults — carrying 50 kB of CSS you don't use. The cost/benefit ratio flips: Bootstrap becomes a liability, not an asset.

The problem with Tailwind

Tailwind solves the over-opinionatedness problem by having no components. But it shifts the problem: for a consistent design, you need to configure the design system in tailwind.config.js — RF colors, Marianne typography — then apply utility classes everywhere in the HTML. That's work.

And for this Symfony project with Twig templates, it meant learning an additional tool, a Node.js build step in a PHP stack, for a result that native CSS can deliver directly. The effort/benefit ratio didn't justify introducing Tailwind into a context where the design system was already defined and documented by the French government.

Why PicoCSS

PicoCSS starts from a different philosophy: clean styles on semantic HTML elements, without classes. A <button> is styled. An <input> is styled. A <nav> is styled. The base is usable immediately without writing a single line of CSS. And most importantly: the defaults are minimal and easy to override with CSS custom properties.

/* Override the PicoCSS design system with RF colors */
:root {
    --pico-primary: #000091;          /* Bleu France */
    --pico-primary-hover: #1212ff;
    --pico-del-color: #e1000f;        /* RF Red */
    --pico-font-family: 'Marianne', system-ui, sans-serif;
    --pico-border-radius: 0;          /* Institutional = no rounding */
}

5 CSS variables and the site looks like a government portal. No !important, no specificity war with the framework. PicoCSS doesn't resist — it yields cleanly because it was designed to do exactly that.

The RF design system in practice

The French government's visual identity is open source — the DSFR design system. Colors, typography, spacing, all defined and documented. With PicoCSS as the base:

Marianne font (downloadable from the official DSFR) loaded via @font-face
CSS variables for --bleu-france, --rouge-marianne, --gris-cool
Custom components — "corruption gauge" badge, politician cards — written in native CSS, no utility classes

The result: a site that deliberately looks like an official portal. The satirical effect relies entirely on the design. A visitor who arrives without context sees an institutional interface before realizing it's satire. That disconnect only works if the design is credible — and it wouldn't have been with off-the-shelf Bootstrap or hastily configured Tailwind.

When to choose what

There's no universal framework. Concrete criteria for deciding:

Situation

Recommended framework

Admin dashboard, generic SaaS

Bootstrap or shadcn/ui

Lots of utilities, custom design via config

Tailwind

Precise design, semantic HTML, solid native CSS skills

PicoCSS

Project < 10 pages, CSS < 500 lines

No framework

The real question isn't "which framework is best" but "what am I going to fight against". Bootstrap imposes its components. Tailwind imposes its classes. PicoCSS imposes almost nothing — which can be an advantage or a disadvantage depending on whether you want to build or to override.

Conclusion

PicoCSS isn't the universal answer. It's the answer when you have a precise design and you don't want to spend your time undoing a framework's decisions. For TOUSPOURRIS.COM, it was the right choice: a coherent institutional design in ~300 lines of custom CSS, without any specificity war.

The code is readable by any developer without knowing the conventions of a specific framework. In 2 years, if someone picks up the project, they read CSS — not Bootstrap or Tailwind. It's a form of technical restraint that has a short-term cost (no ready-made components) and a long-term benefit (no dependencies to maintain, no version migrations to manage).

Vue.js SPA SEO: how I made my app invisible to Google (and how I fixed it)

Odilon HUGONNOT — Mon, 18 May 2026 09:00:03 +0000

I spent three months building CitoyenNote — a Vue.js 3 + Vite SPA. Clean code, Composition API, composables for everything, Pinia for state management. The kind of codebase you're actually proud of. Then I typed the site name into Google and got back a single result: the homepage. With a title of "Document". No description. And none of the 80+ municipality pages were indexed.

That's the SPA SEO problem in a nutshell. Here's what I learned fixing it.

What Google actually sees in a SPA

A classic server-rendered page serves complete HTML on the first request. Google's crawler receives a full <head> with a title, meta description, canonical URL — everything it needs to index the page.

A Vue.js SPA in CSR mode serves this on every URL:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Document</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/assets/index-Bx9kLmQp.js"></script>
  </body>
</html>

Google's crawler does execute JavaScript — but with significant caveats: it uses an older Chromium version, JS rendering is deferred and lower priority than HTML crawling, and there's no guarantee of complete execution on every page. Relying on JS execution for SEO is a gamble. The fix is to give Google correct HTML right from the start.

The full solution requires six steps.

Step 1: get the index.html basics right

The static index.html at the root of your Vite project is the baseline every page will fall back to when JavaScript hasn't run yet. It should be respectable:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />

    <title>CitoyenNote — Citizen reviews of French municipalities</title>
    <meta name="description" content="Read and share ratings and reviews about your municipality: safety, schools, public transport, urban planning. Unfiltered citizen feedback." />

    <!-- Open Graph -->
    <meta property="og:type" content="website" />
    <meta property="og:title" content="CitoyenNote — Citizen reviews of French municipalities" />
    <meta property="og:description" content="Read and share ratings and reviews about your municipality: safety, schools, public transport, urban planning." />
    <meta property="og:url" content="https://citoyennote.fr/" />
    <meta property="og:image" content="https://citoyennote.fr/og-image.jpg" />
    <meta property="og:locale" content="en_US" />

    <!-- Twitter Card -->
    <meta name="twitter:card" content="summary_large_image" />
    <meta name="twitter:title" content="CitoyenNote — Citizen reviews of French municipalities" />
    <meta name="twitter:description" content="Read and share ratings and reviews about your municipality." />
    <meta name="twitter:image" content="https://citoyennote.fr/og-image.jpg" />

    <link rel="canonical" href="https://citoyennote.fr/" />
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

This static fallback is what social media crawlers (Twitter, LinkedIn, Slack) will read when sharing your homepage — they rarely execute JavaScript.

Step 2: @unhead/vue for dynamic meta tags

For every route to have its own title and meta description, you need a library that manipulates the <head> reactively as the route changes. The current standard for Vue 3 is @unhead/vue, which replaces the older vue-meta.

Installation

npm install @unhead/vue

Setup in main.ts

import { createApp } from 'vue'
import { createHead } from '@unhead/vue'
import App from './App.vue'
import router from './router'

const app = createApp(App)
const head = createHead()

app.use(router)
app.use(head)
app.mount('#app')

Usage in a component

The simplest approach: call useHead() in each page component, with computed values that react to async data loading.

// views/MunicipalityView.vue
<script setup lang="ts">
import { computed } from 'vue'
import { useHead } from '@unhead/vue'
import { useMunicipality } from '@/composables/useMunicipality'

const props = defineProps<{ slug: string }>()
const { municipality, loading } = useMunicipality(props.slug)

useHead({
  title: computed(() =>
    municipality.value
      ? `${municipality.value.name} — CitoyenNote`
      : 'Loading... — CitoyenNote'
  ),
  meta: [
    {
      name: 'description',
      content: computed(() =>
        municipality.value
          ? `Citizen reviews of ${municipality.value.name} (${municipality.value.department}): overall score ${municipality.value.score}/10, ${municipality.value.reviewCount} reviews.`
          : 'Municipality reviews on CitoyenNote.'
      ),
    },
    {
      property: 'og:title',
      content: computed(() =>
        municipality.value ? `${municipality.value.name} — CitoyenNote` : 'CitoyenNote'
      ),
    },
    {
      property: 'og:description',
      content: computed(() =>
        municipality.value
          ? `Citizen reviews of ${municipality.value.name}: overall score ${municipality.value.score}/10.`
          : ''
      ),
    },
    {
      property: 'og:url',
      content: computed(() =>
        `https://citoyennote.fr/municipality/${props.slug}`
      ),
    },
    {
      property: 'og:type',
      content: 'article',
    },
  ],
  link: [
    {
      rel: 'canonical',
      href: computed(() => `https://citoyennote.fr/municipality/${props.slug}`),
    },
  ],
})
</script>

The key point: the values are computed(), so they update automatically when municipality.value is populated after the API call. No need to manually call anything when data arrives.

Extract into a composable

If you have many page types, avoid duplicating useHead() calls. Extract into a typed composable:

// composables/useMunicipalitySeo.ts
import { computed, type Ref } from 'vue'
import { useHead } from '@unhead/vue'
import type { Municipality } from '@/types'

export function useMunicipalitySeo(
  municipality: Ref<Municipality | null>,
  slug: string
) {
  useHead({
    title: computed(() =>
      municipality.value
        ? `${municipality.value.name} — CitoyenNote`
        : 'CitoyenNote'
    ),
    meta: [
      {
        name: 'description',
        content: computed(() =>
          municipality.value
            ? `Citizen reviews of ${municipality.value.name}: score ${municipality.value.score}/10, ${municipality.value.reviewCount} reviews.`
            : ''
        ),
      },
      {
        property: 'og:title',
        content: computed(() =>
          municipality.value ? `${municipality.value.name} — CitoyenNote` : 'CitoyenNote'
        ),
      },
      {
        property: 'og:url',
        content: `https://citoyennote.fr/municipality/${slug}`,
      },
    ],
    link: [{ rel: 'canonical', href: `https://citoyennote.fr/municipality/${slug}` }],
  })
}

Usage in the component becomes a single line:

useMunicipalitySeo(municipality, props.slug)

Step 3: robots.txt

Place a robots.txt at the root of your public/ folder — Vite will copy it as-is to the build output:

User-agent: *
Allow: /

Sitemap: https://citoyennote.fr/sitemap.xml

If parts of your app shouldn't be indexed (admin panels, user dashboards, private routes), block them explicitly:

User-agent: *
Disallow: /admin/
Disallow: /dashboard/
Disallow: /settings/
Allow: /

Sitemap: https://citoyennote.fr/sitemap.xml

Step 4: dynamic sitemap

A static sitemap only covers routes you know at build time. For a content-heavy app with thousands of municipality pages, the sitemap must be generated dynamically from the database.

In CitoyenNote's case, the backend is a Go API (Echo framework). I added a dedicated /sitemap.xml route:

// routes/sitemap.go
package routes

import (
    "encoding/xml"
    "net/http"
    "time"

    "github.com/labstack/echo/v4"
    "citoyennote/internal/repository"
)

type URLSet struct {
    XMLName xml.Name `xml:"urlset"`
    Xmlns   string   `xml:"xmlns,attr"`
    URLs    []URL    `xml:"url"`
}

type URL struct {
    Loc        string  `xml:"loc"`
    LastMod    string  `xml:"lastmod,omitempty"`
    ChangeFreq string  `xml:"changefreq,omitempty"`
    Priority   float64 `xml:"priority,omitempty"`
}

func SitemapHandler(repo repository.MunicipalityRepository) echo.HandlerFunc {
    return func(c echo.Context) error {
        municipalities, err := repo.ListAll(c.Request().Context())
        if err != nil {
            return err
        }

        urlset := URLSet{
            Xmlns: "http://www.sitemaps.org/schemas/sitemap/0.9",
        }

        // Static routes
        urlset.URLs = append(urlset.URLs,
            URL{Loc: "https://citoyennote.fr/", Priority: 1.0, ChangeFreq: "daily"},
            URL{Loc: "https://citoyennote.fr/search", Priority: 0.8, ChangeFreq: "weekly"},
        )

        // Dynamic municipality pages
        for _, m := range municipalities {
            urlset.URLs = append(urlset.URLs, URL{
                Loc:        "https://citoyennote.fr/municipality/" + m.Slug,
                LastMod:    m.UpdatedAt.Format(time.DateOnly),
                ChangeFreq: "weekly",
                Priority:   0.7,
            })
        }

        c.Response().Header().Set("Content-Type", "application/xml; charset=UTF-8")
        return xml.NewEncoder(c.Response()).Encode(urlset)
    }
}

No build step, no caching needed for this size. For a site with 100,000+ pages, consider splitting into a sitemap index and multiple sub-sitemaps (Google's limit is 50,000 URLs per sitemap file).

Submit the sitemap URL in Google Search Console and verify it parses correctly.

Step 5: JSON-LD structured data

JSON-LD is Google's preferred format for Schema.org structured data. It goes in a <script type="application/ld+json"> tag in the <head>. @unhead/vue handles this cleanly:

// Add to useMunicipalitySeo.ts
useHead({
  // ... existing title/meta config ...
  script: [
    {
      type: 'application/ld+json',
      innerHTML: computed(() => {
        if (!municipality.value) return ''

        return JSON.stringify({
          '@context': 'https://schema.org',
          '@type': 'Place',
          name: municipality.value.name,
          description: `Citizen reviews of ${municipality.value.name}.`,
          url: `https://citoyennote.fr/municipality/${slug}`,
          aggregateRating: {
            '@type': 'AggregateRating',
            ratingValue: municipality.value.score,
            reviewCount: municipality.value.reviewCount,
            bestRating: 10,
            worstRating: 0,
          },
        })
      }),
    },
  ],
})

The AggregateRating type is what enables star ratings to appear directly in Google search results (rich snippets). Not guaranteed, but Google does pick it up reliably for well-structured pages with enough reviews.

For a blog or article, use @type: "BlogPosting" with datePublished, dateModified, and author. For a product, use @type: "Product". The Google structured data gallery lists all types that qualify for rich results.

Step 6: the 404 route

A SPA with client-side routing needs a server-level fallback. Without it, directly navigating to /municipality/paris returns a real 404 from the server before Vue even loads. Google interprets that as a 404 and won't index the page.

The fix depends on your hosting. On Apache:

# .htaccess at the root of your SPA
<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /

  # Don't rewrite real files and directories
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d

  # Everything else goes to index.html
  RewriteRule ^ index.html [L]
</IfModule>

On Nginx:

location / {
    try_files $uri $uri/ /index.html;
}

On Vite's dev server, this works automatically. On production, it's on you.

Inside Vue Router, add a catch-all route that returns a proper 404 UI — and critically, set the HTTP status code. With SSR or prerendering this is straightforward. With pure CSR, the HTTP response for a non-existent route is always 200 (the server returns index.html). Google handles this gracefully for most cases, but it's worth knowing.

// router/index.ts
const routes = [
  // ... your routes ...
  {
    path: '/:pathMatch(.*)*',
    name: 'NotFound',
    component: () => import('@/views/NotFoundView.vue'),
  },
]

The honest limitation: CSR vs SSR

All of the above makes a CSR SPA considerably more Google-friendly. But there's a ceiling.

Google's crawler does execute JavaScript, but it does so in a second wave, hours or days after the initial crawl. The initial crawl reads raw HTML. So what Google sees first is your static index.html — the same fallback on every URL — with no route-specific content.

If your site depends on search visibility for hundreds or thousands of distinct pages (municipality pages, product pages, article pages), you have two real options:

SSR (Server-Side Rendering): Nuxt 3 for Vue.js. The server renders the full HTML for each request. Google gets the right HTML immediately. The cost: a Node.js server, more complex infrastructure, hydration to manage.
SSG (Static Site Generation): Nuxt or VitePress can pre-render all routes at build time to static HTML files. Perfect for content that doesn't change per-user. The cost: dynamic content (user-specific data, real-time scores) needs hydration after the static shell loads.

For CitoyenNote, I stayed with CSR + the fixes above because the content (municipality scores, reviews) changes frequently and Google does eventually index the JavaScript-rendered pages correctly. The SEO improvement from the fixes was significant: 80+ pages indexed within two weeks of the sitemap submission, versus zero before.

If I were starting again from scratch on a project where SEO is the primary acquisition channel, I'd go with Nuxt 3 from day one.

SEO checklist for Vue.js SPAs

A summary you can run through before launching:

index.html: complete <head> with charset, viewport, default title, meta description, Open Graph tags, Twitter Card, canonical URL
@unhead/vue: installed, registered in main.ts, useHead() called in every page component with computed reactive values
Canonical URLs: set on every page, including the homepage
robots.txt: present in public/, includes Sitemap: directive
Sitemap: all indexable URLs listed, dynamic pages included, submitted to Google Search Console
JSON-LD: relevant schema type on key pages (Place, Product, BlogPosting, Organization...)
Server fallback: .htaccess or Nginx config routes all paths to index.html
404 route: catch-all route defined in Vue Router
Google Search Console: sitemap submitted, URL inspection run on a sample of key pages, coverage report checked after 2 weeks
Social sharing test: Facebook Debugger and Twitter Card Validator on at least 3 URLs (homepage, a content page, a 404)

None of this is particularly complicated. The painful part is discovering three months into a project that you forgot to do it. The checklist exists so you don't have to rediscover it the hard way.

Vue 2 vs Vue 3 and Composition API vs Options API: complete comparison

Odilon HUGONNOT — Sun, 17 May 2026 09:00:02 +0000

Vue 3 launched in late 2020. Five years later, Vue 2 has been officially end-of-life since December 2023, yet migration is still dragging in many projects. Between the reactivity rewrite, the Composition API that throws people off at first, and Vite replacing webpack — there's plenty of reason to stall. Here's what actually changed, what it means for your code, and how to choose between the two APIs.

Vue 2 vs Vue 3: what changed in practice

The reactivity system

This is the deepest change. Vue 2 uses Object.defineProperty to observe mutations — with its well-known limitations: no detection of dynamically added properties, no detection on array indexes. Hence the Vue.set() and this.$set() calls that clutter Vue 2 code.

Vue 3 uses ES2015 Proxy. The entire object is intercepted, not property by property. No more $set, direct mutations are detected natively:

// Vue 2 — adding a reactive property after creation
this.$set(this.user, 'email', 'odilon@example.com') // required

// Vue 3 — works directly
this.user.email = 'odilon@example.com' // reactive automatically

Performance and bundle size

Vue 3 is tree-shakable. Unused features (Transition, KeepAlive, Teleport...) are not included in the final bundle if they aren't imported. Vue 2 included the full runtime regardless.

In practice on an average project: runtime bundle reduced by roughly 40% with Vue 3 vs Vue 2. The reactive diff is also faster thanks to a rewritten virtual DOM patching strategy (static template analysis at compile time).

TypeScript

Vue 2 had a patched-together TypeScript support via vue-class-component and decorators. Functional, but tedious. Vue 3 was rewritten in TypeScript from scratch — types are native, inference works without any special configuration in components.

Fragments, Teleport, Suspense

Three structural additions that were missing in Vue 2:

Fragments: a component can return multiple root elements — no more pointless wrapper <div>
Teleport: render HTML into another DOM node (modals, tooltips) without working around CSS with fragile position: fixed hacks
Suspense: handle async component loading states natively

What breaks during migration

The Vue 3 breaking changes that cause the most damage during migration:

$listeners removed — merged into $attrs
$children removed — use ref or provide/inject
filters removed — use methods or computed properties
v-model: the event is now update:modelValue instead of input
Vuex → Pinia (Vuex 5 never shipped)
Vue Router 4 with some API changes

On a large Vue 2 project with lots of filters, $listeners, and Vuex everywhere, migration takes time. The automated migration via @vue/compat helps but doesn't solve everything.

Options API vs Composition API

This is the question that comes up most often when moving to Vue 3. The short answer: both are officially supported, permanently. It's not a replacement but an alternative.

Options API — quick reminder

export default {
  name: 'UserProfile',
  props: {
    userId: String,
  },
  data() {
    return {
      user: null,
      loading: false,
    }
  },
  computed: {
    displayName() {
      return this.user?.name ?? 'Unknown'
    },
  },
  methods: {
    async fetchUser() {
      this.loading = true
      this.user = await api.getUser(this.userId)
      this.loading = false
    },
  },
  mounted() {
    this.fetchUser()
  },
  watch: {
    userId(newId) {
      this.fetchUser()
    },
  },
}

Composition API — same component

import { ref, computed, watch, onMounted } from 'vue'
import { useUserApi } from '@/composables/useUserApi'

export default {
  name: 'UserProfile',
  props: {
    userId: String,
  },
  setup(props) {
    const user = ref(null)
    const loading = ref(false)

    const displayName = computed(() => user.value?.name ?? 'Unknown')

    async function fetchUser() {
      loading.value = true
      user.value = await api.getUser(props.userId)
      loading.value = false
    }

    watch(() => props.userId, fetchUser)
    onMounted(fetchUser)

    return { user, loading, displayName }
  },
}

Or with <script setup> (the recommended syntax in Vue 3):

// <script setup>
import { ref, computed, watch, onMounted } from 'vue'

const props = defineProps({ userId: String })
const user = ref(null)
const loading = ref(false)

const displayName = computed(() => user.value?.name ?? 'Unknown')

async function fetchUser() {
  loading.value = true
  user.value = await api.getUser(props.userId)
  loading.value = false
}

watch(() => props.userId, fetchUser)
onMounted(fetchUser)

Everything declared inside <script setup> is automatically exposed to the template — no more return {}.

Strengths and weaknesses

Options API

Strengths

Rigid and predictable structure — everyone knows where to find data, methods, computed properties
Low learning curve — ideal for onboarding junior devs or devs coming from other frameworks
Very readable on small components — everything is organized by option type
Abundant documentation, examples everywhere on Stack Overflow and legacy projects

Weaknesses

Business logic gets fragmented across data, methods, computed, watch — impossible to keep one "feature" coherent in a single block
Reusing logic between components forces you through mixins — which create naming collisions and make dependencies opaque
Tedious TypeScript: this inside methods doesn't infer well, annotations everywhere
On large components (200+ lines), navigation becomes painful: data is at the top, the method that modifies it is at the bottom, the watcher is somewhere else

Composition API

Strengths

Business logic can be co-located: everything related to fetchUser (state, method, watcher) stays together
Composables cleanly replace mixins: reusable logic is an explicitly imported function, no magic, no collisions
Native TypeScript: ref<User | null>(null), no this, full inference
More effective tree-shaking: only the Vue functions you use are imported

Weaknesses

More verbose on small components — importing ref, computed, onMounted explicitly for 20 lines of logic
The .value on refs is constant friction, a source of bugs (forgetting .value in JS but not in the template)
Without discipline, <script setup> can turn into a grab-bag — structural freedom has a cost if the team doesn't enforce conventions
Less intuitive for someone coming from Vue 2 or React Class Components — the learning curve is real

Direct comparison on concrete cases

Logic reuse: mixins vs composables

This is where the Composition API wins most clearly. A Vue 2 mixin to handle pagination:

// Vue 2 — mixin
export const paginationMixin = {
  data() {
    return {
      page: 1,
      perPage: 10,
      total: 0,
    }
  },
  computed: {
    totalPages() {
      return Math.ceil(this.total / this.perPage)
    },
  },
  methods: {
    nextPage() { this.page++ },
    prevPage() { this.page-- },
  },
}

// Usage — where data.page comes from is not obvious
export default {
  mixins: [paginationMixin],
  // where does this.page come from? mystery for a new dev
}

// Vue 3 — composable
export function usePagination(initialPerPage = 10) {
  const page = ref(1)
  const perPage = ref(initialPerPage)
  const total = ref(0)

  const totalPages = computed(() => Math.ceil(total.value / perPage.value))

  function nextPage() { page.value++ }
  function prevPage() { page.value-- }

  return { page, perPage, total, totalPages, nextPage, prevPage }
}

// Usage — explicit
const { page, total, nextPage } = usePagination(20)
// we know exactly where page comes from

TypeScript: the concrete difference

// Options API with TypeScript — tedious
export default defineComponent({
  data(): { user: User | null; loading: boolean } { // manual annotation
    return { user: null, loading: false }
  },
  methods: {
    async fetchUser(id: string): Promise<void> {
      this.user = await getUser(id) // this isn't always inferred
    },
  },
})

// Composition API — native inference
const user = ref<User | null>(null)
const loading = ref(false) // inferred as ref<boolean>

async function fetchUser(id: string) {
  user.value = await getUser(id) // correctly typed without annotation
}

Conclusion: when to choose which

Options API if:

You're migrating a Vue 2 project and want to minimize change
The team is junior or comes from other MVC frameworks
Components are small and logic isn't reused
You want a framework-enforced structure without the discipline overhead

Composition API if:

You're starting a new Vue 3 project — it's the ecosystem's default choice
You're using TypeScript seriously
You have complex logic to reuse across components
Components are growing — logic co-location becomes a real advantage

What I wish I'd known when starting with Vue 3: both APIs coexist in the same project. A simple form component can stay in Options API while a complex component with 5 composables switches to Composition API. No need to choose once and for all.

On my recent projects, I use the Composition API by default with <script setup> — TypeScript demands it — and composables for everything touching API calls, complex local state management, and DOM interactions (resize observer, intersection observer, etc.). Options API stays for simple presentational components where the rigid structure is an advantage rather than a constraint.

CLAUDE.md for mobile redesign: the context that changes everything

Odilon HUGONNOT — Sat, 16 May 2026 09:00:02 +0000

Ask Claude Code to "make this responsive" without explaining anything. Here's what you get: desktop-first media queries with max-width everywhere, text-align: justify that looks like swiss cheese on an iPhone SE, 32px-tall buttons untappable with a thumb, and no font-size: 16px on inputs — so guaranteed automatic iOS zoom. This isn't incompetence, it's a lack of context. Claude codes with the generic CSS rules it knows, not the mobile-specific rules you have in mind.

The solution: a specialized CLAUDE.md file. Not the project's generic CLAUDE.md, a dedicated file for mobile redesign and CSS design, with precise rules, pitfalls to avoid, and targets to reach. Claude reads it at session startup and applies these rules consistently.

The problem: Claude without mobile context

Claude Code is a generalist tool. It knows CSS, it knows responsive design, but it doesn't know what your priorities are. Does the project target iPhone SE at 375px or tablets at 768px? Does Lighthouse Accessibility need to hit 90? Is dark mode mandatory? Do you prefer BEM or utility-first?

Without this information, Claude produces correct but generic CSS. It will:

Start from desktop and work down (max-width) rather than the reverse
Forget min-width: 0 on flex items — result: mysterious overflows
Leave inputs at 14px — iOS zoom on every tap
Add text-align: justify because "it looks clean"
Ignore prefers-reduced-motion and safe-area-inset
Not test dark mode

Each of these problems takes 10 seconds to fix once detected. The problem is they pile up and you detect them after shipping.

The specialized CLAUDE.md concept

Claude Code automatically reads CLAUDE.md files present in the project — at the root, and in subdirectories if the instruction is in the config. This is the official mechanism for injecting persistent context into a Claude Code session, without having to repeat it in every prompt.

Most projects have a generic CLAUDE.md: project architecture, code conventions, dev commands. The idea here is different: create specialized CLAUDE.md files for specific tasks. A file dedicated to mobile redesign contains exactly what Claude needs for that task — and nothing superfluous.

You can call it CLAUDE-MOBILE.md and reference it from the main CLAUDE.md, or simply drop it temporarily at the root as CLAUDE.md for the duration of the responsive work. Claude Code also supports the .claude/ directory for additional context files — they're loaded in addition to the root CLAUDE.md, not instead of it.

What this MD contains — and why each section

The file is structured in five sections. Each one responds to a specific moment in the work.

Section 1 — Audit workflow. Before writing any CSS, you need to know where to look. This section gives Claude a precise order: first the viewport tag, then input font sizes, then horizontal overflow, then touch targets. This is the order that minimizes time spent debugging problems caused by an upstream oversight. It also includes Lighthouse targets and the "mobile done" checklist — which prevents Claude from declaring the work finished too early.

Section 2 — Mobile testing tools. Playwright scripts for automated screenshots across multiple device profiles — iPhone SE, iPhone 14, Pixel 7, iPad — without leaving the terminal. Variants for dark mode and prefers-reduced-motion. MCP servers (Puppeteer MCP, Playwright MCP) that allow Claude Code to interact directly with a headless browser during the session. And Lighthouse via CLI to audit in JSON or HTML without opening DevTools.

Section 3 — CSS rules. The complete reference of mobile rules with concrete code for each. Not generic docs: ready-to-use snippets with edge cases already handled. The min-width: 0 trap on flex items, coexistence of the manual toggle with prefers-color-scheme, HTML inputmode attributes that complement the CSS for forms — everything that gets lost when working fast.

Section 4 — Generic CSS conventions. Mobile or not, these rules apply to any CSS work: custom properties for theming, BEM for components, focus-visible for keyboard accessibility, modern properties (clamp(), gap, aspect-ratio, logical properties), and the rule on !important. This is what prevents the session's CSS from looking like a patch applied over existing code.

Section 5 — Test checklist. Devices to test, modes (landscape, dark, reduced motion, text zoom), Lighthouse targets by metric, and screen reader testing basics. Claude uses this to know when the task is truly done, not just "passes on my Chrome emulator at 1440px".

How to use it

Three ways, from simplest to cleanest:

Option 1 — Temporary replacement. Rename or save the existing CLAUDE.md, drop this file at the root as CLAUDE.md for the duration of the responsive work. Restore the original when done. Simple, no configuration.

Option 2 — Reference from existing CLAUDE.md. Add a line to the project's CLAUDE.md:

## Mobile context

For all responsive and CSS work:
see CLAUDE-MOBILE.md at the project root.

Claude Code follows references and reads the pointed file.

Option 3 — .claude/ directory. Place the file in .claude/mobile-css.md. Claude Code automatically loads files in this directory in addition to the root CLAUDE.md. Useful if you have multiple specialized contexts (one for mobile, one for tests, one for deployment) and don't want to merge them.

In all cases, the file stacks with the existing context — it doesn't replace already-present instructions.

The complete file

Here is the exact content to copy. This is the raw file, ready to paste.

# CLAUDE.md — Mobile Redesign & CSS Design

> Specialized context for Claude Code. Drop this file at the project root to guide mobile responsive and CSS design work.

---

## Section 1: Mobile redesign workflow

### Initial audit — where to start

Before touching a single line of CSS, do a quick pass in this order:

1. **Viewport tag** — present? `width=device-width, initial-scale=1`? No `user-scalable=no`?
2. **font-size on inputs** — inspect `<input>`, `<textarea>`, `<select>` fields. If < 16px: iOS zoom guaranteed.
3. **Horizontal overflow** — open Chrome DevTools in mobile mode, check if a scrollbar appears at the bottom. Track with `* { outline: 1px solid red; }`.
4. **Touch targets** — tap buttons and nav links in emulation mode. Anything under 44px height needs fixing.
5. **Justified text** — search for `text-align: justify` in CSS. Remove or limit to desktop only.

### Mobile Lighthouse — targets

Run Lighthouse in "Mobile" mode (not Desktop) in DevTools:

| Metric | Target |
|--------|--------|
| Performance | ≥ 80 |
| Accessibility | ≥ 90 |
| Best Practices | ≥ 90 |
| SEO | ≥ 90 |

Priority alerts to fix: tap targets too small, insufficient contrast, missing viewport, inputs without label.

### DevTools device emulation

- Test with profiles: **iPhone SE (375px)**, **iPhone 14 (390px)**, **Pixel 7 (412px)**, **iPad (768px)**
- Enable "Show media queries" to see active breakpoints
- Test in landscape mode
- Simulate "Slow 4G" network to detect performance issues

### Testing on a real device

Emulation doesn't replace real testing. Specific points to check on an actual phone:
- Automatic iOS zoom on inputs (only visible on real device)
- Scroll momentum and bounce zones
- Safe areas (notch, navigation bar)
- Virtual keyboard pushing the layout

### "Mobile done" checklist

- [ ] No unintentional horizontal scroll
- [ ] All interactive elements ≥ 44×44px
- [ ] No input with font-size < 16px
- [ ] Correct viewport meta tag
- [ ] No `text-align: justify` on mobile
- [ ] Body text ≥ 16px, line-height ≥ 1.5
- [ ] Images with `max-width: 100%`
- [ ] Dark mode works (if implemented)
- [ ] Animations respect `prefers-reduced-motion`
- [ ] Lighthouse Accessibility ≥ 90

---

## Section 2: Mobile testing tools — screenshots, emulation, MCP

### Installing test dependencies

```

bash
# Playwright (recommended — multi-browser)
npm init -y
npm install playwright
npx playwright install chromium

# OR Puppeteer (Chromium only)
npm install puppeteer


```

### Automated mobile screenshots

```

javascript
// screenshot-mobile.mjs
import { chromium } from 'playwright';

const devices = [
  { name: 'iPhone SE', width: 375, height: 667, scale: 2 },
  { name: 'iPhone 14', width: 390, height: 844, scale: 3 },
  { name: 'Pixel 7', width: 412, height: 915, scale: 2.625 },
  { name: 'iPad', width: 768, height: 1024, scale: 2 },
];

const url = process.argv[2] || 'http://localhost:8000';

const browser = await chromium.launch();

for (const device of devices) {
  const context = await browser.newContext({
    viewport: { width: device.width, height: device.height },
    deviceScaleFactor: device.scale,
    isMobile: device.width < 768,
    hasTouch: device.width < 768,
  });
  const page = await context.newPage();
  await page.goto(url, { waitUntil: 'networkidle' });
  await page.screenshot({
    path: `screenshot-${device.name.toLowerCase().replace(/\s/g, '-')}.png`,
    fullPage: true,
  });
  console.log(`✓ ${device.name} (${device.width}px)`);
  await context.close();
}

await browser.close();


```

Usage:

```

bash
node screenshot-mobile.mjs http://localhost:8000
# Generates: screenshot-iphone-se.png, screenshot-iphone-14.png, etc.


```

Claude Code can read these screenshots to visually verify rendering.

### Dark mode and reduced motion screenshots

```

javascript
// screenshot-modes.mjs — dark mode and reduced motion variants
import { chromium } from 'playwright';

const url = process.argv[2] || 'http://localhost:8000';
const browser = await chromium.launch();

// Dark mode - iPhone 14
const darkCtx = await browser.newContext({
  viewport: { width: 390, height: 844 },
  deviceScaleFactor: 3,
  isMobile: true,
  hasTouch: true,
  colorScheme: 'dark',
});
const darkPage = await darkCtx.newPage();
await darkPage.goto(url, { waitUntil: 'networkidle' });
await darkPage.screenshot({ path: 'screenshot-dark-mode.png', fullPage: true });
console.log('✓ Dark mode');
await darkCtx.close();

// Reduced motion - iPhone 14
const reducedCtx = await browser.newContext({
  viewport: { width: 390, height: 844 },
  deviceScaleFactor: 3,
  isMobile: true,
  hasTouch: true,
  reducedMotion: 'reduce',
});
const reducedPage = await reducedCtx.newPage();
await reducedPage.goto(url, { waitUntil: 'networkidle' });
await reducedPage.screenshot({ path: 'screenshot-reduced-motion.png', fullPage: true });
console.log('✓ Reduced motion');
await reducedCtx.close();

await browser.close();


```

### Useful MCP Servers

**Puppeteer MCP** (`@modelcontextprotocol/server-puppeteer`):
- Allows Claude Code to navigate a site, take screenshots, inspect the DOM
- Configuration in `.claude/settings.json`:

```

json
{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}


```

**Playwright MCP** (community `playwright-mcp`):
- Same principle, multi-browser
- Useful for testing rendering across different engines (Chromium, Firefox, WebKit/Safari)

### Lighthouse via CLI

```

bash
# Installation
npm install -g lighthouse

# Mobile audit
lighthouse http://localhost:8000 --preset=perf --form-factor=mobile --output=html --output-path=./lighthouse-mobile.html

# Mobile audit in JSON (parseable)
lighthouse http://localhost:8000 --form-factor=mobile --output=json --output-path=./lighthouse-mobile.json


```

Claude Code can read the HTML report to identify issues.

### Debug with Chrome DevTools Protocol

Playwright and Puppeteer expose CDP (Chrome DevTools Protocol), providing programmatic access to:
- **Network throttling** — simulate Slow 3G/4G to detect loading bottlenecks
- **CSS coverage** — identify CSS rules never applied (dead code)
- **Performance traces** — capture a full trace to analyze rendering frame by frame

---

## Section 3: Mobile CSS Rules — complete reference

### Viewport meta tag

```

html
<!-- ✅ Correct -->
<meta name="viewport" content="width=device-width, initial-scale=1">

<!-- If using safe-area-inset -->
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">

<!-- ❌ Never do this: prevents zoom for visually impaired users -->
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no, maximum-scale=1">


```

### Base reset

```

css
*,
*::before,
*::after {
    box-sizing: border-box;
}

html {
    -webkit-text-size-adjust: 100%;
    text-size-adjust: 100%;
}

html, body {
    overflow-x: hidden;
    max-width: 100%;
}

img, video, svg {
    max-width: 100%;
    height: auto;
    display: block;
}


```

### Text alignment

Simple rule: **left by default, centered only for CTAs, never justify on mobile**.

```

css
/* Mobile base */
h1, h2, h3, h4 {
    text-align: left;
}

p, li {
    text-align: left;
}

/* CTA: centered */
.cta-wrapper {
    text-align: center;
}

/* Justify only on desktop with hyphenation */
@media (min-width: 768px) {
    .prose p {
        text-align: justify;
        hyphens: auto;
        -webkit-hyphens: auto;
    }
}


```

### Touch targets — 44×44px minimum

```

css
/* Buttons */
.btn {
    min-height: 44px;
    min-width: 44px;
    padding: 12px 20px;
    display: inline-flex;
    align-items: center;
    justify-content: center;
}

/* Navigation links */
nav a {
    display: block;
    min-height: 44px;
    padding: 12px 16px;
    line-height: 20px;
}

/* Clickable icons */
.icon-btn {
    width: 44px;
    height: 44px;
    display: flex;
    align-items: center;
    justify-content: center;
    cursor: pointer;
}

/* Enlarged tap zone without changing appearance */
.small-icon {
    position: relative;
    width: 20px;
    height: 20px;
}

.small-icon::after {
    content: '';
    position: absolute;
    inset: -12px;
}


```

### Font-size — iOS zoom prevention and readability

```

css
/* ❌ Less than 16px on inputs = automatic iOS zoom */

/* ✅ Absolute minimum on inputs */
input,
textarea,
select {
    font-size: 16px;
}

/* If different size desired on desktop */
@media (min-width: 768px) {
    input,
    textarea,
    select {
        font-size: 14px;
    }
}

/* Body text */
body {
    font-size: 16px;
    line-height: 1.6;
}

/* Fluid headings with clamp() */
h1 { font-size: clamp(1.5rem, 5vw, 2.5rem); }
h2 { font-size: clamp(1.25rem, 4vw, 2rem); }
h3 { font-size: clamp(1.1rem, 3vw, 1.5rem); }


```

### Media queries — mobile-first only

```

css
/* ✅ Mobile-first: base = mobile, add for larger screens */
.card {
    display: block;
    padding: 16px;
}

@media (min-width: 768px) {
    .card {
        display: flex;
        padding: 24px;
    }
}

@media (min-width: 1024px) {
    .card {
        padding: 32px;
    }
}

/* ❌ Desktop-first: avoid */
.card {
    display: flex;
    padding: 32px;
}

@media (max-width: 767px) {
    .card {
        display: block;
        padding: 16px;
    }
}


```

Standard breakpoints: `480px`, `768px`, `1024px`, `1280px`.

### overflow-x prevention

```

css
html, body {
    overflow-x: hidden;
    max-width: 100%;
}

/* Tables: scroll rather than breaking the layout */
.table-wrapper {
    overflow-x: auto;
}

table {
    min-width: 600px;
    width: 100%;
}

/* Debug: identify the overflowing element */
* { outline: 1px solid red; }


```

Warning: `overflow-x: hidden` on `body` can break `position: sticky`. If a sticky stops working, isolate `overflow-x: hidden` on a dedicated wrapper.

### Images and aspect-ratio

```

css
img {
    max-width: 100%;
    height: auto;
    display: block;
}

/* Fixed ratio to avoid CLS (Cumulative Layout Shift) */
.card-image {
    aspect-ratio: 4 / 3;
    width: 100%;
    object-fit: cover;
}

.hero-image {
    aspect-ratio: 16 / 9;
    width: 100%;
    object-fit: cover;
}

/* Different ratio on mobile */
@media (max-width: 767px) {
    .hero-image {
        aspect-ratio: 4 / 3;
    }
}


```

### Flex and Grid — common pitfalls

```

css
/* Flex: min-width: 0 required to prevent text overflows */
.flex-item {
    min-width: 0;
}

/* Automatic flex wrap */
.card-grid {
    display: flex;
    flex-wrap: wrap;
    gap: 16px;
}

.card-grid .card {
    flex: 1 1 280px;
    min-width: 0;
}

/* Responsive grid without media query */
.auto-grid {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
    gap: 16px;
}

/* Grid: single column on mobile, two columns on desktop */
.two-col {
    display: grid;
    grid-template-columns: 1fr;
    gap: 24px;
}

@media (min-width: 768px) {
    .two-col {
        grid-template-columns: 1fr 1fr;
    }
}


```

### Safe area insets (notch, navigation bar)

```

css
/* Requires viewport-fit=cover in meta tag */

.bottom-nav {
    position: fixed;
    bottom: 0;
    left: 0;
    right: 0;
    height: 56px;
    padding-bottom: env(safe-area-inset-bottom);
    background: var(--color-bg);
}

.top-header {
    position: fixed;
    top: 0;
    left: 0;
    right: 0;
    padding-top: env(safe-area-inset-top);
}

.main-content {
    padding-bottom: calc(56px + env(safe-area-inset-bottom));
    padding-left: env(safe-area-inset-left);
    padding-right: env(safe-area-inset-right);
}


```

If `viewport-fit=cover` is not defined, values equal 0 — these rules have no negative effect.

### prefers-reduced-motion

```

css
/* Animations defined normally */
.fade-in {
    animation: fadeIn 0.4s ease;
}

/* Global removal if user requests it */
@media (prefers-reduced-motion: reduce) {
    *,
    *::before,
    *::after {
        animation-duration: 0.01ms !important;
        animation-iteration-count: 1 !important;
        transition-duration: 0.01ms !important;
        scroll-behavior: auto !important;
    }
}

/* More granular approach */
@media (prefers-reduced-motion: reduce) {
    .fade-in {
        opacity: 1;
        animation: none;
    }
}


```

### prefers-color-scheme — dark mode

```

css
:root {
    --color-bg: #ffffff;
    --color-text: #1a1a1a;
    --color-text-muted: #6b7280;
    --color-border: #e5e7eb;
    --color-surface: #f9fafb;
    --color-primary: #2563eb;
    --color-primary-text: #ffffff;
    --shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
}

@media (prefers-color-scheme: dark) {
    :root {
        --color-bg: #0f172a;
        --color-text: #e2e8f0;
        --color-text-muted: #94a3b8;
        --color-border: #1e293b;
        --color-surface: #1e293b;
        --color-primary: #3b82f6;
        --color-primary-text: #ffffff;
        --shadow: 0 1px 3px rgba(0, 0, 0, 0.4);
    }

    img:not([src*=".svg"]) {
        filter: brightness(0.9);
    }
}

/* Manual toggle coexisting with system preference */
@media (prefers-color-scheme: dark) {
    :root:not([data-theme="light"]) {
        --color-bg: #0f172a;
        /* ... */
    }
}

[data-theme="dark"] {
    --color-bg: #0f172a;
    /* ... */
}

[data-theme="light"] {
    --color-bg: #ffffff;
    /* ... */
}


```

### Forms

```

css
input[type="text"],
input[type="email"],
input[type="password"],
input[type="tel"],
input[type="number"],
textarea,
select {
    width: 100%;
    font-size: 16px; /* required — prevents iOS zoom */
    padding: 12px 16px;
    min-height: 44px;
    border-radius: 8px;
    border: 1px solid var(--color-border);
    -webkit-appearance: none;
    appearance: none;
    background: var(--color-bg);
    color: var(--color-text);
}

label {
    display: block;
    font-size: 16px;
    margin-bottom: 6px;
    font-weight: 500;
}

.form-group {
    margin-bottom: 20px;
}


```

HTML attributes not to forget (CSS can't replace them):

```

html
<!-- Numeric keyboard -->
<input type="text" inputmode="numeric">

<!-- Decimal keyboard -->
<input type="text" inputmode="decimal">

<!-- Email keyboard with direct @ -->
<input type="email" inputmode="email">

<!-- URL keyboard -->
<input type="url" inputmode="url">


```

### Minimum lateral spacing

```

css
.container {
    padding-left: 16px;  /* absolute minimum on mobile */
    padding-right: 16px;
    max-width: 1200px;
    margin: 0 auto;
}

@media (min-width: 768px) {
    .container {
        padding-left: 24px;
        padding-right: 24px;
    }
}

@media (min-width: 1024px) {
    .container {
        padding-left: 32px;
        padding-right: 32px;
    }
}


```

---

## Section 4: CSS Conventions — generic rules

### CSS custom properties for theming

Always define repeated values as custom properties. Never hard-code colors or spacing values scattered throughout CSS.

```

css
:root {
    /* Colors */
    --color-primary: #2563eb;
    --color-primary-hover: #1d4ed8;
    --color-bg: #ffffff;
    --color-text: #1a1a1a;
    --color-text-muted: #6b7280;
    --color-border: #e5e7eb;
    --color-surface: #f9fafb;
    --color-danger: #dc2626;
    --color-success: #16a34a;

    /* Spacing */
    --space-xs: 4px;
    --space-sm: 8px;
    --space-md: 16px;
    --space-lg: 24px;
    --space-xl: 32px;
    --space-2xl: 48px;

    /* Typography */
    --font-size-sm: 0.875rem;
    --font-size-base: 1rem;
    --font-size-lg: 1.125rem;
    --font-size-xl: 1.25rem;
    --line-height-base: 1.6;
    --line-height-tight: 1.3;

    /* Radii */
    --radius-sm: 4px;
    --radius-md: 8px;
    --radius-lg: 12px;
    --radius-full: 9999px;

    /* Shadows */
    --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
    --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.07);
    --shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1);

    /* Transitions */
    --transition-fast: 0.15s ease;
    --transition-base: 0.25s ease;
}


```

### Naming conventions

Be consistent. BEM or utility-first, not both mixed in the same project.

**BEM** (recommended for isolated components):

```

css
/* Block */
.card {}

/* Element */
.card__title {}
.card__body {}
.card__footer {}

/* Modifier */
.card--featured {}
.card--compact {}
.card__title--large {}


```

### Accessibility

**focus-visible** — never remove the outline without replacing it:

```

css
/* ❌ Never do this */
* { outline: none; }
:focus { outline: none; }

/* ✅ Replace the native outline with a custom style */
:focus-visible {
    outline: 2px solid var(--color-primary);
    outline-offset: 2px;
    border-radius: 2px;
}

/* Remove outline only for mouse clicks (not keyboard) */
:focus:not(:focus-visible) {
    outline: none;
}


```

**WCAG AA contrasts**:

| Context | Minimum ratio |
|---------|--------------|
| Normal text (< 18px) | 4.5:1 |
| Large text (≥ 18px or ≥ 14px bold) | 3:1 |
| UI components, icons | 3:1 |

### CSS performance

```

css
/* ❌ Triggers repaint on every animation frame */
.card:hover {
    box-shadow: 0 8px 30px rgba(0,0,0,0.2);
}

/* ✅ Better: prepare the shadow on load, change opacity */
.card {
    box-shadow: 0 8px 30px rgba(0,0,0,0);
    transition: box-shadow var(--transition-base);
}
.card:hover {
    box-shadow: 0 8px 30px rgba(0,0,0,0.2);
}

/* ✅ Use opacity or transform — composited on GPU */
.element {
    transform: translateY(0);
    opacity: 1;
    transition: transform var(--transition-base), opacity var(--transition-base);
}

.element.hidden {
    transform: translateY(8px);
    opacity: 0;
}


```

### Modern CSS to prefer

```

css
/* clamp() — fluid sizes without media queries */
h1 { font-size: clamp(1.5rem, 5vw, 2.5rem); }
.container { padding: clamp(16px, 4vw, 48px); }

/* gap — more readable than margin on children */
.grid {
    display: flex;
    gap: 24px;
}

/* aspect-ratio — more reliable than the padding-top hack */
.video-wrapper {
    aspect-ratio: 16 / 9;
    width: 100%;
}

/* Logical properties — for multilingual support (RTL/LTR) */
.card {
    margin-inline: auto;
    padding-block: 24px;
    border-inline-start: 3px solid var(--color-primary);
}

/* inset — replaces top/right/bottom/left */
.overlay {
    position: fixed;
    inset: 0;
}


```

### Rule on !important

`!important` is accepted only in two cases:
1. Utility classes (`.sr-only`, `.hidden`, `.visually-hidden`) — by convention
2. Overriding third-party styles you don't control (plugins, libraries)

Outside these cases, a `!important` signals a specificity problem to fix at the source.

---

## Section 5: Test checklist

### Devices to test

| Device | Width | Priority |
|--------|-------|----------|
| iPhone SE (2020/2022) | 375px | High — narrowest mainstream screen |
| iPhone 14 / 15 | 390px | High — current iOS reference |
| Android mid-range (Pixel 6a, Samsung A54) | 360–412px | High |
| iPad / iPad Mini | 768px | Medium |
| Desktop laptop | 1280–1440px | Baseline |

### Modes to test

- [ ] Portrait (default)
- [ ] Landscape
- [ ] Dark mode
- [ ] Reduced motion
- [ ] Text zoom at 150%

### Lighthouse — targets

| Score | Target |
|-------|--------|
| Performance | ≥ 80 |
| Accessibility | ≥ 90 |
| Best Practices | ≥ 90 |
| SEO | ≥ 90 |

### Final checklist

- [ ] No horizontal scroll on any tested device
- [ ] All interactive elements keyboard accessible (Tab + Enter/Space)
- [ ] focus-visible visible and distinctive
- [ ] All inputs with font-size ≥ 16px
- [ ] Text with contrast ≥ 4.5:1 (normal) or 3:1 (large)
- [ ] Images with descriptive `alt` or `alt=""` if decorative
- [ ] Forms with `<label>` associated to each input
- [ ] Dark mode: readable text, no blinding white
- [ ] Reduced motion: no animation still playing
- [ ] Lighthouse Accessibility ≥ 90
- [ ] No automatic iOS zoom on inputs
- [ ] Touch targets ≥ 44×44px
```

`

## Download the file

The file is available directly: [Download the CLAUDE.md](https://www.web-developpeur.com/blog/claude-md/contexts/mobile-css-redesign.md). Drop it at the project root or in `.claude/`.

## What's next

The idea behind this file is to build a collection of specialized CLAUDE.md files by task type. Not a generic CLAUDE.md that tries to cover everything and becomes unreadable, but targeted files you activate based on the current work. Mobile CSS, Go unit tests, PostgreSQL migrations, security audit — each with its precise context, targets, and pitfalls.

This one is the first in the series. If you have specialized contexts you already use, or tasks for which you'd like a file of the same kind, the comments are open.

**📄 Associated CLAUDE.md**

[View](https://www.web-developpeur.com/blog/claude-md/view.php?ctx=mobile-css-redesign) • [Download](https://www.web-developpeur.com/blog/claude-md/contexts/mobile-css-redesign.md) • [Catalogue](https://www.web-developpeur.com/blog/claude-md/)

Mobile CSS consistency: all best practices in 2026

Odilon HUGONNOT — Fri, 15 May 2026 09:00:02 +0000

We've all done it: build the interface on a 1440px screen, drag the window to shrink it, decide it "looks fine", and ship to production. Two days later, a user reports that the submit button is too small to tap, that justified text looks like swiss cheese on their iPhone SE, and that the login form triggers automatic Safari zoom. All of it avoidable. In 2026, mobile accounts for over 60% of global web traffic. It's no longer an edge case — it's the primary case.

Here are the concrete CSS rules, organized by theme. No theory: code that works and explanations for why the alternative fails.

Viewport and document base

Before any CSS, the meta viewport tag in the <head>. Without it, mobile browsers simulate a desktop screen and reduce zoom — all responsive CSS becomes useless.

<meta name="viewport" content="width=device-width, initial-scale=1">

Do not add user-scalable=no or maximum-scale=1. This is a disastrous accessibility practice: it prevents visually impaired users from zooming. Apple actually removed the effect of user-scalable=no in iOS 10 for this reason. Useless and harmful.

Then, the basic reset that avoids surprises:

*,
*::before,
*::after {
    box-sizing: border-box;
}

html {
    /* Prevents automatic text enlargement on rotation */
    -webkit-text-size-adjust: 100%;
    text-size-adjust: 100%;
}

Text alignment: the simple rule

Justified text (text-align: justify) looks clean on desktop with a 700px column. On mobile with a 320px column, the hyphenation algorithm creates irregular inter-word spacing, sometimes grotesque. Some mobile browsers don't handle automatic hyphenation (hyphens: auto) correctly. Result: holes in the text, degraded readability.

The rule to follow:

Headings h1–h4: left-aligned. Easier to scan, the eye always knows where to resume.
Body text / paragraphs: left-aligned. Justified on mobile is a bad idea in almost all cases.
CTA buttons: centered. Catches the eye and is easier to tap with the thumb.
Lists: left-aligned. The bullet/number already does the visual work.

/* Base rule — applies from mobile up */
h1, h2, h3, h4 {
    text-align: left;
}

p, li {
    text-align: left;
    /* No justify on mobile */
}

/* If you want justify on desktop only */
@media (min-width: 768px) {
    .prose p {
        text-align: justify;
        hyphens: auto;
        -webkit-hyphens: auto;
    }
}

/* CTA buttons: centered */
.cta-wrapper {
    text-align: center;
}

.btn-cta {
    display: inline-block;
}

Touch targets: 44×44px minimum

Apple recommends 44×44pt, Google Material Design recommends 48×48dp. The basic rule: every interactive element (button, nav link, checkbox, clickable icon) must have a tap zone of at least 44×44px. A 12px-tall link is unusable with a thumb without a magnifier.

/* Buttons: guaranteed minimum size */
.btn {
    min-height: 44px;
    min-width: 44px;
    padding: 12px 20px;
    display: inline-flex;
    align-items: center;
    justify-content: center;
}

/* Navigation links */
nav a {
    display: block;
    min-height: 44px;
    padding: 12px 16px;
    line-height: 20px;
}

/* Inline links in text: enlarged tap zone without touching the layout */
.text-link {
    padding: 4px 0;
    /* The tap zone will be taller than the text */
}

/* Clickable icons (burger menu, close, etc.) */
.icon-btn {
    width: 44px;
    height: 44px;
    display: flex;
    align-items: center;
    justify-content: center;
    cursor: pointer;
}

If an element is visually small (20×20px icon) but needs to be tappable, you can enlarge the click zone without changing the appearance using ::after:

.small-icon {
    position: relative;
    width: 20px;
    height: 20px;
}

.small-icon::after {
    content: '';
    position: absolute;
    inset: -12px; /* enlarges the tap zone by 12px in each direction */
}

Font sizes: the iOS zoom pitfall

Safari on iOS automatically zooms into a form field when the font size is below 16px. It's "helpful" but it breaks the entire page layout. The fix is simple: never go below 16px on inputs.

/* Prevents automatic iOS zoom on inputs */
input,
textarea,
select {
    font-size: 16px; /* Absolute minimum on mobile */
}

/* If you want a different size on desktop */
@media (min-width: 768px) {
    input,
    textarea,
    select {
        font-size: 14px; /* OK on desktop */
    }
}

/* Body text: 16px minimum on mobile */
body {
    font-size: 16px;
    line-height: 1.6;
}

/* Headings: adapt without going too small */
h1 { font-size: clamp(1.5rem, 5vw, 2.5rem); }
h2 { font-size: clamp(1.25rem, 4vw, 2rem); }
h3 { font-size: clamp(1.1rem, 3vw, 1.5rem); }

clamp() is well supported (Chrome 79+, Firefox 75+, Safari 13.1+) and avoids writing media queries for every heading. The syntax: clamp(min, preferred, max). The "preferred" value in vw allows a smooth progression between breakpoints.

Media queries: mobile-first or desktop-first?

This debate has a clear answer. Mobile-first wins, for concrete reasons:

Base CSS applies to mobile devices without overriding media queries
You don't override mobile styles with desktop — you build on them
Slightly better performance: mobile browsers parse fewer conditional rules

/* ✅ Mobile-first: start from mobile, add for larger screens */
.card {
    display: block;
    padding: 16px;
}

@media (min-width: 768px) {
    .card {
        display: flex;
        padding: 24px;
    }
}

@media (min-width: 1024px) {
    .card {
        padding: 32px;
    }
}

/* ❌ Desktop-first: start from desktop, override for mobile */
.card {
    display: flex;
    padding: 32px;
}

@media (max-width: 1023px) {
    .card {
        padding: 24px;
    }
}

@media (max-width: 767px) {
    .card {
        display: block;
        padding: 16px;
    }
}

In practice, both approaches often coexist in a legacy codebase. What matters: be consistent within a given component, don't mix both approaches in the same rules.

Horizontal scroll: the overflow-x trap

Unintentional horizontal scroll on mobile is one of the most common and most painful bugs to debug. Typical causes: an element with a fixed width larger than 100vw, a forgotten white-space: nowrap, a translate going off-screen, an image with no width constraint.

/* Global prevention */
html, body {
    overflow-x: hidden;
    max-width: 100%;
}

/* Responsive images — basic rule */
img, video, svg {
    max-width: 100%;
    height: auto;
}

/* Tables: allow horizontal scroll rather than breaking the layout */
.table-wrapper {
    overflow-x: auto;
    -webkit-overflow-scrolling: touch;
}

table {
    min-width: 600px; /* or whatever width is needed */
    width: 100%;
}

Warning: overflow-x: hidden on body can interfere with position: sticky elements. If a sticky stops working, it's usually an ancestor with overflow that's blocking it. In that case, isolate overflow-x: hidden on a specific wrapper rather than on body.

To debug a mysterious horizontal scroll:

/* Temporary debug: identify which element is overflowing */
* {
    outline: 1px solid red;
}

Spacing and mobile-friendly padding

On mobile, space is precious but thumbs need room. The minimum lateral padding to avoid content flush against the edge: 16px. 20px is more comfortable.

.container {
    padding-left: 16px;
    padding-right: 16px;
    max-width: 1200px;
    margin: 0 auto;
}

@media (min-width: 768px) {
    .container {
        padding-left: 24px;
        padding-right: 24px;
    }
}

@media (min-width: 1024px) {
    .container {
        padding-left: 32px;
        padding-right: 32px;
    }
}

/* Vertical spacing between sections */
.section {
    padding-top: 40px;
    padding-bottom: 40px;
}

@media (min-width: 768px) {
    .section {
        padding-top: 64px;
        padding-bottom: 64px;
    }
}

Mobile forms

Beyond the font-size: 16px already mentioned, forms on mobile have other particularities.

/* Full-width inputs on mobile */
input[type="text"],
input[type="email"],
input[type="password"],
input[type="tel"],
textarea,
select {
    width: 100%;
    font-size: 16px; /* Prevents iOS zoom */
    padding: 12px 16px;
    min-height: 44px;
    border-radius: 8px;
    border: 1px solid #ccc;
    /* Removes native iOS styling for more control */
    -webkit-appearance: none;
    appearance: none;
}

/* Numeric keyboard on mobile for appropriate fields */
/* (HTML, not CSS, but often forgotten) */
/* <input type="tel" inputmode="numeric"> */
/* <input type="text" inputmode="decimal"> */

/* Labels: readable size, sufficient spacing */
label {
    display: block;
    font-size: 16px;
    margin-bottom: 6px;
    font-weight: 500;
}

/* Spacing between fields */
.form-group {
    margin-bottom: 20px;
}

The inputmode attribute (HTML, not CSS) is crucial for displaying the right virtual keyboard: numeric for codes, decimal for amounts, email for emails (shows the @ directly), url for URLs. It costs nothing and significantly improves UX.

Flexbox and Grid: mobile pitfalls

Flexbox and Grid work well on mobile, but a few behaviors can surprise you.

/* Flex: avoid unintentional shrinking */
.flex-item {
    flex-shrink: 0; /* If the element shouldn't shrink */
    min-width: 0;   /* Classic fix: flex items have min-width: auto by default,
                       which prevents text from wrapping */
}

/* Flex wrap to switch to column on mobile */
.card-grid {
    display: flex;
    flex-wrap: wrap;
    gap: 16px;
}

.card-grid .card {
    flex: 1 1 280px; /* Grows, shrinks, base 280px → automatic wrap on mobile */
    min-width: 0;
}

/* Responsive grid without media queries */
.auto-grid {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
    gap: 16px;
}

/* Grid: single column on mobile */
.two-col {
    display: grid;
    grid-template-columns: 1fr;
    gap: 24px;
}

@media (min-width: 768px) {
    .two-col {
        grid-template-columns: 1fr 1fr;
    }
}

The min-width: 0 on flex items is a fix to know by heart. Without it, a long word or a URL inside a flex item can overflow its container even with overflow: hidden or word-break: break-all.

Safe area insets for notched phones

Since the iPhone X and its Android competitors, phones have notches, dynamic islands, and rounded navigation bars that can overlap content. The env(safe-area-inset-*) values let you account for them.

/* Extended viewport to use the full surface */
/* In the meta viewport: viewport-fit=cover is required */
/* <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover"> */

/* Fixed bottom navigation (common pattern on mobile) */
.bottom-nav {
    position: fixed;
    bottom: 0;
    left: 0;
    right: 0;
    height: 56px;
    padding-bottom: env(safe-area-inset-bottom);
    background: #fff;
    border-top: 1px solid #e0e0e0;
}

/* Fixed top header */
.top-header {
    position: fixed;
    top: 0;
    left: 0;
    right: 0;
    padding-top: env(safe-area-inset-top);
}

/* Main content: margin to avoid overlap */
.main-content {
    padding-bottom: calc(56px + env(safe-area-inset-bottom));
    padding-left: env(safe-area-inset-left);
    padding-right: env(safe-area-inset-right);
}

If the site doesn't use viewport-fit=cover, safe area insets equal 0 and these rules have no effect — no risk of breaking anything by adding them.

Mobile navigation: hamburger and patterns

No magic CSS here, but a few rules that avoid classic mistakes:

/* Hamburger menu: hidden on desktop, visible on mobile */
.nav-toggle {
    display: flex;
    align-items: center;
    justify-content: center;
    width: 44px;
    height: 44px;
    background: none;
    border: none;
    cursor: pointer;
    padding: 0;
}

@media (min-width: 768px) {
    .nav-toggle {
        display: none;
    }
}

/* Mobile nav: clean transition */
.nav-menu {
    display: none;
    flex-direction: column;
    position: fixed;
    inset: 0;
    background: #fff;
    z-index: 1000;
    padding: 60px 24px 24px;
    overflow-y: auto;
}

.nav-menu.is-open {
    display: flex;
}

/* Or version with transition */
.nav-menu {
    position: fixed;
    inset: 0;
    background: #fff;
    z-index: 1000;
    padding: 60px 24px 24px;
    overflow-y: auto;
    transform: translateX(-100%);
    transition: transform 0.25s ease;
}

.nav-menu.is-open {
    transform: translateX(0);
}

/* Menu links: large enough to tap */
.nav-menu a {
    display: block;
    padding: 16px 0;
    font-size: 18px;
    border-bottom: 1px solid #f0f0f0;
    text-decoration: none;
    color: inherit;
}

@media (min-width: 768px) {
    .nav-menu {
        position: static;
        transform: none;
        display: flex;
        flex-direction: row;
        padding: 0;
        gap: 24px;
    }

    .nav-menu a {
        padding: 8px 0;
        font-size: 16px;
        border-bottom: none;
    }
}

Performance: prefers-reduced-motion

Some users have configured their system to reduce animations (epilepsy, vestibular disorders, personal preference). The prefers-reduced-motion media query lets you respect their choice.

/* Default animations */
.fade-in {
    animation: fadeIn 0.4s ease;
}

.slide-up {
    animation: slideUp 0.3s ease;
}

/* Remove animations if the user requests it */
@media (prefers-reduced-motion: reduce) {
    *,
    *::before,
    *::after {
        animation-duration: 0.01ms !important;
        animation-iteration-count: 1 !important;
        transition-duration: 0.01ms !important;
        scroll-behavior: auto !important;
    }
}

/* More granular approach: remove only decorative animations */
@media (prefers-reduced-motion: reduce) {
    .decorative-animation {
        animation: none;
    }

    .fade-in {
        opacity: 1; /* Show directly without fade */
    }
}

On mobile, this has an additional impact: animations drain battery. Respecting prefers-reduced-motion also means being more resource-efficient.

Dark mode with prefers-color-scheme

Dark mode has been OS-managed since iOS 13 and Android 10. Users expect web applications to respect their system preference.

/* CSS variables: clean approach for dark mode */
:root {
    --color-bg: #ffffff;
    --color-text: #1a1a1a;
    --color-text-muted: #6b7280;
    --color-border: #e5e7eb;
    --color-surface: #f9fafb;
    --color-primary: #2563eb;
    --color-primary-text: #ffffff;
    --shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
}

@media (prefers-color-scheme: dark) {
    :root {
        --color-bg: #0f172a;
        --color-text: #e2e8f0;
        --color-text-muted: #94a3b8;
        --color-border: #1e293b;
        --color-surface: #1e293b;
        --color-primary: #3b82f6;
        --color-primary-text: #ffffff;
        --shadow: 0 1px 3px rgba(0, 0, 0, 0.4);
    }
}

/* Usage */
body {
    background-color: var(--color-bg);
    color: var(--color-text);
}

.card {
    background: var(--color-surface);
    border: 1px solid var(--color-border);
    box-shadow: var(--shadow);
}

/* Images: slightly dim in dark mode to reduce glare */
@media (prefers-color-scheme: dark) {
    img:not([src*=".svg"]) {
        filter: brightness(0.9);
    }
}

If the site also implements a manual toggle (light/dark button), you need to manage coexistence with the system preference. The classic approach: add a data-theme="dark" class on <html> when the user toggles manually, and scope the variables accordingly.

/* System preference */
@media (prefers-color-scheme: dark) {
    :root:not([data-theme="light"]) {
        --color-bg: #0f172a;
        /* ... */
    }
}

/* Manual override: dark */
[data-theme="dark"] {
    --color-bg: #0f172a;
    /* ... */
}

/* Manual override: light (takes priority over system dark preference) */
[data-theme="light"] {
    --color-bg: #ffffff;
    /* ... */
}

Scroll behavior and -webkit-overflow-scrolling

iOS native scroll has a momentum (inertia) effect that is sometimes missing in custom scrollable areas. Historically, -webkit-overflow-scrolling: touch was added to enable it. It's now the default behavior since iOS 13. The property is deprecated but harmless if it lingers in legacy code.

/* Smooth scroll for anchor links */
html {
    scroll-behavior: smooth;
}

/* Respect prefers-reduced-motion */
@media (prefers-reduced-motion: reduce) {
    html {
        scroll-behavior: auto;
    }
}

/* Custom scrollable area with scroll snap */
.carousel {
    display: flex;
    overflow-x: auto;
    scroll-snap-type: x mandatory;
    gap: 16px;
    padding: 16px;
    /* Hide scrollbar on desktop, keep the scroll */
    scrollbar-width: none; /* Firefox */
    -ms-overflow-style: none; /* IE/Edge */
}

.carousel::-webkit-scrollbar {
    display: none; /* Chrome/Safari */
}

.carousel-item {
    scroll-snap-align: start;
    flex-shrink: 0;
    width: 280px;
}

Images: max-width and aspect-ratio

/* Responsive base */
img {
    max-width: 100%;
    height: auto;
    display: block;
}

/* Avoid layout shift (CLS) with aspect-ratio */
.product-image {
    aspect-ratio: 4 / 3;
    width: 100%;
    object-fit: cover;
    border-radius: 8px;
}

/* Full-width hero image */
.hero-image {
    aspect-ratio: 16 / 9;
    width: 100%;
    object-fit: cover;
}

/* On mobile, squarer ratio */
@media (max-width: 767px) {
    .hero-image {
        aspect-ratio: 4 / 3;
    }
}

/* Images with loading background */
.lazy-image {
    background-color: #f0f0f0;
    aspect-ratio: 16 / 9;
    width: 100%;
}

aspect-ratio is well supported (Chrome 88+, Firefox 89+, Safari 15+) and advantageously replaces the old padding-top hack technique for maintaining the ratio of an image before it loads.

Summary: rules to apply by default

Viewport: width=device-width, initial-scale=1 without user-scalable=no
Box-sizing: border-box on everything
Text-size-adjust: 100% to prevent automatic enlargement
Alignment: headings and body left-aligned, CTA buttons centered, no justify on mobile
Touch targets: 44×44px minimum for everything clickable
Input font-size: 16px minimum, otherwise automatic iOS zoom
Body text: 16px minimum, line-height 1.5–1.6
Media queries: mobile-first (min-width)
Overflow-x: hidden on html/body, tables in a scrollable wrapper
Images: max-width: 100%, aspect-ratio to avoid CLS
Forms: width: 100% on inputs, appropriate inputmode in HTML
Flex items: min-width: 0 to avoid overflows
Safe areas: env(safe-area-inset-*) for fixed elements with viewport-fit=cover
prefers-reduced-motion: remove or attenuate animations
prefers-color-scheme: CSS variables for dark mode
Scroll snap: for native horizontal carousels

None of these rules are revolutionary. What is, is applying them systematically from the start of the project rather than fixing them one by one after user reports.

Docker + Symfony + WSL2: the 3 first-day problems

Odilon HUGONNOT — Thu, 14 May 2026 09:00:02 +0000

New Symfony 7 project. Target stack: PostgreSQL 16, Redis 7, Apache (not Nginx — personal preference, more on that later). Dev environment: WSL2 on Windows. In theory, Docker + WSL2 has been smooth for a few versions now.

In practice, there are 3 problems that show up systematically on day one, that aren't documented together anywhere, and that waste an hour every time. Here's how to avoid them.

The final stack

The complete docker-compose.yml:

services:
  app:
    build: .
    ports:
      - "8080:80"
    volumes:
      - .:/var/www/html
    depends_on:
      - db
      - redis
    environment:
      DATABASE_URL: "postgresql://app:password@db:5432/touspourris"

  db:
    image: postgres:16-alpine
    ports:
      - "5433:5432"   # 5433 on host, not 5432
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: password
      POSTGRES_DB: touspourris
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  postgres_data:

The detail that matters: the 5433:5432 port mapping for PostgreSQL. This is the heart of the first problem.

Problem 1 — The PostgreSQL port conflict

If you have PostgreSQL installed locally on WSL2 — which is common on a dev machine — it's already listening on port 5432. docker compose up starts the PostgreSQL container and tries to bind 5432:5432: immediate conflict.

Error response from daemon: driver failed programming external connectivity on endpoint db:
Bind for 0.0.0.0:5432 failed: port is already allocated

Fix: map to 5433 on the host side (5433:5432 in docker-compose.yml). The container keeps listening on 5432 internally — other Docker services reach it without changing their config. The DATABASE_URL variable points to db:5432, not to the host. Only the port exposed to the host changes.

To connect from the host (DBeaver, psql): localhost:5433. That's all.

Problem 2 — Docker group permissions under WSL2

After installing Docker Engine (not Docker Desktop):

sudo apt install docker.io
sudo usermod -aG docker $USER

Instinct: run docker ps. Result:

permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock

The reason: usermod -aG docker $USER modifies the group for new sessions, not the current one. Two solutions:

# Option 1: activate the group in the current session (temporary)
newgrp docker

# Option 2: fully restart WSL2 (permanent)
# In Windows PowerShell:
wsl --shutdown
# Then relaunch WSL2

newgrp docker opens a subshell with the new group. It works, but only for the current terminal. wsl --shutdown is the permanent fix — WSL2 restarts with groups correctly applied.

Problem 3 — Docker daemon not started when WSL2 launches

WSL2 doesn't start systemd by default (depending on the distro). The Docker daemon doesn't run automatically at startup. First Docker command of the morning:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

Two solutions:

# Option 1: start manually each time
sudo service docker start

# Option 2: enable systemd in WSL2 (Ubuntu 22.04+)
# In /etc/wsl.conf:
[boot]
systemd=true

With systemd=true, Docker starts automatically as a system service. This is the clean solution if your distro supports it. After modifying /etc/wsl.conf, run wsl --shutdown from PowerShell for the change to take effect.

Apache vs Nginx in Docker

Deliberate choice of Apache over Nginx for the app container. Main reason: familiarity with Apache config for Symfony (standard .htaccess, mod_rewrite enabled). Nginx is often recommended for prod performance, but in dev the difference is zero and the extra configuration cost isn't justified.

The Dockerfile for Symfony + Apache:

FROM php:8.3-apache

RUN apt-get update && apt-get install -y \
    git zip unzip libpq-dev \
    && docker-php-ext-install pdo pdo_pgsql \
    && a2enmod rewrite

COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

WORKDIR /var/www/html
COPY . .

RUN composer install --no-dev --optimize-autoloader

RUN chown -R www-data:www-data var/

The pdo_pgsql extension is essential — without it, Doctrine throws an exception on the first call. a2enmod rewrite enables the Apache module so that Symfony's router works. The final chown prevents permission errors on the cache and logs.

The Makefile as a single interface

With Docker, commands get long. A Makefile at the root fixes that:

up:
    docker compose up -d

down:
    docker compose down

shell:
    docker compose exec app bash

console:
    docker compose exec app php bin/console $(cmd)

migrate:
    docker compose exec app php bin/console doctrine:migrations:migrate --no-interaction

Usage: make up, make shell, make console cmd="cache:clear". Everyone on the project uses the same commands without knowing the exact Docker syntax. And new team members have a documented entry point without having to read the entire docker-compose.yml.

Conclusion

The 3 problems — port conflict, group permissions, daemon startup — are independent but all show up on day one. None of them are documented together in official Docker guides for WSL2. By solving them cleanly once (5433 for PG, wsl --shutdown, systemd=true), the setup becomes stable and reproducible.

The rest — Symfony, PostgreSQL, Redis — works just like any standard Docker stack. The problem wasn't Docker, it was the WSL2 environment underneath.

📄 Associated CLAUDE.md

View • Download • Catalogue

PHP async: event loop, Fibers and the limits of single-threading

Odilon HUGONNOT — Wed, 13 May 2026 09:00:01 +0000

A colleague asks: "Can PHP do what Node.js does — jump between tasks on a single thread?" Short answer: yes. Long answer: it's more subtle than that, and the distinction between concurrency and parallelism changes everything.

PHP has a reputation for being sequential and blocking. That's true in the classic Apache + PHP-FPM model. But it's far from inevitable — understanding why it blocks is the first step toward knowing when and how to stop letting it.

The blocking model of PHP-FPM

In PHP-FPM, each HTTP request is handled by an isolated worker. That worker is single-threaded: operations execute one after another, in order. Nothing can happen concurrently within the same process.

Concretely, if your handler makes three HTTP calls to external APIs, they chain sequentially:

t=0ms   → call API users    (200ms waiting on network)
t=200ms → call API orders   (200ms waiting on network)
t=400ms → call API products (200ms waiting on network)
t=600ms → response sent back to client

600 ms. For 580 of those 600 ms, the thread does nothing — it's waiting on network responses. The CPU is idle, but the thread is blocked on I/O. That's where async becomes interesting: that waiting time can be used to make progress on other tasks.

PHP CLI follows the same model: a single thread, sequential execution. The difference from PHP-FPM is that a script can run for a long time — which makes the event loop viable, since you have a persistent process capable of running an event loop.

The event loop: cooperative concurrency

The event loop principle is straightforward: instead of blocking the thread waiting for an I/O response, you register a callback that will be called when the response arrives, then move on to the next task. The thread never sleeps — it loops checking which events are ready to be handled.

ReactPHP is the library that implements this model in PHP. The simplest example to understand the mechanics:

$loop = React\EventLoop\Factory::create();

$loop->addTimer(1, function () { echo "Task A\n"; });
$loop->addTimer(2, function () { echo "Task B\n"; });

$loop->run();

A single thread. Both timers run in the same loop. While waiting for the first second, nothing blocks the thread — the event loop can handle other events in the meantime. This is cooperative concurrency: tasks voluntarily share the thread by yielding control when they wait.

The concrete case that justifies the investment: three HTTP calls in parallel instead of sequential. With React\Http\Browser:

$loop    = React\EventLoop\Factory::create();
$browser = new React\Http\Browser($loop);

$promises = [
    $browser->get('https://api.example.com/users'),
    $browser->get('https://api.example.com/orders'),
    $browser->get('https://api.example.com/products'),
];

React\Promise\all($promises)->then(function (array $responses) {
    foreach ($responses as $response) {
        echo $response->getBody() . "\n";
    }
});

$loop->run();

All three requests are fired simultaneously. The event loop waits for responses and processes each callback as a response arrives. Result: ~200 ms instead of 600 ms. The gain comes entirely from overlapping network wait time — no CPU parallelism, no additional threads.

PHP 8.1 Fibers: native cooperative multitasking

Fibers, introduced in PHP 8.1, are a low-level mechanism for cooperative multitasking. A Fiber can suspend its execution and hand control back to the caller, which can decide to resume the Fiber later with a value.

$fiber = new Fiber(function (): void {
    $value = Fiber::suspend('first suspension');
    echo "Resumed with: " . $value . "\n";
});

$value = $fiber->start();          // starts the Fiber, receives the suspended value
echo "Suspended with: " . $value . "\n";
$fiber->resume('hello');            // resumes the Fiber with a value

Which outputs:

Suspended with: first suspension
Resumed with: hello

A Fiber is essentially a pausable execution context. It doesn't run in parallel with the main code — it explicitly yields control via Fiber::suspend(). That's the heart of cooperative multitasking: each Fiber is responsible for knowing when to yield.

Fibers alone aren't enough to build a usable async system. You need a scheduler that manages the list of active Fibers, resumes those that can make progress, and integrates an event loop for I/O operations. That's what Amphp v3 provides. With Amp, writing async code looks like synchronous code:

use Amp\Http\Client\HttpClientBuilder;

$client = HttpClientBuilder::buildDefault();

// These three calls are launched concurrently,
// but the code reads as if it were sequential
$responses = Amp\Future\awaitAll([
    async(fn() => $client->request(new Request('https://api.example.com/users'))),
    async(fn() => $client->request(new Request('https://api.example.com/orders'))),
    async(fn() => $client->request(new Request('https://api.example.com/products'))),
]);

Readability is Amp's main argument over ReactPHP: no callback chains, no manual promise management. The scheduler handles Fiber suspension and resumption behind the scenes.

What async doesn't solve

Async only solves the problem of time wasted waiting on I/O. If the task is CPU-bound — cryptographic computation, image processing, heavy parsing — there's nothing to gain. The thread is running at 100 %, and suspending the Fiber just delays the work without letting another task execute in the meantime.

The concrete distinction: an HTTP call that takes 200 ms is 199 ms of waiting during which the CPU is free. A bcrypt hash that takes 200 ms is 200 ms of CPU at full load. The event loop helps in the first case, not the second.

The database case is more nuanced. PDO, PHP's default driver, is entirely blocking: a SQL query blocks the thread until the response. With ReactPHP or Amp, using PDO inside a Fiber cancels all the benefit — the Fiber blocks like classic synchronous code. You need native async drivers: amphp/mysql or amphp/postgres for PostgreSQL. Adoption of these drivers is still limited, which makes the Amp + PostgreSQL stack less natural than its Node.js equivalent.

Another limit not to underestimate: synchronous PHP extensions. If a third-party library internally calls a blocking network function (curl without async, some SDKs), the entire loop freezes during that call. The event loop can't do anything against blocking code it doesn't control.

True parallelism: when the event loop isn't enough

When the bottleneck is pure computation rather than I/O waiting, or when you genuinely need multiple CPU threads, PHP has other options — less elegant, but functional.

pcntl_fork — available in PHP CLI, creates a child process that inherits the parent context. Simple for parallelising independent tasks, but watch shared resource management (DB connections, files):

$pid = pcntl_fork();

if ($pid === 0) {
    // Child process
    processHeavyTask();
    exit(0);
} else {
    // Parent process continues
    doOtherWork();
    pcntl_waitpid($pid, $status); // wait for child to finish
}

ext-parallel — a PECL extension that exposes real PHP threads with controlled memory sharing. Cleaner than fork for CPU-bound tasks, but the extension isn't available on all installations and its API surface is limited (only stateless functions can be sent to a thread).

External workers — the most pragmatic solution in production: delegate heavy work to a queue (Redis, RabbitMQ, Beanstalkd) consumed by separate PHP-FPM workers. Symfony Messenger handles this cleanly. The web application stays responsive, heavy tasks execute outside the request/response cycle.

Horizontal scaling of PHP-FPM itself is also a valid answer: multiple workers handle multiple requests in parallel — not in the same thread, but in separate processes managed by the FPM pool. That's the default production model, and for most web applications, it's enough.

Conclusion

PHP can do cooperative concurrency. ReactPHP and Amp have been proving it in production for years. Fibers in PHP 8.1 finally gave a clean native primitive for building schedulers, and Amp v3 makes excellent use of them.

But the answer to "should you go async in PHP?" depends entirely on the problem. If the bottleneck is waiting on network responses in a long-running CLI script — yes, ReactPHP or Amp make sense. If it's a classic web API with a few SQL queries — PHP-FPM with multiple workers, maybe a Redis cache, solves the problem without adding the complexity of an event loop.

What's certain: the argument "PHP can't do async" is wrong. The argument "PHP with an event loop fits all Node.js use cases" is equally wrong. As usual, the nuance is in the load model, not the language.

Bilingual FR/EN blog in pure PHP: architecture without framework or database

Odilon HUGONNOT — Tue, 12 May 2026 09:00:04 +0000

This blog was built in pure PHP, no CMS, no database. First article in the series, already published. At some point the question comes up: is it worth adding English support? Short answer: yes, and it's less complicated than it looks. Long answer: here's how I did it, with the traps that come with it.

No gettext, no i18n library, no database for translations. Just separate PHP files per language, a restructured JSON file, and three layers of routing. The whole thing fits in a few dozen lines of code spread across files you already have.

Why translate a developer blog

Two concrete reasons, no philosophy.

The English-speaking SEO market is 10 to 50 times larger. A query like "php blog without framework" has a search volume that has nothing to do with the French equivalent. If you write about technical topics that interest English-speaking developers — and you probably do if you're reading this — not having an EN version means missing an existing audience without the overhead being that large once the architecture is in place.

It shows recruiters you're bilingual. A portfolio available in English, with properly written technical content, is a strong signal. No need to mention it in your CV — the site speaks for itself. An international recruiter who lands on your article via Google EN immediately sees that you can work in English.

There's a third reason that's not easy to admit but real: writing the same article in two languages forces you to restructure explanations. It often improves the original version in the process.

Architecture decisions

URL structure

The main constraint: don't break existing URLs. All already-published articles live at /blog/slug. These URLs don't move. English versions live at /en/blog/slug.

/blog/blog-multilingue-php-sans-framework      # FR (default)
/en/blog/blog-multilingue-php-sans-framework   # EN

The /en/ prefix is simple to detect, to generate in links, and to route server-side. No ?lang=en parameter, no cookie, no automatic browser language detection — the URL is the source of truth. This is the only model that works correctly for SEO (search engines index distinct URLs) and respects the principle of least surprise for the user.

One PHP file per language

For each article, two files:

blog/posts/
├── my-slug.php       # French version
└── my-slug.en.php    # English version

The alternative — a single file with translation arrays — looks like this in real life:

<?php
$texts = [
    'fr' => [
        'intro' => 'Ce blog a été construit en PHP pur...',
        'section1' => 'Les choix d\'architecture...',
        // 800 lines of content inside quotes with escaping everywhere
    ],
    'en' => [
        'intro' => 'This blog was built in pure PHP...',
        // 800 more lines
    ],
];
echo $texts[$lang]['intro'];

It's unreadable, unmaintainable, and you spend half your time managing apostrophes and quotes. One file per language is more verbose in terms of file count, but each file is simple to read and modify independently. That's the right trade-off for a blog.

Bonus: if an article doesn't have an English version, the .en.php file simply doesn't exist. The router returns a clean 404. No complex fallback logic needed.

Restructured posts.json

Before adding multilingual support, the JSON was flat:

{
  "slug": "my-slug",
  "date": "2026-03-15",
  "title": "Article title",
  "category": "Lessons learned",
  "tags": ["php", "blog"],
  "excerpt": "Short summary."
}

After migration, language-dependent fields are nested inside fr and en objects:

{
  "slug": "my-slug",
  "date": "2026-03-15",
  "fr": {
    "title": "Titre de l'article",
    "category": "Retour d'expérience",
    "tags": ["php", "blog"],
    "excerpt": "Résumé court."
  },
  "en": {
    "title": "Article title",
    "category": "Lessons learned",
    "tags": ["php", "blog"],
    "excerpt": "Short summary."
  }
}

The date stays at root level — it's language-independent. So is the slug — it's the same for both versions.

Migrating existing data is done with a one-shot PHP script (see below). Don't do it by hand for 30+ articles.

template.php receives $lang

The blog_header() signature already had a $lang parameter set up but unused. It becomes functional:

<?php
function blog_header(
    string $title,
    string $description,
    string $canonical_url,
    ?string $og_image = null,
    ?array $article_data = null,
    string $lang = 'fr'
): void {

This parameter drives: the lang attribute on <html>, og:locale, hreflang tags, breadcrumbs, navigation, and the language toggle. One parameter, no global variable.

The three routing layers

The routing architecture is the trickiest part. It has three layers that must stay consistent with each other, otherwise you end up with a site that works in production but not in development, or vice versa.

Layer 1: .htaccess for Apache

The clean FR blog URLs already existed in .htaccess. The EN addition comes down to two lines:

# Blog EN: /en/blog/slug → blog/posts/slug.en.php
RewriteRule ^en/blog/([a-z0-9-]+)/?$ blog/posts/$1.en.php [L,QSA]

# Blog listing EN: /en/blog/ → blog/index.php with lang=en
RewriteRule ^en/blog/?$ blog/index.php?lang=en [L,QSA]

Two rules. That's it. The existing routing already handles FR URLs. The EN article rule must be added before the FR rules to avoid pattern conflicts — Apache rules apply in declaration order.

Layer 2: router.php for the built-in PHP server

The built-in PHP server (php -S localhost:8000 router.php) doesn't execute .htaccess files. The router.php simulates the same rewrites:

<?php
$uri = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
$uri = rtrim($uri, '/');

// EN blog articles
if (preg_match('#^/en/blog/([a-z0-9-]+)$#', $uri, $m)) {
    $file = __DIR__ . '/blog/posts/' . $m[1] . '.en.php';
    if (file_exists($file)) {
        require $file;
        return true;
    }
    // Fallback 404
    http_response_code(404);
    require __DIR__ . '/404.php';
    return true;
}

// EN blog listing
if ($uri === '/en/blog') {
    $_GET['lang'] = 'en';
    require __DIR__ . '/blog/index.php';
    return true;
}

The structure is identical to the Apache logic, translated to PHP. The classic trap here: forgetting to set $_GET['lang'] = 'en' before including index.php. If you test locally and the EN listing displays FR articles, that's where the bug lives.

Layer 3: detection in template.php

The template can receive $lang as a parameter (from articles), but it can also detect the language from the URL (for dynamic pages that don't go through blog_header()):

<?php
// Language detection from URL (fallback if $lang not provided)
function detect_lang(): string {
    $uri = $_SERVER['REQUEST_URI'] ?? '';
    return str_starts_with($uri, '/en/') ? 'en' : 'fr';
}

In practice, articles always pass $lang explicitly. Automatic detection primarily serves the listing and pages that don't have article context.

Template changes

html lang and og:locale

The most visible and simplest change:

<!DOCTYPE html>
<html lang="<?= $lang ?>">
<head>
    ...
    <meta property="og:locale" content="<?= $lang === 'en' ? 'en_US' : 'fr_FR' ?>">

hreflang tags

The hreflang tags tell search engines about alternative versions of a page. They go in the <head> and are generated from the article slug:

<?php if (!empty($article_data['slug'])): ?>
<link rel="alternate" hreflang="fr"
      href="<?= SITE_URL ?>/blog/<?= $article_data['slug'] ?>">
<link rel="alternate" hreflang="en"
      href="<?= SITE_URL ?>/en/blog/<?= $article_data['slug'] ?>">
<link rel="alternate" hreflang="x-default"
      href="<?= SITE_URL ?>/blog/<?= $article_data['slug'] ?>">
<?php endif; ?>

x-default points to the FR version — that's the site's default language. If a user arrives from a country without a localized version, they see FR. Google uses x-default for pages not geographically targeted.

Important: these tags must be reciprocal. The FR page must point to the EN page, and the EN page must point to the FR page. If you miss one direction, Google ignores both.

Adapted breadcrumbs

The breadcrumb changes depending on language — not just the text, but also the URLs:

<?php
$home_url   = $lang === 'en' ? SITE_URL . '/en' : SITE_URL;
$blog_url   = $lang === 'en' ? SITE_URL . '/en/blog' : SITE_URL . '/blog';
$home_label = $lang === 'en' ? 'Home' : 'Accueil';
$blog_label = 'Blog';
?>
<ol class="breadcrumb">
    <li><a href="<?= $home_url ?>"><?= $home_label ?></a></li>
    <li><a href="<?= $blog_url ?>"><?= $blog_label ?></a></li>
    <li class="active"><?= htmlspecialchars($title) ?></li>
</ol>

Language toggle with SVG flags

The navigation toggle shows the flag for the target language (not the current language — the other one). This avoids the paradox of "FR" displayed on a page already in French.

<?php
$toggle_url  = $lang === 'fr'
    ? SITE_URL . '/en/blog/' . ($article_data['slug'] ?? '')
    : SITE_URL . '/blog/'    . ($article_data['slug'] ?? '');
$toggle_lang = $lang === 'fr' ? 'EN' : 'FR';
$toggle_flag = $lang === 'fr' ? '🇬🇧' : '🇫🇷';
// Or SVG inline if emoji rendering is inconsistent
?>
<a href="<?= htmlspecialchars($toggle_url) ?>" class="lang-toggle"
   title="<?= $lang === 'fr' ? 'Read in English' : 'Lire en français' ?>">
    <?= $toggle_flag ?> <?= $toggle_lang ?>
</a>

If you prefer inline SVGs instead of emoji (more reliable on older OS/browsers), here's a compact example:

<?php if ($lang === 'fr'): ?>
<a href="<?= $toggle_url ?>" class="lang-toggle" title="Read in English">
    <svg width="18" height="12" viewBox="0 0 60 40" xmlns="http://www.w3.org/2000/svg">
        <rect width="60" height="40" fill="#012169"/>
        <path d="M0,0 L60,40 M60,0 L0,40" stroke="#fff" stroke-width="8"/>
        <path d="M0,0 L60,40 M60,0 L0,40" stroke="#C8102E" stroke-width="5"/>
        <path d="M30,0 V40 M0,20 H60" stroke="#fff" stroke-width="12"/>
        <path d="M30,0 V40 M0,20 H60" stroke="#C8102E" stroke-width="8"/>
    </svg>
    EN
</a>
<?php else: ?>
<a href="<?= $toggle_url ?>" class="lang-toggle" title="Lire en français">
    <svg width="18" height="12" viewBox="0 0 90 60" xmlns="http://www.w3.org/2000/svg">
        <rect width="30" height="60" fill="#002395"/>
        <rect x="30" width="30" height="60" fill="#EDEDED"/>
        <rect x="60" width="30" height="60" fill="#ED2939"/>
    </svg>
    FR
</a>
<?php endif; ?>

Migrating posts.json: the one-shot script

If you have existing articles with the flat structure, here's the migration script. Run it once from the project root:

<?php
// migrate-posts.php — delete after use
$json = file_get_contents('blog/posts.json');
$posts = json_decode($json, true);

$migrated = [];
foreach ($posts as $post) {
    // Already migrated?
    if (isset($post['fr'])) {
        $migrated[] = $post;
        continue;
    }

    $migrated[] = [
        'slug' => $post['slug'],
        'date' => $post['date'],
        'fr'   => [
            'title'    => $post['title'],
            'category' => $post['category'],
            'tags'     => $post['tags'],
            'excerpt'  => $post['excerpt'],
        ],
        'en'   => [
            'title'    => $post['title'],    // Translate manually
            'category' => $post['category'], // idem
            'tags'     => $post['tags'],
            'excerpt'  => $post['excerpt'],  // idem
        ],
    ];
}

file_put_contents(
    'blog/posts.json',
    json_encode($migrated, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES)
);
echo count($migrated) . " articles migrated.\n";

The script copies FR fields into EN as placeholders. You then rework the EN fields manually. Don't forget to delete migrate-posts.php after you're done — it's not an endpoint you want exposed in production.

Blog listing (index.php)

The listing reads posts.json in JavaScript and filters articles by current language. Two main changes.

Reading the current language

// Determine language from URL
const BLOG_LANG = window.location.pathname.startsWith('/en/') ? 'en' : 'fr';

Fetch with absolute path

This is the most common trap. Using a relative path to fetch posts.json:

// ❌ Relative path — PROBLEM on /en/blog/
fetch('posts.json')
  .then(r => r.json())

On /blog/, this fetch resolves to /blog/posts.json — correct. But on /en/blog/, it resolves to /en/blog/posts.json — 404. The file only exists in one place.

// ✅ Absolute path — works from any URL
fetch('/blog/posts.json')
  .then(r => r.json())
  .then(posts => renderPosts(posts, BLOG_LANG));

This was the first bug I hit after deploying the EN listing. Everything worked locally (router.php serves from the root, so relative paths happened to resolve correctly), but broke immediately on the real URL structure. Absolute paths are the only correct answer here.

Language filter in JS

function renderPosts(posts, lang) {
    // Filter articles that have a version in this language
    const filtered = posts.filter(post => post[lang] && post[lang].title);

    filtered.forEach(post => {
        const data = post[lang];
        const url  = lang === 'en'
            ? `/en/blog/${post.slug}`
            : `/blog/${post.slug}`;

        // Build card with data.title, data.excerpt, data.category, data.tags
        renderCard({ ...data, slug: post.slug, date: post.date, url });
    });
}

This means an article without an EN version simply doesn't appear in the EN listing. That's the correct behaviour — it's not a missing feature, it's the expected result of having a .en.php file as the gating condition.

Category filter translation

Category filter buttons change label depending on language. The FR → EN mapping is a simple constant:

// Categories are read dynamically from posts.json
// The labels come from the nested lang object, so no mapping needed:
// post.fr.category = "Retour d'expérience"
// post.en.category = "Lessons learned"
// They're already translated at the data level.

const categories = [...new Set(
    posts
        .filter(p => p[BLOG_LANG])
        .map(p => p[BLOG_LANG].category)
)].sort();

// Dynamically build filter buttons — no hardcoded list
categories.forEach(cat => {
    const btn = document.createElement('button');
    btn.className = 'btn-category';
    btn.dataset.category = cat;
    btn.textContent = cat;
    filterContainer.appendChild(btn);
});

Because category names are stored in posts.json per language, the buttons are already translated at the data level. No extra mapping layer needed.

Sitemap with hreflang

The XML sitemap must declare alternative URLs for each bilingual page. The xhtml namespace is required for xhtml:link tags:

<?php
$posts = json_decode(file_get_contents(__DIR__ . '/posts.json'), true);
header('Content-Type: application/xml; charset=utf-8');
echo '<?xml version="1.0" encoding="UTF-8"?>' . "\n";
?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
<?php foreach ($posts as $post): ?>
    <?php if (!empty($post['fr'])): ?>
    <url>
        <loc><?= SITE_URL ?>/blog/<?= $post['slug'] ?></loc>
        <lastmod><?= $post['date'] ?></lastmod>
        <changefreq>monthly</changefreq>
        <priority>0.8</priority>
        <xhtml:link rel="alternate" hreflang="fr"
                    href="<?= SITE_URL ?>/blog/<?= $post['slug'] ?>"/>
        <?php if (!empty($post['en'])): ?>
        <xhtml:link rel="alternate" hreflang="en"
                    href="<?= SITE_URL ?>/en/blog/<?= $post['slug'] ?>"/>
        <xhtml:link rel="alternate" hreflang="x-default"
                    href="<?= SITE_URL ?>/blog/<?= $post['slug'] ?>"/>
        <?php endif; ?>
    </url>
    <?php endif; ?>
    <?php if (!empty($post['en'])): ?>
    <url>
        <loc><?= SITE_URL ?>/en/blog/<?= $post['slug'] ?></loc>
        <lastmod><?= $post['date'] ?></lastmod>
        <changefreq>monthly</changefreq>
        <priority>0.7</priority>
        <xhtml:link rel="alternate" hreflang="fr"
                    href="<?= SITE_URL ?>/blog/<?= $post['slug'] ?>"/>
        <xhtml:link rel="alternate" hreflang="en"
                    href="<?= SITE_URL ?>/en/blog/<?= $post['slug'] ?>"/>
        <xhtml:link rel="alternate" hreflang="x-default"
                    href="<?= SITE_URL ?>/blog/<?= $post['slug'] ?>"/>
    </url>
    <?php endif; ?>
<?php endforeach; ?>
</urlset>

EN article priority (0.7) is slightly lower than FR articles (0.8) — the site defaults to French, FR articles are the source of truth. It's a convention, not a strict rule.

What you don't need

List of things I considered and decided against:

An i18n library (gettext, Symfony Translation, etc.) — For a blog, interface strings fit on two hands: "Read more", "Home", "min read". Two ternary operators in the template is sufficient. An i18n library with .po or .yaml files would be pure over-engineering.
Automatic language detection — Detecting Accept-Language and redirecting automatically is a bad idea. It breaks link sharing, surprises users, and causes indexation problems. The URL is the source of truth.
Database for translations — If your content is PHP files, your translations are PHP files. Architectural consistency has value in itself.
A single file with switch($lang) — Covered above. Unreadable once articles go past 200 lines.
Automatic translation (DeepL API, etc.) — Technically possible. But a technically dense blog article translated automatically is obvious to any developer. And it doesn't convince a recruiter that you can work in English. If the goal is demonstrating bilingualism, you actually have to write in English.

Summary of changed files

For an already-running blog, the exhaustive list of changes:

.htaccess — 2 RewriteRule lines for EN URLs
router.php — 2 corresponding PHP routing blocks
blog/template.php — blog_header() uses $lang for html[lang], og:locale, hreflang, breadcrumbs, nav, toggle; blog_footer() receives $lang to filter related articles
blog/posts.json — migrated to nested fr/en structure (one-shot script)
blog/index.php — absolute fetch /blog/posts.json, BLOG_LANG detection from URL, language filter, adapted URLs
blog/sitemap.php — added xhtml namespace and xhtml:link tags
For each existing article: blog/posts/slug.en.php to create

No new configuration files, no new dependencies, no stack change. All modifications are localized in files you're already maintaining.

In practice

This blog has been running with this architecture since the restructuring. Existing FR URLs haven't moved — no redirects to manage, no impact on already-indexed articles' rankings. EN versions are indexable as soon as they're created.

The only real cost is writing time: translating a 1000-word article takes between 30 minutes and an hour depending on technical density. That's the cost that can't be compressed — not the architecture.

If you already have a PHP blog without a framework and you're hesitating to add bilingual support because you think it's complex: the code isn't the hard part.

PHP blog SEO: JSON-LD, ToC and crawlable pagination

Odilon HUGONNOT — Mon, 11 May 2026 09:00:03 +0000

Google Search Console showed zero indexed articles after three weeks of publishing. The articles existed. The URLs returned 200. The sitemap had been submitted. The problem was elsewhere: the blog listing loaded posts.json via fetch(), then rendered all the HTML in JavaScript. As far as Googlebot was concerned, the page was an empty shell with a spinner.

What follows is the set of fixes applied to the shared PHP template — no framework, no build step, plain Apache. Each point has a concrete reason, not just "SEO best practices say so".

The JS-first problem

Googlebot can execute JavaScript. Google has been saying this for years, and it's true. But "can" doesn't mean "systematically" or "immediately". JS crawling goes through a secondary rendering queue — plain HTML pages are indexed first. The result: a fully JS-rendered blog can take weeks to get indexed, and even then, only if Googlebot decides the page is worth the rendering cost.

The second problem is structural: if pagination is handled entirely in JS (click "Page 2" → client-side re-render), page 2 doesn't exist from a crawler's perspective. There's only one URL, and it always shows the first 10 articles. Googlebot doesn't click JavaScript buttons to see more content. Articles on page 3 or 4 will never be crawled.

The fix is straightforward in principle: the server must render the HTML for articles on the current page. JavaScript can then take over for interactive navigation — but the first render must be visible in the page source.

JSON-LD and articleBody: what Google actually wants

Schema.org BlogPosting is the baseline structured data for a blog article. It lets Google display the date, author, and potentially the breadcrumb in rich results. But the most useful field is articleBody: it's the plain text of the article, which Google uses for featured snippets.

The problem: when JSON-LD is generated inside blog_header() (at the top of the page), the article content hasn't been rendered yet. You can't inject articleBody at that point.

The solution is PHP output buffering. In blog_header(), start a buffer and put a placeholder in the JSON-LD:

ob_start();
// JSON-LD with placeholder
$json_ld = '{ "@type": "BlogPosting", "articleBody": "ARTICLE_BODY_PLACEHOLDER", ... }';

Then in blog_footer(), retrieve the full rendered HTML, extract the content of the .article-content div, strip the tags, and inject the text in place of the placeholder before sending everything to the browser:

// In blog_footer() — capture the HTML rendered by the article
$article_html = ob_get_clean();

if (preg_match('/

The complete JSON-LD is injected into <head> just before the buffer is sent. Google sees a real articleBody, not a placeholder. The 5000-character limit is arbitrary — Google truncates anyway.

Server-side ToC and the iconv trap

A server-side table of contents has two advantages: it's visible in the page source (therefore crawlable), and it has no JavaScript dependency. The implementation is straightforward — parse the <h2> and <h3> tags from the article HTML, generate anchors, and inject the ToC at the beginning of .article-content.

The classic trap is generating anchor IDs for headings with accented characters. The standard reflex is to use iconv for transliteration:

// ❌ Depends on system locale — returns empty string on servers without fr_FR.UTF-8
$id = preg_replace('/[^a-z0-9]+/', '-', strtolower(iconv('UTF-8', 'ASCII//TRANSLIT', $heading_text)));

On a server where the fr_FR.UTF-8 locale isn't installed, iconv with //TRANSLIT returns an empty string for accented characters. The generated anchor becomes #--- instead of #les-3-pieges. The ToC link points to nothing.

The fix is an explicit mapping with strtr():

// ✅ Explicit mapping, portable
$id = preg_replace('/[^a-z0-9]+/', '-', strtolower(strtr($heading_text, [
    'à'=>'a','â'=>'a','é'=>'e','è'=>'e','ê'=>'e','ë'=>'e',
    'î'=>'i','ï'=>'i','ô'=>'o','ù'=>'u','û'=>'u','ü'=>'u',
    'ç'=>'c','æ'=>'ae','œ'=>'oe',
])));

No locale dependency. No unpredictable behavior between dev and production. The same heading always generates the same ID. The same pattern is applied both to the <h2> IDs in the article body and to the links in the ToC — consistency guaranteed.

Crawlable pagination: the hybrid approach

The goal is for Googlebot to reach every article, not just those on the first page. The constraint: don't break the existing interactive navigation (search, category filters, click-through pagination).

The hybrid solution: PHP loads posts.json and renders the cards for the current page (determined by the ?page=N query parameter). JavaScript keeps its search and filter functions, but detects whether PHP has already rendered content on initial load — and if so, skips the re-render.

<?php foreach ($page_posts as $post):
    $meta = $post[$lang];
    $url = $base_url . $post['slug'];
?>
<article class="blog-card" data-slug="<?= htmlspecialchars($post['slug']) ?>">
    <h2 class="blog-card-title">
        <a href="<?= htmlspecialchars($url) ?>"><?= htmlspecialchars($meta['title']) ?></a>
    </h2>
    ...
</article>
<?php endforeach; ?>

Pagination links are real <a href="?page=2"> elements, with a data-page attribute so JavaScript can intercept them:

document.querySelectorAll('a[data-page]').forEach(function(link) {
    link.addEventListener('click', function(e) {
        e.preventDefault();
        currentPage = parseInt(this.dataset.page);
        render(filterPosts());
        window.history.pushState({}, '', '?page=' + currentPage);
    });
});

To prevent JS from re-rendering cards that PHP just rendered, add a guard at initial load:

// If no active filter and PHP already rendered articles, skip re-render
var hasPhpContent = document.querySelector('#posts-container article') !== null;
if (searchTerm || (activeCategory !== 'Tous' && activeCategory !== 'All') || !hasPhpContent) {
    render(filterPosts());
}

Googlebot crawls /blog/?page=2, sees the cards in plain HTML, follows the links to individual articles. JavaScript is no longer a prerequisite for indexation. For the user, nothing changes — navigation stays instant.

hreflang, canonical, og:type: the details that matter

These three are often treated as copy-paste boilerplate. Each has a specific purpose.

The canonical must point to the URL without a query string. Without it, /blog/my-article?page=1 and /blog/my-article are two distinct URLs as far as Google is concerned, and it doesn't know which one to index. One line is enough:

$canonical = strtok($current_url, '?');

The hreflang links tell Google that French and English versions of the same content exist. Without them, Google may decide to show the wrong version based on the visitor's language. The x-default is mandatory — it specifies which version to show when no locale matches (typically a Japanese user on a FR/EN blog):

<link rel="alternate" hreflang="fr" href="https://www.web-developpeur.com/blog/" />
<link rel="alternate" hreflang="en" href="https://www.web-developpeur.com/en/blog/" />
<link rel="alternate" hreflang="x-default" href="https://www.web-developpeur.com/blog/" />

The og:type should be article on article pages, and website on the listing and homepage. The distinction affects how Facebook and LinkedIn generate the share preview. og:locale is complementary — fr_FR vs en_US depending on the article language.

Conclusion

None of these changes required rethinking the blog's architecture. Everything lives in the shared PHP template, with a minor adjustment to the listing page JavaScript. No SSR framework, no build step, no dedicated CDN.

The most counter-intuitive part is the output buffering for articleBody: it's a technique from the early 2000s that neatly solves a sequencing problem between a template's header and footer. Same for the strtr() mapping — it's less "elegant" than iconv, but it's what actually works in production.

Two weeks after deploying these changes, Search Console was showing the first indexed articles. Not because Google had suddenly decided to crawl JavaScript better — but because the HTML was finally there, visible from the very first byte of the response.