Installing a Plugin

Plugins are installed by placing the plugin directory into plugins/ inside your Opterius Mail installation. There is no package manager or enable/disable flag — a plugin is active when its directory is present and inactive when it is absent (or renamed with a leading underscore).

Step 1 — Obtain the Plugin#

Plugins are typically distributed as GitHub repositories or ZIP archives.

From GitHub#

cd /opt/opterius-mail/plugins
git clone https://github.com/example/opterius-mail-plugin-signature ./signature

Using git clone makes future updates straightforward (git pull).

From a ZIP file#

cd /opt/opterius-mail/plugins
unzip ~/downloads/opterius-mail-plugin-signature.zip -d signature

Manual file copy#

Create the directory and place the files inside it:

mkdir -p /opt/opterius-mail/plugins/signature
# Copy plugin.php and any other files

Step 2 — Verify the Plugin Structure#

The plugin directory must contain a plugin.php file with the main plugin class. The minimum structure:

plugins/
└── signature/
    └── plugin.php      (required — main class extending App\Plugins\Plugin)

Some plugins include additional files:

plugins/
└── signature/
    ├── plugin.php
    ├── config.php           (plugin-specific config, copied to config/ or read directly)
    ├── views/               (Blade views used by the plugin)
    ├── migrations/          (database migrations, if the plugin requires tables)
    └── README.md

Step 3 — Verify Detection#

Run the plugin list command to confirm Opterius Mail has detected the plugin:

cd /opt/opterius-mail
php artisan mail:plugins:list

Expected output:

Installed plugins:
  [active]  signature  (v1.2.0) — Corporate email signature injection

If the plugin does not appear, check:

• The directory is directly inside plugins/ (not nested inside another folder).
• The directory name does not start with _ or ..
• plugin.php exists and does not have a PHP syntax error (php -l plugins/signature/plugin.php).

Step 4 — Run Migrations (If Required)#

If the plugin ships with database migrations, run them:

php artisan migrate

The plugin's migration files must be registered in its boot() method (the plugin author handles this). If the plugin's README says to run migrations, always do so before using the plugin.

Step 5 — Configure the Plugin#

Most plugins require additional configuration. Check the plugin's README.md for required .env keys.

Adding .env keys#

# Edit .env
nano /opt/opterius-mail/.env

# Example keys for a hypothetical signature plugin
SIGNATURE_PROVIDER=database
SIGNATURE_FOOTER_HTML="<p>Sent from our mail server.</p>"

Copying a config file#

Some plugins provide a config file that should be copied to config/:

cp plugins/signature/config.php config/mail-signature.php

Clearing config cache#

After adding .env keys or config files:

php artisan config:clear

Step 6 — Test the Plugin#

Log into webmail and exercise the feature the plugin provides. Check the Laravel log if something is not working:

tail -f /opt/opterius-mail/storage/logs/laravel.log

Disabling a Plugin#

To disable a plugin without deleting it:

mv /opt/opterius-mail/plugins/signature /opt/opterius-mail/plugins/_signature
php artisan config:clear

The leading underscore causes the PluginManager to skip the directory. Rename it back (remove the underscore) to re-enable.

To permanently remove a plugin:

rm -rf /opt/opterius-mail/plugins/signature
php artisan config:clear

If the plugin created database tables, those tables remain after removal. Remove them manually if they are no longer needed.

Updating a Plugin#

Git-based install#

cd /opt/opterius-mail/plugins/signature
git pull
cd /opt/opterius-mail
php artisan migrate     # run if the update includes new migrations
php artisan config:clear

ZIP-based install#

Replace the plugin directory contents with the new version, then run migrations and clear config cache.

Plugin Isolation#

Plugins run inside the Opterius Mail PHP process. A crashing or misbehaving plugin will affect all users. Before installing third-party plugins in production:

• Review the plugin.php source code.
• Test in a staging environment.
• Only install plugins from trusted authors.