mpm-url-shortener/plugin/INSTALL.md

# MPM API Extras — Server Installation Guide

**For:** mpm.to server administrator  
**What this does:** Adds `delete` and `update` actions to the YOURLS API so that short URL management tools can perform all operations using an API signature token — no admin password required.

---

## What you're installing

A single PHP plugin file: `mpm-api-extras.php`

This plugin registers two new actions on the standard YOURLS API endpoint (`/yourls-api.php`):

- `action=delete` — permanently removes a short URL by keyword
- `action=update` — changes the destination URL, short code, or title of an existing short URL

Both actions are authenticated the same way as all other YOURLS API calls: via a signature token. No changes are made to the admin interface or any existing functionality.

---

## Installation steps

### 1. Upload the plugin file

Copy `mpm-api-extras.php` to the YOURLS **user plugins directory** on the server.

The default location is:

```
/path/to/yourls/user-plugins/mpm-api-extras.php
```

If you're unsure of the path, check `config.php` for the `YOURLS_ABSPATH` constant — the plugins folder is `user-plugins/` relative to that.

Using SFTP, SCP, or your hosting control panel's file manager, place the file there. The directory should already exist; if it doesn't, create it.

### 2. Activate the plugin

1. Log into the YOURLS admin panel at `https://mpm.to/admin/`
2. Navigate to **Manage Plugins** (in the top navigation)
3. Find **MPM API Extras** in the list
4. Click **Activate**

You should see a confirmation message and the plugin status will change to "Active."

### 3. Verify (optional)

To confirm the plugin is working, you can test the delete action with a non-existent keyword — it should return a 404 rather than an "Unknown action" error:

```
https://mpm.to/yourls-api.php?signature=<token>&format=json&action=delete&keyword=__test__
```

Expected response (plugin active):
```json
{"status":"fail","message":"Short URL not found: __test__","errorCode":"404"}
```

Response if plugin is **not** active:
```json
{"simple":"Unknown or missing \"action\" parameter","message":"Unknown or missing \"action\" parameter","errorCode":"400"}
```

---

## Uninstalling

To remove the plugin:

1. Go to **Manage Plugins** → click **Deactivate** next to MPM API Extras
2. Delete `user-plugins/mpm-api-extras.php` from the server

The `delete` and `update` API actions will stop being available immediately after deactivation. No data is removed.

---

## Security notes

- The plugin adds no new authentication mechanism — it uses YOURLS's existing signature token system
- The token must be kept confidential (it's stored in the macOS Keychain on the user's machine, not in any file)
- Only authenticated API calls can trigger these actions; unauthenticated requests are rejected by YOURLS before the plugin code runs
- The plugin does not log requests or store any data

---

## Questions?

Contact the MPM team or refer to the [YOURLS plugin documentation](https://yourls.org/docs/development/plugins).