Media

Il modulo media serve al wordpress Gpci framework per potenziare e semplificare la gestione dei media oltre che a ottimizzare il rendering delle immagini nel frontend.

Funzionalità

Appena attivato il modulo media, automaticamente queste modifiche diventeranno subito attive:

sarà rimossa dal menu admin la sezione delle opzioni media in quanto sarà visibile una sezione molto più personalizzabile nel customizer
durante l'upload tutte le immagini jpeg o png saranno convertite a webp comprese di grandezze media. L'immagine originale non sarà in alcun modo modificata e sarà utilizzata come fallback nei browser senza supporto web
tutte le immagini nel frontend, oltre che diventare in formato webp, avranno aggiunta una query string con valore uguale al timestamp del file immagine src
il suffisso -scaled applicato nel frontend da wordpress sarà rimosso
la grandezza massima dell'attributo srcset sarà rimossa dal frontend
l'attributo srcset sarà rimosso dal frontend per i client che non supportano il formato webp
disabilita l'organizzazione dei media per data

Configurazione

Il modulo media mette a disposizione le seguenti globali php per la configurazione (sia la versione config che config_default):

Globale php	Scorciatoia corrispondente	Tipo di valore	Valore predefinito	Descrizione	Documentazione rilevante
`$GLOBALS['gpci']['config']['module']['media']['php']['upload']['actions']`		array di arrays	[]	Imposta le azioni da eseguire durante il caricamento media	- funzione php MediaAction

Azioni

Tramite la globale di configurazione $GLOBALS['gpci']['config']['module']['media']['php']['upload']['actions'] è possibile configurare azioni automatiche durante il caricamento dei media. La globale php contiene arrays di azioni che saranno eseguite nell'ordine specificato.

- info_file

Ritorna come errore le informazioni sul file caricato e previene il caricamento. Utile per debugging o per ottenere informazioni per configurare le altre azioni. Questa azione ferma il caricamento senza eseguire le successive. Esempio:

//ritorna informazioni sul media invece di caricarlo
$GLOBALS['gpci']['config']['module']['media']['php']['upload']['actions'][] = [ 'id'=>'info_file' ] ;

- info_request

Come sopra ma ritorna le informazioni sulla richiesta ajax corrente relativa al caricamento media. Anche questa azione ferma il caricamento senza eseguire le successive. Esempio:

$GLOBALS['gpci']['config']['module']['media']['php']['upload']['actions'][] = [ 'id'=>'info_request' ];

- block

Blocca il caricamento file. Potrebbe essere comodo a bloccare certi tipi di files completamente oppure in base a permessi o determinati flussi di lavoro. Può ospitare anche la chiave message per definire un messaggio personalizzato. Esempi:

//utilizzo base con messaggio predefinito (blocca tutti i caricamenti)
$GLOBALS['gpci']['config']['module']['media']['php']['upload']['actions'][] = [ 'id'=>'block' ];

//blocca i caricamenti di files webp e jpg con messaggi personalizzati
$GLOBALS['gpci']['config_default']['module']['media']['php']['upload']['actions'][] = [
  'id'          => 'block',
  'message'     => 'Estensioni webp e jpg non permesse!', 
  'conditions'	=> [
    ['file,extension,context'=>'jpg'],
    ['file,extension,context'=>'webp'],
    'operator'=>'OR',
  ]
];
//stessa cosa (con possibilità di separare i messaggi) di:
$GLOBALS['gpci']['config']['module']['media']['php']['upload']['actions'][] = [ 'id'=>'block', 'message'=>'I files con estensione webp non sono permessi!', 'conditions'=>['file,extension,context'=>'webp'] ];
$GLOBALS['gpci']['config']['module']['media']['php']['upload']['actions'][] = [ 'id'=>'block', 'message'=>'I files con estensione jpg non sono permessi!', 'conditions'=>['file,extension,context'=>'jpg'] ];

- convert

Modifica il file caricato esattamente come da funzione FileAction (azione convert). Esempio:

//ridimensiona un'immagine a un massimo di 100x100px
$GLOBALS['gpci']['config_default']['module']['media']['php']['upload']['actions'][] = [ 'id'=>'convert', 'width'=>100, 'height'=>100 ];

- rename

Rinomina il file caricato esattamente come da funzione FileAction (azione rename). Esempi:

