mivita/packages/acme-laravel-dhl/README.md

#DHL Dokuments https://developer.dhl.com/api-reference/parcel-de-shipping-post-parcel-germany-v2?language_content_entity=en#get-started-section/

DHL Laravel Package

A comprehensive Laravel package for DHL shipping, tracking, and returns functionality with direct API integration.

Features

• Direct DHL API Integration: No SDK dependencies, full control over API calls
• German Address Parsing: Automatic extraction of house numbers from German addresses
• Queue Support: Optional asynchronous processing for high-volume operations
• Comprehensive Tracking: Full tracking event history and status management
• Return Label Generation: Easy return shipment creation
• Retry Mechanisms: Built-in retry logic for API calls and file operations
• Laravel Integration: Native service providers, facades, and Eloquent models

Installation

1. Add to composer.json

{
  "repositories": [
    {
      "type": "path",
      "url": "./packages/acme-laravel-dhl"
    }
  ],
  "require": {
    "acme/laravel-dhl": "*"
  }
}

2. Install the package

composer update acme/laravel-dhl

3. Publish configuration and run migrations

php artisan vendor:publish --provider="Acme\Dhl\DhlServiceProvider" --tag="config"
php artisan migrate

Configuration

Add the following environment variables to your .env file:

# DHL API Configuration
DHL_BASE_URL=https://api-eu.dhl.com
DHL_API_KEY=your_api_key_here
DHL_USERNAME=your_username
DHL_PASSWORD=your_password
DHL_BILLING_NUMBER=your_billing_number

# DHL Default Settings
DHL_PRODUCT=V01PAK
DHL_LABEL_FORMAT=PDF
DHL_PROFILE=STANDARD_GRUPPENPROFIL

# Optional Queue Settings
DHL_USE_QUEUE=false

Usage

Creating a Shipment Label

use DHL;

$orderData = [
    'order_id' => 12345,
    'weight_kg' => 2.5,
    'shipper' => [
        'name' => 'Your Company',
        'street' => 'Musterstraße 123',  // House number will be auto-parsed
        'postalCode' => '12345',
        'city' => 'Berlin',
        'country' => 'DE'
    ],
    'consignee' => [
        'name' => 'Customer Name',
        'street' => 'Kundenstraße 456', // House number will be auto-parsed
        'postalCode' => '54321',
        'city' => 'Munich',
        'country' => 'DE'
    ]
];

$result = DHL::createLabel($orderData);
// Returns: ['shipmentNumber' => '123...', 'label_path' => 'dhl/labels/...']

German Address Parsing

The package automatically handles German address formats by extracting house numbers from the street field:

// Input: "Musterstraße 123a"
// Parsed to: street="Musterstraße", houseNumber="123a"

// Supported formats:
"Musterstraße 123"      -> street: "Musterstraße", number: "123"
"Am Markt 7"            -> street: "Am Markt", number: "7"
"Karl-Marx-Straße 156"  -> street: "Karl-Marx-Straße", number: "156"
"Lindenstraße 1-3"      -> street: "Lindenstraße", number: "1-3"
"Muster Str. 99"        -> street: "Muster Str.", number: "99"

Tracking Shipments

use DHL;

// Get current tracking status
$status = DHL::track('1234567890123');

// Returns detailed tracking information including events

Creating Return Labels

use DHL;

$returnData = [
    'original_shipment_id' => 1,
    'return_reason' => 'Customer return',
    // ... address data
];

$return = DHL::createReturn($returnData);

Using Services Directly

use Acme\Dhl\Services\ShippingService;
use Acme\Dhl\Services\TrackingService;

// Dependency injection in controllers
public function createLabel(ShippingService $shipping, Request $request)
{
    $result = $shipping->createLabel($request->validated());
    return response()->json($result);
}

Database Schema

The package creates the following tables:

• dhl_shipments - Main shipment records (outbound and returns)
• dhl_tracking_events - Tracking event history

Queue Configuration

For high-volume applications, enable queue processing:

DHL_USE_QUEUE=true

When enabled, label creation and tracking updates will be processed asynchronously.

Error Handling

The package includes comprehensive error handling:

• DhlApiException - General API errors
• DhlAuthenticationException - Authentication failures
• DhlValidationException - Data validation errors

Testing

Run the included tests:

vendor/bin/phpunit packages/acme-laravel-dhl/tests/

Address Parsing Tests

The package includes comprehensive tests for German address parsing:

vendor/bin/phpunit packages/acme-laravel-dhl/tests/Unit/AddressParserTest.php

Logging

All API calls, address parsing, and errors are logged using Laravel's logging system. Check your logs for debugging information.

License

MIT License