Removing the reinvented wheel

SilverStripe 4 has gone into alpha 1. One of the things we try to accomplish is to move our re-invented wheels to established and known libraries. This is to make sure that the support of our framework stays up to par. RestfulService and Oembed are examples of re-invented wheels that have been removed from SilverStripe 4.

RestfulService is SilverStripe's implementation of consuming data from APIs, whereas Oembed is used for inserting embedded objects like YouTube videos in the content. After a discussion on GitHub, questioning if it should be removed or not, both classes where deemed suitable to be removed and migrated to external libraries.

What does this mean for you?
With RestfulService removed from SilverStripe 4, what are your options? Of course, you still have to consume your APIs. And that’s where Guzzle comes in. Guzzle is a well-maintained, much-used HTTP consumption library. It supports pretty much every way of consuming data from an external source.

How do you migrate your current RestfulService code to Guzzle?

First, you'll need to add Guzzle to your composer.json and run a composer update, to have the library included in your code.

As an example, we are going to get information about a Github user. Here's how that would be done with the RestfulService:

class MyAPIController extends Controller {
       public function getGithubUser() {
                   /** @var RestfulService $service */
                   $service = RestfulService::create('https://api.github.com/users/silverstripe');
                   $result = $service->request();
                   print_r($result->getStatusCode());
                   print_r($result->getHeader('Content-Type'));
                   print_r($result->getBody());
            }
}

To update this code to use Guzzle, there are a few little changes to be made:

use guzzlehttp/guzzle

class MyAPIGuzzler extends Controller {
    public function getGithubUser() {
        $client = new GuzzleHttp\Client(array('base_uri' => 'https://api.github.com');
        $res = $client->request('GET', 'users/silverstripe');
        print_r($res->getStatusCode());
        print_r($res->getHeader('CONTENT-TYPE'));
        print_r($res->getBody()->getContents());
    }
}

As you can see, there’s not much to it. Guzzle is extremely easy to use and is well documented. But there’s a very important difference in the examples above.

To get specific headers in Guzzle, you can call them case-insensitive. That means you don’t have to remember if it was “Content-Type”, “content-type” or “Content-type”. Guzzle does that thinking part for you.

After removing the now deprecated RestfulService, next on the chopping block was Oembed. An implementation for consuming embed services.

The biggest difference is that Framework now requires Embed\Embed as part of the composer requirements.

If you used to use the Oembed class in your own code, moving to Embed is not very complex.

What needs to be done is add the use case to your class using the deprecated Oembed class and use Embed's method of creating the Embedded code:

use Embed\Embed;

class MyClassUsesOembed extends Object {
     public function __construct($url, File $file = null) {
          parent::__construct($url, $file);
          $this->embed = Embed::create($url);
          if(!$this->embed) {
                          throw new SS_HTTPResponse_Exception($response);
          }
     }
}

Codewise, the biggest difference is that now, we’re having the use statement and using

Embed::create($url) instead of Oembed::get_oembed_from_url($url); 

and the responses given by Embed, are slightly different from the Oembed implementation of SilverStripe.

An example of a change is that the HTML property on an Embed-response has changed to code, as per Embed\Embed definition.

The used package was voted as the preferred implementation for SilverStripe 4.

Don’t worry if you run into trouble! At SilverStripe, we have a lot of skilled folks that can help you if you have questions. Just pop in on IRC, for example, to get some help.

Deprecated SilverStripe 4 implementations of OEmbed and RestfulService can be found at github.com/Firesphere

Header photo by Crispin Semmens.