Getting Started

Minimal Steps to Enable DPD Shipping

Install the Bundle
```
composer require agencednd/dpd-france-orocommerce-bundle
```
Ensure your composer.json meets PHP 8.2+ and OroCommerce 5.1+ requirements.

Run Migrations & Data Loaders

bin/console oro:migration:load --force
bin/console oro:migration:data:load --bundles=DndDpdFranceBundle

Clear Cache & Reinstall Assets

bin/console cache:clear
bin/console assets:install

Load Workflows & Translations

bin/console oro:workflow:definitions:load
bin/console oro:translation:load

Create a DPD Integration Navigate to System > Integrations > Manage Integrations > Create Integration and select DPD France. Configure:
- Agency code & contract number (provided by DPD).
- Shipping services (Classic/Predict/Relais).
- FTP credentials (if using DPD Station export).
Enable the DPD Workflow Go to System > Workflows > Manage Workflows and enable the "Checkout with DPD France" workflow.
Test a DPD-Eligible Order Place an order with products configured for DPD shipping (weight in kg, dimensions in cm). Verify the DPD shipping method appears at checkout.

Implementation Patterns

Core Workflow: Shipping Method Integration

Product Configuration
- Set Shipping options for products (weight in kg, dimensions in cm).
- Use the maxQtyForDpdFr attribute (via Product Attributes) to enforce per-product quantity limits. Example: Set to 5 to restrict DPD shipping to ≤5 units per product.
Shipping Rule Creation Create a rule targeting the DPD France integration with conditions like:
```
lineItems.all(
    (lineItem.product.maxQtyForDpdFr < 0)
    or
    (lineItem.product.maxQtyForDpdFr >= lineItem.quantity)
)
```
- Combine with customer groups or other OroCommerce rules (e.g., customer.group.id = 4).
Dynamic Service Limits Override default DPD limits (weight/dimensions/value) via the dnd_dpd_fr_shipping_service table. Example SQL:
```
UPDATE dnd_dpd_fr_shipping_service
SET parcel_max_weight = 30, parcel_max_length = 1.5
WHERE service_code = 'DPD_CLASSIC';
```
Checkout Workflow
- Use the "With DPD France" workflow variant to ensure DPD-specific fields (e.g., relay point selection) are included.
- Extend the workflow to add custom steps (e.g., DPD tracking number input post-shipment).
FTP Export for DPD Station
- Configure FTP details in the DPD Integration settings.
- Trigger exports manually via:
```
bin/console oro:shipment:export:dpd-station
```
- Automate exports via a cron job (e.g., daily at 2 AM):
```
0 2 * * * cd /path/to/project && bin/console oro:shipment:export:dpd-station >> /dev/null 2>&1
```

Advanced Patterns

Custom Shipping Calculations

Extend the bundle’s shipping calculator by creating a custom shipping method handler:

// src/Acme/DpdExtension/DependencyInjection/Compiler/DpdShippingPass.php
use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
use Symfony\Component\DependencyInjection\ContainerBuilder;

class DpdShippingPass implements CompilerPassInterface
{
    public function process(ContainerBuilder $container)
    {
        $definition = $container->findDefinition('dnd_dpd_fr.shipping.calculator');
        $definition->addMethodCall('addCustomCalculator', [new \Acme\CustomCalculator()]);
    }
}

API-Based Rate Updates

Fetch real-time DPD rates via their API and override the bundle’s static rates:

// src/Acme/DpdExtension/Shipping/DpdRateProvider.php
use Dnd\DpdFranceShippingBundle\Provider\ShippingRateProviderInterface;

class DpdRateProvider implements ShippingRateProviderInterface
{
    public function getRates(array $orderData): array
    {
        $response = $this->dpdApiClient->getRates($orderData);
        return $this->mapApiResponseToOroFormat($response);
    }
}

Relay Point Selection

Add a custom field to the checkout workflow for relay point selection:

# config/oro_workflow/workflow_dpd_relay.yml
steps:
  - name: select_relay_point
    entity: Oro\Bundle\OrderBundle\Entity\Order
    transitionToStepOn: complete
    form:
      type: acme_dpd_relay_form_type
      options:
        relay_points: '%dpd_relay_points%'

Gotchas and Tips

Pitfalls

Unit Mismatches
- DPD expects kilograms (kg) and centimeters (cm). Using grams/meters will break calculations.
- Fix: Validate product weights/dimensions via a data fixture or pre-save event:
```
$product->getShippingWeight()->setValue($product->getShippingWeight()->getValue() / 1000); // Convert g to kg
```
FTP Export Failures
- Silent FTP failures may occur if credentials are invalid or the server blocks passive mode.
- Debug: Enable verbose logging in config/packages/dnd_dpd_france.yaml:
```
dnd_dpd_france:
    ftp:
        debug: true
```
- Fix: Use SFTP instead of FTP or configure passive mode in php.ini:
```
allow_url_fopen = On
```
Quantity Limit Overrides
- The three-tier limit system (global → service → product) can cause confusion.
- Tip: Use the product attribute (maxQtyForDpdFr) for fine-grained control. Set to -1 to bypass all limits.
Workflow Cache Issues
- After modifying workflows, clear the workflow cache:
```
bin/console oro:workflow:definitions:load --force
```
- Pro Tip: Use --force to bypass confirmation prompts in CI/CD pipelines.

API Rate Limits

DPD’s API may throttle requests. Cache responses for 5 minutes:

$cacheKey = 'dpd_rates_' . md5(serialize($orderData));
if ($rates = $this->cache->get($cacheKey)) {
    return $rates;
}
$rates = $this->dpdApiClient->getRates($orderData);
$this->cache->set($cacheKey, $rates, 300); // 5-minute cache

Debugging Tips

Log DPD API Responses Override the API client to log raw responses:

// src/Acme/DpdExtension/Client/DpdApiClient.php
class DpdApiClient extends \Dnd\DpdFranceShippingBundle\Client\DpdApiClient
{
    public function getRates(array $data)
    {
        $response = parent::getRates($data);
        \Oro\Bundle\LogBundle\Logger\Logger::info('DPD API Response:', ['data' => $data, 'response' => $response]);
        return $response;
    }
}

Validate FTP Exports Check the local export directory (data/dpd-france/export) for generated files. Use file_get_contents() to inspect:

$exportPath = $this->container->getParameter('dnd_dpd_france.export_dir') . '/export_20231001.xml';
file_put_contents('debug_export.xml', file_get_contents($exportPath));

Shipping Rule Testing Test rules in the OroCommerce Rule Tester (Admin > System > Shipping Rules > [Rule] > Test).
- Pro Tip: Use the Debug Toolbar to inspect $lineItems and $customer objects.

Extension Points

Custom Shipping Methods Extend the bundle’s service list by adding a new entity in dnd_dpd_fr_shipping_service:

INSERT INTO dnd_dpd_fr_shipping_service (service_code, label, description, parcel_max_weight, parcel_max_length)
VALUES ('DPD_EXPRESS', 'DPD Express', '24h Delivery', 20, 1.2);

Post-Shipment Actions Hook into the oro_shipment.post_save event to update DPD tracking:
```
//
```

Dpd France Orocommerce Bundle Laravel Package