marshmallow / keen-delivery
Connect your Laravel application to Keen Delivery
Installs: 2 005
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 0
Requires
- php: ^8.0
- laravel/nova: ^4.0
- marshmallow/commands: ^v1.2.1
- marshmallow/helpers: ^v2.12.1
- marshmallow/nova-tabs: ^2.0.3
- sendynl/php-sdk: ^1.0
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.
Credits
License
The MIT License (MIT). Please see License File for more information.
Resources
API documentation: https://keendelivery.readthedocs.io/en/latest/
Copyright (c) 2021 marshmallow.