YOURLS

https://github.com/yourls/yourls
Admin
YOURLS is a set of PHP scripts that allows you to run your own URL shortener on your server,...
Tokens:49,040
Snippets:377
Trust Score:7.9
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install via Composer

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/spatie/array-to-xml/README.md

Install the package using Composer.

```bash
composer require spatie/array-to-xml
```

--------------------------------

### Usage example for MaxMind\Db\Reader

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/maxmind-db/reader/README.md

Complete example showing how to open a database, retrieve a record, get record with prefix length, and close the reader.

```php
<?php
require_once 'vendor/autoload.php';

use MaxMind\Db\Reader;

$ipAddress = '24.24.24.24';
$databaseFile = 'GeoIP2-City.mmdb';

$reader = new Reader($databaseFile);

// get returns just the record for the IP address
print_r($reader->get($ipAddress));

// getWithPrefixLen returns an array containing the record and the
// associated prefix length for that record.
print_r($reader->getWithPrefixLen($ipAddress));

$reader->close();
```

--------------------------------

### Install composer/ca-bundle with Composer

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/composer/ca-bundle/README.md

Install the latest version of the composer/ca-bundle library using Composer.

```bash
$ composer require composer/ca-bundle
```

--------------------------------

### Full Web Service Client Example

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/geoip2/geoip2/README.md

Complete example showing how to create a reusable client, perform a city lookup, and print various fields from the returned record. Replace the account ID, license key, and method as needed.

```php
<?php
require_once 'vendor/autoload.php';
use GeoIp2\WebService\Client;

// This creates a Client object that can be reused across requests.
// Replace "42" with your account ID and "license_key" with your license
// key. Set the "host" to "geolite.info" in the fourth argument options
// array to use the GeoLite2 web service instead of the GeoIP2 web
// service.
$client = new Client(42, 'abcdef123456');

// Replace "city" with the method corresponding to the web service that
// you are using, e.g., "country", "insights".
$record = $client->city('128.101.101.101');

print($record->country->isoCode . "\n"); // 'US'
print($record->country->name . "\n"); // 'United States'
print($record->country->names['zh-CN'] . "\n"); // '美国'

print($record->mostSpecificSubdivision->name . "\n"); // 'Minnesota'
print($record->mostSpecificSubdivision->isoCode . "\n"); // 'MN'

print($record->city->name . "\n"); // 'Minneapolis'

print($record->postal->code . "\n"); // '55455'

print($record->location->latitude . "\n"); // 44.9733
print($record->location->longitude . "\n"); // -93.2323

print($record->traits->network . "\n"); // '128.101.101.101/32'

```

--------------------------------

### Output HTML for the PHP example

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/ozh/bookmarkletgen/README.md

The output of the PHP example: a bookmarklet link with the crunched and encoded JavaScript.

```html
<a href="javascript:(function()%7Bvar%20link%3D%22https%3A%2F%2Fgoogle.com%2F%22%3Bwindow.location%3Dlink%3B%7D)()%3B">bookmarklet</a>
```

--------------------------------

### Install C extension via PECL

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/maxmind-db/reader/README.md

Legacy method to install the extension from PECL after installing libmaxminddb.

```bash
pecl install maxminddb
```

--------------------------------

### Install php-maxminddb via dnf on Fedora

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/maxmind-db/reader/README.md

Install the RPM package on Fedora using dnf.

```bash
dnf install php-maxminddb
```

--------------------------------

### Install POMO with Composer

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/pomo/pomo/README.md

Installs the POMO library via Composer.

```console
composer require pomo/pomo
```

--------------------------------

### Install with Composer

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/ozh/http_build_url/README.md

Install the ozh/http_build_url package via Composer. Requires PHP 8.1+.

```sh
composer require ozh/http_build_url
```

--------------------------------

### Build C extension from source

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/maxmind-db/reader/README.md

Commands to compile and install the extension from the source distribution.

```bash
cd ext
phpize
./configure
make
make test
sudo make install
```

--------------------------------

### Install source from GitHub

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/rmccue/requests/README.md

Steps to clone the Requests repository and include the autoloader in your scripts, then register it.

```bash
$ git clone git://github.com/WordPress/Requests.git
```

```php
require_once '/path/to/Requests/src/Autoload.php';
```

```php
WpOrg\Requests\Autoload::register();
```

--------------------------------

### Install C Extension with PIE

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/maxmind-db/reader/README.md

