README

NeoEloquent

Neo4j 图 Eloquent 驱动程序 for Laravel，这是由 Ulobby 创建的 Vinelab/NeoEloquent 的分支。

此存储库的版本控制方案遵循 Laravel，因此此包的主版本与 Laravel 支持的主版本相对应。例如，NeoEloquent v6 支持 Laravel v6，NeoEloquent v8 支持 Laravel v8。

在 Ulobby，我们使用 NeoEloquent 在基于 Laravel 的 SaaS 中执行大量 CRUD 操作。由于更复杂的操作通常需要编写原始的 Cypher 语句，因此我们目前不推荐使用多态关系。

聊天 & 支持

加入官方 Neo4j Slack 群组并使用 #neo4j-php 频道。

安装

将包添加到您的 composer.json 并运行 composer update。

Laravel 8

8.0

{
    "require": {
        "ulobby/neoeloquent": "^8.0"
    }
}

Laravel 7

7.0

{
    "require": {
        "ulobby/neoeloquent": "^7.0"
    }
}

Laravel 6

6.0

{
    "require": {
        "ulobby/neoeloquent": "^6.0"
    }
}

在 app/config/app.php 中添加服务提供者

'Vinelab\NeoEloquent\NeoEloquentServiceProvider',

服务提供者将注册此包所需的所有类，并将 Model 类别名到 NeoEloquent，这样您就可以在模型中简单地使用 extend NeoEloquent。

配置

连接

在 app/config/database.php 或在基于环境的配置情况下 app/config/[env]/database.php 中，将 neo4j 设置为默认连接

'default' => 'neo4j',

添加连接默认值

'connections' => [
    'neo4j' => [
        'driver' => 'neo4j',
        'host'   => env('DB_HOST', 'localhost'),
        'port'   => env('DB_PORT', '7474'),
        'username' => env('DB_USERNAME', null),
        'password' => env('DB_PASSWORD', null)
    ]
]

迁移设置

如果您想使用迁移

创建文件夹 app/database/labels
修改 composer.json 并将 app/database/labels 添加到 classmap 数组中
运行 composer dump-autoload

文档

模型

节点标签
软删除

class User extends NeoEloquent {}

NeoEloquent 生成默认节点标签与类名相同，在这种情况下将是 :User。有关节点标签的更多信息，请参阅此处

命名空间模型

当您使用模型命名空间时，标签将考虑完整的命名空间。

namespace Vinelab\Cms;

class Admin extends NeoEloquent { }

从该关系生成的标签将是 VinelabCmsAdmin，这是必要的，以确保在引入另一个 Admin 实例（如 Vinelab\Blog\Admin）时标签不会冲突，这样数据库中的 :Admin 就会变得混乱。

自定义节点标签

您可以指定希望使用的标签（而不是默认生成的标签），它们也是大小写敏感的，因此将按照此处存储。

class User extends NeoEloquent {

    protected $label = 'User'; // or array('User', 'Fan')

    protected $fillable = ['name', 'email'];
}

$user = User::create(['name' => 'Some Name', 'email' => 'some@email.com']);

NeoEloquent 对 $table 变量的回退支持，如果找到并且模型上没有定义 $label，则将使用它。

class User extends NeoEloquent {

    protected $table = 'User';

}

无需担心标签格式，您可以将它们指定为 array('Label1', 'Label2') 或通过冒号分隔它们，并在前面加上冒号是可选的。

软删除

Laravel 5

要启用软删除，您需要使用 use Vinelab\NeoEloquent\Eloquent\SoftDeletes 而不是 Illuminate\Database\Eloquent\SoftDeletes，并且与 Eloquent 一样，您需要在模型中包含 $dates，如下所示

use Vinelab\NeoEloquent\Eloquent\SoftDeletes;

class User extends NeoEloquent {

    use SoftDeletes;

    protected $dates = ['deleted_at'];

}

关系

一对一
一对多
多对多
多态

让我们通过一些节点之间关系示例进行说明。

一对一

class User extends NeoEloquent {

