Intégrer l'API URLW 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 URLW est conçue pour être simple à utiliser depuis n'importe quel langage. Voici un guide complet pour intégrer URLW dans votre projet PHP, avec du code de production prêt à l'emploi.

Prérequis et configuration

Pour utiliser l'API URLW 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 URLW (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://urlw.fr/api/v1');

Raccourcir une URL en PHP

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

<?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 URLW ({$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 URLW : ' . $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 UrlwClient 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 UrlwService dans app/Services/ et enregistrez-le dans le container IoC. Utilisez config('services.urlw.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 URLW pour la liste exhaustive des endpoints et des paramètres. Commencez par créer votre compte URLW pour obtenir votre clé API.