插件开发

plugin/notice/
├── plugin.json                ← 必须
├── plugin.php                 ← 必须
├── src/
│   ├── Hooks.php
│   └── AdminController.php
└── view/default/
    └── admin/plugin/notice/index.html

{
    "name": "notice",
    "title": "公告条",
    "version": "1.0.0",
    "author": "你的名字",
    "description": "在页面顶部显示一条可关闭的公告。",
    "priority": 60,
    "require": {
        "php": ">=7.2"
    },
    "autoload": {
        "Plugin\\Notice\\": "src/"
    },
    "view": "view",
    "config_fields": {
        "enabled": { "label": "启用公告", "type": "switch", "tips": "关闭后前台不再显示" },
        "text":    { "label": "公告文字", "type": "text", "tips": "20 字以内最好看" },
        "link":    { "label": "跳转链接", "type": "text", "tips": "留空则不跳转" }
    },
    "config": {
        "enabled": 1,
        "text": "本站已启用全新会员系统",
        "link": "/register"
    }
}

"require": { "plugins": ["member"] }

<?php
/**
 * 公告条插件 — 入口
 *
 * @var \Aucms\Plugin\PluginInstance $plugin
 */

// 1) 钩子
$plugin->hook('app_init', 'Plugin\\Notice\\Hooks@onAppInit', 20);
$plugin->hook('view_render', 'Plugin\\Notice\\Hooks@onRender', 60);

// 2) 路由（后台必须显式挂 AdminAuth）
$plugin->route(function (\Aucms\Routing\Router $router) {
    $admin = function_exists('config') ? config('app.admin_path', 'admin') : 'admin';
    $router->group(
        array('prefix' => $admin, 'middleware' => array('App\\Middleware\\AdminAuth')),
        function (\Aucms\Routing\Router $router) {
            $router->get('/plugin/notice', 'Plugin\\Notice\\AdminController@index');
            $router->post('/plugin/notice/save', 'Plugin\\Notice\\AdminController@save');
        }
    );
}, 60);

// 3) 后台菜单
$plugin->menu(array(
    'title' => '公告条',
    'url'   => 'plugin/notice',
    'icon'  => 'content',
    'group' => '插件',
));

【最容易踩的坑】后台路由必须写在 route() 回调里。
写在回调外面不会报错，但所有后台路由会集体 404。

不要凭白名单写代码。
要找钩子，去源码里搜 hook('名字')。

<?php

namespace Plugin\Notice;

class Hooks
{
    public static function onAppInit()
    {
        $container = \aucms_container();
        if ($container === null || $container->has('notice.config')) {
            return;
        }
        $container->singleton('notice.config', function () {
            return (array) self::config();
        });
    }

    public static function config()
    {
        try {
            $loaded = \plugin()->loaded();
            if (isset($loaded['notice'])) {
                return (array) $loaded['notice']->config();
            }
        } catch (\Throwable $e) {
            // 落到默认
        }
        return array('enabled' => 0, 'text' => '', 'link' => '');
    }

    public static function onRender($html, $template = '')
    {
        $cfg = self::config();
        if ((int) $cfg['enabled'] !== 1 || trim((string) $cfg['text']) === '') {
            return $html;
        }
        if (strpos(ltrim($template, '/'), 'admin/') === 0) {
            return $html;
        }
        if (strpos($html, 'data-notice-bar') !== false) {
            return $html;
        }

        $text = htmlspecialchars((string) $cfg['text'], ENT_QUOTES, 'UTF-8');
        $link = trim((string) $cfg['link']);
        $inner = $link !== ''
            ? '<a class="notice-bar__link" href="' . htmlspecialchars($link, ENT_QUOTES, 'UTF-8') . '">' . $text . '</a>'
            : '<span>' . $text . '</span>';

        $bar = '<div class="notice-bar" data-notice-bar>'
            . $inner
            . '<button type="button" class="notice-bar__close" aria-label="关闭">&times;</button>'
            . '</div>'
            . '<style>.notice-bar{display:flex;align-items:center;justify-content:center;gap:12px;'
            . 'padding:9px 16px;background:#eef4ff;color:#1d4ed8;font-size:14px}'
            . '.notice-bar a{color:#1d4ed8}.notice-bar__close{border:0;background:none;font-size:18px;'
            . 'cursor:pointer;color:#5b7bd5;line-height:1}</style>'
            . '<script>(function(){var b=document.querySelector("[data-notice-bar]");'
            . 'if(!b)return;b.querySelector(".notice-bar__close").onclick=function(){b.remove()};})();</script>';

        $pos = stripos($html, '<body');
        if ($pos !== false) {
            $gt = strpos($html, '>', $pos);
            if ($gt !== false) {
                return substr($html, 0, $gt + 1) . $bar . substr($html, $gt + 1);
            }
        }
        return $bar . $html;
    }
}

<?php

namespace Plugin\Notice;

use Aucms\Http\Request;

class AdminController extends \App\Controller\Admin\BaseController
{
    const FORM_SCOPE = 'plugin.notice.save';

