Magento

The Magento module allows a shop owner to implement the creation of orders in Boekuwzending.

Prerequisites

The minimum requirements for running this module in Magento are:

• Magento 2.3
• PHP 7.4
• Composer < 2 (e.g. 1.10.19)

And all transitive dependencies specified in the composer.json which will be installed during the module installation.

Retrieve your credentials

To let the module communicate securely with the Boekuwzending API, you will need to request credentials. These credentials can be retrieved via the Mijn Boekuwzending platform. When logged in click on your username, navigate to "Integraties" and click the "Integratie starten" button next to Magento.

Enter your Shop URL and choose the default sender address. You can change this address when processing the imported orders.

After submitting with "Koppelen" you will be shown your credentials. Keep these credentials safe, you will need them later to configure the Magento module.

Installation

This module only supports manual installation, meaning you can't install it from the Marketplace.

Manual installation

To install the module in your Magento installation you need shell access (SSH) to the server. Assuming Composer is already present, in the Magento directory, execute the following commands as the user that Magento runs as:

bin/magento maintenance:enable 
composer require boekuwzending/magento 
bin/magento module:enable Boekuwzending_Magento
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:clean
bin/magento maintenance:disable 

This is a common workflow for many Magento modules. First, the maintenance mode is enabled, ensuring no visitors of the site will encounter any errors. Then the module is downloaded from GitHub using Composer. Note that you'll need access keys for the Composer directory of Magento, available through https://marketplace.magento.com/customer/accessKeys/.

The Composer installation may take a while, as Composer carefully calculates all dependencies that are currently required and whether there will be any conflicts with the requirements of the module to be installed.

Then some Magento commands are run, which enable the module, upgrade the configuration and database, compile the classes for dependency injection (DI) and finally to clean the cache and disable the maintenance mode again.

Database

The setup:upgrade command utilizes the db_schema.xml of the module to create a new database table boekuwzending_order, which allows linking one Magento order to zero or more Boekuwzending orders.

Updating

When a new version of the module is released, you can update it using the following commands in the Magento directory:

bin/magento maintenance:enable 
composer update boekuwzending/magento 
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:clean
bin/magento maintenance:disable

The same information as mentioned at the installation applies.

Composer can cache packages quite aggressively, so if you're trying to update to a version that was released recently, you might need to bypass the cache in the second command, replacing it with:

composer update boekuwzending/magento --no-cache

After running the composer command, you can verify the proper verison was installed using:

composer show | grep boekuwzending

You should see the expected version:

boekuwzending/magento     v1.1.0

Configuration

The module is configured from the Admin interface. You can find the settings under Stores -> Configuration -> Sales -> Delivery methods.

Usage

When configured, the shipping method looks like this:

Users can now select this shipping method. When placing the order, it is immediately forwarded through the Boekuwzending API, making it known in Imported Shipments at https://mijn.boekuwzending.com/.

Management

An order that is not linked to Boekuwzending looks like this:

Orders are usually linked on a one-to-one basis:

It's also possible to click "Create new order" and split an order into multiple orders at Boekuwzending:

Extensibility

Starting with version 2.0.0 of the plugin you'll be able to intercept the Boekuwzending order model before it gets sent to the Boekuwzending API.

To do so, register an observer in your site's /etc/events.xml:

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Event/etc/events.xsd">
    <event name="boekuwzending_order_create_before">
        <observer name="boekuwzending_order_create_before_observer" instance="YourNamespace\YourModule\Observer\OrderCreateBeforeObserver"/>
    </event>
</config>

The event is dispatched after the model has been populated from the Magento order. The event data will be an array in this format:

[
    'boekuwzending_order' => /** @var Boekuwzending\Resource\Order */,
    'magento_order' => /** @var Magento\Sales\Model\Order */,
]

A sample implementation:

<?php

namespace YourNamespace\YourModule\Observer;

class OrderCreateBeforeObserver implements Magento\Framework\Event\ObserverInterface
{
    /**
    * Gets executed before an order will be sent to the Boekuwzending API.
    */
    public function execute(\Magento\Framework\Event\Observer $observer): void
    {            
        /** @var Magento\Sales\Model\Order $magentoOrder */
        $magentoOrder = $observer->getData('magento_order');

        // Use for example $street = $magentoOrder->getShippingAddress()->getStreet()

        /** @var Boekuwzending\Resource\Order $order */
        $order = $observer->getData('boekuwzending_order');

        /** @var Boekuwzending\Resource\Address $shipTo */
        $shipTo = $order->getShipToAddress();

        // You could use $street[0], $street[1], $street[2],
        // but the array will be sized to the actual input.

        $shipTo->setStreet('Observerstreet'); // $street[0]
        $shipTo->setNumber('42'); // $street[1]
        $shipTo->setNumberAddition('A'); // $street[2]

        // Clear the result of our parsing
        $shipTo->setAddressLine2(null);
    }
}

Our code puts $street[1] and $street[2] into the "address line 2" property if it can't parse it. You'll need to clear the "address line 2" property if you perform manual parsing as shown above, using $shipTo->setAddressLine2(null), otherwise you can end up with duplicate data.