safer/peykad

Laravel SDK for Peykad SMS API

Maintainers

Package info

github.com/saferproject/PeykadSDK

pkg:composer/safer/peykad

Transparency log

Statistics

Installs: 7

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

Security

Advisories: 0

Aikido package health analysis

v1.0.4 2026-08-03 10:08 UTC

Requires

Requires (Dev)

MIT f3068a11cb3c4e847f2e8632625cbdf9546f2494

smslaravelpeykad

Published on Packagist.org on 2026-08-03 10:08 UTC

This package is not auto-updated.

Last update: 2026-08-04 08:24:31 UTC

README

Tests PHP 8.1+ Laravel 10–13 License: MIT

A simple, defensive Laravel client for Peykad's developer SMS API. It supports Laravel 10, 11, 12, and 13 on PHP 8.1 or newer.

English · فارسی

Menu

Version support

Peykad SDK v2 supports the following Laravel and PHP combinations:

Laravel Compatible PHP versions Package CI Upstream framework status
10.x 8.1, 8.2, 8.3 Yes Upstream security support ended February 4, 2025
11.x 8.2, 8.3, 8.4 Yes Upstream security support ended March 12, 2026
12.x 8.2, 8.3, 8.4, 8.5 Yes Security fixes until February 24, 2027
13.x 8.3, 8.4, 8.5 Yes Security fixes until March 17, 2028

The package-level Composer requirement is PHP ^8.1. The installed Laravel major determines the effective PHP requirement, so PHP 8.1 can be used only with Laravel 10. Composer automatically selects a compatible combination.

Laravel 10 and 11 remain package-compatible for existing applications, but their official security-support periods have ended. New security-sensitive projects should use Laravel 12 or 13 and a PHP branch currently supported by the PHP project. Laravel 14 will be added only after its stable release passes this package's CI.

Compatibility dates come from the official Laravel support policy and PHP supported versions pages.

Installation

composer require safer/peykad

Laravel discovers the service provider automatically. Publish the configuration file when you want to customize its values:

php artisan vendor:publish --tag=peykad

The legacy peykad publish tag is also supported.

Configuration

Add your Peykad developer credentials to .env:

PEYKAD_USERNAME=your-developer-username
PEYKAD_PASSWORD=your-developer-password

The endpoint and network limits have secure defaults and can be changed when needed:

PEYKAD_SMS_URL=https://api.peykad.ir/api/developer/send_message
PEYKAD_TIMEOUT=10
PEYKAD_CONNECT_TIMEOUT=5

After changing environment values in a cached production application, run php artisan config:cache again.

Do not enable PEYKAD_ALLOW_INSECURE_HTTP in production. It exists only for isolated local HTTP test servers; HTTPS and certificate verification are otherwise enforced.

Sending a message

Use the facade for the shortest call:

use Peykad\Facades\Peykad;

$response = Peykad::send(
    '09121234567',
    'Your verification code is 123456'
);

Multiple receiver values are supported:

$response = Peykad::send(
    ['09121234567', '09351234567'],
    'Service announcement'
);

Pass the optional send_time value as the third argument. It must contain at most 11 digits:

$response = Peykad::send(
    ['09121234567', '09351234567'],
    'Scheduled message',
    1800000000
);

The SDK sends this JSON body to the configured URL:

{
    "receiver_phones": ["09121234567", "09351234567"],
    "username": "configured-username",
    "password": "configured-password",
    "text": "Scheduled message",
    "send_time": 1800000000
}

receiver_phones, username, password, and text are always sent. send_time is omitted when it is not supplied. On success, send() returns the complete decoded JSON response as an array.

You can also inject the singleton service:

use Peykad\Services\SmsService;

final class SendLoginCode
{
    public function __construct(private SmsService $sms)
    {
    }

    public function handle(string $mobile, string $code): array
    {
        return $this->sms->send($mobile, "Login code: {$code}");
    }
}

Complete API error responses

Every non-2xx HTTP response throws ApiException. The exception retains the entire Laravel HTTP response, so validation errors and other API details remain available:

use Peykad\Exceptions\ApiException;
use Peykad\Exceptions\ConfigurationException;
use Peykad\Exceptions\PeykadException;
use Peykad\Exceptions\UnexpectedResponseException;
use Peykad\Exceptions\ValidationException;

try {
    $result = Peykad::send($receivers, $text, $sendTime);
} catch (ValidationException $exception) {
    // The local arguments are empty or structurally invalid.
} catch (ConfigurationException $exception) {
    // Credentials, URL, or timeout configuration is invalid.
} catch (UnexpectedResponseException $exception) {
    // A 2xx response was returned, but its body was not JSON data.
    $body = $exception->responseBody();
} catch (ApiException $exception) {
    $status = $exception->statusCode();       // e.g. 422, or null on connection failure
    $data = $exception->responseData();       // decoded JSON, including Laravel errors
    $body = $exception->responseBody();       // complete raw response body
    $headers = $exception->responseHeaders(); // complete response headers
    $response = $exception->response();       // Illuminate\Http\Client\Response|null

    $receiverErrors = $data['errors']['receiver_phones'] ?? [];
}

