README

Laravel Keen Delivery

This package makes it easy to link with the Keen Delivery API. You connect it by simply adding a trait to your model which should be able to be shipped. The package takes care of the rest. We've also added a number of features to make it easy to manage your shipments via Laravel Nova.

Installation

You can install this package using composer.

composer require marshmallow/keen-delivery

Migrations

Run the migrations. The migration will create a table in your database where all shipments will be stored. We will also store the request and response to/of the Keen Delivery API.

php artisan migrate

Publish the config

After publishing the config, please change the config to your specifications. Below you will find an explanation of all the config values.

php artisan vendor:publish --provider="Marshmallow\KeenDelivery\ServiceProvider" --tag="config"

Update your .env

Add your Sendy Access Token token to your .env file. And add the Sendy shop UUiD.

SENDY_ACCESS_TOKEN="*****"
SENDY_SHOP_ID="*****"

To enable the old Keen Delivery API set the following variable to true.

KEEN_DELIVERY_LEGACY_ENABLED=true

Add your Keen Delivery API token to your .env file. You can also add this to your config but this is not advised.

KEEN_DELIVERY_API_TOKEN="*****"

Usage

Add the trait to your model

First you need to add the KeenDelivery trait to the model which can be shipped.

use Marshmallow\KeenDelivery\Traits\KeenDelivery;

class Order
{
    use KeenDelivery;
    // ...

Implement abstract methods

Next you need to implement all the methods we need to create a shipment with KeenDelivery. See the example below.

use Marshmallow\KeenDelivery\Traits\KeenDelivery;

class Order
{
    use KeenDelivery;

    // ...

    /**
     * Keen Delivery
     */
    public function getDeliveryReference(): string
    {
        return __('Shipment for order: #:order_id', [
            'order_id' => $this->id,
        ]);
    }

    public function getDeliveryCompanyName(): ?string
    {
        return $this->shippingAddress()->company_name;
    }

    public function getDeliveryContactPerson(): ?string
    {
        return $this->shippingAddress()->name;
    }

    public function getDeliveryStreet(): string
    {
        return $this->shippingAddress()->address;
    }

    public function getDeliveryNumber(): string
    {
        return $this->shippingAddress()->house_number;
    }

    public function getDeliveryAddition(): ?string
    {
        return $this->shippingAddress()->house_number_addon;
    }

    public function getDeliveryZipCode(): string
    {
        return $this->shippingAddress()->postal_code;
    }

    public function getDeliveryCity(): string
    {
        return $this->shippingAddress()->city;
    }

    public function getDeliveryCountry(): string
    {
        return $this->shippingAddress()->country?->id ?? 'NL';
    }

    public function getDeliveryPhone(): ?string
    {
        return $this->customer->phone_number;
    }

    public function getDeliveryEmail(): ?string
    {
        return $this->customer->email;
    }

    public function getDeliveryComment(): ?string
    {
        return null;
    }

    public function getDeliveryPredict(): ?string
    {
        return '';
    }

    /**
     * Return the weight in kilo's
     */
    public function getDeliveryWeight(): ?int
    {
        return 1;
    }

    public function getCustomDeliveryData(): array
    {
        return [
            /**
             * Use email notifications for DPD
             */
            'predict' => 2,
        ];
    }

Create a shipment

After you have done this, you can create your shipping labels like so:

$order->createShipment()

Events

This package will trigger event on some actions. Below you will find an overview of the events that you can hook in to.

Use in Laravel Nova

If you want to use this package in Nova, you must start by publishing the Nova Resource. This can be done by running the command below. This command will create the file app\Nova\Delivery.php if it does not already exist.

php artisan marshmallow:resource Delivery KeenDelivery

Update your own resource

In this example, we assume that you want to be able to link your orders to this package. We have a number of useful functions that give you a lot of information and possibilities in Nova. In this example we are talking about orders, however, this can be applied to all your models and resources.

Show the shipments

Add the relationship below to App\Nova\Order to make the shipments visible in the detail view of your orders.

public function fields(Request $request)
{
    // ...
    MorphMany::make(__('Deliveries'), 'deliverable', Delivery::class),
}

Show Tracking information on your index

We have created a helper that allows you to add the Track & Trace number and a download button to download the shipping label to the index of your resource.

use Marshmallow\KeenDelivery\Facades\KeenDelivery;

public function fields(Request $request)
{
    // ...
    KeenDelivery::shipmentInfoField(),
}

Filters

We also have a filter ready by default. With this filter, you can filter on all orders that have been successfully submitted to Keen Delivery. You can also filter on orders that have not yet or not successfully been submitted with Keen Delivery.

public function filters(Request $request)
{
    return [
        new ShipmentNotifiedFilter,
    ];
}

Actions

There are two actions in this package that will make your life extra easy.

Submit for shipmet

With this action you can submit an order from Nova to Keen Delivery. It is also possible to submit multiple orders at the same time.

public function actions(Request $request)
{
    return [
        //
        new SubmitForShipment,
    ];
}

Download labels

With this action you can download the label of a shipment. It is also possible to download the shipping labels of multiple orders at once.

public function actions(Request $request)
{
    return [
        //
        new DownloadLabels,
    ];
}

API

The following API methods are useful for the setup of this package. With the verifyApiToken you can check if you actually have a working connection with the Keen Deliver API and with listShippingMethods you can see which shipping methods are available to you.

use Marshmallow\KeenDelivery\Facades\KeenDeliveryApi;

KeenDeliveryApi::verifyApiToken();
KeenDeliveryApi::listShippingMethods();

Sendy Api

The following API methods are useful for the setup of this package. With the me you can check if you actually have a working connection with the Keen Deliver API and with listShippingMethods you can see which shipping methods are available to you. You can also use the 'shops' method to get all the shops that are connected to your account. Or use the getShopUuid to get the UUID of the first shop.

use Marshmallow\KeenDelivery\Facades\SendyApi;

SendyApi::me();
SendyApi::getShopUuid();
SendyApi::listShops();
SendyApi::getShippingPreference();
SendyApi::listShippingPreferences();
SendyApi::listCarriers();
SendyApi::listShippingMethods();
SendyApi::listServices($carrierId);
SendyApi::getShipment($shipmentId);

Carriers

The tables below show which carries and which services are currently supported by this package.

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email stef@marshmallow.dev instead of using the issue tracker.

marshmallow / keen-delivery

Maintainers

Details