gophr-app-inc/gophr-bridge-php

PHP SDK for interacting with the Gophr Bridge API - delivery and logistics management

v1.0.5 2025-09-24 16:41 UTC

Requires

• php: ^8.0
• guzzlehttp/guzzle: ^7.0

Requires (Dev)

• phpunit/phpunit: ^9.0|^10.0
• squizlabs/php_codesniffer: ^3.6

proprietary

• Gophr Engineering

• api
• sdk
• Bridge
• shipping
• delivery
• logistics
• courier
• gophr

README

A simple, lightweight PHP SDK for interacting with the Gophr Bridge API. This SDK provides easy-to-use methods for getting delivery quotes and creating shipments.

Installation

Install the pa#### Shipment Helper Methods

Object-Oriented Approach (Recommended):

### Main Methods

#### `getQuote(array $quoteData): GophrQuote`
Get a delivery quote.

**Parameters:**
- `$quoteData` - Array with quote request data

**Returns:** `GophrQuote` object with convenient accessors

#### `createShipment(array $shipmentData): GophrShipment`
Create a shipment using a quote ID (returns `GophrShipment`).

**Parameters:**
- `$shipmentData` - Array with shipment creation data

**Returns:** `GophrShipment` object with convenient accessors

### GophrQuote and GophrShipment

The SDK now returns typed wrapper objects for responses:

- `GophrQuote` — use `isSuccessful()`, `getStandardQuoteId()`, `getStandardQuoteFee()`, `getSummary()`, etc.
- `GophrShipment` — use `getDeliveryId()`, `getDeliveryStatus()`, `getShippingFee()`, `isSuccessful()`, etc.

These objects provide a clear, object-oriented API and replace the previous array-based helper methods.
$gophr = new GophrBridge([
    'clientId' => 'your_client_id',
    'clientSecret' => 'your_client_secret',
    'testing' => true // true for development, false for production
]);

// Get a quote
$quote = $gophr->getQuote([
    'first_name' => 'John',
    'last_name' => 'Doe',
    'phone' => '5555555555',
    'email' => '[e-mail]',
    'address_1' => '1000 Ryan St',
    'city' => 'Lake Charles',
    'state' => 'LA',
    'zip' => '70602',
    'country' => 'US',
    'items' => [[
        'quantity' => 1,
        'name' => 'Test Item',
        'weight' => 1
    ]]
]);

echo "Standard fee: $" . ($quote->getStandardQuoteFee() ?? 'N/A');

// Create shipment with clean object interface
$quoteId = $quote->getStandardQuoteId();
$shipment = $gophr->createShipment(['quote_id' => $quoteId]);

echo "Delivery ID: " . ($shipment->getDeliveryId() ?? 'N/A') . PHP_EOL;
echo "Status: " . ($shipment->getDeliveryStatus() ?? 'N/A') . PHP_EOL;

Getting Started Quickly

# 1. Install the SDK
composer require gophr-app-inc/gophr-bridge-php

# 2. Create a basic example file
cat > gophr-test.php << 'EOF'
<?php
require_once 'vendor/autoload.php';

use GophrAppInc\GophrBridgePhp\GophrBridge;

$gophr = new GophrBridge([
    'clientId' => 'your_client_id',
    'clientSecret' => 'your_client_secret',
    'testing' => true // development API
]);

try {
    $quote = $gophr->getQuote([
        'first_name' => 'John',
        'last_name' => 'Doe',
        'phone' => '5555555555',
        'email' => '[e-mail]',
        'address_1' => '1000 Ryan St',
        'city' => 'Lake Charles',
        'state' => 'LA',
        'zip' => '70602',
        'country' => 'US',
        'items' => [['quantity' => 1, 'name' => 'Test Item', 'weight' => 1]]
    ]);
    
    echo "Standard fee: $" . ($quote->getStandardQuoteFee() ?? 'N/A');
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}
EOF

# 3. Add your credentials and run
php gophr-test.php

Requirements

• PHP 8.0 or higher
• Guzzle HTTP client (automatically installed)

API Environments

The SDK automatically selects the appropriate API endpoint based on the testing configuration:

• Development/Testing (testing: true): https://dev-api-bridge.gophr.app
• Production (testing: false): https://api-bridge.gophr.app

The testing parameter defaults to true if not specified, ensuring safe development by default.

Configuration

Environment Variables

Create a .env file in your project root:

GOPHR_CLIENT_ID=your_client_id
GOPHR_CLIENT_SECRET=your_client_secret
GOPHR_TESTING=true

SDK Initialization

use GophrAppInc\GophrBridgePhp\GophrBridge;

$gophr = new GophrBridge([
    'clientId' => 'your_client_id',
    'clientSecret' => 'your_client_secret',
    'testing' => true // true for development API, false for production API
]);

