Ortto SDK for Laravel

A modern, elegant Laravel SDK for the Ortto Customer Data Platform API. Built on top of Saloon, this package provides a fluent interface to interact with Ortto's REST API.

Features

• Full Ortto API coverage (People, Activities, Campaigns, and more)
• Built with Saloon for robust HTTP communication
• Laravel integration via service provider
• Type-safe requests and responses
• Comprehensive test coverage
• Modern PHP 8.4+ syntax

Requirements

• PHP 8.4 or higher
• Laravel 10.x or 11.x

Installation

Install the package via Composer:

composer require phpdevkits/ortto-sdk

Publish the configuration file:

php artisan vendor:publish --provider="PhpDevKits\Ortto\OrttoServiceProvider"

Add your Ortto API credentials to your .env file:

ORTTO_API_KEY=your-api-key-here
ORTTO_REGION=ap3  # Options: ap3 (default), au, eu

Configuration

The configuration file will be published to config/ortto.php:

return [
    'api_key' => env('ORTTO_API_KEY'),
    'region' => env('ORTTO_REGION', 'ap3'),
];

Service Endpoints

Ortto uses region-specific endpoints:

• Default (AP3): https://api.ap3api.com/ - For most Ortto users
• Australia: https://api.au1api.com/ - For AU region instances
• Europe: https://api.eu1api.com/ - For EU region instances

Usage

People Management

use PhpDevKits\Ortto\Facades\Ortto;

// Create or update a person
Ortto::people()->merge([
    'email' => 'user@example.com',
    'first_name' => 'John',
    'last_name' => 'Doe',
]);

// Get a person by email
$person = Ortto::people()->get('user@example.com');

// Delete a person
Ortto::people()->delete('user@example.com');

Activities

// Track a custom activity
Ortto::activities()->create([
    'email' => 'user@example.com',
    'activity_name' => 'product_viewed',
    'attributes' => [
        'product_id' => '12345',
        'product_name' => 'Premium Widget',
    ],
]);

Campaigns

// Send a campaign email
Ortto::campaigns()->send([
    'campaign_id' => 'your-campaign-id',
    'recipients' => [
        ['email' => 'user@example.com'],
    ],
]);

Extending the SDK

The SDK is designed to be extensible, allowing you to customize behavior for your specific needs.

Caching Responses

The SDK is built on Saloon and supports the Saloon Cache Plugin.

Cache All Requests

Extend the Ortto connector to add caching to all API requests:

use PhpDevKits\Ortto\Ortto;
use Saloon\CachePlugin\Contracts\Cacheable;
use Saloon\CachePlugin\Traits\HasCaching;
use Saloon\CachePlugin\Contracts\Driver;
use Saloon\CachePlugin\Drivers\LaravelCacheDriver;

class CachedOrtto extends Ortto implements Cacheable
{
    use HasCaching;

    public function resolveCacheDriver(): Driver
    {
        return new LaravelCacheDriver('redis');
    }

    public function cacheExpiryInSeconds(): int
    {
        return 3600; // Cache for 1 hour
    }
}

// Usage
$ortto = new CachedOrtto();
$response = $ortto->person()->get(
    fields: [PersonField::Email->value, PersonField::FirstName->value]
);
// Subsequent identical requests will use the cache

Cache Specific Requests

Extend individual request classes for granular caching control:

use PhpDevKits\Ortto\Requests\Person\GetPeople;
use Saloon\CachePlugin\Contracts\Cacheable;
use Saloon\CachePlugin\Traits\HasCaching;
use Saloon\CachePlugin\Contracts\Driver;
use Saloon\CachePlugin\Drivers\LaravelCacheDriver;

class CachedGetPeople extends GetPeople implements Cacheable
{
    use HasCaching;

    public function resolveCacheDriver(): Driver
    {
        return new LaravelCacheDriver('redis');
    }

    public function cacheExpiryInSeconds(): int
    {
        return 600; // Cache for 10 minutes
    }
}

// Usage
$ortto = new Ortto();
$response = $ortto->send(
    new CachedGetPeople(
        fields: [PersonField::Email->value]
    )
);

Custom Resource Classes

Override resource classes to add custom behavior like logging, rate limiting, or validation:

// app/Ortto/CustomPersonResource.php
namespace App\Ortto;

use PhpDevKits\Ortto\Resources\PersonResource;
use Saloon\Http\Response;
use Illuminate\Support\Facades\Log;

class CustomPersonResource extends PersonResource
{
    public function get(array $fields, ...): Response
    {
        // Add custom logic before the request
        Log::info('Fetching people with fields', ['fields' => $fields]);

        // Call the parent method
        $response = parent::get($fields, ...);

        // Add custom logic after the request
        Log::info('Fetched people', [
            'status' => $response->status(),
            'count' => count($response->json('contacts', []))
        ]);

        return $response;
    }

    // Override other methods as needed
}

Configure your custom resource in config/ortto.php:

'resources' => [
    'person' => \App\Ortto\CustomPersonResource::class,
],

Now all calls to $ortto->person() will use your custom resource:

$ortto = new Ortto();
$ortto->person()->get(...); // Uses CustomPersonResource

Advanced: Combining Caching with Custom Resources

namespace App\Ortto;

use PhpDevKits\Ortto\Resources\PersonResource;
use PhpDevKits\Ortto\Requests\Person\GetPeople;
use Saloon\CachePlugin\Contracts\Cacheable;
use Saloon\CachePlugin\Traits\HasCaching;
use Saloon\CachePlugin\Contracts\Driver;
use Saloon\CachePlugin\Drivers\LaravelCacheDriver;
use Saloon\Http\Response;

class CachedPersonResource extends PersonResource
{
    public function get(array $fields, ...): Response
    {
        // Create a cached version of GetPeople
        $request = new class(...) extends GetPeople implements Cacheable {
            use HasCaching;

            public function resolveCacheDriver(): Driver
            {
                return new LaravelCacheDriver('redis');
            }

            public function cacheExpiryInSeconds(): int
            {
                return 600;
            }
        };

        return $this->connector->send($request);
    }
}

Documentation

Browse the docs/ directory for detailed documentation:

• Introduction - Learn about Ortto SDK and its features
• Installation Guide - Get set up in minutes
• Testing Overview - Testing with Pest and Lawman
• Architecture Tests - Validate Saloon architecture with Lawman
• Mocking - Mock API responses with Saloon MockClient

API Reference

For detailed information about Ortto's API endpoints and parameters, refer to the Ortto API Documentation.

Development

Clone the repository and install dependencies:

git clone https://github.com/phpdevkits/ortto-sdk.git
cd ortto-sdk
composer install

Code Quality

Keep a modern codebase with Pint:

composer lint

Run refactors using Rector:

composer refactor

Run static analysis using PHPStan:

composer test:types

Run unit tests using PEST:

composer test:unit

Run the entire test suite:

composer test

Testing

The package includes comprehensive test coverage using PEST and Lawman for architecture testing:

composer test

Learn more about testing in our Testing Documentation.

Changelog

Please see CHANGELOG for recent changes.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please email security@example.com instead of using the issue tracker.

Credits

This package is built with modern PHP tools and frameworks:

• Laravel - The PHP framework for web artisans
• Saloon - Build beautiful API integrations
• Pest PHP - An elegant PHP testing framework
• Lawman - Architecture testing for Saloon
• PHPStan - PHP static analysis tool
• Laravel Pint - PHP code style fixer
• Rector - Instant upgrades and automated refactoring

Special thanks to:

• Ortto for their Customer Data Platform API
• Ortto API Documentation

License

The MIT License (MIT). Please see License File for more information.