📱 SMS Gateway for Android™ PHP API Client

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
  • 🔖 Table of Contents
  • ✨ Features
  • ⚙️ Prerequisites
  • 📦 Installation
  • 🚀 Quickstart
    • Sending an SMS
    • Managing Devices
  • 📚 Full API Reference
    • Client Initialization
    • 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

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

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.