Every Client’s Dream — a PHP project finished under budget and before deadline. How to do it?
This case study proves that what used to seem impossible can come true. Thanks to the gained trust, skills had the opportunity to bloom wildly and the whole project was finished better than expected.
The challenge: to build a Software Development Kit to simplify and ease the work with Client’s partners who have PHP e-commerce based systems.
Customer: one “friendly e-commerce platform” integrating third party e-commerce systems.
Main goals:
- build a thin wrapper over raw REST API calls
- provide “clean” and unified way to perform API calls
- provide a basic error preventing layer
- process requests and responses minimal way
Technologies used:
- PHP 5.4 (tested on versions up to 5.6)
- Guzzle (low level PHP HTTP client)
- Composer (dependency manager in PHP)
- Travis CI (Continuous Integration system)
- GitHub (source code hosting service)
The business story
Many e-commerce systems run on PHP programming language based systems. In order to simplify the integration with our Partner’s system, the idea of the “basic building block” was born. Having a generic API only is sometimes not enough to provide a rapid integration boost.
The Development story
The first barrier to the integration of the third party Partner’s applications is the lack of SDK. For example, take typical REST API calls. PHP programmers constantly need to wrap low level cURL calls. They start with the preparation of laborious requests and the interpretation of incoming responses. To add some sugar, every API producer adds some of its specifics, for example search and sort request construction rules. Responses may contain some metadata which need to be handled as well. Having all of this in mind we needed to build a library to allow integrators to skip this part and focus on their own e-commerce system specific tasks.
From the very beginning, the project was prepared as an open source library. The most liberal MIT license was picked, to be exact. GPL licenses cause troubles with the fact that the system using/modifying it must be released with the same license. MIT doesn’t have this restriction.
Open Source projects set a high target. Many OS projects have hundreds of contributors. They must have the proper environment to develop/get help/create issues. Automated testing and continuous integration is a basic requirement. GitHub is a perfect and well known place for every developer.
The next thing is that nowadays PHP community worked out some standards. For example, the Composer dependency manager (developed by the Symfony framework community) has become a standard per se. A properly prepared Composer package minimises the amount of work required to have the library installed. Modern PHP software just has to be Composer compatible.
Semantic versioning (roughly speaking — when the library loses its backward compatibility over time) is another requirement. Integrators have to know when it is risky to update to a new version.
Decent documentation is another requirement. Integrators want to know what a particular piece of code does and what outcome is expected. Proper documentation contains code snippets almost ready to use.
Integrators can easily create extensions on top of SDK, for example Magento Plugin. Developers using SDK do not need to know how the underlying communication between their system and API is implemented. They just set request params and read responses.
Recipe for success by Dawid Spiechowicz, XSolve Developer
Much depends on the attitude and approach of the Partner. I think it is important to open on both sides, early reporting on the possible slowdown of work and possible errors. If the Partner knows what he or she wants and is technologically aware and mature in terms of business and organisation, the work usually goes very well. In this project, I worked with our Partner’s CTO. We were able to build mutual trust. We evened out knowledge and expectations. Despite working remotely, I had the impression that we were cooperating side by side and in real time. The whole time I had the contact with one of the developers on the part of the Partner. Telecommuting was the most effective. The Partner took into account our proposals regarding the changes in the MIT license, the use of the Composer, the use of Guzzle, etc.
Photo credits: XSolve, Flickr
Originally published at www.xsolvesoftware.com on April 24, 2015.
