README

协调器

协调器是一个针对Laravel的通用资源预订系统，它以简洁性为设计理念。它将允许您使用简单的直观API预订（或安排）资源。

该包的构建假设您可能需要根据自己的需求对其进行扩展，因此使用了很多约定。请确保熟悉概念。

安装

您可以通过composer安装此包

composer require binary-cats/coordinator

服务提供程序将自动注册自身并在您的Laravel安装中添加以下配置

use BinaryCats\Coordinator\Eloquent\Booking;
use Spatie\Period\Boundaries;
use Spatie\Period\Precision;

return [

    /*
    |--------------------------------------------------------------------------
    | Coordinator: Booking Model
    |--------------------------------------------------------------------------
    |
    | The default is `BinaryCats\Coordinator\Eloquent\Booking`.
    | You are likely to extend the class or replace it with your implementation:
    | Model must implement `BinaryCats\Coordinator\Contracts\Booking`
    |
    */

    'booking_model' => Booking::class,

    /*
    |--------------------------------------------------------------------------
    | Booking Period: Precision
    |--------------------------------------------------------------------------
    | Date precision is important if you want to reliably compare two periods:
    | @see https://stitcher.io/blog/comparing-dates
    |
    | Valid options are:
    | YEAR|DAY|HOUR|MINUTE|SECOND
    */

   'precision' => Precision::SECOND(),

   /*
    |--------------------------------------------------------------------------
    | Booking Period: Boundaries
    |--------------------------------------------------------------------------
    | By default, period comparisons are done with included boundaries
    |
    | Valid options are:
    | EXCLUDE_NONE|EXCLUDE_START|EXCLUDE_END|EXCLUDE_ALL
    */

   'boundaries' => Boundaries::EXCLUDE_NONE(),
];

要更改设置中的任何内容，您可以使用以下方式发布配置文件

php artisan vendor:publish --tag=coordinator-config

配置文件将发布在 config/coordinator.php

迁移

运行以下命令将发布用于预订表的单一迁移

php artisan vendor:publish --tag=coordinator-migrations

概念

该包为您提供单个模型：预订。

预订模型

Booking 是一个将可预订资源（如 Room、Table 或 TechSupport）与预订该资源的模型关联起来的单一记录。由于“预订”这个词在每个词中都出现，因此可能一开始难以理解。本质上，Booking 是一个 关联模型，具有两个多态键：代表关系所有者的 model 和代表我们想要预订的资源 resource。

一个简单的例子可能有助于理解

当客户想要租用房间时，我们有一个客户和他们想要租用的资源之间的关系。

客户是 model，房间是 resource，他们的关系存储为 Booking。

可用性

您可能不想有重叠的预订资源，但这不应阻止您尝试！

在您可能希望创建两个预订的情况下，无论谁首先确认，谁就获得时段，另一人取消预订，这是有正当用例的。

协调器不会试图强迫您这样做，但这意味着您需要自行实现此逻辑。

使用

让我们准备我们的模型。首先，可预订的资源

use BinaryCats\Coordinator\CanBeBooked;
use BinaryCats\Coordinator\Contracts\BookableResource;
use Illuminate\Database\Eloquent\Model;

class Room extends Model implements BookableResource
{
    use CanBeBooked;
}

注意，Resource 实现 BinaryCats\Coordinator\Contracts\BookableResource。

现在，一个预订资源的模型

use BinaryCats\Coordinator\BooksResources;
use BinaryCats\Coordinator\Contracts\CanBookResources;
use Illuminate\Database\Eloquent\Model;

class User extends Model implements CanBookResources
{
    use BooksResources;
}

注意，Model 实现 BinaryCats\Coordinator\Contracts\CanBookResources。

与通知一样，您不应该局限于“这是一个预订东西的用户”这样的想法。任何模型都可以预订任何其他资源；例如，司机用户可以被配送预订。

协调器提供流畅的接口来创建预订，可以在关系的任一侧使用

    $booking = User::first()->createBookingFor(Room::first(), [
        'starts_at' => '2021-01-01 15:45',
        'ends_at' => '2021-01-02 15:45',
    ]);

