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->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 hamedmax73/laravel-google-calendar

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

php artisan vendor:publish --provider="hamedmax73\laravel-google-calender\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和服务”。

在下一页上，搜索“日历”并从列表中选择“Google日历API”。

从这里，按“启用”以为此项目启用Google日历API。

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

从该页面，打开“创建凭证”下拉菜单并选择“服务帐户密钥”。

在下一屏幕上，您可以给服务帐户命名。您可以为它命名任何您想要的名称。在服务帐户ID中您将看到一个电子邮件地址。我们将在本指南的后续部分使用此电子邮件地址。选择“JSON”作为密钥类型，然后点击“创建”以下载JSON文件。您将收到一个警告，表明服务帐户没有角色，您可以安全地忽略此警告并创建服务帐户而不分配角色。

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

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

现在API站点上的一切都已设置好，我们还需要在Google日历网站上配置一些内容。转到Google日历并查看您要通过PHP操作的那个日历的设置。在“与特定人员共享”选项卡上，点击“添加人员”按钮，并添加在API站点上创建凭证时显示的服务帐户ID。

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

OAuth2认证

本包支持OAuth2认证。这允许您使用实际谷歌账户进行认证，并使用自己的谷歌账户创建和管理事件。

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

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

用法

获取事件

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

该函数的完整签名是

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

您可以在$queryParameters中传递的参数列表请参阅谷歌日历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');

获取单个事件

谷歌为每个单个事件分配一个唯一的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从谷歌获取单个事件

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',
 ];

限制

谷歌日历API提供了许多选项。本包不支持所有这些选项。例如，使用本包无法正确管理重复事件。如果您坚持使用具有名称和日期的事件创建，则应该没问题。

从v1升级到v2

v1和v2之间的唯一主要区别在于底层使用的是谷歌API v2而不是v1。以下是升级所需的步骤

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

变更日志

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

测试

composer test

贡献

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

安全

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

鸣谢

感谢Sebastiaan Luca 在创建此包的 v2 版本中提供的巨大帮助。

许可证

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

hamedmax73 / laravel-google-calendar

维护者

详细信息