PHPackages                             luoyou/hyperf-json-relation - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. luoyou/hyperf-json-relation

ActiveLibrary[Database & ORM](/categories/database)

luoyou/hyperf-json-relation
===========================

基于hyperf的json-relation，解决数据库中使用json字段的关联with问题

1.0.0(2y ago)35MITPHP

Since Aug 20Pushed 2y ago1 watchersCompare

[ Source](https://github.com/luoyou/hyperf-json-relation)[ Packagist](https://packagist.org/packages/luoyou/hyperf-json-relation)[ RSS](/packages/luoyou-hyperf-json-relation/feed)WikiDiscussions main Synced yesterday

READMEChangelogDependencies (4)Versions (2)Used By (0)

介绍
--

[](#介绍)

本扩展基于 [staudenmeir/eloquent-json-relations](https://github.com/staudenmeir/eloquent-json-relations) ，将其对 hyperf 做了适配，使其支持 mysql 中的 json 字段的关联

源库支持 MySQL,MariaDB,postgreSQL,SQLite,SQL Server，但 hyperf 的 ORM 目前仅支持 MySQL，所以目前仅针对 MySQL 做了适配，后续 hyperf 支持其他数据库时再进行适配

本扩展为 `BelongsTo`、`HasOne`、`HasMany`、`HasOneThrough`、`HasManyThrough`、`MorphTo`、`MorphOne` 和 `MorphMany` 关系添加了对 JSON 外键的支持。

它还为 [many-to-many](#many-to-many-relationships) 和 [has-many-through](#has-many-through-relationships) 关系提供了 JSON 数组支持。

兼容性
---

[](#兼容性)

数据库HyperfMySQL 5.7+3.0+安装
--

[](#安装)

```
composer require "luoyou/hyperf-json-relation:^1.0"
```

使用方法
----

[](#使用方法)

- [一对多关系](#%E4%B8%80%E5%AF%B9%E5%A4%9A%E5%85%B3%E7%B3%BB)
- [多对多关系](#%E5%A4%9A%E5%AF%B9%E5%A4%9A%E5%85%B3%E7%B3%BB)
    - [查询性能](#mysql-%E6%9F%A5%E8%AF%A2%E6%80%A7%E8%83%BD)

### 一对多关系

[](#一对多关系)

在这个示例中，User 与 Locale 之间有一个 BelongsTo 关系。没有专用的列，但外键（locale\_id）存储在 JSON 字段中（users.options）：

```
class User extends Model
{
    use \Luoyou\HyperfJsonRelation\HasJsonRelationships;

    protected $casts = [
        'options' => 'json',
    ];

    public function locale()
    {
        return $this->belongsTo(Locale::class, 'options->locale_id');
    }
}

class Locale extends Model
{
    use \Luoyou\HyperfJsonRelation\HasJsonRelationships;

    public function users()
    {
        return $this->hasMany(User::class, 'options->locale_id');
    }
}
```

### 多对多关系

[](#多对多关系)

该扩展还引入了两种新的关系类型：BelongsToJson 和 HasManyJson。

使用它们可以实现包含 JSON 数组的多对多关系。

在这个示例中，User 与 Role 之间有一个 BelongsToMany 关系。没有中间表，但外键以数组形式存储在 JSON 字段中（users.options）：

1. ID 数组 默认情况下，关系以 ID 数组的形式存储中间记录：

```
class User extends Model
{
    use \Luoyou\HyperfJsonRelation\HasJsonRelationships;

    protected $casts = [
       'options' => 'json',
    ];

    public function roles()
    {
        return $this->belongsToJson(Role::class, 'options->role_ids');
    }
}

class Role extends Model
{
    use \Luoyou\HyperfJsonRelation\HasJsonRelationships;

    public function users()
    {
       return $this->hasManyJson(User::class, 'options->role_ids');
    }
}
```

2. 对象数据 还可以将中间记录存储为带有福建属性的对象：

```
class User extends Model
{
    use \Luoyou\HyperfJsonRelation\HasJsonRelationships;

    protected $casts = [
       'options' => 'json',
    ];

    public function roles()
    {
        return $this->belongsToJson(Role::class, 'options->roles[]->role_id');
    }
}

class Role extends Model
{
    use \Luoyou\HyperfJsonRelation\HasJsonRelationships;

    public function users()
    {
       return $this->hasManyJson(User::class, 'options->roles[]->role_id');
    }
}
```

在这里，options->roles 是 JSON 数组的路径。role\_id 是记录对象内部的外键属性的名称：

MySQL 查询性能
----------

[](#mysql-查询性能)

在 MySQL 8.0.17+ 上，我们可以通过[多值索引](https://dev.mysql.com/doc/refman/8.0/en/create-index.html#create-index-multi-valued)来提高查询性能。

当数组是列本身时（例如 users.role\_ids），使用以下迁移：

```
Schema::create('users', function (Blueprint $table) {
    // ...

    // ID 数组
    $table->rawIndex('(cast(`role_ids` as unsigned array))', 'users_role_ids_index');

    // 对象数组
    $table->rawIndex('(cast(`roles`->\'$[*]."role_id"\' as unsigned array))', 'users_roles_index');
});
```

当数组嵌套在对象内部时（例如 users.options->role\_ids），使用以下迁移：

```
Schema::create('users', function (Blueprint $table) {
    // ...

    // ID 数组
    $table->rawIndex('(cast(`options`->\'$."role_ids"\' as unsigned array))', 'users_role_ids_index');

    // 对象数组
    $table->rawIndex('(cast(`options`->\'$."roles"[*]."role_id"\' as unsigned array))', 'users_roles_index');
});
```

创建多值索引与普通的索引不同，其中在已经运行的业务上添加多值索引后，很可能引起当前代码插入报错（未满足 json 字段转换为多值索引的结果要求）,查询的时候只有`member of`,`json_contains`,`json_overlaps`三个函数可以走到索引，添加索引前请务必仔细测试代码，避免插入数据报错，通过 explain 来检查能否走到索引。

---

更多详细的使用文档，请参照源代码库：

###  Health Score

21

—

LowBetter than 18% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity7

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

1049d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/2688923?v=4)[luo](/maintainers/luoyou)[@luoyou](https://github.com/luoyou)

---

Top Contributors

[![luoyou](https://avatars.githubusercontent.com/u/2688923?v=4)](https://github.com/luoyou "luoyou (6 commits)")

### Embed Badge

![Health badge](/badges/luoyou-hyperf-json-relation/health.svg)

```
[![Health](https://phpackages.com/badges/luoyou-hyperf-json-relation/health.svg)](https://phpackages.com/packages/luoyou-hyperf-json-relation)
```

###  Alternatives

[hyperf/database

A flexible database library.

192.9M322](/packages/hyperf-database)[hyperf/database-pgsql

A pgsql handler for hyperf/database.

12321.2k22](/packages/hyperf-database-pgsql)[hyperf/amqp

A amqplib for hyperf.

231.3M72](/packages/hyperf-amqp)[hyperf/http-server

A HTTP Server for Hyperf.

103.0M372](/packages/hyperf-http-server)[chadw/hyperf-database-sqlserver

Add Sql Server support to Hyperf

109.5k](/packages/chadw-hyperf-database-sqlserver)[jonas-elias/hyperf-oracle

A oracle handler for hyperf/database.

102.5k](/packages/jonas-elias-hyperf-oracle)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)