README

ShipEngine PHP

⚠️ WARNING: This is alpha software under active development. Caveat emptor until a 0.1.0 release is ready.

A PHP library built on the ShipEngine API offering low-level access as well as convenience methods.

Table of Contents

Quick Start
Examples
Testing
Linting
Contributing

Quick Start

Install ShipEngine via Composer:

composer require shipengine/shipengine

The only configuration requirement is an API Key.

The following example assumes that you have already set the SHIPENGIEN_API_KEY environment variable with your Api Key using putenv().

Examples

Methods

validateAddress - Indicates whether the provided address is valid. If the address is valid, the method returns a normalized version of the address based on the standards of the country in which the address resides.
normalizeAddress - Returns a normalized, or standardized, version of the address. If the address cannot be normalized, an error is returned.
trackPackage - Track a package by packageId or by carrierCode and trackingNumber. This method returns the all tracking events for a given shipment.

Class Objects

ShipEngine - A configurable entry point to the ShipEngine API SDK, this class provides convenience methods for various ShipEngine API Services.

Instantiate ShipEngine Class

<?php declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use ShipEngine\ShipEngine;

$apiKey = getenv('SHIPENGINE_API_KEY');

$shipengine = new ShipEngine($apiKey);

You can also pass the ShipEngine object an array containing configuration options instead of a string.

<?php declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use ShipEngine\ShipEngine;

$apiKey = getenv('SHIPENGINE_API_KEY');

$config = array(
    'apiKey' => $apiKey,
    'pageSize' => 75,
    'retries' => 3,
    'timeout' => \DateInterval('PT15S')
);

$shipengine = new ShipEngine($config);

Testing

You can now run all tests using PHPUnit: phpunit

composer test

Linting

You can utilize the composer script that runs phpcs, phpstan, and php-cs-fixer.

composer lint

Contributing

Contributions, enhancements, and bug-fixes are welcome! Open an issue on GitHub and submit a pull request.

We are managing php environment with Nix and Direnv, and we recommend downloading them before contributing to this project.

The quickest way to install Nix is to open a terminal and run the following command, make sure to follow the instructions output by the installation script:
```
curl -L https://nixos.org/nix/install | sh
```
Next, install Direnv using one of th methods outlined on their install page here: Direnv Installation
Lastly, you will need open your terminal and while this repository the current working directory and run direnv allow, this will allow direnv to auto-load every time you navigate to the repo. This will automatically load the Nix environment which is running the proper version of PHP and Xdebug (PHP 7.4) this repository supports/requires.
```
direnv allow
```
- You will need to cd out of the project directory after you first install direnv and run direnv allow from within the project directory, and then cd back into the project directory for direnv to auto-load the Nix environment properly.

This project also makes use of pre-commit hooks to help run lint and tests at time of commit, to leverage this you will need to install pre-commit and run the following command while in this repo:

pre-commit install

indeximstudio / shipengine

Maintainers

Details