mirror of
https://github.com/mivodev/mivodev.github.io.git
synced 2026-01-26 21:41:53 +07:00
80 lines
2.5 KiB
Markdown
80 lines
2.5 KiB
Markdown
# Plugin Development Guide
|
|
|
|
Mivo supports a modular plugin system that allows developers to extend functionality, add themes, or integrate third-party services. This guide details the rules and structure required for your plugin to work with Mivo and appear in the Registry.
|
|
|
|
## Directory Structure
|
|
|
|
A valid Mivo plugin must have a flat structure with a `plugin.php` file in the root.
|
|
|
|
```text
|
|
plugin-name/
|
|
├── plugin.php # (Required) Entry point & Metadata
|
|
├── composer.json # (Optional) Dependencies
|
|
├── README.md # (Required) Documentation for Registry
|
|
├── theme/ # (Optional) Captive Portal theme files
|
|
│ └── styles.css
|
|
└── src/ # (Optional) PHP Classes
|
|
```
|
|
|
|
## Metadata Header
|
|
|
|
Your `plugin.php` **must** start with a specific comment block. The Registry crawler uses this to categorize and display your plugin.
|
|
|
|
```php
|
|
<?php
|
|
/**
|
|
* Plugin Name: My Awesome Plugin
|
|
* Description: Adds a dark mode toggle to the hotspot login page.
|
|
* Version: 1.0.0
|
|
* Author: YourName
|
|
* Category: Hotspot Tools
|
|
* Scope: Global
|
|
* Tags: theme, dark-mode, ui
|
|
* Core Version: >=1.2.0
|
|
*/
|
|
|
|
use App\Core\Hooks;
|
|
|
|
// Plugin logic starts here...
|
|
```
|
|
|
|
### Required Fields
|
|
- **Plugin Name**: Displayed title.
|
|
- **Description**: Short summary (max 160 chars).
|
|
- **Version**: SemVer format (e.g., `1.0.0`).
|
|
- **Category**: One of: `Hotspot Tools`, `System Tools`, `Payment Gateway`, `Reports`, `Language Pack`.
|
|
- **Scope**: `Global` (available everywhere) or `Session` (specific to a router session).
|
|
- **Tags**: Comma-separated search keywords.
|
|
|
|
## Release & Registry Rules
|
|
|
|
To get your plugin listed in the [Official Registry](/plugins/):
|
|
|
|
1. **Public Repository**: Host your code on GitHub.
|
|
2. **Naming**: Repository name should start with `plugin-` (e.g., `plugin-advanced-login`).
|
|
3. **Versioning**: Use **Git Tags** for releases. The Registry strictly prefers tagged releases over the main branch.
|
|
- Tag format: `v1.0.0`.
|
|
- You can use GitHub Actions to auto-generate ZIPs.
|
|
4. **Documentation**: A comprehensive `README.md` is mandatory. It will be mirrored to the Mivo website.
|
|
|
|
## Sample GitHub Workflow
|
|
|
|
Create `.github/workflows/release.yml` to automatically package your plugin:
|
|
|
|
```yaml
|
|
name: Release Plugin
|
|
on:
|
|
push:
|
|
tags: ['v*']
|
|
|
|
jobs:
|
|
build:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v4
|
|
- run: zip -r plugin.zip . -x "*.git*"
|
|
- uses: softprops/action-gh-release@v1
|
|
with:
|
|
files: plugin.zip
|
|
```
|