README

A comprehensive PHP client library for interacting with the Zoho Analytics API v2, featuring OAuth2 authentication, embed URL generation, data export, and comprehensive testing capabilities.

🚀 Features

• OAuth2 Authentication with automatic token refresh
• Embed URL Generation for dashboards and reports
• Shared URL Creation (login required)
• Private URL Creation (no login required)
• Data Export in multiple formats (CSV, JSON, XML, PDF, etc.)
• Comprehensive Testing Suite with interactive mode
• Environment Variable Support for secure credential management
• Token Management with automatic persistence

📋 Requirements

• PHP 7.4 or higher
• Composer
• Zoho Analytics account
• Zoho OAuth application credentials

🛠️ Installation

1. Clone the repository:

   git clone <repository-url>
   cd zoho-analytics-auth

2. Install dependencies:

   composer install

3. Set up credentials:

   cp .env.example .env
   # Edit .env with your actual credentials

🔧 Configuration

Option 1: Environment Variables (Recommended)

Copy .env.example to .env and fill in your credentials:

ZOHO_CLIENT_ID=your_client_id_here
ZOHO_CLIENT_SECRET=your_client_secret_here
ZOHO_ORG_ID=your_organization_id_here

Option 2: External Files

Create these files in your parent directory:

• ../../ZOHO-CLIENT-ID.txt
• ../../ZOHO-CLIENT-SECRET.txt
• ../../ZOHO-ORG-ID.txt

Getting Zoho Credentials

1. OAuth Application:

   • Visit Zoho API Console
   • Create a new application
   • Note your Client ID and Client Secret

2. Organization ID:

   • Log into Zoho Analytics
   • Go to Settings → Organization
   • Find your Organization ID

🎯 Usage

Quick Start

# Run OAuth authentication flow
php run.php

# Run comprehensive test suite
php test.php

# Interactive testing mode
php test.php interactive

Programmatic Usage

require_once 'vendor/autoload.php';

use Codechap\ZohoAnalyticsApi\Auth;
use Codechap\ZohoAnalyticsApi\Client;

// Initialize authentication
$auth = new Auth();
$auth->set('clientId', 'your_client_id')
     ->set('clientSecret', 'your_client_secret')
     ->set('redirectUri', 'http://localhost:8080')
     ->set('accountsUrl', 'https://accounts.zoho.eu')
     ->set('scopes', [
         'ZohoAnalytics.data.all',
         'ZohoAnalytics.metadata.read',
         'ZohoAnalytics.embed.read',
         'ZohoAnalytics.embed.update'
     ]);

// Create API client
$client = new Client($auth, 'your_org_id');

// Example: Create embed URL
$config = [
    'includeTitle' => true,
    'includeToolBar' => true,
    'validityPeriod' => 3600
];

$result = $client->makeRequest('GET', "/restapi/v2/workspaces/{$workspaceId}/views/{$viewId}/publish/embed", [
    'query' => ['CONFIG' => json_encode($config)]
]);

🧪 Testing Features

Available Tests

1. Workspace Listing - List all accessible workspaces
2. View Listing - List views within a workspace
3. Embed URLs - Create time-limited embed URLs (no login required)
4. Shared URLs - Create shared URLs (login required)
5. Private URLs - Create private URLs (no login required)
6. Data Export - Export data in various formats
7. Token Refresh - Test automatic token renewal

Interactive Mode

php test.php interactive

Menu options:

• [0] List workspaces
• [1] List views in workspace
• [2] Create embed URL
• [3] Create shared URL
• [4] Create private URL (no login)
• [5] Test advanced embed options
• [6] Export data from view
• [7] Test token refresh
• [8] Run full test suite

Full Test Suite

php test.php

Runs all tests automatically and provides comprehensive output including:

• Authentication status
• Available workspaces and views
• Generated URLs for testing
• Export capabilities
• Error diagnostics

🔐 Security

Credential Protection

• Environment Variables: Preferred method for credential storage
• File Exclusion: All credential files are gitignored
• Token Security: Tokens are stored locally and never committed
• No Hardcoding: No credentials are hardcoded in the codebase

OAuth Scopes

The application uses minimal required scopes:

• ZohoAnalytics.data.all - Data access
• ZohoAnalytics.metadata.read - Workspace/view metadata
• ZohoAnalytics.embed.read - Embed URL creation
• ZohoAnalytics.embed.update - Private URL creation

📊 API Endpoints

Supported Endpoints

Endpoint	Purpose	Login Required	Expiry
/publish/embed	Embed URLs	No	Configurable (default: 1h)
/publish	Shared URLs	Yes	Permanent
/publish/privatelink	Private URLs	No	Configurable
/data	Data Export	N/A	N/A

URL Types Comparison

Feature	Embed URL	Shared URL	Private URL
Login Required	❌ No	✅ Yes	❌ No
Expiry Control	✅ Yes	❌ No	✅ Yes
Security	Time-based	Login-based	Key-based
Use Case	Embedding	Sharing	Public access

🚨 Troubleshooting

Permission Issues

If you get SECURITY_NOT_PERMITTED errors:

1. User Permissions:

   • Must have 'Workspace Admin' or 'Workspace Editor' role
   • Must have 'Embed' permissions enabled

2. OAuth Scopes:

   • Ensure all required scopes are granted
   • Re-authenticate if you added new scopes

3. Organization Settings:

   • Enable 'Embed Reports' in Organization permissions
   • Check domain restrictions

Common Issues

• Invalid Credentials: Check environment variables or credential files
• Token Expired: Run php run.php to re-authenticate
• Missing Permissions: Verify user role in Zoho Analytics workspace
• Network Issues: Check firewall settings for OAuth callbacks

📁 Project Structure

zoho-analytics-auth/
├── src/
│   ├── Auth.php          # OAuth2 authentication handler
│   └── Client.php        # API client with request handling
├── test.php              # Comprehensive testing suite
├── run.php               # OAuth authentication flow
├── export.php            # Data export examples
├── .env.example          # Environment configuration template
├── .gitignore            # Security exclusions
└── README.md             # This file

🤝 Contributing

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

📄 License

This project is open source. Please check the license file for details.

🔗 Related Links

• Zoho Analytics API Documentation
• Zoho API Console
• OAuth 2.0 Specification

⚠️ Important Notes

• Never commit credentials to version control
• Use HTTPS for all API requests
• Store tokens securely and never share them
• Test in development before production use
• Monitor API usage to stay within limits

For support or questions, please open an issue in the repository.