README

Fireboost PHP SDK is a PHP library for interacting with the Fireboost API. This SDK provides functionalities to manage cache operations, including saving, reading, and deleting cached data with automatic authentication handling.

Installation

You can install the Fireboost PHP SDK via Composer:

composer require fireboostio/fireboost-php-sdk

Usage

Below are examples demonstrating how to use the SDK:

Basic Usage

<?php
use FireboostIO\SDK\CacheManager;
use FireboostIO\SDK\Adapter\SessionAdapter;

// Create a CacheManager instance with default SessionAdapter
$apiKey = 'your-api-key'; // Or set FIREBOOST_API_KEY environment variable
$cacheManager = new CacheManager(new SessionAdapter(), $apiKey);

// Save data to cache
$cacheKey = 'example/key';
$content = ['name' => 'Example', 'value' => 123];
$isPublic = true; // Set to true for publicly accessible cache
$response = $cacheManager->saveCache($cacheKey, $content, $isPublic);

// Read data from cache
$data = $cacheManager->readCache($cacheKey);

// Read public data (no authentication required)
$publicData = $cacheManager->readPublicCache($cacheKey);

// Delete data from cache
$cacheManager->deleteCache($cacheKey);

// Delete all data from cache
$cacheManager->deleteAllCache();

// Get cache usage statistics
$stats = $cacheManager->getStatistics();

// Get all cache entries with cursor pagination
$cursor = null;
$allEntries = [];

do {
    $response = $cacheManager->getAllCache($cursor);

    // Process the current page of results
    foreach ($response->getKeys() as $entry) {
        $allEntries[] = $entry;
        // Process each entry as needed
    }

    // Get the cursor for the next page
    $cursor = $response->getCursor();

    // Continue until there's no more cursor (end of pagination)
} while ($cursor !== null);

Pagination with getAllCache

The getAllCache() method supports cursor-based pagination to efficiently retrieve large sets of cache entries:

<?php
use FireboostIO\SDK\CacheManager;

$cacheManager = new CacheManager();

// Initial request with no cursor
$response = $cacheManager->getAllCache();

// Display the first page of results
foreach ($response->getKeys() as $entry) {
    echo "Key: " . $entry->getCacheKey() . ", Value: " . json_encode($entry->getValue()) . "\n";
}

// Check if there are more pages
if ($response->getCursor() !== null) {
    // Fetch the next page using the cursor
    $nextPageResponse = $cacheManager->getAllCache($response->getCursor());

    // Process next page...
}

Using Different Storage Adapters

The SDK supports multiple storage adapters for JWT tokens:

Session Adapter (Default)

use FireboostIO\SDK\Adapter\SessionAdapter;

$adapter = new SessionAdapter();
// Or with custom session keys:
$adapter = new SessionAdapter('custom_token_key', 'custom_login_attempts_key');

Redis Adapter

use FireboostIO\SDK\Adapter\RedisAdapter;

// With default Redis connection
$adapter = new RedisAdapter();

// Or with custom Redis connection
$redis = new \Redis();
$redis->connect('redis-server.example.com', 6379);
$adapter = new RedisAdapter($redis, 'custom:token:key:', 'custom:login:attempts:', 3600);

Database Adapter

use FireboostIO\SDK\Adapter\DatabaseAdapter;

$pdo = new PDO('mysql:host=localhost;dbname=myapp', 'username', 'password');
$adapter = new DatabaseAdapter($pdo, 'custom_tokens_table', 'user_identifier');

File Adapter

use FireboostIO\SDK\Adapter\FileAdapter;

// With default system temp directory
$adapter = new FileAdapter();

// Or with custom storage directory
$adapter = new FileAdapter('/path/to/storage', 'token_filename', 'login_attempts_filename');

WordPress Transient Adapter

use FireboostIO\SDK\Adapter\WPTransientAdapter;

// With default settings (1 hour token TTL, 24 hour login attempt TTL)
$adapter = new WPTransientAdapter();

// Or with custom settings
$adapter = new WPTransientAdapter(
    'custom_token_key',           // Custom transient key for token
    'custom_login_attempts_key',  // Custom transient key for login attempts
    7200,                         // Token TTL: 2 hours
    43200                         // Login attempt TTL: 12 hours
);