Installs the C extension for MaxMind DB Reader via PIE, which provides significantly faster IP lookups. Requires the libmaxminddb C library.

```bash
pie install maxmind-db/reader-ext
```

--------------------------------

### Prettify XML output with ArrayToXml::prettify()

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/spatie/array-to-xml/README.md

Shows how to create an ArrayToXml instance from an array and then call prettify() to produce indented XML, or call toXml() without prettification to get a single-line XML string. The example uses the same input array for both variants.

```php
$array = [
    'Good guy' => [
        'name' => 'Luke Skywalker',
        'weapon' => 'Lightsaber'
    ],
    'Bad guy' => [
        'name' => 'Sauron',
        'weapon' => 'Evil Eye'
    ]
];
$arrayToXml = new ArrayToXml($array);
```

```php
$arrayToXml->prettify()->toXml();
```

```xml
<?xml version="1.0"?>
<root>
    <Good_guy>
        <name>Luke Skywalker</name>
        <weapon>Lightsaber</weapon>
    </Good_guy>
    <Bad_guy>
        <name>Sauron</name>
        <weapon>Evil Eye</weapon>
    </Bad_guy>
</root>
```

```php
$arrayToXml->toXml();
```

```xml
<?xml version="1.0"?>
<root><Good_guy><name>Luke Skywalker</name><weapon>Lightsaber</weapon></Good_guy><Bad_guy><name>Sauron</name><weapon>Evil Eye</weapon></Bad_guy></root>
```

--------------------------------

### Install PHPUnit with Composer

Source: https://github.com/yourls/yourls/blob/master/tests/README.md

Installs PHPUnit and other test dependencies for the YOURLS test suite. Run from the YOURLS root directory.

```bash
composer -d tests/ install
```

--------------------------------

### Install Pure PHP Reader with Composer

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/maxmind-db/reader/README.md

Installs the pure PHP implementation of the MaxMind DB Reader via Composer. Creates composer.json, composer.lock, and the vendor directory.

```bash
php composer.phar require maxmind-db/reader:^1.13.1
```

--------------------------------

### Create Client with Language and Host Options

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/geoip2/geoip2/README.md

Creates a client with additional arguments: the third argument sets language preferences for the ->name method, and the fourth sets options such as host and timeout. This example uses the GeoLite2 web service by setting the host to geolite.info.

```php
$client = new Client(42, 'abcdef123456', ['en'], ['host' => 'geolite.info']);
```

--------------------------------

### Run tests

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/ozh/http_build_url/README.md

Commands to install dependencies and run the test suite using PHPUnit.

```sh
composer install
vendor/bin/phpunit
```

--------------------------------

### PHP example: crunching JavaScript into a bookmarklet

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/ozh/bookmarkletgen/README.md

Example usage of the library: it crunches a JavaScript snippet and prints an HTML link with the resulting bookmarklet URL. Requires either Composer's autoload or manual inclusion of the class file.

```php
<?php
$javascript = <<<CODE
var link="https://google.com/"; // destination
window.location = link;
CODE;

require 'vendor/autoload.php'; // if you install using Composer
require 'path/to/Bookmarkletgen.php'; // otherwise

$book = new \Ozh\Bookmarkletgen\Bookmarkletgen;
$link = $book->crunch( $javascript );

printf( '<a href="%s">bookmarklet</a>', $link );
```

--------------------------------

### Install psr/log with Composer

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/psr/log/README.md

Install the psr/log package via Composer to use the PSR-3 logger interface.

```bash
composer require psr/log
```

--------------------------------

### Install php-maxminddb via yum on CentOS/RHEL 7

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/maxmind-db/reader/README.md

Install the RPM package on CentOS or RHEL 7 after enabling EPEL.

```bash
yum install php-maxminddb
```

--------------------------------

### Basic GET request with authentication and headers

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/rmccue/requests/README.md

Shows how to send a GET request using WpOrg\Requests\Requests::get() with custom headers and authentication options. The response status code, headers, and body are then dumped.

```php
$headers = array('Accept' => 'application/json');
$options = array('auth' => array('user', 'pass'));
$request = WpOrg\Requests\Requests::get('https://api.github.com/gists', $headers, $options);

var_dump($request->status_code);
// int(200)

var_dump($request->headers['content-type']);
// string(31) "application/json; charset=utf-8"

var_dump($request->body);
// string(26891) "[...]"
```

--------------------------------

