README

Official PHP SDK for the Nashra API.

Requirements

PHP 8.2+
Laravel 11 or 12

Installation

composer require nashra/sdk

The package auto-discovers itself. No manual provider registration needed.

Configuration

Publish the config file:

php artisan vendor:publish --tag=nashra-config

Add your API key to .env:

NASHRA_API_KEY=your-api-key
NASHRA_BASE_URL=https://app.nashra.ai/api/v1  # optional
NASHRA_TIMEOUT=30                               # optional, seconds
NASHRA_MAX_RETRIES=3                            # optional

Usage

Via Facade

use Nashra\Sdk\Facades\Nashra;

// Subscribers
$subscribers = Nashra::subscribers()->list(['search' => 'john']);
$subscriber = Nashra::subscribers()->create(['email' => 'john@example.com', 'first_name' => 'John']);
$subscriber = Nashra::subscribers()->find('uuid');
$subscriber = Nashra::subscribers()->update('uuid', ['first_name' => 'Jane']);
Nashra::subscribers()->delete('uuid');

// Tags
$tags = Nashra::tags()->list();
$tag = Nashra::tags()->create(['name' => 'VIP', 'color' => '#FF0000']);
$tag = Nashra::tags()->update('uuid', ['name' => 'Premium']);
Nashra::tags()->delete('uuid');

// Custom Fields
$fields = Nashra::fields()->list();
$field = Nashra::fields()->create([
    'field_name' => 'Company',
    'data_name' => 'company',
    'type' => 'text',
]);
$field = Nashra::fields()->update('uuid', ['is_required' => true]);
Nashra::fields()->delete('uuid');

// Segments (read-only)
$segments = Nashra::segments()->list();
$segment = Nashra::segments()->find('uuid');

Via Dependency Injection

use Nashra\Sdk\Nashra;

class SubscriberController
{
    public function __construct(private Nashra $nashra) {}

    public function index()
    {
        return $this->nashra->subscribers()->list();
    }
}

Direct Instantiation

Works outside of Laravel too:

$nashra = new \Nashra\Sdk\Nashra('your-api-key');
$nashra->subscribers()->list();

Pagination

Paginated endpoints return a PaginatedResponse that implements IteratorAggregate:

// Auto-paginate through all pages
foreach (Nashra::subscribers()->list() as $subscriber) {
    echo $subscriber->email;
}

// Work with a single page
$page = Nashra::subscribers()->list(['page' => 2, 'per_page' => 50]);
$page->items();       // Subscriber[]
$page->total();       // int
$page->currentPage(); // int
$page->lastPage();    // int
$page->hasMorePages(); // bool

Error Handling

The SDK throws typed exceptions for different error scenarios:

use Nashra\Sdk\Exceptions\AuthenticationException;
use Nashra\Sdk\Exceptions\AuthorizationException;
use Nashra\Sdk\Exceptions\NotFoundException;
use Nashra\Sdk\Exceptions\ValidationException;
use Nashra\Sdk\Exceptions\RateLimitException;
use Nashra\Sdk\Exceptions\ApiException;

try {
    Nashra::subscribers()->create(['email' => 'invalid']);
} catch (ValidationException $e) {
    $e->errors(); // ['email' => ['The email must be a valid email address.']]
} catch (AuthenticationException $e) {
    // Invalid API key (401)
} catch (AuthorizationException $e) {
    // No newsletter configured (403)
} catch (NotFoundException $e) {
    // Resource not found (404)
} catch (RateLimitException $e) {
    $e->retryAfter(); // seconds until retry
} catch (ApiException $e) {
    // Server error (5xx)
}

Data Objects

All API responses are mapped to readonly data objects:

Subscriber - email, firstName, lastName, status, tags, extraAttributes, notes
Tag - name, color
CustomField - fieldName, dataName, type, isRequired
Segment - name, subscribersCount, storedConditions

Testing

Since the SDK uses Laravel's HTTP client under the hood, you can use Http::fake() to mock API responses in your tests:

use Illuminate\Support\Facades\Http;
use Nashra\Sdk\Facades\Nashra;

Http::fake([
    '*/subscribers' => Http::response([
        'data' => [
            [
                'uuid' => 'test-uuid',
                'email' => 'john@example.com',
                'first_name' => 'John',
                'last_name' => 'Doe',
                'status' => 'subscribed',
                'tags' => [],
            ],
        ],
        'meta' => [
            'current_page' => 1,
            'last_page' => 1,
            'total' => 1,
            'per_page' => 15,
        ],
    ]),
]);

$subscribers = Nashra::subscribers()->list();

You can also mock specific scenarios like validation errors:

Http::fake([
    '*/subscribers' => Http::response([
        'error' => [
            'message' => 'Validation failed',
            'details' => ['email' => ['The email must be a valid email address.']],
        ],
    ], 422),
]);

License

MIT

nashra / sdk

Maintainers

Package info

Statistics

Security