README

此包为 Laravel 提供了一个数据库驱动程序，使您可以使用 Netflex API 作为 Laravel 应用程序的后端数据库。

此包支持 Laravel 8 至 10，以及 PHP 7.4 至 8.2。

动机/为什么？

Laravel 提供了一个强大的数据库抽象层，允许您使用各种不同的数据库后端。

在 Laravel 生态系统中的大多数第一方和第三方包都假设您正在使用关系型数据库后端。

此包允许您将 Netflex API 用作 Laravel 应用程序的后端数据库，弥合了 Netflex API 和 Laravel 之间的差距。

这使您能够使用 Laravel 的大部分功能，同时仍然使用 Netflex API 作为后端。

安装

您可以通过 composer 安装此包

composer require netflex/database

使用方法

配置

将以下内容添加到您的 config/database.php 文件中

return [
    'connections' => [

        'netflex' => [
            'driver' => 'netflex',
            'adapter' => 'entry',
        ]
    ]
];

请注意，如果想要执行“写入”操作，则必须指定 adapter 属性，并设置为有效的适配器名称。以下适配器目前受支持

entry（完全支持）
customer（写入支持，由于 API 限制，不支持模式操作）
page（只读支持）
read-only（也用作 default 的别名，用于回退目的）

如果未指定适配器，连接将只能作为只读连接工作，并且您将无法查询您的连接模式或执行任何写入操作。

请注意，使用 entry 适配器时，您的模型 $prefix 属性将被 entry_ 预先添加，以匹配 Netflex 索引命名约定。

您还可以提供自定义适配器类。它需要实现 Netflex\Database\DBAL\Contracts\DatabaseAdapter 接口。

适配器负责在 Laravel 的数据库层和 Netflex API 之间进行转换。

高级配置

使用不同的 API 连接

如果您配置了多个 API 连接，可以通过在连接配置中设置 connection 属性来指定要使用哪个连接。（参考 netflex/api）

[
    'driver' => 'netflex',
    'adapter' => 'entry',
    'connection' => 'my-connection' // Refers to a Netflex API connection
]

Eloquent

参考模型

此包提供了一个参考模型，您可以用作模型的基础。对于大多数用例，这被推荐，因为它提供了许多有用的功能。

namespace App\Models;

use Netflex\Database\Eloquent\Model;

class Article extends Model
{
    //
}

模型

要使用 Netflex API 作为 Eloquent 模型的数据库后端，您只需注册一个使用 netflex 驱动程序的数据库连接即可。

如果您已为 Netflex 结构配置了别名，则可以跳过 $table 属性，让 Eloquent 根据模型的别名为您解析索引名称。

如果您通过 Laravel 迁移创建结构并使用 entry 适配器，我们将自动为您添加一个表别名。此别名遵循复数模型名称的 snake_case 规范。

示例

在以下示例中，使用名为 structures 的默认数据库连接配置了 netflex 驱动和 entry 适配器。

config/database.php

return [
    'default' => 'structures',

    'connections' => [

        'structures' => [
            'driver' => 'netflex',
            'adapter' => 'entry',
        ]
    ]
];

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Article extends Model
{
    //
}

Laravel 会根据模型名称推断表名，并使用在 'netflex' 驱动后连接上配置的 entry_ 前缀。

这意味着搜索查询将被映射到 entry_articles 索引。

如果不使用别名，可以使用以下语法

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Article extends Model
{
    protected $table = '10000';
}

如果您有多个数据库连接，并且默认连接未配置为使用 netflex 驱动，您可以通过在模型上设置 $connection 属性来指定要使用的连接。

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Article extends Model
{
    protected $connection = 'structures';
    protected $table = '10000';
}

注意事项

由于 Netflex API 使用 created 和 updated 字段名作为默认的时间戳，请记住在您的模型中配置这一点，因为 Eloquent 默认假设 created_at 和 updated_at。

const CREATED_AT = 'created';
const UPDATED_AT = 'updated';

迁移

支持对 entry 适配器进行迁移，并将在 Netflex 中自动创建或更改结构。

Netflex API 中的保留字段将自动处理，不会被添加或更改。这允许您为 Netflex 和关系型数据库使用相同的迁移。

不支持唯一约束和级联。您可以在迁移中包含它们，但它们将被忽略。

您可以通过 Artisan 正常创建和管理迁移。

如果没有指定类型，将使用以下类型

text（字符串）
textarea（bigText，text，bigInt 等）
integer（int）
float（float，decimal）
checkbox（布尔值）
json（json）

支持默认值。在这里，您还可以使用 Netflex 的特殊语法来自动添加某些值，如日期时间、UUID 等。有关更多信息，请参阅 Netflex 文档。

假设您已配置默认数据库连接使用 netflex 驱动和 entry 适配器

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    /**
     * Run the migrations.
     */
    public function up(): void
    {
        Schema::create('articles', function (Blueprint $table) {
            $table->id(); // Ignored by Netflex
            $table->string('intro');
            $table->timestamp('written_at')->useCurrent(); // Sets the default_value config to "{datetime}"
            $table->text('body')->widget('editor-large'); // You may specify which widget to use in the Netflex UI
        });
    }

    /**
     * Reverse the migrations.
     */
    public function down(): void
    {
        Schema::dropIfExists('articles');
    }
};

Netflex 特定功能

如果您以前使用过 Netflex SDK 的模型实现，一些功能是开箱即用的，并且与 Eloquent 模型直接不兼容。

此包提供了一些特质，您可以将它们应用到模型上以恢复此功能。

如果您使用 Netflex\Database\Eloquent\Model 作为基础模型，则所有这些功能都是开箱即用的（除了缓存）。

缓存

由于缓存应由应用程序处理，因此此驱动程序不处理缓存。自动缓存的替代方案是使用带有标签的缓存驱动程序并安装处理缓存 Eloquent 模型的第三方包。

推荐包

genealabs/laravel-model-caching

自动尊重条目的发布状态

如果您想自动尊重条目的发布状态，可以将 Netflex\Database\Concerns\Publishable 特质应用到模型上。

在保存时从 API 刷新数据

在插入或更新条目时，一些数据可能会被 API 修改，例如 id 或 url 属性等。

Laravel 不会在保存后自动刷新模型（出于性能原因），因此您可能会得到过时的数据。

如果您想在保存后自动刷新模型，可以将 Netflex\Database\Concerns\RefreshesOnSave 特质应用到模型上。

自动设置条目名称

如果您尝试插入没有设置 name 属性的条目，API 将引发错误。在 Netflex SDK 中，模型会自动处理这种情况，但这与 Eloquent 模型不一致。

您可以通过将 Netflex\Database\Concerns\GeneratesName 特质应用到模型上来恢复此功能。

这将自动为条目生成一个基于 UUID 的名称，除非提供名称。

限制

此包已在 PHP >7.4 和 PHP 8.0 到 8.2 上进行了测试。

当前内部虚拟PDO实现作为一个独立的包实现（netflex/dbal）。这是因为PDO在PHP 7.4和8.0之间的内部类型签名发生了变化，我们需要支持这两个版本。

在后续阶段，当我们停止支持PHP 7.4时，我们将PDO占位符移动到这个包的代码库中。

许可证

MIT许可证（MIT）。请参阅许可文件获取更多信息。

netflex / database

维护者

详细信息