企业官网建设流程全解析

mobile-air（NativePHP for Mobile）让你用 PHP + Laravel 直接构建真正的 iOS 和 Android 原生应用。当你需要调用相机、传感器、支付等原生能力时，答案就是原生插件：用 Kotlin 和 Swift 编写平台代码，通过nativephp.json清单向 PHP 运行时声明桥接函数，再用 Hook 机制介入构建流程。本教程带你从零完成一个插件的创建、清单声明、双端原生代码编写与 Hook 开发。

先看懂插件系统：两种类型 + 一层安全白名单

mobile-air 的插件体系位于 src/Plugins/，核心概念只有三个：

1. 两种插件类型（由composer.json的type字段决定）

2. 桥接函数（Bridge Function）：PHP 端通过nativephp_call('插件名.函数名', ...)调用，清单里声明它映射到哪个 Kotlin 类或 Swift 类。

3. 白名单机制：PluginDiscovery 扫描 Composer 已安装包后，只信任在App\Providers\NativeServiceProvider的plugins()方法中显式注册的插件——防止传递依赖偷偷注入恶意插件。所以发布插件前别忘了先注册（下文有命令）。

插件的完整能力由 Plugin.php 暴露：平台判断、权限、依赖、事件、Hook、资源、组件声明等全部从这里读取。

一键创建插件脚手架：native:plugin:create 步骤

在你的 Laravel 项目根目录执行：

php artisan native:plugin:create my-vendor/plugin-example

命令交互式询问 5 个问题：插件类型（system / ui）、包名、命名空间、描述、输出路径。常用选项：--namespace、--path、--force、--with-boost（生成 AI 辅助指南）。实现见 PluginCreateCommand.php。

系统插件会生成如下目录结构：

plugin-example/ ├── composer.json # type: nativephp-plugin ├── nativephp.json # 插件清单（核心文件） ├── src/ │ ├── ExampleServiceProvider.php │ ├── Example.php # PHP 实现类 │ ├── Facades/Example.php │ ├── Commands/CopyAssetsCommand.php # copy_assets Hook │ └── Events/ExampleCompleted.php ├── resources/ │ ├── android/ExampleFunctions.kt # Kotlin 原生代码 │ ├── ios/ExampleFunctions.swift # Swift 原生代码 │ └── js/example.js # JS 桥接模块 └── tests/ # 预置 Pest 测试

composer.json必须声明type与extra.nativephp.manifest指向清单文件，可参考 valid-plugin/composer.json。

nativephp.json 清单声明：核心字段逐项解析

清单解析与校验逻辑在 PluginManifest.php 中。唯一必填字段是namespace（须为合法 PHP 标识符），完整示例：

{ "namespace": "Example", "platforms": ["android", "ios"], "bridge_functions": [ { "name": "Example.Execute", "android": "com.myvendor.pluginexample.ExampleFunctions.Execute", "ios": "ExampleFunctions.Execute", "description": "执行插件功能" } ], "android": { "min_version": 24, "permissions": ["android.permission.VIBRATE"], "dependencies": { "implementation": ["com.example:test:1.0.0"] } }, "ios": { "min_version": "14.0", "info_plist": { "NSCameraUsageDescription": "需要相机权限" } }, "events": ["App\\Example\\Events\\ExampleCompleted"], "hooks": { "copy_assets": "nativephp:example:copy-assets" } }

关键字段说明：

• bridge_functions：每条必须有name，且至少声明android或ios一个平台实现（否则清单校验直接报错）。
• platforms：缺省表示双端；写错平台名（如"IOS"）会被拒绝而非静默忽略，见 PluginManifest.php。
• android：支持permissions、dependencies（Gradle 库）、activities/services/receivers/providers（合并进 AndroidManifest）、gradle_plugins、proguard_rules、repositories、init_function、project_files。
• ios：支持info_plist（权限描述文案）、info_plist_localizations、dependencies（SwiftPM + CocoaPods）、entitlements、capabilities、background_modes、sources（显式白名单 Swift 文件）。
• assets：构建时自动拷贝的静态资源，支持${ENV_VAR}占位符替换。
• secrets：声明构建所需的环境变量密钥，由 PluginSecretsValidator.php 在构建前校验，缺失即告警。
• events：PHP 事件类列表，原生侧回调可触发这些事件。

