README

Gmail

Laravel 9 的 Gmail API

您需要在 Google Console 中创建一个应用程序。请在此处获取指导 here。

如果您需要 Laravel 5 兼容性，请使用版本 2.0.x。如果您需要 Laravel 6 兼容性，请使用版本 3.0.x。如果您需要 Laravel 7 兼容性，请使用版本 4.0.x。如果您需要 Laravel 8 兼容性，请使用版本 5.0.x。

要求

PHP ^8.0
Laravel 9

安装

将 dacastro4/laravel-gmail 添加到 composer.json。

"dacastro4/laravel-gmail": "^6.1"

运行 composer update 以拉取最新版本。

或者运行

composer require dacastro4/laravel-gmail

现在打开 config/app.php 并将服务提供者添加到 providers 数组中。

'providers' => [
    Dacastro4\LaravelGmail\LaravelGmailServiceProvider::class,
]

现在添加别名。

'aliases' => [
    'LaravelGmail' => Dacastro4\LaravelGmail\Facade\LaravelGmail::class,
]

对于 laravel >=5.5，这样就完成了。此包支持 Laravel 新的 Package Discovery。

为了与 PHP 7.4 兼容，请使用版本 v5.0

从 5.0 迁移到 6.0

需要 Laravel 9，并且您必须将依赖项更改为 "laravel/laravel": "^9.0"。请遵循从 8.x 升级到 9.0 指南

从 4.0 迁移到 5.0

需要 Laravel 8，并且您必须将依赖项更改为 "laravel/laravel": "^8.0"。请遵循从 7.x 升级到 8.0 指南

从 3.0 迁移到 4.0

需要 Laravel 7，并且您必须将依赖项更改为 "laravel/laravel": "^7.0"。请遵循从 6.x 升级到 7.0 指南

从 2.0 迁移到 3.0

需要 Laravel 6，并且您只需更改依赖项为 "laravel/laravel": "^6.0"

从 1.0 迁移到 2.0

唯一的更改是多重凭据功能。

将您的 composer.json 从 "dacastro4/laravel-gmail": "^1.0" 更改为 "dacastro4/laravel-gmail": "^2.0"

我必须更改版本，因为有一个拼写错误，这可能会破坏调用这些属性的应用程序。

所有包含“威胁”一词的变量都更改为“线程”（是的，我知道..对不起）。例如

邮件类 $threatId > $threadId

回复类 $mail->setReplyThreat() > $mail->setReplyThread()

等等。

从 0.6 迁移到 1.0

唯一的更改是多重凭据功能。

将您的 composer.json 从 "dacastro4/laravel-gmail": "^0.6" 更改为 "dacastro4/laravel-gmail": "^1.0"

如果您不想使用多用户凭据，您就不必做任何事情，如果您想这样做，您将需要再次登录以创建每个用户的新的凭据文件。

配置

您只需在您的 .env 文件中设置以下变量，然后您就可以开始了

GOOGLE_PROJECT_ID=
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_REDIRECT_URI=
GOOGLE_ALLOW_MULTIPLE_CREDENTIALS
GOOGLE_ALLOW_JSON_ENCRYPT

要修改作用域和凭据文件名，只需运行

运行 php artisan vendor:publish --provider="Dacastro4\LaravelGmail\LaravelGmailServiceProvider" 并修改配置文件 config/gmail.php。

允许多用户凭据

为了允许多用户凭证更改，请在您的配置文件中将 allow_multiple_credentials 设置为 true，或者如果您不使用配置文件，请将 .env 变量 GOOGLE_ALLOW_MULTIPLE_CREDENTIALS 设置为 true。

允许对 JSON 文件进行加密

为了允许对 JSON 文件进行加密，请在您的配置文件中将 allow_json_encrypt 设置为 true，或者如果您不使用配置文件，请将 .env 变量 GOOGLE_ALLOW_JSON_ENCRYPT 设置为 true。

可用的作用域