### Install source from zip/tarball

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/rmccue/requests/README.md

Commands to download and extract the Requests source from a tarball or zipball.

```bash
$ curl -L https://github.com/WordPress/Requests/tarball/stable | tar xzv
(or)
$ wget https://github.com/WordPress/Requests/tarball/stable -O - | tar xzv
```

--------------------------------

### Compression example: before and after

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/ozh/bookmarkletgen/README.md

Shows the compression behavior of the library: it removes extra spaces but preserves spaces inside literal strings, and encodes the result for use in a bookmarklet URL.

```javascript
function   someName(   param   ) {
     alert( "this is a string" )
}
```

```js
function%20someName(param){alert("this%20is%20a%20string")}
```

--------------------------------

### Install GeoIP2 via Composer

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/geoip2/geoip2/README.md

Installs the GeoIP2 PHP API package via Composer. This command creates composer.json and composer.lock files and a vendor directory in the project root.

```sh
php composer.phar require geoip2/geoip2:~2.0
```

--------------------------------

### Autoload POMO with Composer

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/pomo/pomo/README.md

Shows how to include the Composer autoloader and use the POMO\MO class after installation.

```php
<?php

require 'vendor/autoload.php';

use POMO\MO;

[...]
```

--------------------------------

### Composer requirement for ozh/bookmarkletgen

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/ozh/bookmarkletgen/README.md

Add this requirement to your composer.json file and run composer install to install the library via Composer.

```json
{
    "require": {
        "ozh/bookmarkletgen": "~1.3"
    }
}
```

--------------------------------

### Expected Test Suite Output

Source: https://github.com/yourls/yourls/blob/master/tests/README.md

Example output from running the YOURLS test suite, showing progress and a successful summary.

```text
YOURLS installed, starting PHPUnit

PHPUnit by Sebastian Bergmann and contributors.

Configuration: ...\phpunit.xml.dist

...............................................................  63 / 519 ( 12%)
............................................................... 126 / 519 ( 24%)
............................................................... 189 / 519 ( 36%)
............................................................... 252 / 519 ( 48%)
............................................................... 315 / 519 ( 60%)
............................................................... 378 / 519 ( 72%)
............................................................... 441 / 519 ( 84%)
............................................................... 504 / 519 ( 97%)
...............                                                 519 / 519 (100%)

Time: 6.06 seconds, Memory: 24.25Mb

OK (519 tests, 1123 assertions)
```

--------------------------------

### Copy Test Configuration File

Source: https://github.com/yourls/yourls/blob/master/tests/README.md

Copies the sample test configuration file to the active configuration file. Edit the copied file to match your MySQL setup.

```bash
cp tests/data/config/yourls-tests-config-sample.php tests/yourls-tests-config.php
```

--------------------------------

### Include standalone autoload.php

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/maxmind-db/reader/README.md

Required for standalone installation without Composer. Include this file before using the library.

```php
require('/path/to/MaxMind-DB-Reader-php/autoload.php');
```

--------------------------------

### Install with Composer

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/rmccue/requests/README.md

Commands to add the Requests library as a dependency using Composer, either via the command line or by adding to composer.json.

```sh
composer require rmccue/requests
```

```json
{
    "require": {
        "rmccue/requests": "^2.0"
    }
}
```

--------------------------------

### http_build_url()

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/ozh/http_build_url/README.md

Documentation for the http_build_url() function, including its signature, parameters, flags, and usage examples.