    public function phone()
    {
        return $this->hasOne('Phone');
    }

这表示从 :User 节点到 :Phone 节点的 OUTGOING 关系方向。

保存

$phone = new Phone(['code' => 961, 'number' => '98765432'])
$relation = $user->phone()->save($phone);

此语句执行的 Cypher 语句如下

MATCH (user:`User`)
WHERE id(user) = 1
CREATE (user)-[:PHONE]->(phone:`Phone` {code: 961, number: '98765432', created_at: 7543788, updated_at: 7543788})
RETURN phone;

定义此关系的逆关系

class Phone extends NeoEloquent {

    public function user()
    {
        return $this->belongsTo('User');
    }
}

这表示从 :User 节点到该 :Phone 节点的 INCOMING 关系方向。

关联模型

由于我们不处理外键，在我们的案例中，这不仅仅是设置父模型的 foreign key 属性。在 Neo4j（以及图数据库）中，关系本身就是一个实体，也可以有自己的属性，因此引入了边

注意：关联模型在调用 associate() 时不会自动持久化关系。

$account = Account::find(1986);

// $relation will be Vinelab\NeoEloquent\Eloquent\Edges\EdgeIn
$relation = $user->account()->associate($account);

// Save the relation
$relation->save();

此语句执行的 Cypher 语句如下

MATCH (account:`Account`), (user:`User`)
WHERE id(account) = 1986 AND id(user) = 9862
MERGE (account)<-[rel_user_account:ACCOUNT]-(user)
RETURN rel_user_account;

一对多

class User extends NeoEloquent {

    public function posts()
    {
        return $this->hasMany('Post', 'POSTED');
    }
}

这表示从 :User 节点到 :Post 节点的 OUTGOING 关系方向。

$user = User::find(1);
$post = new Post(['title' => 'The Title', 'body' => 'Hot Body']);
$user->posts()->save($post);

类似于 One-To-One 关系，save() 语句返回的值是 Edge[In|Out]

此语句执行的 Cypher 语句如下

MATCH (user:`User`)
WHERE id(user) = 1
CREATE (user)-[rel_user_post:POSTED]->(post:`Post` {title: 'The Title', body: 'Hot Body', created_at: '15-05-2014', updated_at: '15-05-2014'})
RETURN rel_user_post;

定义此关系的逆关系

class Post extends NeoEloquent {

    public function author()
    {
        return $this->belongsTo('User', 'POSTED');
    }
}

这表示从 :User 节点到该 :Post 节点的 INCOMING 关系方向。

多对多

class User extends NeoEloquent {

    public function followers()
    {
        return $this->belongsToMany('User', 'FOLLOWS');
    }
}

这表示一个 :User 节点与另一个 :User 节点之间的 INCOMING 关系。

$jd = User::find(1012);
$mc = User::find(1013);

$jd 关注 $mc

$jd->followers()->save($mc);

或使用 attach() 方法

$jd->followers()->attach($mc);
// Or..
$jd->followers()->attach(1013); // 1013 being the id of $mc ($mc->getKey())

此语句执行的 Cypher 语句如下

MATCH (user:`User`), (followers:`User`)
WHERE id(user) = 1012 AND id(followers) = 1013
CREATE (followers)-[:FOLLOWS]->(user)
RETURN rel_follows;

$mc 反关注 $jd

$mc->followers()->save($jd);

此语句执行的 Cypher 语句如下

MATCH (user:`User`), (followers:`User`)
WHERE id(user) = 1013 AND id(followers) = 1012
CREATE (user)-[rel_user_followers:FOLLOWS]->(followers)
RETURN rel_follows;

获取 $jd 的关注者

$followers = $jd->followers;

此语句执行的 Cypher 语句如下

MATCH (user:`User`), (followers:`User`), (user)-[rel_user_followers:FOLLOWS]-(followers)
WHERE id(user) = 1012
RETURN rel_follows;

动态属性

class Phone extends NeoEloquent {

    public function user()
    {
        return $this->belongsTo('User');
    }

}

$phone = Phone::find(1006);
$user = $phone->user;
// or getting an attribute out of the related model
$name = $phone->user->name;

多态

多态关系的概念在本质上与骨骼相关，但在图数据库中，我们将其表示为 HyperEdge。

HyperEdge 涉及三个模型，即父模型、Hyper 模型和相关模型，如图所示

在代码中，这将通过三个模型 User、Comment 和 Post 表示，其中 ID 为 1 的 User 发布了一条 Post，而 ID 为 6 的 User 在该 Post 上 COMMENTED 一条 Comment，如下所示

class User extends NeoEloquent {

