Google Sheets API for Laravel

一个面向 Laravel 的 Google Sheets API v4 扩展包。它屏蔽了 Google PHP 客户端库的复杂性，提供了直观且富有表现力的方法链 API。

特性

支持多种认证方式 —— OAuth 2.0（面向单个用户的访问）、Service Account（服务器间通信）、API key（公开数据）
流畅的 API —— 通过方法链直观地操作数据
与 Laravel Collection 集成 —— 将 Google Sheets 的数据转换为 Laravel Collection，方便进行数组处理
可扩展 —— 通过 macro 系统可以为 facade 添加自定义方法
与 Google Drive 集成 —— 支持电子表格的管理与列表查询

常见使用场景

用户仪表盘 —— 展示与操作 Google Sheets 中的数据
数据导入 / 导出 —— 在 Laravel 应用与 Google Sheets 之间迁移大量数据
自动生成报表 —— 通过程序生成和更新报表
多用户应用 —— 让用户各自管理自己的 Google Sheets

设计理念

本包的主要目的是 从 Google Sheets 读取数据。它并不鼓励在读取前指定复杂条件，而是先将全部数据取回作为 Laravel Collection，然后在 Laravel 一侧进行后续处理。

系统要求

PHP >= 8.3
Laravel >= 12.0

安装

用 Composer 安装

composer require revolution/laravel-google-sheets

发布配置文件

php artisan vendor:publish --tag="google-config"

启用 Google API

在 Google Cloud Console 中启用以下 API：

Google Sheets API
Google Drive API

选择并配置认证方式

从下列三种方式中选择：

Service Account —— 面向服务器间通信 / 自动化任务
OAuth 2.0 —— 面向单个用户的访问
API key —— 仅公开数据

认证方式对比

方式	用途	用户操作	访问范围	难度
Service Account	服务器间通信 / 自动化	不需要	已共享的电子表格	中
OAuth 2.0	面向用户的应用	需要同意	用户各自的表格	高
API key	仅公开数据	不需要	只能访问公开电子表格	低

基本用法

以下面的电子表格结构为例。

id	name	mail
1	name1	mail1
2	name2	mail2

电子表格 URL: https://docs.google.com/spreadsheets/d/{spreadsheetID}/... 请从 URL 中取出 spreadsheetId。

使用 Service Account

使用 Service Account 认证时，不需要额外设置 token。

use Revolution\Google\Sheets\Facades\Sheets;

// Service Account 认证会在初始化时自动完成
$values = Sheets::spreadsheet('spreadsheetId')->sheet('Sheet 1')->all();
// [
//   ['id', 'name', 'mail'],
//   ['1', 'name1', 'mail1'],
//   ['2', 'name2', 'mail2']
// ]

使用 OAuth

使用 OAuth 认证时，需要设置用户的 access token。

use Revolution\Google\Sheets\Facades\Sheets;

$user = $request->user();

$token = [
    'access_token'  => $user->access_token,
    'refresh_token' => $user->refresh_token,
    'expires_in'    => $user->expires_in,
    'created'       => $user->updated_at->getTimestamp(),
];

// all() 返回数组
$values = Sheets::setAccessToken($token)->spreadsheet('spreadsheetId')->sheet('Sheet 1')->all();
// [
//   ['id', 'name', 'mail'],
//   ['1', 'name1', 'mail1'],
//   ['2', 'name1', 'mail2']
// ]

用表头作为 key 获取数据（推荐）

Collection 的转换比较方便，后续处理也更灵活，因此推荐这种方式。

use Revolution\Google\Sheets\Facades\Sheets;

// get() 返回 Laravel Collection
$rows = Sheets::sheet('Sheet 1')->get();

$header = $rows->pull(0);
$values = Sheets::collection(header: $header, rows: $rows);
$values->toArray()
// [
//   ['id' => '1', 'name' => 'name1', 'mail' => 'mail1'],
//   ['id' => '2', 'name' => 'name2', 'mail' => 'mail2']
// ]

Blade

@foreach($values as $value)
  {{ data_get($value, 'name') }}
@endforeach

使用 A1 表示法

use Revolution\Google\Sheets\Facades\Sheets;

$values = Sheets::sheet('Sheet 1')->range('A1:B2')->all();
// [
//   ['id', 'name'],
//   ['1', 'name1'],
// ]

关于 A1 表示法

A1 表示法是 Google 电子表格中指定单元格或范围的标准方式（例如 “A1”、“A1:B2”）。

“A1” 指的是 A 列第 1 行的单元格。
“A1:B2” 指的是从 A1 到 B2 的矩形范围。
“A:B” 指的是 A 列和 B 列的全部行。

如果你对 A1 表示法不太熟悉，或者范围是动态的、比较复杂，通常先获取全部数据、再在 Laravel 中通过 Collection 处理/过滤，会更简单。

后续步骤

Service Account 认证 —— 最常见的方式
OAuth 2.0 认证 —— 面向单个用户的访问
laravel-google-sheets
示例项目 —— 覆盖 Laravel 5.5 到 13 的示例
相关包: Google Search Console API for Laravel

在线演示

你可以通过 Laravel Google Sheets Demo 查看实际运行效果。

GitHub Copilot

SDK

AI SDK

VOICEVOX

启动套件

Feed 与 RSS

中间件

特性

常见使用场景

设计理念

系统要求

安装

认证方式对比

基本用法

使用 Service Account

使用 OAuth

用表头作为 key 获取数据（推荐）

使用 A1 表示法

关于 A1 表示法

后续步骤

在线演示

​特性

​常见使用场景

​设计理念

​系统要求

​安装

​认证方式对比

​基本用法

​使用 Service Account

​使用 OAuth

​用表头作为 key 获取数据（推荐）

​使用 A1 表示法

​关于 A1 表示法

​后续步骤

​在线演示

特性

常见使用场景

设计理念

系统要求

安装

认证方式对比

基本用法

使用 Service Account

使用 OAuth

用表头作为 key 获取数据（推荐）

使用 A1 表示法

关于 A1 表示法

后续步骤

在线演示