tigusigalpa/easyship-php

Modern PHP/Laravel client for EasyShip API with full endpoint coverage

v1.0.0 2026-02-16 16:00 UTC

Requires

• php: ^8.1
• ext-json: *
• guzzlehttp/guzzle: ^7.0

Requires (Dev)

• laravel/pint: ^1.0
• mockery/mockery: ^1.5
• orchestra/testbench: ^8.0|^9.0
• phpunit/phpunit: ^10.0

MIT

• Igor Sazonov

• api
• laravel
• shipping
• logistics
• easyship

README

Modern, fully-featured PHP/Laravel client for the EasyShip API with complete endpoint coverage (348+ endpoints).

Features

• ✅ Complete API Coverage - All 348+ EasyShip API endpoints implemented
• ✅ Modern PHP - Built for PHP 8.1+ with strict typing
• ✅ Laravel Integration - Service Provider, Facade, and configuration
• ✅ Webhook Support - Full webhook handling with signature verification
• ✅ OAuth 2.0 - Complete OAuth flow for partner integrations
• ✅ Exception Handling - Typed exceptions for different error scenarios
• ✅ Retry Logic - Automatic retry for transient failures
• ✅ Sandbox/Production - Easy environment switching
• ✅ PSR-4 Autoloading - Follows PSR-12 coding standards
• ✅ Well Documented - Comprehensive PHPDoc comments

Requirements

• PHP 8.1 or higher
• Laravel 9, 10, 11, or 12 (optional)
• Guzzle HTTP Client 7.0+

Installation

Install via Composer:

composer require tigusigalpa/easyship-php

Configuration

Standalone PHP

use Tigusigalpa\EasyShip\EasyShipClient;

$client = new EasyShipClient([
    'api_token' => 'sand_xxxxxxxxxxxxxxxx', // or prod_xxxxxxxxxxxxxxxx
    'timeout' => 30,
    'retry' => 3,
]);

Laravel

1. Publish the configuration file:

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

1. Add your API token to .env:

EASYSHIP_API_TOKEN=sand_xxxxxxxxxxxxxxxx
EASYSHIP_TIMEOUT=30
EASYSHIP_RETRY=3

1. Use the Facade or dependency injection:

use Tigusigalpa\EasyShip\Laravel\Facades\EasyShip;

// Using Facade
$shipments = EasyShip::shipments()->list();

// Using Dependency Injection
use Tigusigalpa\EasyShip\EasyShipClient;

class ShippingController extends Controller
{
    public function __construct(private EasyShipClient $easyship)
    {
    }

    public function index()
    {
        $shipments = $this->easyship->shipments()->list();
    }
}

Quick Start

Create a Shipment

$shipment = $client->shipments()->create([
    'platform_name' => 'Custom',
    'platform_order_number' => 'ORDER-001',
    'destination_address' => [
        'line_1' => '123 Main St',
        'city' => 'New York',
        'state' => 'NY',
        'postal_code' => '10001',
        'country_code' => 'US',
        'contact_name' => 'John Doe',
        'contact_phone' => '[phone]',
        'contact_email' => '[e-mail]',
    ],
    'items' => [
        [
            'description' => 'T-Shirt',
            'sku' => 'TSHIRT-001',
            'quantity' => 2,
            'declared_currency' => 'USD',
            'declared_customs_value' => 25.00,
            'actual_weight' => 0.5,
        ],
    ],
]);

Get Shipping Rates

$rates = $client->rates()->calculate([
    'origin_country_code' => 'US',
    'origin_postal_code' => '90001',
    'destination_country_code' => 'GB',
    'destination_postal_code' => 'SW1A 1AA',
    'items' => [
        [
            'actual_weight' => 1.5,
            'height' => 10,
            'width' => 10,
            'length' => 10,
            'declared_currency' => 'USD',
            'declared_customs_value' => 50.00,
        ],
    ],
]);

List Shipments

$shipments = $client->shipments()->list([
    'page' => 1,
    'per_page' => 50,
    'status' => 'delivered',
]);

Track a Shipment

$tracking = $client->trackings()->show('TRACKING_NUMBER');

API Modules

The client provides access to all EasyShip API resources through dedicated modules:

Account & Settings

• account() - Account information
• settings() - Account settings management

Addresses

• addresses() - Address management and validation

Analytics

• analytics() - Analytics and reporting data

Shipments

• shipments() - Create, update, and manage shipments
• rates() - Get shipping rates
• trackings() - Track shipments
• labels() - Generate shipping labels

Couriers

• couriers() - Courier management
• courierServices() - Courier service information

Products & Inventory

• products() - Product catalog management
• boxes() - Box/packaging management

Pickups

• pickups() - Schedule and manage pickups

Financial