all (此作用域在 Gmail 作用域中不存在，我已添加。)
compose
insert
labels
metadata
modify
readonly
send
settings_basic
settings_sharing

更多关于 Gmail API 作用域的信息

注意：要更改作用域，用户必须注销并重新登录。

附加作用域

如果您需要添加附加作用域。

在 config/gmail.php 中以 URL 风格添加附加作用域

 'additional_scopes' => [
            'https://www.googleapis.com/auth/drive',
            'https://www.googleapis.com/auth/documents',
            'https://www.googleapis.com/auth/spreadsheets'
    ],

示例

欢迎 Blade

<body>
    <h1>{{ LaravelGmail::user() }}</h1>
    @if(LaravelGmail::check())
        <a href="{{ url('oauth/gmail/logout') }}">logout</a>
    @else
        <a href="{{ url('oauth/gmail') }}">login</a>
    @endif
</body>

路由

Route::get('/oauth/gmail', function (){
    return LaravelGmail::redirect();
});

Route::get('/oauth/gmail/callback', function (){
    LaravelGmail::makeToken();
    return redirect()->to('/');
});

Route::get('/oauth/gmail/logout', function (){
    LaravelGmail::logout(); //It returns exception if fails
    return redirect()->to('/');
});

然后，在您的控制器或其他任何您想要执行逻辑的地方，您可以执行如下操作：

$messages = LaravelGmail::message()->subject('test')->unread()->preload()->all();
foreach ( $messages as $message ) {
    $body = $message->getHtmlBody();
    $subject = $message->getSubject();
}

注意：如果您没有预加载消息，您必须执行如下操作：$body = $message->load()->getSubject();之后，您不需要再次调用它。

分页

使用 $messages->hasNextPage() 检查是否可获取下一页。使用 $messages->next() 获取下一页结果，这些结果与您首次加载第一页时使用的参数（每页结果、过滤器等）相同。使用 $messages->getPageToken() 获取下一页的唯一标识符。这在将结果存储到缓存时创建唯一标识符时非常有用。一般来说，使用 API 进行分页是一种不好的做法。它既慢又昂贵。因此，建议在页面之间移动时检索缓存的成果，并且只有在需要时才清除缓存。

文档

基本

LaravelGmail::getAuthUrl 获取用户认证的 URL。

LaravelGmail::redirect 您可以将此用作直接方法 <a href="{{ LaravelGmail::redirect() }}">登录</a>

LaravelGmail::makeToken() 在 JSON 文件中设置和保存 AccessToken（在回调中很有用）

LaravelGmail::logout 注销用户

LaravelGmail::check 检查用户是否已登录

LaravelGmail::setUserId($account_id)->makeToken() 设置和保存 $account_id 的 AccessToken（自 v5.1.2 添加）

发送

use Dacastro4\LaravelGmail\Services\Message\Mail;

...

$mail = new Mail;

对于 to、from、cc 和 bcc，您可以设置一个包含电子邮件和名称的数组，或者一个包含电子邮件和名称的字符串。

$mail->using( $token ) 如果您不想使用令牌文件，可以使用此函数设置请求中要使用的令牌。它不会刷新

$mail->to( $to, $name = null ) 设置收件人的电子邮件和名称，名称为可选

$mail->from( $from, $name = null ) 设置发送者的电子邮件

$mail->cc( $cc, $name = null ) 设置抄送

$mail->bcc( $bcc, $name = null ) 设置密件抄送

$mail->subject( $subject ) 设置电子邮件的主题

$mail->message( $message ) 设置电子邮件正文

$mail->view( 'view.name', $dataArray ) 从 Blade 文件设置正文

$mail->markdown( 'view.name', $dataArray ) 从 markdown 文件设置正文

$mail->attach( ...$path ) 向电子邮件添加文件附件

$mail->priority( $priority ) 设置电子邮件的优先级，从 1 到 5

$mail->reply() 回复现有的电子邮件

