Plugin development
File Structure (Plugins)
The following is based on the initial files generated by "Create App":
/path/zb_users/plugin/demoPlugin │ logo.png [Required] Icon, 128x128; │ plugin.xml [Required] Readme file; │ main.php [Optional] In-app management page, generated only if filled during plugin creation; │ include.php [Optional] In-app embedded page, generated only if filled during plugin creation; │
The maximum automatically created files are the four listed above. You can create additional folders and files as needed:
│ function.php [Optional] It is not recommended to place additional "*.PHP" files in the root directory other than this one; │ If "function.php" is insufficient, split it and place it in the "function" folder; ├─class [Optional] Place class definition files here; ├─css [Optional] CSS style files, try to separate frontend and backend; ├─script [Optional] JS script directory, try to separate frontend and backend; └─other [Optional] Other custom folders and content
Hello Z-Blog
Create an app with "demoPlugin" as the "App ID",
Fill in "
First Plugin" for the "App Name";Keep other information as default;
No additional files need to be created;
Overwrite the content of "
include.php" with the following code;You can directly click the "
Copy to clipboard" button to copy;After "Enabling the plugin", browse any "frontend page" to see the effect;
<?php
// If there are other PHP files, you can include them here, or "include as needed" where necessary
// require __DIR__ . "function.php";
// require __DIR__ . "class/db.php";
# Register plugin
RegisterPlugin("demoPlugin","ActivePlugin_demoPlugin");
// Register interface function
function ActivePlugin_demoPlugin()
{
// Register function to the interface named 'Filter_Plugin_Index_Begin'
Add_Filter_Plugin('Filter_Plugin_Index_Begin','demoPlugin_HelloZBlog');
}
// Interface function definition
function demoPlugin_HelloZBlog()
{
// Note: Declare $zbp as global before using it in the function
global $zbp;
// Insert content into the <head></head> of the frontend page
$zbp->header .="<script>alert(\"hello & {$zbp->user->Name}\")</script>";
// Read plugin configuration item
$InstallTime = $zbp->Config('demoPlugin')->InstallTime;
$zbp->header .="<script>alert(\"The first activation time of the 'demoPlugin' plugin is {$InstallTime}\")</script>";
}
// Called when the plugin is activated
function InstallPlugin_demoPlugin()
{
global $zbp;
$InstallTime = date('Y-m-d H:i:s');
// Check if the configuration item exists
// $zbp->HasConfig('plugin ID'); // return bool
if (!$zbp->HasConfig('demoPlugin')) {
$zbp->Config('demoPlugin')->version = 1;
$zbp->Config('demoPlugin')->InstallTime = $InstallTime;
$zbp->SaveConfig('demoPlugin');
}
}
// Called when the plugin is deactivated
function UninstallPlugin_demoPlugin()
{
global $zbp;
// If the corresponding option exists and is enabled, delete the current plugin configuration
// $zbp->Config('plugin ID')->HasKey('config name'); // return bool
if ($zbp->Config('demoPlugin')->HasKey('DelConfig') &&
$zbp->Config('demoPlugin')->DelConfig == 1) {
$zbp->DelConfig('demoPlugin');
}
}Registration and Interface Mounting
Z-BlogPHP system plugins are notified to the system through active insertion. Therefore, the RegisterPlugin function must be called in the "include.php" file for the plugin to enter the system's plugin architecture.
// Register plugin
RegisterPlugin("plugin ID","ActivePlugin_plugin ID");Then, complete the mounting of "most" interfaces in ActivePlugin_plugin ID;
// Specific interface mounting
function ActivePlugin_plugin ID() {
Add_Filter_Plugin('API Name','Code to execute (function)');
}Note: You can perform checks before mounting interfaces as needed; you can also mount interface B within interface A.
Execute on Plugin "Enable / Disable / Update"
You can define functions as follows, which will be automatically called when the plugin performs the corresponding operation;
function InstallPlugin_plugin ID(){}
function UninstallPlugin_plugin ID(){}
function UpdatePlugin_plugin ID(){}
// Compatibility with older versions
function plugin ID_Updated(){UpdatePlugin_plugin ID();}Plugin Status Check
// Exit the current page directly if the plugin is not enabled (generally used for configuration pages)
if (!$zbp->CheckPlugin('plugin ID')) {$zbp->ShowError(48);die();}User Permission Check
In the default generated main.php, in addition to the $zbp->CheckPlugin() call above, there is also the following instruction to check user permissions:
// `root` means administrator privileges
$action='root';
if (!$zbp->CheckRights($action)) {$zbp->ShowError(6);die();}$zbp->CheckRights() is used to check if the "current user" (including visitors) has the permission to perform a certain operation represented by the passed parameter. It can be combined with "user levels" for fine-grained permission management;
You can view the permissions held by the current user via
-host-/zb_system/cmd.php?act=misc&type=vrs;Permissions can be flexibly defined for user levels; "Z-Blog Role Allocator - Z-Blog App Center"
Refer to "User Level Definition";
Plugin Configuration Data Storage and Retrieval
The "Hello Z-Blog" example already contains relevant usage. The following is a step-by-step explanation;
"Configuration item" "values" can be numbers, strings, or arrays; for PHP objects, theoretically, they need to be serializable. In practical use, it is recommended to convert them to JSON for storage;
1. Set and save configuration options
$zbp->Config('plugin ID')->config name = value;
$zbp->SaveConfig('plugin ID');2. Read configuration options
$s = $zbp->Config('plugin ID')->config name;
echo $s;3. Check if a configuration option has been created
$zbp->HasConfig('plugin ID'); // return bool4. Check if a specific key-value pair of a configuration option exists
$zbp->Config('plugin ID')->HasKey('config name'); // return bool5. Delete a specific configuration
$zbp->Config('plugin ID')->DelKey('config name');
$zbp->SaveConfig('plugin ID');6. Delete configurations
When deactivating a plugin, you can choose to delete configuration items. Generally, we recommend keeping the configuration for future re-activation, or providing a dedicated switch option for user confirmation before deletion;
$zbp->DelConfig('plugin ID');CSRF Related "Important"
For actions that require user clicks on links or form submissions, which in turn affect data or files, in addition to necessary user permission verification, CSRF Token verification should also be added;
When submitting via GET method, if your target address is cmd.php, you can use the following function:
<?php echo BuildSafeCmdURL('act=TagPst'); ?>
If not, you can also directly use:
<?php echo BuildSafeURL('main.php'); ?>
When submitting via POST method, you can add the following within the form:
<input type="hidden" name="csrfToken" value="<?php echo $zbp->GetCSRFToken();?>">
For in-app operations, such as saving configuration items or uploading files, you can use CheckIsRefererValid(); for verification;
if (count($_POST) > 0) {
CheckIsRefererValid();
// Your code, example below
// Configuration item saving ↓
foreach ($_POST as $key => $value) {
$zbp->Config("demoPlugin")->$key = $value;
}
$zbp->SaveConfig("demoPlugin");
// End
$zbp->SetHint('good');
Redirect('./main.php');
}Note: For older versions of Z-Blog PHP, you may need to check first: if (function_exists('CheckIsRefererValid')) {CheckIsRefererValid();}
Article link: http://docs.zbp.cool/zblogdocs/zblogapp/10.html
Helpful?
2025-10-09 15:56:36