更多真实示例可看 valid-plugin/nativephp.json 和 plugin-with-native-code/nativephp.json。

Swift 与 Kotlin 原生代码怎么写

Kotlin（Android）：文件放在resources/android/下，每个桥接函数是一个实现BridgeFunction接口的类，且必须声明 package（编译器按 package 组织源码目录）：

object ExampleFunctions { class Execute(private val activity: FragmentActivity) : BridgeFunction { override fun execute(parameters: Map<String, Any>): Map<String, Any> { return BridgeResponse.success(mapOf("result" to "executed")) } } }

Swift（iOS）：文件放在resources/ios/下，用枚举包裹一组BridgeFunction类：

enum ExampleFunctions { class Execute: BridgeFunction { func execute(parameters: [String: Any]) throws -> [String: Any] { return BridgeResponse.success(data: ["status": "ready"]) } } }

构建时你不需要手动改任何原生工程，编译器全自动接管：

• AndroidPluginCompiler.php 把.kt文件拷贝进独立的生成源码根，自动生成PluginBridgeFunctionRegistration.kt注册文件，并合并权限、Gradle 依赖、ProGuard keep 规则。
• IOSPluginCompiler.php 拷贝 Swift 源码到ios/NativePHP/Bridge/Plugins，生成注册文件，合并 Info.plist 条目、entitlements 与 SwiftPM/CocoaPods 依赖。

每次编译都会清理旧产物重建，避免删除/改名文件后出现重复类导致编译失败。

Hook 机制：在构建流程中插入自定义逻辑

🪝 这是插件系统最灵活的部分。构建过程有 4 个 Hook 时机（定义于 PluginHookRunner.php 与 PluginHookRunner.php）：

创建 Hook 一条命令：

php artisan native:plugin:make-hook packages/my-vendor/plugin-example copy_assets

命令会生成继承自 NativePluginHookCommand 的 Hook 类，自动写回nativephp.json的hooks字段，并注册进你的 ServiceProvider（实现见 PluginMakeHookCommand.php）。

构建时框架会以 Artisan 命令方式调用你的 Hook，并传入--platform、--build-path、--plugin-path、--app-id、--config等上下文。Hook 内可用的实用方法：

• 判断平台：$this->isAndroid()/$this->isIos()
• 拷贝资源：copyToAndroidAssets()、copyToAndroidRes()、copyToIosBundle()、copyToIosAssets()
• 下载文件：downloadFile()、downloadIfMissing()、downloadAndUnzip()
• 读取上下文：buildPath()、pluginPath()、appId()、config()、allPlugins()

⚠️ 注意错误语义差异：pre_compile/copy_assets/post_compile失败会中断构建（抛出PluginHookFailedException），而post_build失败只告警不阻断——因为此时应用已经构建完成（见 PluginHookRunner.php）。

插件管理命令速查表

注册是白名单机制生效的关键一步：PluginRegisterCommand.php 会把插件的 ServiceProvider 写入app/Providers/NativeServiceProvider.php。发布前建议跑一遍native:plugin:validate（PluginValidateCommand.php）提前暴露清单错误。

上手清单：发布前自查

1. ✅composer.json声明了正确的type与extra.nativephp.manifest
2. ✅nativephp.json的namespace与 PHP 类、原生代码命名一致
3. ✅ Kotlin 文件均有package声明；桥接函数与原生类一一对应
4. ✅ 权限/Info.plist 描述文案已在清单中声明
5. ✅ 插件已通过native:plugin:register加入白名单
6. ✅native:plugin:validate无错误

掌握以上六步，你就能为 mobile-air 生态贡献自己的原生插件了——无论是封装一个相机 SDK，还是为 Blade 模板造一个全新 UI 组件。

相关源码与文档路径

• 插件核心模型：src/Plugins/Plugin.php
• 清单解析与校验：src/Plugins/PluginManifest.php
• 插件发现与白名单：src/Plugins/PluginDiscovery.php
• 双端编译器：src/Plugins/Compilers/
• 清单字段参考示例：tests/Fixtures/plugins/