PHP e cURL: inviare dati con richieste POST in modo sicuro e pratico

by theArchitect
Add as preferred source on Google
SHARE
PHP e cURL: inviare dati con richieste POST in modo sicuro e pratico
© Guida-HTML5.it

Introduzione

Quando si lavora con API, form esterni o servizi web di terze parti, molto spesso non basta leggere una risposta: bisogna anche inviare dati. In PHP, una delle soluzioni più flessibili e diffuse per farlo è cURL, una libreria che permette di eseguire richieste HTTP in modo controllato e professionale.

In questo tutorial vedremo un sotto-argomento molto utile e concreto: come inviare dati con una richiesta POST usando cURL in PHP. È un caso d’uso estremamente comune, ad esempio per:

  • inviare i dati di un form a un’API esterna;
  • creare utenti su un servizio remoto;
  • trasmettere credenziali o parametri di ricerca;
  • automatizzare operazioni tra applicazioni diverse.

L’obiettivo non è solo “far funzionare” la richiesta, ma farlo con un approccio corretto: gestione degli errori, impostazioni essenziali e codice leggibile.

Codice completo

<?php

// URL dell´endpoint API che riceve i dati
$url = ´https://api.example.com/contatti´;

// Dati da inviare tramite POST
$payload = [
    ´nome´  => ´Mario Rossi´,
    ´email´ => ´[email protected]´,
    ´ruolo´ => ´developer´
];

// Inizializza una nuova sessione cURL
$ch = curl_init($url);

// Imposta le opzioni della richiesta
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,  // Restituisce la risposta come stringa
    CURLOPT_POST           => true,  // Usa il metodo POST
    CURLOPT_POSTFIELDS     => http_build_query($payload), // Converte l´array in formato query string
    CURLOPT_HTTPHEADER     => [
        ´Content-Type: application/x-www-form-urlencoded´,
        ´Accept: application/json´
    ],
    CURLOPT_TIMEOUT        => 15,    // Timeout in secondi
]);

// Esegue la richiesta
$response = curl_exec($ch);

// Controlla eventuali errori di cURL
if ($response === false) {
    $error = curl_error($ch);
    $errno = curl_errno($ch);

    curl_close($ch);

    die("Errore cURL ($errno): $error");
}

// Recupera il codice HTTP della risposta
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

// Chiude la sessione cURL
curl_close($ch);

// Gestione base della risposta
if ($httpCode >= 200 && $httpCode < 300) {
    echo "Richiesta completata con successo.n";
    echo "Risposta del server:n";
    echo $response;
} else {
    echo "La richiesta ha restituito un codice HTTP non valido: " . $httpCode . "n";
    echo "Risposta del server:n";
    echo $response;
}

Spiegazione

1. Inizializzazione della sessione cURL

La funzione curl_init() crea un handle cURL, cioè un oggetto interno che rappresenta la richiesta HTTP. Nel nostro esempio passiamo direttamente l’URL, così cURL sa subito dove inviare la richiesta.

2. Impostazione delle opzioni

Con curl_setopt_array() configuriamo tutto in un colpo solo. È una scelta più ordinata rispetto a chiamare curl_setopt() più volte.

  • CURLOPT_RETURNTRANSFER: fondamentale, perché evita che la risposta venga stampata automaticamente a schermo e la restituisce invece come stringa.
  • CURLOPT_POST: indica che la richiesta deve essere di tipo POST.
  • CURLOPT_POSTFIELDS: contiene i dati da inviare. In questo caso usiamo http_build_query() per trasformare l’array in formato compatibile con application/x-www-form-urlencoded.
  • CURLOPT_HTTPHEADER: specifica gli header HTTP. Qui dichiariamo il tipo di contenuto e il formato atteso in risposta.
  • CURLOPT_TIMEOUT: evita che lo script resti bloccato troppo a lungo se il server non risponde.

3. Esecuzione della richiesta

curl_exec() invia effettivamente la richiesta. Se qualcosa va storto a livello di rete, DNS, SSL o protocollo, la funzione restituisce false.

Per questo motivo è importante verificare subito il valore di ritorno e, in caso di errore, usare:

  • curl_error() per ottenere il messaggio descrittivo;
  • curl_errno() per ottenere il codice numerico dell’errore.

4. Controllo del codice HTTP

Anche se la richiesta è andata a buon fine dal punto di vista tecnico, il server potrebbe comunque rispondere con un errore applicativo, ad esempio 400 Bad Request o 500 Internal Server Error. Per questo controlliamo il codice HTTP con curl_getinfo().

In generale, i codici compresi tra 200 e 299 indicano successo. Se il server risponde con un altro codice, conviene trattare la risposta come un fallimento e analizzarne il contenuto.

5. Chiusura della risorsa

Infine, curl_close() libera le risorse allocate. È una buona abitudine da mantenere sempre, soprattutto in script che fanno molte richieste o girano in ambienti persistenti.

Best practice

  • Valida sempre i dati prima di inviarli: cURL non sostituisce la validazione lato applicazione. Se stai passando dati raccolti da un form, controlla email, stringhe vuote e formati non validi.
  • Imposta un timeout: senza timeout, una richiesta lenta può bloccare l’esecuzione del tuo script più del necessario.
  • Controlla sia l’errore cURL sia il codice HTTP: sono due livelli diversi di problema. Uno riguarda la connessione, l’altro la risposta del server.
  • Usa gli header corretti: un endpoint può aspettarsi JSON, form URL encoded o altri formati. Se gli header non corrispondono, la richiesta potrebbe fallire anche se il codice PHP è corretto.
  • Non hardcodare dati sensibili: token, password e chiavi API non dovrebbero essere inseriti direttamente nel codice sorgente. Meglio usare variabili d’ambiente o file di configurazione protetti.
  • Logga gli errori in modo controllato: in produzione evita di mostrare dettagli tecnici all’utente finale. Registra invece le informazioni in un file di log sicuro.

Se l’API richiede dati in formato JSON, puoi cambiare strategia: invece di http_build_query(), usi json_encode() e imposti Content-Type: application/json. Questo è molto comune nei servizi moderni.

Riepilogo

In questo tutorial abbiamo visto come usare cURL in PHP per inviare dati con una richiesta POST. È una delle operazioni più frequenti nello sviluppo web moderno e rappresenta un’ottima base per interagire con API esterne e servizi remoti.

I punti chiave da ricordare sono:

  • inizializzare la sessione con curl_init();
  • configurare la richiesta con curl_setopt_array();
  • inviare i dati tramite CURLOPT_POSTFIELDS;
  • gestire errori e codice HTTP in modo separato;
  • chiudere sempre la connessione con curl_close().

Con questa base puoi costruire integrazioni affidabili e leggibili, evitando gli errori più comuni quando si lavora con richieste HTTP in PHP.

Approfondisci con risorse ufficiali

  • Manuale PHP su cURL: documentazione ufficiale delle funzioni e delle opzioni disponibili.
  • curl_init(): per comprendere come iniziare una sessione cURL.
  • curl_setopt() e curl_setopt_array(): per configurare in dettaglio una richiesta.
  • curl_exec(): per eseguire la richiesta e ottenere la risposta.
  • curl_getinfo(): per leggere metadati utili come il codice HTTP.
  • curl_error() e curl_errno(): per diagnosticare i problemi di connessione o protocollo.

Se vuoi, nel prossimo passo posso scrivere un secondo tutorial dedicato a inviare JSON con cURL in PHP, con un esempio ancora più vicino alle API moderne.

Add as preferred source on Google
SHARE