# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

ShopwareDHLAdapter (internal name: `ViisonDHL`) is a Shopware 5 backend plugin that integrates DHL shipping services (label generation, returns, daily closing/manifests, export documents). Developed by Pickware GmbH. Requires PHP SOAP extension.

Without a valid license, the plugin operates in development/sandbox mode using DHL test credentials.

## Commands

### Linting
```bash
composer phpcs        # PHP CodeSniffer (VIISON style guide)
composer phpcs:fix    # Auto-fix PHP style issues
npm run eslint        # JavaScript linting (viison-style-guide for Shopware plugins)
npm run eslint:fix    # Auto-fix JS style issues
```

### Testing
Tests are in `Test/Tests/` and run via PHPUnit through the CI tooling. The CI pipeline (Travis) sets up a full Shopware installation before running tests. Tests require a running Shopware instance with MySQL.

Test configuration: `Test/phpunit.xml`, `Test/config.json`

## Architecture

### Plugin Bootstrap & Lifecycle
- `Bootstrap.php` — Main entry point (`Shopware_Plugins_Backend_ViisonDHL_Bootstrap`). Handles install/update/uninstall, configuration, and event registration. Very large file (~2300 lines).
- `Util.php` — Singleton utility class extending `ShippingCommonUtil`.

### Namespace & Autoloading
PSR-4 root: `Shopware\Plugins\ViisonDHL\` maps to repository root.

### Core Business Logic (`Classes/`)
- `ShippingProvider.php` — Main shipping provider, implements label creation and return label interfaces
- `DHLCommunication.php` — SOAP client for DHL Geschäftskundenversand (GKP) API
- `ShippingLabelGenerator.php` — Orchestrates label generation
- `*Request.php` files — Request builders for DHL API calls (CreateShipmentOrder, DeleteShipmentOrder, GetLabel, GetManifest, DoManifest)
- `DhlRetoureApi/` — REST-based DHL Online Retoure (return labels) integration
- `DHLPortalConfigScraper/` — Scrapes DHL portal for configuration/credentials (uses Goutte)
- `DhlServiceOptions/`, `DhlExpressServiceOptions/` — Service option handling (COD, signed receipt, etc.)

### Event-Driven Architecture (`Subscribers/`)
- `Services.php` — Registers services in Shopware DI container (prefix: `viison_dhl.*`)
- `Controllers.php` — Registers backend controllers
- `ShippingProviders.php` — Registers as a shipping provider
- Subdirectories for Backend, Modules, Components subscribers

### Backend Controllers (`Controllers/Backend/`)
- `ViisonDHLConfig.php` — Configuration management
- `ViisonDHLOrder.php` — Order-level label operations
- `ViisonDHLShipping.php` — Shipping method configuration
- `ViisonDHLDailyClosing.php` — Manifest/daily closing
- `ViisonDHLFreeFormLabels.php` — Manual label creation

### Frontend (`Views/`)
- `backend/viison_dhl_shipping/` — ExtJS/Sencha views, controllers, models for the backend UI
- `documents/` — Label and document templates

### External API Communication
- **DHL GKP (Geschäftskundenversand):** SOAP-based, WSDL files cached locally in `WsdlDocuments/gkp/`
- **DHL Express:** SOAP-based, WSDL in `WsdlDocuments/express/`
- **DHL Online Retoure:** REST-based (`Classes/DhlRetoureApi/`)
- Logging via `DhlSoapLogger` and `DhlHttpLogger` (Monolog-based, masks sensitive data)

### Shared Dependencies (installed into repo via Composer)
- `ViisonCommon/` — Shared Shopware plugin framework (`viison/shopwarecommon`)
- `ViisonShippingCommon/` — Shared shipping abstractions (`viison/shopwareshippingcommon`)
- `pickware-autoload/` — Internal autoloader (bundles Goutte v2/v4)

These directories are excluded from linting and autoloading.

### Database Tables
- `s_order_viison_dhl` — Order shipping data
- `s_core_shops_viison_dhl` — Per-shop DHL configuration
- `s_viison_dhl_products` — DHL product definitions
- `s_premium_dispatch_viison_dhl` — Dispatch method to DHL product mapping

### Translations
INI-based snippets in `Snippets/` (German/English), organized by `bootstrap/`, `backend/`, `exceptions/`.

## Code Style
- PHP: VIISON style guide (PSR-2 compatible), enforced via `phpcs.xml`
- JavaScript: VIISON style guide for Shopware plugins, enforced via `.eslintrc.js`