fix: render customizer images through wordpress media

docs/runbook.md

@@ -35,6 +35,19 @@ HTTPS redirects during production startup.
 2. Run `docker compose --profile tools run --rm wp-cli -c 'wp theme status azionelab'`.
 3. Verify file ownership before changing permissions; never make the tree world-writable.
 
+## Uploaded image does not appear on the public page
+
+1. Confirm the image was selected in **Appearance > Customize**, not only uploaded in
+   **Media**. For the teacher portrait, use **Appearance > Customize > Il maestro >
+   Foto**, then publish the change.
+2. Hard-refresh the browser or purge the CDN cache. An NGINX log status `304` for
+   `/wp-content/uploads/...` is not an application error; it means the browser already
+   has a cached copy and NGINX did not resend the file body.
+3. If the upload appears in Media but not on the page, inspect the generated `<img>`
+   URL and verify it uses the public scheme/host configured by `WP_URL`.
+4. Confirm the uploaded file exists under `WORDPRESS_DATA_PATH/wp-content/uploads` and
+   is readable by the WordPress container user.
+
 ## A service cannot write to its volume
 
 1. Stop the affected service.

wordpress/theme/azionelab/front-page.php

@@ -25,7 +25,7 @@ $features = array(
                 </div>
             </div>
             <figure class="hero-visual">
-                <img src="<?php echo esc_url( $hero_image ); ?>" alt="Il gruppo durante un esercizio teatrale" width="960" height="1120" fetchpriority="high">
+                <?php echo azionelab_image( $hero_image, 'Il gruppo durante un esercizio teatrale', array( 'width' => '960', 'height' => '1120', 'fetchpriority' => 'high' ) ); ?>
                 <figcaption>Il gruppo è materia viva.</figcaption>
             </figure>
         </div>
@@ -57,7 +57,7 @@ $features = array(
 
     <section class="section section-sand" id="laboratorio" aria-labelledby="laboratory-title">
         <div class="container split-grid">
-            <div class="editorial-image"><img src="<?php echo esc_url( $laboratory_image ); ?>" alt="Esercizio di movimento nello spazio" width="960" height="760" loading="lazy"></div>
+            <div class="editorial-image"><?php echo azionelab_image( $laboratory_image, 'Esercizio di movimento nello spazio', array( 'width' => '960', 'height' => '760', 'loading' => 'lazy' ) ); ?></div>
             <div>
                 <p class="eyebrow">Pratica e ricerca</p>
                 <h2 id="laboratory-title"><?php echo esc_html( azionelab_mod( 'laboratory_title' ) ); ?></h2>
@@ -69,7 +69,7 @@ $features = array(
 
     <section class="section" id="maestro" aria-labelledby="teacher-title">
         <div class="container teacher-grid">
-            <div class="teacher-photo"><img src="<?php echo esc_url( $teacher_image ); ?>" alt="Ritratto di <?php echo esc_attr( azionelab_mod( 'teacher_name' ) ); ?>" width="760" height="900" loading="lazy"></div>
+            <div class="teacher-photo"><?php echo azionelab_image( $teacher_image, 'Ritratto di ' . azionelab_mod( 'teacher_name' ), array( 'width' => '760', 'height' => '900', 'loading' => 'lazy' ) ); ?></div>
             <div>
                 <p class="eyebrow">La guida del percorso</p>
                 <h2 id="teacher-title">Il maestro</h2>

wordpress/theme/azionelab/functions.php

@@ -45,6 +45,30 @@ function azionelab_asset( string $filename ): string {
     return get_theme_file_uri( 'assets/images/' . $filename );
 }
 
+function azionelab_image( string $url, string $alt, array $attributes = array() ): string {
+    $attributes = array_merge(
+        array(
+            'alt' => $alt,
+        ),
+        $attributes
+    );
+
+    $attachment_id = attachment_url_to_postid( $url );
+    if ( $attachment_id > 0 ) {
+        return wp_get_attachment_image( $attachment_id, 'large', false, $attributes ) ?: '';
+    }
+
+    $html_attributes = '';
+    foreach ( $attributes as $name => $value ) {
+        if ( '' === (string) $value ) {
+            continue;
+        }
+        $html_attributes .= sprintf( ' %s="%s"', esc_attr( $name ), esc_attr( (string) $value ) );
+    }
+
+    return sprintf( '<img src="%s"%s>', esc_url( $url ), $html_attributes );
+}
+
 function azionelab_phone_href( string $number ): string {
     return preg_replace( '/[^0-9+]/', '', $number ) ?: '';
 }