> ## 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 クライアントライブラリの複雑性を隠蔽し、直感的で表現力豊かなメソッドチェーン API を提供します。

## 特徴

* **複数の認証方式対応** — OAuth 2.0（ユーザー個別アクセス）、Service Account（サーバー間通信）、API キー（公開データ）
* **流暢な API** — メソッドチェーンで直感的にデータ操作
* **Laravel Collection 統合** — Google Sheets のデータを Laravel Collection に変換。配列処理が簡単
* **拡張性** — マクロシステムでファサードにカスタムメソッド追加可能
* **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](/jp/packages/laravel-google-sheets/service-account) — サーバー間通信・自動化タスク向け
    * [OAuth 2.0](/jp/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から取得してください。

### サービスアカウント

サービスアカウント認証を使用する場合、トークンの設定は不要です。

```php theme={null}
use Revolution\Google\Sheets\Facades\Sheets;

// サービスアカウント認証は設定時に自動的に行われます
$values = Sheets::spreadsheet('spreadsheetId')->sheet('Sheet 1')->all();
// [
//   ['id', 'name', 'mail'],
//   ['1', 'name1', 'mail1'],
//   ['2', 'name2', 'mail2']
// ]
```

### OAuth

OAuth認証を使用する場合、ユーザーのアクセストークンを設定する必要があります。

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

### ヘッダーをキーとしてシートの値を取得する（推奨）

コレクションの変換は簡単で、その後の処理も柔軟に対応できるため、この方法をお勧めします。

```php theme={null}
use Revolution\Google\Sheets\Facades\Sheets;

// get() は Laravel コレクションを返します
$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コレクションを使用して取得後に処理/フィルタリングする方が簡単な場合が多いです。

## 次のステップ

* [Service Account 認証](/jp/packages/laravel-google-sheets/service-account) — 最も一般的な方式
* [OAuth 2.0 認証](/jp/packages/laravel-google-sheets/oauth) — ユーザー個別アクセス
* [laravel-google-sheets](https://github.com/invokable/laravel-google-sheets)
* [デモプロジェクト](https://github.com/invokable/google-sheets-project) — Laravel 5.5 から 13 まで対応例
* [関連パッケージ: Google Search Console API for Laravel](https://github.com/invokable/laravel-google-searchconsole)

## ライブデモ

実際の動作は [Laravel Google Sheets デモ](https://sheets.kawax.biz/) で確認できます。