Skip to content
PHP skeleton to kickstart development of microservices
Branch: develop
Clone or download
Latest commit a350d5f May 21, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci ☸️ Removed deploy_staging - deploying master to Kubernetes as new sta… May 20, 2019
app Added myparcelcom_shipment_id to shipment resource. May 10, 2019
bootstrap 🔨 Fixed namespaces of the JsonApi package dependencies where needed. Feb 7, 2018
config 🚧 Added validation translation file to add default messages and attri… Apr 12, 2019
docker 🐛 🐳 On build use the right specifications branch May 6, 2019
kube 🐳 Refactored building process for CircleCI Apr 29, 2019
public 🚨 formatted declare construct according to PSR-12 May 23, 2018
resources/lang/en ♻️ Added custom attribute names for item value properties. Apr 23, 2019
storage 🎉 Initial skeleton application Oct 19, 2017
tests Added myparcelcom_shipment_id to shipment resource. May 10, 2019
.env.dist 🔧 Removed github api token from config files Mar 20, 2018
.gitattributes 🎉 Initial skeleton application Oct 19, 2017
.gitignore 🎉 Initial skeleton application Oct 19, 2017 👌 Added docblock to redirect property and renamed shipmentRules method. Apr 15, 2019
artisan 🎉 Initial skeleton application Oct 19, 2017
composer.json 🔖 moved spec to required dev May 9, 2019
docker-compose.yml 🐳 Refactored building process for CircleCI Apr 29, 2019 💚 Added option to ignore tests Apr 9, 2019
phpunit.xml - Microservice Skeleton

This is a skeleton application for a microservice that facilitates the communication between the API and a carrier API.

The skeleton application already handles most of the communication with the API. Most of the functionality that needs to be implemented is described in TODOs in the application. It basically comes down to the following:

  • Transform existing classes to valid post and get requests for the carrier API.
  • Handle responses from the carrier API and map them to the existing classes.



The project uses Docker to run a local development environment. To install Docker, follow the steps in the documentation.


To setup the project (install composer dependencies, setup database, etc), run the following command:

./ setup


A few credentials are required to let carriers know who is making the request. The MyParcelCom API sends these credentials to the microservice in the X-MYPARCELCOM-CREDENTIALS header. These credentials are carrier specific, and usually consist of an api-user and api-password, or maybe an api-key for the carrier's API. The data in the X-MYPARCELCOM-CREDENTIALS header should be formatted in JSON, as the ExtractCredentials middleware in the microservice automatically converts this JSON to an array. It then passes the credentials array on to the implementation of the CarrierApiGatewayInterface through the setCredentials() method. Persisting information such as the API url should be set in the .env file.


There are several TODO comments added to the codebase to help you get started on what to implement. There are also several tests to check if everything is working as it is supposed to. The endpoint tests are the starting point to check if an endpoint does what is required from the carrier specification.

Response Stubs

The endpoint tests should not make actual calls to the carrier. They use a CarrierApiGatewayMock class to mock external calls. To make sure the tests do work with actual data, stubs must be created for the carrier responses.

To create the response stub, just make a call to the carrier's endpoint with your favorite API tool (like Postman). Copy and paste the entire response of the carrier into a file inside the /tests/Stubs directory. The file name should be equal to the url you accessed with the exception that all / characters are replaced with -. It should also be prefixed with the http method followed by another - and end in .stub.

For example:

// This request:
GET 'shipping/shipment/235446474/label'

// Would be stored as:

Error handling

Errors from the carrier should be transformed to JSON API error objects. To get you started, an AbstractErrorMapper can be found in app/Carrier/Errors/Mappers. This AbstractErrorMapper can be extended and called from the CarrierApiGateway to parse carrier responses and transform it into exceptions the exception handler can transform to a valid JSON schema response.

Carrier specific shipment requirements

Carriers tend to have specific requirements for a shipment request. Some carriers might require the shipment request to contain a description while others don't. To preemptively validate a shipment request based on a set of defined rules, we use the Laravel form request validation. When building a microservice, these rules should be added to make sure the request to the carrier is valid. The rules should be added to the shipmentRules() method in the /app/Http/ShipmentRequest.php file. For more information on Laravel's form request validation, see their documentation here.

Things to keep in mind

  • Labels must be returned as a base64 encoded string. If the carrier already returns a base64 encoded string make sure you don't encode it twice. The base64 encoded string should decode to a A6 sized PDF in landscape format. If the label is in portrait orientation rotate it 270 degrees so the top is on the left.
  • If the microservice needs to store data (logs, labels, service tables, etc.) make sure to save it in storage/.
  • Not all carriers have their own endpoint for credential verification. If they don't you can make a harmless request (such as a status update request) to test the credentials for the validate-credentials endpoint.
  • All time must be set in UTC


To start the containers, run:

./ up

To stop the containers, run:

./ stop

The following commands are available:

  • ./ - List running containers (for this repo).
  • ./ up - Start the containers.
  • ./ down - Stop the containers.
  • ./ setup - Setup the development environment.
  • ./ update - Update the development environment.
  • ./ upgrade - Upgrade the dependencies.
  • ./ composer <args> - Run composer inside the api container.
  • ./ artisan <args> - Run artisan commands inside the api container.
  • ./ test <args> - Run phpunit tests.
  • ./ test pudo|shipment|status - Test if one of the endpoints is correctly implemented.
  • ./ test skeleton - Test if the skeleton works correctly.
  • ./ microservice <args> - Run any command on the carrier container (nginx + php).
  • ./ <args> - Run any docker-compose command.

Composer commands

A few composer scripts have been defined, you can call these using the following commands:

  • ./ composer check-style - Check if the code is PSR-2 compliant.
  • ./ composer fix-style - Automatically fix non-PSR-2 code (not all errors can be automatically fixed).

TIP: You will run many ./ commands. Alias all the things!

# ~/.bashrc

alias mp="./"


To use Xdebug from your IDE you only have to configure the IDE. The used configuration can be found in docker/app/conf/xdebug.ini. Below are the steps to setup PhpStorm.

PhpStorm setup

  1. Go to Settings -> Languages & Frameworks -> PHP -> Servers and add a new server.
    1. Set a fancy name.
    2. For host and port use the address you use on your local machine to reach the api.
    3. Check Use path mappings
    4. Set the absolute path of the root directory to /opt/microservice and press enter.
    5. Apply/OK
  2. Go to Run -> Edit configurations and add a new PHP Remote Debug configuration.
    1. Set a fancy name.
    2. Choose your previously created server.
    3. Set the Ide key to the XDEBUG_IDE_KEY in your .env.
You can’t perform that action at this time.