    public function comments($morph = null)
    {
        return $this->hyperMorph($morph, 'Comment', 'COMMENTED', 'ON');
    }

}

为了保持简单但仍然涉及三个模型，我们必须传递 $morph，它可以是任何 commentable 模型，在我们的案例中是 Video 或 Post 模型。

注意：请确保将其默认设置为 null，这样我们就可以稍后通过 $user->comments 动态或急切地加载。

使用 create() 方法创建 Comment。

$user = User::find(6);
$post = Post::find(2);

$user->comments($post)->create(['text' => 'Totally agree!', 'likes' => 0, 'abuse' => 0]);

通常我们将返回一个边，但这次它不是有方向的，它是一个 HyperEdge 的实例，更多信息请参阅HyperEdges。

或者你可以保存 Comment 实例

$comment = new Comment(['text' => 'Magnificent', 'likes' => 0, 'abuse' => 0]);

$user->comments($post)->save($comment);

还支持在 BelongsToMany 关系中找到的所有功能，如通过 ID 关联模型

$user->comments($post)->attach([$id, $otherId]);

或断开模型

$user->comments($post)->detach($comment); // or $comment->id

同步

$user->comments($post)->sync([$id, $otherId, $someId]);

检索多态关系

从我们之前的示例中，我们将使用 Video 模型来检索它们的评论

class Video extends NeoEloquent {

    public function comments()
    {
        return $this->morphMany('Comment', 'ON');
    }

}

动态加载多态模型

$video = Video::find(3);
$comments = $video->comments;

急切加载多态模型

$video = Video::with('comments')->find(3);
foreach ($video->comments as $comment)
{
    //
}

检索多态关系的逆关系

class Comment extends NeoEloquent {

    public function commentable()
    {
        return $this->morphTo();
    }

}

$postComment = Comment::find(7);
$post = $comment->commentable;

$videoComment = Comment::find(5);
$video = $comment->commentable;

// You can also eager load them
Comment::with('commentable')->get();

您还可以指定希望返回的 morph 类型

class Comment extends NeoEloquent {

    public function post()
    {
        return $this->morphTo('Post', 'ON');
    }

    public function video()
    {
        return $this->morphTo('Video', 'ON');
    }

}

多态关系简述

为了深入了解，以下是参与多态关系的三个模型是如何连接的

class User extends NeoEloquent {

    public function comments($morph = null)
    {
        return $this->hyperMorph($morph, 'Comment', 'COMMENTED', 'ON');
    }

}

class Post extends NeoEloquent { // Video is the same as this one

    public function comments()
    {
        return $this->morphMany('Comment', 'ON');
    }

}

class Comment extends NeoEloquent {

    public function commentable()
    {
        return $this->morphTo();
    }

}

急切加载

class Book extends NeoEloquent {

    public function author()
    {
        return $this->belongsTo('Author');
    }
}

以尽可能低的开销加载作者及其书籍。

foreach (Book::with('author')->get() as $book)
{
    echo $book->author->name;
}

循环中只运行了两个 Cypher 查询

MATCH (book:`Book`) RETURN *;

MATCH (book:`Book`), (book)<-[:WROTE]-(author:`Author`) WHERE id(book) IN [1, 2, 3, 4, 5, ...] RETURN book, author;

边

EdgeIn
EdgeOut
HyperEdge
处理边
边属性

简介

由于图中的关系与其它数据库类型有很大不同，因此我们需要相应地处理它们。关系有方向，可以是分别指向父节点的入向和出向。

EdgeIn

表示从相关模型指向父模型的方向为INCOMING的关系。

class Location extends NeoEloquent {

    public function user()
    {
        return $this->belongsTo('User', 'LOCATED_AT');
    }

}

将User关联到Location

$location = Location::find(1922);
$user = User::find(3876);
$relation = $location->associate($user);

在Cypher中，这会映射为(:Location)<-[:LOCATED_AT]-(:User)，其中$relation是一个表示指向父节点的入向关系的EdgeIn实例。

并且您仍然可以访问边上的模型

$relation = $location->associate($user);
$location = $relation->parent();
$user = $relation->related();

EdgeOut

表示从父模型指向相关模型的方向为OUTGOING的关系。

class User extends NeoEloquent {

    public function posts()
    {
        return $this->hasMany('Post', 'POSTED');
    }

}

要保存从:User到:Post的出向边，它看起来是这样的

$post = new Post(['...']);
$posted = $user->posts()->save($post);

在Cypher中，这将表示为(:User)-[:POSTED]->(:Post)，其中$posted是EdgeOut实例。

并获取相关模型

$edge = $user->posts()->save($post);
$user = $edge->parent();
$post = $edge->related();

HyperEdge

此边作为多态关系的结果出现，表示涉及两个其他边left和right的边，可以通过left()和right()方法访问。

此边与其他边略有不同，因为它不是两个模型之间的直接关系，这意味着它没有特定的方向。

$edge = $user->comments($post)->attach($comment);
// Access the left and right edges
$left = $edge->left();
$user = $left->parent();
$comment = $left->related();

$right = $edge->right();
$comment = $right->parent();
$post = $right->related();

处理边

如前所述，与SQL中的外键不同，边是图中的实体，在文档中，它们要么是嵌入，要么是作为引用的id。因此，我们开发了它们来作为轻量级模型，这意味着您可以像处理Eloquent实例一样处理它们 - 在一定程度上，除了超边。

// Create a new relationship
$relation = $location->associate($user); // Vinelab\NeoEloquent\Eloquent\Edges\EdgeIn

// Save the relationship to the database
$relation->save(); // true

对于HyperEdge，您可以通过以下方式访问所有三个模型

$edge    = $user->comments($post)->save($comment);
$user    = $edge->parent();
$comment = $edge->hyper();
$post    = $edge->related();

边属性

默认情况下，边将具有created_at和updated_at时间戳，并且只有在将父模型上的$timestamps设置为true以启用时间戳时才会自动设置和更新。

$located_at = $location->associate($user);
$located_at->since = 1966;
$located_at->present = true;
$located_at->save();

// $created_at and $updated_at are Carbon\Carbon instances
$created_at = $located_at->created_at;
$updated_at = $located_at->updated_at;

从关系检索边

与创建关联将创建一个EdgeIn关系相同，我们可以通过在belongsTo关系上调用edge($model)方法来检索两个模型之间的边。

$location = Location::find(1892);
$edge = $location->user()->edge();

您也可以指定边的另一端的模型。

注意：默认情况下，NeoEloquent会尝试执行内部操作$location->user以根据关系函数名确定边的相关端，在这种情况下是user()。

$location = Location::find(1892);
$edge = $location->user()->edge($location->user);

仅限 Neo

使用CreateWith

在这里，您将找到NeoEloquent特定的方法和实现，这些方法和Eloquent方法一起使处理图和Neo4j变得非常愉快！

使用CreateWith

创建关系
附加关系

此方法将“某种程度上”填补关系数据库和文档数据库之间的差距，它允许在一次数据库调用中创建多个相关模型。

创建新记录和关系

以下是一个创建包含附件照片和视频的帖子的示例

class Post extends NeoEloquent {

    public function photos()
    {
        return $this->hasMany('Photo', 'PHOTO');
    }

    public function videos()
    {
        return $this->hasMany('Video', 'VIDEO');
    }
}

Post::createWith(['title' => 'the title', 'body' => 'the body'], [
    'photos' => [
        [
            'url'      => 'http://url',
            'caption'  => '...',
            'metadata' => '...'
        ],
        [
            'url' => 'http://other.url',
            'caption' => 'the bay',
            'metadata' => '...'
        ]
    ],

    'videos' => [
        'title' => 'Boats passing us by',
        'description' => '...'
    ]
]);

键photos和videos必须与Post模型中关系方法的名称相同。

上面示例中执行的Cypher查询是

CREATE (post:`Post` {title: 'the title', body: 'the body'}),
(post)-[:PHOTO]->(:`Photo` {url: 'http://url', caption: '...', metadata: '...'}),
(post)-[:PHOTO]->(:`Photo` {url: 'http://other', caption: 'the bay', metadata: '...'}),
(post)-[:VIDEO]->(:`Video` {title: 'Boats passing us by', description: '...'});

我们将以这种方式获取创建的节点及其关系

您也可以混合模型和属性作为关系值，但不是必需的，因为NeoEloquent会将提供的属性通过$fillable过滤器管道传递。

$videos = new Video(['title' => 'foo', 'description' => 'bar']);
Post::createWith($info, compact('videos'));

您也可以使用单个属性数组

class User extends NeoEloquent {

    public function account()
    {
        return $this->hasOne('Account');
    }
}

User::createWith(['name' => 'foo'], ['account' => ['guid' => 'bar', 'email' => 'some@mail.net']]);

将现有记录作为关系附加

createWith足够智能，可以知道当您传递现有模型、模型ID或需要创建的新记录时，它知道差异，这允许混合新记录和现有记录。

class Post extends NeoEloquent {

    public function tags()
    {
        return $this->hasMany('Tag', 'TAG');
    }
}

$tag1 = Tag::create(['title' => 'php']);
$tag2 = Tag::create(['title' => 'dev']);

$post = Post::createWith(['title' => 'foo', 'body' => 'bar'], ['tags' => [$tag1, $tag2]]);

我们将获取与现有 Tag 节点相关的 Post。

或者使用模型的 id。

Post::createWith(['title' => 'foo', 'body' => 'bar'], ['tags' => 1, 'privacy' => 2]);

附加记录的查询的 Cypher 语句为：

CREATE (post:`Post` {title: 'foo', 'body' => 'bar'})
WITH post
MATCH (tag:`Tag`)
WHERE id(tag) IN [1, 2]
CREATE (post)-[:TAG]->(tag);

迁移

为了使迁移工作，请执行以下操作：

创建文件夹 app/database/labels
修改 composer.json 并将 app/database/labels 添加到 classmap 数组中

由于 Neo4j 是一个无模式的数据库，因此您不需要预先定义标签的属性类型。但是，您可以使用 NeoEloquent 的简单索引和约束。

命令

NeoEloquent 在 neo4j 命名空间下引入了新的命令，因此您仍然可以并行使用 Eloquent 的迁移命令。

迁移命令与 Eloquent 的相同，形式为 neo4j:migrate[:command]

neo4j:make:migration                 Create a new migration file
neo4j:migrate                        Run the database migrations
neo4j:migrate:reset                  Rollback all database migrations
neo4j:migrate:refresh                Reset and re-run all migrations
neo4j:migrate:rollback               Rollback the last database migration

创建迁移

类似于 Laravel，您可以使用 Artisan 的 make 命令创建新的迁移。

php artisan neo4j:migrate:make create_user_label

标签迁移将放在 app/database/labels 中。

您可以为命令添加额外的选项，例如：

php artisan neo4j:migrate:make foo --path=app/labels
php artisan neo4j:migrate:make create_user_label --create=User
php artisan neo4j:migrate:make create_user_label --label=User

运行迁移

运行所有未运行的迁移

php artisan neo4j:migrate

运行特定路径的所有未运行的迁移

php artisan neo4j:migrate --path=app/foo/labels

运行特定包的所有未运行的迁移

php artisan neo4j:migrate --package=vendor/package

注意：如果在运行迁移时收到“找不到类”的错误，请尝试运行 composer dump-autoload 命令。

在生产中强制运行迁移

要强制在生产数据库上运行迁移，可以使用以下命令：

php artisan neo4j:migrate --force

回滚迁移

回滚最后一个迁移操作

php artisan neo4j:migrate:rollback

回滚所有迁移

php artisan neo4j:migrate:reset

回滚所有迁移并重新运行它们

php artisan neo4j:migrate:refresh

php artisan neo4j:migrate:refresh --seed

模式

NeoEloquent 会自动为您别名化 Neo4jSchema 门面，以便在操作标签时使用。

Neo4jSchema::label('User', function(Blueprint $label)
{
    $label->unique('uuid');
});

如果您决定手动编写迁移类（不使用生成器），请确保有这些 use 语句：

use Vinelab\NeoEloquent\Schema\Blueprint;
use Vinelab\NeoEloquent\Migrations\Migration;

目前 Neo4j 支持 UNIQUE 约束和 INDEX 属性。您可以在以下位置了解更多信息：

http://docs.neo4j.org/chunked/stable/graphdb-neo4j-schema.html

模式方法

删除标签

Neo4jSchema::drop('User');
Neo4jSchema::dropIfExists('User');

重命名标签

Neo4jSchema::renameLabel($from, $to);

检查标签是否存在

if (Neo4jSchema::hasLabel('User')) {

} else {

}

检查关系是否存在

if (Neo4jSchema::hasRelation('FRIEND_OF')) {

} else {

}

您可以在以下位置了解有关迁移和模式的信息：

https://laravel.net.cn/docs/schema

https://laravel.net.cn/docs/migrations

聚合

除了 Eloquent 构建器聚合之外，NeoEloquent 还支持 Neo4j 特定聚合，如 percentile 和 standard deviation，以方便起见，保留相同的函数名。有关更多信息，请参阅文档。

table() 表示模型的标签

$users = DB::table('User')->count();

$distinct = DB::table('User')->countDistinct('points');

$price = DB::table('Order')->max('price');

$price = DB::table('Order')->min('price');

$price = DB::table('Order')->avg('price');

$total = DB::table('User')->sum('votes');

$disc = DB::table('User')->percentileDisc('votes', 0.2);

$cont = DB::table('User')->percentileCont('votes', 0.8);

$deviation = DB::table('User')->stdev('sex');

$population = DB::table('User')->stdevp('sex');

$emails = DB::table('User')->collect('email');

变更日志

请查看发行版获取详细信息。

避免

以下是一些约束和图特定注意事项，这是一个功能列表，这些功能可能不受支持或不推荐使用。

JOIN 😖

它们对图没有意义，并且图讨厌它们！这使得它们故意不受支持。如果您从基于 SQL 的应用程序迁移，它们将是您的噩梦。

多对多关系中的交叉表

这不支持，相反，我们将使用边来处理模型之间的关系。

嵌套数组和对象

由于单个对象映射类型存储的限制，您不能在单个模型中具有嵌套的数组或对象，请确保它是扁平的。示例：

// Don't
User::create(['name' => 'Some Name', 'location' => ['lat' => 123, 'lng'=> -123 ] ]);

请查看 createWith() 方法了解如何以图的方式实现此操作。

测试

安装Neo4j实例并使用默认配置localhost:7474运行它
确保数据库图是空的，以避免冲突
运行composer install后，应该有/vendor/bin/phpunit
在确认Neo4j实例正在运行后，运行./vendor/bin/phpunit

标记为不完整的测试表示它们是已知问题或不受支持的特性，请检查包含的消息以获取更多信息。

ideepblue / neoeloquent

维护者

详细信息

README

NeoEloquent

聊天 & 支持

快速参考

安装

Laravel 8

8.0

Laravel 7

7.0

Laravel 6

6.0

配置

连接

迁移设置

文档

模型

命名空间模型

自定义节点标签

软删除

Laravel 5

关系

一对一

保存

定义此关系的逆关系

关联模型

一对多

定义此关系的逆关系

多对多

动态属性

多态

检索多态关系

动态加载多态模型

急切加载多态模型

检索多态关系的逆关系

多态关系简述

急切加载

边

简介

EdgeIn

EdgeOut

HyperEdge

处理边

边属性

从关系检索边

仅限 Neo

使用CreateWith

创建新记录和关系

将现有记录作为关系附加

迁移

命令

创建迁移

运行迁移

运行所有未运行的迁移

运行特定路径的所有未运行的迁移

运行特定包的所有未运行的迁移

在生产中强制运行迁移

回滚迁移

回滚最后一个迁移操作

回滚所有迁移

回滚所有迁移并重新运行它们

模式

模式方法

删除标签

重命名标签

检查标签是否存在

检查关系是否存在

聚合

变更日志

避免

JOIN 😖

多对多关系中的交叉表

嵌套数组和对象

测试