Enhance Android SMS Gateway PHP client with new entities and API methods #68

capcom6 · 2025-05-31T04:37:07Z

Summary by CodeRabbit

New Features
- Introduced builder patterns for creating messages and settings, enabling more flexible and readable object construction.
- Added support for device management, system health checks, message inbox export, log retrieval, user settings management, and webhook management.
- Expanded message options with priority and validity period fields.
- Added support for webhook event types.
Documentation
- Updated usage instructions to demonstrate the new builder patterns and reflect updated method names and API structure.
- Improved API method categorization and descriptions for clarity.
- Completely overhauled README into a comprehensive, structured manual including features, prerequisites, security best practices, API reference, and contribution guidelines.
Bug Fixes
- Enforced validation to prevent setting mutually exclusive message parameters.
Tests
- Added comprehensive tests for new client features, message and settings builders, and updated existing tests to match the new API.

coderabbitai · 2025-05-31T04:39:44Z

Walkthrough

This update introduces extensive enhancements to the Android SMS Gateway PHP client. It adds new domain entities, builder classes for Message and Settings, and a comprehensive enumeration for webhook events. The Client class is expanded with new API methods for device, system, settings, logs, and webhook management, and deprecated methods are replaced. Tests and documentation are updated to reflect these changes.

Changes

File(s)	Change Summary
README.md	Usage examples updated to use builder patterns; method names updated; API methods reorganized and expanded.
src/Client.php	Added new public API methods for devices, system, settings, logs, webhooks; deprecated old methods; updated signatures.
src/Domain/Message.php	Added `priority` and `validUntil` properties; updated constructor and serialization logic; validation for TTL and validUntil.
src/Domain/MessageBuilder.php	New builder class for `Message` objects with fluent setters and validation.
src/Domain/Device.php src/Domain/LogEntry.php src/Domain/MessagesExportRequest.php src/Domain/Settings.php src/Domain/Webhook.php	New domain classes for device, log entry, message export request, settings, and webhook entities.
src/Domain/SettingsBuilder.php	New builder class for `Settings` objects with fluent setters.
src/Enums/WebhookEvent.php	New enum-like class for webhook event types with validation and factory methods.
src/Domain/RecipientState.php	PHPDoc updated to clarify `$phoneNumber` can be a hash; no logic changes.
tests/ClientTest.php	Test methods renamed and expanded to cover all new client API methods; imports updated.
tests/Domain/MessageBuilderTest.php	New tests for `MessageBuilder` covering minimal, full, invalid, and chaining cases.
tests/Domain/SettingsBuilderTest.php	New test for `SettingsBuilder` with minimal parameters.
tests/Domain/MessageTest.php	Assertion updated to check `isEncrypted` instead of `ttl` being null.
tests/EncryptorTest.php	Added namespace declaration for the test class.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant Client
    participant Server

    User->>Client: Build Message via MessageBuilder
    User->>Client: SendMessage(message)
    Client->>Server: POST /3rdparty/v1/messages
    Server-->>Client: MessageState
    Client-->>User: MessageState

    User->>Client: ListDevices()
    Client->>Server: GET /3rdparty/v1/devices
    Server-->>Client: [Device, ...]
    Client-->>User: [Device, ...]

    User->>Client: GetLogs(from, to)
    Client->>Server: GET /3rdparty/v1/logs?from=...&to=...
    Server-->>Client: [LogEntry, ...]
    Client-->>User: [LogEntry, ...]

    User->>Client: RegisterWebhook(webhook)
    Client->>Server: POST /3rdparty/v1/webhooks
    Server-->>Client: Webhook
    Client-->>User: Webhook

sequenceDiagram
    participant User
    participant SettingsBuilder
    participant Client
    participant Server

    User->>SettingsBuilder: setEncryption(...), setGateway(...), ...
    User->>SettingsBuilder: build()
    SettingsBuilder-->>User: Settings
    User->>Client: UpdateSettings(settings)
    Client->>Server: PUT /3rdparty/v1/settings
    Server-->>Client: object
    Client-->>User: object

✨ Finishing Touches

📝 Generate Docstrings

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Explain this complex logic.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
- @coderabbitai explain this code block.
- @coderabbitai modularize this function.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read src/utils.ts and explain its main purpose.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
- @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

@coderabbitai pause to pause the reviews on a PR.
@coderabbitai resume to resume the paused reviews.
@coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
@coderabbitai full review to do a full review from scratch and review all the files again.
@coderabbitai summary to regenerate the summary of the PR.
@coderabbitai generate docstrings to generate docstrings for this PR.
@coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
@coderabbitai resolve resolve all the CodeRabbit review comments.
@coderabbitai configuration to show the current CodeRabbit configuration for the repository.
@coderabbitai help to get help.

