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