//rinomina il file caricato con un nome statico
$GLOBALS['gpci']['config_default']['module']['media']['php']['upload']['actions'][] = [ 'id'=>'rename', 'name'=>'nuovo_nome' ];

//rinomina il file caricato come il titolo della pagina corrente (se caricato da un post)
/$GLOBALS['gpci']['config_default']['module']['media']['php']['upload']['actions'][] = [ 'id'=>'rename', 'name'=>'wp,title,id' ];

- upload_dir

Modifica la cartella di caricamento del media, è possibile utilizzare come valore un percorso semplificato. Esempi:

//Carica il file alla cartella root del sito/cartella_personalizzata
$GLOBALS['gpci']['config_default']['module']['media']['php']['upload']['actions'][] = [ 'id'=>'upload_dir', 'dir'=>'site_root/cartella_personalizzata' ];

Altra documentazione rilevante

funzione php HookAction (azione set_upload_dir)

- update

Modifica il media caricato esattamente come da funzione MediaAction (azione update), quindi i dati salvati nel database. Nei valori è possibile utilizzare la conversione dinamica come stringa. Esempi:

//Modifica alcuni attributi con testi semplici
$GLOBALS['gpci']['default']['module']['media']['php']['upload']['actions'][] = [
  'id'=>'update', 'alt'=>'attributo alt', 'title'=>'Nuovo titolo', 'description'=>'Descrizione' ]
];

//Modifica attributo con una conversione dinamica
$GLOBALS['gpci']['default']['module']['media']['php']['upload']['actions'][] = [
  'id'=>'update', 'alt'=>'function,nome_funzione' ]
];
//funzione php
function nome_funzione(){
  $data = GetField('campo_personalizzato_data');
  return "Data evento: $data";
}

Altra documentazione rilevante

lista mime types

Customizer

Nel customizer sarà aggiunto un nuovo pannello media da configurare il prima possibile, al cui interno è presente la seguente sezione:

Grandezze

In questa sezione è possibile configurare le grandezze media, Il risultato sarà la mappatura di vari hook ma soprattutto della funzione add_image_size (in caso che lo slug non sia uno di quelli del core), in caso contrario (quindi se lo slug è uno tra: thumbnail, medium, medium_large, large, 1536x1536, 2048x2048) sarà solo aggiornata la grandezza corrispondente. Possiamo aggiungere una grandezza per volta o cliccare su un template e aggiungerle tutte insieme (vedi dopo). Ora aggiungiamone una per volta per capire il meccanismo cliccando sul pulsante aggiungi grandezza e compiliamo i campi:

Slug - id testuale della grandezza (sarà usato anche come nome del gruppo immagine), obbligatorio
Visibile nell'editor - specifica se l'immagine è selezionabile nel backend, altrimenti sarà usata solo come parte dell'attributo srcset
Nome - nome selezionabile della grandezza media, se la grandezza è visibile nell'editor impostare sempre (altrimenti il nome della grandezza diventerà un messaggio di errore come promemoria finchè non sarà fatto), se la grandezza media non è visibile lasciare vuoto
Larghezza - larghezza in pixel della grandezza media, è possibile inserire 0 (ma raramente utile) per impostare larghezza automatica
Altezza - altezza in pixel della grandezza media, probabilmente sarà 0 (escluse le grandezze relative gli opengraph) ma è possibile inserire un'altezza fissa
Crop - impostare eventuale ritaglio dell'immagine (che quindi potrebbe risultare parziale) e posizione XY di partenza, alternativamente lasciare su nessun ritaglio

Dopo aver compilato tutto ricordarsi di salvare il customizer per salvare le modifiche.

Oltre alla configurazione di ogni singola grandezza media, in questa sezione troviamo in alto due modal:

grandezze media correnti - contiene due tabelle relative le grandezze media correnti selezionabili e non
esempi grandezze media - contiene i templates a pulsanti relativi a questa sezione (vedi sotto). Per ogni template è presente un pulsante "usa queste grandezze media" che se cliccato, dopo una richiesta di conferma, imposterà le grandezze media come nel template e ricaricherà il customizer

TemplatesBtn

Questo modulo mette a disposizione una zona di templates a pulsanti:

module-media-mediasizes

Questo template definisce le grandezze media visibili nel modal esempi grandezze media come descritto nella sezione precedente e consiste in un array di oggetti con le seguenti proprietà:

