README

⚠️ 此包已被弃用且不再维护。未建议替代包。 ⚠️

Rinvex Repository 是一个简单、直观且智能的 Active Repository 实现，具有极其灵活和细粒度的缓存系统，用于 Laravel，用于抽象数据层，使应用程序更易于维护。

💡 如果您需要 Laravel 5.5 支持，请使用 dev-develop 分支。它很稳定，但尚未标记，因为测试套件尚未完成。 💡

功能

缓存，缓存，缓存！
防止代码重复。
减少潜在的编程错误。
以灵活的方式细粒度缓存查询。
应用集中管理的、一致的访问规则和逻辑。
实现并集中管理领域模型的缓存策略。
通过将客户端对象从领域模型中分离出来，提高代码的可维护性和可读性。
通过自动化和隔离客户端对象以及领域模型来支持单元测试，最大化可测试的代码量。
将行为与相关数据关联起来。例如，计算字段或强制执行实体内部数据元素之间的复杂关系或业务规则。

快速示例（TL;DR）

Rinvex\Repository\Repositories\BaseRepository 是一个抽象类，具体的实现必须扩展它。

Rinvex\Repository\Repositories\EloquentRepository 是目前唯一的可用仓库实现（未来还将有更多，您也可以开发自己的实现），它使得创建新的 eloquent 模型实例以及轻松操作它们变得容易。要使用 EloquentRepository，您的仓库必须首先扩展它

namespace App\Repositories;

use Rinvex\Repository\Repositories\EloquentRepository;

class FooRepository extends EloquentRepository
{
    protected $repositoryId = 'rinvex.repository.uniqueid';

    protected $model = 'App\Models\User';
}

就是这样，您完成了！是的，就这么简单。

但如果您想更多地控制容器实例，或者想要动态地传递模型名称，您可以选择以下方式

namespace App\Repositories;

use Illuminate\Contracts\Container\Container;
use Rinvex\Repository\Repositories\EloquentRepository;

class FooRepository extends EloquentRepository
{
    // Instantiate repository object with required data
    public function __construct(Container $container)
    {
        $this->setContainer($container)
             ->setModel(\App\Models\User::class)
             ->setRepositoryId('rinvex.repository.uniqueid');

    }
}

现在，在您的控制器中，您可以通过 $repository = new \App\Repositories\FooRepository(); 传统地实例化仓库，或者使用 Laravel 的出色依赖注入和 IoC 来实现魔法

namespace App\Http\Controllers;

use App\Repositories\FooRepository;

class BarController
{
    // Inject `FooRepository` from the IoC
    public function baz(FooRepository $repository)
    {
        // Find entity by primary key
        $repository->find(1);

        // Find all entities
        $repository->findAll();

        // Create a new entity
        $repository->create(['name' => 'Example']);
    }
}

Rinvex Repository 工作流程 - 创建仓库

Rinvex 仓库工作流程 - 在控制器中使用

UML 图

任务完成！你现在可以使用这个包了！✅

除非你需要深入了解并了解一些高级内容，否则你可以跳过以下步骤！😉

安装

安装此包的最佳和最简单方法是通过 Composer。

兼容性

此包完全兼容 Laravel 5.1.*，5.2.* 和 5.3.*。

虽然此包倾向于无框架，但它在一定程度上采用了 Laravel 的文化和最佳实践。它主要与 Laravel 进行了测试，但您仍然可以使用它与其他框架或甚至没有任何框架。

所需包

打开您的应用程序的 composer.json 文件，并在 require 数组中添加以下行

"rinvex/laravel-repositories": "3.0.*"

注意： 确保在完成所需更改后，通过运行 composer validate 确保 composer.json 文件有效。

安装依赖

在终端运行 composer install 或 composer update 命令，根据您的应用程序状态安装新要求。

注意： 请参阅 Composer 的基本用法文档以获取更多详细信息。

集成

Rinvex 仓库 包是框架无关的，因此可以轻松地原生或与您喜欢的框架集成。

原生集成

在框架之外集成此包非常简单，只需要求自动加载包的 vendor/autoload.php 文件。

