🛠️ 插件本地化

ThinkAdmin 提供完善的插件本地化定制机制，支持插件的自定义修改和扩展开发。

📚 基础概念

🤔 基本介绍

插件本地化是指将插件从 vendor 目录复制到项目本地目录，进行自定义修改和扩展。

简单理解：就像把插件"搬回家"，可以自由修改，不用担心升级时被覆盖。

传统方式（不推荐）：

// ❌ 直接修改 vendor 目录下的插件
// vendor/zoujingli/think-plugs-account/src/Service.php
// 问题：执行 composer update 时会被覆盖

使用插件本地化（推荐）：

// ✅ 复制到本地目录，然后修改
// plugin/think-plugs-account/src/Service.php
// 配置 composer.json 指向本地目录
// 执行 composer update 时不会覆盖

🤔 使用优势

问题1：插件升级时代码被覆盖

直接修改 vendor 目录下的插件，执行 composer update 时会被覆盖：

# ❌ 直接修改 vendor 目录
vendor/zoujingli/think-plugs-account/src/Service.php
# 执行 composer update 后，修改丢失

问题2：无法自定义扩展

直接使用插件，无法进行自定义扩展：

// ❌ 无法修改插件代码
// 只能使用插件提供的功能
// 无法添加自定义功能

使用插件本地化的优势：

// ✅ 可以自由修改和扩展
// 1. 复制插件到本地目录
// 2. 配置 composer.json 指向本地目录
// 3. 可以自由修改，不会被覆盖

🎯 核心功能

功能1：自定义修改

可以修改插件的代码，满足特定需求：

// 修改插件 Service 类
namespace plugin\account;

class Service extends Plugin
{
    // 自定义修改
    public function register(): void
    {
        // 添加自定义逻辑
    }
}

功能2：功能扩展

可以基于插件进行功能扩展：

// 扩展插件功能
namespace app\custom;

use plugin\account\Service as AccountService;

class CustomService extends AccountService
{
    // 扩展功能
    public function customMethod()
    {
        // 自定义功能
    }
}

功能3：版本控制

可以避免插件升级时的代码覆盖：

// 本地插件不会被 composer update 覆盖
// 可以安全地进行自定义修改

🚀 主要功能

本地化开发: 支持插件的本地化定制开发
版本控制: 避免插件升级时的代码覆盖
扩展开发: 支持基于插件的功能扩展
自定义修改: 支持插件的自定义修改
社区贡献: 支持将改进贡献给社区
开发灵活性: 提供灵活的插件开发方式

⚠️ 重要提示

不建议直接修改: 应用插件安装在 vendor 目录，执行 composer 指令时可能会被替换，因此不建议直接对插件进行修改和扩展。

📋 开发方式

ThinkAdmin 支持两种开发方式，各有特点：

1. 常规应用开发

基于插件进行扩展，而不是直接修改插件本身。

特点：

扩展方式: 基于插件进行扩展，而不是直接修改
自定义模块: 通过创建自定义模块实现扩展功能
服务接口: 调用插件提供的服务接口或数据模型
兼容性: 保持对原插件的兼容性和升级能力

使用场景：

需要扩展插件功能
需要保持插件可升级
需要调用插件提供的服务

2. 定制插件开发

将插件复制到本地目录，进行自定义修改和扩展。

特点：

本地复制: 将插件复制到项目的其他目录
版本管理: 修改 composer.json 配置为开发版本
目录配置: 配置 repositories 指向本地目录
自定义修改: 对复制后的插件进行修改和扩展

使用场景：

需要修改插件核心代码
需要深度定制插件
不需要插件升级功能

🔧 开发流程

1. 插件复制

目标目录: 建议放在 plugin/package-name 目录
完整复制: 复制插件的所有文件
结构保持: 保持插件的原始结构

2. 配置修改

composer.json: 修改项目根目录的 composer.json
版本设置: 将对应 require 记录版本修改为开发版本
仓库配置: 配置 repositories 部分指向本地目录

3. 开发修改

功能扩展: 根据需求进行功能扩展
代码修改: 对插件代码进行自定义修改
测试验证: 确保修改不影响核心功能

4. 社区贡献

改进提交: 将有意义改进提交给社区
代码审查: 通过维护者审查和合并
持续发展: 促进插件的持续发展和改进

常规应用开发

在大多数情况下，建议基于插件进行扩展，而不是直接修改插件本身。为了保持插件的可持续升级，您可以通过创建自定义模块来实现扩展功能。通过调用插件提供的服务接口或数据模型，您可以轻松地利用插件的功能，同时保留对原插件的兼容性和升级能力。

这种扩展方式有助于避免破坏插件的核心代码，确保其稳定性和安全性。同时，它还提供了更大的灵活性，使您能够根据业务需求定制和扩展功能，而不会影响插件的未来更新和升级。

因此，在开发过程中我们鼓励采用插件化的扩展方式，通过调用插件的服务接口或数据模型来实现自定义功能，以确保系统的可持续性和可维护性。

定制插件开发

