README

此包使与 Google 日历协同工作变得轻松。一旦设置好，您可以执行以下操作

use Spatie\GoogleCalendar\Event;

//create a new event
$event = new Event;

$event->name = 'A new event';
$event->description = 'Event description';
$event->startDateTime = Carbon\Carbon::now();
$event->endDateTime = Carbon\Carbon::now()->addHour();
$event->addAttendee([
    'email' => 'john@example.com',
    'name' => 'John Doe',
    'comment' => 'Lorum ipsum',
]);
$event->addAttendee(['email' => 'anotherEmail@gmail.com']);
$event->addMeetLink(); // optionally add a google meet link to the event

$event->save();

// get all future events on a calendar
$events = Event::get();

// update existing event
$firstEvent = $events->first();
$firstEvent->name = 'updated name';
$firstEvent->save();

$firstEvent->update(['name' => 'updated again']);

// create a new event
Event::create([
   'name' => 'A new event',
   'startDateTime' => Carbon\Carbon::now(),
   'endDateTime' => Carbon\Carbon::now()->addHour(),
]);

// delete an event
$event->delete();

Spatie 是一家位于比利时安特卫普的网页设计公司。您可以在我们的网站上找到我们所有开源项目的概述 在这里。

支持我们

我们投入了大量资源来创建 一流的开放源代码包。您可以通过 购买我们的付费产品之一 来支持我们。

我们非常感谢您从您的家乡寄给我们一张明信片，说明您正在使用我们哪些包。您可以在我们的 联系页面 上找到我们的地址。我们将在 我们的虚拟明信片墙上 发布收到的所有明信片。

安装

您可以通过 composer 安装此包

composer require spatie/laravel-google-calendar

您必须使用此命令发布配置

php artisan vendor:publish --provider="Spatie\GoogleCalendar\GoogleCalendarServiceProvider"

这将发布一个名为 google-calendar.php 的文件到您的配置目录中，内容如下

return [

    'default_auth_profile' => env('GOOGLE_CALENDAR_AUTH_PROFILE', 'service_account'),

    'auth_profiles' => [

        /*
         * Authenticate using a service account.
         */
        'service_account' => [
            /*
             * Path to the json file containing the credentials.
             */
            'credentials_json' => storage_path('app/google-calendar/service-account-credentials.json'),
        ],

        /*
         * Authenticate with actual google user account.
         */
        'oauth' => [
            /*
             * Path to the json file containing the oauth2 credentials.
             */
            'credentials_json' => storage_path('app/google-calendar/oauth-credentials.json'),

            /*
             * Path to the json file containing the oauth2 token.
             */
            'token_json' => storage_path('app/google-calendar/oauth-token.json'),
        ],
    ],

    /*
     *  The id of the Google Calendar that will be used by default.
     */
    'calendar_id' => env('GOOGLE_CALENDAR_ID'),
];

如何获取与 Google 日历通信的凭证

首先，您需要获取用于使用 Google API 的凭证。我假设您已经创建了一个 Google 账户并已登录。前往 Google API 控制台 并在标题中点击 "选择项目"。

接下来，我们必须指定项目可以使用的 API。从标题中选择 "启用 API 和服务"。

在下一页，搜索 "Calendar" 并从列表中选择 "Google Calendar API"。

从这里，按 "启用" 以为此项目启用 Google Calendar API。

现在，您已经创建了一个可以访问日历 API 的项目，是时候下载包含这些凭证的文件了。在侧边栏中点击 "凭证"，然后点击 "API 和服务中的凭证" 链接。

从此页面，打开 "创建凭证" 下拉菜单并选择 "服务账户密钥"。

在下一屏幕上，您可以给服务账户起一个名字。您可以取任何名字。在服务账户 ID 中您会看到一个电子邮件地址。我们稍后会在此指南中使用此电子邮件地址。选择 "JSON" 作为密钥类型，点击 "创建" 下载 JSON 文件。您将收到一个警告，表明服务账户没有角色，您可以安全地忽略此警告，不分配角色即可创建服务账户。

如果您已将域范围访问委托给服务账户并希望模拟用户账户，请在配置文件中指定用户账户的电子邮件地址。

将 json 文件保存在您的 Laravel 项目中，位置在包配置文件中 service_account_credentials_json 键指定的位置。因为 json 文件可能包含敏感信息，我不建议将其提交到您的 git 仓库。

现在API站点上的所有设置都已就绪，我们还需要在Google日历网站上配置一些设置。请前往Google日历并查看您想通过PHP操作的日历的设置。在“与特定人员共享”选项卡上，点击“添加人员”按钮，并添加在API站点创建凭据时显示的服务帐户ID。

滚动到“集成日历”部分以查看日历的ID。您需要在配置文件中指定该ID。

OAuth2身份验证

此包支持OAuth2身份验证。这允许您使用实际Google帐户进行身份验证，并使用您自己的Google帐户创建和管理事件。

