Download the PHP package kazistm/vargo without Composer

Vargo

Vargo is a unified Laravel package for integrating Algerian delivery providers. It gives you a single, consistent API to create shipments, track packages, manage locations, and access advanced provider features — regardless of which carrier is underneath.

Supports 90+ providers across Yalidine, EcoTrack, Procolis, ZR Express, Maystro, MDM, Zimou Express, Near Delivery, and many more Algerian delivery networks.

Table of Contents

• Requirements
• Installation
• Configuration
• Quick Start
• Helper Functions
• Service Manager & Facade
• Available Providers
  • Provider Families
  • Full Provider List
• Core Concepts
  • Driver Capabilities
  • Delivery Modes
  • Delivery Statuses
• Universal API
  • Shipments
  • Tracking
  • Locations
  • Labels
  • Validation
  • Returns
  • Remarks
  • Filter by Status
• Advanced Provider Features
  • ZR Express
  • Maystro
  • MDM Express
  • Zimou Express
• DTOs Reference
  • CreateShipmentData
  • TrackShipmentData
  • Response DTOs
• Enums Reference
• Status Normalization
• Checking Capabilities
• Connection Validation
• Error Handling
• Request Tracing (X-Trace-Id)
• Authentication Fields
• Architecture Overview
• Testing with Vargo

Requirements

Installation

The service provider is auto-discovered. You can publish the configuration and public logo assets using their respective tags:

Or publish both at once by referencing the service provider class:

Database & Location Data Prerequisite

Vargo uses kazistm/algeria-geo for geographic data (wilayas/communes). Make sure to publish and run migrations/seeders for the algeria-geo package to populate these tables in your database:

Configuration

The published config/delivery.php file controls which providers are available and their base URLs:

Clone Providers — providers like Samex, Guepex, or Yalitec are built on top of a parent platform (EcoTrack or Yalidine). They share the same underlying API but use a different base_url. The alias_of key declares this relationship, and driver->isAlias() returns true for these.

Quick Start

Using the delivery() Helper

Using the Facade

Switching Providers at Runtime

Service Manager & Facade

Fluent Service Manager

The DeliveryServiceManager supports a fluent interface for fine-grained control:

Facade

Helper Functions

Two global helpers are registered automatically:

Example:

Available Providers

Provider Families

Full Provider List

Tip: All 80+ provider enum cases are defined in KaziSTM\Vargo\Enums\DeliveryProviders. See COVERED-DRIVERS.md for a complete reference of all 91 supported providers and their API capabilities. Use DeliveryProviders::cases() to get all of them at runtime.

Core Concepts

Driver Capabilities

Not all providers support the same features. Vargo tracks this via the DriverCapability enum (113 cases). Check whether a driver supports a specific operation before calling it:

Common capabilities:

Delivery Modes

Each driver normalizes its own internal representation to this common enum. Use the normalization helpers on any driver:

Delivery Statuses

Vargo maps every provider's raw status to one of five canonical values:

These normalized values appear in ShipmentTrackingData::$status, ShipmentSummaryData::$status, and ShipmentEventData::$status. The $providerStatus property on the same DTOs always contains the raw, provider-specific value.

Universal API

All drivers share these methods through the InteractsWithPackages, InteractsWithLocations and related contracts.

Shipments

Create a Shipment

Accepts either a CreateShipmentData DTO or a plain array:

Update a Shipment

Delete a Shipment

List Shipments

Get a Shipment

Tracking

Get Tracking

Get Shipment History

Get Multiple Histories (Batch)

Locations

States / Wilayas

Municipalities / Communes

Stop Desk Offices

Delivery Prices

Labels

Validation

Some providers require an explicit confirmation step after creating a shipment:

Returns

Remarks

Filter by Status

For providers that support it (FILTER_ORDERS_STATUS capability), filter a list of tracking numbers down to those matching specific statuses:

Advanced Provider Features

ZR Express

ZR Express is the most feature-rich driver, supporting the full API surface: shipments, catalog, clients, claims, treasury, webhooks, pickup bags, and reports.