注意：有关更多详细信息，请查阅 Composer 的自动加载文档。

在您的终端上运行以下命令以发布配置文件

php artisan vendor:publish --tag="rinvex-repository-config"

注意：有关更多详细信息，请查阅 Laravel 的配置文档。

您已准备好。集成已完成，现在您可以使用所有可用方法，有关示例，请参阅使用部分。

配置

如果您遵循了之前的集成步骤，则您发布的配置文件位于 config/rinvex.repository.php。

配置选项非常易于表达和自我解释，如下所示

return [

    /*
    |--------------------------------------------------------------------------
    | Models Directory
    |--------------------------------------------------------------------------
    |
    | Here you may specify the default models directory, just write
    | directory name, like 'Models' not the full path.
    |
    | Default: 'Models'
    |
    */

    'models' => 'Models',

    /*
    |--------------------------------------------------------------------------
    | Caching Strategy
    |--------------------------------------------------------------------------
    */

    'cache' => [

        /*
        |--------------------------------------------------------------------------
        | Cache Keys File
        |--------------------------------------------------------------------------
        |
        | Here you may specify the cache keys file that is used only with cache
        | drivers that does not support cache tags. It is mandatory to keep
        | track of cache keys for later usage on cache flush process.
        |
        | Default: storage_path('framework/cache/rinvex.repository.json')
        |
        */

        'keys_file' => storage_path('framework/cache/rinvex.repository.json'),

        /*
        |--------------------------------------------------------------------------
        | Cache Lifetime
        |--------------------------------------------------------------------------
        |
        | Here you may specify the number of seconds that you wish the cache
        | to be remembered before it expires. If you want the cache to be
        | remembered forever, set this option to -1. 0 means disabled.
        |
        | Default: -1
        |
        */

        'lifetime' => -1,

        /*
        |--------------------------------------------------------------------------
        | Cache Clear
        |--------------------------------------------------------------------------
        |
        | Specify which actions would you like to clear cache upon success.
        | All repository cached data will be cleared accordingly.
        |
        | Default: ['create', 'update', 'delete']
        |
        */

        'clear_on' => [
            'create',
            'update',
            'delete',
        ],

        /*
        |--------------------------------------------------------------------------
        | Cache Skipping URI
        |--------------------------------------------------------------------------
        |
        | For testing purposes, or maybe some certain situations, you may wish
        | to skip caching layer and get fresh data result set just for the
        | current request. This option allows you to specify custom
        | URL parameter for skipping caching layer easily.
        |
        | Default: 'skipCache'
        |
        */

        'skip_uri' => 'skipCache',

    ],

];

使用

详细文档

`setContainer()`, `getContainer()`

setContainer 方法设置 IoC 容器实例，而 getContainer 返回它

// Set the IoC container instance
$repository->setContainer(new \Illuminate\Container\Container());

// Get the IoC container instance
$container = $repository->getContainer();

`setConnection()`, `getConnection()`

setConnection 方法设置与仓库关联的连接，而 getConnection 返回它

// Set the connection associated with the repository
$repository->setConnection('mysql');

// Get the current connection for the repository
$connection = $repository->getConnection();

注意：传递给 setConnection 方法的名称应与您的 config/database.php 配置文件中列出的连接之一相匹配。

`setModel()`, `getModel()`

setModel 方法设置仓库模型，而 getModel 返回它

// Set the repository model
$repository->setModel(\App\Models\User::class);

// Get the repository model
$repositoryModel = $repository->getModel();

`setRepositoryId()`, `getRepositoryId()`

setRepositoryId 方法设置仓库标识符，而 getRepositoryId 返回它（它可以是您想要的任何内容，但必须是每个仓库的唯一）

// Set the repository identifier
$repository->setRepositoryId('rinvex.repository.uniqueid');

// Get the repository identifier
$repositoryId = $repository->getRepositoryId();

`setCacheLifetime()`, `getCacheLifetime()`

setCacheLifetime 方法设置仓库缓存有效期，而 getCacheLifetime 返回它

