Step by Step Guide to Building an Agile CRM API Integration in PHP

Aug 17, 2024 • 7 minute read

Introduction

Hey there, fellow developer! Ready to supercharge your PHP application with some Agile CRM goodness? You're in the right place. We're going to walk through building an integration with the Agile CRM API, giving your app the power to manage contacts, deals, and tasks like a pro. Let's dive in!

Prerequisites

Before we get our hands dirty, make sure you've got:

A PHP environment up and running (PHP 7.4+ recommended)
An Agile CRM account with API credentials in hand
A burning desire to code something awesome

Setting up the project

First things first, let's get our project off the ground:

mkdir agile-crm-integration
cd agile-crm-integration
composer init
composer require guzzlehttp/guzzle

We're using Guzzle to handle our HTTP requests because, let's face it, it makes our lives so much easier.

Authentication

Alright, security first! Let's create a base API client class to handle our authentication:

<?php

use GuzzleHttp\Client;

class AgileCRMClient
{
    private $client;
    private $apiKey;
    private $domain;

    public function __construct($domain, $email, $apiKey)
    {
        $this->domain = $domain;
        $this->apiKey = $apiKey;
        $this->client = new Client([
            'base_uri' => "https://{$domain}.agilecrm.com/dev/api/",
            'headers' => [
                'Accept' => 'application/json',
                'Content-Type' => 'application/json',
                'Authorization' => 'Basic ' . base64_encode($email . ':' . $apiKey)
            ]
        ]);
    }

    // We'll add more methods here soon!
}

Core API Functionality

Now for the fun part! Let's add some methods to interact with contacts, deals, and tasks.

Contacts

public function getContacts()
{
    $response = $this->client->get('contacts');
    return json_decode($response->getBody(), true);
}

public function createContact($data)
{
    $response = $this->client->post('contacts', ['json' => $data]);
    return json_decode($response->getBody(), true);
}

public function updateContact($id, $data)
{
    $response = $this->client->put("contacts/{$id}", ['json' => $data]);
    return json_decode($response->getBody(), true);
}

Deals

public function getDeals()
{
    $response = $this->client->get('opportunity');
    return json_decode($response->getBody(), true);
}

public function createDeal($data)
{
    $response = $this->client->post('opportunity', ['json' => $data]);
    return json_decode($response->getBody(), true);
}

public function updateDealStatus($id, $status)
{
    $response = $this->client->put("opportunity/partial-update", ['json' => [
        'id' => $id,
        'milestone' => $status
    ]]);
    return json_decode($response->getBody(), true);
}

Tasks

public function getTasks()
{
    $response = $this->client->get('tasks');
    return json_decode($response->getBody(), true);
}

public function createTask($data)
{
    $response = $this->client->post('tasks', ['json' => $data]);
    return json_decode($response->getBody(), true);
}

public function completeTask($id)
{
    $response = $this->client->post("tasks/complete/{$id}");
    return json_decode($response->getBody(), true);
}

Error Handling

Let's not forget about error handling. Wrap your API calls in try-catch blocks:

try {
    $contacts = $client->getContacts();
} catch (\GuzzleHttp\Exception\RequestException $e) {
    // Handle API errors here
    echo "Oops! " . $e->getMessage();
}

Data Synchronization

For keeping things in sync and respecting rate limits, consider implementing a queue system. Here's a simple example:

class SyncQueue
{
    private $queue = [];

    public function add($method, $params)
    {
        $this->queue[] = ['method' => $method, 'params' => $params];
    }

    public function process($client)
    {
        foreach ($this->queue as $item) {
            call_user_func_array([$client, $item['method']], $item['params']);
            sleep(1); // Respect rate limits
        }
        $this->queue = [];
    }
}

Testing

Don't forget to test your integration! Here's a quick PHPUnit test to get you started:

use PHPUnit\Framework\TestCase;

class AgileCRMClientTest extends TestCase
{
    private $client;

    protected function setUp(): void
    {
        $this->client = new AgileCRMClient('your-domain', 'your-email', 'your-api-key');
    }

    public function testGetContacts()
    {
        $contacts = $this->client->getContacts();
        $this->assertIsArray($contacts);
    }
}

Best Practices

Keep your API credentials secure (use environment variables!)
Implement proper error logging
Use meaningful variable and method names
Comment your code (your future self will thank you)

Conclusion

And there you have it! You've just built a solid foundation for integrating Agile CRM into your PHP application. Remember, this is just the beginning. There's so much more you can do with the Agile CRM API, so don't be afraid to explore and expand on what we've covered here.

Keep coding, keep learning, and most importantly, have fun with it!

Resources

Now go forth and build something amazing! 🚀