EG Forgejo Updater

Plugin WordPress minimale per aggiornare automaticamente plugin ospitati su un'istanza Forgejo self-hosted.

Sostituto leggero di Git Updater: nessun banner pubblicitario, nessun problema di compatibilità con Redis, token salvato in wp-config.php una volta sola.

---

Struttura del progetto

eg-forgejo-updater/
├── eg-forgejo-updater.php            # Bootstrap, header plugin, include classi
├── uninstall.php                     # Pulizia dati alla disinstallazione
├── index.php                         # Protezione directory listing
├── readme.txt                        # Readme formato standard WordPress
├── CHANGELOG.md                      # Storico modifiche
├── LICENSE                           # GPL-2.0-or-later
└── includes/
    ├── class-eg-forgejo-api.php      # Client API REST Forgejo
    ├── class-eg-forgejo-updater.php  # Hook WordPress per rilevamento e installazione aggiornamenti
    ├── class-eg-forgejo-admin.php    # Pagina di amministrazione (sottomenu Plugin)
    └── index.php                     # Protezione directory listing

---

Requisiti

• WordPress 6.0 o superiore
• PHP 8.0 o superiore (usa typed properties e named arguments)
• Istanza Forgejo accessibile via HTTPS dall'host WordPress
• Per ogni plugin da gestire: almeno un tag o una release nel relativo repo Forgejo

---

Installazione

1. Caricare la cartella eg-forgejo-updater/ in wp-content/plugins/
2. Aggiungere FORGEJO_ACCESS_TOKEN in wp-config.php (necessario per repo privati)
3. Attivare il plugin da Pannello di controllo > Plugin
4. I plugin con header Forgejo Plugin URI o Gitea Plugin URI vengono rilevati automaticamente
5. Per installare altri plugin da Forgejo, usare la funzione integrata descritta di seguito

---

Configurazione in wp-config.php

Aggiungere queste righe prima della riga /* That's all, stop editing! */:

// Token di accesso personale (necessario per repo privati)
define( 'FORGEJO_ACCESS_TOKEN', 'il_tuo_token_qui' );

// URL base dell'istanza Forgejo (opzionale dalla v2.0 - ricavato dall'header del plugin)
define( 'FORGEJO_BASE_URL', 'https://git.esempio.com' );

Note sulla costante FORGEJO_ACCESS_TOKEN

Necessaria per repo privati. Il token viene usato in due punti:

1. Nell'header Authorization: token xxx delle chiamate all'API REST Forgejo
2. Nell'header Authorization: token xxx della richiesta di download del file ZIP durante l'aggiornamento

Il token viene aggiunto solo alle richieste verso URL Forgejo conosciuti (dalla costante FORGEJO_BASE_URL e/o dagli header dei plugin). Non viene mai inviato a domini terzi.

Note sulla costante FORGEJO_BASE_URL

Opzionale dalla versione 2.0. Se i plugin hanno l'header Forgejo Plugin URI con URL completo (es. https://git.esempio.com/owner/repo), il base URL viene ricavato automaticamente. Resta utile per i plugin aggiunti manualmente senza header.

Auto-discovery dei plugin

Dalla versione 2.0 il plugin rileva automaticamente i plugin da gestire leggendo l'header del file PHP principale. Sono supportati due header, compatibili con Git Updater:

/**
 * Plugin Name: Il Mio Plugin
 * Forgejo Plugin URI: https://git.esempio.com/owner/il-mio-plugin
 */

oppure:

/**
 * Plugin Name: Il Mio Plugin
 * Gitea Plugin URI: https://git.esempio.com/owner/il-mio-plugin
 */

Se FORGEJO_BASE_URL e definita, si puo usare anche il formato breve:

 * Forgejo Plugin URI: owner/il-mio-plugin