// Set the repository cache lifetime
$repository->setCacheLifetime(123);

// Get the repository cache lifetime
$cacheLifetime = $repository->getCacheLifetime();

`setCacheDriver()`, `getCacheDriver()`

setCacheDriver 方法设置仓库缓存驱动程序，而 getCacheDriver 返回它

// Set the repository cache driver
$repository->setCacheDriver('redis');

// Get the repository cache driver
$cacheDriver = $repository->getCacheDriver();

`enableCacheClear()`, `isCacheClearEnabled()`

enableCacheClear 方法启用仓库缓存清除，而 isCacheClearEnabled 确定其状态

// Enable repository cache clear
$repository->enableCacheClear(true);

// Disable repository cache clear
$repository->enableCacheClear(false);

// Determine if repository cache clear is enabled
$cacheClearStatus = $repository->isCacheClearEnabled();

`createModel()`

createModel() 方法创建一个新的仓库模型实例

$repositoryModelInstance = $repository->createModel();

`forgetCache()`

forgetCache() 方法用于清除仓库缓存

$repository->forgetCache();

`with()`

with 方法设置需要预加载的关系

// Pass a string
$repository->with('relationship');

// Or an array
$repository->with(['relationship1', 'relationship2']);

`where()`

where 方法向查询中添加基本 where 子句

$repository->where('slug', '=', 'example');

`whereIn()`

whereIn 方法向查询中添加 "where in" 子句

$repository->whereIn('id', [1, 2, 5, 8]);

`whereNotIn()`

whereNotIn 方法向查询中添加 "where not in" 子句

$repository->whereNotIn('id', [1, 2, 5, 8]);

`whereHas()`

whereHas 方法向查询中添加 "where has relationship" 子句

use Illuminate\Database\Eloquent\Builder;

$repository->whereHas('attachments', function (Builder $builder) use ($attachment) {
    $builder->where('attachment_id', $attachment->id);
});

注意： 所有 where* 方法都是可链式的，可以在单个请求中多次调用。它们会在内部保留一个数组以存储所有 where 子句，并在执行查询之前应用它们。

`offset()`

offset 方法设置查询的 "偏移" 值

$repository->offset(5);

`limit()`

limit 方法设置查询的 "限制" 值

$repository->limit(9);

`orderBy()`

orderBy 方法向查询中添加 "order by" 子句

$repository->orderBy('id', 'asc');

`find()`

find 方法通过主键查找实体

$entity = $repository->find(1);

`findOrFail()`

findOrFail() 方法通过主键查找实体，如果未找到则抛出异常

$entity = $repository->findOrFail(1);

`findOrNew()`

findOrNew() 方法通过主键查找实体，如果未找到则返回新的实体实例

$entity = $repository->findOrNew(1);

`findBy()`

findBy 方法通过实体的一个属性查找实体

$entity = $repository->findBy('id', 1);

`findFirst()`

findFirst 方法查找第一个实体

$firstEntity = $repository->findFirst();

`findAll()`

findAll 方法查找所有实体

$allEntities = $repository->findAll();

`paginate()`

paginate 方法对所有实体进行分页

$entitiesPagination = $repository->paginate(15, ['*'], 'page', 2);

如你所猜，这个查询是第一页的前15条记录。

`simplePaginate()`

simplePaginate 方法将所有实体分页到一个简单的分页器中

$entitiesSimplePagination = $repository->simplePaginate(15);

`findWhere()`

findWhere 方法查找所有匹配 where 条件的实体

// Matching values with equal '=' operator
$repository->findWhere(['slug', '=', 'example']);

`findWhereIn()`

findWhereIn 方法查找所有匹配 whereIn 条件的实体

$includedEntities = $repository->findwhereIn(['id', [1, 2, 5, 8]]);

`findWhereNotIn()`

findWhereNotIn 方法用于查找所有符合 whereNotIn 条件的数据实体

$excludedEntities = $repository->findWhereNotIn(['id', [1, 2, 5, 8]]);

`findWhereHas()`

findWhereHas 方法用于查找所有符合 whereHas 条件的数据实体