如果确实需要对插件进行修改和扩展（包含 admin 和 wechat 模块），可以采取以下步骤来操作：

首先，将原始插件复制到项目的其他目录。例如，对于名为 ThinkPlugsAccount 的插件，可以将其文件复制到 plugin/think-plugs-account 目录中。这样做可以保留原始插件的完整性，同时允许您在复制后的版本上进行自定义修改。

接下来，需要修改项目根目录下的 composer.json 配置文件。找到对应插件的 require 部分，并将其版本改为开发版本。如果该插件在 composer.json 中没有记录，则需要添加相应的条目，名称应与插件包配置中的 name 字段一致。

同时，在 composer.json 文件中配置 repositories 部分，指向您刚刚复制的插件目录。这样，Composer 将能够从该目录加载插件，并将其视为开发版本。

完成上述步骤后，您就可以对复制后的插件进行修改和扩展了。请注意，在进行修改时，建议遵循良好的编程实践，并确保您的更改不会破坏插件的核心功能或引入安全隐患。

最后，如果您对插件进行了有意义的改进，并希望将其贡献给社区，可以考虑与原插件的维护者联系，提交您的更改以进行审查和合并。这样可以帮助其他开发者从您的改进中受益，并促进插件的持续发展和改进。

📝 操作步骤总结

拷贝插件文件：将插件所有文件复制到项目的指定目录，建议放在 plugin/package-name 目录
修改 Composer 配置：修改项目根目录的 composer.json 配置
配置本地仓库：在 composer.json 中增加 repositories 本地记录并指向插件目录
执行更新命令：运行 composer update -o 完成插件切换
注意事项：切换后该插件将失去在线升级能力

🔧 完整配置示例

项目 composer.json 配置

{
  "type": "project",
  "name": "zoujingli/thinkadmin",
  "license": "MIT",
  "homepage": "https://thinkadmin.top",
  "description": "Application Development Framework",
  "authors": [
    {
      "name": "Anyon",
      "email": "zoujingli@qq.com"
    }
  ],
  "require": {
    "php": ">7.1",
    "ext-gd": "*",
    "ext-json": "*",
    "ext-openssl": "*",
    "zoujingli/think-plugs-account": "dev-master"
  },
  "repositories": [
    {
      "type": "path",
      "url": "plugin/think-plugs-account"
    }
  ],
  "config": {
    "sort-packages": true,
    "allow-plugins": {
      "zoujingli/think-install": true
    }
  }
}

插件 composer.json 配置插件 composer.json 配置

{
  "type": "think-admin-plugin",
  "name": "zoujingli/think-plugs-account",
  "version": "dev-master",
  "license": "VIP",
  "homepage": "https://thinkadmin.top",
  "description": "Account Plugin for ThinkAdmin",
  "authors": [
    {
      "name": "Anyon",
      "email": "zoujingli@qq.com"
    }
  ],
  "require": {
    "php": ">7.1",
    "ext-gd": "*",
    "ext-curl": "*",
    "ext-json": "*",
    "zoujingli/think-install": "^1.0|@dev",
    "zoujingli/think-library": "^6.1|@dev"
  },
  "autoload": {
    "psr-4": {
      "plugin\\account\\": "src"
    }
  },
  "extra": {
    "think": {
      "services": [
        "plugin\\account\\Service"
      ]
    },
    "config": {
      "type": "plugin",
      "name": "用户账号管理",
      "document": "https://thinkadmin.top/plugin/think-plugs-account.html",
      "license": ["VIP"]
    },
    "plugin": {
      "copy": {
        "stc/database": "database/migrations"
      }
    }
  }
}

项目 composer.json 配置（简化版）

{
  "type": "project",
  "require": {
    "zoujingli/think-plugs-account": "dev-master"
  },
  "repositories": {
    "ThinkPlugsAccount": {
      "type": "path",
      "url": "plugin/think-plugs-account"
    }
  }
}

🔧 完整操作流程

步骤1：复制插件文件

# 从 vendor 目录复制插件到本地目录
cp -r vendor/zoujingli/think-plugs-account plugin/think-plugs-account

步骤2：修改项目 composer.json

{
  "require": {
    "zoujingli/think-plugs-account": "dev-master"  // 改为开发版本
  },
  "repositories": {
    "ThinkPlugsAccount": {
      "type": "path",
      "url": "plugin/think-plugs-account"  // 指向本地目录
    }
  }
}

步骤3：执行 Composer 更新

# 更新依赖，切换到本地插件
composer update zoujingli/think-plugs-account -o

步骤4：修改插件代码

现在可以自由修改 plugin/think-plugs-account 目录下的代码，修改后立即生效。

⚠️ 注意事项

升级限制

失去在线升级能力: 切换到本地插件后，将无法通过 composer update 在线升级
手动维护: 需要手动关注原插件的更新，并手动合并更新内容

版本管理

Git 管理: 建议将本地插件目录加入 Git 版本控制
分支管理: 可以创建独立分支管理定制版本

兼容性

保持接口: 修改插件时尽量保持对外接口不变
测试验证: 修改后需要充分测试，确保不影响其他功能