Google Sheets API for Laravel

Google Sheets API v4 的 Laravel 專用套件。隱藏了 Google PHP client library 的複雜性,提供直觀且富有表現力的 method chain API。

特色

支援多種驗證方式 — OAuth 2.0(使用者個別存取)、Service Account(伺服器間通訊)、API 金鑰(公開資料)
流暢的 API — 以 method chain 直觀地操作資料
整合 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

選擇並設定驗證方式

從 3 種方式擇一設定:

Service Account — 適合伺服器間通訊、自動化任務
OAuth 2.0 — 適合使用者個別存取
API 金鑰 — 僅適用於公開資料

驗證方式選擇

方式	用途	使用者操作	存取範圍	難易度
Service Account	伺服器間通訊、自動化	不需要	已共用的試算表	中
OAuth 2.0	使用者導向應用程式	需要同意	使用者個別試算表	高
API 金鑰	僅公開資料	不需要	僅限公開試算表	低

基本用法

考慮以下試算表結構的範例。

id	name	mail
1	name1	mail1
2	name2	mail2

Spreadsheet URL: https://docs.google.com/spreadsheets/d/{spreadsheetID}/... spreadsheetId 請從 URL 取得。

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']
// ]

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
Demo 專案 — 支援 Laravel 5.5 至 13 的範例
相關套件: Google Search Console API for Laravel

線上 Demo

實際運作可於 Laravel Google Sheets Demo 查看。

GitHub Copilot

SDK

AI SDK

VOICEVOX

入門套件

Feed 與 RSS

中介層

特色

常見使用情境

設計理念

系統需求

安裝

驗證方式選擇

基本用法

Service Account

OAuth

以 header 為 key 取得工作表值(建議)

使用 A1 表示法

關於 A1 表示法

下一步

線上 Demo

​特色

​常見使用情境

​設計理念

​系統需求

​安裝

​驗證方式選擇

​基本用法

​Service Account

​OAuth

​以 header 為 key 取得工作表值(建議)

​使用 A1 表示法

​關於 A1 表示法

​下一步

​線上 Demo

特色

常見使用情境

設計理念

系統需求

安裝

驗證方式選擇

基本用法

Service Account

OAuth

以 header 為 key 取得工作表值(建議)

使用 A1 表示法

關於 A1 表示法

下一步

線上 Demo