README

A comprehensive Mondial Relay integration plugin for Sylius 2.x, providing pickup point shipping functionality for French and European e-commerce stores.

Features

🗺️ Pickup Point Selection: Interactive widget for customers to choose relay points during checkout
📦 Dual API Support:
- REST API v2 (Connect): For shipment creation, label generation with Basic Auth
- SOAP API v1: For relay point search (WSI4_PointRelais_Recherche)
🎫 Label & QR Code Generation: Automatic shipping labels with QR codes for drop-off
📊 Admin Interface:
- Configuration page for API credentials
- Relay point details in order view
- QR code generation from admin panel
🔌 Sylius 2 Twig Hooks: Native integration with Sylius 2 hook system
⚡ Performance: Built-in caching for API responses
🧪 Sandbox Mode: Test integration without affecting production
🔒 Type Safety: PHP 8.2+ with readonly classes and strict typing
📝 Well Documented: Complete API documentation and usage examples

Requirements

PHP 8.2 or higher
Sylius 2.0 or higher
Symfony 7.0 or higher
MySQL 8.0+ or PostgreSQL 13+
A valid Mondial Relay merchant account

Installation

1. Install via Composer

composer require kiora/sylius-mondial-relay-plugin

2. Register the Bundle

The bundle is automatically registered via Symfony Flex. If not, add it manually to config/bundles.php:

<?php

return [
    // ...
    Kiora\SyliusMondialRelayPlugin\KioraSyliusMondialRelayPlugin::class => ['all' => true],
];

3. Import Routes

Create config/routes/kiora_mondial_relay.yaml:

# Admin routes (configuration, shipment actions)
kiora_mondial_relay_admin:
    resource: '@KioraSyliusMondialRelayPlugin/config/routes/admin.yaml'

# Shop routes (relay point search/select during checkout)
kiora_mondial_relay_shop:
    resource: '@KioraSyliusMondialRelayPlugin/config/routes/shop.yaml'

4. Extend Shipment Entity (optional)

To store pickup point selections, extend Sylius Shipment entity with the provided trait:

<?php
// src/Entity/Shipping/Shipment.php

namespace App\Entity\Shipping;

use Doctrine\ORM\Mapping as ORM;
use Kiora\SyliusMondialRelayPlugin\Entity\MondialRelayShipmentInterface;
use Kiora\SyliusMondialRelayPlugin\Entity\MondialRelayShipmentTrait;
use Sylius\Component\Core\Model\Shipment as BaseShipment;

#[ORM\Entity]
#[ORM\Table(name: 'sylius_shipment')]
class Shipment extends BaseShipment implements MondialRelayShipmentInterface
{
    use MondialRelayShipmentTrait;
}

Then run migrations:

bin/console doctrine:migrations:diff
bin/console doctrine:migrations:migrate

5. Clear Cache

bin/console cache:clear

6. Configure API Credentials

Navigate to Admin > Configuration > Mondial Relay to configure:

REST API v2 (Connect): API Key, API Secret, Brand ID for shipment creation and labels
SOAP API v1: Enseigne code and Private Key for relay point search
Sandbox Mode: Enable/disable test environment

The configuration is stored in config/mondial_relay.json and can be tested directly from the admin interface.

Usage

Quick Start with API Client

The plugin provides a complete HTTP client for interacting with the Mondial Relay API:

<?php

use Kiora\SyliusMondialRelayPlugin\Api\Client\MondialRelayApiClientInterface;
use Kiora\SyliusMondialRelayPlugin\Api\DTO\RelayPointSearchCriteria;

class MyService
{
    public function __construct(
        private readonly MondialRelayApiClientInterface $apiClient
    ) {}

    public function searchRelayPoints(string $postalCode): void
    {
        // Search by postal code
        $criteria = RelayPointSearchCriteria::fromPostalCode(
            postalCode: $postalCode,
            countryCode: 'FR',
            radius: 10,
            limit: 20
        );

        $collection = $this->apiClient->findRelayPoints($criteria);

        foreach ($collection as $relayPoint) {
            echo sprintf(
                "%s - %s (%s km)\n",
                $relayPoint->name,
                $relayPoint->getFullAddress(),
                $relayPoint->getDistanceKm()
            );
        }
    }
}