All package exceptions implement PeykadException, so applications that do not need separate handling can catch that interface once:

try {
    $result = Peykad::send($receivers, $text);
} catch (PeykadException $exception) {
    report($exception);
}

Checking credit balance

You can check your Peykad account credit using the credit() method.

The method requires the developer username and password and returns the complete decoded API response:

use Peykad\Facades\Peykad;

$response = Peykad::credit(
    'your-developer-username',
    'your-developer-password'
);

No automatic retry is performed. Retrying a message submission after an uncertain connection failure could deliver the same SMS twice. Add retries at the application level only when your workflow has an idempotency guarantee.

Security

  • Developer credentials are loaded from configuration and sent only in the request JSON body.
  • HTTPS and TLS certificate verification are enabled by default.
  • Redirects are disabled so credentials cannot be forwarded to another URL.
  • Connection and total request durations are bounded.
  • URLs, credentials, receiver structure, message text, and send_time are validated before network access.
  • On PHP 8.2 and newer, phone numbers, message text, and configuration are marked as sensitive PHP parameters so exception stack traces redact them.

Never commit real credentials or log the request payload because it contains credentials, receiver phone numbers, and message text. Report vulnerabilities privately according to SECURITY.md.

Testing

composer install
composer test
composer audit --locked
composer validate --strict

Consuming applications can use Laravel's HTTP fake without making a live API request:

use Illuminate\Support\Facades\Http;

Http::fake([
    'api.peykad.ir/*' => Http::response(['id' => 'test-message']),
]);

راهنمای فارسی

این پکیج برای ارسال پیامک از طریق API توسعه‌دهندگان پیکاد در لاراول ۱۰، ۱۱، ۱۲ و ۱۳ و PHP 8.1 به بالا ساخته شده است.

نسخه‌های پشتیبانی‌شده

لاراول نسخه‌های PHP وضعیت
۱۰ ۸.۱، ۸.۲، ۸.۳ سازگار؛ پشتیبانی امنیتی لاراول پایان یافته است
۱۱ ۸.۲، ۸.۳، ۸.۴ سازگار؛ پشتیبانی امنیتی لاراول پایان یافته است
۱۲ ۸.۲، ۸.۳، ۸.۴، ۸.۵ پشتیبانی و تست می‌شود
۱۳ ۸.۳، ۸.۴، ۸.۵ پشتیبانی و تست می‌شود

لاراول ۱۰ و ۱۱ برای پروژه‌های قدیمی با پکیج سازگار هستند، اما دوره پشتیبانی امنیتی رسمی آن‌ها پایان یافته است. برای پروژه‌های جدید استفاده از لاراول ۱۲ یا ۱۳ و نسخه فعال PHP پیشنهاد می‌شود.

نصب و انتشار تنظیمات:

composer require safer/peykad
php artisan vendor:publish --tag=peykad

اطلاعات ورود را در .env قرار دهید:

PEYKAD_USERNAME=your-developer-username
PEYKAD_PASSWORD=your-developer-password

ارسال ساده، چند شماره و ارسال زمان‌بندی‌شده:

use Peykad\Facades\Peykad;

$result = Peykad::send('09121234567', 'متن پیامک');

$result = Peykad::send(
    ['09121234567', '09351234567'],
    'متن پیامک',
    1800000000
);

در بخش فارسی بعد از مثال‌های send اضافه کن:

دریافت اعتبار حساب

برای دریافت موجودی اعتبار حساب پیکاد می‌توانید از متد credit() استفاده کنید.

این متد فقط نام کاربری و رمز عبور توسعه‌دهنده را دریافت می‌کند:

use Peykad\Facades\Peykad;

$result = Peykad::credit(
    'your-developer-username',
    'your-developer-password'
);
PEYKAD_USERNAME=your-developer-username
PEYKAD_PASSWORD=your-developer-password
{
    "success": true,
    "message": "متن پیام",
    "data": [
      "credit": 15000
    ]
}

در خطاهای API، کلاس ApiException پرتاب می‌شود. تمام خطاهای پکیج رابط PeykadException را پیاده‌سازی می‌کنند. با متدهای statusCode()، responseData()، responseBody()، responseHeaders() و response() می‌توانید به تمام جزئیات پاسخ خطا دسترسی داشته باشید.

License

Peykad SDK is open-source software licensed under the MIT license.