Download the PHP package omobude/dhl-symfony-bundle without Composer

DHL Symfony Bundle

Modern Symfony 7+ bundle for DHL API integration. Create shipment labels, view and download DHL shipments label with ease using OAuth authentication.

Features

• 🚀 Create DHL shipments
• 📦 Download shipping labels (PDF)
• 🔐 OAuth 2.0 authentication with automatic token management
• ⚡ Token caching for optimal performance
• 🧪 Sandbox mode for testing
• 📝 Comprehensive logging support
• 🎯 Type-safe models with PHP 8.2+
• 🇬🇧 Northern Ireland clearance declaration support (Windsor Framework / UKIMS)
• 🔄 Modern Symfony 7 integration

Requirements

• PHP 8.2 or higher
• Symfony 7.0 or higher
• Symfony Cache component
• DHL Developer Account (Sign up here)

Table of Contents

• Installation
• Getting DHL Credentials
• Usage
  • Creating a Shipment
  • Northern Ireland Shipments (Clearance Declaration)
  • Downloading a Label
• Configuration Reference
• Switching to Production
• Troubleshooting
• Contributing
• License

Installation

Step 1: Install the Bundle

Step 2: Register the Bundle (If Not Auto-Registered)

If Symfony Flex doesn't automatically register the bundle, manually add it to config/bundles.php:

Note: With Symfony Flex, this step is usually automatic. Only add this manually if you encounter the error: "There is no extension able to load the configuration for 'omobude_dhl'".

Step 3: Configure Environment Variables

Add your DHL credentials to your .env file:

Step 4: Create Bundle Configuration

Create the file config/packages/omobude_dhl.yaml:

Step 5: Clear Cache

Getting DHL Credentials

For Sandbox (Testing)

1. Go to DHL Developer Portal
2. Sign up for a free account
3. Create a new application
4. Navigate to your application settings
5. Copy your Client ID and Client Secret
6. Use these credentials in your .env file

For Production

1. Contact DHL to request production API access
2. Complete any required business verification
3. Receive your production Client ID and Client Secret
4. Update your production environment variables
5. Set sandbox: false in your configuration

Usage

Creating a Shipment

Northern Ireland Shipments (Clearance Declaration)

Shipments delivered to Northern Ireland (postcodes starting with BT) require an additional clearance declaration under the Windsor Framework / UK Internal Market Scheme (UKIMS). The bundle automatically detects Northern Ireland postcodes and will throw a BadRequestHttpException if a clearance declaration is missing.

When is a Clearance Declaration Required?

Building a Clearance Declaration

A clearance declaration is composed of two model classes:

• ClearanceDeclaration — top-level customs information for the shipment
• ClearanceItem — line-item details for each product in the shipment

ClearanceDeclaration Fields

Note on EORI / UKIMS: Although marked optional in the model, most B2C movements into Northern Ireland under the Windsor Framework will require a valid UKIMS number to qualify for the green-lane "not at risk" treatment. Check your DHL contract and current HMRC guidance before omitting these fields.

ClearanceItem Fields

Validation Behaviour

The bundle enforces clearance declaration rules at the point of calling toArray() on ShipmentData (which happens automatically inside DhlApiClient::createShipment()):

• ✅ NI postcode + clearance declaration present → shipment proceeds
• ❌ NI postcode + no clearance declaration → throws BadRequestHttpException
• ✅ GB postcode + no clearance declaration → shipment proceeds
• ✅ GB postcode + clearance declaration present → shipment proceeds (declaration is included)

Always catch BadRequestHttpException separately if you want to surface clear validation errors to your users before the request hits the DHL API.

Downloading a Label

Checking Sandbox Mode

Configuration Reference

DHL Product Codes

Common product codes for orderedProduct:

Recipient Types

Valid values for recipientType:

• residential - Home delivery
• business - Business address

Address Types

Valid values for addressType:

