jason-guru/neo-eloquent

Laravel对Neo4j图形数据库REST接口的包装


README

SensioLabsInsight

Build Status

NeoEloquent

Neo4j图形Eloquent驱动程序,用于Laravel

聊天 & 支持

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

快速参考

安装

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

Laravel 5

5.7

5.6

{
    "require": {
        "vinelab/neoeloquent": "^1.4.6"
    }
}

5.5

{
    "require": {
        "vinelab/neoeloquent": "^1.4.5"
    }
}

5.4

{
    "require": {
        "vinelab/neoeloquent": "1.4.3"
    }
}

5.3

{
    "require": {
        "vinelab/neoeloquent": "1.4.2"
    }
}

5.2

{
    "require": {
        "vinelab/neoeloquent": "1.3.*"
    }
}

5.1

{
    "require": {
        "vinelab/neoeloquent": "1.2.*"
    }
}

5.0

{
    "require": {
        "vinelab/neoeloquent": "1.2.5"
    }
}

Laravel 4

{
    "require": {
        "vinelab/neoeloquent": "1.1.*"
    }
}

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)
    ]
]

Lumen

对于Lumen,您需要在应用程序根目录中创建一个名为config的新文件夹,并在其中添加一个名为database.php的文件。在那里,您将添加以下代码。

<?php

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

并在bootstrap/app.php中添加以下行

$app->configure('database');

这是为了使Lumen能够读取除提供的默认配置以外的其他配置。

在添加服务提供者的情况下,您必须在bootstrap/app.php的注册提供者部分中添加它。您可以这样添加

$app->register('Vinelab\NeoEloquent\NeoEloquentServiceProvider');

迁移设置

如果您愿意有迁移

  • 创建文件夹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'];

}

Laravel 4

要启用软删除,您需要将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关系方向。

关联模型

由于我们不处理外键,在这种情况下,我们不仅要设置父模型的父键属性。在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);

类似于一对一关系,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模型

HyperEdges

同样,在代码中,这将通过三个模型UserCommentPost表示,其中ID为1的User发布了一个Post,ID为6的User对那个Post上的Comment进行了评论,如下所示

class User extends NeoEloquent {

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

}

为了保持简单但仍然涉及三个模型,我们必须传递任何commentable模型,在我们的例子中,它可以是VideoPost模型。

注意:请确保将其默认设置为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();

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

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

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

class Location extends NeoEloquent {

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

}

要将 UserLocation 关联

$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

HyperEdge 的情况下,您可以如下访问所有三个模型

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

边属性

默认情况下,边将具有自动设置和更新的时间戳 created_atupdated_at,但只有当在父模型上设置 $timestampstrue 时才会启用时间戳。

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

在这里,您可以找到 NeoEloquent 特定的方法和实现,与 Eloquent 精美的方法结合,可以让处理图和 Neo4j 变得非常愉快!

创建与

此方法“在一定程度上”填补了关系数据库和文档数据库之间的差距,它允许在一次数据库请求中创建多个相关模型。

创建新记录和关系

以下是一个创建带有附加照片和视频的帖子的示例

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' => '...'
    ]
]);

photosvideos 必须与 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: '...'});

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

CreateWith

您还可以将模型和属性作为关系值混合,但这不是必需的,因为 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 特定聚合,如 percentilestandard 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');

更新日志

请查看 发布 以获取详细信息。

避免

以下是一些约束和图特定问题,以及不支持或不建议的功能列表。

连接 😖

  • 对于图来说,这没有意义,而且图讨厌它们!这使它们故意不支持。如果您从基于 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

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