contentsize - larghezza del contenuto del sito per cui le grandezze media sono ideali
desc - descrizione aggiuntiva (esempio i padding e i block spacing ideali)
mediasizes - array di oggetti contenenti le proprietà che definiscono la singola grandezza media

Ogni oggetto interno a mediasizes ha quindi le seguenti proprietà (che corrispondono ai campi visti nella sezione precedente):

media_size_slug - slug testuale
media_size_editor_visible - visibilità della grandezza media nel backend
media_size_name - nome selezionabile
media_size_w - larghezza in pixel
media_size_h - altezza in pixel
media_size_crop - eventuale cropping

Esempio

{
  "module-media-mediasizes":[
    { "contentsize":"1460px", "desc":"Grandezze calcolate con un padding del gruppo e un block-spacing tra le colonne di 20px.", "mediasizes":[
	  { "media_size_slug":"thumbnail", "media_size_name":"6 colonne uguali (220px)", "media_size_w":220, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":1 },
	  { "media_size_slug":"medium", "media_size_name":"5 colonne uguali (268px)", "media_size_w":268, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":1 },
	  { "media_size_slug":"medium_large", "media_size_name":"4 colonne uguali (340px)", "media_size_w":340, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":1 },
	  { "media_size_slug":"large", "media_size_name":"3 colonne uguali (460px)", "media_size_w":460, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":1 },
	  { "media_size_slug":"467w", "media_size_name":"2 colonne, 66/33, piccola (467px)", "media_size_w":467, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":1 },
	  { "media_size_slug":"934w", "media_size_name":"2 colonne, 66/33, grande (934px)", "media_size_w":934, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":1 },
	  { "media_size_slug":"345w", "media_size_name":"3 colonne, ampia centrale, piccola (345px)", "media_size_w":345, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":1 },
	  { "media_size_slug":"690w", "media_size_name":"3 colonne, ampia centrale, grande (690px)", "media_size_w":690, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":1 },
	  { "media_size_slug":"700w", "media_size_name":"2 colonne uguali (700px)", "media_size_w":700, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":1 },
	  { "media_size_slug":"1420w", "media_size_name":"1 colonna (1420px)", "media_size_w":1420, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":1 },
	  { "media_size_slug":"2840w", "media_size_name":"", "media_size_w":2840, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":0 },
	  { "media_size_slug":"1400w", "media_size_name":"", "media_size_w":1400, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":0 },
	  { "media_size_slug":"536w", "media_size_name":"", "media_size_w":536, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":0 },
	  { "media_size_slug":"440w", "media_size_name":"", "media_size_w":440, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":0 },
	  { "media_size_slug":"ogimage-large", "media_size_name":"", "media_size_w":1200, "media_size_h":630, "media_size_crop":"left-top", "media_size_editor_visible":0 },
	  { "media_size_slug":"ogimage-medium", "media_size_name":"", "media_size_w":640, "media_size_h":360, "media_size_crop":"left-top", "media_size_editor_visible":0 },
	  { "media_size_slug":"ogimage-small", "media_size_name":"", "media_size_w":200, "media_size_h":200, "media_size_crop":"left-top", "media_size_editor_visible":0 }
	] },

	{ "contentsize":"1280px", "desc":"Grandezze calcolate con un padding del gruppo e un block-spacing tra le colonne di 20px.", "mediasizes":[
	  { "media_size_slug":"thumbnail", "media_size_name":"6 colonne uguali (190px)", "media_size_w":190, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":1 },
	  { "media_size_slug":"medium", "media_size_name":"5 colonne uguali (232px)", "media_size_w":232, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":1 },
	  { "media_size_slug":"medium_large", "media_size_name":"4 colonne uguali (295px)", "media_size_w":295, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":1 },
	  { "media_size_slug":"large", "media_size_name":"3 colonne uguali (400px)", "media_size_w":400, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":1 },
	  { "media_size_slug":"407w", "media_size_name":"2 colonne, 66/33, piccola (407px)", "media_size_w":407, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":1 },
	  { "media_size_slug":"814w", "media_size_name":"2 colonne, 66/33, grande (814px)", "media_size_w":814, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":1 },
	  { "media_size_slug":"300w", "media_size_name":"3 colonne, ampia centrale, piccola (300px)", "media_size_w":300, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":1 },
	  { "media_size_slug":"690w", "media_size_name":"3 colonne, ampia centrale, grande (690px)", "media_size_w":690, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":1 },
	  { "media_size_slug":"600w", "media_size_name":"2 colonne uguali (600px)", "media_size_w":600, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":1 },
	  { "media_size_slug":"1240w", "media_size_name":"1 colonna (1240px)", "media_size_w":1204, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":1 },
	  { "media_size_slug":"2840w", "media_size_name":"", "media_size_w":2840, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":0 },
	  { "media_size_slug":"1220w", "media_size_name":"", "media_size_w":1220, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":0 },
	  { "media_size_slug":"610w", "media_size_name":"", "media_size_w":610, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":0 },
	  { "media_size_slug":"464w", "media_size_name":"", "media_size_w":464, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":0 },
	  { "media_size_slug":"380w", "media_size_name":"", "media_size_w":380, "media_size_h":0, "media_size_crop":"", "media_size_editor_visible":0 },
	  { "media_size_slug":"ogimage-large", "media_size_name":"", "media_size_w":1200, "media_size_h":630, "media_size_crop":"left-top", "media_size_editor_visible":0 },
	  { "media_size_slug":"ogimage-medium", "media_size_name":"", "media_size_w":640, "media_size_h":360, "media_size_crop":"left-top", "media_size_editor_visible":0 },
	  { "media_size_slug":"ogimage-small", "media_size_name":"", "media_size_w":200, "media_size_h":200, "media_size_crop":"left-top", "media_size_editor_visible":0 }
	] }
  ]	
}

Funzioni

Il modulo media aggiunge le seguenti funzioni ad uso pubblico:

CreateAttachment (REVISIONARE)

Questa funzione aggiunge un nuovo media alla libreria, molto probabilmente sarà utilizzata in un blocco gutenberg form per fare caricare media nel frontend agli utenti. E' utilizzabile in due modi:

caricare media da file (ricordarsi di applicare l'attributo)
caricare media da un url (quindi copiarlo da un url locale o remoto)

Parametri

$file - variabile Superglobal - opzionale - default: false
Utilizzare la superglobal $_POST['name'] o $_FILES['name'] con il parametro name del campo del form corrispondente
$updates - array associativo - opzionale - default: []
inserire chiavi e valori per aggiornare il media appena inserito, i valori possibili sono:

_wp_attachment_image_alt - aggiorna l'attributo alt del media
post_title - aggiorna il titolo del media
post_excerpt - aggiorna la didascalia del media
post_content - aggiorna la descrizione del media

Se viene specificata una chiave diversa da questa si suppone che sia sempre un campo personalizzato, quindi verrà usata la funzione update_post_meta internamente a CreateAttachment.

Return

La funzione ritorna l'id del media inserito in caso di successo oppure false in caso di fallimento.

Esempi

Utilizzata in un blocco form (con un input type=file name=media), crea un media da un file caricato dall'utente:

//Form inviato via php
$media = $_FILES['media'] ?? false;

if( $media ){
  $id = CreateAttachment( $media );
  if( $id ){ $content = 'Messaggio di successo'; }
  else{ $content = 'Messaggio di fallimento'; }
}

//Form inviato via javascript
$media = $_FILES['media'] ?? false;

if( $media ){
  $id = CreateAttachment( $media );
  if( $id ){ echo 'Messaggio di successo'; }
  else{ echo 'Messaggio di fallimento'; }
}

Utilizzata in un blocco form via php o javascript (con un input type=url name=media):

$media = $_POST['media'] ?? false;

if( $media ){
  $id = CreateAttachment( $media );
  if( $id ){ /*Messaggio di successo*/ }
  else{ /*Messaggio di fallimento*/ }
}

Ora carichiamo il media e aggiorniamo anche i suoi campi:

$media = $_FILES['media'] ?? false;

if( $media ){
  $id = CreateAttachment( $media, $updates=[
    '_wp_attachment_image_alt' => 'alt',
    'post_title'               => 'titolo',
    'post_excerpt'             => 'didascalia',
    'post_content'             => 'descrizione',
    'campo_personalizzato'     => 'campo personalizzato'
] );
  if( $id ){ /*Messaggio di successo*/ }
  else{ /*Messaggio di fallimento*/ }
}

Funzioni interne

Il modulo media aggiunge le seguenti funzioni ad uso interno:

GpciModuleMediaActionConditions

Processa le condizioni inerenti l'azione singola. Se non rispettate salterà l'azione corrente.

Parametri

$action - array associativo - array rappresentante l'azione singola definita nel contenitore $GLOBALS['gpci']['modules']['media']['actions']
$args - array associativo - valori da confrontare con quelli definiti nelle condizioni dell'azione - default: []

Return

True (l'azione sarà eseguita) o false (l'azione sarà saltata).

Esempio

//da hook wp_handle_upload_prefilter
if( !GpciModuleMediaActionConditions( $action, [ 'mime'=>$mime, 'type'=>$type, 'subtype'=>$subtype, 'width'=>$width, 'height'=>$height ] ) ){ continue; }

Campi personalizzati

Il modulo media aggiungenuovi campi personalizzati ai seguenti contesti:

Media singolo

Il modulo media aggiunge ai media singoli, all'interno della metabox modulo media, i seguenti campi:

File originale

Id: gpci_module_media_original_basename

Memorizza il nome ed estensione del file originale quando viene eseguita una conversione automatica a webp.

cartella di upload

Id: gpci_module_media_upload_dir

Percorso alla cartella di upload, in formato semplificato, quando differente dalla cartella di upload predefinita.

Url immagine originale (deprecato)

Id: media_url_original_image

Memorizza l'url dell'immagine originale quando viene eseguita una conversione automatica a webp. Rimane temporaneamente solo per retro compatibilità, verrà sostituito in un secondo momento dal file originlale.

Hooks

Il modulo media agisce tramite i seguenti hooks:

mb_settings_pages

Aggiunge il pannello media al customizer.

rwmb_meta_boxes

aggiunge i campi personalizzati al media singolo
aggiunge i campi personalizzati al customizer

wp_handle_upload_prefilter

Durante l'upload dei file tramite libreria media processa le azioni:

info_file
info_request
block
convert
upload_dir (imposta il filtro)

wp_handle_upload

Converte automaticamente a webp i files di tipo image/jpeg e image/png.

wp_generate_attachment_metadata

aggiorna il campo personalizzato file originale se c'è stata una conversione automatica a webp
processa l'azione upload_dir
processa l'azione update

get_attached_file

Corregge il percorso file dei media caricati in cartelle personalizzate.

wp_get_attachment_url

Corregge l'url dei media caricati in cartelle personalizzate.

delete_attachment

quando eliminato un media elimina anche il file originale se c'e' stata conversione automatica a webp
imposta un'eventuale la cartella di upload personalizzata pre la preparazione all'eliminazione dei files collegati al media

after_delete_post

Resetta la cartella di upload dopo l'eliminazione di un attachment.

big_image_size_threshold

Rimuove il suffisso -scaled ai file immagini grandi

intermediate_image_sizes

Disabilita le grandezze media del core non definite nel caso che nel customizer siano configurate grandezzze media personalizzate.

option_uploads_use_yearmonth_folders

Disabilita l'organizzazione dei media caricati in cartelle anno/data.

max_srcset_image_width

Disabilita il limite di larghezza massima dall'attributo srcset.

wp_calculate_image_srcset

Disabilita l'attributo srcset per i browser senza supporto webp.

wp_content_img_tag

rimuove webp dall'attributo src se il browser non supporta webp supporto servendo quindi il file originale (solo se esistente)
aggiunge le query strings contenente il timestamp ai tag src e srcset singoli

Funzionalità

Configurazione

Azioni

- info_file

- info_request

- block

- convert

- rename

- upload_dir

Altra documentazione rilevante

- update

Altra documentazione rilevante

Elenco di estensioni/mime types permessi da wordpress senza filtri

Customizer

Grandezze

TemplatesBtn

module-media-mediasizes

Esempio

Funzioni

CreateAttachment (REVISIONARE)

Parametri

Return

Esempi

Funzioni interne

GpciModuleMediaActionConditions

Parametri

Return

Esempio

Campi personalizzati

Media singolo

File originale

cartella di upload

Url immagine originale (deprecato)

Hooks

mb_settings_pages

rwmb_meta_boxes

wp_handle_upload_prefilter

wp_handle_upload

wp_generate_attachment_metadata

get_attached_file

wp_get_attachment_url

delete_attachment

after_delete_post

big_image_size_threshold

intermediate_image_sizes

option_uploads_use_yearmonth_folders

max_srcset_image_width

wp_calculate_image_srcset

wp_content_img_tag