和

    $booking = Room::first()->createBookingFor(User::first(), [
        'starts_at' => '2021-01-01 15:45',
        'ends_at' => '2021-01-02 15:45',
    ]);

将产生相同的结果。

检查可用性

可预订资源提供检查在给定时间点是否可用或已预订的方法

要使用 isAvailableAt 检查 Room 在给定时间点是否可用。第一个参数可以是任何可以转换为 Carbon\Carbon 实例的实现、字符串或甚至是周期

Room::first()->isAvailableAt(new DateTime);
Room::first()->isAvailableAt(Carbon\Carbon::now());
Room::first()->isAvailableAt('2021-01-01 15:45');
Room::first()->isAvailableAt('2021-01-01 3:45 PM CST');

要检查“2021-01-01”当天《房间》是否可用，您可以使用isAvailableAt方法。

    // bookings = [
    //      [
    //          ...
    //          'starts_at' => '2021-01-01',
    //          'ends_at' => '2021-01-02',
    //          'cancelled_at' => '2021-04-02'
    //      ]
    // ];
    Room::first()->isAvailableAt('2021-01-01');
    // true;

您可以通过传递第二个参数来考虑已取消的预订。

    // bookings = [
    //      [
    //          ...
    //          'starts_at' => '2021-01-01',
    //          'ends_at' => '2021-01-02',
    //          'cancelled_at' => '2021-04-02'
    //      ]
    // ];
    Room::first()->isAvailableAt('2021-01-01', true);
    // false

您可以使用isBookedAt方法检查在特定时刻《房间》是否已被预订。

    // bookings = [
    //      [
    //          ...
    //          'starts_at' => '2021-01-01',
    //          'ends_at' => '2021-01-02',
    //          'cancelled_at' => '2021-04-02'
    //      ]
    // ];
    Room::first()->isBookedAt('2021-01-01');
    // false;

您可以通过传递第二个参数来考虑已取消的预订。

    // bookings = [
    //      [
    //          ...
    //          'starts_at' => '2021-01-01',
    //          'ends_at' => '2021-01-02',
    //          'cancelled_at' => '2021-04-02'
    //      ]
    // ];
    Room::first()->isBookedAt('2021-01-01', true);
    // true;

高级用法

您也可以检查资源在某个时间段内是否已被预订或可用。在这样做的时候，请确保您比较的是精度相同的时期。最简单的方法是直接依赖协调器本身的设置。

use BinaryCats\Coordinator\Coordinator;
use Spatie\Period\Period;

    $period = Period::make('2021-01-01 15:45:00', '2021-01-02 15:45:00', Coordinator::defaultPrecision());

    // bookings = [
    //      [
    //          ...
    //          'starts_at' => '2021-01-01 10:00:00',
    //          'ends_at' => '2021-01-02 09:00:00',
    //      ]
    // ];
    Room::first()->isBookedAt($period);
    // true;

默认情况下，协调器会查找SECOND作为精度。您可以通过更新coordinator.precision配置键来更改这一点。更多关于时期计算的信息请点击这里；

您还可以检查资源在给定模型中是否可用。然而，由于这更多是一个策略问题，您需要提供闭包解析逻辑。例如，您可能希望使用Gate来委托授权逻辑。

use Illuminate\Support\Facades\Gate;

Room::first()->isAvailableFor(User::first(), function($model, $resource) {
    // Assuming model is \Illuminate\Contracts\Auth\Access\Authorizable
    return Gate::forUser($model)->allows('book', $resource);
});

或者任何其他方式

Room::first()->isAvailableFor(User::first(), function($model, $resource) {
    // ... return resolution
});

变更日志

有关最近更改的更多信息，请参阅变更日志。

测试

composer test

贡献

有关详细信息，请参阅贡献指南。

安全性

如果您发现任何安全相关的问题，请通过电子邮件cyrill.kalita@gmail.com联系，而不是使用问题跟踪器。

Postcardware

您可以使用这个包，但如果它进入了您的生产环境，我们非常希望您能从家乡寄给我们一张明信片，说明您正在使用我们哪个包。

binary-cats / coordinator

维护者

详情