API ClicAven in PHP: guida con esempi di codice

Sviluppate in PHP e volete integrare la creazione di link brevi nella vostra applicazione? L'API REST ClicAven è progettata per essere semplice da usare da qualsiasi linguaggio. Ecco una guida completa per integrare ClicAven nel vostro progetto PHP, con codice di produzione pronto all'uso.

Prerequisiti e configurazione

Per utilizzare l'API ClicAven da PHP, avete bisogno di:

• PHP 7.4 o superiore
• L'estensione cURL attivata (verificate con phpinfo() o php -m | grep curl)
• La vostra chiave API ClicAven (disponibile in Impostazioni → API del vostro account)

Iniziate archiviando la vostra chiave API in modo sicuro, idealmente in una variabile d'ambiente o in un file di configurazione non versionato:

<?php
// Caricamento da variabile d'ambiente (raccomandato)
$apiKey = getenv('CLICAVEN_API_KEY');

// O da file di config (mai nel codice versionato!)
// $apiKey = 'la_vostra_chiave_api_qui';

define('CLICAVEN_API_BASE', 'https://clicaven.com/api/v1');

Abbreviare un URL in PHP

Ecco una funzione PHP completa per creare un link breve tramite l'API ClicAven:

<?php
function clicavenShorten(string $url, string $apiKey, string $slug = '', string $domain = ''): array
{
$payload = ['url' => $url];

if (!empty($slug)) {
    $payload['slug'] = $slug;
}
if (!empty($domain)) {
    $payload['domain'] = $domain;
}

$ch = curl_init(CLICAVEN_API_BASE . '/links');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
        'Accept: application/json',
    ],
    CURLOPT_TIMEOUT        => 10,
    CURLOPT_SSL_VERIFYPEER => true,
]);

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

if ($curlError) {
    throw new \RuntimeException('Errore cURL: ' . $curlError);
}

$data = json_decode($response, true);

if ($httpCode < 200 || $httpCode >= 300) {
    $message = $data['message'] ?? 'Errore sconosciuto';
    throw new \RuntimeException("Errore API ClicAven ({$httpCode}): {$message}");
}

return $data;
}

// Utilizzo
try {
$result = clicavenShorten(
    'https://esempio.com/la-mia-lunga-pagina-prodotto?ref=newsletter',
    getenv('CLICAVEN_API_KEY'),
    'promo-estate',
    'go.vostro-brand.it'
);

echo 'Link breve creato: ' . $result['short_url'] . PHP_EOL;
// Output: Link breve creato: https://go.vostro-brand.it/promo-estate

} catch (\RuntimeException $e) {
error_log('Errore ClicAven: ' . $e->getMessage());
// Gestire l'errore secondo la logica applicativa
}

Recuperare le statistiche di un link

Per visualizzare le statistiche di clic di un link nella vostra applicazione:

<?php
function clicavenGetStats(string $linkId, string $apiKey): array
{
$ch = curl_init(CLICAVEN_API_BASE . '/links/' . urlencode($linkId) . '/stats');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Accept: application/json',
    ],
    CURLOPT_TIMEOUT        => 10,
]);

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

if ($httpCode !== 200) {
    throw new \RuntimeException("Impossibile recuperare le statistiche (HTTP {$httpCode})");
}

return json_decode($response, true);
}

$stats = clicavenGetStats('lnk_abc123', getenv('CLICAVEN_API_KEY'));
echo 'Clic totali: ' . $stats['total_clicks'] . PHP_EOL;
echo 'Clic unici: ' . $stats['unique_clicks'] . PHP_EOL;

Integrazione in un progetto Symfony o Laravel

Per un'integrazione pulita in un progetto Symfony o Laravel, create un servizio dedicato:

• Symfony: create una classe ClicavenClient come servizio con iniezione di HttpClientInterface (componente symfony/http-client). Dichiarate la vostra chiave API in services.yaml da una variabile d'ambiente CLICAVEN_API_KEY.
• Laravel: create un ClicavenService in app/Services/ e registratelo nel container IoC. Utilizzate config('services.clicaven.key') per la chiave.

In entrambi i casi, incapsulate la logica HTTP in questo servizio e non chiamatelo mai direttamente dai vostri controller. Questo facilita i test unitari con mock.

Consultate la documentazione completa dell'API ClicAven per l'elenco esaustivo degli endpoint e dei parametri. Iniziate creando il vostro account ClicAven per ottenere la vostra chiave API.