• doorstep - Standard delivery
• neighbour - Deliver to neighbour if recipient not available

Shipment Movement Types

Valid values for ClearanceDeclaration::$shipmentMovementType:

• B2C - Business to consumer
• B2B - Business to business

Switching to Production

Step 1: Update Environment Variables

Update your production .env file:

Step 3: Clear Production Cache

Step 4: Test in Production

Always test with a single shipment first to ensure everything works correctly.

Troubleshooting

Bundle Not Registered

Problem: "There is no extension able to load the configuration for 'omobude_dhl'"

Solution:

1. Ensure the bundle is registered in config/bundles.php:

2. Clear the cache: php bin/console cache:clear
3. Verify installation: composer show omobude/dhl-symfony-bundle

Authentication Errors

Problem: "Authentication failed" or "Invalid credentials"

Solution:

• Verify your Client ID and Client Secret are correct
• Ensure you're using sandbox credentials with sandbox: true
• Check that credentials are properly set in .env
• Try clearing the token cache: php bin/console cache:clear

Configuration Errors

Problem: "The child config 'client_id' under 'omobude_dhl' must be configured"

Solution:

1. Ensure config/packages/omobude_dhl.yaml exists
2. Verify the configuration syntax is correct
3. Check that environment variables are defined in .env
4. Run php bin/console debug:config omobude_dhl to verify

Northern Ireland Clearance Errors

Problem: BadRequestHttpException: Clearance declaration is required for Northern Ireland deliveries (postcode: BT1 5GS).

Solution:

• The destination postcode starts with BT (Northern Ireland), so a ClearanceDeclaration must be passed to ShipmentData
• See the Northern Ireland Shipments section for a full example
• Make sure your ClearanceDeclaration includes a valid shipmentMovementType, totalValue, numberOfItems, and at least one ClearanceItem
• For most B2C movements, also include a valid UKIMS number via sendersUKIMSNumber

Token Caching Issues

Problem: "Cached token expired" or authentication errors after some time

Solution:

• The bundle automatically refreshes tokens
• Clear cache if issues persist: php bin/console cache:clear
• Check cache directory permissions: var/cache/ should be writable
• Verify symfony/cache is installed

API Errors

Problem: DHL API returns error codes

Solution:

• Check DHL API Documentation for error codes
• Enable logging to see detailed error messages
• Verify all required fields are provided
• Ensure addresses are in the correct format

Debugging

Enable detailed logging:

Check logs:

Verify bundle configuration:

Environment-Specific Configuration

Development

Staging

Production

Security Best Practices

1. Never commit credentials - Add .env to .gitignore
2. Use environment variables - Store credentials in environment, not code
3. Separate environments - Use different credentials for dev/staging/prod
4. Monitor access logs - Check DHL dashboard for unusual activity
5. Use HTTPS only - The bundle uses HTTPS by default
6. Limit permissions - Only grant necessary access to DHL accounts

Recommended .gitignore

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Write tests for your changes
5. Ensure all tests pass: ./vendor/bin/phpunit
6. Commit your changes: git commit -m 'Add amazing feature'
7. Push to the branch: git push origin feature/amazing-feature
8. Open a Pull Request

Coding Standards

• Follow PSR-12 coding standards
• Use PHP 8.2+ features (typed properties, readonly, etc.)
• Write PHPDoc comments for all public methods
• Add tests for new features

License

This bundle is released under the MIT License. See the LICENSE file for details.

Author

Omobude Kelly

• GitHub: @komobude2021
• Email: [email protected]

Support

Need help? Here are your options:

• 📖 Read the Documentation
• 🐛 Report Issues
• 💬 GitHub Discussions
• 📧 Email Support
• 📚 DHL API Documentation

Acknowledgments

• Built for the Symfony community
• Powered by DHL API
• Inspired by modern Symfony best practices

Made with ❤️ for the Symfony community

If this bundle helped you, please consider giving it a ⭐ on GitHub!