# Add a support screen to your WordPress plugin with mammothwp/support

When a user needs help with a plugin, the first reply is often a list of questions: which WordPress version, which PHP version, which other plugins are active. Each plugin that builds its own contact form also adds another screen to wp-admin.

[mammothwp/support](https://github.com/mammothwp/support) gives every plugin that bundles it one shared **Support** screen. The user fills in a form in wp-admin, and the site sends one email with `wp_mail()`. A site report is added to that email only if the user ticks a box. The box is unticked by default, and **Preview what will be sent** shows the exact text before anything goes out.

<div class="guide-video">
  <iframe
    width="1280"
    height="720"
    src="https://www.youtube-nocookie.com/embed/35ulOX_SbIQ"
    title="Add a Support screen with one call"
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
    allowfullscreen
    loading="lazy"
    referrerpolicy="strict-origin-when-cross-origin"
  ></iframe>
  <p>Screen recording of composer require, register_plugin(), and the Support form. No voiceover; captions are burned in.</p>
</div>

## Install

```bash
composer require mammothwp/support
```

The package requires PHP 8.1 or newer and pulls in `mammothwp/wp-kit` `^2.0` as a dependency. No `@dev` flag or `minimum-stability` change is needed.

## Register your plugin

In your main plugin file, after the Composer autoloader is loaded:

```php
\MammothWP\Support\Support::register_plugin( __FILE__, [
    'email' => 'support@example.com', // where tickets for this plugin go
] );
```

That is the whole integration. The name, version, vendor and slug come from the plugin header and folder name. `email` is required. Without a valid address the plugin is still listed, but its Send button is disabled and `_doing_it_wrong()` is raised. There is no fallback address.

If you prefer not to put the address in PHP, add `mammothwp-support.json` to the plugin root and call `register_plugin( __FILE__ )`:

```json
{
    "email": "support@example.com",
    "docs_url": "https://example.com/docs"
}
```

Keys in the PHP array override the JSON file. [MammothWP Acceptance Logs](https://wordpress.org/plugins/mammoth-acceptance-logs/) on wordpress.org uses this approach: it ships a `mammothwp-support.json` file and calls `register_plugin()` with only the plugin file.

## Where the screen appears

There is one screen, and plugins can add shortcuts to it but cannot move it. By default it sits under Tools > Support. When a registered plugin has the vendor "Mammoth WP", it gets its own top-level menu instead. A plugin can add a shortcut under its own menu:

```php
\MammothWP\Support\Support::register_plugin( __FILE__, [
    'email' => 'support@example.com',
    'menu'  => [ 'parent' => 'my-plugin-settings', 'title' => 'Support' ],
] );
```

The shortcut links to the shared screen with your plugin preselected. Every registered plugin also gets a "Support" action link on the Plugins screen.

Site owners can change the location with the `MMWP_SUPPORT_MENU` constant or the `mmwp_support_menu` filter, and the recipient with `MMWP_SUPPORT_EMAIL_<SLUG>` or the `mmwp_support_email` filter. Agencies can rebrand the screen with `MMWP_SUPPORT_WHITELABEL` or the `mmwp_support_branding` filter.

## Check it from WP-CLI

The package registers its operations through wp-kit, so the same actions are available over REST (`mmwp/v1`), WP-CLI and the Abilities API. To see which plugins are registered and where their tickets go:

```bash
wp mmwp support plugins
```

To see the exact email a ticket would produce without sending it:

```bash
wp mmwp support send --plugin=my-plugin --message="Test ticket" --reply-to=you@example.com --dry-run
```

A dry run prints the recipient, subject, headers, body and attachment name, and sends nothing. `--include-report` and `--include-log` are off unless you pass them.

## Add your own report section

If your plugin has settings that help with support, add a section to the site report:

```php
add_filter( 'mmwp_support_report_sections', function ( array $sections ): array {
    $sections[] = new My_Plugin_Report_Section(); // implements \MammothWP\Support\Report\Section_Interface
    return $sections;
} );
```

`Section_Interface` has three methods: `key()`, `label()` and `collect()`. The contract is that a section returns no secrets: no keys, tokens, passwords or customer data.

## When several plugins bundle it

Each bundled copy registers its version in a shared registry, and on `plugins_loaded` only the highest version boots. The user sees one Support screen, whichever plugins they have installed.

## When to use it

- You want a support form inside wp-admin that emails your support address.
- You want users to decide whether a site report is attached, and to see it first.
- You ship several plugins and want them to share one support screen.

## When not to

- Your support runs through a help desk API rather than email. The only built-in transport is `wp_mail()`.
- Your plugin must run on PHP versions older than 8.1.
- You cannot ship Composer dependencies inside your plugin.

## Links

- GitHub: https://github.com/mammothwp/support
- Packagist: https://packagist.org/packages/mammothwp/support
- License: GPLv2 or later