Step by Step Guide to Building a TickTick API Integration in PHP

Aug 11, 2024 • 6 minute read

Introduction

Hey there, fellow developer! Ready to supercharge your productivity app with TickTick's powerful API? In this guide, we'll walk through building a sleek PHP integration that'll have you managing tasks like a pro. Let's dive in and make some magic happen!

Prerequisites

Before we start coding, make sure you've got:

A PHP environment (7.4+ recommended)
A TickTick developer account (grab one here)
Composer installed for managing dependencies

We'll be using Guzzle for our HTTP requests, so let's get that set up:

composer require guzzlehttp/guzzle

Authentication

First things first, let's get you authenticated:

Head to the TickTick developer portal and create a new app
Snag your client ID and secret
Implement the OAuth 2.0 flow (don't worry, it's not as scary as it sounds!)

Here's a quick snippet to get you started:

$provider = new \League\OAuth2\Client\Provider\GenericProvider([
    'clientId'                => 'YOUR_CLIENT_ID',
    'clientSecret'            => 'YOUR_CLIENT_SECRET',
    'redirectUri'             => 'YOUR_REDIRECT_URI',
    'urlAuthorize'            => 'https://ticktick.com/oauth/authorize',
    'urlAccessToken'          => 'https://ticktick.com/oauth/token',
    'urlResourceOwnerDetails' => 'https://api.ticktick.com/api/v2/user'
]);

Setting Up the Project

Let's keep it simple with a basic file structure:

ticktick-integration/
├── src/
│   └── TickTickClient.php
├── tests/
├── composer.json
└── .gitignore

Making API Requests

Now for the fun part! Let's create our TickTickClient class:

use GuzzleHttp\Client;

class TickTickClient
{
    private $client;
    private $accessToken;

    public function __construct($accessToken)
    {
        $this->accessToken = $accessToken;
        $this->client = new Client([
            'base_uri' => 'https://api.ticktick.com/api/v2/',
            'headers' => [
                'Authorization' => 'Bearer ' . $this->accessToken,
                'Content-Type' => 'application/json'
            ]
        ]);
    }

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

Core Functionality Implementation

Let's add some methods to our TickTickClient class:

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

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

public function updateTask($taskId, $taskData)
{
    $response = $this->client->put("task/$taskId", ['json' => $taskData]);
    return json_decode($response->getBody(), true);
}

public function deleteTask($taskId)
{
    $response = $this->client->delete("task/$taskId");
    return $response->getStatusCode() === 204;
}

Error Handling and Rate Limiting

Let's add some error handling to our requests:

private function request($method, $endpoint, $options = [])
{
    try {
        $response = $this->client->request($method, $endpoint, $options);
        return json_decode($response->getBody(), true);
    } catch (\GuzzleHttp\Exception\ClientException $e) {
        $response = $e->getResponse();
        $statusCode = $response->getStatusCode();
        $body = json_decode($response->getBody(), true);
        
        if ($statusCode === 429) {
            // Handle rate limiting
            $retryAfter = $response->getHeader('Retry-After')[0] ?? 60;
            sleep($retryAfter);
            return $this->request($method, $endpoint, $options);
        }
        
        throw new \Exception("API Error: " . ($body['error'] ?? 'Unknown error'));
    }
}

Advanced Features (Optional)

Want to level up? Try implementing these:

Project management: getProjects(), createProject(), etc.
Tag operations: getTags(), createTag(), etc.
Attachment handling: addAttachment(), getAttachments(), etc.

Testing the Integration

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

use PHPUnit\Framework\TestCase;

class TickTickClientTest extends TestCase
{
    private $client;

    protected function setUp(): void
    {
        $this->client = new TickTickClient('YOUR_ACCESS_TOKEN');
    }

    public function testGetTasks()
    {
        $tasks = $this->client->getTasks();
        $this->assertIsArray($tasks);
    }

    // Add more tests for other methods
}

Conclusion

And there you have it! You've just built a robust TickTick API integration in PHP. Pretty cool, right? Remember, this is just the beginning – there's so much more you can do with the TickTick API. Keep exploring, keep coding, and most importantly, keep having fun!

Resources

Now go forth and conquer those tasks! Happy coding! 🚀