Steps to setup new courier service
Backend
1. Add courier entry
- Add courier data into
CourierSeeder.phpseeder file which is located inside/database/seedersfolder. -
New courier data should be added into couriers array in run function. For example, if your courier name is Gls. Then the file will look like this.
<?php namespace Database\Seeders; use App\Models\Courier; use Carbon\Carbon; use Illuminate\Database\Seeder; use Illuminate\Support\Facades\DB; class CourierSeeder extends Seeder { public function run() { DB::table(Courier::getTableName())->truncate(); $couriers = [ [ 'id' => 1, 'name' => 'Bookurier', 'url' => 'http://www.bookurier.ro/colete/serv/', 'active' => 1, 'classname' => 'App\Services\CourierServices\Bookurier', 'created_at' => Carbon::now() ], [ 'id' => 2, 'name' => 'Gls', 'url' => 'https://api.mygls.ro/', 'active' => 1, 'classname' => 'App\Services\CourierServices\Gls', 'created_at' => Carbon::now() ] ]; foreach ($couriers as $courier) { DB::table(Courier::getTableName())->insert($courier); } } } -
Here, url is the api endpoint for the courier and classname is the name of the class that you will create later in
App\Services\CourierServices\folder. You can choose any classname but recomended is to keep same name as in name field to avoid any confusion. - After adding into seeder file, run the seeder and you will see the entry for the new courier into couriers table. > php artisan db:seed --class=CourierSeeder
2. Create class file
- Create contract class for the courier in
App\Services\CourierServiceswhich will implement CourierServiceProvider interface inApp\Services\CourierServices\Contract -
Implement all the methods from the interface into the class. Add the logic as per the courier as different courier can have different way of calling their api, cost calculation and so on. The file will look as given in the below code snippet.
<?php namespace App\Services\CourierServices; use App\Services\CourierServices\Contract\CourierServiceProvider; use Illuminate\Http\Request; use Exception; class Gls implements CourierServiceProvider { public function __construct() { $this->status = [ 1 => 73, 2 => 74 ]; } public function generateOrder(Request $request, RequestLog $requestLog) { try { /* Add you own logic here */ // Prepare the request data structure. // Call the courier api with given format // Response with proper structure. } catch (Exception $e) { // Log any error occurs. } } public function deleteOrder (Request $request, RequestLog $requestLog) { try { /* Add you own logic here */ // Prepare the request data structure. // Call the courier api with given format // Response with proper structure. } catch (Exception $e) { // Log any error occurs. } } . . . /* Implement other funtions also. */ -
You can also add any new method if the courier provider supports. For that you have to define that method as empty in all other courier contract files which you see in
app\Services\CourierServicesfolder. If any method from the interface is not supported by the courier then you should leave it as empty methods in the class. - Use
ApiResponsertrait to structure your response in functions. -
You can use courierSettings helper function to get the settings for current courier and user anywhere in the contract file.
-
In constructor, map the status to the status ids defined in status array of
config/constants.phpfile. If status description doesn't matches any, create one. So basically this means that constants will have all the status from any courier.
-
After that, map them with general_statuses also. Which means we have our own custom general status in the system. we actually access the order status based on that and order can be in any one of the status defined in general_statuses array.
- List of general statuses.
- 0: Error, please contact customer support
- 1: AWB was registered
- 2: Picked up from sender
- 3: In transit
- 4: Delivery in process
- 5: Delivered
- 6: AWB deleted
- Any order should be in any one of the above statuses
3. Create commands (optional)
This step is only usefull if you need to store any data set from the courier provider into your laravel database for any future references. For example, if you want to import services from Gls courier provider, then
- Create the class in app\Console\Commands folder. You can choose any classname but for simplicity follow the classname pattern as GlsCourierData
- Create the controller class app\Http\Controllers\GlsCourierController.php.
- Call the controller methods from the handle method of GlsCourierData class. See below code snippet.
<?php
namespace App\Console\Commands;
use App\Http\Controllers\GlsCourierController;
use Illuminate\Console\Command;
class GlsCourierData extends Command
{
protected $signature = 'import:GlsCourierData';
protected $description = 'Command description';
public function __construct()
{
parent::__construct();
}
public function handle(GlsCourierController $GlsController)
{
echo $GlsController->getServices() . "\n";
}
}
- Define the signature for the command. You can execute the controller functions by just calling the artisan command as below > php artisan import:GlsCourierData
Frontend
1. Create seperate vue component for courier settings
-
Create the component file inside
resources\js\src\components<template> // body </template> <script> export default { name: 'GlsCourierSettings', data () { return {} } } </script> -
Import and use the created component into resources\js\src\components\CourierSettings.vue as given in the below screenshot
-
Based on the courier name, we decide what courier settings component to render
-
Add the credentials and other details that you have for the courier in order to make apis work.
2. Update the resources\js\src\AwbGenerator.vue component.
-
Add the fields into fieldsToShow array that needs to be shown on AwbGenerate modal based on courier facility. You can also add new field if it is not there in the data array. We decide which courier fields to render based on courier id that come from couriers table as you can see in the screenshot.
