如何在项目中使用Composer加载 Google-API-PHP-Client 库操作谷歌服务

直接用 composer require google/apiclient 就行，官方包已经内置了自动加载，v2.15+ 是唯一推荐的稳定版本，PHP 版本得 ≥7.4，还得打开 json、curl、mbstring 这三个扩展。初始化的时候必须调用 setScopes()，注意区分服务账号和 OAuth 授权，类名也换成 GoogleService* 命名空间了。

直接用 composer require google/apiclient 就够了

别再去手动下载 ZIP、改 autoload，更不用自己写什么 PSR-4 映射——官方包对 Composer 自动加载的支持已经很完善了。google/apiclient 是唯一推荐的稳定版（v2.15+），旧版 google/apiclient-services 已经被合并到主包里，单独 require 反而会引起类冲突。

执行命令后，vendor/ 目录下会自动生成 google/apiclient 及其依赖（比如 guzzlehttp/guzzle、psr/http-client）。如果提示 ext-json missing 或 ext-curl not loaded，说明 PHP 缺了基础扩展——这可不是库的问题，是运行环境没配置好。

• PHP 版本必须 ≥ 7.4（v2.15 起不再支持 7.2）
• 必须启用 json、curl、mbstring 扩展
• 如果在 CLI 环境里跑（比如 cron 脚本），记得先用 php -m | grep curl 确认一下输出

初始化 Client 时必须显式设置 setScopes()

不设 scope 就去调 API？十有八九会撞上 401 Invalid Credentials 或 403 Insufficient Permission。Google 可不会给你“默认全开”的特权，每个请求都必须声明最小必要权限。

举个例子：读取 Gmail 邮件要用 https://www.googleapis.com/auth/gmail.readonly，写入日历要用 https://www.googleapis.com/auth/calendar.events。scope 字符串不能拼错、不能多空格、也不能漏掉 https:// 前缀。

• 多个 scope 用数组传进去：$client->setScopes(['scope1', 'scope2'])
• 开发阶段建议先用 https://www.googleapis.com/auth/drive.metadata.readonly 测试，它权限低、审批快
• 生产环境上线前，一定要去 Google Cloud Console 的 OAuth 同意页面补全应用名称和授权域名，否则用户授权页直接给你来个 404

服务账号（Service Account）和 OAuth 2.0 用户授权不能混用

这是最容易踩的坑：拿着服务账号的 JSON 文件去调需要用户上下文的 API（比如 GmailUsersMessagesResource），结果返回 400 Request had invalid authentication credentials——因为服务账号默认代表的是“机器”，不是“某个 G Suite 用户”。

区分起来其实很简单：

• 服务账号适合后台任务（比如定时同步公司共享 Drive 文件夹），要用 $client->setAuthConfig('service-account.json') + $client->useApplicationDefaultCredentials()，再 impersonate('user@domain.com')
• 普通用户授权必须走 OAuth 2.0 流程：先 createAuthUrl() 跳转，用户同意后拿到 code，再 fetchAccessTokenWithAuthCode($code) 换 token
• 拿到的 access_token 有效期只有 1 小时，必须配合 refresh_token 自动续期；refresh_token 只在首次授权时返回一次，记得存到数据库或文件里

Google_Service_* 类名已废弃，改用 namespaced 类

v2.0 之后就不再支持 Google_Service_Drive 这类旧类名了。现在所有服务都要通过 GoogleService* 命名空间来访问，比如 GoogleServiceDrive、GoogleServiceCalendar。如果代码里还在写 new Google_Service_Drive($client)，马上就会收到 Class not found 错误。

新版实例化的方式统一为：

$drive = new GoogleServiceDrive($client);
$files = $drive->files->listFiles(['q' => "name contains 'report'"])->getFiles();

注意参数传递方式也变了：旧版用关联数组（array('q' => ...)），新版虽然仍然接受，但部分方法（比如 batch()）要求传 GoogleServiceDriveDriveFile 实例而不是数组。

IDE 自动补全可能有点滞后，最靠谱的做法是以 vendor/google/apiclient/src/Service/ 目录结构为准，别太相信那些过时的博客示例。