> ## 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](/ko/packages/laravel-google-sheets/service-account) — 서버 간 통신·자동화 태스크용
    * [OAuth 2.0](/ko/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 인증](/ko/packages/laravel-google-sheets/service-account) — 가장 일반적인 방식
* [OAuth 2.0 인증](/ko/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/)에서 확인할 수 있습니다.


## Related topics

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