Adding 'query parameter' feature

* It is now possible to define the name of a query parameter in the plugin
  settings, which can be used in the YOURLS REST API
* If used, the query parameter's value is used as base URL for generated
  shortlinks

README.md

@@ -20,27 +20,74 @@ can be helpful if you want to serve YOURLS from a different sub-domain (e.g.,
 ``https://link.acme.com``), but generate short links for a sub-directory of the
 domain for your main web presence (e.g., ``https://acme.com/r``).
 
+When using the REST API, this plugin provides an option to specify the name of a
+query parameter, whose value holds a base URL to use for the generated short
+URL. For instance, if we name the query parameter ``base_url`` in the plugin
+configuration, we can request a short URL as follows:
+
+```
+curl "https://lnk.acme.com/yourls-api.php?signature=XXXXXXXXXX&action=shorturl&format=txt&base_url=https://pink.pony&url=https://this.is.my.veeeeery.long.url.com/with/a/very/deep/path.html?and=also&some=query&para=meters"
+
+https://pink.pony/vUvNW
+```
+
+We can freely choose the name of the query parameter, e.g., we can name it
+``foo_bar``, and YOURLS will return the same result:
+
+```
+curl "https://lnk.acme.com/yourls-api.php?signature=XXXXXXXXXX&action=shorturl&format=txt&foo_bar=https://pink.pony&url=https://this.is.my.veeeeery.long.url.com/with/a/very/deep/path.html?and=also&some=query&para=meters"
+
+https://pink.pony/vUvNW
+```
+
 :bulb: **NOTE:** You must take care that the other end (e.g.,
-``https://acme.com/r``) performs redirects back to the site where YOURLS is
-served from (e.g. ``https://link.acme.com``).
+``https://acme.com/r``, ``https://pink.pony``) performs redirects back to the
+site where YOURLS is served from (e.g. ``https://link.acme.com``).
 
 ![The admin interface of the plugin](config.png)
 
+### URL precedence
+
+The short link's base URL is chosen as follws:
+
+1. If the query parameter name is set in the plugin's configuration, and YOURLS
+   is accessed via the REST API with the query parameter assigned, the **query
+   parameter's value** is used as the generated shortlink's base URL.
+
+1. If the query parameter name is not set in the configuration, or no query
+   parameter is given in the query string when accessing YOURLS via the REST
+   API, the plugin's **default base URL** as configured in the plugin settings
+   is used as the generated shortlink's base URL.
+
+1. If no default base URL is set in the plugin configuration, the **value of
+   ``YOURLS_SITE``** is used as the generated shortlink's base URL.
+
 ### Example
 
 Lets assume the following:
 
     YOURLS_SITE: "https://link.acme.com" (a constant defined in `config.php`)
-    ck_base_url: "https://acme.com/r" (a configuration option)
+    ck_base_url_default: "https://acme.com/r" (a configuration option)
+    ck_base_url_query_parameter: "base_url" (a configuration option)
 
-Then, YOURLS will create the (example) short link
+Then, YOURLS will create the (example) short link (when accessed from the YOURLS
+admin interface, or from the REST API without specifying the `base_url` query
+parameter):
 
     https://acme.com/r/Ac3fG
 
 instead of
 
     https://link.acme.com/Ac3fG
 
+If invoking YOURLS via its REST API while setting the ``base_url`` query
+parameter to ``https://foo.bar``, YOURLS returns the following shortlink (let's
+say the full API call is specified like this:
+`https://lnk.acme.com/yourls-api.php?signature=XXXXXXXXXX&action=shorturl&format=txt&base_url=https://foo.bar&url=https://short.this/url/for/me`):
+
+    https://foo.bar/Ac3fG
+
+
 It is assumed that the system behind ``https://acme.com/r`` performs (e.g.,
 wildcard) redirects from ``https://acme.com/r/(.*)`` to
 ``https://link.acme.com/$1`` which are then further redirected by YOURLS to the
@@ -78,6 +125,9 @@ respective target URLs.
 
        tar -xavvf 1.0.0.tar.gz
 
+1. Eventually upload the unzipped archive to your YOURLS instance (e.g., using
+   `ftp` or `sftp`)
+
 1. Create a symlink to the extracted folder, and name it
 `` yourls-plugin-baseurl-rewrite`` (basically we remove the version string),
    e.g.:
@@ -89,6 +139,29 @@ respective target URLs.
 
 1. Have fun!
 
+
+## Updating
+
+### The easy way: git
+
+1. Move into the plugin's directory, and pull the plugin's latest changes::
+
+    git pull
+
+2. Eventually, check out a specific version:
+
+    git checkout 1.1.0
+
+3. Configure the plugin in the administration page
+
+4. Have fun!
+
+
+### The hard way: manual download and copy
+
+Follow the [installation instructions for manual copy](#the-hard-way-manual-copy),
+and choose the most recent version.
+
 ## License
 
 This package is licensed under the [MIT License](LICENSE).

plugin.php

@@ -6,14 +6,13 @@
              (e.g., https://acme.com/r), different from the base domain of the
              Yourls installation. This can be helpful if you want to serve
              Yourls from a sub-domain (e.g., https://link.acme.com), 
-Version: 1.0.2
+Version: 1.1.0
 Author: Christian Krieg <[email protected]>
 */
 
 // No direct call
 if( !defined( 'YOURLS_ABSPATH' ) ) die();
 
-
 //
 // This filter function actually rewrites short URLs by replacing the original
 // base URL (as specified by ``YOURLS_SITE`` in `config.php`) with the base URL
@@ -26,29 +25,39 @@
 //
 //     YOURLS_SITE: "https://link.acme.com" (a constant defined in `config.php`)
 //     ck_base_url: "https://acme.com/r" (a configuration option)
+//    ck_base_url_query_parameter: "base_url" (a configuration option)
 //
-// Then, YOURLS will create the (example) short link
+// Then, YOURLS will create the (example) short link  (when accessed from the
+// YOURLS admin interface, or from the REST API without specifying the
+// `base_url` query parameter)
 //
 //     https://acme.com/r/Ac3fG
 //
 // instead of
 //
 //     https://link.acme.com/Ac3fG
 //
+// If invoking YOURLS via its REST API while setting the ``base_url`` query
+// parameter to ``https://foo.bar``, YOURLS returns the following shortlink
+// (let's say the full API call is specified like this:
+// `https://lnk.acme.com/yourls-api.php?signature=XXXXXXXXXX&action=shorturl&format=txt&base_url=https://foo.bar&url=https://short.this/url/for/me`):
+// 
+//     https://foo.bar/Ac3fG
+//
 // It is assumed that the system behind ``https://acme.com/r`` performs (e.g.,
 // wildcard) redirects from ``https://acme.com/r/(.*)`` to
 // ``https://link.acme.com/$1`` which are then further redirected to the target
 // URL.
 //
 yourls_add_filter( 'yourls_link', 'ck_base_url_rewrite' );
 function ck_base_url_rewrite ($link) {
-    $default_base_url = yourls_get_option( 'ck_default_base_url', '');
+    $base_url_default = yourls_get_option( 'ck_base_url_default', '');
     $base_url_query_parameter = yourls_get_option( 'ck_base_url_query_parameter', '');
 
     $base_url = (
         isset($_REQUEST[$base_url_query_parameter])
         ? $_REQUEST[$base_url_query_parameter]
-        : $default_base_url
+        : $base_url_default
     );
 
     if ( empty($base_url) )
@@ -77,7 +86,7 @@ function ck_base_url_rewrite_init() {
 // The function that will draw the admin page
 function ck_base_url_rewrite_display_page () {
     // Check if form was submitted
-    if( isset( $_POST['default_base_url'] ) or
+    if( isset( $_POST['base_url_default'] ) or
         isset( $_POST['base_url_query_parameter'] )
     ) {
         // If so, verify nonce
@@ -86,7 +95,7 @@ function ck_base_url_rewrite_display_page () {
         ck_base_url_rewrite_settings_update();
     }
 
-    $default_base_url = yourls_get_option('ck_default_base_url', '');
+    $base_url_default = yourls_get_option('ck_base_url_default', '');
     $base_url_query_parameter = yourls_get_option('ck_base_url_query_parameter', '');
     $nonce = yourls_create_nonce('base_url_settings');
 
@@ -97,7 +106,7 @@ function ck_base_url_rewrite_display_page () {
             <input type="hidden" name="nonce" value="$nonce" />
             <p>
                 <label>Shortlink Default Base URL:</label>
-                <input type="text" name="default_base_url" value="$default_base_url" />
+                <input type="text" name="base_url_default" value="$base_url_default" />
             </p>
             <p>
                 <label>Query parameter (Leave blank to disable):</label>
@@ -112,9 +121,9 @@ function ck_base_url_rewrite_display_page () {
 
 // The function that updates the configuration option
 function ck_base_url_rewrite_settings_update() {
-    $default_base_url = $_POST['default_base_url'];
+    $base_url_default = $_POST['base_url_default'];
     $base_url_query_parameter = $_POST['base_url_query_parameter'];
-    yourls_update_option( 'ck_default_base_url', $default_base_url );
+    yourls_update_option( 'ck_base_url_default', $base_url_default );
     yourls_update_option( 'ck_base_url_query_parameter', $base_url_query_parameter);
 }