README

Orbit 是 Laravel Eloquent 的平面文件驱动程序。它允许你使用你熟悉的方法替换通用的数据库，用实际文件来操作。

安装

要在项目中安装 Orbit，请运行以下命令

composer require esyede/orbit

使用

要开始使用 Orbit，请创建一个 Laravel 模型并使用 Orbit\Concerns\Orbital 特性。

class Post extends Model
{
    use \Orbit\Concerns\Orbital;
}

Orbital 特性负责钩入 Eloquent 生命周期并确保所有交互都得到正确处理。

定义模式

就像数据库迁移一样，你需要定义 Orbit 模型可以拥有的不同数据。在你的模型中添加一个 public static function schema(Blueprint $table) 方法。

此方法需要接受一个 Illuminate\Database\Schema\Blueprint 实例，就像迁移一样。

use Illuminate\Database\Schema\Blueprint;

class Post extends Model
{
    use \Orbit\Concerns\Orbital;

    public static function schema(Blueprint $table)
    {
        $table->string('title');
        $table->string('slug');
        $table->timestamp('published_at');
    }
}

如果你的某些数据是可选的，请确保相应的列是 nullable。

存储内容

默认情况下，所有内容都存储在应用根目录下的 content 文件夹中。如果你想更改此设置，发布 orbit.php 配置文件并更改 orbit.paths.content 选项。

Orbit 将将模型的基本名称转换为复数蛇形字符串，并使用该字符串作为主要文件夹名称，例如 Post -> content/posts，PostCategory => content/post_categories。

🚨 改变模型名称将阻止 Orbit 在旧文件夹中找到任何现有记录。如果你希望更改文件夹名称，请在你的模型类上重写 public static function getOrbitalName 方法并返回旧名称。

每次你调用 Model::create()、Model::update 或 Model::delete 时，Orbit 都会拦截这些调用并将它们转发到必要的驱动程序方法。然后驱动程序负责执行必要的文件系统调用。

更改主键

就像正常的 Eloquent 模型一样，你可以更改 Orbit 模型的主键。重写 Model::getKeyName 方法并返回你新模型的名字。

class Post extends Model
{
    use Orbital;

    public function getKeyName()
    {
        return 'slug';
    }
    
    public function getIncrementing()
    {
        return false;
    }
}

如果你的模型的主键（你在 getKeyName 中定义的键）不需要自动递增，你可以在模型上定义 public $incrementing = false 或重写 getIncrementing 方法。

标准的 Orbit 驱动程序将尊重新的键名，并在创建、更新和删除磁盘上的文件时使用该键名，例如，一个具有 slug hello-world 的 Post 将写入 content/posts/hello-world.md 文件。

🚨 在记录已存在之后更改模型键可能导致损坏。确保更改文件名称后，以便 Orbit 不创建重复内容。

软删除

由于 Orbit 需要在模型更新时更新磁盘上的文件，所以标准的 Eloquent SoftDeletes 特性并不完全适用。如果你想为 Orbit 模型添加软删除支持，你可以使用 Orbit\Concerns\SoftDeletes 特性。

此特性在底层使用 Eloquent，因此你可以访问所有正常的 SoftDeletes 方法，包括 isForceDeleting() 和 forceDelete()。

Orbit 版本添加了必要的钩子以执行文件系统操作以及确保你不完全删除你的内容。

验证规则

当处理检查数据库（例如 验证规则 中的 exists 和 unique）时，您应该使用模型的 完全限定命名空间（FQN） 而不是表名。

这是因为 Orbit 在一个单独的数据库连接上运行 - 使用 FQN 将允许 Laravel 正确解析合格的表名。

class StorePostRequest extends FormRequest
{
    public function authorize(): bool
    {
        return true;
    }

    public function rules(): array
    {
        return [
            'slug' => 'required|alpha_dash|unique:App\Post,id',
            // 'slug' => ['required', 'alpha_dash', Rule::unique(Post::class)],
            'title' => 'required',
            'description' => 'required',
        ];
    }
  }

测试

如之前在 验证规则 部分中提到的，Orbit 在一个名为 orbit 的自定义连接上运行。这意味着只要指定连接名称，Laravel 的数据库测试工具就可以正常工作。

$this->assertDatabaseCount('posts', 5, 'orbit');

$this->assertDatabaseHas('posts', [
    'title' => 'Hello, world',
    'slug' => 'hello-world',
], 'orbit');

驱动程序

Orbit 是一个基于驱动的包，这使得更改数据存储格式变得非常容易。

默认情况下，Orbit 提供以下驱动程序

• md -> Orbit\Drivers\Markdown
• json -> Orbit\Drivers\Json
• yaml -> Orbit\Drivers\Yaml

md

这是一个可以解析 Markdown 文件以及 YAML 前端内容的 Markdown。

当 Orbit 使用此驱动程序加载文件时，它将把每个前端密钥映射到模型 schema 中的列。

默认情况下，Markdown 驱动程序还将添加一个 TEXT content 列到您的模式中。这用于存储文件中的 Markdown 正文。

💡 如果您想自定义 content 列的名称，可以使用 Markdown::contentColumn() 方法并提供新的列名。这适用于所有使用 Markdown 驱动程序的模型。

json

这是一个可以解析 .json 文件的 JSON 驱动程序。文件中的每个键都映射到您的模式中的列。

yaml

这是一个可以解析 .yml 文件的 YAML 驱动程序。文件中的每个键都映射到您的模式中的列。

注册驱动程序

您可以使用 Orbit::extend 方法注册自定义 Orbit 驱动程序。您应该从 ServiceProvider 中的 boot 方法调用此方法。

\Orbit\Facades\Orbit::extend('json', function ($app) {
    return new \App\Drivers\JsonDriver($app);
})

所有驱动程序都必须实现 Orbit\Contracts\Driver 接口，或者扩展 Orbit\Drivers\FileDriver 类。这强制驱动程序至少有 4 个方法

interface Driver
{
    public function shouldRestoreCache(string $directory): bool;

    public function save(Model $model, string $directory): bool;

    public function delete(Model $model, string $directory): bool;

    public function all(string $directory): Collection;
}

以下是每个方法的作用

• shouldRestoreCache - 用于确定是否更新文件缓存。
• save - 用于将模型更改持久化到磁盘上的文件或创建新文件。
• delete - 用于从磁盘上删除现有文件。
• all - 用于从磁盘检索所有记录并缓存。

扩展 FileDriver

扩展 Orbit\Drivers\FileDriver 类在您希望有人为您处理繁重的工作时很有用。要使用此基类，您应该做以下事情

1. 实现一个 extension(): string 方法，返回文件扩展名为字符串，例如 return 'md' 用于 Markdown。
2. 实现一个 dumpContent(Model $model): string 方法。此方法应返回文件的更新内容。
3. 实现一个 parseContent(SplFileInfo $file): array 方法。此方法应返回一个 key => value 对的数组，其中每个 key 是模式中的列。

更改驱动程序

如果您想为您的模型使用不同的驱动程序，您可以在模型中添加一个 public static $driver 属性并将值设置为驱动程序名称。

class Post extends Model
{
    use Orbital;

    public static $driver = 'json';
}

驱动器名称是在与Orbit注册时确定的。您应始终使用驱动器的字符串名称，而不是完全限定的类名。

禁用Orbit

如果您有一个使用Orbital特征的模型，并希望临时禁用Orbit的功能，您可以在您的模型上重写enableOrbit(): bool方法

class Post extends Model
{
    use Orbital;

    public static function enableOrbit(): bool
    {
        return false;
    }
}