创建插件

脚手架插件

创建插件的最快方法是使用交互式脚手架命令：

php artisan native:plugin:create

这将引导你完成命名、命名空间选择和功能选项，然后生成完整的插件结构。

10 倍速构建插件

编写原生 Kotlin 和 Swift 代码是插件开发中最困难的部分。用于 Claude Code 的 NativePHP 插件开发工具包可以在几分钟内生成生产就绪的插件——包含桥接函数、事件、权限和平台特定实现。

获取插件开发工具包 →

插件结构

插件遵循标准布局：

my-plugin/
├── composer.json          # 包元数据，type 必须是 "nativephp-plugin"
├── nativephp.json         # 插件清单
├── src/
│   ├── MyPluginServiceProvider.php
│   ├── MyPlugin.php       # 主类
│   ├── Facades/
│   │   └── MyPlugin.php
│   ├── Events/
│   │   └── SomethingHappened.php
│   └── Commands/          # 生命周期钩子命令
├── resources/
│   ├── android/src/       # Kotlin 桥接函数
│   ├── ios/Sources/       # Swift 桥接函数
│   └── js/                # JavaScript 库存根

Android 包命名

Android/Kotlin 代码必须在每个文件顶部声明包。使用你自己的供应商命名空间包以避免冲突：

// resources/android/src/MyPluginFunctions.kt
package com.myvendor.plugins.myplugin

import com.nativephp.mobile.bridge.BridgeFunction
import com.nativephp.mobile.bridge.BridgeResponse

object MyPluginFunctions {
    class DoSomething : BridgeFunction {
        override fun execute(parameters: Map<String, Any>): Map<String, Any> {
            return BridgeResponse.success(mapOf("status" to "done"))
        }
    }
}

编译器根据包声明放置文件，因此 package com.myvendor.plugins.myplugin 导致文件被放置在 app/src/main/java/com/myvendor/plugins/myplugin/MyPluginFunctions.kt。

注意

没有包声明的文件将被放置在回退位置，但这不推荐。始终在你的 Kotlin 文件中声明包。

在清单的桥接函数中引用完整的包路径：

{
    "bridge_functions": [{
        "name": "MyPlugin.DoSomething",
        "android": "com.myvendor.plugins.myplugin.MyPluginFunctions.DoSomething"
    }]
}

composer.json

你的 composer.json 必须指定插件类型：

{
    "name": "vendor/my-plugin",
    "type": "nativephp-plugin",
    "extra": {
        "laravel": {
            "providers": ["Vendor\\MyPlugin\\MyPluginServiceProvider"]
        },
        "nativephp": {
            "manifest": "nativephp.json"
        }
    }
}

type: nativephp-plugin 告诉 NativePHP 在此包中查找原生代码。

nativephp.json 清单

清单声明插件的原生特定配置。包元数据（name、version、description、service_provider）来自你的 composer.json——不要在这里重复。

{
    "namespace": "MyPlugin",
    "bridge_functions": [
        {
            "name": "MyPlugin.DoSomething",
            "ios": "MyPluginFunctions.DoSomething",
            "android": "com.nativephp.plugins.myplugin.MyPluginFunctions.DoSomething"
        }
    ],
    "events": ["Vendor\\MyPlugin\\Events\\SomethingHappened"],
    "android": {
        "permissions": ["android.permission.CAMERA"],
        "dependencies": {
            "implementation": ["com.google.mlkit:barcode-scanning:17.2.0"]
        }
    },
    "ios": {
        "info_plist": {
            "NSCameraUsageDescription": "Camera is used for scanning"
        },
        "dependencies": {
            "pods": [{"name": "GoogleMLKit/BarcodeScanning", "version": "~> 4.0"}]
        }
    }
}

清单字段

字段	必需	描述
namespace	是	插件的命名空间（用于代码生成和目录结构）
bridge_functions	否	原生函数映射数组
events	否	插件分发的事件类
android.permissions	否	Android 权限字符串
android.features	否	Android uses-feature 声明
android.dependencies	否	Gradle 依赖项
android.repositories	否	自定义 Maven 仓库
android.activities	否	要在清单中注册的 Activities
android.services	否	要在清单中注册的 Services
android.receivers	否	要注册的广播接收器
android.providers	否	要注册的 Content Providers
android.meta_data	否	应用程序 meta-data 条目
android.min_version	否	所需的最低 Android SDK 版本
android.init_function	否	在应用初始化期间调用的原生函数
ios.info_plist	否	Info.plist 条目（权限、API 密钥）
ios.dependencies	否	Swift 包和 CocoaPods
ios.background_modes	否	UIBackgroundModes 值
ios.entitlements	否	应用权利
ios.capabilities	否	Xcode 项目的 iOS 功能
ios.min_version	否	所需的最低 iOS 版本
ios.init_function	否	在应用初始化期间调用的原生函数
assets	否	声明式资源复制
hooks	否	生命周期钩子命令
secrets	否	必需的环境变量

有关每个字段的详细文档，请参阅高级配置。

本地开发

在开发期间，将你的插件作为路径仓库添加到应用的 composer.json 中：