Authentication:

Catalog:

Clients:

Claims:

Treasury:

Pickup Bags:

Webhooks:

Reports:

Maystro

Authentication:

Catalog:

Webhooks:

MDM Express

MDM is a full-featured e-commerce and delivery platform with stores, product variants, offers, and media management.

Authentication:

Stores:

Catalog (Products, Variants, Offers):

Stats & Auth:

Zimou Express

Zimou is the most feature-complete fully-integrated driver, covering orders, employees, payments, products (incl. dropship & warehouse), stores, and miscellaneous platform utilities.

Authentication:

Standard Parcel Operations (shared with all drivers):

Orders (Zimou-native):

Products (Standard, Dropship & Warehouse):

Stores:

Payments:

Employees:

Platform Utilities:

DTOs Reference

CreateShipmentData

TrackShipmentData

Response DTOs

ShipmentActionResultData

Returned by createShipment(), deleteShipment(), validateShipment(), etc.

ShipmentTrackingData

Returned by getTracking(), getShipmentHistory(), getShipmentHistories().

ShipmentEventData

Individual timeline entry within ShipmentTrackingData::$events.

ShipmentSummaryData

Returned by listShipments(), getShipment().

CityData (Wilaya)

CommuneData

ProviderOfficeData (Stop-desk)

DeliveryPriceData

Enums Reference

DeliveryStatuses — normalized status vocabulary

DeliveryMode — delivery type

DeliveryServiceLevel — pricing tiers

DeliveryType — shipment type

HttpMethods — used internally

Status Normalization

Vargo normalizes each provider's raw shipment status into a consistent DeliveryStatuses value. Get the normalizer class for the active driver:

Each provider has a dedicated *PackagesStatus enum and a corresponding *PackageStatusNormalizer class that maps raw provider status values to the 5 canonical DeliveryStatuses values.

Checking Capabilities

Always check driver capabilities before calling optional methods:

Calling an unsupported method throws KaziSTM\Vargo\Exceptions\UnsupportedDriverFeatureException.

Connection Validation

Test whether a driver's credentials are valid against the live provider API:

This fires a real lightweight HTTP request to the provider. Use sparingly (e.g., when saving credentials in your admin panel).

Error Handling

Vargo throws typed exceptions:

Request Tracing (X-Trace-Id)

To help with debugging and tracing API requests across delivery providers, Vargo automatically generates and injects a unique trace UUID into the headers of every outgoing HTTP request:

• X-Trace-Id: A unique UUID generated per HTTP request.
• X-Provider: The slug name of the active provider.

You can inspect these headers or use them for request correlation in your logging system.

Authentication Fields

Use getAuthenticationFields() to dynamically build credential forms in your admin panel:

This allows a single dynamic form component to handle all providers.

Testing with Vargo

Vargo is built for testability. Use Laravel's Http::fake() to mock provider responses in your tests:

Package Test Helpers

The package's own test suite provides reusable helpers in tests/Support/:

Architecture Overview

For a detailed guide on the design principles, codebase structure, and trait organization, see the Vargo Architecture Guide.

Clone Pattern: 83 drivers subclass a base driver, overriding only getName() and getCompanyLogo(). All API logic is in service traits (Services/{Provider}/Traits/).

Factory Pattern: CreateShipmentDataFactory / TrackShipmentDataFactory accept both camelCase and snake_case keys and are idempotent (pass-through if already a DTO).

Capability Declaration: Each driver declares protected array $capabilities. Calling an unsupported method auto-throws UnsupportedDriverFeatureException via the HandleUnsupportedActions trait.

Location Resolution: LocationNormalizer uses a bundled LocationIndex of Algeria's 1541 communes and 58 wilayas to canonically resolve provider location strings/IDs to CityData/CommuneData.

Credential Validation: validateCredentialStructure() runs at construction time using each driver's getAuthenticationFields() rules. validateConnection() fires a lightweight live API ping, cached for 10 minutes.

Provider Capability Matrix

License

MIT — see LICENSE for details.