```APIDOC
## http_build_url()

### Description
Builds a URL by merging parts from an array or string into a base URL, according to flags. This is an implementation of the `pecl_http` function for environments without that extension.

### Method
Function

### Signature
```php
http_build_url(
    string|array $url,
    string|array|null $parts = [],
    int $flags = HTTP_URL_REPLACE,
    ?array &$new_url = null
): string
```

### Parameters
- **$url** (string|array) - Required - The base URL, either as a string or an associative array in the shape returned by `parse_url()`.
- **$parts** (string|array|null) - Optional - The parts to merge into the base URL, either as a string or an associative array. Defaults to `[]`.
- **$flags** (int) - Optional - Bitmask of `HTTP_URL_*` constants controlling the merge behavior. Defaults to `HTTP_URL_REPLACE`.
- **&$new_url** (?array) - Optional - If provided, filled with the parts of the resulting URL as `parse_url()` would return them.

### Return Value
Returns the resulting URL as a string.

### Flags
| Constant | Effect |
|----------|--------|
| `HTTP_URL_REPLACE` | Replace every part given in `$parts` (default) |
| `HTTP_URL_JOIN_PATH` | Join the path of `$parts` onto the path of `$url` |
| `HTTP_URL_JOIN_QUERY` | Merge the query strings of `$url` and `$parts` |
| `HTTP_URL_STRIP_USER` | Strip the user |
| `HTTP_URL_STRIP_PASS` | Strip the password |
| `HTTP_URL_STRIP_AUTH` | Strip user and password |
| `HTTP_URL_STRIP_PORT` | Strip the port |
| `HTTP_URL_STRIP_PATH` | Strip the path |
| `HTTP_URL_STRIP_QUERY` | Strip the query string |
| `HTTP_URL_STRIP_FRAGMENT` | Strip the fragment |
| `HTTP_URL_STRIP_ALL` | Strip everything but scheme and host |

### Examples
```php
// Replace parts of a URL (the default)
echo http_build_url('http://example.com/some/path?a=b', ['host' => 'example.org']);
// http://example.org/some/path?a=b

// Join a relative path, merge the query string, drop auth and fragment
echo http_build_url(
    'http://user@www.example.com/pub/index.php?a=b#files',
    [
        'scheme' => 'ftp',
        'host'   => 'ftp.example.com',
        'path'   => 'files/current/',
        'query'  => 'a=c',
    ],
    HTTP_URL_STRIP_AUTH | HTTP_URL_JOIN_PATH | HTTP_URL_JOIN_QUERY | HTTP_URL_STRIP_FRAGMENT
);
// ftp://ftp.example.com/pub/files/current/?a=c

// Get the composed parts back
http_build_url('http://example.com/path?a=b', [], HTTP_URL_STRIP_QUERY, $parts);
// $parts === ['scheme' => 'http', 'host' => 'example.com', 'path' => '/path']
```
```

--------------------------------

### Run a single set of Requests tests with PHPUnit

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/rmccue/requests/README.md

Run a specific test set by specifying its name, for example 'Transport/cURL'.

```bash
$ phpunit Transport/cURL
```

--------------------------------

### Get composed parts back

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/ozh/http_build_url/README.md

Shows how to retrieve the parts of the resulting URL as an array using the $new_url reference parameter. The expected result is shown in the comment.

```php
// Get the composed parts back
http_build_url('http://example.com/path?a=b', [], HTTP_URL_STRIP_QUERY, $parts);
// $parts === ['scheme' => 'http', 'host' => 'example.com', 'path' => '/path']
```

--------------------------------

### Add processing instruction with ArrayToXml::addProcessingInstruction()

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/spatie/array-to-xml/README.md

Shows how to prepend a processing instruction before the root element using addProcessingInstruction($target, $data). The example adds an xml-stylesheet instruction and then calls toXml() to produce the final XML.

```php
$arrayToXml = new ArrayToXml($array);
$arrayToXml->addProcessingInstruction('xml-stylesheet', 'type="text/xsl" href="base.xsl"');
$result = $arrayToXml->toXml();
```

```xml
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="base.xsl"?>
<root><Good_guy><name>Luke Skywalker</name><weapon>Lightsaber</weapon></Good_guy><Bad_guy><name>Sauron</name><weapon>Evil Eye</weapon></Bad_guy></root>
```

--------------------------------

### Test in a New Process with NewProcessTrait

Source: https://github.com/yourls/yourls/blob/master/tests/README.md

Example test using NewProcessTrait to run a scenario in a fresh PHP process. The trait runs tests/data/scripts/run-scenario.php, which defines constants, boots YOURLS, runs the scenario file, and reports JSON of constants and included files.

```php
class SomeTest extends PHPUnit\Framework\TestCase {
    use NewProcessTrait;

    public function test_something() {
        $report = $this->run_in_new_process( 'some-scenario', array( 'YOURLS_SOMETHING' => false ) );

        $this->assertArrayNotHasKey( 'YOURLS_USER', $report['constants'] );
        $this->assertNotContains( 'includes/auth.php', $report['included'] );
    }
}
```

--------------------------------

### Setting DOMDocument properties via constructor

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/spatie/array-to-xml/README.md

Shows how to set DOMDocument properties by passing an array as the sixth argument to ArrayToXml::convert(). The example enables 'formatOutput'.

