Installation

Installation Guide

This guide will walk you through installing and setting up the Google Sheets Helper library in your PHP project.

Prerequisites

Before installing the library, ensure you have:

• PHP 7.4 or higher installed
• Composer package manager installed
• Google Cloud Platform account with Sheets API enabled
• Git (optional, for development)

Step 1: Install via Composer

Using Composer Require

composer require reandimo/google-sheets-helper

Using Composer.json

Add to your composer.json:

{
    "require": {
        "reandimo/google-sheets-helper": "^1.2.0"
    }
}

Then run:

composer install

Development Installation

For development or testing:

git clone https://github.com/reandimo/google-sheets-helper.git
cd google-sheets-helper
composer install

Step 2: Google Cloud Platform Setup

1. Create a New Project

1. Go to Google Cloud Console
2. Click "Select a project" → "New Project"
3. Enter a project name and click "Create"

2. Enable Google Sheets API

1. In your project, go to "APIs & Services" → "Library"
2. Search for "Google Sheets API"
3. Click on it and press "Enable"

3. Create Credentials

Option A: Service Account (Recommended for Server Applications)

1. Go to "APIs & Services" → "Credentials"
2. Click "Create Credentials" → "Service Account"
3. Fill in the service account details
4. Click "Create and Continue"
5. Skip role assignment (click "Continue")
6. Click "Done"
7. Click on the created service account
8. Go to "Keys" tab
9. Click "Add Key" → "Create New Key"
10. Choose "JSON" format
11. Download the file and rename it to credentials.json

Option B: OAuth 2.0 (For User Applications)

1. Go to "APIs & Services" → "Credentials"
2. Click "Create Credentials" → "OAuth 2.0 Client IDs"
3. Choose "Desktop application" or "Web application"
4. Fill in the required information
5. Download the file and rename it to credentials.json

Step 3: Project Structure

After installation, your project structure should look like:

your-project/
├── composer.json
├── composer.lock
├── vendor/
│   └── reandimo/
│       └── google-sheets-helper/
│           ├── src/
│           ├── firstauth
│           └── README.md
├── credentials.json
├── token.json (will be generated)
└── your-script.php

Step 4: Generate Authentication Token

Using the Included Script

The library includes a firstauth script for first-time authentication:

php ./vendor/reandimo/google-sheets-helper/firstauth

Follow the interactive prompts:

1. Open the provided URL in your browser
2. Sign in with your Google account
3. Grant permissions to the application
4. Copy the authorization code from the browser
5. Paste the code in the terminal
6. Verify the token file was created

Manual Authentication

If you prefer to handle authentication manually:

<?php
require __DIR__ . '/vendor/autoload.php';

use reandimo\GoogleSheetsApi\Helper;

$sheets = new Helper('path/to/credentials.json', 'path/to/token.json');
$sheets->firstAuth('path/to/token.json');

Step 5: Verify Installation

Create a test script to verify everything is working:

<?php
require __DIR__ . '/vendor/autoload.php';

use reandimo\GoogleSheetsApi\Helper;

try {
    // Set environment variables
    putenv('credentialFilePath=' . __DIR__ . '/credentials.json');
    putenv('tokenPath=' . __DIR__ . '/token.json');
    
    // Create instance
    $sheets = new Helper();
    
    echo "✅ Google Sheets Helper installed successfully!\n";
    echo "✅ Authentication working!\n";
    
} catch (Exception $e) {
    echo "❌ Installation failed: " . $e->getMessage() . "\n";
}

Run the test:

php test-installation.php

Step 6: Share Spreadsheet (Service Account)

If using a service account, you need to share your Google Sheets with the service account email:

1. Find the service account email in your credentials.json file
2. Open your Google Sheet
3. Click "Share" button
4. Add the service account email with "Editor" permissions
5. Remove the "Notify people" checkmark
6. Click "Share"

Troubleshooting Installation

Common Issues

Composer Issues

# Clear composer cache
composer clear-cache

# Update composer
composer self-update

# Install with verbose output
composer install -v

Permission Issues

# Make firstauth executable
chmod +x ./vendor/reandimo/google-sheets-helper/firstauth

# Check file permissions
ls -la credentials.json
ls -la token.json

Google API Issues

• Ensure Google Sheets API is enabled
• Check that credentials file is valid JSON
• Verify service account has proper permissions
• Check API quotas and limits

Verification Commands

# Check PHP version
php -v

# Check Composer
composer --version

# Verify library installation
composer show reandimo/google-sheets-helper

# Check file existence
ls -la credentials.json token.json

Next Steps

After successful installation:

1. Quick Start Guide - Learn basic usage
2. Configuration - Understand library configuration
3. Examples - See practical examples
4. API Reference - Complete method documentation

Support

If you encounter issues during installation:

• Check the Troubleshooting page
• Review Common Issues
• Open an issue on GitHub

---

Ready to get started? Move on to the Quick Start Guide to begin using the library!