read

Over the last couple of years I've worked on several APIs, and during that time I've developed a set of tools that can be shared across multiple Laravel packages. One of these is a package which I lovingly called "Artisan API". I recently posted this package up on Github for the world to use.

It's a cool little package that gives you a friendly layer over Fractal so you can send out responses from your controller with things like this:

// respond with a collection
return $this->api->respondWithCollection($users, new UserTransformer());

// alot of simple helper functions for quick responses 
return $this->api->respondNotFound();

return $this->api->respondUnauthorized('Hey you can be here!');

return $this->api->respondOK();

// method chaining so you can send out custom responses

return $this->api
    ->setStatus(401)
    ->setResponseCode(ResponseCodes::UNAUTHORIZED)
    ->respondWithError('Not logged in');

It also came with a Facade if you like to do things that way instead

return API::respondWithItem($user, new UserTransformer());

it works with all the features of Fractal such as transformers and includes etc.

This is of course just a small glimpse of what can be done. For more information about fractal i suggest taking a look at http://fractal.thephpleague.com/ to get a better idea of all the capabilities.

Lesson 1: Project development workflow

I followed a fantastic guide here: https://medium.com/@tabacitu/creating-laravel-5-packages-for-dummies-ec6a4ded2e93, to help me understand a good development workflow. The best thing that I learned is that after you register your package with packagist.com (composer), you can still develop the package in your application after doing composer install by using the "--prefer-source" flag. If you do

composer install --prefer-source

This will install your dependencies so that when you navigate to the folder you can still use git and push changes to your package while using it! Makes it much easier then trying to develop the entire package separately.

Lesson 2: How to get the cool badges for your github package page

Most of the badges are very easy to get and use. They are simply a URL that you put in the readme file.

There is a terrific video tutorial here: https://egghead.io/lessons/javascript-how-to-write-a-javascript-library-adding-badges-to-your-readme To get you started on that.

My favorite badge for this project is the 100% code coverage badge. I used https://coveralls.io/ to get my badge. To get the code coverage recognized by coveralls I used this: https://github.com/satooshi/php-coveralls. It has relevant guides for travis-ci and many other automated build tools. What is great about coveralls is that it seems that is completely free for open source projects!

I wanted to make one important note about badges... It took many hours for my version badges to update. If you update the version of your package don't be surprised if the badge shows the wrong version for a day. I made the mistake of trying to "fix" this issue that I thought I was having, but I realized eventually that I was just being impatient and the badge was cached.

Should I use this package? Probably not.

When I originally created it, there was not alot of great alternatives. It has served it's purpose very well, and it will still be maintained as I have several projects which use the package.

BUT... I recently discovered Laravel Responder. A package which essentially does the same thing, except for it has some added bells and whistles for automatic includes on relations etc. It looks really fantastic and it has a decent following already and alot of interested users. This is good of course because it means it will most likely survive for a long time and continually improve over time.

TLDR

  1. You can develop your package while using it in a project by using "composer install --prefer-dist".
  2. You can get badges by linking urls in your README.
  3. Coveralls.io is cool because you can get the code coverage badge for free on open source projects
  4. It takes forever for packagist to update your release version badges, so just be aware that they are cached and will eventually update.
  5. Should you use this package? Nah, Laravel Responder is already a better and more mature option, however this package continues to serve me well on my older projects.
Blog Logo

Isaac Earl

Web dev & whatever else


Published

Blog Comments powered by Disqus.
Image

Isaac's Blog

Ramblings of a software dev

Back to Overview