Other keywords and placeholders

Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

coderabbitai

Actionable comments posted: 2

🧹 Nitpick comments (8)

tests/Domain/SettingsBuilderTest.php (1)
9-16: Consider expanding test coverage for the builder pattern.

While the current test verifies basic builder functionality, consider adding tests for:

Building with individual setter methods

Method chaining verification

Building with all possible parameters set

Edge cases and validation

Example additional test:
public function testBuildWithAllParameters(): void {
    $settings = (new SettingsBuilder())
        ->withEncryption((object)['enabled' => true])
        ->withGateway((object)['host' => 'example.com'])
        ->build();
    
    $this->assertInstanceOf(Settings::class, $settings);
    $obj = $settings->ToObject();
    $this->assertObjectHasProperty('encryption', $obj);
    $this->assertObjectHasProperty('gateway', $obj);
}
src/Domain/Settings.php (1)
10-63: LGTM! Well-structured domain class with room for type safety improvements.

The Settings class follows good domain modeling patterns with proper serialization support and clean constructor design. The conditional property inclusion in ToObject() is efficient for API payloads.

Consider these improvements for better type safety and usability:

Add getter methods for property access:
public function getEncryption(): ?object { return $this->encryption; }
public function getGateway(): ?object { return $this->gateway; }
// ... etc
Consider more specific types instead of generic object:
private ?EncryptionSettings $encryption;
private ?GatewaySettings $gateway;
Add validation in constructor or setters if the objects have expected structure.
README.md (1)

67-95: Well-organized API documentation structure.

The categorization of client methods into logical groups (Message, Device, System, Settings, Webhook) makes the API much more discoverable and easier to navigate. The deprecation notices for old methods are clearly marked.

Minor formatting inconsistency: Consider using consistent list formatting throughout. The static analysis suggests using dashes instead of asterisks for unordered lists, but this is a minor stylistic choice.

🧰 Tools

🪛 LanguageTool

[uncategorized] ~70-~70: Loose punctuation mark.
Context: ...ssage. * SendMessage(Message $message): Send a new SMS message. * `GetState(str...

(UNLIKELY_OPENING_PUNCTUATION)

[uncategorized] ~72-~72: Loose punctuation mark.
Context: ... its ID. * GetMessageState(string $id): Retrieve the state of a previously sent...

(UNLIKELY_OPENING_PUNCTUATION)

[uncategorized] ~76-~76: Loose punctuation mark.
Context: .... ### Device Methods * ListDevices(): List all registered devices. * `RemoveD...

(UNLIKELY_OPENING_PUNCTUATION)

[uncategorized] ~77-~77: Loose punctuation mark.
Context: ...ed devices. * RemoveDevice(string $id): Remove a device by ID. ### System Meth...

(UNLIKELY_OPENING_PUNCTUATION)

[uncategorized] ~81-~81: Loose punctuation mark.
Context: .... ### System Methods * HealthCheck(): Check system health. * `RequestInboxExp...

(UNLIKELY_OPENING_PUNCTUATION)

[uncategorized] ~82-~82: Loose punctuation mark.
Context: ... * RequestInboxExport(object $request): Request inbox messages export. * `GetLo...

(UNLIKELY_OPENING_PUNCTUATION)

[uncategorized] ~83-~83: Loose punctuation mark.
Context: ...tring $from = null, ?string $to = null)`: Get logs within a specified time range....

(UNLIKELY_OPENING_PUNCTUATION)

[uncategorized] ~87-~87: Loose punctuation mark.
Context: ... ### Settings Methods * GetSettings(): Get user settings. * `UpdateSettings(ob...

(UNLIKELY_OPENING_PUNCTUATION)

[uncategorized] ~88-~88: Loose punctuation mark.
Context: ...gs. * UpdateSettings(object $settings): Update user settings. * `PatchSettings(...

(UNLIKELY_OPENING_PUNCTUATION)

[uncategorized] ~89-~89: Loose punctuation mark.
Context: ...ngs. * PatchSettings(object $settings): Partially update user settings. ### We...

(UNLIKELY_OPENING_PUNCTUATION)

[uncategorized] ~93-~93: Loose punctuation mark.
Context: ... ### Webhook Methods * ListWebhooks(): List all registered webhooks. * `Regist...

(UNLIKELY_OPENING_PUNCTUATION)