• credit() - Credit management
• paymentSources() - Payment source management
• billingDocuments() - Billing document access
• transactionRecords() - Transaction history

Webhooks

• webhooks() - Webhook configuration

Organizations & Companies

• organizations() - Organization management
• companies() - Company management

Shipping Rules

• shippingRules() - Automated shipping rule configuration

Other Resources

• batches() - Batch operations
• manifests() - Manifest generation
• insurancePolicies() - Insurance management
• taxesAndDuties() - Tax and duty calculations
• stores() - Store integrations
• tags() - Tag management
• locations() - Drop-off location finder

Webhooks

Setting Up Webhook Handler

use Tigusigalpa\EasyShip\Webhooks\WebhookHandler;
use Tigusigalpa\EasyShip\Webhooks\WebhookVerifier;

$verifier = new WebhookVerifier('your-webhook-secret');
$handler = new WebhookHandler($verifier);

// In your webhook endpoint
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_EASYSHIP_SIGNATURE'] ?? '';

try {
    $event = $handler->handle($payload, $signature);
    
    // Handle different event types
    if ($event instanceof \Tigusigalpa\EasyShip\Webhooks\Events\ShipmentCreated) {
        $shipmentId = $event->getShipmentId();
        // Handle shipment created
    }
} catch (\Tigusigalpa\EasyShip\Exceptions\EasyShipException $e) {
    // Invalid signature or malformed payload
    http_response_code(400);
}

Laravel Webhook Example

// routes/api.php
Route::post('/webhooks/easyship', [WebhookController::class, 'handle']);

// app/Http/Controllers/WebhookController.php
use Tigusigalpa\EasyShip\Webhooks\WebhookHandler;
use Tigusigalpa\EasyShip\Webhooks\WebhookVerifier;

class WebhookController extends Controller
{
    public function handle(Request $request)
    {
        $verifier = new WebhookVerifier(config('easyship.webhook_secret'));
        $handler = new WebhookHandler($verifier);
        
        $event = $handler->handle(
            $request->getContent(),
            $request->header('X-Easyship-Signature')
        );
        
        event(new EasyShipWebhookReceived($event));
        
        return response()->json(['status' => 'success']);
    }
}

OAuth 2.0

For partner integrations using OAuth:

// Step 1: Redirect user to authorization URL
$authUrl = "https://app.easyship.com/oauth/authorize?" . http_build_query([
    'client_id' => 'your-client-id',
    'redirect_uri' => 'https://yourapp.com/callback',
    'response_type' => 'code',
    'scope' => 'shipments:read shipments:write',
]);

// Step 2: Exchange authorization code for access token
$token = $client->oauth()->createAccessToken([
    'grant_type' => 'authorization_code',
    'code' => $authorizationCode,
    'client_id' => 'your-client-id',
    'client_secret' => 'your-client-secret',
    'redirect_uri' => 'https://yourapp.com/callback',
]);

// Step 3: Use the access token
$client = new EasyShipClient([
    'api_token' => $token['access_token'],
]);

Error Handling

The library provides typed exceptions for different error scenarios:

use Tigusigalpa\EasyShip\Exceptions\AuthenticationException;
use Tigusigalpa\EasyShip\Exceptions\ValidationException;
use Tigusigalpa\EasyShip\Exceptions\RateLimitException;
use Tigusigalpa\EasyShip\Exceptions\ApiException;

try {
    $shipment = $client->shipments()->create($data);
} catch (AuthenticationException $e) {
    // Invalid API token (401)
    echo "Authentication failed: " . $e->getMessage();
} catch (ValidationException $e) {
    // Validation errors (422)
    echo "Validation failed: " . $e->getMessage();
    print_r($e->getErrors());
} catch (RateLimitException $e) {
    // Rate limit exceeded (429)
    echo "Rate limit exceeded. Please try again later.";
} catch (ApiException $e) {
    // Other API errors
    echo "API error: " . $e->getMessage();
}

Environment Switching

The library automatically detects sandbox vs production based on your API token prefix:

• Tokens starting with sand_ use the sandbox environment
• Tokens starting with prod_ use the production environment

// Sandbox
$client = new EasyShipClient([
    'api_token' => 'sand_xxxxxxxxxxxxxxxx',
]);

// Production
$client = new EasyShipClient([
    'api_token' => 'prod_xxxxxxxxxxxxxxxx',
]);

Testing

Run the test suite:

composer test

API Documentation

For detailed API documentation, visit:

• EasyShip API Reference
• EasyShip Developer Portal

Changelog

Please see CHANGELOG for recent changes.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Security

If you discover any security-related issues, please email [e-mail] instead of using the issue tracker.

Credits

• Igor Sazonov

License

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

Support

For support, please:

• Check the EasyShip API Documentation
• Open an issue on GitHub
• Contact: [e-mail]