Integrare OpenAI in un modulo custom.

Portare un LLM dentro un modulo Joomla (o un componente custom) è possibile senza framework esterni: basta una chiave API OpenAI, una chiamata HTTP e un po' di gestione degli errori. In questo articolo vediamo come incapsulare la chiamata in una classe riutilizzabile e esporla in un modulo che l'utente può usare dal frontend.

Cosa ti serve

• Un account OpenAI e una API key (da non committare mai nel codice: usa variabili d'ambiente o la configurazione protetta di Joomla).
• PHP con curl o l'estensione HTTP per le richieste.
• Un modulo Joomla 5 che raccoglie l'input dell'utente (es. un campo testo) e passa il valore a un helper che chiama l'API.

Chiamata API da PHP

L'endpoint Chat Completions richiede un JSON con model, messages e opzionalmente max_tokens. Ecco un esempio minimo di helper che invia la richiesta e restituisce il testo della risposta (o null in caso di errore):

// Helper chiamata OpenAI Chat Completions
public static function ask(string $userMessage, string $apiKey): ?string
{
    $url = 'https://api.openai.com/v1/chat/completions';
    $body = [
        'model' => 'gpt-4o-mini',
        'messages' => [
            ['role' => 'user', 'content' => $userMessage]
        ],
        'max_tokens' => 500
    ];

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => json_encode($body),
        CURLOPT_HTTPHEADER => [
            'Content-Type: application/json',
            'Authorization: Bearer ' . $apiKey
        ],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 30
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200 || !$response) {
        return null;
    }
    $data = json_decode($response, true);
    return $data['choices'][0]['message']['content'] ?? null;
}

Nel modulo Joomla leggi l'API key dalla configurazione globale o da un parametro del modulo (sempre protetto e non esposto in frontend). Limita la lunghezza dell'input utente e applica un rate limit per evitare abusi. Per scenari più complessi (RAG, contesto aziendale) puoi costruire un array di messages che include anche il contesto recuperato da un database o da un vector store.

In sintesi: integrare OpenAI in un modulo custom è alla portata di uno sviluppatore Joomla che conosce PHP e le API REST. Il passo successivo è arricchire il contesto (RAG) e, se serve, delegare le chiamate a un servizio Python esterno per pipeline più pesanti.