README

Laravel ACalendar 包旨在为 Laravel 应用程序提供高级事件管理功能。它允许开发者无缝地将事件功能集成到 Eloquent 模型中，管理事件发生，并轻松处理重复事件。本指南概述了包的主要功能、安装过程和详细示例的用法。

功能和主要概念

• 灵活的事件管理：直接与 Eloquent 模型相关联地创建、更新和删除事件。
• 支持多种事件类型：处理不同类型的事件，包括单次事件、全天、日期范围和定时事件。
• 重复事件：全面支持可自定义频率的重复事件。
• Eloquent 模型集成：使用特质和接口轻松将任何 Eloquent 模型与事件集成。
• 动态事件实例生成：自动处理重复事件在指定日期范围内的实例生成。
• 自定义事件集合方法：提供 byDay() 方法对事件实例进行分组，便于日历视图或每日摘要。

安装

1. 通过 Composer 安装包

composer require aurorawebsoftware/acalendar

1. 发布配置和迁移文件

php artisan vendor:publish --provider="AuroraWebSoftware\ACalendar\ACalendarServiceProvider"

1. 执行迁移

php artisan migrate

枚举

类型枚举

• DATE_ALL_DAY：全天发生的事件。
• DATE_POINT：分配给特定日期的事件。
• DATETIME_POINT：分配给特定日期和时间的事件。
• DATE_RANGE：跨越多个日期的事件。
• DATETIME_RANGE：具有特定开始和结束日期和时间的事件。

重复频率枚举

• DAY：事件每天重复。
• WEEK：事件每周重复。
• MONTH：事件每月重复。
• YEAR：事件每年重复。

与模型集成

实现 EventableModelContract 并在您的模型中使用 HasEvents 特质

namespace App\Models;

use AuroraWebSoftware\ACalendar\Contracts\EventableModelContract;
use AuroraWebSoftware\ACalendar\Traits\HasEvents;
use Illuminate\Database\Eloquent\Model;

class Task extends Model implements EventableModelContract
{
    use HasEvents;

    protected $fillable = ['name'];

    public static function getModelType(): string
    {
        return self::class;
    }

    public function getModelId(): int
    {
        return $this->id;
    }

    public function getEventTitle(): ?string
    {
        return $this->name;
    }
}

使用示例

创建事件

$task = Task::find(1);
$task->updateOrCreateEvent(
    key: 'deadline',
    type: Type::DATE_POINT,
    start: Carbon::tomorrow(),
    title: 'Preparing SRS Docs'
);

$task->updateOrCreateEvent(
    key: 'deadline',
    type: Type::DATE_POINT,
    start: Carbon::tomorrow(),
    title: 'Preparing SRS Docs'
);

带有键的模型只能创建一个事件

检索事件实例

• 实例上的动态方法

$events = $task->eventInstances('deadline', Carbon::now(), Carbon::now()->addMonth(1));

• 模型类上的静态方法

$events = Task::allEventInstances('deadline', Carbon::now(), Carbon::now()->addMonth(1));

处理重复事件

$meeting = Meeting::find(1);
$meeting->updateOrCreateEvent(
    key: 'Weekly Review',
    type: Type::DATETIME_POINT,
    start: Carbon::parse('next monday 10:00'),
    repeatFrequency: RepeatFrequency::WEEK,
    repeatPeriod: 1,
    title: 'Weekly Review Meeting'
);

使用 byDay 方法

在 Laravel ACalendar 包中的 byDay() 方法根据事件发生的日期对事件实例进行分组，返回一个集合，其中每个键是一个日期，值是该日期发生的事件集合。此方法通过按日期索引格式组织事件，简化了日历视图或每日计划，便于显示每天发生的事件。

• 通过按日分类事件，便于开发日历界面。

$eventInstances = $meeting->eventInstances(null, Carbon::now(), Carbon::now()->addWeeks(4));
$byDay = $eventInstances->byDay();

