README

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

use Patimio66\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->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();

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

支持我们

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

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

安装

您可以通过composer安装此包

composer require spatie/laravel-google-calendar

您必须使用以下命令发布配置

php artisan vendor:publish --provider="Patimio66\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

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

从数据库进行OAuth2认证

如果您已经在数据库中存储了用户的令牌，您也可以使用user_oauth而不是oauth来使用他们的令牌进行OAuth认证

GOOGLE_CALENDAR_AUTH_PROFILE=user_oauth

在文件config/google-calendar.php中，您可以自定义guard以及存储用户令牌的column。

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

    /*
     * Auth guard.
     */
    'guard' => 'web',

    /*
     * Column stored calendar token.
     */
    'column' => 'calendar_token',
],

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

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

用法

获取事件

您可以通过调用Event::get();来获取所有事件，这将返回未来一年中的所有事件。一个事件以Patimio66\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;

创建一个事件

您可以直接创建一个Patimio66\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方法获取事件并从Patimio66\GoogleCalendar\Event对象获取id属性来获取此ID

// get the id of the first upcoming event in the calendar.
$eventId = Event::get()->first()->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',
 ];

限制

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）。请参阅许可证文件以获取更多信息。