Download the PHP package asciisd/zoho-v8 without Composer

Zoho CRM Laravel Package (API v8)

A minimal and elegant Laravel wrapper for Zoho CRM API v8. This package provides a clean, Laravel-style interface for interacting with Zoho CRM with model-like classes, automatic token management, and webhook support.

Features

✅ Model-like Interface - Use intuitive model classes like ZohoContact::create(), ZohoLead::find(), etc.
✅ Automatic Token Management - Hybrid cache + database token storage with auto-refresh
✅ Automatic Field Detection - Dynamically fetches and caches all available fields from your CRM
✅ Full CRUD Operations - Create, Read, Update, Delete, Search, Upsert, and more
✅ Webhook Support - Handle Zoho CRM webhooks with Laravel events
✅ Comprehensive Artisan Commands - Easy setup, testing, and data synchronization
✅ Laravel 11+ Support - Built for modern Laravel applications
✅ Minimal Code - Super easy to integrate and use
✅ Multiple Data Centers - Support for US, EU, IN, CN, JP, AU, CA

Requirements

• PHP 8.2 or higher
• Laravel 11.0 or higher
• Zoho CRM Account with API access

Installation

Install the package via Composer:

Publish Configuration

Publish the configuration file and migrations:

Run Migrations

Run the migration to create the OAuth tokens table:

Get Zoho API Credentials

Before configuring the package, you need to create a Zoho API Client to get your OAuth credentials.

Don't have a Zoho account? Sign up at Zoho CRM and choose your preferred data center during registration.

Step 1: Choose Your Data Center

Visit the Zoho API Console and sign in with the correct data center where your Zoho CRM account is registered:

Important: The data center you choose must match where your Zoho CRM data is stored. Check your Zoho CRM URL to determine your data center.

Step 2: Create API Client

1. Sign in to the Zoho API Console
2. Click "Add Client" or "Get Started"
3. Choose "Server-based Applications"