{
    "repositories": [
        {"type": "path", "url": "../packages/my-plugin"}
    ]
}

然后引入它：

composer require vendor/my-plugin

对插件 PHP 代码的更改会立即生效。对原生代码的更改需要使用 php artisan native:run 重新构建。

在测试插件原生代码或清单的重大更改时，你可能需要强制全新安装原生项目：

php artisan native:install --force

这确保原生项目使用你最新的插件配置从头重建。

尽早且频繁验证

运行 php artisan native:plugin:validate 在尝试构建之前捕获清单错误、缺失的原生代码或不匹配的函数声明。

注册插件

使用 Composer 安装插件后，你需要注册它，以便它被编译到你的原生构建中。

首次设置

发布 NativeServiceProvider：

php artisan vendor:publish --tag=nativephp-plugins-provider

这会创建 app/Providers/NativeServiceProvider.php。

注册插件

php artisan native:plugin:register vendor/plugin-name

这会自动将插件的服务提供者添加到你的 plugins() 数组中：

public function plugins(): array
{
    return [
        \Vendor\PluginName\PluginNameServiceProvider::class,
    ];
}

列出插件

# 显示已注册的插件
php artisan native:plugin:list

# 显示所有已安装的插件（包括未注册的）
php artisan native:plugin:list --all

移除插件

php artisan native:plugin:register vendor/plugin-name --remove

注意

这种明确注册是一种安全措施。它防止传递依赖项在未经你同意的情况下自动注册插件。

JavaScript 库

插件可以为 SPA 框架提供 JavaScript 库。脚手架在 resources/js/ 中创建一个存根：

// resources/js/myPlugin.js
const baseUrl = '/_native/api/call';

async function bridgeCall(method, params = {}) {
    const response = await fetch(baseUrl, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ method, params })
    });
    return response.json();
}

export async function doSomething(options = {}) {
    return bridgeCall('MyPlugin.DoSomething', options);
}

用户可以直接在 Vue、React 或原生 JS 中导入你的函数。

NativePHP 插件开发工具包

构建原生插件的最快方式

大多数 Laravel 开发者不是 Kotlin 或 Swift 专家——这没关系。用于 Claude Code 的 NativePHP 插件开发工具包将自然语言转换为生产就绪的原生代码。

描述你想要的（"一个扫描条形码并返回产品信息的插件"），就能获得一个完整、可工作的插件，包含正确的桥接函数、事件、权限以及 iOS 和 Android 实现。

获取插件开发工具包 →

如果你使用 Claude Code，插件开发工具包通过专门针对 NativePHP 架构训练的专业代理来增强你的工作流程。

包含内容

• Kotlin/Android 专家代理 — 编写正确的桥接函数，处理 Android 生命周期，配置 Gradle
• Swift/iOS 专家代理 — 实现 iOS 桥接函数，管理 Info.plist，配置 SPM/CocoaPods
• 插件架构师代理 — 设计插件结构、清单配置和 Laravel 集成
• 交互式命令 — /create-nativephp-plugin 从描述中生成完整插件
• 验证工具 — /validate-nativephp-plugin 在构建前捕获错误

为什么值得

编写原生移动代码很难。这些代理理解：

• NativePHP 的桥接函数模式和响应格式
• 平台特定的 API 以及如何将它们暴露给 PHP
• 权限声明、权利和清单配置
• 从原生代码向 Livewire 组件分发事件
• 跨 Gradle、CocoaPods 和 SPM 的依赖管理

不需要学习两种新语言及其生态系统，描述你需要什么，让代理处理实现细节。

获取插件开发工具包 →

AI 开发工具

NativePHP 包含用于 AI 辅助插件开发的内置命令。

安装开发代理

为插件开发安装专业 AI 代理：

php artisan native:plugin:install-agent

这会将代理定义文件复制到项目的 .claude/agents/ 目录。可用的代理包括：

• kotlin-android-expert — 深度 Android/Kotlin 原生开发
• swift-ios-expert — 深度 iOS/Swift 原生开发
• js-bridge-expert — JavaScript/TypeScript 客户端集成
• plugin-writer — 通用插件脚手架和结构
• plugin-docs-writer — 文档和 Boost 指南

使用 --all 安装所有代理而不提示，或使用 --force 覆盖现有文件。

创建 Boost 指南

如果你使用 Boost，为你的插件创建 AI 指南：

php artisan native:plugin:boost

这会在你的插件中生成 resources/boost/guidelines/core.blade.php 文件，记录：

• 如何使用你的插件 facade
• 可用方法及其描述
• 事件以及如何监听它们
• JavaScript 使用示例

当用户安装你的插件并运行 php artisan boost:install 时，这些指南会自动加载，帮助 AI 助手正确理解如何使用你的插件。

准备好构建了吗？

你现在拥有创建 NativePHP 插件所需的一切。对于大多数开发者，插件开发工具包是从想法到可工作插件的最快路径——它处理原生代码的复杂性，让你可以专注于插件做什么，而不是如何编写 Kotlin 和 Swift。