README

Orbit 是 Laravel Eloquent 的平面文件驱动。它允许你用你可以操作的真正文件替换你的通用数据库。

安装

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

composer require ryangjchandler/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 是 schema 中的一个列。

更改驱动程序

如果您想为您的模式之一使用不同的驱动程序，您可以在模式中添加一个 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;
    }
}