Getting Started

Install the package and publish its config:

composer require phpsa/laravel-yourls-plugin
php artisan vendor:publish --provider="Phpsa\LaravelYourls\YourlsServiceProvider" --tag="config"

Set the two values you actually need in .env:

YOURLS_URL=https://sho.rt
YOURLS_SIGNATURE=your-yourls-signature-token

YOURLS_URL is the YOURLS installation base URL, not the API endpoint. The signature is the token from YOURLS’ “Secure passwordless API call” section, not your admin password.

The first useful use case is shortening a link inside a controller or service:

use Phpsa\LaravelYourls\Facades\Yourls;

$short = Yourls::shorten('https://example.com/a/long/campaign/link');

Before building around it, do a one-off dump() or dd() of the return value against your YOURLS instance. These wrappers are thin, and depending on the version the method may return the YOURLS JSON payload (with status, shorturl, url, title, keyword) or just the short URL string. Confirm that first, then decide whether you need a small adapter in your app.

If package discovery is disabled, register the service provider and facade alias manually in config/app.php. If the package does not support your Laravel version, check composer.json constraints and test on a branch before adopting it; the last release was December 2023.

Implementation Patterns

Wrap it in your own service. Do not scatter Yourls::shorten() calls across controllers. Create an application service such as App\Services\ShortLinkService that owns URL shortening, stores the mapping, and normalises the package response:

class ShortLinkService
{
    public function shorten(string $url, ?string $keyword = null): ShortLink
    {
        $response = Yourls::shorten($url, $keyword);

        // Persist shorturl, keyword, target URL, and a local identifier.
        // Normalise the package return shape here, not in controllers.
    }
}

This gives you one place to add logging, retries, exception mapping, and tests.

Store the result. YOURLS already stores links, but your Laravel app usually needs its own record: the local model that owns the link, the campaign, the user, and the short URL. Store at minimum long_url, short_url, keyword, and created_by. Treat YOURLS as the redirect engine, not your source of truth.

Use custom keywords deliberately. A custom keyword is typically the second argument:

Yourls::shorten($url, 'spring-sale-2024');

Generate keywords from a slug plus a short random suffix, e.g. spring-sale-2024-a8f3, to avoid collisions. Check the YOURLS response before assuming success.

Batch and background work. For imports or bulk campaigns, dispatch jobs and throttle them. YOURLS is a PHP app backed by MySQL; hammering it from a queue worker with no delay will produce timeouts and duplicate-looking failures. Use Bus::batch() and a per-job delay or rate limiter.

Testing. If the package uses Laravel’s HTTP client, fake the YOURLS endpoint:

Http::fake([
    '*/yourls-api.php*' => Http::response([
        'status' => 'success',
        'shorturl' => 'https://sho.rt/abc',
        'url' => 'https://example.com/long',
        'keyword' => 'abc',
    ]),
]);

If it uses Guzzle directly, bind a fake client or mock your own ShortLinkService instead. Either way, test the failure path: YOURLS returns HTTP 200 with status: fail for many errors.

Multiple environments or instances. Keep one config per environment. If you need multiple YOURLS installations, avoid changing global config at runtime; instantiate a small client per instance or create a dedicated service configured from a database row.

Gotchas and Tips

Trailing slashes break the endpoint. YOURLS_URL=https://sho.rt/ can produce https://sho.rt//yourls-api.php. Use https://sho.rt.
HTTP 200 does not mean success. YOURLS commonly returns {"status":"fail","code":"...","message":"..."} with a 200 response. Always check status before reading shorturl.
Keyword collisions are normal. A duplicate keyword fails. Either generate unique keywords up front or catch the failure and retry with a suffix.
The signature is not a password. Use the signature token from YOURLS. Also confirm the API is enabled and reachable from the Laravel host; firewall and DNS issues are common.
JSON vs XML. If the package does not force format=json, set it in the config or pass it through. XML responses are painful to debug in Laravel.
Config cache surprises. After changing YOURLS_URL or YOURLS_SIGNATURE, run php artisan config:clear. In production, run php artisan config:cache as part of deploy.
No built-in retries or circuit breaking. Add Http::retry() in your wrapper if the package exposes the client, or implement retry logic in your service. Do not retry aggressively on keyword collisions.
Timeouts should be short. A URL shortener call in a web request should not hang for 30 seconds. Set a 3–5 second timeout and fail gracefully, falling back to storing the long URL without a short link if necessary.
Debug with the raw payload. When something fails, log the full YOURLS response, the endpoint URL, and the action. Never log the signature token.
Laravel version drift. The package is small and last released in 2023. If you are on Laravel 11 or 12, test installation and the facade binding early. If it fails, wrapping the YOURLS API directly with Http is only a few lines.
Extension point is your wrapper, not the vendor code. The package is intentionally thin. Put retries, DTOs, logging, exception handling, and multi-instance support in your own service rather than editing vendor/.

Laravel Yourls Plugin Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips