README

Neo4j 图形 Eloquent 驱动器，适用于 Laravel 11+。这是从https://github.com/Vinelab/NeoEloquent分叉而来，包含适用于 Laravel 11+ 和 PHP 8.2+ 所需的所有修复。

快速参考

安装
配置
模型
关系
边
迁移
模式
聚合
仅限于Neo
要避免的事情

安装

运行 composer require global-innovation/neo4j-laravel-eloquent

或者将包添加到你的 composer.json 并运行 composer update。

{
    "require": {
        "global-innovation/neo4j-laravel-eloquent": "~2.3.0"
    }
}

在 bootstrap/providers.php 中添加服务提供者

Vinelab\NeoEloquent\NeoEloquentServiceProvider::class,

服务提供者将注册此包所需的所有类，并将 Model 类别名设置为 NeoEloquent，因此你可以在模型中简单地 extend NeoEloquent。

配置

连接

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

'default' => 'neo4j',

添加连接默认值

'connections' => [
    'neo4j' => [
        'driver' => 'neo4j',
        'host'   => 'localhost',
        'port'   => 7687,
        'username' => 'username',
        'password' => 'password',
    ]
]

如果你在使用ENV变量，请记住更新你的ENV变量（.env）。

迁移设置

如果你愿意使用迁移

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

文档

use NeoEloquent;

class User extends NeoEloquent {}

正如其名，NeoEloquent将从类名生成默认节点标签，在这种情况下将是 :User。有关节点标签的更多信息，请参阅节点标签

命名空间模型

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

namespace App\Models;

use NeoEloquent;

class Admin extends NeoEloquent { }

从该关系生成的标签将是 VinelabCmsAdmin，这是为了确保在引入另一个 Admin 实例（如 Vinelab\Blog\Admin）时标签不会冲突，否则数据库中的 :Admin 将导致混乱。

自定义节点标签

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

use NeoEloquent;

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，则将使用它。

use NeoEloquent;

class User extends NeoEloquent {

    protected $table = 'User';

}

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

软删除

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

use Vinelab\NeoEloquent\Eloquent\SoftDeletingTrait;

class User extends NeoEloquent {

    use SoftDeletingTrait;

    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;

多态

多态关系的概念与骨本身纯粹相关，但当涉及到图时，我们将其表示为超边。

超边涉及三个模型，即parent模型，hyper模型和related模型，如图所示

在代码中，这将以三个模型User Comment和Post的形式表示，其中id为1的User发布了一个Post，而id为6的User评论了该Post，如下所示

class User extends NeoEloquent {

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

}

为了保持简单，同时仍然涉及三个模型，我们不得不传递任何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的更多信息，请在此处阅读HyperEdges。

或者你可以保存一个Comment实例

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

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

此外，所有在BelongsToMany关系中发现的功能都得到了支持，比如通过Ids附加模型

$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();

您也可以指定要返回的形态类型

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
处理边
边属性

介绍

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

边让您能够像处理模型一样操作关系属性。

$edge = $location->associate($user);
$edge->last_visited = 'today';
$edge->save(); // true

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()方法访问。

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

$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

在超边的情况下，您可以通过以下方式访问所有三个模型

$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;

从关系检索边

与创建关联的方式一样，我们可以通过在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:make:migration create_user_label

标签迁移将被放置在 app/database/labels

您可以在命令中添加额外的选项，例如

php artisan neo4j:make:migration foo --path=app/labels
php artisan neo4j:make:migration create_user_label --create=User
php artisan neo4j:make:migration 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

标记为不完整的测试意味着它们要么是已知问题，要么是不支持的功能，请检查包含的消息以获取更多信息。

工厂类

您也可以使用默认的 Laravel factory() 辅助器为 NeoEloquent 模型。

在 database/factories/ 中定义所需的工厂类（了解更多）[https://laravel.net.cn/docs/5.6/database-testing#writing-factories];
使用 factory() 的方式与默认的 Laravel factory() 相同。

global-innovation / neo4j-laravel-eloquent

维护者

详细信息

README

快速参考

安装

配置

连接

迁移设置

文档

模型

命名空间模型

自定义节点标签

软删除

关系

一对一

保存

定义此关系的反向

关联模型

一对多

定义此关系的反向

多对多

动态属性

多态

检索多态关系

动态加载多态模型

贪婪加载多态模型

检索多态关系的逆关系

多态关系简述

贪婪加载

边

介绍

EdgeIn

EdgeOut

HyperEdge

处理边

边属性

从关系检索边

仅限于Neo

使用CreateWith

创建新记录和关系

将现有记录作为关系附加

迁移

命令

创建迁移

运行迁移

运行所有未处理的迁移

运行路径的所有未处理的迁移

运行包的所有未处理的迁移

在生产中强制运行迁移

回滚迁移

回滚最后一个迁移操作

回滚所有迁移

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

模式

模式方法

删除标签

重命名标签

检查标签的存在性

检查关系的存在性

聚合

变更日志

避免

JOIN 😖

多对多关系中的交叉表

嵌套数组和对象

测试

工厂类