README

Official PHP SDK for the EagleBirth API.

Installation

Install via Composer:

composer require eaglebirth/eaglebirth-php

Requirements

PHP 7.4 or higher
cURL extension
JSON extension

Quick Start

<?php

require_once 'vendor/autoload.php';

use EagleBirth\EagleBirth;

// Initialize the client
$client = new EagleBirth('eb_test_your_api_key_here');

// Send an email
$response = $client->email->send(
    email: 'user@example.com',
    subject: 'Welcome!',
    message: 'Thank you for signing up.'
);

print_r($response);

Authentication

Get your API key from https://eaglebirth.com > Dashboard > Apps > API Keys

// Test environment - automatically routes to sandbox.eaglebirth.com
$client = new EagleBirth('eb_test_...');

// Production environment - automatically routes to eaglebirth.com
$client = new EagleBirth('eb_live_...');

Environments

The SDK automatically routes requests to the correct environment based on your API key prefix:

Sandbox/Test (eb_test_...) - Routes to sandbox.eaglebirth.com. For development and testing. No charges, uses test data.
Production (eb_live_...) - Routes to eaglebirth.com. For live applications. Real charges apply.

No additional configuration needed - just use the appropriate API key and the SDK will automatically connect to the right server. You can create separate API keys for each environment from your dashboard.

Usage Examples

Email

// Send a simple email
$client->email->send(
    email: 'user@example.com',
    subject: 'Welcome to our service',
    message: 'Thank you for joining us!'
);

// Send with custom reply-to and header
$client->email->send(
    email: 'user@example.com',
    subject: 'Account Verification',
    message: 'Please verify your email address.',
    replyTo: 'support@myapp.com',
    header: 'MyApp Verification'
);

SMS

// Send an SMS
$client->sms->send(
    phoneNumber: '+1234567890',
    message: 'Your verification code is 123456'
);

// Get SMS pricing
$prices = $client->sms->getPrices('+1234567890');
print_r($prices);

// Send a WhatsApp message
$client->whatsapp->send(
    phoneNumber: '+1234567890',
    message: 'Hello from EagleBirth!',
    template: 'normal_message'
);

OTP (One-Time Passwords)

// Send OTP via email
$result = $client->otp->send(
    validationType: 'email',
    email: 'user@example.com',
    codeLength: 6,
    timeout: 180,
    trials: 3
);
$codeId = $result['code_id'];

// Validate the OTP
$validation = $client->otp->validate(
    codeId: $codeId,
    code: '123456'
);

// Check if code was validated
$status = $client->otp->checkValidated($codeId);

QR Code Generation

// Generate a simple QR code
$qr = $client->qr->generate(
    text: 'https://example.com'
);

// Generate with custom colors and logo
$qr = $client->qr->generate(
    text: 'https://example.com',
    image: '/path/to/logo.png',
    imageType: 'object',
    color: '#000000',
    backgroundColor: '#FFFFFF',
    qrType: 'rounded'
);

// Generate with logo from URL
$qr = $client->qr->generate(
    text: 'https://example.com',
    image: 'https://example.com/logo.png',
    imageType: 'link'
);

Vision AI

// Extract face details from an image file
$details = $client->vision->extractFaceDetails(
    image: '/path/to/photo.jpg',
    imageType: 'object'
);

// Extract face details from image URL
$details = $client->vision->extractFaceDetails(
    image: 'https://example.com/photo.jpg',
    imageType: 'link'
);

// Compare two faces
$comparison = $client->vision->compareFaces(
    image1: '/path/to/photo1.jpg',
    image2: '/path/to/photo2.jpg',
    image1Type: 'object',
    image2Type: 'object'
);

// Extract text from image (OCR)
$text = $client->vision->extractText(
    image: '/path/to/document.jpg',
    imageType: 'object'
);

Cloud Storage

// Create a directory
$client->storage->directory->create(
    path: '/photos/vacation/',
    private: 'yes',  // 'yes' or 'no'
    directoryPassword: 'secret123'  // Optional password protection
);

// Upload a file
$client->storage->file->upload(
    file: '/path/to/document.pdf',
    path: '/documents/report.pdf',
    private: 'no',
    filePassword: 'filepass123'  // Optional file password
);

