# Buone pratiche per i siti PHP

Quelle: https://madpublishing.ch/it/aiuto/buone-pratiche-php
Stand: 2026-10-11

> Dieci regole che mantengono un sito PHP da noi sicuro, robusto e facile da curare – ognuna con un esempio. Le tre più importanti: i segreti vanno nell’area dati, mai nei file del sito né nella chat. Il percorso verso l’area dati lo leggi da PUBLISHING_STORAGE. E gli errori li cerchi nell’anteprima, perché solo lei li mostra.
> 
> Le basi – quali cartelle esistono, cosa fa la scheda «Dati», quali limiti valgono – stanno in PHP e l’area dati. Anche il tuo assistente conosce queste regole e costruisce di conseguenza.

Dieci regole che mantengono un sito PHP da noi sicuro, robusto e facile da curare – ognuna con un esempio. Le tre più importanti: i segreti vanno nell’area dati, mai nei file del sito né nella chat. Il percorso verso l’area dati lo leggi da `PUBLISHING_STORAGE`. E gli errori li cerchi nell’anteprima, perché solo lei li mostra.

Le basi – quali cartelle esistono, cosa fa la scheda «Dati», quali limiti valgono – stanno in [PHP e l’area dati](https://madpublishing.ch/it/aiuto/php-e-area-dati). Anche il tuo assistente conosce queste regole e costruisce di conseguenza.

## 1. I segreti vanno nell’area dati

Chiavi API, password SMTP e credenziali stanno in **un file nell’area dati**, che carichi nella scheda «Dati». Non nei file del sito, e non nella chat.

- **Non nei file del sito:** tutto ciò che sta lì viene pubblicato, e ogni modifica viene conservata come versione. Una chiave che ci è stata una volta resta nella cronologia anche dopo averla eliminata.
- **Non nella chat:** quello che scrivi lì passa attraverso un modello linguistico. Il tuo assistente ti dice quale file, con quali campi, si aspetta il suo codice – i valori li inserisci tu.

Per la configurazione usa **JSON e non PHP**. Un `config.php` nell’area dati viene trattenuto dalla cache di PHP: se lo sostituisci, quello nuovo vale solo dopo la prossima pausa del sito. Un file JSON viene riletto a ogni richiesta.

```json
{
  "smtp": { "host": "mail.fornitore.ch", "user": "sito@tuo-dominio.ch", "password": "…" },
  "pagamento": { "chiave": "sk_live_…" }
}
```

```php
<?php
function config(): array
{
    static $config = null;

    if ($config === null) {
        $file = percorso_dati('config.json'); // percorso_dati() sta nella regola 2

        if (!is_file($file)) {
            throw new RuntimeException('config.json manca nell’area dati.');
        }

        $config = json_decode(file_get_contents($file), true, 512, JSON_THROW_ON_ERROR);
    }

    return $config;
}
```

## 2. Leggere il percorso dall’ambiente

Non scrivere `/var/www/storage` in venti punti. Basta una piccola funzione, e sul tuo computer imposti `PUBLISHING_STORAGE` su una cartella locale – lo stesso codice gira così in entrambi i posti.

```php
<?php
function percorso_dati(string $file = ''): string
{
    $base = rtrim(getenv('PUBLISHING_STORAGE') ?: '/var/www/storage', '/');

    return $file === '' ? $base : $base . '/' . ltrim($file, '/');
}
```

`getenv()` e non `$_ENV` – qui resta vuoto.

## 3. Separare anteprima e live con i dati, non con il codice

L’anteprima ha la sua area dati. Mettici un `config.json` con **chiavi di prova** – per esempio la modalità test della tua API di pagamento – e live uno con quelle vere. Lo stesso codice usa così la prova nell’anteprima e il caso reale live, senza una sola condizione.

Se nel codice devi saperlo comunque:

```php
$anteprima = getenv('PUBLISHING_VORSCHAU') === '1';
```

## 4. I dati in SQLite invece che in un server di database

Da noi non c’è un server di database, e non puoi raggiungerne uno altrui (MySQL ha bisogno della porta 3306; sono aperte solo 80, 443, 587 e 465). Per richieste, ordini e iscrizioni basta **SQLite**: un unico file nell’area dati, con tutto ciò che ci si aspetta da un database.

```php
<?php
$db = new PDO('sqlite:' . percorso_dati('dati.sqlite'));
$db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
// Aspettare invece di fallire quando qualcun altro sta scrivendo.
$db->exec('PRAGMA busy_timeout = 5000');

$db->exec('CREATE TABLE IF NOT EXISTS richieste (
    id INTEGER PRIMARY KEY,
    nome TEXT NOT NULL,
    email TEXT NOT NULL,
    messaggio TEXT NOT NULL,
    ricevuta TEXT NOT NULL
)');

$nuova = $db->prepare('INSERT INTO richieste (nome, email, messaggio, ricevuta) VALUES (?, ?, ?, ?)');
$nuova->execute([$nome, $email, $messaggio, date('c')]);
```

- **Sempre con i segnaposto** (`?`), mai con testo composto. È la protezione contro la SQL injection.
- Per un backup basta quell’unico file – scaricalo nella scheda «Dati», possibilmente in un momento tranquillo.

Per pochissimi dati – una lista di venti voci – basta anche un file JSON. Allora vale la regola 5.

## 5. Scrivere in contemporanea: bloccare e sostituire

Fino a otto richieste girano contemporaneamente. Due che scrivono lo stesso file lo distruggono – e un file JSON scritto a metà blocca l’intero sito.

**Aggiungere** con un blocco:

```php
file_put_contents(percorso_dati('iscrizioni.csv'), $riga . "\n", FILE_APPEND | LOCK_EX);
```

**Sostituire interamente** tramite un file intermedio nella stessa cartella. La rinomina avviene in un colpo solo: chi legge vede il file vecchio o quello nuovo, mai una metà.

```php
function salva(string $file, string $contenuto): void
{
    $destinazione = percorso_dati($file);
    $meta = $destinazione . '.' . bin2hex(random_bytes(4)) . '.tmp';

    file_put_contents($meta, $contenuto, LOCK_EX);
    rename($meta, $destinazione);
}
```

**Leggere, modificare, riscrivere** – un contatore, per esempio – richiede un blocco attorno a tutto:

```php
$blocco = fopen(percorso_dati('contatore.lock'), 'c');
flock($blocco, LOCK_EX);

$stato = (int) @file_get_contents(percorso_dati('contatore.txt'));
salva('contatore.txt', (string) ($stato + 1));

flock($blocco, LOCK_UN);
fclose($blocco);
```

Se diventa di più, usa SQLite – lì tutto questo è già risolto.

## 6. E-mail via SMTP, non con mail()

Da noi `mail()` non invia nulla e restituisce `false`. Per un modulo di contatto usi **SMTP presso un fornitore di posta** – è comunque la via migliore: il fornitore si occupa della verifica del mittente (SPF, DKIM), e i tuoi messaggi non finiscono nello spam.

- **Porta 587** con STARTTLS o **465** con TLS. La porta 25 è bloccata.
- Le credenziali nel `config.json` dell’area dati (regola 1).
- **Il mittente è il tuo indirizzo**, quello del visitatore va in «Rispondi a». Chi inserisce l’indirizzo del visitatore come mittente falsifica un mittente – ed è esattamente ciò che i programmi di posta scartano.
- **Salva anche la richiesta** (regola 4). Se il fornitore di posta ha un guasto, non si perde nulla.

Con PHPMailer:

```php
<?php
use PHPMailer\PHPMailer\PHPMailer;

require __DIR__ . '/vendor/autoload.php';

$smtp = config()['smtp'];

$mail = new PHPMailer(true);
$mail->isSMTP();
$mail->Host = $smtp['host'];
$mail->Port = 587;
$mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
$mail->SMTPAuth = true;
$mail->Username = $smtp['user'];
$mail->Password = $smtp['password'];
$mail->CharSet = 'UTF-8';

$mail->setFrom('sito@tuo-dominio.ch', 'Sito web');
$mail->addReplyTo($email, $nome);
$mail->addAddress('contatto@tuo-dominio.ch');
$mail->Subject = 'Nuova richiesta dal sito';
$mail->Body = $messaggio;

$mail->send();
```

Nell’anteprima così invii messaggi veri, se lì ci sono le stesse credenziali. Metti quindi nell’area dell’anteprima una configurazione con un indirizzo di prova come destinatario (regola 3).

## 7. Accettare in sicurezza i caricamenti dei visitatori

Un file caricato è un input estraneo – e lo sono anche il suo nome, la sua dimensione e il tipo dichiarato.

```php
<?php
$file = $_FILES['ricevuta'] ?? null;

if (!$file || $file['error'] !== UPLOAD_ERR_OK) {
    exit('Il caricamento non è riuscito.');
}

if ($file['size'] > 10 * 1024 * 1024) {
    exit('Il file supera i 10 MB.');
}

// Determinare il tipo dal contenuto, non dal nome.
$tipo = (new finfo(FILEINFO_MIME_TYPE))->file($file['tmp_name']);
$ammessi = ['image/jpeg' => 'jpg', 'image/png' => 'png', 'application/pdf' => 'pdf'];

if (!isset($ammessi[$tipo])) {
    exit('Sono ammessi JPG, PNG e PDF.');
}

// Un nome proprio e casuale – mai quello del visitatore.
$nome = bin2hex(random_bytes(16)) . '.' . $ammessi[$tipo];

if (!is_dir(percorso_dati('uploads'))) {
    mkdir(percorso_dati('uploads'), 0770, true);
}

move_uploaded_file($file['tmp_name'], percorso_dati('uploads/' . $nome));
```

La consegna passa poi da uno script tuo, che verifica prima chi può vedere il file – e controlla rigorosamente il nome prima di usarlo:

```php
if (!preg_match('/^[a-f0-9]{32}\.(jpg|png|pdf)$/', $nome)) {
    http_response_code(404);
    exit;
}

header('Content-Type: application/octet-stream');
header('Content-Disposition: attachment; filename="ricevuta.' . pathinfo($nome, PATHINFO_EXTENSION) . '"');
header('X-Content-Type-Options: nosniff');
readfile(percorso_dati('uploads/' . $nome));
```

Indica il limite nel modulo stesso – altrimenti un visitatore con un file troppo grande vede solo una pagina di errore. Il limite massimo da noi è di 100 MB per file.

## 8. Trovare gli errori

**Nell’anteprima** PHP mostra ogni errore, compresi gli avvisi sulle funzioni deprecate. **Live** non ne mostra nessuno – i visitatori non devono vedere percorsi e query. Il registro del sito pubblicato non ti è accessibile. Se te ne serve uno, scrivilo tu stesso nell’area dati, con un limite perché non cresca all’infinito:

```php
function registro(string $riga): void
{
    $file = percorso_dati('sito.log');

    // Da 1 MB inizia un nuovo file; il precedente resta come .1.
    if (is_file($file) && filesize($file) > 1024 * 1024) {
        rename($file, $file . '.1');
    }

    file_put_contents($file, date('c') . ' ' . $riga . "\n", FILE_APPEND | LOCK_EX);
}

set_exception_handler(function (Throwable $errore) {
    registro(get_class($errore) . ': ' . $errore->getMessage() . ' in ' . $errore->getFile() . ':' . $errore->getLine());
    http_response_code(500);
    echo 'Qualcosa è andato storto. Riprova più tardi.';
});
```

Il registro lo scarichi nella scheda «Dati». **Non scriverci password, chiavi o dati di pagamento completi.**

## 9. Ordine nell’area dati

- **Una struttura chiara:** `config.json` in cima, sotto cartelle come `uploads/` ed `export/`, il database come `dati.sqlite`.
- **Tenere d’occhio lo spazio.** Live e anteprima condividono il limite del tuo piano; la scheda «Dati» mostra quanto è occupato. Quando è pieno, il portale non accetta più nulla.
- **Fare pulizia, senza cron.** Niente gira da solo a intervalli regolari. Fai quindi girare la pulizia di tanto in tanto durante una richiesta normale:

```php
// Più o meno a ogni centesima richiesta: eliminare i caricamenti più vecchi di 90 giorni.
if (random_int(1, 100) === 1) {
    foreach (glob(percorso_dati('uploads/*')) ?: [] as $vecchio) {
        if (filemtime($vecchio) < time() - 90 * 86400) {
            unlink($vecchio);
        }
    }
}
```

- **Non toccare `sessions`.** Lì PHP gestisce gli accessi dei tuoi visitatori.

## 10. Fare il backup da sé

**Il nostro backup quotidiano protegge i nostri sistemi, non singoli stati dei tuoi dati.** Non ne ripristiniamo nulla su richiesta. I file del tuo sito si recuperano tramite le versioni; quello che il tuo PHP ha scritto no. Scarica quindi regolarmente i dati importanti nella scheda «Dati» – oppure dai al tuo sito una funzione di esportazione, protetta da un accesso, che esporta gli ordini in CSV. Quello che scarichi tu una volta al mese è ciò che ti resta dopo un errore.

## Le pause e cosa significano

Dopo 15 minuti senza visite il tuo sito fa una pausa; la richiesta successiva lo riavvia e dura un po’ di più. Le sessioni e l’area dati lo superano. **Ciò che stava in `/tmp` no** – mettici solo quello che serve alla richiesta in corso.

La cache trattiene i tuoi file PHP fino alla prossima pubblicazione. È veloce e corretto, perché cambiano solo allora. Lo stesso vale per i file PHP nell’area dati – per questo la configurazione va in un file JSON (regola 1).

## Librerie con Composer

Sul server non ci sono né riga di comando né Composer. Le librerie come PHPMailer le installi sul tuo computer e carichi la cartella `vendor/` insieme ai file del sito – nel modo più semplice come ZIP nella scheda «File».

```
composer config platform.php 8.4
composer require phpmailer/phpmailer
composer install --no-dev --optimize-autoloader
```

`composer config platform.php 8.4` fa scegliere a Composer versioni compatibili con PHP 8.4 – anche se sul tuo computer è installata un’altra versione. Puoi caricare anche `composer.json` e `composer.lock`; il sito non li serve mai.

## Errori frequenti e loro causa

| Cosa vedi | Causa | Rimedio |
|---|---|---|
| `open_basedir restriction in effect` | Un percorso fuori dalle posizioni ammesse | Costruire i percorsi con `percorso_dati()` (regola 2) |
| `Read-only file system` o `Permission denied` in scrittura | Scrittura nei file del sito | Scrivere nell’area dati |
| Funziona live, non nell’anteprima | Manca la configurazione nell’area dell’anteprima | Passare ad «Anteprima» nella scheda «Dati» e depositarla lì |
| `mail()` restituisce `false` | Con `mail()` non si invia nulla | SMTP presso un fornitore di posta (regola 6) |
| `could not find driver` o nessuna connessione a MySQL | Nessun server di database, porta 3306 bloccata | SQLite (regola 4) |
| Una connessione a un servizio resta appesa | Una porta diversa da 80, 443, 587 o 465 | Usare l’accesso HTTPS del servizio |
| Il caricamento si interrompe con l’errore 413 | File più grande di 100 MB | Indicare il limite nel modulo (regola 7) |
| Live solo una pagina bianca | Un errore che live non viene mostrato | Aprire la stessa pagina nell’anteprima |
| Una nuova configurazione non ha effetto | Un `config.php` nell’area dati, trattenuto dalla cache | JSON invece di PHP (regola 1) |
| I visitatori vengono continuamente disconnessi | `session.save_path` è stato modificato | Lasciare l’impostazione – le sessioni stanno già nell’area dati |
| Il portale non accetta più file | Lo spazio del piano è esaurito | Fare pulizia (regola 9) o chiedere più spazio |