dreamsms/laravel-dreamsms

A Laravel package providing a fluent, easy-to-use wrapper around the DreamSMS API for user registration, token management, sender configuration, balance inquiry and sending single or multi-recipient SMS messages. Developed by هوية الأحلام لتقنية المعلومات (Dreams), Saudi Arabia’s leading creative &

v1.0.5 2025-06-24 13:08 UTC

Requires

• php: ^7.4|^8.0|^8.1|^8.2|^8.3|^8.4
• illuminate/support: ^8.0|^9.0|^10.0|^11.0|^12.0

MIT

• Yacoub Al-haidari

• sms
• notification
• laravel
• API-Client
• laravel-package
• sms-api
• sms-sending
• dreamsms

README

Comprehensive reference for every method provided by the dreamsms/laravel-dreamsms package.

1. Installation & Configuration

1.1 Install via Composer

composer require dreamsms/laravel-dreamsms

1.2 Publish Configuration

php artisan vendor:publish --provider="DreamSms\LaravelDreamSms\DreamSmsServiceProvider" --tag=config

1.3 Environment Variables

Add these to your .env:

DREAMSMS_BASE_URL=https://www.dreams.sa/index.php/api
DREAMSMS_USER=your_username
DREAMSMS_SECRET_KEY=your_api_secret_key
DREAMSMS_CLIENT_ID=your_oauth_client_id
DREAMSMS_CLIENT_SECRET=your_oauth_client_secret

1.4 Config File (config/dreamsms.php)

return [
    'base_url'      => env('DREAMSMS_BASE_URL'),
    'user'          => env('DREAMSMS_USER'),
    'secret_key'    => env('DREAMSMS_SECRET_KEY'),
    'client_id'     => env('DREAMSMS_CLIENT_ID'),
    'client_secret' => env('DREAMSMS_CLIENT_SECRET'),
];

2. Service Usage

Use the Facade or inject the DreamSms service.

use DreamSms; // Facade

// OR via DI
public function __construct(DreamSms\LaravelDreamSms\DreamSms $sms)
{
    $this->sms = $sms;
}

3. API Methods Reference

Each section details endpoint, parameters, expected response, and Laravel usage.

3.1 register(array $user): array

Description: Register a new DreamSMS user account.

HTTP Method	Endpoint
POST	/Register

Parameters

Name	Type	Required	Description
user	string	yes	Desired username
password	string	yes	Password (min 6 chars)
name	string	yes	Full name
mobile	string	yes	Mobile number (e.g. 9665...)
email	string	yes	Valid e‑mail address

Example Request

$response = DreamSms::register([
    'user'     => 'newuser',
    'password' => 'pass1234',
    'name'     => 'John Doe',
    'mobile'   => '966512345678',
    'email'    => '[e-mail]',
]);

Success Response

{
  "code": 999,
  "message": "Success register user",
  "data": { /* user details */ }
}

Error Codes

• 100: Missing parameters
• 110: Username already used
• 111: Mobile already used
• 112: Email already used
• 120: Username contains invalid characters
• 121: Password too short (<6)
• 122: Invalid username
• 123: Invalid password

3.2 generateToken(): array

Description: Obtain OAuth2 Bearer token.

HTTP Method	Endpoint
POST	/token/generate

Parameters

Name	Type	Required	Description
grant_type	string	yes	Must be client_credentials
client_id	string	yes	OAuth client ID
client_secret	string	yes	OAuth client secret

Example Request

$tokenData = DreamSms::generateToken();

Success Response

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ0e..."
}

Error Responses

• 401 invalid_client: Authentication failed
• 400 unsupported_grant_type: Wrong grant type

3.3 activate(string $user, string $code): array

Description: Activate a newly registered account.

HTTP Method	Endpoint
POST	/activate

Parameters

Name	Type	Required	Description
user	string	yes	Username
secret_key	string	yes	API secret key
code	string	yes	Activation code

Example Request

DreamSms::activate('newuser', '123456');

Response Codes

