README

A modern PHP client for seamless integration with the SMS Gateway for Android 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

✨ 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

⚙️ 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;
}

📚 Full API Reference

Client Initialization

$client = 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
);

Core Methods

Category	Method	Description
Messages	`SendMessage(Message $message)`	Send SMS message
	`GetMessageState(string $id)`	Get message status by ID
	`RequestInboxExport(MessagesExportRequest $request)`	Request inbox export via webhooks
Devices	`ListDevices()`	List registered devices
	`RemoveDevice(string $id)`	Remove device by ID
System	`HealthCheck()`	Check API health status
	`GetLogs(?string $from, ?string $to)`	Retrieve system logs
Settings	`GetSettings()`	Get account settings
	`PatchSettings(Settings $settings)`	Partially update account settings
	`ReplaceSettings(Settings $settings)`	Replace account settings
Webhooks	`ListWebhooks()`	List registered webhooks
	`RegisterWebhook(Webhook $webhook)`	Register new webhook
	`DeleteWebhook(string $id)`	Delete webhook by ID

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

Never store credentials in code - Use environment variables:

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

Use HTTPS - Ensure all API traffic is encrypted
Validate inputs - Sanitize phone numbers and message content
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:

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
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.

capcom6 / android-sms-gateway

Maintainers

Details