    public function index(Request $request)
    {
        $plugin = \plugin()->loaded()['notice'];
        return $this->admin('plugin/notice/index', array(
            'cfg'        => (array) $plugin->config(),
            'form_token' => $this->security->formToken(self::FORM_SCOPE),
        ));
    }

    public function save(Request $request)
    {
        if (!$this->checkFormToken($request, self::FORM_SCOPE)) {
            return $this->error('表单已过期，请刷新页面后重试');
        }

        $plugin = \plugin()->loaded()['notice'];
        $plugin->saveConfig(array(
            'enabled' => (int) $request->post('enabled', 0) === 1 ? 1 : 0,
            'text'    => \Aucms\Security::strip((string) $request->post('text', ''), 100),
            'link'    => \Aucms\Security::strip((string) $request->post('link', ''), 255),
        ));

        return $this->success(array('redirect' => '/admin/plugin/notice'), '已保存');
    }
}

{layout admin/layout}

<div class="nv-card">
  <div class="nv-card-head"><h3 class="nv-card-title">公告条设置</h3></div>
  <div class="nv-card-body">
    <form method="post" action="/admin/plugin/notice/save">
      <input type="hidden" name="_token" value="{$csrf}">
      <input type="hidden" name="_form_token" value="{$form_token}">

      <div class="nv-form-row">
        <label class="nv-label">启用</label>
        <select class="nv-input" name="enabled">
          <option value="1" {if $cfg.enabled == 1}selected{/if}>开启</option>
          <option value="0" {if $cfg.enabled == 0}selected{/if}>关闭</option>
        </select>
      </div>

      <div class="nv-form-row">
        <label class="nv-label">公告文字</label>
        <input class="nv-input" type="text" name="text" value="{$cfg.text}" maxlength="100">
      </div>

      <div class="nv-form-row">
        <label class="nv-label">跳转链接</label>
        <input class="nv-input" type="text" name="link" value="{$cfg.link}" placeholder="/register">
        <p class="nv-tips">留空则只显示文字</p>
      </div>

      <div class="nv-form-actions">
        <button class="nv-btn nv-btn-primary" type="submit">保存</button>
      </div>
    </form>
  </div>
</div>

$form_token 不会自动注入，必须在 index() 里显式传进模板。
少了它，保存会 419「表单已过期」。
两个令牌都要有：
  _token       → 防跨站
  _form_token  → 防重复提交

php aucms plugin:enable notice

php aucms cache:rebuild

<?php
return array(
    'hit' => array(
        'columns' => array(
            'id'         => 'id',
            'target_id'  => 'int not null default 0',
            'ip'         => 'string:64 not null default \'\'',
            'created_at' => 'timestamp not null default 0',
        ),
        'options' => array(
            'primary' => 'id',
            'index'   => array('target' => array('target_id')),
        ),
    ),
);

<?php
/**
 * @var \Aucms\Plugin\PluginInstance $plugin
 * @var \Aucms\Plugin\PluginManager  $manager
 */

// 【必须】install 时 autoload 还没注册，要手动 require
require_once __DIR__ . '/src/Hooks.php';

$db = $plugin->container()->make('db');
$schema = new \Aucms\Db\Schema($db->connection(), $db->prefix());
$tables = include __DIR__ . '/tables.php';

foreach ($tables as $name => $def) {
    if ($schema->hasTable($name)) {
        continue;   // 重复安装不报错
    }
    $schema->create($name, $def['columns'], isset($def['options']) ? $def['options'] : array());
}

return true;   // 返回 false 表示安装失败

$plugin->hook('app_init', function () {
    $view = \app('view');
    $view->tag('notice', function ($attrs, $body) {
        $text = isset($attrs['text']) ? $attrs['text'] : '';
        return '<span class="notice">' . htmlspecialchars($text, ENT_QUOTES, 'UTF-8') . '</span>';
    });
});

{notice text="限时活动" /}

属性一律是字符串，数字要自己转。
标签名不要和内置的 if/loop/include/layout 重名。

$plugin->hook('field_types', function ($types) {
    $types['rating'] = array(
        'label'  => '星级评分',
        'render' => function ($value) {
            $n = max(0, min(5, (int) $value));
            return str_repeat('★', $n) . str_repeat('☆', 5 - $n);
        },
        'form'   => function ($field, $value) {
            $name = htmlspecialchars($field['name'], ENT_QUOTES, 'UTF-8');
            $html = '<select class="nv-input" name="' . $name . '">';
            for ($i = 0; $i <= 5; $i++) {
                $html .= '<option value="' . $i . '"'
                    . ((string) $i === (string) $value ? ' selected' : '') . '>' . $i . ' 星</option>';
            }
            return $html . '</select>';
        },
    );
    return $types;
});

php .workbuddy/tools/lint_classes.php
php .workbuddy/tools/lint_methods.php
php .workbuddy/tools/lint_redirects.php

不要把 data/plugin_config/notice.php 打进去（那是调试配置）
不要留 var_dump
plugin.json 的 version 记得 +1