foreach ($byDay as $date => $events) {
    echo "Date: $date\n";
    foreach ($events as $event) {
        echo "- {$event->title} at {$event->start->format('H:i')}\n";
    }
}

场景设置

假设我们有三个模型 - Conference、Webinar 和 Exhibition，每个模型都如前例所示与 ACalendar 包集成。这些模型将展示不同的事件类型，如 DATE_ALL_DAY、DATE_RANGE 和 DATETIME_RANGE。

Conference：全天事件

会议通常持续一整天。以下是设置会议全天事件的方法

$conference = Conference::create(['name' => 'Tech Innovators Conference', 'description' => 'A gathering of technology innovators.']);

$conference->updateOrCreateEvent(
    key: 'tech_innovators_2024',
    type: Type::DATE_ALL_DAY,
    start: Carbon::parse('2024-09-10'),
    title: 'Tech Innovators Conference - All Day'
);

Webinar：日期范围事件

网络研讨会可以跨越多天。本例演示了创建覆盖日期范围的事件

$webinar = Webinar::create(['title' => 'Digital Marketing 101', 'host' => 'Marketing Gurus']);

$webinar->updateOrCreateEvent(
    key: 'digital_marketing_101',
    type: Type::DATE_RANGE,
    start: Carbon::parse('2024-10-05'),
    end: Carbon::parse('2024-10-07'),
    title: 'Digital Marketing 101 Webinar'
);

Exhibition：日期时间范围事件

展览可能具有特定的开始和结束时间。以下是设置具有日期时间范围的活动的步骤

$exhibition = Exhibition::create(['name' => 'Artists of the 21st Century', 'location' => 'City Art Gallery']);

$exhibition->updateOrCreateEvent(
    key: '21st_century_artists',
    type: Type::DATETIME_RANGE,
    start: Carbon::parse('2024-11-20 09:00'),
    end: Carbon::parse('2024-11-20 17:00'),
    title: 'Artists of the 21st Century Exhibition'
);

查询和显示事件实例

显示即将举行的会议

检索并显示未来一年的所有即将举行的会议

phpCopy code
$upcomingConferences = Conference::allEventInstances(
    null,
    Carbon::now(),
    Carbon::now()->addYear(1)
);

foreach ($upcomingConferences as $event) {
    echo "Conference: {$event->title} on {$event->start->toDateString()}\n";
}

下个月的网络研讨会日程

生成下个月发生的所有网络研讨会的日程，按天分组

phpCopy code
$nextMonthWebinars = Webinar::allEventInstances(
    null,
    Carbon::now()->addMonth(),
    Carbon::now()->addMonths(2)
)->byDay();

foreach ($nextMonthWebinars as $date => $webinars) {
    echo "Date: $date\n";
    foreach ($webinars as $webinar) {
        echo "- Webinar: {$webinar->title} from {$webinar->start->toDateString()} to {$webinar->end->toDateString()}\n";
    }
}

展览时间

对于展览，了解确切的开放和关闭时间可能很有用

phpCopy code
$exhibitionDetails = Exhibition::allEventInstances('21st_century_artists', Carbon::now(), Carbon::now()->addMonth(1));

foreach ($exhibitionDetails as $detail) {
    echo "Exhibition: {$detail->title}, Start: {$detail->start->toDateTimeString()}, End: {$detail->end->toDateTimeString()}\n";
}

这些示例仅展示了Laravel ACalendar包在管理事件时所能实现的许多可能性中的一小部分。通过利用不同的事件类型和重复频率，开发者可以定制该包以满足他们在Laravel应用程序中广泛的会议管理需求。

本Laravel ACalendar包指南旨在为在您的Laravel应用程序中集成和使用事件管理提供一个坚实的基础。通过遵循安装说明并探索全面的示例，您可以利用该包的功能来增强您项目的高级事件处理能力。