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快速入门工具。遵循此指南将生成两个文件，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）。有关更多信息，请参阅许可证文件。