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

# DHL Paket Installation & Setup

## 1. Paket im Hauptprojekt registrieren

### composer.json erweitern

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

### Installation

```bash
composer update acme/laravel-dhl
```

## 2. Service Provider registrieren

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

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

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

## 3. Konfiguration publizieren

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

# Migrations ausführen
php artisan migrate
```

## 4. Umgebungsvariablen konfigurieren

### .env erweitern

```env
# 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)

```bash
php artisan dhl:test-connection
```

### Oder via Tinker

```php
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

```php
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

```php
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

```php
use DHL;

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

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

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

## Troubleshooting

### Composer-Probleme

```bash
# 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

```bash
# 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

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