README

A modern PHP client for seamless integration with the SMSGate API. Send SMS messages, manage devices, and configure webhooks through your PHP applications with this intuitive library.

🔖 Table of Contents

• 📱 SMS Gateway for Android™ PHP API Client
  • 🔖 Table of Contents
  • ✨ Features
  • ⚙️ Prerequisites
  • 📦 Installation
  • 🚀 Quickstart
    • Sending an SMS
    • Managing Devices
  • 🔐 Authentication
    • Basic Authentication
    • JWT Authentication
      • Generating a JWT Token
      • Using a JWT Token
      • Revoking a JWT Token
  • 📚 Full API Reference
    • Client Initialization
      • Basic Authentication
    • Core Methods
    • Builder Methods
  • 🔒 Security Notes
    • Best Practices
    • Encryption Support
  • 👥 Contributing
    • Development Setup
  • 📄 License

✨ Features

• Builder Pattern: Fluent interface for message and settings configuration
• PSR Standards: Compatible with any PSR-18 HTTP client
• Comprehensive API: Access to all SMS Gateway endpoints
• Error Handling: Structured exception management
• Type Safety: Strict typing throughout the codebase
• Encryption Support: End-to-end message encryption
• Dual Authentication: Support for both Basic and JWT authentication
• Token Management: Generate, use, and revoke JWT tokens with configurable scopes and TTL

⚙️ Prerequisites

• PHP 7.4+
• Composer
• PSR-18 compatible HTTP client (e.g., Guzzle)
• SMS Gateway for Android account

📦 Installation

composer require capcom6/android-sms-gateway

🚀 Quickstart

Sending an SMS

<?php

require 'vendor/autoload.php';

use AndroidSmsGateway\Client;
use AndroidSmsGateway\Domain\MessageBuilder;

// Initialize client with credentials
$client = new Client('your_login', 'your_password');

// Build message with fluent interface
$message = (new MessageBuilder('Your message text here.', ['+1234567890']))
    ->setTtl(3600)                  // Message time-to-live in seconds
    ->setSimNumber(1)               // Use SIM slot 1
    ->setWithDeliveryReport(true)   // Request delivery report
    ->setPriority(100)              // Higher priority message
    ->build();

// Send message
try {
    $messageState = $client->SendMessage($message);
    echo "✅ Message sent! ID: " . $messageState->ID() . PHP_EOL;
    
    // Check status after delay
    sleep(5);
    $updatedState = $client->GetMessageState($messageState->ID());
    echo "📊 Message status: " . $updatedState->State() . PHP_EOL;
} catch (\Exception $e) {
    echo "❌ Error: " . $e->getMessage() . PHP_EOL;
    exit(1);
}

Managing Devices

// List registered devices
$devices = $client->ListDevices();
echo "📱 Registered devices: " . count($devices) . PHP_EOL;

// Remove a device
try {
    $client->RemoveDevice('device-id-123');
    echo "🗑️ Device removed successfully" . PHP_EOL;
} catch (\Exception $e) {
    echo "❌ Device removal failed: " . $e->getMessage() . PHP_EOL;
}

🔐 Authentication

The SMSGate client supports two authentication methods: Basic Authentication and JWT (JSON Web Token) authentication. Each method has its own use cases and benefits.

Basic Authentication

// Initialize client with Basic authentication
$client = new Client('your_login', 'your_password');

JWT Authentication

JWT authentication uses bearer tokens for authentication.

Generating a JWT Token

use AndroidSmsGateway\Client;
use AndroidSmsGateway\Domain\TokenRequest;

// First, create a client with Basic authentication to generate a token
$basicClient = new Client('your_login', 'your_password');

// Create a token request with specific scopes and TTL
$tokenRequest = new TokenRequest(
    ['messages:send', 'messages:read'],  // Scopes for permissions
    3600                                 // Token TTL in seconds (optional)
);

// Generate the token
$tokenResponse = $basicClient->GenerateToken($tokenRequest);
$jwtToken = $tokenResponse->AccessToken();

echo "Token generated! Expires at: " . $tokenResponse->ExpiresAt() . PHP_EOL;

Using a JWT Token

// Initialize client with JWT authentication
$jwtClient = new Client(null, $jwtToken);

// Now use the client as usual
$message = (new MessageBuilder('Your message text here.', ['+1234567890']))->build();
$messageState = $jwtClient->SendMessage($message);

Revoking a JWT Token

// Revoke a token using its ID (jti)
$basicClient->RevokeToken($tokenResponse->ID());
echo "Token revoked successfully!" . PHP_EOL;

📚 Full API Reference

Client Initialization

The client supports two authentication methods: Basic Authentication and JWT Bearer Tokens.

Basic Authentication

$clientBasic = new Client(
    string $login,
    string $password,
    string $serverUrl = 'https://api.sms-gate.app/3rdparty/v1',
    ?\Psr\Http\Client\ClientInterface $httpClient = null,
    ?\AndroidSmsGateway\Encryptor $encryptor = null
);

$clientJWT = new Client(
    null,                           // Set login to null for JWT
    string $jwtToken,               // JWT token as the second parameter
    string $serverUrl = 'https://api.sms-gate.app/3rdparty/v1',
    ?\Psr\Http\Client\ClientInterface $httpClient = null,
    ?\AndroidSmsGateway\Encryptor $encryptor = null
);

Core Methods

Builder Methods

// Message Builder
$message = (new MessageBuilder(string $text, array $recipients))
    ->setTtl(int $seconds)
    ->setSimNumber(int $simSlot)
    ->setWithDeliveryReport(bool $enable)
    ->setPriority(int $value)
    ->build();

🔒 Security Notes

Best Practices

1. Never store credentials in code - Use environment variables:

   $login = getenv('SMS_GATEWAY_LOGIN');
   $password = getenv('SMS_GATEWAY_PASSWORD');

2. Use HTTPS - Ensure all API traffic is encrypted
3. Validate inputs - Sanitize phone numbers and message content
4. Rotate credentials - Regularly update your API credentials

Encryption Support

use AndroidSmsGateway\Encryptor;

// Initialize client with encryption
$encryptor = new Encryptor('your-secret-passphrase');
$client = new Client($login, $password, Client::DEFAULT_URL, null, $encryptor);

👥 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Development Setup

git clone https://github.com/android-sms-gateway/client-php.git
cd client-php
composer install

📄 License

This library is open-sourced software licensed under the Apache-2.0 license.

Note: Android is a trademark of Google LLC. This project is not affiliated with or endorsed by Google.