use Illuminate\Database\Eloquent\Builder;

$entities = $repository->findWhereHas(['attachments', function (Builder $builder) use ($attachment) {
    $builder->where('attachment_id', $attachment->id);
}]);

注意

findWhereHas 方法将返回一个匹配闭包内条件的实体集合。如果您需要嵌入 attachments 关联，在这种情况下，您需要在调用 findWhereHas() 之前调用 with() 方法，如下所示： $repository->with('attachments')->findWhereHas([...]);

从 v2.0.0 版本开始，所有 findWhere、findWhereIn 和 findWhereNotIn 方法的签名都已更改。

所有 findWhere、findWhereIn 和 findWhereNotIn 方法分别利用 where、whereIn 和 whereNotIn 方法，因此第一个参数是所需参数的数组。

所有 find* 方法都可以通过前面的 where 子句进行过滤，而且可以通过这种方式进行链式操作。所有的 where 子句都会在执行查询之前存储在一个数组中并应用。请查看以下示例

findAll 方法的过滤示例

$allFilteredEntities = $repository->where('slug', '=', 'example')->findAll();

findFirst 方法的另一个过滤示例，带有链式子句

$allFilteredEntities = $repository->where('name', 'LIKE', '%TEST%')->where('slug', '=', 'example')->findFirst();

`create()`

create 方法使用给定的属性创建一个新的实体

$createdEntity = $repository->create(['name' => 'Example']);

`update()`

update 方法使用给定的属性更新一个实体

$updatedEntity = $repository->update(1, ['name' => 'Example2']);

`store()`

store 方法使用给定的属性存储一个实体

// Existing Entity
$storedEntity = $repository->store(1, ['name' => 'Example2']);

// New Entity
$storedEntity = $repository->store(null, ['name' => 'Example2']);

注意： 此方法只是 create 和 update 方法的别名。在单表用于创建和更新过程时非常有用。

`delete()`

delete 方法使用给定的 id 删除一个实体

$deletedEntity = $repository->delete(1);

`beginTransaction()`

beginTransaction 方法开始一个数据库事务

$repository->beginTransaction();

`commit()`

commit 方法提交一个数据库事务

$repository->commit();

`rollBack()`

rollBack 方法回滚一个数据库事务

$repository->rollBack();

注意

所有 find* 方法都接受一个可选的参数，用于选择属性。

所有 set* 方法返回当前仓库的实例，因此可以进行链式操作。

create、update 和 delete 方法始终返回一个包含两个值的数组，第一个是操作状态（成功或失败）作为一个布尔值，第二个是刚刚操作的模型实例。

建议通过仓库构造函数显式设置 IoC 容器实例、仓库模型和仓库标识符，如上述示例所示，但此包足够智能，可以猜测任何缺失的要求。请参阅自动猜测部分。

将代码转换为接口

作为最佳实践，建议为接口进行编码，特别是对于可扩展的项目。以下示例将解释如何实现。

首先，为每个实体创建一个接口（抽象）。

use Rinvex\Repository\Contracts\CacheableContract;
use Rinvex\Repository\Contracts\RepositoryContract;

interface UserRepositoryContract extends RepositoryContract, CacheableContract
{
    //
}

其次，为每个实体创建一个仓储（具体实现）。

use Rinvex\Repository\Repositories\EloquentRepository;

class UserEloquentRepository extends EloquentRepository implements UserRepositoryContract
{
    //
}

现在在 Laravel 服务提供者中，将两者绑定到 IoC 容器中（在 register 方法内部）。

$this->app->bind(UserRepositoryContract::class, UserEloquentRepository::class)

这样我们就不必手动实例化仓储，并且可以轻松地在多个实现之间切换。IoC 容器将负责所需的依赖项。

注意：请参阅 Laravel 的服务提供者和服务容器文档以获取更多详细信息。

添加自定义实现

由于我们专注于抽象数据层，并且将抽象接口与具体实现分离，因此添加自己的实现很容易。

例如，如果你的领域模型使用 Web 服务或文件系统数据存储作为其数据源，你只需要扩展 BaseRepository 类即可。查看