```php
$result = ArrayToXml::convert(
   $array, 
   $rootElement, 
   $replaceSpacesByUnderScoresInKeyNames, 
   $xmlEncoding, 
   $xmlVersion, 
   ['formatOutput' => true]
);
```

--------------------------------

### Shorten URL with jQuery GET request

Source: https://github.com/yourls/yourls/blob/master/readme.html

Example of a GET request with Javascript (using jQuery) to shorten a URL. Sends username, password, action, format, and url parameters to the API endpoint. The callback function receives the server response and can access the new short URL via data.shorturl.

```javascript
var api_url  = 'http://sho.rt/yourls-api.php';
var response = $.get( api_url, {
    username: "your_username",
    password: "your_password",
    action:   "shorturl",
    format:   "json",
    url:      "http://ozh.org/"
    },
    // callback function that will deal with the server response
    function( data) {
        // now do something with the data, for instance show new short URL:
        alert(data.shorturl);
    }
);
```

--------------------------------

### Join path and query, strip auth and fragment

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/ozh/http_build_url/README.md

Demonstrates using multiple flags to join a relative path, merge query strings, and strip authentication and fragment. The output is shown in the comment.

```php
// Join a relative path, merge the query string, drop auth and fragment
echo http_build_url(
    'http://user@www.example.com/pub/index.php?a=b#files',
    [
        'scheme' => 'ftp',
        'host'   => 'ftp.example.com',
        'path'   => 'files/current/',
        'query'  => 'a=c',
    ],
    HTTP_URL_STRIP_AUTH | HTTP_URL_JOIN_PATH | HTTP_URL_JOIN_QUERY | HTTP_URL_STRIP_FRAGMENT
);
// ftp://ftp.example.com/pub/files/current/?a=c
```

--------------------------------

### Basic usage of POMO\MO

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/pomo/pomo/README.md

Shows how to create an MO object, import a .mo file, and translate a string using the POMO library.

```php
<?php
use POMO\MO;

// Create MO object
$translations = new MO();

// Import MO file
$translations->import_from_file($the_mo_filepath);

// Translate
$translations->translate($text);
```

--------------------------------

### Sample XML return for expand action

Source: https://github.com/yourls/yourls/blob/master/readme.html

Sample return in XML format for the expand action. Shows the structure of a successful response, including the keyword, short URL, long URL, message, and statusCode.

```xml
<result>
    <keyword>ozh</keyword>
    <shorturl>http://sho.rt/ozh</shorturl>
    <longurl>http://ozh.org/</longurl>
    <message>success</message>
    <statusCode>200</statusCode>
</result>
```

--------------------------------

### Create GeoIP2 WebService Client

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/geoip2/geoip2/README.md

Creates a WebService client with your account ID and license key. Required before making any lookup calls.

```php
$client = new Client(42, 'abcdef123456');
```

--------------------------------

### Require Composer Autoloader

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/maxmind-db/reader/README.md

Requires the Composer autoloader after installing dependencies, enabling use of the MaxMind DB Reader classes.

```php
require 'vendor/autoload.php';
```

--------------------------------

### Use CaBundle with cURL

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/composer/ca-bundle/README.md

Use the system CA bundle path with cURL. If the path is a directory, set CURLOPT_CAPATH; otherwise set CURLOPT_CAINFO.

```php
$curl = curl_init("https://example.org/");

$caPathOrFile = \Composer\CaBundle\CaBundle::getSystemCaRootBundlePath();
if (is_dir($caPathOrFile)) {
    curl_setopt($curl, CURLOPT_CAPATH, $caPathOrFile);
} else {
    curl_setopt($curl, CURLOPT_CAINFO, $caPathOrFile);
}

$result = curl_exec($curl);
```

--------------------------------

### Sample JSON return for shorturl action

Source: https://github.com/yourls/yourls/blob/master/readme.html

Sample return in JSON format for the shorturl action. Shows the structure of a successful response, including the shortened URL, status, message, and statusCode.

```json
{
  "url": {
    "keyword": "ozh",
    "url": "http:\/\/ozh.org",
    "title": "Ozh RICHARD \u00ab ozh.org",
    "date": "2014-10-24 16:01:39",
    "ip": "127.0.0.1"
  },
  "status": "success",
  "message": "http:\/\/ozh.org added to database",
  "title": "Ozh RICHARD \u00ab ozh.org",
  "shorturl": "http:\/\/sho.rt\/1f",
  "statusCode": "200"
}
```

