Writing a Basic Plugin
April 12, 2019Latest Security Audit
April 25, 2019Plugin Hooks
When you create a plugin for UserSpice, you can use our plugin hooks to allow you to inject code on common pages without modifying the page itself. Basically when you do your install.php file for your plugin, put
$hooks['account.php']['bottom'] = 'hooks/accountbottom.php';
So list the page, the position and the link to the file that is the "include" on that page. Note that you can use the same include on multiple pages. There's nothing wrong with also doing…
$hooks['join.php']['bottom'] = 'hooks/accountbottom.php';
if your include code is the same. Be sure to test your hooks because you can seriously break projects. Plugin hooks are automatically uninstalled when a plugin is uninstalled.
If you want to know exactly where a plugin hook will be in the code, visit the page referenced and look for the includeHook function like includeHook($hooks,'post');
The new 'pre' hook is usually included right below the getMyHooks() function.
Standard Plugin Hooks
admin.php?view=general❌✅❌✅❌Version 5.2.6 or later
| Page | pre | post | body | form | bottom | Description |
|---|---|---|---|---|---|---|
| account.php | ✅ | ❌ | ✅ | ❌ | ✅ | Body is below gravitar. Bottom is bottom right. |
| admin.php?view=general | ✅ | ❌ | ✅ | ❌ | ❌ | Do form and post in one div or use the built in settings table AJAX |
| admin_settings.php (v5.1.5) | ✅ | ❌ | ❌ | ❌ | ✅ | Pre is before the if statements. Bottom is before json encode. DO NOT echo text inside this hook. |
| admin.php?view=social(v4.4) | ❌ | ❌ | ✅ | ❌ | ❌ | Do form and post in one div or use the built in settings table AJAX |
| admin.php?view=user (v5.0.5+) | ✅ | ✅ | ✅ | ✅ | ✅ | Body is above the form. |
| admin.php?view=users (v5.0.5+) | ✅ | ✅ | ✅ | ✅ | ✅ | Pre is above the table. Body is the table header. Bottom is the table. Form is the new user modal. |
| forgot_password.php (v.5.3.0+) | ✅ | ✅ | ❌ | ❌ | ✅ | |
| join.php | ✅ | ✅ | ✅ | ✅ | ✅ | Form is inside /views/_join.php |
| login.php | ✅ | ✅ | ✅ | ✅ | ✅ | Post is just before validation passed so you can boot them. |
| user_settings.php | ✅ | ✅ | ✅ | ✅ | ✅ |
Event Plugin Hooks
As of version 5.1.4, we also have "event hooks". These can be triggered when a certain event happens on your site. They're included very similarly to other hooks with the exception that they don't use the php page name. Instead they all use the body position and the event hook name.
$hooks['loginFail']['body'] = 'hooks/accountbody.php';
Current event names are:
| Event | body | Notes |
|---|---|---|
| cloakBegin | ✅ | 5.4.1+ Admin cloaks into another user |
| cloakEnd | ✅ | 5.4.1+ Admin ended a cloaking session |
| createAttempt | ✅ | 5.3.8+ Admin attempts to create user from dashboard |
| loginFail | ✅ | |
| loginSuccess | ✅ | |
| logout | ✅ | |
| noAccess | ✅ | Did not have permission to visit a page |
| joinAttempt | ✅ | v5.3.0 or later |
| joinFail | ✅ | For join success, use the standard join.php "post" position instead |
| hitBanned | ✅ | User was redirected to banned.php |
| forgotPassword | ✅ | v5.3.0 or later |
| passwordResetFail | ✅ | v5.5.0 or later |
| passwordResetSuccess | ✅ | v5.5.0 or later |
| verifySuccess | ✅ | in verify.php |
| verifyResend | ✅ | in verify.php |
| verifyResend | ✅ | in verify.php |
API Plugin Hooks
The UserSpice API introduced in late 2021 has some special hooks that allow you to hook into events that happen in the API. The primary reason for these hooks is that they cannot assume incoming data is $_POST and should use the $data variable. Current Hooks are:
Current event names are:
| API Event | API Version | body |
|---|---|---|
| loginFailApi | 1+ | ✅ |
| loginSuccessApi | 1+ | ✅ |
| joinAttemptApi | 1+ | ✅ |
| joinSuccessApi | 1+ | ✅ |
| joinFailApi | 1+ | ✅ |
