PHPackages                             salavati/sapak-sms-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. salavati/sapak-sms-php

ActiveLibrary[API Development](/categories/api)

salavati/sapak-sms-php
======================

A lightweight PHP SDK for SAPAK SMS API

v1.0.0(6mo ago)021MITPHPPHP >=8.1

Since Nov 7Pushed 6mo agoCompare

[ Source](https://github.com/ali-salavati/sapak-sms)[ Packagist](https://packagist.org/packages/salavati/sapak-sms-php)[ RSS](/packages/salavati-sapak-sms-php/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (4)Versions (2)Used By (1)

Sapak SMS PHP SDK
=================

[](#sapak-sms-php-sdk)

A modern, clean, and opinionated PHP SDK for interacting with the Sapak SMS API.

This SDK is built with developers in mind, focusing on clean code principles, strong typing, and a safe, ergonomic developer experience.

> **Note:** This is an unofficial SDK.
> The official Sapak API documentation can be found at:

---

Table of Contents
-----------------

[](#table-of-contents)

- [Features](#features)
- [Installation](#installation)
- [Quick Start: Instantiation](#quick-start-instantiation)
- [Error Handling](#error-handling)
- [Usage Examples](#usage-examples)
    - [A. Get Account Credit](#a-get-account-credit)
    - [B. Send Message (One-to-Many)](#b-send-message-one-to-many)
    - [C. Send Messages (Peer-to-Peer)](#c-send-messages-peer-to-peer)
    - [D. Get Message Statuses (The Safe Way)](#d-get-message-statuses)
    - [E. Find Received Messages (Smart Date Handling)](#e-find-received-messages-smart-date-handling)
- [Testing](#testing)

---

Features
--------

[](#features)

- **Clean, Modern Interface:** Uses typed DTOs (Data Transfer Objects) instead of messy arrays.
- **Opinionated Design:** Actively prevents unsafe operations (like N+1 queries).
- **Smart Date Handling:** Accepts standard DateTime objects and automatically handles the complex Jalali conversion required by the API.
- **Robust Error Handling:** Throws custom, catchable exceptions (`ValidationException`, `AuthenticationException`) instead of generic Guzzle errors.
- **Helper Methods:** Provides "value-add" features, like constants for status codes (`STATUS_DELIVERED`) and text helpers (`getStatusText()`).
- **Fully Tested:** High test coverage to ensure reliability.

---

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require salavati/sapak-sms-php
```

---

Quick Start: Instantiation
--------------------------

[](#quick-start-instantiation)

You only need your API key to get started.

```
use Sapak\Sms\SapakClient;

$apiKey = 'YOUR_API_KEY_HERE';
$client = new SapakClient($apiKey);
```

---

Error Handling
--------------

[](#error-handling)

This SDK abstracts all HTTP errors into specific exceptions. Always wrap your calls in a `try...catch` block.

```
use Sapak\Sms\Exceptions\ValidationException;
use Sapak\Sms\Exceptions\AuthenticationException;
use Sapak\Sms\Exceptions\ApiException;

try {
    // Make an API call, e.g., $client->messages()->send(...)

} catch (ValidationException $e) {
    // 400 Bad Request or 422 Unprocessable
    // The request was malformed (e.g., missing 'text').
    echo "Validation Error: " . $e->getMessage();

} catch (AuthenticationException $e) {
    // 401 Unauthorized or 403 Forbidden
    // Your API key is likely invalid.
    echo "Auth Error: " . $e->getMessage();

} catch (ApiException $e) {
    // 500, 404, 429, or other generic errors
    echo "API Error: " . $e->getMessage();
}
```

---

Usage Examples
--------------

[](#usage-examples)

### A. Get Account Credit

[](#a-get-account-credit)

Access account information via the `account()` resource.

```
// Returns a DTO, not a raw number
$creditDto = $client->account()->getCredit();

echo "Your credit is: " . $creditDto->credit . " Rials";
```

### B. Send Message (One-to-Many)

[](#b-send-message-one-to-many)

Use the `SendMessage` DTO to prepare your request. This provides client-side validation.

```
use Sapak\Sms\DTOs\Requests\SendMessage;

$message = new SendMessage(
    from: '985000...',
    to: ['98912...', '98913...'],
    text: 'This is a test message.'
);

// You can also schedule it (must be an ATOM/RFC3339 string)
$futureDate = (new \DateTime('+10 minutes'))->format(\DateTime::ATOM);
$scheduledMessage = new SendMessage(
    from: '985000...',
    to: ['98912...'],
    text: 'A scheduled message.',
    sendAt: $futureDate
);

$results = $client->messages()->send($message);

echo "Message submitted. ID: " . $results[0]->id;
echo "Status code: " . $results[0]->status;
```

### C. Send Messages (Peer-to-Peer)

[](#c-send-messages-peer-to-peer)

Create an array of `SendPeerToPeer` DTOs.

```
use Sapak\Sms\DTOs\Requests\SendPeerToPeer;

$p2p_messages = [
    new SendPeerToPeer(
        sender: '985000...',
        recipient: '98912...',
        message: 'Hello, User 1.'
    ),
    new SendPeerToPeer(
        sender: '985000...',
        recipient: '98935...',
        message: 'Hello, User 2.'
    )
];

$results = $client->messages()->sendPeerToPeer($p2p_messages);
```

### D. Get Message Statuses

[](#d-get-message-statuses)

To prevent N+1 API requests, this SDK only supports checking statuses in a batch. If you need to check only one ID, pass it as an array: `getStatuses([12345])`.

```
use Sapak\Sms\DTOs\Responses\SentMessageStatus;

$messageIds = [12345, 12346, 12347];

$statuses = $client->messages()->getStatuses($messageIds);

foreach ($statuses as $status) {
    echo "ID: " . $status->id . " has status code: " . $status->status . "\n";

    // Use the built-in constants for safe checking (No Magic Numbers!)
    if ($status->status === SentMessageStatus::STATUS_DELIVERED) {
        echo "Message {$status->id} was delivered!\n";
    }

    // Use the helper method for a human-readable text
    echo "Meaning: " . $status->getStatusText() . "\n";
}
```

### E. Find Received Messages (Smart Date Handling)

[](#e-find-received-messages-smart-date-handling)

Pass standard `DateTimeInterface` objects. The SDK handles the complex Jalali conversion for you.

> **Note on Date Handling:**
> The Sapak API requires a non-standard Jalali string format (`YYYY-MM-DD HH:mm:ss`). Instead of forcing you to handle this, the SDK does the work. It accepts standard PHP `DateTimeInterface` objects (Gregorian) and automatically converts them to the required Jalali format for the request. It also converts the Jalali date strings in the response back to standard `DateTimeImmutable` objects.

```
use Sapak\Sms\DTOs\Requests\FindMessages;

$filters = new FindMessages(
    pageNumber: 1,
    pageSize: 20,
    fromDate: new \DateTime('-3 days'), // find($filters);

// The DTO converts the API's Jalali string back to DateTimeImmutable!
foreach ($receivedMessages as $message) {
    echo "From: " . $message->fromNumber . "\n";
    echo "Text: " . $message->body . "\n";
    echo "Received At: " . $message->date->format('Y-m-d H:i:s') . "\n";
}
```

---

Testing
-------

[](#testing)

To run the test suite, clone the repository, install dependencies, and run PHPUnit:

```
git clone https://github.com/ali-salavati/sapak-sms.git
cd sapak-sms-php
composer install
composer test
```

###  Health Score

33

—

LowBetter than 74% of packages

Maintenance73

Regular maintenance activity

Popularity2

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity43

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

183d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/31b75c8cf97d1a168d01c49d000f13a9066ccade69c3f577ce866c46fdad7766?d=identicon)[ali.salavati](/maintainers/ali.salavati)

---

Top Contributors

[![ali-salavati](https://avatars.githubusercontent.com/u/81990398?v=4)](https://github.com/ali-salavati "ali-salavati (33 commits)")

---

Tags

phpapisdksmssapak

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/salavati-sapak-sms-php/health.svg)

```
[![Health](https://phpackages.com/badges/salavati-sapak-sms-php/health.svg)](https://phpackages.com/packages/salavati-sapak-sms-php)
```

###  Alternatives

[openai-php/laravel

OpenAI PHP for Laravel is a supercharged PHP API client that allows you to interact with the Open AI API

3.7k7.6M74](/packages/openai-php-laravel)[hubspot/api-client

Hubspot API client

23414.2M16](/packages/hubspot-api-client)[php-opencloud/openstack

PHP SDK for OpenStack APIs. Supports BlockStorage, Compute, Identity, Images, Networking and Metric Gnocchi

2292.2M23](/packages/php-opencloud-openstack)[mailchimp/transactional

458.9M16](/packages/mailchimp-transactional)[resend/resend-php

Resend PHP library.

564.7M21](/packages/resend-resend-php)[checkout/checkout-sdk-php

Checkout.com SDK for PHP

553.3M7](/packages/checkout-checkout-sdk-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)