How to create an Active Record style PHP SDK Part 1

Jul 09, 2014

Table of contents:

1. What is the Active Record Pattern?
2. Why use the Active Record Pattern?
3. What are the benefit and drawbacks of using the Active Record Pattern for a PHP SDK
4. Setting up the package
5. Conclusion

Over the last couple of years, more and more online applications and web services have opened access to their APIs. This has been a fantastic opportunity to integrate various different applications together, pull data from sources or connect and build upon third-party services.

What’s more, a lot of the more developer focused services even produce and support official open source libraries for integrating their service into your application as quickly and easily as possible. And if there aren’t official libraries, more often than not, someone has already faced your predicament and built the library for you.

However, from time to time you do find a service that has an API but no open source library that would be a good fit to use.

Over the next couple of weeks I’m going to be looking at building a PHP SDK (Software Developer Kit) using the Active Record pattern. For some reason, you don’t see many PHP SDKs in the style of Active Record, whereas you see a lot in the world of Ruby.

As you will more than likely face the situation where you have to develop an SDK for a service to integrate into your application or for your own application, I thought this would be an interesting and practical series to get you started.

What is the Active Record Pattern?

Before I jump straight into the code, I think it will be valuable to talk about the Active Record pattern and why I’ve chosen to use it for this PHP SDK.

As I covered in What’s the difference between Active Record and Data Mapper?, the two main patterns of Object-relational mapping are Active Record and Data Mapper.

The Active Record pattern is where the entity you are working with is coupled to the persistence layer that stores the object. This means to save the entity to the storage is as simple as calling the save() method:

$user = new User();
$user->username = "philipbrown";
$user->save();

The Active Record style code above is extremely simple to understand what’s going on. This makes the Active Record style, both really powerful and really intuitive.

Why use the Active Record Pattern?

So why would I want to use the Active Record style for a PHP SDK?

Whilst in many situations it’s a drawback, having the persistence tied directly to the entity can often be an advantage.

In the case of working with a third-party SDK within your application, I think it’s better to think of the entity and it’s storage as one thing.

For example, when you pull data from an API, you don’t want to work with the raw JSON response, you want an entity object that you can use in your application. When you want to send changes back to the API, you don’t want to have to transform an object into a JSON payload and then send it back using a HTTP service.

Ideally, you just want to use the third-party service as objects and let the SDK deal with transferring the requests and response back and forth.

What are the benefit and drawbacks of using the Active Record Pattern for a PHP SDK

Now that I’ve explained what the Active Record pattern is and briefly why you would want to use, let’s look at the benefits and drawbacks of using the pattern for a PHP SDK.

Firstly, using the Active Record pattern will make working with the API much easier. An SDK that provides you with JSON responses isn’t that helpful in my opinion. By using the Active Record pattern we can provide fully implemented objects that can be used straight out of the box as a source of two-way communication with the API.

Secondly, the Active Record pattern will allow us to validate and restrict usage depending on the “business rules” of the API. This will hopefully make working with the API much easier for the developer as they will be restricted to only making requests that are valid.

And thirdly, we can encapsulate the relationships between the different resources of the API as Active Record style relationships. This will make working with objects and retrieving or creating related objects a lot easier.

However, using the Active Record pattern does have it’s downsides.

Firstly every single entity will need to inherit all of the persistence functionality as well as a HTTP connection in order to talk to the API. As with the traditional use of the Active Record pattern with a database, this can lead to a lot of overhead.

Secondly, in my experience, API’s usually have some weird idiosyncrasies and inconsistencies. By using the Active Record pattern we must tackle these inconsistencies to provide an abstracted and consistent interface with the API. We can’t just dump the payload to the developer like you could if you were just providing the raw JSON response.

And thirdly, the Active Record pattern relies on relationships between entities to fluently access related items. With a traditional SDK, you don’t have to worry about this because you can just leave it up to the developer to consume how they wish. But because we’re writing this in the style of Active Record, this will be another thing we will have to tackle.

Setting up the package

The package we’re going to be building over the next couple of weeks will be for CapsuleCRM, a Software as a Service application for tracking the companies and people you do business with. If you want to follow along you can sign up for a free account.

As with a couple of the recent PHP package tutorials, I will be porting an existing Ruby library to PHP. In this case I will be working from this package as my inspiration. If you are looking to pick up Ruby as a second language, this might be a good opportunity to learn how Ruby is similar and different to PHP.

The first thing to do is to set up the structure of the PHP package. I’ve already covered this in How to create a PSR-4 PHP package so I won’t cover old ground again.

Secondly I want to provide an example.php file that will provide examples of how to use this package. When connecting to the CapsuleCRM API we need to provide an API key and a subdomain. In order to make getting started with the package easier, I will provide a template file called configuration.php that will hold the developers API key and subdomain:

return [
    "key" => ",

'subdomain' => ",
];

Next commit this file to your Git repository and then add it to the .gitignore file and run the following command so git will not track any more changes to it:

git update-index -assume-unchanged configuration.php

Conclusion

This first article in this series was really just an introduction to the project and the initial first steps. For some reason you don’t see many Active Record style PHP SDK packages. I actually can’t think of any off the top of my head.

I think the Active Record pattern makes working with an API SDK really easy. If you are thinking about providing an open source SDK for your application, hopefully this mini-series will be a source of inspiration.

Over the next couple of weeks we will be tackling each aspect of building the package step-by-step. If you want to grab a copy of the code, it is available on GitHub.