See complete documentation: API Client Documentation

See working examples: docs/examples/basic-usage.php

Testing the Integration

Use the provided Makefile commands for development:

# Install dependencies
make install

# Run tests
make test

# Run static analysis
make phpstan

# Fix code style
make cs-fix

# Run all quality checks
make check

Development

Project Structure

kiora-sylius-mondial-relay-plugin/
├── config/
│   ├── routes/
│   │   ├── admin.yaml                 # Admin routes (configuration, shipments)
│   │   └── shop.yaml                  # Shop routes (relay point search/select)
│   ├── services.yaml                  # Service definitions
│   └── twig_hooks.yaml                # Sylius 2 Twig Hooks configuration
├── src/
│   ├── Api/
│   │   ├── Client/
│   │   │   ├── MondialRelayApiClient.php      # REST API v2 client
│   │   │   ├── MondialRelayApiClientInterface.php
│   │   │   └── MondialRelaySoapClient.php     # SOAP API v1 client
│   │   ├── DTO/
│   │   │   ├── RelayPointSearchCriteria.php   # Search parameters
│   │   │   ├── RelayPointDTO.php              # Relay point data
│   │   │   ├── RelayPointCollection.php       # Iterable collection
│   │   │   └── ...
│   │   └── Exception/
│   │       └── MondialRelayApiException.php   # API exceptions
│   ├── Controller/
│   │   ├── Admin/
│   │   │   ├── ConfigurationController.php    # API configuration page
│   │   │   └── ShipmentController.php         # Label/QR code generation
│   │   └── Shop/
│   │       └── RelayPointController.php       # Relay point search/select
│   ├── Entity/
│   │   ├── MondialRelayPickupPoint.php        # Pickup point entity
│   │   └── MondialRelayShipmentTrait.php      # Shipment extension trait
│   ├── Service/
│   │   ├── MondialRelayLabelGenerator.php     # Shipping labels
│   │   └── MondialRelayQrCodeGenerator.php    # QR codes for drop-off
│   ├── DependencyInjection/
│   │   ├── Configuration.php
│   │   └── KioraSyliusMondialRelayExtension.php
│   └── KioraSyliusMondialRelayPlugin.php
├── templates/
│   ├── admin/
│   │   ├── configuration/             # Admin configuration page templates
│   │   └── order/show/                # Order detail Mondial Relay info
│   └── shop/
│       └── checkout/                  # Relay point selector widget
├── CHANGELOG.md
├── composer.json
└── README.md

Running Tests

composer test

Static Analysis

composer phpstan

Code Style

composer cs-fix

Troubleshooting

API Authentication Errors

If you receive authentication errors:

Verify your credentials in the Mondial Relay merchant portal
Ensure you're using the correct environment (sandbox vs production)
Check that the API secret is properly configured for request signing

Cache Issues

Clear the plugin cache:

bin/console cache:pool:clear kiora_sylius_mondial_relay.cache

Network Timeouts

Increase the HTTP timeout in your configuration:

kiora_sylius_mondial_relay:
    http:
        timeout: 30

Documentation

Plugin Documentation

API Client Guide - Complete HTTP client documentation
API Client Summary - Implementation details and statistics
Code Examples - 8 working examples for common use cases
Changelog - Version history and changes

External Documentation

Support

For bugs, feature requests, or questions:

GitHub Issues: Create an issue
Email: support@kiora.tech

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Commit your changes with clear messages
Add tests for new functionality
Submit a pull request

License

This plugin is licensed under the MIT License. See LICENSE for details.

Credits

Developed by Kiora

Built for Sylius, the modern e-commerce framework for PHP.

Note: This plugin requires a valid Mondial Relay merchant account. Visit Mondial Relay Professional to register.

kiora / sylius-mondial-relay-plugin

Maintainers

Details