STOPBOT SmartURLs V2 - PHP

This is a PHP SmartURLs client for the STOPBOT V2 API.

It is based on the public legacy SmartURLs PHP flow, but updated for the V2 response shape:

• API endpoint: https://api.stopbot.net/services/shorterlink
• Normal redirect response uses flat fields such as redirectTo, blockAccess, jsResponse, and uniqueCode
• JavaScript verification uses /rsc/rjs.json?token=...
• The server sends js=1, keyname, and code={uniqueCode} back to the STOPBOT API

Install

Upload the contents of this php-v2 folder to your SmartURLs domain.

Set your API key through an environment variable:

STOPBOT_API_KEY=your_api_key

Or create config.local.php next to config.php:

<?php
$StopbotApiKey = 'your_api_key';
$SmartUrlsSigningKey = 'change_this_random_secret';
$SmartUrlsTrustProxyHeaders = true;

Do not commit config.local.php.

STOPBOT Panel Configuration

Before using this client, create or configure your SmartURLs key in the STOPBOT panel:

1. Sign in to panel.stopbot.net.
2. Open the SmartURLs or Shortlink section.
3. Create a new SmartURLs key, or open an existing one.
4. Configure the redirect destination and protection rules from the panel.
5. Copy the SmartURLs keyname.

The keyname is the value used in your public SmartURLs URL.

For example, if the panel shows a SmartURLs page like:

https://panel.stopbot.net/shortlink-swWV8j

then the keyname is:

swWV8j

After uploading this PHP client to your domain, visitors should access:

https://your-domain.example/swWV8j

This client sends swWV8j to the STOPBOT V2 API as the keyname parameter.

Important notes:

• The API key configured in config.local.php or STOPBOT_API_KEY must belong to the same STOPBOT account that owns the SmartURLs keyname.
• Do not expose your API key in frontend JavaScript, public repositories, logs, screenshots, or support messages.
• Use the full public domain URL only for visitors. Use only the keyname when configuring or testing this PHP client.

Apache Rewrite

The included .htaccess maps paths like:

https://your-domain.example/keyname

to:

index.php?q=keyname

Nginx Integration

Nginx does not read .htaccess, so you must add the rewrite rule in your Nginx server block.

Example configuration:

server {
    listen 80;
    server_name your-domain.example;

    root /var/www/smarturls;
    index index.php;

    location / {
        try_files $uri $uri/ @smarturls;
    }

    location @smarturls {
        rewrite ^/(.*)$ /index.php?q=$1&$args last;
    }

    location ~ \.php$ {
        try_files $fastcgi_script_name =404;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    }

    location = /config.local.php {
        deny all;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Adjust these values for your server:

• server_name should use your SmartURLs domain.
• root should point to the uploaded php-v2 directory or the web root that contains index.php.
• fastcgi_pass must match your PHP-FPM socket or TCP address.

After changing the configuration, test and reload Nginx:

sudo nginx -t
sudo systemctl reload nginx

With this setup, a request like:

https://your-domain.example/keyname

is routed internally to:

index.php?q=keyname

The JavaScript verification route also works through the same rewrite:

https://your-domain.example/rsc/rjs.json?token=...

JavaScript Verification Flow

When the V2 API returns jsResponse=1, this client renders a hidden browser check page.

The browser calls:

/rsc/rjs.json?token=...

The token is signed by the server and contains the keyname, the API uniqueCode, and an expiry timestamp.

The PHP server verifies the token, then calls STOPBOT V2 with:

js=1&keyname={keyname}&code={uniqueCode}

This is different from the legacy V1 flow, which called rjs.json with only the original keyname.