• 999: Success
• 100: Missing parameters
• 110: Invalid username or secret_key
• 111: Wrong activation code

3.4 checkUser(): array

Description: Verify account credentials and activation status.

HTTP Method	Endpoint
POST	/chk_user

Parameters

Name	Type	Required	Description
user	string	yes	Username
secret_key	string	yes	API key

Success Response

{ "code": 999, "message": "Valid account" }

Error Codes

• -100: Missing parameters
• -110: Account not exist or wrong credentials
• -111: Account not activated
• -112: Blocked account

3.5 balance(): array

Description: Retrieve SMS credit balance.

HTTP Method	Endpoint
POST	/chk_balance

Parameters

Name	Type	Required	Description
user	string	yes	Username
secret_key	string	yes	API key

Success Response

{ "balance": 123.45 }

Error Codes

• -100: Missing parameters
• -110: Invalid credentials

3.6 addSender(string $sender): array

Description: Create a new sender name.

HTTP Method	Endpoint
POST	/newsender

Parameters

Name	Type	Required	Description
user	string	yes	Username
secret_key	string	yes	API key
sendertext	string	yes	Sender name (max 11 chars)

Error Codes

• -113: Duplicate sender
• -114: Invalid sender name (chars or length)

3.7 senderStatus(string $sender): array

Description: Check activation status of a sender.

HTTP Method	Endpoint
POST	/senderstatus

Parameters

Name	Type	Required	Description
user	string	yes	Username
secret_key	string	yes	API key
sendertext	string	yes	Sender name

Status Values

• Active, UnActive, Rejected

3.8 userSenders(): array

Description: List all senders for your account.

HTTP Method	Endpoint
POST	/usersender

Success Response (XML)

<usersender>
  <sender>
    <id>52</id>
    <text>MySender</text>
    <status>Active</status>
    <default>false</default>
    <date>2025-06-01</date>
    <notes>...</notes>
  </sender>
</usersender>

3.9 sendSms(string $to, string $message, string $sender, array $options = []): array

Description: Send a single SMS, optionally with calendar reminder.

HTTP Method	Endpoint
POST	/sendsms

Required Parameters

Name	Type	Description
user	string	Username
secret_key	string	API key
to	string	Recipient mobile number
message	string	Message body
sender	string	Sender name

Optional Calendar Fields (is_calander = 1)

Name	Description
calander_date	YYYY-MM-DD
calander_time	HH:MM
reminder	Minutes before event
reminder_text	Reminder message
location_url	Google Maps URL

Example Usage

DreamSms::sendSms(
    '966512345678',
    'Meeting at 5pm',
    'MyApp',
    [
        'is_calander'   => 1,
        'calander_date' => '2025-07-01',
        'calander_time' => '17:00',
        'reminder'      => 30,
        'reminder_text' => 'Don’t forget!',
    ]
);

Response

• SMS_ID:mobileNumber on success
• Negative codes for errors (-113 insufficient balance, -119 invalid datetime, etc.)

3.10 sendMulti(array $toWithMsg, string $sender): array

Description: Send different messages to multiple recipients in one request.

HTTP Method	Endpoint
POST	/sendsms_multi

Parameters

Name	Type	Description
user	string	Username
secret_key	string	API key
sender	string	Sender name
to	string	JSON: {"9665...":"Msg1","9665...":"Msg2"}

Example Usage

DreamSms::sendMulti([
    '966512345678' => 'Hello Alice',
    '966512345679' => 'Hello Bob',
], 'MySender');

Response

Same format as single sendSms response.

4. Error Handling

Catch DreamSms\LaravelDreamSms\Exceptions\DreamSmsException to manage HTTP or API errors:

try {
    DreamSms::sendSms(...);
} catch (DreamSmsException $e) {
    report($e);
    // handle or display $e->getMessage()
}

6. Contributions

1. Fork and clone
2. Create a branch feature/your-feature
3. Write tests & code
4. Submit a PR

Please follow PSR-12 and include tests for new methods.

7. License

MIT. See LICENSE.