Perfect for WordPress plugins and themes - uses WordPress transients for persistent storage across REST API calls.

Creating Your Own Custom Adapter

You can create your own custom adapter by implementing the TokenStorageAdapterInterface. This allows you to store JWT tokens and login attempt counters in any storage system of your choice.

<?php

namespace YourNamespace;

use FireboostIO\SDK\Adapter\TokenStorageAdapterInterface;

class CustomAdapter implements TokenStorageAdapterInterface
{
    // Your storage mechanism (e.g., a custom database connection, API, etc.)
    private $storage;

    public function __construct($storage)
    {
        $this->storage = $storage;
    }

    /**
     * Store a JWT token
     */
    public function storeToken(string $token): bool
    {
        // Implement token storage logic
        // Return true if successful, false otherwise
        return true;
    }

    /**
     * Retrieve the stored JWT token
     */
    public function getToken(): ?string
    {
        // Implement token retrieval logic
        // Return the token or null if not found
        return $storedToken ?? null;
    }

    /**
     * Clear the stored JWT token
     */
    public function clearToken(): bool
    {
        // Implement token clearing logic
        // Return true if successful, false otherwise
        return true;
    }

    /**
     * Check if a token is stored
     */
    public function hasToken(): bool
    {
        // Implement token existence check
        // Return true if a token exists, false otherwise
        return !empty($this->getToken());
    }

    /**
     * Increment the login attempt counter
     */
    public function incrementLoginAttempt(): int
    {
        // Implement login attempt increment logic
        // Return the new count
        return $newCount;
    }

    /**
     * Get the current login attempt count
     */
    public function getLoginAttemptCount(): int
    {
        // Implement login attempt count retrieval logic
        // Return the current count
        return $currentCount;
    }

    /**
     * Reset the login attempt counter to 0
     */
    public function resetLoginAttemptCount(): bool
    {
        // Implement login attempt reset logic
        // Return true if successful, false otherwise
        return true;
    }
}

// Then use your custom adapter with the CacheManager
$customAdapter = new CustomAdapter($yourStorageMechanism);
$cacheManager = new CacheManager($customAdapter, $apiKey);

Exception Handling

When using the Fireboost PHP SDK, you may encounter the following exceptions:

ApiException

Thrown when an error occurs during API communication. This exception is thrown by the following methods:

• saveCache() - When there's an error saving data to the cache
• readCache() - When there's an error reading data from the cache
• deleteCache() - When there's an error deleting data from the cache
• readPublicCache() - When there's an error reading public data from the cache
• getStatistics() - When there's an error retrieving cache statistics

The SDK automatically handles 401 Unauthorized errors by attempting to re-authenticate, but other API errors will be propagated to your code.

InvalidArgumentException

Thrown in the following cases:

• When the API key is missing or invalid
• When the API key doesn't contain the required project information

RuntimeException

Thrown in the following cases:

• When the maximum login attempts (3) are reached, indicating a potential issue with your API key
• When using the FileAdapter and the storage directory cannot be created or is not writable

Redis-related Exceptions

When using the RedisAdapter, Redis-related exceptions (like connection failures) may be propagated to your code.

Example of Exception Handling

use FireboostIO\SDK\CacheManager;
use FireboostIO\ApiException;
use InvalidArgumentException;
use RuntimeException;

$cacheManager = new CacheManager();

try {
    $data = $cacheManager->readCache('example/key');
    // Process the data
} catch (ApiException $e) {
    // Handle API-related errors
    echo "API Error: " . $e->getMessage() . " (Code: " . $e->getCode() . ")";
} catch (InvalidArgumentException $e) {
    // Handle invalid argument errors
    echo "Invalid Argument: " . $e->getMessage();
} catch (RuntimeException $e) {
    // Handle runtime errors
    echo "Runtime Error: " . $e->getMessage();
} catch (\Exception $e) {
    // Handle any other unexpected exceptions
    echo "Unexpected Error: " . $e->getMessage();
}

License

This project is licensed under the MIT License. See the LICENSE file for details.