--------------------------------

### Run the Requests test suite with PHPUnit

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/rmccue/requests/README.md

Run the full test suite using PHPUnit. Requires the PHP JSON extension to be enabled.

```bash
$ phpunit
```

--------------------------------

### Run YOURLS Test Suite

Source: https://github.com/yourls/yourls/blob/master/tests/README.md

Runs the full YOURLS test suite from the YOURLS root directory. Expect output showing progress and a summary like 'OK (519 tests, 1123 assertions)'.

```bash
composer -d tests/ run test -- --configuration=../phpunit.xml.dist ..
```

--------------------------------

### POST yourls-api.php

Source: https://github.com/yourls/yourls/blob/master/readme.html

The YOURLS API endpoint accepts HTTP GET or POST requests with parameters for authentication, action, and action-specific data. This snippet documents the general usage and the available actions.

```APIDOC
## [POST] yourls-api.php

### Description
The YOURLS API endpoint allows generating short URLs, expanding them, and retrieving statistics. It accepts parameters via GET or POST, with authentication via username/password or signature.

### Method
POST

### Endpoint
http://your-own-domain-here.com/yourls-api.php

### Parameters
#### Authentication Parameters
- **username** (string) - Required - Your YOURLS username.
- **password** (string) - Required - Your YOURLS password.
- **signature** (string) - Optional - Passwordless API signature (alternative to username/password).

#### Common Parameters
- **action** (string) - Required - The action to perform: "shorturl", "expand", "url-stats", "stats", "db-stats", or "version".
- **format** (string) - Optional - Output format: "jsonp", "json", "xml", or "simple" (depending on action).

#### Action-specific Parameters
- **url** (string) - Required for action=shorturl - The URL to shorten.
- **keyword** (string) - Optional for action=shorturl - Custom keyword for the short URL.
- **title** (string) - Optional for action=shorturl - Title for the short URL.
- **shorturl** (string) - Required for action=expand and action=url-stats - The short URL to expand or get stats for (can be 'abc' or 'http://site/abc').
- **filter** (string) - Required for action=stats - Filter: "top", "bottom", "rand", or "last".
- **limit** (integer) - Required for action=stats - Maximum number of links to return.

### Request Example
```
POST /yourls-api.php HTTP/1.1
Host: your-own-domain-here.com
Content-Type: application/x-www-form-urlencoded

username=your_username&password=your_password&action=shorturl&format=json&url=http%3A%2F%2Fozh.org
```

### Response
#### Success Response (200)
The response format depends on the requested format (JSON, XML, etc.). For JSON, a typical response includes fields like `status`, `message`, `shorturl`, and `statusCode`.

#### Response Example (JSON for shorturl action)
```json
{
  "url": {
    "keyword": "ozh",
    "url": "http:\/\/ozh.org",
    "title": "Ozh RICHARD \u00ab ozh.org",
    "date": "2014-10-24 16:01:39",
    "ip": "127.0.0.1"
  },
  "status": "success",
  "message": "http:\/\/ozh.org added to database",
  "title": "Ozh RICHARD \u00ab ozh.org",
  "shorturl": "http:\/\/sho.rt\/1f",
  "statusCode": "200"
}
```

#### Response Example (XML for expand action)
```xml
<result>
    <keyword>ozh</keyword>
    <shorturl>http://sho.rt/ozh</shorturl>
    <longurl>http://ozh.org/</longurl>
    <message>success</message>
    <statusCode>200</statusCode>
</result>
```
```

--------------------------------

### Enable Public API Access in YOURLS

Source: https://github.com/yourls/yourls/blob/master/sample-public-api.txt

Use this PHP file to expose the YOURLS API without requiring login. Set YOURLS_PRIVATE to false and include yourls-api.php. Rename this file to api.php and place it in the same directory as yourls-api.php.

```php
<?php

/* 
 * This file shows how to implement a public API (no login or username needed) for your setup
 * even if your install is private (no public access to admin area)
 *
 * Rename this file like "api.php" and put it in the same directory as yourls-api.php
 *
 */

define('YOURLS_PRIVATE', false);

require_once( dirname(__FILE__).'/yourls-api.php' );
```

--------------------------------

### ISP lookup with GeoIP2 Reader

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/geoip2/geoip2/README.md

Get ISP and organization information for an IP address using the GeoIP2 ISP database. The isp() method returns a record with autonomous system number, organization, ISP, and network details.