$mail->send() 发送新电子邮件

$mail->setHeader( $header, $value ) 设置电子邮件的头部

邮件

$mail->getId 返回电子邮件的 ID

$mail->getInternalDate 返回 UNIX 格式的日期

$mail->getDate 从电子邮件头部返回一个 Carbon 日期

$mail->getLabels 返回电子邮件的所有标签的数组

$mail->getHeaders 返回头信息集合。每个头信息是一个包含键和值的数组

$mail->getSubject 返回主题的字符串

$mail->getFrom 返回发送者的姓名和电子邮件的数组

$mail->getFromName 返回姓名的字符串

$mail->getFromEmail 返回电子邮件的字符串

$mail->getTo 返回所有收件者的姓名和电子邮件的数组

$mail->getDeliveredTo 返回收件人的电子邮件

$mail->getPlainTextBody 返回电子邮件的纯文本版本

$mail->getRawPlainTextBody 返回基于base64加密的原始邮件正文版本

$mail->hasAttachments 返回一个布尔值，表示电子邮件是否有附件

$mail->load 加载电子邮件的所有信息（标签、正文、头信息）。您需要在单个电子邮件上调用此函数。要从开始加载，请参阅 preload()

$mail->getHeader( $headerName, $regex = null ) 通过名称返回头信息。可选地，您可以对值执行正则表达式

    $mailbox = new LaravelGmailClass(config(), LaravelGmail::user());

    $label = new \Google_Service_Gmail_Label($this);
    $label->setMessageListVisibility('show'); `show || hide`
    $label->setLabelListVisibility('labelShow'); `labelShow || labelShowIfUnread || labelHide`
    $label->setName('labelName');
    $mailbox->createLabel($userEmail, $label);

FirstOrCreateLabel: 如果不存在，则在电子邮件上使用标签名称创建新标签

https://developers.google.com/gmail/api/reference/rest/v1/users.labels/create

示例

    $mailbox = new LaravelGmailClass(config(), LaravelGmail::user());

    $label = new \Google_Service_Gmail_Label($this);
    $label->setMessageListVisibility('show'); `show || hide`
    $label->setLabelListVisibility('labelShow'); `labelShow || labelShowIfUnread || labelHide`
    $label->setName('labelName');
    $mailbox->firstOrCreateLabel($userEmail, $label);

附件

use Dacastro4\LaravelGmail\Services\Message\Attachment
...

$attachment = new Attachment;

$attachment->getId 返回附件的ID

$attachment->getFileName 返回附件的文件名

$attachment->getMimeType 返回MIME类型。例如：application/pdf

$attachment->getSize 返回附件的大小（字节数）

$attachment->getData 从附件获取所有信息。如果您调用 getAttachmentsWithData，则不需要此方法。

$attachment->saveAttachmentTo($path = null, $filename = null, $disk = 'local') 在存储文件夹中保存附件。您可以传递路径、名称和磁盘以使用。

消息

LaravelGmail::message()->all( $pageToken = null ) 返回收件箱中的所有电子邮件

LaravelGmail::message()->take(2)->all( $pageToken = null ) take 方法通过设置的数字限制查询返回的电子邮件数量

LaravelGmail::message()->get( $id ) 返回具有所有信息的单个电子邮件

修饰符

您可以使用这些方法修改查询。例如

获取所有未读电子邮件： LaravelGmail::message()->unread()->all()

message()->unread()

message()->from( $email )

message()->in( $box = 'inbox' )

message()->hasAttachment()

message()->subject($subject)

->after($date) 和 ->before($date)

message()->raw($query) 用于自定义查询

所有可能的过滤器都在 Filterable 特性

当然，您可以用作流畅的API。

    LaravelGmail::message()
                ->from('someone@gmail.com')
                ->unread()
                ->in('TRASH')
                ->hasAttachment()
                ->all()

附件

use Dacastro4\LaravelGmail\Services\Message\Attachment
...

$attachment = new Attachment;