README

ShipEngine PHP

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

Table of Contents

• Quick Start
• Examples
  • Methods
  • Class Objects
  • Instantiate ShipEngine Class
• 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 SHIPENGINE_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('PT60S')
);

$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