Intégrer l'API ClicAven en PHP : guide complet avec exemples de code

Vous développez en PHP et souhaitez intégrer la création de liens courts dans votre application ? L'API REST ClicAven est conçue pour être simple à utiliser depuis n'importe quel langage. Voici un guide complet pour intégrer ClicAven dans votre projet PHP, avec du code de production prêt à l'emploi.

Prérequis et configuration

Pour utiliser l'API ClicAven depuis PHP, vous avez besoin de :

• PHP 7.4 ou supérieur
• L'extension cURL activée (vérifiez avec phpinfo() ou php -m | grep curl)
• Votre clé API ClicAven (disponible dans Paramètres → API de votre compte)

Commencez par stocker votre clé API de manière sécurisée, idéalement dans une variable d'environnement ou un fichier de configuration non versionné :

<?php
// Chargement depuis une variable d'environnement (recommandé)
$apiKey = getenv('URLW_API_KEY');

// Ou depuis un fichier de config (jamais dans le code versionné !)
// $apiKey = 'votre_cle_api_ici';

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

Raccourcir une URL en PHP

Voici une fonction PHP complète pour créer un lien court via l'API ClicAven :

<?php
function urlwShorten(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(URLW_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('Erreur cURL : ' . $curlError);
}

$data = json_decode($response, true);

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

return $data;
}

// Utilisation
try {
$result = urlwShorten(
    'https://exemple.com/ma-longue-page-produit?ref=newsletter',
    getenv('URLW_API_KEY'),
    'promo-ete',
    'go.votre-marque.fr'
);

echo 'Lien court créé : ' . $result['short_url'] . PHP_EOL;
// Affiche : Lien court créé : https://go.votre-marque.fr/promo-ete

} catch (\RuntimeException $e) {
error_log('Erreur ClicAven : ' . $e->getMessage());
// Gérer l'erreur selon votre logique applicative
}

Récupérer les statistiques d'un lien

Pour afficher les statistiques de clic d'un lien dans votre application :

<?php
function urlwGetStats(string $linkId, string $apiKey): array
{
$ch = curl_init(URLW_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("Impossible de récupérer les stats (HTTP {$httpCode})");
}

return json_decode($response, true);
}

$stats = urlwGetStats('lnk_abc123', getenv('URLW_API_KEY'));
echo 'Clics totaux : ' . $stats['total_clicks'] . PHP_EOL;
echo 'Clics uniques : ' . $stats['unique_clicks'] . PHP_EOL;

Intégration dans un projet Symfony ou Laravel

Pour une intégration propre dans un projet Symfony ou Laravel, créez un service dédié :

• Symfony : créez une classe ClicavenClient comme service avec injection du HttpClientInterface (composant symfony/http-client). Déclarez votre clé API dans services.yaml depuis une variable d'environnement URLW_API_KEY.
• Laravel : créez un ClicavenService dans app/Services/ et enregistrez-le dans le container IoC. Utilisez config('services.clicaven.key') pour la clé.

Dans les deux cas, encapsulez la logique HTTP dans ce service et ne l'appelez jamais directement depuis vos contrôleurs. Cela facilite les tests unitaires avec des mocks.

Consultez la documentation complète de l'API ClicAven pour la liste exhaustive des endpoints et des paramètres. Commencez par créer votre compte ClicAven pour obtenir votre clé API.