README

simple-eloquent 是 hongxunpan/simple-framework 的 Eloquent 基础设施 Module。

它只负责：

声明并约束 illuminate/database 支持版本；
注册命名连接、默认连接并启动 Eloquent；
提供标准连接配置对象、可替换配置加载器和 Capsule 工厂；
提供 config/eloquent.php 默认模板；
在完整 Composer 自动加载前裁剪 Illuminate Support 与 framework 冲突的 env()；
提供不包含业务约定的基础 Model。

它不负责业务 Model、Query DSL、Projection、数据权限、Repository 业务规则或 API 响应。

安装与启用

composer require hongxunpan/simple-eloquent
php bin/simple module:enable eloquent

Composer 安装包不等于启用 Module。启用后，项目的 config/module.php 会登记 HongXunPan\SimpleEloquent\EloquentModule。Installer 只处理 Illuminate helper 冲突，不会扫描、创建、覆盖或删除项目配置文件。

配置

默认 EloquentConfigLoader 读取：

config('eloquent.default');
config('eloquent.connections');

项目没有 config/eloquent.php 时，默认 Loader 使用包内模板及标准 DB_* 环境变量，因此 minimal 项目可先启用，再决定是否显式发布配置。

eloquent.* 只是默认适配器约定，不是 Module 强制契约。运行时真正依赖的是：

HongXunPan\SimpleEloquent\Config\ConnectionConfig

自定义配置名称

$app->singleton(
    \HongXunPan\SimpleEloquent\Config\ConnectionConfigLoader::class,
    ProjectConnectionConfigLoader::class,
);

项目 Loader 可以读取任意配置名称、远程配置中心或其他来源。

不使用配置文件

$app->instance(
    \HongXunPan\SimpleEloquent\Config\ConnectionConfig::class,
    new \HongXunPan\SimpleEloquent\Config\ConnectionConfig(
        default: 'main',
        connections: $connections,
    ),
);

历史项目适配

本包不提供任何历史配置 Loader。旧项目需要继续读取原有配置时，应在消费者项目内实现 ConnectionConfigLoader，待迁移完成后随项目代码删除。

项目 Provider 在 Module Provider 之后注册，因此还可以按需覆盖 ConnectionConfig、ConnectionConfigLoader、CapsuleFactory 或整个 Capsule。

配置发布边界

resources/config/eloquent.php 是默认配置模板，但启用 Module 不会自动复制它。

需要默认配置文件时显式发布：

php bin/simple module:publish eloquent config

不接受默认配置名称的项目不执行该命令，只覆盖 Loader 或直接绑定 ConnectionConfig。

Model 边界

包内提供 HongXunPan\SimpleEloquent\Model，但启用 Module 不会自动创建项目 Model。

项目需要时应显式创建：

namespace App\Models;

abstract class Model extends \HongXunPan\SimpleEloquent\Model
{
}

resources/model/Model.php 是通用发布命令使用的模板：

php bin/simple module:publish eloquent model

发布后的文件立即归项目所有，Module refresh 不再覆盖。

Helper 兼容

Illuminate Support 12.x 会在 Composer 自动加载阶段先声明 env()。这会抢占 simple-framework 的同名核心函数。

Eloquent Installer 只禁用 Illuminate 的 env() 声明，不清空整个 helper 文件：

只接受已知的 Illuminate Support 12.x 和已知文件结构；
使用 framework AtomicFile::replace() 原子替换；
重复执行结果一致；
Composer 更新后由通用 module:refresh 重新核验；
遇到未知版本或结构立即停止；
禁用 Module 时恢复原始声明；
不创建持久备份，失败时以内存快照回滚本次文件变更。

开发验证

composer validate --strict
composer test

独立仓测试通过 require-dev 引入 Dotenv，仅用于满足 Illuminate env() 在安装器执行前的测试依赖；Module 运行时仍由 simple-framework 提供环境变量能力。

正式发布前还必须在 simple-php 集成站点完成 require → module:enable → 完整启动 验证。Composer 安全公告验证是否执行，以对应发布任务单为准，不在本包 README 中设为固定门禁。

hongxunpan / simple-eloquent

Maintainers

Package info

Statistics

Security