Integrar a API URLW em PHP: guia completo com exemplos de código

Está a desenvolver em PHP e pretende integrar a criação de links curtos na sua aplicação? A API REST URLW foi concebida para ser simples de utilizar a partir de qualquer linguagem. Eis um guia completo para integrar o URLW no seu projeto PHP, com código de produção pronto a utilizar.

Pré-requisitos e configuração

Para utilizar a API URLW a partir de PHP, precisa de:

• PHP 7.4 ou superior
• A extensão cURL ativada (verifique com phpinfo() ou php -m | grep curl)
• A sua chave API URLW (disponível em Definições → API da sua conta)

Comece por armazenar a sua chave API de forma segura, idealmente numa variável de ambiente ou num ficheiro de configuração não versionado:

<?php
// Carregamento a partir de uma variável de ambiente (recomendado)
$apiKey = getenv('URLW_API_KEY');

// Ou a partir de um ficheiro de config (nunca no código versionado!)
// $apiKey = 'a_sua_chave_api_aqui';

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

Encurtar um URL em PHP

Eis uma função PHP completa para criar um link curto via 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('Erro cURL: ' . $curlError);
}

$data = json_decode($response, true);

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

return $data;
}

// Utilização
try {
$result = urlwShorten(
    'https://exemplo.com/a-minha-longa-pagina-de-produto?ref=newsletter',
    getenv('URLW_API_KEY'),
    'promo-verao',
    'go.a-sua-marca.fr'
);

echo 'Link curto criado: ' . $result['short_url'] . PHP_EOL;
// Exibe: Link curto criado: https://go.a-sua-marca.fr/promo-verao

} catch (\RuntimeException $e) {
error_log('Erro URLW: ' . $e->getMessage());
// Trate o erro de acordo com a sua lógica aplicacional
}

Recuperar as estatísticas de um link

Para exibir as estatísticas de cliques de um link na sua aplicação:

<?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("Impossível recuperar as estatísticas (HTTP {$httpCode})");
}

return json_decode($response, true);
}

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

Integração num projeto Symfony ou Laravel

Para uma integração limpa num projeto Symfony ou Laravel, crie um serviço dedicado:

• Symfony: crie uma classe UrlwClient como serviço com injeção do HttpClientInterface (componente symfony/http-client). Declare a sua chave API em services.yaml a partir de uma variável de ambiente URLW_API_KEY.
• Laravel: crie um UrlwService em app/Services/ e registe-o no container IoC. Utilize config('services.urlw.key') para a chave.

Em ambos os casos, encapsule a lógica HTTP neste serviço e nunca a chame diretamente a partir dos seus controladores. Isso facilita os testes unitários com mocks.

Consulte a documentação completa da API URLW para a lista exaustiva de endpoints e parâmetros. Comece por criar a sua conta URLW para obter a sua chave API.