Usage

Getting a Quote

$quote = $gophr->getQuote([
    'first_name' => 'John',
    'last_name' => 'Doe',
    'phone' => '5555555555',
    'email' => '[e-mail]',
    'address_1' => '123 Main St',
    'address_2' => 'Apt 4B', // optional
    'city' => 'New York',
    'state' => 'NY',
    'zip' => '10001',
    'country' => 'US',
    'pick_up_instructions' => 'Ring the bell', // optional
    'drop_off_instructions' => 'Leave with doorman', // optional
    'scheduled_for' => null, // null for ASAP, or 'YYYY-MM-DD' for scheduled
    'items' => [
        [
            'quantity' => 2,
            'name' => 'Documents',
            'sku' => 'DOC-001', // optional
            'weight' => 1
        ]
    ]
]);

Creating a Shipment

// Get quote ID from previous quote
$quoteId = $quote->getStandardQuoteId();

// Create shipment (returns a GophrShipment object)
$shipment = $gophr->createShipment([
    'quote_id' => $quoteId,
    'drop_off_instructions' => 'Call when arriving' // optional
]);

// Now you can call methods directly on the shipment object
$deliveryId = $shipment->getDeliveryId();
$status = $shipment->getDeliveryStatus();
$fee = $shipment->getShippingFee();
$isSuccessful = $shipment->isSuccessful();

// Option 2: Traditional array approach (backward compatibility)
$shipmentData = $gophr->createShipment([
    'quote_id' => $quoteId,
    'drop_off_instructions' => 'Call when arriving'
]);
// Then use helper methods: $gophr->getDeliveryId($shipmentData)

Using Helper Methods

The SDK provides numerous helper methods to safely extract data from responses:

Quote Helper Methods

// Check if request was successful
$success = $quote->isSuccessful();

// Extract quote information
$standardFee = $quote->getStandardQuoteFee();
$expeditedFee = $quote->getExpeditedQuoteFee();
$standardQuoteId = $quote->getStandardQuoteId();
$expeditedQuoteId = $quote->getExpeditedQuoteId();

// Get formatted summary
$summary = $quote->getSummary();
/*
Returns:
[
    'success' => true,
    'standard' => [
        'quoteId' => 'quote_123',
        'fee' => 15.50
    ],
    'expedited' => [
        'quoteId' => 'quote_456',
        'fee' => 25.00
    ]
]
*/

Building Quote Data with Helper Method

For more structured data creation, use the buildQuoteData helper:

$customerInfo = [
    'firstName' => 'Jane',
    'lastName' => 'Smith',
    'phone' => '5555551234',
    'email' => '[e-mail]'
];

$addressInfo = [
    'address1' => '123 Main St',
    'address2' => 'Apt 4B',
    'city' => 'New York',
    'state' => 'NY',
    'zip' => '10001',
    'country' => 'US'
];

$items = [
    [
        'quantity' => 1,
        'name' => 'Books',
        'weight' => 5
    ]
];

$options = [
    'pickupInstructions' => 'Call when arriving',
    'dropoffInstructions' => 'Ring apartment buzzer',
    'scheduledFor' => null // ASAP
];

$quoteData = $gophr->buildQuoteData($customerInfo, $addressInfo, $items, $options);
$quote = $gophr->getQuote($quoteData);

Accessing Full Response Data

For complete access to response data:

// Get full payloads via wrapper objects
$quotePayload = $quote->getPayload();
$shipmentPayload = $shipment->getRawData();

// Access any property directly
$coordinates = $shipmentPayload['pick_up']['lat'] ?? null;

Error Handling

The SDK uses typed exceptions for different error scenarios:

use GophrAppInc\GophrBridgePhp\Exceptions\GophrBridgeException;
use GophrAppInc\GophrBridgePhp\Exceptions\ApiException;
use GophrAppInc\GophrBridgePhp\Exceptions\NetworkException;

try {
    $quote = $gophr->getQuote($quoteData);
} catch (ApiException $e) {
    // API returned an error response
    echo "API Error: " . $e->getMessage();
    $details = $e->getDetails();
    echo "Status: " . $details['status'];
} catch (NetworkException $e) {
    // Network connectivity issue
    echo "Network Error: " . $e->getMessage();
} catch (GophrBridgeException $e) {
    // General SDK error (configuration, etc.)
    echo "SDK Error: " . $e->getMessage();
}

Formatted Error Logging

Use the built-in error logger for detailed error information:

try {
    $quote = $gophr->getQuote($quoteData);
} catch (GophrBridgeException $e) {
    GophrBridge::logError($e);
}

This will output formatted error information including status codes, URLs, and response details.

Examples

Complete Working Example

See examples/complete-example.php for a comprehensive example that demonstrates:

