Skip to content

FAQ

Jump to bottom
Renan Diaz edited this page Aug 22, 2025 · 1 revision

Frequently Asked Questions (FAQ)

Common questions and answers about the Google Sheets Helper library.

🔧 General Questions

What is Google Sheets Helper?

Google Sheets Helper is a PHP library that simplifies working with the Google Sheets API. It provides an easy-to-use interface for common operations like reading, writing, updating, and managing Google Spreadsheets.

What PHP version do I need?

The library requires PHP 7.4 or higher. This ensures compatibility with modern PHP features and the Google API client library.

Is this library free to use?

Yes! The library is open source and released under the MIT License, which means you can use it freely in both personal and commercial projects.

How does this compare to the official Google API client?

The official Google API client provides low-level access to all Google APIs. This helper library wraps that client to provide:

  • Simplified method names
  • Built-in error handling
  • Common operation shortcuts
  • Better developer experience

You can still access the underlying Google client when you need advanced features.

📦 Installation & Setup

How do I install the library?

composer require reandimo/google-sheets-helper

I'm getting a "Class not found" error. What's wrong?

Make sure you have:

  1. Run composer install or composer update
  2. Included the autoloader: require __DIR__ . '/vendor/autoload.php';
  3. Used the correct namespace: use reandimo\GoogleSheetsApi\Helper;

Where do I get my Google API credentials?

  1. Go to Google Cloud Console
  2. Create a new project or select existing one
  3. Enable the Google Sheets API
  4. Create credentials (Service Account recommended)
  5. Download the JSON file and rename it to credentials.json

What's the difference between Service Account and OAuth 2.0?

  • Service Account: Best for server applications, automated scripts, and when you don't need user interaction
  • OAuth 2.0: Best for user-facing applications where users need to authorize access to their own sheets

For most use cases, Service Account is recommended.

🔐 Authentication Issues

I'm getting "No credential file" error

Check that:

  1. Your credentials.json file exists and is readable
  2. The file path is correct (absolute or relative)
  3. File permissions allow PHP to read the file

"Token file does not exist" error

You need to generate a token file first:

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

Follow the interactive prompts to authenticate.

"You have to run 'firstauth'" error

This means your token has expired. Run the firstauth script again:

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

Authentication worked yesterday but not today

Google API tokens can expire. Try:

  1. Running firstauth again
  2. Checking if your credentials file is still valid
  3. Verifying your Google Cloud project still has the API enabled

📊 Working with Data

How do I find my spreadsheet ID?

The spreadsheet ID is in the URL when you open your Google Sheet:

https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit#gid=0

The long string after /d/ and before /edit is your spreadsheet ID.

What's the difference between "RAW" and "USER_ENTERED"?

  • RAW: Values are inserted exactly as provided (e.g., "=SUM(A1:A10)" stays as text)
  • USER_ENTERED: Values are parsed as if typed by a user (e.g., "=SUM(A1:A10)" becomes a formula)

How do I leave a cell empty when appending data?

Use Google_Model::NULL_VALUE:

use Google_Model;

$sheets->appendSingleRow([
    'John Doe',
    'john@example.com',
    Google_Model::NULL_VALUE, // Empty cell
    'Developer'
]);

Can I work with multiple spreadsheets at once?

Yes! Create multiple instances:

$sheet1 = new Helper();
$sheet1->setSpreadsheetId('spreadsheet-1-id');

$sheet2 = new Helper();
$sheet2->setSpreadsheetId('spreadsheet-2-id');

How do I get all data from a column?

Use the column notation:

$sheets->setSpreadsheetRange('A:A'); // Whole column A
$values = $sheets->get();

How do I get all data from a row?

Use the row notation:

$sheets->setSpreadsheetRange('1:1'); // Whole row 1
$values = $sheets->get();

🚨 Common Errors

"There's no ID spreadsheet set"

You need to set the spreadsheet ID first:

$sheets->setSpreadsheetId('your-spreadsheet-id');

"There's no worksheet range set"

You need to set the range before operations:

$sheets->setSpreadsheetRange('A1:Z100');

"There's no worksheet name set"

You need to set the worksheet name:

$sheets->setWorksheetName('Sheet1');

"Worksheet with name 'X' was not found"

Check that:

  1. The worksheet name is exactly correct (case-sensitive)
  2. The worksheet exists in your spreadsheet
  3. Your service account has access to the spreadsheet

"No data found in range"

This usually means:

  1. The range is empty
  2. The range is outside your data
  3. The worksheet name is incorrect

"Google API Error: Quota exceeded"

You've hit Google's API rate limits. Try:

  1. Implementing delays between requests
  2. Using batch operations
  3. Checking your Google Cloud quotas
  4. Waiting before making more requests

🎯 Best Practices

How should I handle errors?

Always use try-catch blocks:

try {
    $values = $sheets->get();
    // Process data
} catch (Exception $e) {
    // Handle error appropriately
    error_log("Google Sheets error: " . $e->getMessage());
}

How can I improve performance?

  1. Batch operations: Use append() instead of multiple appendSingleRow() calls
  2. Limit ranges: Only read/write the data you need
  3. Cache data: Store frequently accessed data locally
  4. Rate limiting: Add delays between API calls

What's the best way to store credentials?

Use environment variables:

putenv('credentialFilePath=path/to/credentials.json');
putenv('tokenPath=path/to/token.json');

This keeps credentials out of your code and makes them easier to manage.

How do I handle large datasets?

  1. Process in chunks: Read/write data in smaller ranges
  2. Use pagination: Process data page by page
  3. Background processing: Use queues for large operations
  4. Monitor quotas: Keep track of API usage

🔧 Advanced Usage

Can I access the underlying Google API client?

Yes! Use getService() or getClient():

$service = $sheets->getService();
$client = $sheets->getClient();

// Access advanced Google API methods

How do I work with formulas?

Set the value input option to "USER_ENTERED":

$sheets->setValueInputOption('USER_ENTERED');
$sheets->updateSingleCell('A1', '=SUM(B1:B10)');

Can I format cells beyond background color?

The helper library provides basic formatting. For advanced formatting, access the underlying service:

$service = $sheets->getService();
// Use Google's advanced formatting methods

How do I handle different data types?

The library automatically handles:

  • Strings
  • Numbers
  • Dates (as strings)
  • Formulas (with USER_ENTERED option)
  • Empty cells (with NULL_VALUE)

🆘 Getting Help

Where can I get help?

  1. GitHub Issues: Report bugs or request features
  2. Stack Overflow: Tag questions with google-sheets-api and php
  3. Documentation: Check the Google Sheets API docs

How do I report a bug?

  1. Check if it's already reported in GitHub Issues
  2. Create a new issue with:
    • Clear description of the problem
    • Steps to reproduce
    • Error messages
    • Your environment (PHP version, library version)

Can I contribute to the library?

Absolutely! We welcome contributions:

  1. Fork the repository
  2. Make your changes
  3. Add tests if applicable
  4. Submit a pull request

Is there a changelog?

Check the GitHub releases for version history and changes.

📚 Additional Resources

Official Documentation

Related Libraries

Community

Still have questions? Open an issue on GitHub or ask on Stack Overflow with the tags google-sheets-api and php!

Clone this wiki locally