Bruno Alesiani

FundCollector: scheda tecnica

Una panoramica tecnica di FundCollector, il plugin WordPress per le donazioni di cui curo progettazione e sviluppo: cosa fa, come è organizzato il codice, con quali servizi esterni dialoga e come gestisce i pagamenti, che per natura sono asincroni e non sempre arrivano nell'ordine atteso.

Cosa fa il plugin

FundCollector permette a un'associazione, a un ente o a un professionista di ricevere donazioni dal proprio sito WordPress: crea moduli di donazione personalizzabili, accetta pagamenti con PayPal e bonifico bancario, registra donazioni e donatori, invia le email di conferma e offre un pannello di amministrazione con elenchi, filtri e statistiche.

È distribuito in due edizioni. La Free è pubblicata su WordPress.org, quindi il codice è pubblico e verificabile. La Pro è un secondo plugin che si innesta sul primo e aggiunge pagamenti con Mollie, donazioni ricorrenti, report CSV e PDF, backup e ripristino dei dati.

Il pannello e i moduli sono tradotti in cinque lingue oltre all'inglese (italiano, francese, spagnolo, portoghese, tedesco).

Modulo di donazione di FundCollector, con scelta della frequenza e dell'importo
~40.000righe di PHP nel plugin Free
~17.000righe di PHP nel plugin Pro
~13.000righe di JavaScript nativo
8tabelle MySQL personalizzate

Architettura

Un «monolite modulare»: un unico plugin, organizzato per aree di responsabilità, non per servizi separati.

Schema a livelli dell'architettura di FundCollector Cinque livelli, dall'interfaccia utente a WordPress, e a destra il plugin Pro che si innesta sul Free tramite hook e filtri. Interfaccia Shortcode · blocco Gutenberg · JavaScript nativo · pannello admin (oltre 30 azioni AJAX) Dominio Donazioni · donatori · form · email · statistiche · ricorrenze (Pro) Integrazioni Interfaccia gateway + factory → PayPal · bonifico · Mollie (Pro) · reCAPTCHA · licenze Servizi di base Impostazioni · logger · cifratura · migrazioni DB · token anti-duplicato · traduzioni WordPress hook · AJAX · REST API · WP-Cron · tabelle custom Plugin Pro Mollie Ricorrenze Report CSV/PDF Backup e ripristino Licenze e update si innesta sul Free con hook e filtri, senza duplicarne il codice
I livelli del plugin Free (a sinistra) e il modo in cui il Pro vi si appoggia (a destra).
  • Gateway astratti. Ogni metodo di pagamento implementa la stessa interfaccia e viene creato da una factory: aggiungere un fornitore non richiede di toccare il checkout.
  • Orchestrazione a eventi. I passaggi principali passano dal sistema di hook di WordPress. Il Pro estende il Free allo stesso modo, e in questo modo i due plugin restano separati ma compatibili.
  • Dati sotto controllo. Donazioni, donatori, form e ricorrenze stanno in tabelle dedicate, non in post type e meta. Le migrazioni sono versionate e retrocompatibili, perché il plugin gira su siti in produzione che non devono perdere dati.
  • Una scelta consapevole. Il monolite modulare è il compromesso giusto per un plugin WordPress: installazione semplice e compatibilità con l'ecosistema, in cambio di una disciplina rigorosa sui contratti tra i moduli.

Struttura del codice

Le classi sono raggruppate per dominio. Ecco le cartelle principali.

Cartella Contenuto Edizione
includes/core/ Servizi di base: impostazioni, logger, cifratura, migratore del database, gestione dei token del form, dati temporanei, email e traduzioni. Free
includes/frontend/ Checkout pubblico: shortcode, rendering dei moduli, gestione dell'invio. Free
includes/admin/ Gestione di donazioni, donatori e form; statistiche; procedura guidata iniziale; viste del pannello. Free
includes/gateways/ e integrations/ Interfaccia e factory dei gateway; PayPal REST, gestione automatica dei webhook, collegamento guidato dell'account PayPal; bonifico bancario. Free
includes/blocks/ Blocco per l'editor Gutenberg. Free
gateways/mollie/, gateways/paypal/ Mollie (collegamento OAuth, pagamenti, webhook) e ricorrenze PayPal basate su abbonamenti e metodi di pagamento salvati. Pro
recurring-donations/ Gestore dello stato delle donazioni ricorrenti. Pro
reports/, backup/, licensing/ Esportazioni CSV e PDF; backup e ripristino con validazione dell'archivio; licenze e aggiornamenti. Pro

Che tipo di chiamate fa

Il plugin parla con servizi esterni tramite l'HTTP API di WordPress e, a sua volta, espone endpoint che altri servizi chiamano.

In uscita

