Documentazione tecnica.

Requisiti

Cart Cleaner è progettato per PrestaShop 8.x. Non è retrocompatibile con 1.7. Verifica prima di procedere:

• PrestaShop: 8.0.0 → 8.x (tutte le release)
• PHP: 7.4 → 8.3
• MySQL: 5.6+ o MariaDB 10.3+
• Permessi: scrittura su /modules/, /var/logs/
• Cron: accesso a crontab o equivalente (hosting shared: pannello cron del tuo provider)

Il modulo non richiede estensioni PHP aggiuntive oltre a quelle standard di PrestaShop.

Installazione

Due modalità. L'upload ZIP è quella raccomandata, FTP manuale è utile per hosting con limiti sul peso upload.

Metodo 1 · Upload ZIP

1. Scarica l'archivio cartcleaner.zip dall'area clienti dopo l'acquisto.
2. Accedi al backoffice PrestaShop: Moduli → Module Manager.
3. Clicca Carica un modulo in alto a destra.
4. Trascina lo ZIP o selezionalo dal file system.
5. Attendi la conferma di installazione: il modulo crea la tabella log, genera un token cron, registra i tre hook.
6. Clicca Configura sul tile del modulo per aprire la pagina di amministrazione.

Metodo 2 · FTP manuale

1. Scompatta cartcleaner.zip localmente.
2. Carica la cartella cartcleaner/ via FTP in /modules/ del tuo PrestaShop.
3. Verifica i permessi: la cartella e i file devono essere leggibili dal processo PHP.
4. Dal backoffice: Moduli → Module Manager, cerca "Cart Cleaner", clicca Installa.

Configurazione

La pagina di configurazione ha quattro parametri. I default sono quelli che consigliamo out-of-the-box: cambiali solo se hai ragioni specifiche.

Setup cron

Il cron è opzionale ma raccomandato. Senza cron il modulo continua a funzionare (i tre hook sono sufficienti), ma perdi la manutenzione automatica: sweep delle regole residue e purga log.

Comando crontab

Dal backoffice del modulo copia l'URL già compilato con il tuo token. Il formato è:

# ogni notte alle 3:00
0 3 * * * curl -s "https://tuoshop.com/module/cartcleaner/cron?token=XXXXXXXX" > /dev/null 2>&1

Frequenze consigliate

• Shop piccoli/medi: ogni notte (es. alle 3:00)
• Shop con traffico elevato: ogni 6 ore
• Shop con migliaia di coupon: ogni ora (occhio al carico)

Rigenerazione token

Se sospetti che il token sia stato esposto (es. in un log pubblico o un commit Git), rigeneralo dal backoffice salvando un nuovo valore. Ricordati di aggiornare anche il comando crontab.

Hook reference

Il modulo registra tre hook in fase di installazione. Puoi verificarne la registrazione dal backoffice in Moduli → Posizione.

actionObjectCartRuleUpdateAfter

Layer 01 · pulizia reattiva. Si attiva ogni volta che l'entità CartRule viene aggiornata. Il modulo filtra gli eventi in cui active == 0 e avvia la pulizia dei carrelli collegati.

actionCartSave

Layer 02 · save-time guard. Si attiva a ogni persistenza del Cart. Il modulo verifica che tutte le cart rule applicate al carrello siano ancora attive. Quelle scadute nel frattempo vengono rimosse.

actionValidateOrder

Layer 03 · last-line defense. Si attiva prima della finalizzazione dell'ordine. Se una regola inattiva è sopravvissuta, viene rimossa. Questo layer è toggleabile tramite CARTCLEANER_ORDER_PROTECTION.

Database schema

Il modulo crea una singola tabella in installazione e la rimuove in disinstallazione.

CREATE TABLE ps_cartcleaner_log (
  id_log          INT UNSIGNED NOT NULL AUTO_INCREMENT,
  id_cart_rule    INT UNSIGNED NOT NULL,
  cart_rule_name  VARCHAR(255) NULL,
  cart_rule_code  VARCHAR(64)  NULL,
  carts_found     INT UNSIGNED DEFAULT 0,
  carts_cleaned   INT UNSIGNED DEFAULT 0,
  carts_errors    INT UNSIGNED DEFAULT 0,
  source          VARCHAR(16) NOT NULL,
  id_employee     INT UNSIGNED NULL,
  details         TEXT NULL,
  date_add        DATETIME NOT NULL,
  PRIMARY KEY (id_log),
  INDEX (id_cart_rule),
  INDEX (source),
  INDEX (date_add)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Valori possibili per source: hook, manual, cron, checkout.

Il modulo non modifica alcuna tabella core di PrestaShop. L'interazione è limitata a lettura su ps_cart_rule e DELETE su ps_cart_cart_rule.

Troubleshooting

L'hook non si attiva alla disattivazione

Verifica in Moduli → Posizione che CartCleaner sia registrato su actionObjectCartRuleUpdateAfter. Se manca, esegui:

$php bin/console prestashop:module reset cartcleaner

Il cron restituisce 401 / 403

Il token è errato o scaduto. Copia l'URL aggiornato dal backoffice e rimpiazza la riga in crontab. Ricorda: il token è case-sensitive.

Timeout durante sweep globale

Hai troppi carrelli/regole in contemporanea. Abbassa CARTCLEANER_BATCH_SIZE a 100 o 200 e riprova. In alternativa usa il cron orario invece dello sweep manuale.

Gli ordini esistenti vengono modificati

Cart Cleaner non tocca mai ordini già validati. Opera solo sulla tabella ps_cart_cart_rule, che è distinta da ps_order_cart_rule. Se vedi modifiche su ordini, non è Cart Cleaner.

Come esportare i log

Dal backoffice del modulo clicca Esporta CSV sopra la tabella Storico. Ottieni un file UTF-8 con BOM (Excel italiano apre correttamente gli accenti), separatore ;, campo employee_name già risolto via JOIN con la tabella employee.

Per backup completi via riga di comando resta sempre possibile usare mysqldump:

$mysqldump -u USER -p DB ps_cartcleaner_log > log.sql

Disinstallazione

Dal backoffice: Moduli → Module Manager, trova Cart Cleaner, clicca il menu ⋯ → Disinstalla.

La disinstallazione:

• Rimuove i tre hook dalle posizioni
• Elimina la tabella ps_cartcleaner_log (e tutti i log con essa)
• Elimina le quattro variabili CARTCLEANER_* da ps_configuration
• Non tocca né carrelli né ordini né cart rule esistenti