URLW-API in PHP integrieren: vollständiger Leitfaden mit Code-Beispielen

Entwickeln Sie in PHP und möchten Sie die Erstellung von Kurzlinks in Ihre Anwendung integrieren? Die URLW REST-API ist so konzipiert, dass sie von jeder Programmiersprache aus einfach zu verwenden ist. Hier ist ein vollständiger Leitfaden zur Integration von URLW in Ihr PHP-Projekt mit produktionsreifen Code-Beispielen.

Voraussetzungen und Konfiguration

Um die URLW-API von PHP aus zu verwenden, benötigen Sie:

• PHP 7.4 oder höher
• Die aktivierte cURL-Erweiterung (prüfen Sie mit phpinfo() oder php -m | grep curl)
• Ihren URLW-API-Schlüssel (verfügbar unter Einstellungen → API in Ihrem Konto)

Beginnen Sie damit, Ihren API-Schlüssel sicher zu speichern, idealerweise in einer Umgebungsvariable oder einer nicht versionierten Konfigurationsdatei:

<?php
// Laden aus einer Umgebungsvariable (empfohlen)
$apiKey = getenv('URLW_API_KEY');

// Oder aus einer Konfigurationsdatei (niemals im versionierten Code!)
// $apiKey = 'ihr_api_schluessel_hier';

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

Eine URL in PHP kürzen

Hier ist eine vollständige PHP-Funktion zur Erstellung eines Kurzlinks über die URLW-API:

<?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('cURL-Fehler: ' . $curlError);
}

$data = json_decode($response, true);

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

return $data;
}

// Verwendung
try {
$result = urlwShorten(
    'https://beispiel.de/meine-lange-produktseite?ref=newsletter',
    getenv('URLW_API_KEY'),
    'sommer-aktion',
    'go.ihre-marke.de'
);

echo 'Kurzlink erstellt: ' . $result['short_url'] . PHP_EOL;
// Ausgabe: Kurzlink erstellt: https://go.ihre-marke.de/sommer-aktion

} catch (\RuntimeException $e) {
error_log('URLW-Fehler: ' . $e->getMessage());
// Fehler gemäß Ihrer Anwendungslogik behandeln
}

Statistiken eines Links abrufen

Um die Klickstatistiken eines Links in Ihrer Anwendung anzuzeigen:

<?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("Statistiken konnten nicht abgerufen werden (HTTP {$httpCode})");
}

return json_decode($response, true);
}

$stats = urlwGetStats('lnk_abc123', getenv('URLW_API_KEY'));
echo 'Gesamtklicks: ' . $stats['total_clicks'] . PHP_EOL;
echo 'Eindeutige Klicks: ' . $stats['unique_clicks'] . PHP_EOL;

Integration in ein Symfony- oder Laravel-Projekt

Für eine saubere Integration in ein Symfony- oder Laravel-Projekt erstellen Sie einen dedizierten Service:

• Symfony: Erstellen Sie eine UrlwClient-Klasse als Service mit Injektion des HttpClientInterface (Komponente symfony/http-client). Deklarieren Sie Ihren API-Schlüssel in services.yaml aus einer Umgebungsvariable URLW_API_KEY.
• Laravel: Erstellen Sie einen UrlwService in app/Services/ und registrieren Sie ihn im IoC-Container. Verwenden Sie config('services.urlw.key') für den Schlüssel.

Kapseln Sie in beiden Fällen die HTTP-Logik in diesem Service und rufen Sie ihn nie direkt aus Ihren Controllern heraus auf. Das erleichtert Unit-Tests mit Mocks.

Lesen Sie die vollständige URLW-API-Dokumentation für die vollständige Liste der Endpoints und Parameter. Beginnen Sie damit, Ihr URLW-Konto zu erstellen, um Ihren API-Schlüssel zu erhalten.