```php
<?php
require_once 'vendor/autoload.php';
use GeoIp2\Database\Reader;

// This creates the Reader object, which should be reused across
// lookups.
$reader = new Reader('/usr/local/share/GeoIP/GeoIP2-ISP.mmdb');

$record = $reader->isp('128.101.101.101');

print($record->autonomousSystemNumber . "\n"); // 217
print($record->autonomousSystemOrganization . "\n"); // 'University of Minnesota'
print($record->isp . "\n"); // 'University of Minnesota'
print($record->organization . "\n"); // 'University of Minnesota'

print($record->ipAddress . "\n"); // '128.101.101.101'
print($record->network . "\n"); // '128.101.101.101/32'
```

--------------------------------

### Instantiate MaxMind\Db\Reader

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/maxmind-db/reader/README.md

After including the autoload file, instantiate the Reader class with the path to the .mmdb file.

```php
use MaxMind\Db\Reader;
$reader = new Reader('example.mmdb');
```

--------------------------------

### Drop XML declaration with ArrayToXml::dropXmlDeclaration()

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/spatie/array-to-xml/README.md

Demonstrates how to omit the default XML declaration by calling dropXmlDeclaration() on an ArrayToXml instance. The example uses a custom root element with a namespace attribute and shows the resulting XML without the declaration.

```php
$root = [
    'rootElementName' => 'soap:Envelope',
    '_attributes' => [
        'xmlns:soap' => 'http://www.w3.org/2003/05/soap-envelope/',
    ],
];
$array = [
    'soap:Header' => [],
    'soap:Body' => [
        'soap:key' => 'soap:value',
    ],
];
$arrayToXml = new ArrayToXml($array, $root);

$result = $arrayToXml->dropXmlDeclaration()->toXml();
```

```xml
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope/"><soap:Header/><soap:Body><soap:key>soap:value</soap:key></soap:Body></soap:Envelope>
```

--------------------------------

### Adding comments with _comment keys

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/spatie/array-to-xml/README.md

Shows how to add comments to XML nodes using keys starting with `_comment`. Comments are placed based on the key's position in the array. A comment is omitted if its value is an empty string or null.

```php
$array = [
    'Good guy' => [
        '_comment' => 'Our hero',
        'name' => 'Luke Skywalker',
        'weapon' => 'Lightsaber'
    ],
    'Bad guy' => [
        'name' => 'Sauron',
        'weapon' => 'Evil Eye',
        '_comment' => 'Finally gone',
    ],
    'Another guy' => [
        '_comment' => 'The GOAT',
        'name' => 'John Wick',
        '_comment2' => 'famous for',
        'weapon' => 'Pencil',
        '_comment_other' => 'His dog needs an entry',
    ];
    'The survivor' => [
        '_attributes' => ['house'=>'Hogwarts'],
        '_value' => 'Harry Potter',
        '_comment' => 'He made it',
    ]
];

$result = ArrayToXml::convert($array);
```

```xml
<?xml version="1.0"?>
<root>
    <Good_guy>
        <!--Our hero-->
        <name>Luke Skywalker</name>
        <weapon>Lightsaber</weapon>
    </Good_guy>
    <Bad_guy>
        <name>Sauron</name>
        <weapon>Evil Eye</weapon>
        <!--Finally gone-->
    </Bad_guy>
    <Another_guy>
        <!--The GOAT-->
        <name>John Wick</name>
        <!--famous for-->
        <weapon>Pencil</weapon>
        <!--His dog needs an entry-->
    </Another_guy>
    <The_survivor house="Hogwarts">Harry Potter<!--He made it--></The_survivor>
</root>
```

--------------------------------

### Use CaBundle with PHP Streams

Source: https://github.com/yourls/yourls/blob/master/includes/vendor/composer/ca-bundle/README.md

Use the system CA bundle path with PHP streams. Configure the SSL context with 'capath' or 'cafile' depending on whether the path is a directory.

```php
$opts = array(
    'http' => array(
        'method' => "GET"
    )
);

$caPathOrFile = \Composer\CaBundle\CaBundle::getSystemCaRootBundlePath();
if (is_dir($caPathOrFile)) {
    $opts['ssl']['capath'] = $caPathOrFile;
} else {
    $opts['ssl']['cafile'] = $caPathOrFile;
}

$context = stream_context_create($opts);
$result = file_get_contents('https://example.com', false, $context);
```
Tokens:
Raw