class FilesystemRepository extends BaseRepository
{
    // Implement here all `RepositoryContract` methods that query/persist data to & from filesystem or whatever datastore
}

EloquentRepository 触发的事件

仓储在每次操作时都会触发事件，例如 create、update、delete。所有触发的事件都以前缀 repository 的标识符（你在之前的仓储构造函数中设置的）为前缀，如下所示

rinvex.repository.uniqueid.entity.created
rinvex.repository.uniqueid.entity.updated
rinvex.repository.uniqueid.entity.deleted

为了方便起见，以 .entity.created、.entity.updated 或 .entity.deleted 结尾的事件具有相应的监听器。通常，我们需要在每个成功操作后清除缓存（如果启用且存在）。

还有一个事件 rinvex.repository.uniqueid.entity.cache.flushed，它在缓存清除时触发。默认情况下，它没有监听器，但如果你有模型关系并需要进行其他操作，你可能需要监听它。

强制性的仓储约定

以下是使用此包时需要了解的一些约定。此包遵循最佳实践，试图让网络工匠的开发更加容易，因此它有一些约定来实现标准化和互操作性。

所有触发的事件都有一个唯一的后缀，例如 .entity.created。注意 .entity.，这是自动事件监听器订阅的强制要求。
任何使用 Rinvex Repository 的包的默认目录结构如下

├── config                  --> config files
|
├── database
|   ├── factories           --> database factory files
|   ├── migrations          --> database migration files
|   └── seeds               --> database seed files
|
├── resources
|   └── lang
|       └── en              --> English language files
|
├── routes                  --> Routes files
|   ├── api.php
|   ├── console.php
|   └── web.php
|
├── src                     --> self explanatory directories
|   ├── Console
|   |   └── Commands
|   |
|   ├── Http
|   |   ├── Controllers
|   |   ├── Middleware
|   |   └── Requests
|   |
|   ├── Events
|   ├── Exceptions
|   ├── Facades
|   ├── Jobs
|   ├── Listeners
|   ├── Models
|   ├── Overrides
|   ├── Policies
|   ├── Providers
|   ├── Repositories
|   ├── Scopes
|   ├── Support
|   └── Traits
|
└── composer.json           --> composer dependencies file

注意： Rinvex Repository 遵循 PSR-4: Autoloader 并期望使用它的其他包也遵循相同的标准。这是自动猜测所必需的，例如，当仓储模型缺失时，它将被自动猜测并相应地解决，尽管可能不需要完整的目录结构，但它仍然是所有 Rinvex 包的标准。

自动猜测

虽然强烈建议显式设置 IoC 容器、仓储标识符和仓储模型；但此包足够智能，可以在缺少这些所需数据时猜测任何数据。

IoC 容器 app() 助手用作回退，如果未显式提供 IoC 容器实例。
存储库标识符建议将存储库标识符设置为点分隔的名称，例如 rinvex.repository.uniqueid，但如果缺失，将使用完全限定的存储库类名称（实际上是 static::class 的值）。
存储库模型通常，存储库按照如下方式命名空间 Rinvex\Demos\Repositories\ItemRepository，因此相应的模型应按如下方式命名空间 Rinvex\Demos\Models\Item。这就是此包根据默认目录结构猜测模型的方式，如果模型缺失。

灵活且细粒度缓存

Rinvex 存储库具有强大、简单且细粒度的缓存系统，可以处理几乎所有边缘情况。虽然您可以整体启用/禁用应用程序的缓存，但您有灵活性，可以逐个查询启用/禁用缓存！这使您能够排除某些查询被缓存，即使该方法默认或以其他方式被缓存。

让我们看看我们可以控制哪些缓存级别

整个应用程序缓存

有关更多详细信息，请参阅 Laravel 的缓存文档。

单个查询缓存

更改每个查询的缓存或禁用它

// Set cache lifetime for this individual query to 123 seconds
$repository->setCacheLifetime(123);

// Set cache lifetime for this individual query to forever
$repository->setCacheLifetime(-1);

// Disable cache for this individual query
$repository->setCacheLifetime(0);

