mivita/dev/2026-05-13-dhl-modul/legacy/PAKET-INSTALLATION.md

DHL Paket Installation & Setup

1. Paket im Hauptprojekt registrieren

composer.json erweitern

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

Installation

composer update acme/laravel-dhl

2. Service Provider registrieren

config/app.php (falls Auto-Discovery nicht funktioniert)

'providers' => [
    // ...
    Acme\Dhl\DhlServiceProvider::class,
],

'aliases' => [
    // ...
    'DHL' => Acme\Dhl\Facades\DHL::class,
],

3. Konfiguration publizieren

# Konfigurationsdatei publizieren
php artisan vendor:publish --provider="Acme\Dhl\DhlServiceProvider" --tag="config"

# Migrations ausführen
php artisan migrate

4. Umgebungsvariablen konfigurieren

.env erweitern

# 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_PRINT_FORMAT=A4
DHL_RETOURE_PRINT_FORMAT=A4
DHL_PROFILE=STANDARD_GRUPPENPROFIL

# DHL Webhook (optional)
DHL_WEBHOOK_ENABLED=false
DHL_WEBHOOK_SECRET=your_webhook_secret
DHL_WEBHOOK_ROUTE=dhl/webhooks/tracking

# DHL Queue Settings (optional)
DHL_USE_QUEUE=false

5. Test-Verbindung prüfen

Artisan Command (zu erstellen)

php artisan dhl:test-connection

Oder via Tinker

php artisan tinker

// Service-Container Test
app(Acme\Dhl\Services\ShippingService::class);

// Model Test
use Acme\Dhl\Models\DhlShipment;
DhlShipment::query()->count();

// API-Test (vereinfacht)
// $client = app(Acme\Dhl\Support\DhlClient::class);
// $client->testConnection();

6. Integration in bestehende Models

ShoppingOrder Model erweitern

use Acme\Dhl\Models\DhlShipment;

class ShoppingOrder extends Model
{
    /**
     * DHL Sendungen für diese Bestellung
     */
    public function dhlShipments(): HasMany
    {
        return $this->hasMany(DhlShipment::class, 'order_id');
    }

    /**
     * Ausgehende DHL Sendungen
     */
    public function dhlOutboundShipments(): HasMany
    {
        return $this->dhlShipments()->outbound();
    }

    /**
     * DHL Retouren
     */
    public function dhlReturns(): HasMany
    {
        return $this->dhlShipments()->returns();
    }

    /**
     * Hat DHL Sendungen
     */
    public function hasDhlShipments(): bool
    {
        return $this->dhlShipments()->exists();
    }

    /**
     * Neueste DHL Sendung
     */
    public function latestDhlShipment(): ?DhlShipment
    {
        return $this->dhlShipments()
            ->latest()
            ->first();
    }
}

7. Verwendung in Controllern

Beispiel Controller-Integration

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

class OrderController extends Controller
{
    public function createDhlLabel(
        ShoppingOrder $order,
        ShippingService $shippingService
    ) {
        try {
            $result = $shippingService->createLabel([
                'order_id' => $order->id,
                'shipper' => [
                    'name' => 'Ihre Firma',
                    'street' => 'Ihre Straße 123',
                    'postalCode' => '12345',
                    'city' => 'Ihre Stadt',
                    'country' => 'DE'
                ],
                'consignee' => [
                    'name' => $order->shipping_name,
                    'street' => $order->shipping_street,
                    'postalCode' => $order->shipping_zip,
                    'city' => $order->shipping_city,
                    'country' => $order->shipping_country
                ],
                'weight_kg' => $order->total_weight ?? 1.0
            ]);

            return response()->json([
                'success' => true,
                'shipment_number' => $result['shipmentNumber'],
                'label_path' => $result['label_path']
            ]);

        } catch (Exception $e) {
            return response()->json([
                'success' => false,
                'error' => $e->getMessage()
            ], 422);
        }
    }
}

8. Facade-Verwendung

use DHL;

// Label erstellen
$result = DHL::createLabel($orderData);

// Tracking-Status abrufen
$status = DHL::getTrackingStatus('1234567890');

// Retourenlabel erstellen
$return = DHL::createReturn($returnData);

Troubleshooting

Composer-Probleme

# Cache leeren
composer dump-autoload
php artisan config:clear
php artisan cache:clear

# Paket neu installieren
composer remove acme/laravel-dhl
composer install

Migration-Probleme

# Migrations-Status prüfen
php artisan migrate:status

# Rollback und neu migrieren
php artisan migrate:rollback --step=2
php artisan migrate

Service-Provider nicht gefunden

# Auto-Discovery cache leeren
composer dump-autoload
php artisan package:discover