3brs/sylius-ppl-parcelshops-plugin

PPL parcelshops plugin for Sylius

Maintainers

Details

github.com/3BRS/sylius-ppl-parcelshops

Source

Issues

Installs: 0

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 0

Forks: 0

Open Issues: 0

Type:sylius-plugin

pkg:composer/3brs/sylius-ppl-parcelshops-plugin

dev-main 2025-12-08 14:12 UTC

Requires

Requires (Dev)

Conflicts

MIT 6fc4d882222e7f2812ba9667c555bca13fc95a6e

This package is auto-updated.

Last update: 2025-12-08 14:12:30 UTC

README

PPL parcelshop plugin

Features

  • Enables sending shipments via PPL to PPL parcelshops.
  • The user can choose the PPL parcelshops from the map during checkout in the Shipment step PPL_modal.png
  • See PPL parcelshop in final checkout step and also in the admin panel.
  • Export CSV with the PPL parcelshops shipments and import it easily into PPL's system.

PPL CSV import configuration

Installation

1. Install the plugin via Composer

composer require 3brs/sylius-ppl-parcelshops-plugin

2. Register the bundles

Add plugin classes to your config/bundles.php:

return [
    // ...
    ThreeBRS\SyliusShipmentExportPlugin\ThreeBRSSyliusShipmentExportPlugin::class => ['all' => true],
    ThreeBRS\SyliusPplParcelshopsPlugin\ThreeBRSSyliusPplParcelshopsPlugin::class => ['all' => true],
];

3. Import routing

Add routing to config/routes.yaml:

threebrs_sylius_shipment_export_plugin:
    resource: "@ThreeBRSSyliusShipmentExportPlugin/Resources/config/routing.y*ml"
    prefix: '/%sylius_admin.path_name%'

threebrs_sylius_ppl_parcelshops_plugin:
    resource: '@ThreeBRSSyliusPplParcelshopsPlugin/Resources/config/routing.yaml'
    prefix: /

4. Import plugin configuration

Add config import to config/packages/_sylius.yaml:

imports:
    # ...
    - { resource: "@ThreeBRSSyliusPplParcelshopsPlugin/Resources/config/config.yaml" }

5. Configure entity models

Your Entity Shipment has to implement \ThreeBRS\SyliusPplParcelshopsPlugin\Model\PplShipmentInterface. You can use the trait \ThreeBRS\SyliusPplParcelshopsPlugin\Model\PplShipmentTrait.

Example:

<?php

namespace App\Entity\Shipping;

use Doctrine\ORM\Mapping as ORM;
use Sylius\Component\Core\Model\Shipment as BaseShipment;
use ThreeBRS\SyliusPplParcelshopsPlugin\Model\PplShipmentInterface;
use ThreeBRS\SyliusPplParcelshopsPlugin\Model\PplShipmentTrait;

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

Your Entity ShippingMethod has to implement \ThreeBRS\SyliusPplParcelshopsPlugin\Model\PplShippingMethodInterface. You can use the trait \ThreeBRS\SyliusPplParcelshopsPlugin\Model\PplShippingMethodTrait.

Example:

<?php

namespace App\Entity\Shipping;

use Doctrine\ORM\Mapping as ORM;
use Sylius\Component\Core\Model\ShippingMethod as BaseShippingMethod;
use ThreeBRS\SyliusPplParcelshopsPlugin\Model\PplShippingMethodInterface;
use ThreeBRS\SyliusPplParcelshopsPlugin\Model\PplShippingMethodTrait;

#[ORM\Entity]
#[ORM\Table(name: 'sylius_shipping_method')]
class ShippingMethod extends BaseShippingMethod implements PplShippingMethodInterface
{
    use PplShippingMethodTrait;
}

For more details on entity customization, see Sylius docs - Customizing Models.

6. Override templates

Admin Shipping Method Form

Override templates/bundles/SyliusAdminBundle/ShippingMethod/_form.html.twig and include the PPL form:

