Skip to content

Commit 920e0f7

Browse files
capcom6capcom6
committed
[docs] update README
1 parent 0db8d72 commit 920e0f7

File tree

1 file changed

+152
-62
lines changed

1 file changed

+152
-62
lines changed

‎README.md

Lines changed: 152 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,58 @@
1-
# SMS Gateway for Android™ PHP API Client
2-
3-
This is a PHP client library for interfacing with the [SMS Gateway for Android](https://sms-gate.app) API.
4-
5-
## Requirements
6-
7-
- PHP 7.4 or higher
8-
- A PSR-18 compatible HTTP client implementation
9-
10-
## Installation
11-
12-
You can install the package via composer:
1+
# 📱 SMS Gateway for Android™ PHP API Client
2+
3+
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=for-the-badge)](https://opensource.org/licenses/Apache-2.0)
4+
[![Latest Stable Version](https://img.shields.io/packagist/v/capcom6/android-sms-gateway.svg?style=for-the-badge)](https://packagist.org/packages/capcom6/android-sms-gateway)
5+
[![PHP Version Require](https://img.shields.io/packagist/php-v/capcom6/android-sms-gateway?style=for-the-badge)](https://packagist.org/packages/capcom6/android-sms-gateway)
6+
[![Total Downloads](https://img.shields.io/packagist/dt/capcom6/android-sms-gateway.svg?style=for-the-badge)](https://packagist.org/packages/capcom6/android-sms-gateway)
7+
8+
A modern PHP client for seamless integration with the [SMS Gateway for Android](https://sms-gate.app) API. Send SMS messages, manage devices, and configure webhooks through your PHP applications with this intuitive library.
9+
10+
## 🔖 Table of Contents
11+
12+
- [📱 SMS Gateway for Android™ PHP API Client](#-sms-gateway-for-android-php-api-client)
13+
- [🔖 Table of Contents](#-table-of-contents)
14+
- [✨ Features](#-features)
15+
- [⚙️ Prerequisites](#️-prerequisites)
16+
- [📦 Installation](#-installation)
17+
- [🚀 Quickstart](#-quickstart)
18+
- [Sending an SMS](#sending-an-sms)
19+
- [Managing Devices](#managing-devices)
20+
- [📚 Full API Reference](#-full-api-reference)
21+
- [Client Initialization](#client-initialization)
22+
- [Core Methods](#core-methods)
23+
- [Builder Methods](#builder-methods)
24+
- [🔒 Security Notes](#-security-notes)
25+
- [Best Practices](#best-practices)
26+
- [Encryption Support](#encryption-support)
27+
- [👥 Contributing](#-contributing)
28+
- [Development Setup](#development-setup)
29+
- [📄 License](#-license)
30+
31+
## ✨ Features
32+
33+
- **Builder Pattern**: Fluent interface for message and settings configuration
34+
- **PSR Standards**: Compatible with any PSR-18 HTTP client
35+
- **Comprehensive API**: Access to all SMS Gateway endpoints
36+
- **Error Handling**: Structured exception management
37+
- **Type Safety**: Strict typing throughout the codebase
38+
- **Encryption Support**: End-to-end message encryption
39+
40+
## ⚙️ Prerequisites
41+
42+
- PHP 7.4+
43+
- [Composer](https://getcomposer.org/)
44+
- PSR-18 compatible HTTP client (e.g., [Guzzle](https://github.com/guzzle/guzzle))
45+
- SMS Gateway for Android account
46+
47+
## 📦 Installation
1348

1449
```bash
1550
composer require capcom6/android-sms-gateway
1651
```
1752

18-
## Usage
19-
20-
### Using the Builder Pattern
21-
22-
The library provides builder classes for creating `Message` and `Settings` objects with numerous optional fields.
23-
24-
#### Creating a Message
53+
## 🚀 Quickstart
2554

55+
### Sending an SMS
2656
```php
2757
<?php
2858

@@ -31,73 +61,133 @@ require 'vendor/autoload.php';
3161
use AndroidSmsGateway\Client;
3262
use AndroidSmsGateway\Domain\MessageBuilder;
3363

34-
$login = 'your_login';
35-
$password = 'your_password';
36-
37-
$client = new Client($login, $password);
64+
// Initialize client with credentials
65+
$client = new Client('your_login', 'your_password');
3866

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

75+
// Send message
4676
try {
4777
$messageState = $client->SendMessage($message);
48-
echo "Message sent with ID: " . $messageState->ID() . PHP_EOL;
49-
} catch (Exception $e) {
50-
echo "Error sending message: " . $e->getMessage() . PHP_EOL;
51-
die(1);
78+
echo "✅ Message sent! ID: " . $messageState->ID() . PHP_EOL;
79+
80+
// Check status after delay
81+
sleep(5);
82+
$updatedState = $client->GetMessageState($messageState->ID());
83+
echo "📊 Message status: " . $updatedState->State() . PHP_EOL;
84+
} catch (\Exception $e) {
85+
echo "❌ Error: " . $e->getMessage() . PHP_EOL;
86+
exit(1);
5287
}
88+
```
89+
90+
### Managing Devices
91+
92+
```php
93+
// List registered devices
94+
$devices = $client->ListDevices();
95+
echo "📱 Registered devices: " . count($devices) . PHP_EOL;
5396

97+
// Remove a device
5498
try {
55-
$messageState = $client->GetMessageState($messageState->ID());
56-
echo "Message state: " . $messageState->State() . PHP_EOL;
57-
} catch (Exception $e) {
58-
echo "Error getting message state: " . $e->getMessage() . PHP_EOL;
59-
die(1);
99+
$client->RemoveDevice('device-id-123');
100+
echo "🗑️ Device removed successfully" . PHP_EOL;
101+
} catch (\Exception $e) {
102+
echo "❌ Device removal failed: " . $e->getMessage() . PHP_EOL;
60103
}
61104
```
62105

63-
## Client
106+
## 📚 Full API Reference
64107

65-
The `Client` is used for sending SMS messages in plain text, but can also be used for sending encrypted messages by providing an `Encryptor`.
108+
### Client Initialization
109+
```php
110+
$client = new Client(
111+
string $login,
112+
string $password,
113+
string $serverUrl = 'https://api.sms-gate.app/3rdparty/v1',
114+
?\Psr\Http\Client\ClientInterface $httpClient = null,
115+
?\AndroidSmsGateway\Encryptor $encryptor = null
116+
);
117+
```
66118

67-
### Message Methods
119+
### Core Methods
120+
121+
| Category | Method | Description |
122+
| ------------ | ---------------------------------------------------- | --------------------------------- |
123+
| **Messages** | `SendMessage(Message $message)` | Send SMS message |
124+
| | `GetMessageState(string $id)` | Get message status by ID |
125+
| | `RequestInboxExport(MessagesExportRequest $request)` | Request inbox export via webhooks |
126+
| **Devices** | `ListDevices()` | List registered devices |
127+
| | `RemoveDevice(string $id)` | Remove device by ID |
128+
| **System** | `HealthCheck()` | Check API health status |
129+
| | `GetLogs(?string $from, ?string $to)` | Retrieve system logs |
130+
| **Settings** | `GetSettings()` | Get account settings |
131+
| | `PatchSettings(Settings $settings)` | Partially update account settings |
132+
| | `ReplaceSettings(Settings $settings)` | Replace account settings |
133+
| **Webhooks** | `ListWebhooks()` | List registered webhooks |
134+
| | `RegisterWebhook(Webhook $webhook)` | Register new webhook |
135+
| | `DeleteWebhook(string $id)` | Delete webhook by ID |
136+
137+
### Builder Methods
138+
```php
139+
// Message Builder
140+
$message = (new MessageBuilder(string $text, array $recipients))
141+
->setTtl(int $seconds)
142+
->setSimNumber(int $simSlot)
143+
->setWithDeliveryReport(bool $enable)
144+
->setPriority(int $value)
145+
->build();
146+
```
68147

69-
* `Send(Message $message)` (deprecated): Send a new SMS message.
70-
* `SendMessage(Message $message)`: Send a new SMS message.
71-
* `GetState(string $id)` (deprecated): Retrieve the state of a previously sent message by its ID.
72-
* `GetMessageState(string $id)`: Retrieve the state of a previously sent message by its ID.
148+
## 🔒 Security Notes
73149

74-
### Device Methods
150+
### Best Practices
75151

76-
* `ListDevices()`: List all registered devices.
77-
* `RemoveDevice(string $id)`: Remove a device by ID.
152+
1. **Never store credentials in code** - Use environment variables:
153+
```php
154+
$login = getenv('SMS_GATEWAY_LOGIN');
155+
$password = getenv('SMS_GATEWAY_PASSWORD');
156+
```
157+
2. **Use HTTPS** - Ensure all API traffic is encrypted
158+
3. **Validate inputs** - Sanitize phone numbers and message content
159+
4. **Rotate credentials** - Regularly update your API credentials
78160

79-
### System Methods
161+
### Encryption Support
80162

81-
* `HealthCheck()`: Check system health.
82-
* `RequestInboxExport(object $request)`: Request inbox messages export.
83-
* `GetLogs(?string $from = null, ?string $to = null)`: Get logs within a specified time range.
163+
```php
164+
use AndroidSmsGateway\Encryptor;
84165

85-
### Settings Methods
166+
// Initialize client with encryption
167+
$encryptor = new Encryptor('your-secret-passphrase');
168+
$client = new Client($login, $password, Client::DEFAULT_URL, null, $encryptor);
169+
```
86170

87-
* `GetSettings()`: Get user settings.
88-
* `UpdateSettings(object $settings)`: Update user settings.
89-
* `PatchSettings(object $settings)`: Partially update user settings.
171+
## 👥 Contributing
90172

91-
### Webhook Methods
173+
We welcome contributions! Please follow these steps:
92174

93-
* `ListWebhooks()`: List all registered webhooks.
94-
* `RegisterWebhook(object $webhook)`: Register a new webhook.
95-
* `DeleteWebhook(string $id)`: Delete a webhook by ID.
175+
1. Fork the repository
176+
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
177+
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
178+
4. Push to the branch (`git push origin feature/AmazingFeature`)
179+
5. Open a Pull Request
96180

97-
# Contributing
181+
### Development Setup
182+
```bash
183+
git clone https://github.com/android-sms-gateway/client-php.git
184+
cd client-php
185+
composer install
186+
```
98187

99-
Contributions are welcome! Please submit a pull request or create an issue for anything you'd like to add or change.
188+
## 📄 License
189+
This library is open-sourced software licensed under the [Apache-2.0 license](LICENSE).
100190

101-
# License
191+
---
102192

103-
This library is open-sourced software licensed under the [Apache-2.0 license](LICENSE).
193+
**Note**: Android is a trademark of Google LLC. This project is not affiliated with or endorsed by Google.

0 commit comments

Comments
 (0)