Integrar la API de URLW en PHP: guía completa con ejemplos de código

¿Desarrolla en PHP y desea integrar la creación de enlaces cortos en su aplicación? La API REST de URLW está diseñada para ser sencilla de usar desde cualquier lenguaje. Aquí tiene una guía completa para integrar URLW en su proyecto PHP, con código de producción listo para usar.

Requisitos previos y configuración

Para utilizar la API de URLW desde PHP, necesita:

• PHP 7.4 o superior
• La extensión cURL activada (verifíquelo con phpinfo() o php -m | grep curl)
• Su clave API de URLW (disponible en Ajustes → API de su cuenta)

Comience almacenando su clave API de forma segura, preferiblemente en una variable de entorno o un archivo de configuración no versionado:

<?php
// Carga desde una variable de entorno (recomendado)
$apiKey = getenv('URLW_API_KEY');

// O desde un archivo de config (¡nunca en el código versionado!)
// $apiKey = 'su_clave_api_aqui';

define('URLW_API_BASE', 'https://urlw.fr/api/v1');

Acortar una URL en PHP

Aquí tiene una función PHP completa para crear un enlace corto mediante la API de 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('Error cURL: ' . $curlError);
}

$data = json_decode($response, true);

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

return $data;
}

// Uso
try {
$result = urlwShorten(
    'https://ejemplo.com/mi-larga-pagina-producto?ref=newsletter',
    getenv('URLW_API_KEY'),
    'promo-verano',
    'go.su-marca.es'
);

echo 'Enlace corto creado: ' . $result['short_url'] . PHP_EOL;
// Muestra: Enlace corto creado: https://go.su-marca.es/promo-verano

} catch (\RuntimeException $e) {
error_log('Error URLW: ' . $e->getMessage());
// Gestione el error según su lógica de aplicación
}

Obtener las estadísticas de un enlace

Para mostrar las estadísticas de clics de un enlace en su aplicación:

<?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("No se pueden obtener las estadísticas (HTTP {$httpCode})");
}

return json_decode($response, true);
}

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

Integración en un proyecto Symfony o Laravel

Para una integración limpia en un proyecto Symfony o Laravel, cree un servicio dedicado:

• Symfony: cree una clase UrlwClient como servicio con inyección del HttpClientInterface (componente symfony/http-client). Declare su clave API en services.yaml desde una variable de entorno URLW_API_KEY.
• Laravel: cree un UrlwService en app/Services/ y regístrelo en el contenedor IoC. Use config('services.urlw.key') para la clave.

En ambos casos, encapsule la lógica HTTP en este servicio y nunca la llame directamente desde sus controladores. Esto facilita las pruebas unitarias con mocks.

Consulte la documentación completa de la API de URLW para la lista exhaustiva de endpoints y parámetros. Empiece por crear su cuenta URLW para obtener su clave API.