• Getting quotes
• Creating shipments
• Using all helper methods
• Error handling
• Advanced usage patterns

Simple Example

See examples/simple-example.php for a minimal working example.

Running Examples

1. Copy .env.example to .env and fill in your credentials
2. Install dependencies: composer install
3. Run the example: php examples/complete-example.php

Development

Installing Dependencies

composer install

Running Tests

composer test

Code Style

# Check code style
composer cs-check

# Fix code style
composer cs-fix

API Reference

Main Methods

getQuote(array $quoteData): array

Get a delivery quote.

Parameters:

• $quoteData - Array with quote request data

Returns: Quote response array

createShipment(array $shipmentData): array

Create a shipment using a quote ID (returns raw array).

Parameters:

• $shipmentData - Array with shipment creation data

Returns: Shipment response array

createShipment(array $shipmentData): GophrShipment

Create a shipment using a quote ID (returns a GophrShipment object with convenient methods).

Parameters:

• $shipmentData - Array with shipment creation data

Returns: GophrShipment object with convenient methods

Helper Methods

Quote Helpers (object API)

• Use the GophrQuote object methods instead of legacy array helpers:
  • $quote->isSuccessful(): bool
  • $quote->getStandardQuoteId(): ?string
  • $quote->getExpeditedQuoteId(): ?string
  • $quote->getStandardQuoteFee(): ?float
  • $quote->getExpeditedQuoteFee(): ?float
  • $quote->getSummary(): array
  • $quote->getPayload(): ?array

Shipment Helpers (object API)

• Use the GophrShipment object methods instead of legacy array helpers:
  • $shipment->getDeliveryId(): string|int|null
  • $shipment->getDeliveryStatus(): ?string
  • $shipment->getShippingFee(): ?float
  • $shipment->getVehicleType(): ?string
  • $shipment->getDistance(): ?float
  • $shipment->getShipmentWeight(): ?float
  • $shipment->isExpedited(): bool
  • $shipment->getScheduledFor(): ?string
  • $shipment->getPickupAddress(): ?array
  • $shipment->getDeliveryAddress(): ?array
  • $shipment->getRawData(): array (full payload)
  • $shipment->getTrackingUrl(): ?string
  • $shipment->isSuccessful(): bool
  • $shipment->getErrorMessage(): ?string

GophrShipment Class

The GophrShipment class provides a clean, object-oriented interface for working with shipment data.

Creating a GophrShipment

// Create from the bridge (recommended)
$shipment = $gophr->createShipment(['quote_id' => $quoteId]);

// Or manually from array data
$shipment = new GophrShipment($shipmentResponseArray);

Available Methods

• getDeliveryId(): string|int|null - Get delivery ID
• getDeliveryStatus(): string|null - Get current status
• getShippingFee(): float|null - Get shipping fee
• getVehicleType(): string|null - Get assigned vehicle type
• getDistance(): float|null - Get delivery distance
• getShipmentWeight(): float|null - Get package weight
• isExpedited(): bool - Check if expedited delivery
• getScheduledFor(): string|null - Get scheduled delivery time
• getPickupAddress(): array|null - Get pickup address
• getDeliveryAddress(): array|null - Get delivery address
• getTrackingUrl(): string|null - Get tracking URL
• isSuccessful(): bool - Check if shipment was successful
• getErrorMessage(): string|null - Get error message if failed
• getRawData(): array - Get original response array
• toArray(): array - Convert to array (for compatibility)

Package Distribution

// (see GophrShipment::getRawData() for access to full shipment payload)

Utility Methods

• buildQuoteData(array $customerInfo, array $addressInfo, array $items, array $options = []): array
• static logError(\Exception $error): void

Package Distribution

This package uses multiple methods to ensure only necessary files are distributed via Packagist:

1. files array in composer.json - Explicitly includes only essential files
2. .gitattributes - Excludes development files using export-ignore

Included in Package:

• src/ - Main SDK code
• examples/ - Usage examples
• README.md - Documentation
• LICENSE - License file
• CHANGELOG.md - Version history

Excluded from Package:

• Tests and test configuration
• CI/CD pipeline files
• Development documentation
• IDE configuration files
• Environment templates

License

This software is proprietary and licensed only to Gophr customers. See LICENSE file for complete terms.

Requires a valid Gophr customer account and API credentials. Contact [e-mail] for access.

Support

For issues and questions:

• Create an issue on GitHub
• Contact: [e-mail]

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

See DEPLOYMENT.md for information about the release process and CI/CD pipeline.

Deployment

This package uses automated deployment via Bitbucket Pipelines to Packagist. See DEPLOYMENT.md for detailed setup and release instructions.

Changelog

1.0.0

• Initial release
• Full API coverage
• Comprehensive helper methods
• Error handling
• Documentation and examples