// List directory contents
$contents = $client->storage->directory->listContent(
    path: '/photos/vacation/',
    directoryPassword: 'secret123'  // If directory is password protected
);

foreach ($contents['data']['directories'] as $dir) {
    echo "Directory: {$dir['path']}\n";
}

foreach ($contents['data']['files'] as $file) {
    echo "File: {$file['filename']} - {$file['size']} bytes\n";
}

// Retrieve a file
$fileData = $client->storage->file->retrieve(
    path: '/documents/report.pdf',
    password: 'filepass123'  // If file is password protected
);

// Update file privacy
$client->storage->file->updatePrivacy(
    path: '/documents/report.pdf',
    private: 'yes',
    refreshToken: 'yes'  // Generate new access token
);

// Update directory password
$client->storage->directory->updatePassword(
    path: '/photos/vacation/',
    directoryPassword: 'newsecret456'
);

// Delete a file
$client->storage->file->delete(path: '/documents/old_report.pdf');

// Delete a directory
$client->storage->directory->delete(path: '/photos/old_vacation/');

User Management

Manage your application's end users. All operations use your API key (no additional authentication needed).

// Note: The client is already authenticated with your API key.
// User Management operates on your app's users.

```php
// Create a new user
$user = $client->users->create(
    email: 'newuser@example.com',
    username: 'johndoe',
    firstName: 'John',
    lastName: 'Doe',
    password: 'securepassword123',
    phone: '+1234567890'
);
echo "User created with ID: {$user['data']['user_id']}\n";

// Check if a user exists
$exists = $client->users->exists(username: 'johndoe');
if ($exists['data']['exists']) {
    echo "User exists!\n";
}

// Get user details
$userDetails = $client->users->get(username: 'johndoe');
echo "User email: {$userDetails['data']['email']}\n";

// List all users (paginated)
$users = $client->users->listAll(page: 1, limit: 10);
foreach ($users['data']['users'] as $user) {
    echo "{$user['username']} - {$user['email']}\n";
}

// Update user details
$client->users->update(
    username: 'johndoe',
    email: 'newemail@example.com',
    firstName: 'Jonathan'
);

// Sign in a user (classic username/password)
$signinResult = $client->users->signIn(
    username: 'johndoe',
    password: 'securepassword123'
);
$accessToken = $signinResult['data']['access'];
$refreshToken = $signinResult['data']['refresh'];

// Sign in with third-party auth (e.g., Google, Facebook)
$signinResult = $client->users->signIn(
    authenticationType: 'google',
    authenticationTypeId: 'google_user_id_12345'
);

// OAuth PKCE Flow with EagleBirth Auth UI
// After user authenticates via EagleBirth Auth UI, you'll receive a 'code'
// Exchange the code for user session and data
$userSession = $client->users->exchangeCodeForUser(
    code: 'authorization_code_from_redirect',
    codeVerifier: 'your_code_verifier'
);
echo "User email: {$userSession['data']['email']}\n";
echo "Access token: {$userSession['data']['access']}\n";
echo "User ID: {$userSession['data']['user_id']}\n";

// Verify if a session token is valid
$isValid = $client->users->verifyToken(token: $accessToken);

// Refresh user session token
$newTokens = $client->users->refreshToken(refresh: $refreshToken);

// Update user password (admin action)
$client->users->updatePassword(
    username: 'johndoe',
    password: 'newpassword456'
);

// Send verification code for password reset
$codeResponse = $client->users->sendVerificationCode(username: 'johndoe');
$codeId = $codeResponse['data']['code_id'];

// Validate the verification code
$client->users->validateVerificationCode(
    code: '123456',
    codeId: $codeId
);

// Reset password using verification code (self-service)
$client->users->resetPassword(
    code: '123456',
    codeId: $codeId,
    password: 'brandnewpassword789'
);

// Update user status
$client->users->updateStatus(
    username: 'johndoe',
    status: 'suspended'  // Options: 'active', 'suspended', 'pending', 'deleted'
);

// Update user type/role
$client->users->updateType(
    username: 'johndoe',
    type: 'premium'
);

// Reactivate a suspended user
$client->users->reactivate(username: 'johndoe');

// Sign out a user (invalidate refresh token)
$client->users->signOut(refreshToken: $refreshToken);

// Delete a user
$client->users->delete(username: 'johndoe');

OAuth PKCE Flow (EagleBirth Auth UI)

When users authenticate through EagleBirth's hosted Auth UI, you'll receive an authorization code that needs to be exchanged for user data and session tokens.

// Step 1: Redirect users to EagleBirth Auth UI with PKCE parameters
// (You generate code_verifier and code_challenge in your app)

// Step 2: After successful authentication, EagleBirth redirects back to your app
// with a 'code' parameter in the URL

// Step 3: Exchange the code for user session data
$userSession = $client->users->exchangeCodeForUser(
    code: 'code_from_url_redirect',
    codeVerifier: 'your_original_code_verifier'
);

// Access user information
$userData = $userSession['data'];
echo "Email: {$userData['email']}\n";
echo "Username: {$userData['username']}\n";
echo "Name: {$userData['first_name']} {$userData['last_name']}\n";
echo "Phone: {$userData['phone']}\n";
echo "User ID: {$userData['user_id']}\n";

// Access session tokens
$accessToken = $userData['access'];
$refreshToken = $userData['refresh'];

// Use the access token for authenticated requests
// Store the refresh token for renewing the session

Error Handling

use EagleBirth\Exceptions\EagleBirthException;
use EagleBirth\Exceptions\AuthenticationException;
use EagleBirth\Exceptions\APIException;

try {
    $response = $client->email->send(
        email: 'user@example.com',
        subject: 'Test',
        message: 'Hello!'
    );
} catch (AuthenticationException $e) {
    // Invalid API key or authentication failed
    echo "Authentication error: " . $e->getMessage();
} catch (APIException $e) {
    // API returned an error
    echo "API error: " . $e->getMessage();
    echo "Status code: " . $e->getCode();
} catch (EagleBirthException $e) {
    // General SDK error
    echo "Error: " . $e->getMessage();
}

Configuration

// Custom base URL (for testing or self-hosted)
$client = new EagleBirth(
    apiKey: 'eb_test_...',
    baseUrl: 'https://custom-api.example.com/api'
);

// Custom timeout (default: 30 seconds)
$client = new EagleBirth(
    apiKey: 'eb_test_...',
    baseUrl: null,
    timeout: 60
);

Cloud Storage

// Upload a file
$client->storage->file->upload(
    file: '/path/to/document.pdf',
    path: '/docs/report.pdf',
    private: 'no'
);

// Create a directory
$client->storage->directory->create(
    path: '/photos/vacation/',
    private: 'yes'
);

// List directory contents
$contents = $client->storage->directory->listContent(path: '/photos/');

// Retrieve a file
$fileData = $client->storage->file->retrieve(path: '/docs/report.pdf');

Authentication

// Sign in with app credentials
$authResponse = $client->auth->signIn(
    clientId: 'your_client_id',
    secretId: 'your_secret_id'
);

// Get user tokens
$tokens = $client->auth->getToken(
    username: 'user@example.com',
    password: 'password123'
);

// Refresh access token
$newToken = $client->auth->refreshToken(refresh: 'your_refresh_token');

Available Resources

$client->email - Email notifications
$client->sms - SMS messaging
$client->whatsapp - WhatsApp messaging
$client->otp - OTP/verification codes
$client->qr - QR code generation
$client->vision - Vision AI (face detection, OCR, face comparison)
$client->storage - Cloud storage (files and directories)
- $client->storage->file - File operations
- $client->storage->directory - Directory operations
$client->users - User management for your app's end users

Support

Documentation: https://eaglebirth.com/developer/documentation
Email: contact@eaglebirth.com
Dashboard: https://eaglebirth.com

License

MIT License

eaglebirth / eaglebirth-php

Maintainers

Package info

Statistics

Security

README

Installation

Requirements

Quick Start

Authentication

Environments

Usage Examples

Email

SMS

WhatsApp

OTP (One-Time Passwords)

QR Code Generation

Vision AI

Cloud Storage

User Management

OAuth PKCE Flow (EagleBirth Auth UI)

Error Handling

Configuration

Cloud Storage

Authentication

Available Resources

Support

License