Skip to content

android-sms-gateway/client-php

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

📱 SMS Gateway for Android™ PHP API Client

License Latest Stable Version PHP Version Require Total Downloads

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

✨ 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

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
Authentication GenerateToken(TokenRequest $request) Generate a new JWT token
RevokeToken(string $jti) Revoke a JWT token 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.