> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Sheets API for Laravel

> 在 Laravel 中使用 Google Sheets API v4。流暢且直觀的介面。

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

## 安裝

<Steps>
  <Step title="以 Composer 安裝">
    ```bash theme={null}
    composer require revolution/laravel-google-sheets
    ```
  </Step>

  <Step title="發佈設定檔">
    ```bash theme={null}
    php artisan vendor:publish --tag="google-config"
    ```
  </Step>

  <Step title="啟用 Google API">
    於 [Google Cloud Console](https://console.cloud.google.com/) 啟用以下 API:

    * **Google Sheets API**
    * **Google Drive API**
  </Step>

  <Step title="選擇並設定驗證方式">
    從 3 種方式擇一設定:

    * [Service Account](/zh-TW/packages/laravel-google-sheets/service-account) — 適合伺服器間通訊、自動化任務
    * [OAuth 2.0](/zh-TW/packages/laravel-google-sheets/oauth) — 適合使用者個別存取
    * API 金鑰 — 僅適用於公開資料
  </Step>
</Steps>

## 驗證方式選擇

| 方式                  | 用途         | 使用者操作 | 存取範圍     | 難易度 |
| ------------------- | ---------- | ----- | -------- | --- |
| **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。

```php theme={null}
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。

```php theme={null}
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']
// ]
```

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

Collection 的轉換簡便,後續處理也能靈活對應,因此推薦此方式。

```php theme={null}
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

```php theme={null}
@foreach($values as $value)
  {{ data_get($value, 'name') }}
@endforeach
```

### 使用 A1 表示法

```php theme={null}
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 驗證](/zh-TW/packages/laravel-google-sheets/service-account) — 最常見的方式
* [OAuth 2.0 驗證](/zh-TW/packages/laravel-google-sheets/oauth) — 使用者個別存取
* [laravel-google-sheets](https://github.com/invokable/laravel-google-sheets)
* [Demo 專案](https://github.com/invokable/google-sheets-project) — 支援 Laravel 5.5 至 13 的範例
* [相關套件: Google Search Console API for Laravel](https://github.com/invokable/laravel-google-searchconsole)

## 線上 Demo

實際運作可於 [Laravel Google Sheets Demo](https://sheets.kawax.biz/) 查看。


## Related topics

- [Google Sheets API for Laravel](/en/packages/laravel-google-sheets/index.md)