{# @SyliusAdmin/ShippingMethod/_form.html.twig #}
{# ... existing form content ... #}
{{ include('@ThreeBRSSyliusPplParcelshopsPlugin/Admin/ShippingMethod/_pplForm.html.twig') }}
{# ... rest of the form ... #}
  • see tests/Application/templates/bundles/SyliusAdminBundle/ShippingMethod/_form.html.twig for example

Shop Checkout Shipping Choice

Override templates/bundles/SyliusShopBundle/Checkout/SelectShipping/_choice.html.twig and include the PPL widget at the end:

{# @SyliusShop/Checkout/SelectShipping/_choice.html #}
{# ... existing shipping choice content ... #}
{{ include('@ThreeBRSSyliusPplParcelshopsPlugin/Shop/Checkout/SelectShipping/_pplChoice.html.twig') }}
  • see tests/Application/templates/bundles/SyliusShopBundle/Checkout/SelectShipping/_choice.html.twig for example

Shop Order Addresses

Override templates/bundles/SyliusShopBundle/Common/Order/_addresses.html.twig and replace the shipping address section:

{# @SyliusAdmin/Order/Show/_addresses.html.twig #}
<div class="ui segment">
    <div class="ui two column divided stackable grid">
        <div class="column" id="sylius-billing-address" {{ sylius_test_html_attribute('billing-address') }}>
            <div class="ui small dividing header">{{ 'sylius.ui.billing_address'|trans }}</div>
            {% include '@SyliusShop/Common/_address.html.twig' with {'address': order.billingAddress} %}
        </div>
        <div class="column" id="sylius-shipping-address" {{ sylius_test_html_attribute('shipping-address') }}>
            <div class="ui small dividing header">{{ 'sylius.ui.shipping_address'|trans }}</div>
            {{ include('@ThreeBRSSyliusPplParcelshopsPlugin/Shop/Common/Order/_addresses.html.twig') }}
        </div>
    </div>
</div>

Admin Order Addresses

Override templates/bundles/SyliusAdminBundle/Order/Show/_addresses.html.twig and replace the shipping address section:

{# @ThreeBRSShipmentExportPlugin/_row.html.twig #}
{% if order.shippingAddress is not null %}
    <h4 class="ui top attached styled header">
        {{ 'sylius.ui.shipping_address'|trans }}
    </h4>
    <div class="ui attached segment" id="shipping-address">
        {{ include('@ThreeBRSSyliusPplParcelshopsPlugin/Admin/Common/Order/_addresses.html.twig') }}
    </div>
{% endif %}
{# ... billing address and other content ... #}

Shop Layout (JavaScript)

Include the PPL JavaScript in your shop layout (e.g., templates/bundles/SyliusShopBundle/layout.html.twig):

{% block javascripts %}
    {{ parent() }}
    {{ include('@ThreeBRSSyliusPplParcelshopsPlugin/Shop/_javascripts.html.twig') }}
{% endblock %}

7. Create and run database migrations

Generate and run doctrine migrations to add the required database columns:

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

Configuration

The plugin can be configured using the following parameters in your config/packages/_sylius.yaml or config/services.yaml:

parameters:
    # Shipping method codes that should be exported to PPL CSV format
    # Default: ['ppl_parcel_shop']
    # IMPORTANT: Only shipments using shipping methods with these codes will be exported
    threebrs_sylius_ppl_parcelshops_plugin_ppl_shipping_method_codes: ['ppl_parcel_shop', 'your_custom_ppl_method']

    # Country codes where PPL parcelshop service is available
    # Default: ['CZ', 'SK', 'DE', 'PL', 'HU', 'BG', 'RO', 'NL', 'AT']
    threebrs_sylius_ppl_parcelshops_plugin_ppl_countries: ['CZ', 'SK', 'DE', 'PL', 'HU', 'BG', 'RO', 'NL', 'AT']

Note: The threebrs_sylius_ppl_parcelshops_plugin_ppl_shipping_method_codes parameter determines which shipments will appear in the export list. Make sure your shipping method code matches one of the codes in this array, otherwise the shipments won't be available for export.

Usage

1. Create a PPL Parcelshop Shipping Method

  1. Go to the admin panel: Shipping Methods → Create
  2. Fill in the basic information:
    • Code: Use ppl_parcel_shop (default) or a custom code that matches the threebrs_sylius_ppl_parcelshops_plugin_ppl_shipping_method_codes parameter
    • Zone: Select appropriate shipping zone
    • Calculator: Choose your preferred shipping calculator
  3. Check the "To PPL ParcelShop enabled" option
  4. Configure PPL country options:
    • Display ParcelShops from selected countries: Choose which countries' parcelshops should be available for selection (multiple selection allowed)
    • Default selected country on the map with ParcelShops: Choose which country will be pre-selected when the parcelshop map opens
  5. Save the shipping method

Important: The shipping method code must be listed in the threebrs_sylius_ppl_parcelshops_plugin_ppl_shipping_method_codes parameter (see Configuration section above). If using a custom code, add it to this parameter in your configuration.

2. Customer Checkout Flow

When a customer selects a PPL parcelshop shipping method during checkout:

  1. A PPL parcelshop selector widget will appear
  2. The customer can choose their preferred parcelshop from an interactive map
  3. The selected parcelshop information (ID, name, address) is saved with the shipment
  4. The parcelshop details are visible in the order confirmation

3. Export Shipments to PPL

  1. Go to the admin panel: Shipment Export
  2. Select the PPL ParcelShop exporter type
  3. Choose the shipments you want to export
  4. Click Export to download a CSV file
  5. Import the CSV file into PPL's system

The CSV export includes all necessary information for PPL processing:

  • Parcelshop ID and details
  • Recipient information
  • Package weight and dimensions
  • Cash on delivery amount (if applicable)
  • Order reference

Development

Usage

  • Develop your plugin in /src
  • See bin/ for useful commands

Testing

After your changes you must ensure that the tests are still passing.

$ composer install
$ bin/console doctrine:schema:create -e test
$ bin/behat
$ bin/phpstan.sh
$ bin/ecs.sh

License

This library is under the MIT license.

Credits

Developed by 3BRS
Forked from manGoweb.