更改每个查询的缓存驱动程序

// Set cache driver for this individual query to redis
$repository->setCacheDriver('redis');

两个 setCacheLifetime 和 setCacheDriver 方法都是可链式的

// Change cache lifetime & driver on runtime
$repository->setCacheLifetime(123)->setCacheDriver('redis')->findAll();

// Use default cache lifetime & driver
$repository->findAll();

除非明确禁用，否则默认对所有存储库启用缓存，并保留为您的 rinvex.repository.cache.lifetime 配置值指定的时间，使用默认应用程序的缓存驱动程序 cache.default（这也可以按查询更改）。

是否缓存结果完全由您决定，虽然所有检索 find* 方法默认启用缓存，但您可以为单个查询启用/禁用缓存，或根据需要控制缓存的方式、缓存时间以及使用哪个驱动程序。

暂时跳过单个 HTTP 请求缓存

最后，您可以通过在 URL 中传递以下查询字符串来跳过单个请求的缓存 skipCache=true。您可以通过 rinvex.repository.cache.skip_uri 配置选项修改此参数的名称。

最终思考

由于这是一个不断发展的实现，其变化可能取决于实际用例。
存储库智能地将缺失的调用方法传递给底层模型，因此您实际上可以通过利用存储库模型来实现任何类型的逻辑，甚至是复杂查询。
有关 Active Repository 实现的更多信息，我已发布了一篇题为 Active Repository is good & Awesomely Usable 的文章，如果您感兴趣，请阅读。
存储库以非常智能的方式使用缓存标签，即使您选择的缓存驱动程序不支持它。存储库将自行管理它以实现精确的缓存管理。在幕后，它使用 JSON 文件来存储缓存键。请检查 rinvex.repository.cache.keys_file 配置选项以更改文件路径。
Rinvex仓库遵循与PSR-1: 基本编码标准、PSR-2: 编码风格指南和PSR-4: 自动加载器兼容的FIG PHP标准建议，以确保共享PHP代码之间的高互操作性。
目前我认为通过实现条件模式来增加一个更复杂的层以进行过滤并无明显优势，我更愿意保持它现在这样简单，使用传统的where子句，因为我们可以达到相同的结果。（你有不同的看法吗？请解释一下。）

变更日志

有关项目的完整历史，请参阅变更日志。

支持

以下支持渠道随时可供您使用：

贡献 & 协议

感谢您考虑为这个项目做出贡献！贡献指南可以在CONTRIBUTING.md中找到。

欢迎提出错误报告、功能请求和拉取请求。

安全漏洞

如果您在此项目中发现安全漏洞，请发送电子邮件至help@rinvex.com。所有安全漏洞都将得到及时处理。

关于Rinvex

Rinvex是一家成立于2016年6月的开罗，埃及的软件解决方案初创公司，专注于为中小企业提供集成企业解决方案。我们相信，我们的动力——价值、触达和影响力——是我们与众不同的地方，通过软件的力量释放我们哲学的无穷可能性。我们喜欢称之为“生活节奏的创新”。这就是我们如何为推进人类文明尽我们的一份力量。

许可协议

此软件根据MIT许可协议（MIT）发布。

rinvex / laravel-repositories

维护者

详情

README

功能

快速示例（TL;DR）

目录

安装

兼容性

所需包

安装依赖

集成

原生集成

配置

使用

详细文档

setContainer(), getContainer()

setConnection(), getConnection()

setModel(), getModel()

setRepositoryId(), getRepositoryId()

setCacheLifetime(), getCacheLifetime()

setCacheDriver(), getCacheDriver()

enableCacheClear(), isCacheClearEnabled()

createModel()

forgetCache()

with()

where()

whereIn()

whereNotIn()

whereHas()

offset()

limit()

orderBy()

find()

findOrFail()

findOrNew()

findBy()

findFirst()

findAll()

paginate()

simplePaginate()

findWhere()

findWhereIn()

findWhereNotIn()

findWhereHas()

create()

update()

store()

delete()

beginTransaction()

commit()

rollBack()