Servizio Chiamate Scopo Edizione
PayPal REST /v1/oauth2/token
/v2/checkout/orders
/v2/payments/captures 		Autenticazione OAuth2, creazione e cattura degli ordini. Le richieste di scrittura portano un identificatore di idempotenza (PayPal-Request-Id). Free
PayPal Webhooks /v1/notifications/webhooks
/v1/notifications/verify-webhook-signature 		Registrazione automatica del webhook e verifica della firma di ogni evento ricevuto. Free
PayPal Vault /v3/vault/setup-tokens
/v3/vault/payment-tokens		 Salvataggio del metodo di pagamento per le donazioni ricorrenti. Pro
Mollie api.mollie.com/v2 + OAuth2 Pagamenti, mandati e abbonamenti; rinnovo anticipato del token di accesso. Pro
Google reCAPTCHA siteverify Controllo anti-bot lato server, con soglia di punteggio configurabile. Free
Servizio FundCollector Endpoint proxy Collegamento guidato dell'account PayPal e scambio dei token Mollie, così alcuni segreti non restano sul sito del cliente. Free Pro
Negozio licenze (EDD) activate_license, check_license, get_version Attivazione della licenza e aggiornamenti automatici del Pro. Pro

In entrata

Endpoint Chi lo chiama Protezione
admin-post.php?action=fundcollector_paypal_webhook_rest Webhook di PayPal (eventi PAYMENT.CAPTURE.*, CHECKOUT.ORDER.*) Firma verificata tramite l'API di PayPal
/wp-json/fundcollector-pro/v1/mollie-webhook e …/mollie-subscription-webhook Webhook di Mollie L'evento non è creduto sulla parola: l'oggetto viene richiesto di nuovo a Mollie
/wp-json/fundcollector/v1/logs Assistenza tecnica Token temporaneo e revocabile
admin-ajax.php (oltre 30 azioni) Modulo di donazione pubblico e pannello admin Nonce, verifica dei permessi, token anti-doppio invio, honeypot, reCAPTCHA

Le attività differite, come i nuovi tentativi e la riconciliazione, passano da WP-Cron, lo scheduler di WordPress.

La parte difficile: pagamenti asincroni

Quando il donatore paga, il sito riceve due segnali indipendenti: il ritorno del donatore e il webhook del fornitore. Non c'è garanzia sull'ordine, e il webhook può arrivare più volte.

Flusso di una donazione con PayPal Sequenza tra browser del donatore, sito WordPress e PayPal: invio del modulo, creazione dell'ordine, approvazione, cattura e webhook asincrono. Browser Sito WordPress PayPal 1. Invio del modulo (AJAX, nonce e token) 2. Crea l'ordine (con identificatore di idempotenza) 3. Il donatore approva il pagamento su PayPal 4. Richiesta di cattura (AJAX) 5. Cattura dell'ordine 6. Webhook firmato, in modo asincrono 7. Il sito elabora i due segnali Verifica la firma · controlla se la donazione esiste già · aggiorna lo stato in modo idempotente · invia le email
Flusso semplificato di una donazione una tantum con PayPal. Il passaggio 6 può arrivare prima o dopo il 4 e il 5.
  • Idempotenza. Lo stesso evento può arrivare due volte senza creare due donazioni: controlli di duplicato, identificatori di richiesta e vincoli di unicità nel database.
  • Stati intermedi. Una donazione segnalata come «in attesa» viene aggiornata allo stato definitivo quando arriva l'esito finale, invece di essere scartata come duplicato.
  • Nuovi tentativi. Per le ricorrenze Mollie, la creazione dell'abbonamento dopo il primo pagamento attende il mandato e riprova con tempi crescenti tramite WP-Cron.
  • Tracciabilità. Ogni passaggio è registrato da un logger dedicato, e il registro può essere consultato dall'assistenza con un accesso temporaneo.

Sicurezza e qualità del codice

Sicurezza

  • Verifica dei permessi e nonce sulle operazioni di amministrazione.
  • Sanitizzazione di ogni input ed escape di ogni output.
  • Credenziali e dati sensibili cifrati nel database con AES-256-CBC.
  • Protezione anti-spam: honeypot, reCAPTCHA opzionale, token anti-doppio invio.
  • Backup e ripristino del Pro con validazione dell'archivio e transazioni di database.

Qualità

  • Test automatici con PHPUnit, e test end-to-end del modulo di donazione con Playwright.
  • Analisi statica con PHPStan, controllo dello stile con PHPCS, ESLint e Stylelint.
  • Verifica con Plugin Check, lo strumento di controllo di WordPress.org.
  • Procedura di build che produce il pacchetto di distribuzione.
  • Documentazione tecnica interna di architettura, flussi e database.

Le cifre sopra riportate (righe di codice, numero di tabelle) sono quelle del codice attuale e cambiano a ogni versione. Il plugin Free è consultabile su WordPress.org.

Sito del prodotto FundCollector su WordPress.org Contattami