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',
    'responseStatus' => 'needsAction',
]);
$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控制台中设置一个同意屏幕。这将允许非技术用户轻松生成自己的令牌。这是完全可选的。

用法

获取事件

您可以通过调用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; // display 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）。有关更多信息，请参阅许可文件。