4. Fill in the required details:

   • Client Name: Your application name (e.g., "Laravel Zoho Integration")
   • Homepage URL: Your website URL (e.g., https://yourapp.com)
   • Authorized Redirect URIs: Your callback URL (e.g., https://yourapp.test/zoho/callback or http://localhost:8000/zoho/callback for local development)
5. Click "Create"

Step 3: Copy Credentials

After creating the client, you'll see:

• Client ID - A long string like 1000.XXXXXXXXXXXXX
• Client Secret - Your secret key

Keep these credentials secure! Never commit them to version control.

Step 4: Configure OAuth Scopes

When setting up authentication, the package will request these scopes by default:

For additional features, you may need:

• ZohoCRM.org.ALL - Organization information
• ZohoCRM.bulk.ALL - Bulk operations
• ZohoCRM.notifications.ALL - Webhooks and notifications

Configure Environment Variables

Add the credentials to your .env file:

For Local Development:

Make sure the redirect URI matches exactly what you entered in the Zoho API Console (including protocol and port).

Setup Checklist

Before running the setup command, ensure:

• [ ] You have a Zoho CRM account
• [ ] You've signed in to the correct data center in API Console
• [ ] You've created a Server-based Application client
• [ ] Your ZOHO_CLIENT_ID is set in .env
• [ ] Your ZOHO_CLIENT_SECRET is set in .env
• [ ] Your ZOHO_REDIRECT_URI exactly matches the API Console
• [ ] Your ZOHO_DATA_CENTER matches your CRM URL
• [ ] You've run php artisan migrate

Quick Start

1. Authentication Setup

Run the setup command to authenticate with Zoho CRM:

This interactive command will:

1. Generate an authorization URL
2. Accept your grant token/code
3. Generate and store access & refresh tokens
4. Test the connection

2. Basic Usage

Create a Contact

Find a Contact

Update a Contact

Delete a Contact

Get All Contacts

Search Contacts

Upsert (Create or Update)

Available Modules

The package provides model classes for all major Zoho CRM modules:

• ZohoContact - Contacts module
• ZohoAccount - Accounts module
• ZohoLead - Leads module
• ZohoDeal - Deals module
• ZohoTask - Tasks module
• ZohoEvent - Events module
• ZohoCall - Calls module
• ZohoNote - Notes module
• ZohoProduct - Products module
• ZohoInvoice - Invoices module

All modules extend the base ZohoModel class and support the same methods.

Using the Facade

You can also use the Zoho facade for a fluent interface:

Advanced Usage

Get Related Records

Update Multiple Records

Delete Multiple Records

Get Deleted Records

Convert Lead

Get Record Count

Clone a Record

Field Management

The package automatically fetches all available field names for each module from the Zoho CRM API and caches them for improved performance. This ensures you always get all fields without needing to manually specify them.

Get Field Metadata

Fetch complete field metadata including field types, properties, and configurations:

Specify Custom Fields

You can override the automatic field fetching by specifying custom fields for individual requests:

Clear Field Cache

If you've added new custom fields to your Zoho CRM or need to refresh the cached field names:

Note: Field names are automatically cached after the first request to each module. The cache persists for the duration of the application runtime. If you modify fields in your Zoho CRM (add/remove custom fields), you should clear the cache to fetch the updated field list.

Artisan Commands

Setup Authentication

Interactive OAuth setup wizard.

Authentication Management

Test CRUD Operations

Sync Data

Token Management

Webhook Integration

Setup Webhook in Zoho CRM

1. Go to Setup → Developer Space → Webhooks
2. Create a new webhook
3. Set URL to: https://your-domain.com/zoho/webhook
4. Select the modules and events you want to track

Handle Webhook Events

Listen to webhook events in your application:

Webhook Security

Add a webhook secret to your .env file for signature verification:

Model Synchronization

The package provides a powerful trait-based system to automatically sync any Laravel model with any Zoho CRM module. When you create, update, or delete a model in your Laravel application, it will automatically sync with Zoho CRM in the background using Laravel queues.

Features

✅ Automatic Syncing - Sync on create, update, and delete events
✅ Queued Processing - Non-blocking background sync with Laravel queues
✅ Automatic Retries - 3 automatic retries with exponential backoff
✅ Field Mapping - Flexible field mapping between Laravel models and Zoho fields
✅ Polymorphic Storage - Store Zoho record IDs using polymorphic relationships
✅ Conditional Sync - Add custom logic to control when syncing occurs
✅ Manual Control - Temporarily disable syncing or trigger manual syncs

Installation

Publish and run the sync migration:

This will create the zoho_syncs table to store the relationship between your Laravel models and Zoho records.

Basic Usage

Add the SyncsWithZoho trait to any model and define the getZohoModule() method:

Now, whenever you create, update, or delete a user, it will automatically sync with Zoho CRM Contacts:

Field Mapping

By default, the trait will sync all fillable attributes using the same field names. To customize field mapping between your Laravel model and Zoho fields:

DemoAccount to Lead Example

Here's how to sync a DemoAccount model with Zoho CRM Leads:

Conditional Syncing

Add custom logic to control when a model should sync:

Temporarily Disable Syncing

Use the withoutZohoSync() method to temporarily disable syncing:

Manual Sync

Trigger a manual sync immediately (not queued):

Accessing Zoho Record ID

Get the Zoho CRM record ID for any synced model:

Configuration

Configure sync behavior in config/zoho.php:

Environment Variables

Add these to your .env file:

How It Works

1. Model Event: When you create/update/delete a model with the SyncsWithZoho trait
2. Job Dispatch: A SyncModelToZoho job is dispatched to the queue
3. Field Transform: Model data is transformed using your field mapping
4. API Call: The job makes the appropriate Zoho CRM API call
5. Record Storage: The Zoho record ID is stored in the zoho_syncs table
6. Retry Logic: If the API call fails, it retries 3 times with exponential backoff
7. Logging: Success and failures are logged for monitoring

Queue Workers

Make sure you have queue workers running to process sync jobs:

Error Handling

Failed syncs are automatically retried 3 times. After all retries fail, errors are logged to your application log:

Configuration

The package configuration file (config/zoho.php) includes:

Error Handling

The package provides custom exceptions for better error handling:

Data Centers

The package supports all Zoho CRM data centers:

• US - United States (https://www.zohoapis.com)
• EU - Europe (https://www.zohoapis.eu)
• IN - India (https://www.zohoapis.in)
• CN - China (https://www.zohoapis.com.cn)
• JP - Japan (https://www.zohoapis.jp)
• AU - Australia (https://www.zohoapis.com.au)
• CA - Canada (https://www.zohoapis.ca)

Set your data center in .env:

Token Storage

The package supports three token storage methods:

1. Cache Only - Fast but volatile
2. Database Only - Persistent but slower
3. Both (Recommended) - Cache with database fallback

Configure in .env:

Testing

Troubleshooting

Wrong Data Center Error

Error: Invalid OAuth credentials or Authentication failed

Solution: Make sure your ZOHO_DATA_CENTER in .env matches where your Zoho CRM account is registered:

The API Console you use to create credentials must match your data center.

Redirect URI Mismatch

Error: redirect_uri_mismatch during OAuth setup

Solution:

1. Check that ZOHO_REDIRECT_URI in .env exactly matches what you entered in Zoho API Console
2. Include the protocol (http:// or https://)
3. Include the port if using non-standard ports (:8000, :3000, etc.)
4. No trailing slashes unless you added them in the API Console

Token Expired Error

If you get a token expired error, refresh the token:

Invalid Credentials

Make sure your .env file has the correct credentials:

If credentials are invalid:

1. Verify ZOHO_CLIENT_ID and ZOHO_CLIENT_SECRET from API Console
2. Check that you're using the correct data center
3. Run php artisan zoho:setup to re-authenticate

Grant Token Expired

Error: invalid_code or Grant token has expired

Solution: Grant tokens from Zoho expire quickly (usually within 2-3 minutes). When running php artisan zoho:setup:

1. Generate the authorization URL
2. Immediately open it in your browser
3. Copy the code from the redirect URL
4. Quickly paste it into the terminal

If it expires, just run php artisan zoho:setup again.

Rate Limit Exceeded

Zoho CRM has API rate limits. The package will throw a ZohoApiException with code 429. Implement retry logic with exponential backoff.

Rate Limits:

• 100 API calls per minute per user
• 5,000 API calls per day (varies by plan)

Connection Timeout

Error: Connection timed out or Failed to connect

Solution:

1. Check your internet connection
2. Verify your firewall allows outbound HTTPS connections
3. Check if Zoho services are down: Zoho Status
4. Try a different data center if you have a regional account

Cache Issues

If tokens aren't refreshing properly:

FAQ

How do I know which data center I'm in?

Check the URL you use to access Zoho CRM:

• crm.zoho.com = US
• crm.zoho.eu = EU
• crm.zoho.in = IN
• And so on...

Can I use the same credentials for multiple environments?

Yes, but you should:

1. Create separate API clients for development and production
2. Use different redirect URIs for each environment
3. Store credentials separately in each .env file

What scopes do I need?

For basic CRUD operations:

For advanced features (webhooks, bulk operations):

The zoho:setup command uses the default scopes, but you can specify custom scopes when generating the authorization URL.

How long do tokens last?

• Access Token: 1 hour (auto-refreshed by the package)
• Refresh Token: No expiration (unless revoked)
• Grant Token: 2-3 minutes (use immediately)

Can I test without SSL locally?

Yes, for local development you can use:

However, for production, always use HTTPS.

Do I need to create a route for the redirect URI?

No, the package doesn't require an actual route at the redirect URI. The redirect URI is only used during the OAuth setup process to receive the authorization code, which you'll copy manually from the browser's address bar.

If you want to automate this, you can create a route that captures the code and displays it, but it's not required for the package to work.

How do I switch data centers?

1. Update ZOHO_DATA_CENTER in .env
2. Clear tokens: php artisan zoho:token:refresh --clear-cache
3. Re-authenticate: php artisan zoho:setup

Note: Your data must exist in the target data center.

Can I use this package with Zoho Sandbox?

Yes! Set in your .env:

Then authenticate with your sandbox credentials.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Security

If you discover any security-related issues, please email [email protected] instead of using the issue tracker.

Credits

• Ascii SD
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

Support

For support, please open an issue on GitHub or contact [email protected].

Changelog

Please see CHANGELOG for more information on what has changed recently.