docs: 开发规范/教程/demo 全套 + 修复插件运行期自动加载缺口
- demo 插件 plugins/demo.hello-world：演示短代码过滤器、comment.created 钩子、路由+命名空间视图、迁移+模型、后台设置页、filament.post_form 表单注入 - demo 主题 themes/demo：最小可运行主题（覆盖 partials + 绿色系样式） - 教程 docs/tutorial-plugin.md / docs/tutorial-theme.md（10 分钟上手）；规范 docs/development.md（代码/插件/主题/队列/测试/提交） - README 增加开发者文档导航与上手示例 - 修复关键缺口：插件类原来靠 composer.json 硬编码加载，第三方 ZIP 安装的插件无法加载；现改为启动时扫描 plugins/*/src 运行期注册 PSR-4（register 阶段，保证 Filament 面板解析插件页面前就绪），composer.json 移除硬编码 - 测试：demo 插件 3 个用例 + demo 主题渲染；全量 89 通过
This commit is contained in:
ak
+25
@@ -0,0 +1,25 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
use Illuminate\Database\Migrations\Migration;
|
||||
use Illuminate\Database\Schema\Blueprint;
|
||||
use Illuminate\Support\Facades\Schema;
|
||||
|
||||
return new class extends Migration
|
||||
{
|
||||
public function up(): void
|
||||
{
|
||||
Schema::create('hello_world_logs', function (Blueprint $table) {
|
||||
$table->id();
|
||||
$table->foreignId('comment_id')->nullable()->constrained()->nullOnDelete();
|
||||
$table->string('note', 500)->nullable();
|
||||
$table->timestamps();
|
||||
});
|
||||
}
|
||||
|
||||
public function down(): void
|
||||
{
|
||||
Schema::dropIfExists('hello_world_logs');
|
||||
}
|
||||
};
|
||||
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"title": "Hello World 示例插件",
|
||||
"version": "1.0.0",
|
||||
"description": "插件开发教程配套示例：演示短代码过滤器、钩子监听、后台页面、前台路由、迁移的完整写法",
|
||||
"usage": "启用后：\n1. 文章正文写 [hello 世界] 会渲染为问候语\n2. 访问 /hello-world 查看前台演示页\n3. 后台「插件 → Hello World 设置」可配置问候语\n4. 新评论会写入一条 hello_world_logs 记录（可在 tinker 查看）\n\n对照 docs/tutorial-plugin.md 学习每个文件的写法",
|
||||
"author": "LaraLog",
|
||||
"type": "demo",
|
||||
"provider": "Plugins\\Demo\\HelloWorld\\ServiceProvider",
|
||||
"filament_pages": [
|
||||
"Plugins\\Demo\\HelloWorld\\Filament\\Pages\\HelloWorldSettings"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,8 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
use Illuminate\Support\Facades\Route;
|
||||
use Plugins\Demo\HelloWorld\Http\HelloWorldController;
|
||||
|
||||
Route::get('/hello-world', [HelloWorldController::class, 'index'])->name('hello-world.index');
|
||||
@@ -0,0 +1,65 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace Plugins\Demo\HelloWorld\Filament\Pages;
|
||||
|
||||
use App\Models\Setting;
|
||||
use Filament\Actions\Action;
|
||||
use Filament\Forms\Components\TextInput;
|
||||
use Filament\Forms\Concerns\InteractsWithForms;
|
||||
use Filament\Notifications\Notification;
|
||||
use Filament\Pages\Page;
|
||||
use Filament\Schemas\Schema;
|
||||
|
||||
class HelloWorldSettings extends Page
|
||||
{
|
||||
use InteractsWithForms;
|
||||
|
||||
protected static \UnitEnum|string|null $navigationGroup = '插件';
|
||||
|
||||
protected static string|\BackedEnum|null $navigationIcon = 'heroicon-o-face-smile';
|
||||
|
||||
protected static ?string $navigationLabel = 'Hello World 设置';
|
||||
|
||||
protected static ?string $title = 'Hello World 设置';
|
||||
|
||||
protected string $view = 'filament.pages.plugin-settings';
|
||||
|
||||
public array $data = [];
|
||||
|
||||
public function mount(): void
|
||||
{
|
||||
$this->form->fill([
|
||||
'hello_world_greeting' => Setting::get('hello_world_greeting', '你好'),
|
||||
]);
|
||||
}
|
||||
|
||||
public function form(Schema $schema): Schema
|
||||
{
|
||||
return $schema
|
||||
->components([
|
||||
\Filament\Schemas\Components\Section::make('问候语')
|
||||
->schema([
|
||||
TextInput::make('hello_world_greeting')->label('默认问候语')->required(),
|
||||
]),
|
||||
])
|
||||
->statePath('data');
|
||||
}
|
||||
|
||||
public function save(): void
|
||||
{
|
||||
foreach ($this->form->getState() as $key => $value) {
|
||||
Setting::set($key, (string) $value);
|
||||
}
|
||||
|
||||
Notification::make()->title('已保存')->success()->send();
|
||||
}
|
||||
|
||||
protected function getFormActions(): array
|
||||
{
|
||||
return [
|
||||
Action::make('save')->label('保存')->submit('save'),
|
||||
];
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,25 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace Plugins\Demo\HelloWorld\Http;
|
||||
|
||||
use Plugins\Demo\HelloWorld\Models\HelloWorldLog;
|
||||
|
||||
class HelloWorldController
|
||||
{
|
||||
/**
|
||||
* 前台演示页：展示插件渲染能力（视图走插件命名空间 demo-hello::）。
|
||||
* 主题的 SidebarComposer 只覆盖核心前台视图，插件页面需手动调用它
|
||||
* 注入共享数据（siteName/siteDescription/sidebar 等），才能安全复用 partials。
|
||||
*/
|
||||
public function index()
|
||||
{
|
||||
$logs = HelloWorldLog::query()->with('comment')->latest()->limit(10)->get();
|
||||
|
||||
$view = view('demo-hello::hello', ['logs' => $logs]);
|
||||
app(\App\Blog\View\Composers\SidebarComposer::class)->compose($view);
|
||||
|
||||
return $view;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,21 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace Plugins\Demo\HelloWorld\Models;
|
||||
|
||||
use Illuminate\Database\Eloquent\Model;
|
||||
use Illuminate\Database\Eloquent\Relations\BelongsTo;
|
||||
|
||||
/**
|
||||
* 演示模型：插件自带迁移创建的表。
|
||||
*/
|
||||
class HelloWorldLog extends Model
|
||||
{
|
||||
protected $fillable = ['comment_id', 'note'];
|
||||
|
||||
public function comment(): BelongsTo
|
||||
{
|
||||
return $this->belongsTo(\App\Models\Comment::class);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,62 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace Plugins\Demo\HelloWorld;
|
||||
|
||||
use App\Blog\Support\PluginManager;
|
||||
use App\Blog\Support\PluginServiceProvider;
|
||||
use App\Models\Comment;
|
||||
use App\Models\Post;
|
||||
use App\Models\Setting;
|
||||
use Filament\Forms\Components\TextInput;
|
||||
use Filament\Schemas\Components\Section;
|
||||
use Filament\Schemas\Schema;
|
||||
use Illuminate\Support\Facades\Log;
|
||||
use Plugins\Demo\HelloWorld\Models\HelloWorldLog;
|
||||
|
||||
class ServiceProvider extends PluginServiceProvider
|
||||
{
|
||||
protected function boot(PluginManager $manager): void
|
||||
{
|
||||
// 1. 加载前台路由（可选）
|
||||
$this->loadRoutes(__DIR__.'/../routes/web.php');
|
||||
|
||||
// 2. 注册视图命名空间（可选）：views/ -> demo-hello::xxx
|
||||
$this->loadViews(__DIR__.'/../views', 'demo-hello');
|
||||
|
||||
// 3. 过滤器示例：文章渲染时把 [hello xxx] 短代码替换为问候语
|
||||
$manager->addFilter('post.rendered', function (string $html, Post $post) {
|
||||
$greeting = (string) Setting::get('hello_world_greeting', '你好');
|
||||
|
||||
return preg_replace_callback(
|
||||
'/\[hello\s+([^\]]+)\]/',
|
||||
fn (array $m) => '<span class="hello-world">'.$greeting.'，'.e($m[1]).'！</span>',
|
||||
$html
|
||||
);
|
||||
}, 20);
|
||||
|
||||
// 4. 动作示例：新评论创建时写日志（演示数据关联 + 钩子监听）
|
||||
$manager->addAction('comment.created', function (Comment $comment) {
|
||||
HelloWorldLog::create([
|
||||
'comment_id' => $comment->id,
|
||||
'note' => '捕获新评论：'.mb_substr($comment->content, 0, 30),
|
||||
]);
|
||||
Log::info('HelloWorld: 捕获新评论 #'.$comment->id);
|
||||
});
|
||||
|
||||
// 5. 后台表单注入示例：给文章编辑页加一个演示字段（meta.demo_note）
|
||||
$manager->addAction('filament.post_form', function (Schema $schema) {
|
||||
$schema->components([
|
||||
...$schema->getComponents(),
|
||||
Section::make('Hello World 演示')
|
||||
->collapsible()
|
||||
->schema([
|
||||
TextInput::make('meta.demo_note')
|
||||
->label('演示字段（存到文章 meta）')
|
||||
->helperText('这是插件注入的字段，停用插件后消失'),
|
||||
]),
|
||||
]);
|
||||
});
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,31 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>Hello World 演示 - {{ blog_setting('site_name', config('blog.name')) }}</title>
|
||||
<link rel="stylesheet" href="{{ theme('asset', 'style.css') }}">
|
||||
</head>
|
||||
<body>
|
||||
@include('partials.header')
|
||||
<div class="container main-layout">
|
||||
<main class="content">
|
||||
<article class="post-full">
|
||||
<h1 class="post-title">Hello World 演示页</h1>
|
||||
<p>这个页面由插件路由渲染，视图来自插件目录 <code>views/hello.blade.php</code>（命名空间 <code>demo-hello::</code>）。</p>
|
||||
<p>在文章正文里写 <code>[hello 世界]</code>，渲染时会变成：<span class="hello-world">你好，世界！</span></p>
|
||||
<p>最近捕获的评论（<code>hello_world_logs</code> 表）：</p>
|
||||
<ul>
|
||||
@forelse($logs as $log)
|
||||
<li>#{{ $log->comment_id }}：{{ $log->note }}</li>
|
||||
@empty
|
||||
<li>暂无记录，去发一条评论试试</li>
|
||||
@endforelse
|
||||
</ul>
|
||||
</article>
|
||||
</main>
|
||||
@include('partials.sidebar')
|
||||
</div>
|
||||
@include('partials.footer')
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user