I plugin rilevati automaticamente appaiono nella tabella con sorgente "auto" e non possono essere rimossi dalla lista (basta rimuovere l'header per escluderli).

Perché in wp-config.php e non nel database

Salvare credenziali nel database WordPress (anche cifrate) le espone potenzialmente a plugin malevoli o a dump del database. wp-config.php è al di fuori del webroot in configurazioni standard e non viene mai servito da NGINX/Apache. Questo approccio è compatibile con Redis Object Cache perché non dipende dai transient per le credenziali.

---

Come funziona il rilevamento degli aggiornamenti

Flusso completo

WordPress scheduler (ogni 12h) o azione manuale
  └── Filtro site_transient_update_plugins
        └── Per ogni plugin con header Forgejo/Gitea Plugin URI:
              └── get_transient(eg_fu_release_{md5(plugin_file)})
                    ├── Cache presente → usa dato cached
                    └── Cache assente  → chiama API Forgejo (1 sola chiamata)
                          └── GET /api/v1/repos/{owner}/{repo}/raw/{file}.php?ref=main
                                └── Parsa "Version:" dal sorgente remoto
                                      ├── Versione remota > installata → inietta in $transient->response
                                      └── Versione uguale o inferiore  → rimuove da $transient->response

Frequenza controllo

La cache dei dati di versione e salvata come WordPress transient con TTL di 12 ore (CACHE_TTL = 43200). Questo significa:

• Il controllo automatico avviene ogni 12 ore, in sincronia con il ciclo nativo di WordPress
• Andando in Dashboard > Aggiornamenti e cliccando "Controlla di nuovo" si forza un controllo immediato
• Il pulsante "Controlla aggiornamenti ora" nella pagina del plugin svuota esplicitamente tutti i transient

Confronto versioni

WordPress utilizza internamente version_compare() (PHP nativo). La versione remota viene letta direttamente dall'header Version: del file PHP principale sul branch del repo.

---

Gestione del file ZIP durante l'aggiornamento

Download dell'archivio

Il plugin scarica l'archivio ZIP del branch primario dal repo Forgejo:

https://git.esempio.com/owner/repo/archive/main.zip

Problema del nome cartella

Forgejo genera archivi con nome cartella tipo repo-main/ che non corrisponde allo slug del plugin (es. eg-fediverso-box/). WordPress si aspetta che la cartella estratta abbia lo stesso nome dello slug.

Il plugin risolve questo tramite il filtro upgrader_source_selection che rinomina la cartella estratta allo slug corretto prima che WordPress completi l'installazione.

---

Installare un plugin da Forgejo

EG Forgejo Updater permette di installare qualsiasi plugin pubblico ospitato su Forgejo direttamente da WordPress, senza scaricare zip, senza FTP, senza upload manuale.

Come fare

1. Vai su Plugin → Forgejo Updater
2. Nella sezione "Installa plugin da Forgejo", incolla l'URL del repository
3. Clicca "Verifica e continua"
4. Il plugin esegue una checklist automatica:
   • Formato URL valido
   • Istanza Forgejo/Gitea riconosciuta
   • Repository raggiungibile
   • File PHP principale trovato
   • Header Plugin Name e Version presenti
   • Header Forgejo Plugin URI presente (necessario per gli aggiornamenti automatici)
5. Se tutti i controlli passano, viene mostrata un'anteprima con nome, versione e autore
6. Clicca "Installa plugin" per procedere
7. Attiva il plugin dalla lista plugin

Una volta installato, il plugin viene rilevato automaticamente dall'auto-discovery e riceverà gli aggiornamenti come tutti gli altri.

Aggiunta tramite header (auto-discovery)

Per i plugin già installati con l'header nel file PHP principale:

 * Forgejo Plugin URI: https://git.emanuelegori.uno/emanuelegori/repotest
 * Primary Branch: main

Il plugin viene rilevato automaticamente al caricamento della pagina, senza nessuna configurazione aggiuntiva.

---

Icona Forgejo nella lista plugin

Nella pagina Plugin > Plugin installati, ogni plugin gestito da questo updater mostra un link aggiuntivo nella riga delle meta informazioni (sotto il nome e la descrizione), con il logo Forgejo e un link diretto al repository.

Il logo SVG è incorporato inline nel PHP (get_forgejo_svg()), senza file di asset separati e senza richieste HTTP aggiuntive.

---

Hook WordPress utilizzati

Hook	Classe	Scopo
plugins_loaded	bootstrap	Inizializzazione classi
site_transient_update_plugins	Updater	Iniezione dati aggiornamento nel ciclo nativo WP
plugins_api	Updater	Popup "Dettagli versione" nella dashboard
plugin_row_meta	Updater	Icona Forgejo e link repo nella lista plugin
http_request_args	Updater	Aggiunta token Authorization per download repo privati
upgrader_source_selection	Updater	Correzione nome cartella ZIP da zipball
upgrader_process_complete	Updater	Svuotamento cache dopo aggiornamento completato
admin_menu	Admin	Registrazione sottomenu in Plugin
admin_post_eg_fu_preview	Admin	Verifica URL repo e checklist compatibilità
admin_post_eg_fu_install	Admin	Installazione plugin da zip Forgejo
admin_post_eg_fu_delete	Admin	Rimozione plugin dalla lista
admin_post_eg_fu_check	Admin	Forza controllo aggiornamenti immediato
admin_notices	Admin	Notifiche feedback operazioni

---

Compatibilità Redis Object Cache

I transient vengono salvati tramite le funzioni native set_transient() / get_transient() / delete_transient() di WordPress. Con Redis Object Cache attivo questi vengono automaticamente memorizzati in Redis senza configurazioni aggiuntive. Non vengono usate query SQL dirette né accessi al database bypass, eliminando il problema di incompatibilità che affliggeva Git Updater.

---

Pubblicare una nuova versione

Per ogni nuova versione di un plugin gestito:

1. Aggiornare Version: nell'header del file PHP principale del plugin
2. Fare commit e push sul branch primario

Entro 12 ore (o immediatamente cliccando "Controlla aggiornamenti ora") WordPress mostrera la notifica di aggiornamento disponibile. Non serve creare release o tag.

---

Aggiornamento dello stesso EG Forgejo Updater

Questo plugin gestisce se stesso grazie all'header Forgejo Plugin URI nel proprio file principale. Si aggiorna esattamente come gli altri plugin.

---

Licenza

GPL-2.0-or-later