[uncategorized] ~94-~94: Loose punctuation mark.
Context: ...ks. * RegisterWebhook(object $webhook): Register a new webhook. * `DeleteWebhoo...

(UNLIKELY_OPENING_PUNCTUATION)

[uncategorized] ~95-~95: Loose punctuation mark.
Context: ...w webhook. * DeleteWebhook(string $id): Delete a webhook by ID. # Contributing...

(UNLIKELY_OPENING_PUNCTUATION)

🪛 markdownlint-cli2 (0.17.2)

69-69: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

70-70: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

71-71: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

72-72: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

76-76: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

77-77: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

81-81: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

82-82: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

83-83: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

87-87: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

88-88: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

89-89: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

93-93: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

94-94: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

95-95: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)
src/Domain/MessagesExportRequest.php (1)
10-58: Clean domain class implementation following established patterns.

The class correctly implements SerializableInterface with proper constructor, factory method, and serialization. The structure is consistent with other domain classes in the codebase.

Consider adding input validation for date format and device ID if these have specific requirements:
 public function __construct(string $deviceId, string $since, string $until) {
+    if (empty($deviceId)) {
+        throw new \InvalidArgumentException('Device ID cannot be empty');
+    }
     $this->deviceId = $deviceId;
     $this->since = $since;
     $this->until = $until;
 }
src/Domain/SettingsBuilder.php (1)
5-5: Remove unused import.

The InvalidArgumentException import is not used in this class.
-use InvalidArgumentException;
src/Domain/MessageBuilder.php (1)
36-36: Remove extra blank line.

There's an unnecessary blank line that should be removed for consistency.
 private bool $withDeliveryReport = true;
-

 /**
src/Enums/WebhookEvent.php (1)
12-20: Consider moving the _ALL_ constant to the top of the class for better readability.

While PHP allows forward references to class constants, it's more conventional and clearer to define constants before they're used. This improves code readability and makes the validation logic easier to follow.
 final class WebhookEvent {
     public const SMS_RECEIVED = 'sms:received';
     public const SMS_SENT = 'sms:sent';
     public const SMS_DELIVERED = 'sms:delivered';
     public const SMS_FAILED = 'sms:failed';
     public const SYSTEM_PING = 'system:ping';
 
+    private const _ALL_ = [
+        self::SMS_RECEIVED,
+        self::SMS_SENT,
+        self::SMS_DELIVERED,
+        self::SMS_FAILED,
+        self::SYSTEM_PING,
+    ];
+
     private string $value;
 
     private function __construct(string $value) {
And remove the constant definition from lines 54-60.

Also applies to: 54-60
tests/ClientTest.php (1)
303-305: Remove unnecessary empty line.
     public function testPatchSettings(): void {
-
-
         $settings = new Settings(

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1c73ad6 and 49aa0e9.

📒 Files selected for processing (16)

README.md (2 hunks)
src/Client.php (4 hunks)
src/Domain/Device.php (1 hunks)
src/Domain/LogEntry.php (1 hunks)
src/Domain/Message.php (3 hunks)
src/Domain/MessageBuilder.php (1 hunks)
src/Domain/MessagesExportRequest.php (1 hunks)
src/Domain/RecipientState.php (1 hunks)
src/Domain/Settings.php (1 hunks)
src/Domain/SettingsBuilder.php (1 hunks)
src/Domain/Webhook.php (1 hunks)
src/Enums/WebhookEvent.php (1 hunks)
tests/ClientTest.php (7 hunks)
tests/Domain/MessageBuilderTest.php (1 hunks)
tests/Domain/MessageTest.php (1 hunks)
tests/Domain/SettingsBuilderTest.php (1 hunks)

🧰 Additional context used

🧬 Code Graph Analysis (3)

tests/Domain/MessageBuilderTest.php (1)

src/Domain/MessageBuilder.php (8)

MessageBuilder (10-170)

build (154-169)

setId (67-70)

setTtl (89-92)

setSimNumber (100-103)

setWithDeliveryReport (111-114)

setPriority (132-135)

setValidUntil (143-146)

src/Enums/WebhookEvent.php (1)

src/Domain/Webhook.php (1)

__construct (38-48)

src/Client.php (7)

src/Domain/Device.php (2)

Device (10-149)

FromObject (69-78)

src/Domain/LogEntry.php (3)

LogEntry (10-140)

Message (109-111)

FromObject (69-78)

src/Domain/Webhook.php (2)

Webhook (11-110)

FromObject (54-61)

src/Domain/MessagesExportRequest.php (2)

MessagesExportRequest (10-59)

FromObject (41-47)

src/Domain/Settings.php (2)

Settings (10-112)

FromObject (69-78)

src/Domain/Message.php (2)

Message (11-118)

Encrypt (80-92)

src/Domain/MessageState.php (2)

MessageState (11-120)

FromObject (108-119)

🪛 LanguageTool

README.md

[uncategorized] ~70-~70: Loose punctuation mark.
Context: ...ssage. * SendMessage(Message $message): Send a new SMS message. * `GetState(str...