OAuth2身份验证需要除凭据文件外还需要一个令牌文件。生成这两个文件的最简单方法是通过使用php quickstart工具。按照此指南将生成两个文件，credentials.json和token.json。它们必须分别保存为您的项目的oauth-credentials.json和oauth-token.json。请检查本包中的配置文件，以获取有关保存这些文件的详细信息。

要使用OAuth2，您还必须在.env文件中设置一个新的环境变量

GOOGLE_CALENDAR_AUTH_PROFILE=oauth

如果您正在从此包的旧版本升级，您将需要强制发布配置

php artisan vendor:publish --provider="Spatie\GoogleCalendar\GoogleCalendarServiceProvider" --force

最后，为了在您的应用程序中获得更流畅的体验，您可以在Google API控制台中设置一个同意屏幕，而不是使用quickstart工具。这将允许您的应用程序的非技术用户轻松生成自己的令牌。这是完全可选的。

用法

获取事件

您可以通过调用Event::get();来获取所有事件，这将返回未来一年的所有事件。事件以Spatie\GoogleCalendar\Event对象的形式出现。

函数的完整签名如下

public static function get(Carbon $startDateTime = null, Carbon $endDateTime = null, array $queryParameters = [], string $calendarId = null): Collection

您可以在$queryParameters中传递的参数列于Google日历API文档中关于list的文档上。

访问事件的开始和结束日期

您可以使用这些getter来检索开始和结束日期作为Carbon实例

$events = Event::get();

$events[0]->startDate;
$events[0]->startDateTime;
$events[0]->endDate;
$events[0]->endDateTime;

创建事件

您只需创建一个Spatie\GoogleCalendar\Event-对象

$event = new Event;

$event->name = 'A new event';
$event->startDateTime = Carbon\Carbon::now();
$event->endDateTime = Carbon\Carbon::now()->addHour();

$event->save();

您还可以静态地调用create

Event::create([
   'name' => 'A new event',
   'startDateTime' => Carbon\Carbon::now(),
   'endDateTime' => Carbon\Carbon::now()->addHour(),
]);

这将创建一个具有特定开始和结束时间的活动。如果您想创建一个全天活动，您必须使用startDate和endDate而不是startDateTime和endDateTime。

$event = new Event;

$event->name = 'A new full day event';
$event->startDate = Carbon\Carbon::now();
$event->endDate = Carbon\Carbon::now()->addDay();

$event->save();

您可以根据简单的文本字符串创建事件，如下所示

$event = new Event();

$event->quickSave('Appointment at Somewhere on April 25 10am-10:25am');

// statically
Event::quickCreate('Appointment at Somewhere on April 25 10am-10:25am');

获取单个事件

Google为每个单个事件分配一个唯一的ID。您可以通过使用get方法获取事件，并在Spatie\GoogleCalendar\Event-对象上获取id属性来获取此ID

// get the id of the first upcoming event in the calendar.
$eventId = Event::get()->first()->id;

// you can also get the id after creating the event, then you can save it to database.
$event = new Event;
$newEvent = $event->save();
echo $newEvent->id; // displey the event id

您可以使用此ID从Google获取单个事件

Event::find($eventId);

更新事件

很简单，只需更改一些属性并调用save()

$event = Event::find($eventId);

$event->name = 'My updated title';
$event->save();

或者，您还可以使用更新方法

$event = Event::find($eventId)

$event->update(['name' => 'My updated title']);

删除事件

没有其他事！

$event = Event::find($eventId);

$event->delete();

设置源

您可以在事件中设置源URL，这些URL仅对事件创建者可见（有关源属性的更多信息，请参阅文档）。此函数仅在通过OAuth身份验证时才有效。

$yourEvent->source = [
   'title' => 'Test Source Title',
   'url' => 'http://testsource.url',
 ];

设置颜色

您可以为您的事件设置特定颜色（颜色ID 1 到 11）。可能的选择仅限于Google日历API的颜色定义。您可以在此处找到它们。

$yourevent->setColorId(11);

限制

Google日历API提供了许多选项。此包不支持全部功能。例如，无法使用此包正确管理重复事件。如果你坚持使用名称和日期创建事件，应该不会有问题。

从v1升级到v2

在v1和v2之间唯一的重大区别在于，内部使用的是Google API v2而不是v1。以下是升级所需的步骤

• 将配置文件名从laravel-google-calendar重命名为google-calendar
• 在配置文件中将client_secret_json键重命名为service_account_credentials_json

变更日志

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

测试

composer test

贡献

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

安全

如果你发现任何与安全相关的问题，请通过电子邮件freek@spatie.be联系，而不是使用问题跟踪器。

鸣谢

• Freek Van der Herten
• 所有贡献者

非常感谢Sebastiaan Luca为创建此包的v2版本提供的巨大帮助。

许可证

MIT许可证（MIT）。有关更多信息，请参阅许可证文件。