This is the first article in a series about Docker and Docker tooling with the aim to give a foundation of developing with Docker.

This is a quick guide on how to get set up locally to develop with Docker. It assumes you have a basic understanding of what Docker and containerization is.

Concepts for Running Docker

There are a couple concepts important to understand that helped me a lot in getting up to speed:

Docker has two sides to it: a Docker client that can send commands to a Docker server (also referred to as the Docker host). The server is running the Docker daemon that will actually do the work. The daemon cannot run on Windows or Mac: it's Linux only. So to develop locally, you need a virtual machine (VM)^[1] to run the daemon and act as the server, and your Mac (or Windows)^[2] machine will act as the client, sending commands to build and run containers.

Here's an image taken from the Docker OSX installation docs that illustrates it well:

The Setup

So for development, you need Docker (the client) installed on your computer and a VM to act as the server. Then you set some environment variables to point to the Docker server (the daemon runs on TCP port 2376 by default), and commands run on the client will be sent to the server. When you build, the build context is sent to the server, and then the server does all the building.

Docker Toolbox

Fortunately, Docker has provided some tools to help you do all this: Docker Machine can provision a VM for you, and Docker Toolbox will install Docker, Docker Machine, VirtualBox (which can run VMs) and a few other tools.

After you download and install all those tools with the Toolbox, you can create a VM with Machine:

docker-machine -d virtualbox create default

(Where default is the name you want to give the VM, and can be anything you want.)

That will set up a VM appropriate for Docker development and then you can run a command to set up your environment so the client will use the VM as the server:

eval $(docker-machine env default)

To test that it's working correctly, you can run the Docker hello world:

docker run hello-world

It will pull (download) the hello world image if it isn't already downloaded on the server (which if you just set up a new Machine, it won't be) and if everything's working, print something like:

Hello from Docker.
This message shows that your installation appears to be working correctly.

(more content)...

Conclusion

Hopefully this will serve as a foundation to understand what's going on in subsequent articles, and to hopefully better follow along.

They say they guarantee their Prime shipments^[1] to be delivered by a particular date, but what do they do when that date is pushed back (as was the case with one of my shipments recently)?

Nothing.

I even opened a ticket to complain. They didn't even take responsibility, just blamed the carrier (perhaps it was the carrier's fault, but at no time did I receive a guarantee from UPS or FedEx, etc).

To be clear: I'm bothered that they slap that "guarantee" on it and it means nothing. They just do it to make you feel warm and fuzzy, but they're not going to do anything about it unless you make a real stink. As seen in the conversation below, I did end up getting a $5 credit, but I didn't want it that way.

I either want them to stop giving me empty guarantees, or have some sort of blanket policy to give a small credit when the ball gets dropped. The latter seems unrealistic since they don't have control over a lot of what it takes to deliver a package, and I would be satisfied with the former. Just call it what it is: an estimated date of delivery.

If you're curious, here's a screenshot of the original conversation and the entire conversation in text form is below:

Me: Hi, I got a shipping notice that an item was shipped with a "Guaranteed delivery date: Tuesday, June 2, 2015" and I was notified on the day it was supposed to be deliver that it won't be here (estimated) until "Monday, June 8, 2015"

Amazon: Hello, my name is Redacted. I'm here to help you today.

Me: Hello

Amazon: I'm sorry to hear that you haven't received the item as promised.
Just to make sure, are you referring to the item "Canon CA-110 CA110 Replacement AC Power Supply Adapter Charger for VIXIA HF R200 R20 R21 M500 M50 M52 R300 R30 R32 LEGRIA HF R26 R28 R206 Camcorders"?

Me: Correct

Amazon: Thanks for confirming.
It seems that the carrier delayed the package in transit. In this case, I'll contact the carrier on behalf of you and instruct to deliver your package with high priority.
Will that work for you?

Me: Well, what exactly is meant by "Guaranteed delivery date"
?

Amazon: I understand your concern, Cameron. the carrier delayed the package in transit. I'll also forward this to our shipping team to check the issue with carrier.
In addition to our large selection, one of the benefits we try very hard to offer our customers is convenience. I'm very sorry for the inconvenience you experienced in this case.

Me: You didn't really answer the question

Amazon: I understand your concern that we've promised you to deliver your package on guaranteed delivery date and the package was not delivered as promised.
To help compensate any inconvenience, I'll help you with one month prime extension. In this case, are you able to wait until June 5, 2015 to get the package?

Me: So... the guarantee means nothing? It's just marketing speak?
A false assurance?

Amazon: No, Cameron. I'm very sorry about all of this. I hope you'll consider this an isolated incident and give us another chance in the future.

Me: Well, maybe you should change the text to always say "estimated" instead of "guaranteed" if you're not going to do anything when it falls short.

Amazon: I understand your concern completely. I'm really sorry for the delay in delivering the package. If you prefer I'll help you with full refund and please refuse the package while delivery. I'll also forward this to our shipping team to check the issue with carrier and this will not happen in future.

Me: No, it's okay. That's not what I want

Amazon: To help you, I'll contact the carrier on behalf of you and instruct to deliver your package with high priority.

Me: That's not really what I want either, and you've said that at least 3 times now.

Amazon: To help compensate the inconvenience I'll help you with $5 promotional credit to your account.
Will that work for you?

Me: I guess, but ultimately, I would like for Amazon not to say they guarantee deliveries when they don't typically do anything about it. Either have a policy to give something like $5 credit if something goes wrong, or don't claim a "guaranteed delivery." It's very confusing and misleading.

Amazon: I understand your concern. I'll forward this to our appropriate team.

Me: Thank you

Amazon: I've issued $5 promotional credit to your account.

Me: Thanks

Amazon: You're welcome.
Thanks for your understanding and patience!
Is there anything else I can assist you with today?

Me: Nope

Amazon: Thanks for shopping at Amazon.com. We appreciate your business and look forward to serving you again in the near future.
Have a nice day!
Take care, bye!
Please click the "End Chat" link to close this window.

Me: You, too! Bye

This will make it a lot easier to keep Ghost up to date, and again, hopefully set the stage for bigger change that will probably come in 5-10 years at this rate...

I also updated to Node 0.12.1. I would have updated to io.js, but that would have taken more effort.

Most of the site is still intact. I completely removed a couple pages that had very few views and have been "deprecated" for over a year. So no one should even really notice anything other than the fact that the old home page is now gone (it's now the list of blog posts). I was never a fan of that page, so I'm not sad to see it gone.

Anyway, now all it takes to update Ghost is an npm update and we're off! I recommend you self-hosters give it a try. It's actually pretty slick and converting the blog itself was the easy part (updating the legacy content was less-so, but I think we're all good now!).

This is mostly a benefit to me (or I should say I mostly did it for me), but there are a number of benefits for you, the user, too.

Please report any issues you spot that might be related to this change so I can fix them.

This article assumes we're all on the same page as to why we should be using migrations. This article is to dissect the how.

The Current State

I tried to research as many different migration tools as I could before writing this article. I even pulled down code for a few of them to get a more hands-on feel for some of them.

Full Disclosure: I haven't used very many of these in a real-world application, and some I haven't used at all, just perused the docs. Please let me know if I got something wrong.

Four of the six migration tools on the first page of a Google Search for php database migrations all have similar approaches (using Phinx as an example, as it's mentioned four times on the first page and it's framework/ORM agnostic):

<?php

use Phinx\Migration\AbstractMigration;

class CreateUserLoginsTable extends AbstractMigration
{
    /**
     * Migrate Up.
     */
    public function up()
    {
        // create the table
        $table = $this->table('user_logins');
        $table->addColumn('user_id', 'integer')
              ->addColumn('created', 'datetime')
              ->create();
    }

    /**
     * Migrate Down.
     */
    public function down()
    {
		$this->dropTable('user_logins');
    }
}

This is a incremental snapshot of what you want to have done in the database. If at a later time, you need to add an updated field to the database, you must create a new migration:

<?php

use Phinx\Migration\AbstractMigration;

class AddUpdatedColumnToUserLoginsTable extends AbstractMigration
{
    /**
     * Migrate Up.
     */
    public function up()
    {
        $table = $this->table('user_logins');
        $table->addColumn('updated', 'datetime')
              ->save();
    }

    /**
     * Migrate Down.
     */
    public function down()
    {
        $table = $this->table('user_logins');
		$table->removeColumn('updated')
              ->save();
    }
}

The syntax is different, but for the most part, the approach is the same.

From here, you just run some sort of command to run the pending up commands, and if there is an issue, you can rollback which runs the down commands. The idea here is that you commit these migrations with your code, and if so if you pull down any particular commit of the code, you can either move forward or back, going through each migration in order, to arrive at the state the database was in at that particular commit.

What's Wrong with this Approach?

First of all, It's so very tedious to make minor changes to your database. If you're still in development and haven't pushed your code, you can just rollback, make a change to the migration, and then re-run the migration. This is a bad idea to do if you've already pushed the migration, especially if you've already pushed it to production. Changing migrations after the fact can (and often do) cause systems that have already run those migrations to not pick up those changes and thus the database is no longer in sync.

For this second reason, I feel that it's so obvious that this is an issue, it's easily overlooked—including me—until the glass was shattered by looking at how other languages do it: no where in the code is there an absolute list of the fields on the models/fields in the database.

Okay, okay, I guess that point really does depend on the code you're using, i.e. the framework may or may not have a way to support this. In my research, I found Laravel to be the most popular PHP framework this year. Laravel does not use property names on the model, and thus you can't really go to the model to see what fields belong there. On the other hand, Phalcon, another popular PHP framework, does. This is less of an issue in frameworks Phalcon, but Phalcon doesn't support the "easier way" of doing migrations that I will discuss later.

Other Contenders

Doctrine and Propel are both under the Symfony umbrella, and that may explain why they have some similar functionality. They both allow for a configuration file definition of models (Doctrine actually has a bunch of different ways you can define the models).

I find this approach to be a lot better, but the way these ORMs do it still have their issues. Let's first explain how they approach it:

As an example (taken from the Propel docs), you would create an XML file:

<database name="bookstore" defaultIdMethod="native">
  <table name="book" description="Book Table">
    <column name="id" type="integer" primaryKey="true" autoIncrement="true" />
    <column name="title" type="varchar" required="true" primaryString="true" />
    <column name="isbn" required="true" type="varchar" size="24" phpName="ISBN" />
    <column name="author_id" type="integer" />
    <foreign-key foreignTable="author" onDelete="setnull" onUpdate="cascade">
      <reference local="author_id" foreign="id" />
    </foreign-key>
  </table>
  <table name="author">
    <column name="id" type="integer" primaryKey="true" autoIncrement="true" />
    <column name="first_name" type="varchar" />
    <column name="last_name" type="varchar" />
  </table>
</database>

You would then execute a diff command, that will automatically create a migration for you (both Doctrine and Propel create code that executes raw-SQL migrations on the high level, i.e. DB::exec('CREATE table ...');).

It looks at the current schema in the database and creates a diff based on the current state of the XML config (you would then run that migration to actually change the database). The first time you run that diff command, it would create the table and all the columns. Then, if you want to add another column after the fact, you edit the schema XML, adding the necessarily XML, i.e. in the author table node in the example, you could add

<column name="middle_name" type="varchar" />

Then you run another diff command, and it would create and up and down migration that would, respectively, add and remove the middle_name column to the authors table.

The Comparison

I find this 2nd approach to be vastly more simple. You only have to change the schema in one place, and the tedious part is done for your automagically. You have an absolute definition of the schema (which maps to the models) for quick reference.

The only downside I can think of: you could only have one pending migration at a time. You'd have to apply the last migration before you could do another diff, otherwise the diff wouldn't work, because it'd be based off an old version of the schema. You could get around it with comparing the schema that would be if you ran the first migration before creating a second.

I don't find this necessary. If you've pushed, you should have executing that migration anyway. If you haven't pushed, you can just undo that migration and create a new one. i.e. instead of having 2 migrations: A -> B -> C, you just have one: A -> C.

Now, while I think the approach is superior, the only two stable, in-common-use migration tools I could find were wrapped behind huge ORMs. I've played with Doctrine migrations a lot, but a ton of the configuration defines behavior of the model that has nothing to do with the migrations, but with how Doctrine behaves. Basically: it's tied too tightly to the Doctrine ORM and isn't appropriate to use with other ORMs/frameworks.

The Solution: A Proposal

The solution is to start with an existing tool that can handle all the abstraction away to make migrations easier to handle. That is, I think Phinx is the perfect place to start. Rather than having to re-invent the wheel and figure out how to write raw SQL to support different database vendors, we take what we know does work as a starting point.

Phinx is also ORM/framework agnostic, and building a tool to extend from Phinx would wisely also be ORM/framework agnostic, and should be able to replace another ORM/framework migration approach.

From there, we support schema definitions like Propel. But we don't only offer XML. We offer basically any transactional data format that can be mapped to a PHP array that would look something like this:

[
	'table' => 'users',
    'columns' => [
    	'name' => [
        	'type' => 'string',
            'length' => 100,
        ],
        'email' => [
        	'type' => 'string',
        ]
        ...
    ]
]

It'd be easy to support XML, YAML, JSON, obviously a PHP array.

If you were to run a diff on this schema for the first time, you'd end up with this migration in Phinx, automatically generated:

<?php

use Phinx\Migration\AbstractMigration;

class AutoCreateUserTable extends AbstractMigration
{
    /**
     * Migrate Up.
     */
    public function up()
    {
    	// IDs are automatically added in Phinx
        // (IDs can be changed/overridden)
        $table = $this->table('users');
        $table->addColumn('name', 'string', ['length' => 100])
              ->addColumn('email', 'string')
              ->create();
    }

    /**
     * Migrate Down.
     */
    public function down()
    {
		$this->dropTable('users');
    }
}

Bam. Best of both worlds. We still have incremental migrations, but it's done automatically. Before committing this migration, we could make tweaks (just as long as the final schema is the same). For example, if the auto-migration generated dropped and added a column when what you wanted was to rename the column, you could tweak the migration to rename the column instead. Just as long as the final state of the database is same as the current schema.

Or, better yet, the accompanying command-line tool would detect those types of discrepancies, and ask you if you want to drop/add or rename. (This may be a v2 type of thing.)

As a last thought, there's something else I want to add... I know this will be controversial, I strongly believe it should support PHP annotations. Which don't technically exist, I know (I think they should. Maybe a blog post for another day). While I think PHPdoc annotations aren't great... I think it's worth the "not so greatness."

The rationale is that if you have a framework that has the field names in the models like Phalcon, you wouldn't want to have to update your schema in two places (the schema definition and the model definition). For example:

<?php namespace App;

use \Phalcon\Mvc\Model;

/**
 * @Table('Users')
 */
class Users extends Model
{
	/**
	 * @Type('integer')
     * @Signed(false)
     * @PrimaryKey
	 */
    public $id;

	/**
	 * @Type('string')
     * @Length(100)
	 */
    public $name;

	/**
	 * @Type('string')
	 */
    public $email;
}

This way, you still have your schema and your model definition and no redundant code.

Conclusion

I hope you see the potential as I do. I'm okay if you think this idea is stupid. You don't have to use it. I obviously think you should. I think it greatly simpliefies the process and lowers the barrier of entry. As far as I can find, this would be the first and only not-tied-to-an-ORM/framework implementation in PHP out there.

I hope to have a working proof-of-concept prototype up by the end of the year with at least MySQL support for basic stuff.

Please, if you have any questions, comments, suggestions, corrections, personal crises, or you just wanna call me out on something, please feel free to leave a comment, contact me, or reach out to me on Twitter.

Appendix A: Because Node is often used with noSQL databases, it is more common to have a schema defintion approach, and a few ORMs I've used in Node (Waterline, Sequelize) have support for SQL database vendors and thus provide automatic database syncing based on schema.

Appendix B: .NET supports a couple different ways to do automatic migrations. It's pretty powerful and in the .NET world, it's hard to say something like this is "only for small, simple projects."

"Never. You don't need'em. Well, for loops. They're required there.

"And null loops such as: while (something);. But you probably shouldn't be using those anyway, right?

"Oh, and case "foo": doSomething(); break

"Er, and in front of a leading ( or [ at the start of the line. Can't forget that. Otherwise the expression could be interpreted as a function call or property access, respectively.

"Well, and I guess lines starting with - and + need to be prefixed with a semicolon, but that'll probably like never come up.

"But yeah, just don't forget those simple edge cases and you'll be fine. It's really pretty simple. You'll probably only waste a few hours occasionally on stupid little things you forgot."

"Simple, eh? I have a pretty simple rule when to use them, too: always. Much easier to remember!"

Thanks to npm's style guide that helped me write this article by showing me just how foolish the don't use them policy is for semicolons in JavaScript.

It has a neat little feature that will sync your folders on the host to the guest VM, so you don't even have to SSH into the guest VM do most actions.

Occassionally, however, you need to run a command directly on the guest VM, such as a migration. Normally, you have to either run vagrant ssh and then change the directory to where the project is (it's very common to create an alias on the guest that points to the project root in the form of /vagrant/), run the command and then exit to get back to your normal shell.

Or, you can combine that into one command:

vagrant ssh -c "cd /vagrant && command to run"

But that is a lot to type out every time!

So I created a little "Vagrant user do" bash function (just place this in your .bashrc (or, if you're like me, your .zshrc)):

function vudo() {
  eval "vagrant ssh -c \"cd /vagrant && $@\""
}

Usage:

$ vudo composer update
$ vudo php artisan migrate
$ vudo anycommandyouwanttorunonyourvmfromyourvagrantfolder

Now you can quickly and easily run one-off commands in your VM with very little effort.

I present the Server Grab Pattern:

// inside a controller (or whatever. you get the idea):
$q.all({
    users:   api.get('users'),
    books:   api.get('books'),
    bananas: api.get('fruit').then(function (fruit) {
        return _.pluck(fruit, 'banana');
    }
}).then(function (responses) {
	angular.extend($scope, responses);
}).catch(errorHandler);

The idea here is that it's a very clear way to simultaneously grab a bunch of stuff from the server, maybe do individual manipulations before attaching to the $scope where it's clear where each piece goes, etc, etc.

And then in one line in the response, you put everything on the $scope and you can handle all the errors at once. Once I started using this, I cut down on a lot of lines of code and I personally find it easier to read than what I was using before, too.

What's Happening

$q.all can take an array or map of promises (they don't even actually have to be promises!) and runs them all asyncronously and once all of those promises are returned, then it passes the array/map with the resolved values to the then handler. Since you can chain promises, you can arbitrarily do something with just certain responses and they could even return promises (or not, like in this example, as this example makes it clearer that we're manipulating that data straight from the server).

Yeah, I think promises are pretty dang awesome, too.

It's just a cool little pattern I've been using and wanted to share. Ya know. Since it's 11:37pm on June 30th and my goal was to write 2 posts every month this year...

$parsers/$formatters are an array of actions that take in input, translate it to either the computer-friendly or human-friendly format respectively and return the translated value.

The Code

angular.module('myApp')
.directive('myDirective', function () {
	return {
    	// $parsers/$formatters live on the
        // ngModel controller, so we need this!
    	require: 'ngModel',
        link: function (scope, elem, attrs, ngModel) {
        	ngModel.$parsers.push(function toModel(input) {
            	// do something to format user input
                // to be more "computer-friendly"
                return modifiedInput;
            });
            
            ngModel.$formatters.push(function toView(input) {
            	// do something to format user input
                // to be more "human-friendly"
                return modifiedInput;
            });
        }
    };
});

Your $parsers/$formatters can do just about anything, and you don't strictly need to have one of each, but it usually makes sense that if you take an input and apply a matching $parser and $formatter (or vice versa), you would get the same original input. This is just probably the most common use-case, but a hard and fast rule or anything.

Note that we're pushing (you can also unshift) functions onto our $formatters/$parsers. Remember that inputs can have multiple directives on them, and thus can have multiple $formatters/$parsers.

Example: Tag List

In this example, you can enter in a string of comma separated values, and the model will be an actual array of values split by the commas. Conversely, you can set the model to an array and the input will appear as a string of comma separated values.

See the Pen $parsers/$formatters demo by Cameron Spear (@CWSpear) on CodePen.

But it's still not simple enough! And I like simple. I work on all sorts of projects, and while I often like the fine-tuning of error handling that Angular affords me, sometimes, I just need something simpler that Just Works™ with minimal effort and configuration.

That's why I built the Form Errors directive. (Catchy name, eh?) It couldn't be simpler to use and the default configuration works 99% of the time (or at least it does for me).

Let's see it in action

<form name="theForm">
  <input type="text" name="name" ng-model="user.name" required>
  <input type="password" "password" ng-model="user.name" required ng-minlength="8">
  <form-errors></form-errors>
  <button type="submit">Submit</button>
<form>

That's it. Really. By putting <form-errors></form-errors> inside a form, it will display a list errors as we type. We can conditionally show the list if we want (see demo), only after they try to submit it, or we can just show it to them as they type.

In this example, <form-errors></form-errors> would display this markup for this form when it's blank:

<ul class="form-errors">
  <li class="form-error">Name is required.</li>
  <li class="form-error">Password is required.</li>
</ul>

It automagically gets the name to use from the name attribute of the input and humanizes it, meaning it turns camelCase into Camel Case, dash-case into Dash Case and snake_case into Snake Case. You can override this to be anything you want with the nice-name attribute on the input. (See docs for how to do this and also how to display custom messages.)

If you start typing in the Name field in the example above, the Name is required message goes away. If you start typing in the Password field, the message is changed to Password is too short until the password is at least 8 characters long, then that disappears, too.

Ease = Efficiency = Time = Money

This thing really has saved me a lot of time because I can be more efficient about how I do the markup and handle the form errors. It may not be the best UX, but when you're doing a ton of forms with a ton of inputs each, this can save you a lot of time.

You can combine this with the ng-invalid classes Angular adds on inputs to get the best of both worlds: immediately drawing them to the error and displaying a message as to what went wrong, all with the minimal amount of effor.

I hope the directive can help you as much as it's helped me. Check out the project on GitHub.

But we did it! Big thanks to Lawrence Allen for desiging these awesome sites and helping me get everything ready to launch.

Millennium Sport Technologies

Millennium Sport Technologies (MST) sells quality sport supplements. They wanted a quality responsive ecommerce site that they could manage the products themselves (something that they couldn't do on their old site).

Roast House Coffee

Roast House Coffee (RHC) sells coffee. Really good, high quality coffee. We got the awesome opportunity to not only build them a new website, but we (i.e. Lawrence) redid all their branding and labels, too, which is really exciting!

Need a website?

If you like what you see and are in need of a new website, please contact us on the Mavrx site and we can build something awesome together!

Anyway, this post isn't about how awesome Craft is (which it is), it's about a piece of auspiciously missing documents: how to create your own Twig filter inside of craft!

Word It Up

For demonstration purposes, we're going to create a simple "Word It Up" filter that takes a number and converts each letter into its corresponding words (just on a per-digit basis).

For example, if we were to put this in our template:

<p>{{ 123 | wordItUp }}</p>

it would output:

<p>one two three</p>

Building the Twig Extension

This guide will assume you're familiar with building Craft Plugins. (The full code used in this example is up on GitHub as a template.)

Your Twig Extension files will go within a your plugin directory in a directory called twigextensions. So assuming our plugin is named Word It Up (which is it is in this example), our directory structure would look like this:

craft
└── plugins
    └── worditup
        ├── WordItUpPlugin.php
        └── twigextensions
            └── WordItUpTwigExtension.php

(As an aside, you should definitely checkout the tree command line tool (i.e. brew install tree).)

In our WordItUpPlugin.php file, the only thing special we need to do is add an addTwigExtension function and return an instance of our Twig Extension:

public function addTwigExtension()
{
    Craft::import('plugins.worditup.twigextensions.WordItUpTwigExtension');

    return new WordItUpTwigExtension();
}

Now we go into the WordItUpTwigExtension.php file itself. We need to include use some Twig stuff at the top of our file (along with the Craft namespace):

namespace Craft;

use Twig_Extension;
use Twig_Filter_Method;

class WordItUpTwigExtension extends \Twig_Extension
{
	...

The only other "special" stuff we'd need is a getFilters function that returns Twig-wrappered methods referenced in your class:

public function getFilters()
{
    return array(
        'wordItUp' => new Twig_Filter_Method($this, 'wordItUp'),
    );
}

All this says is that if we use a wordItUp filter in the Twig template, it will pass the input to your wordItUp function in from the current ($this) class.

Extra Parameters

For completeness sake, the way filter parameters get mapped from Twig template to filter function is like so:

{% set red = 'red' %}
{% set blue = 'blue' %}
{% set green = 'green' %}
{{ red | someFilter(blue, green) }}

maps to

public function someFilter($one, $two, $three) 
{
	echo $one; // 'red'
	echo $two; // 'blue'
	echo $three; // 'green'
}

so you can pass in as many extra parameters as you need.

Full Example

Here's the full WordItUpTwigExtension.php file:

<?php 
namespace Craft;

use Twig_Extension;
use Twig_Filter_Method;

class WordItUpTwigExtension extends \Twig_Extension
{
    private $digitToWord = array(
        0 => 'zero',
        1 => 'one',
        2 => 'two',
        3 => 'three',
        4 => 'four',
        5 => 'five',
        6 => 'six',
        7 => 'seven',
        8 => 'eight',
        9 => 'nine',
    );

    public function getName()
    {
        return 'WordItUp';
    }

    public function getFilters()
    {
        return array(
            'wordItUp' => new Twig_Filter_Method($this, 'wordItUp'),
        );
    }

    public function wordItUp($number)
    {
        $output = array();
        
        foreach (str_split(intval($number)) as $digit) {
            $output[] = $this->digitToWord[$digit];
        }

        return implode(' ', $output);
    }
}

Conclusion

Now you can go and install your plugin via the Craft dashboard and use your new filter in a plugin, and voila! You "Worded It Up!"

You can now turn

<p>{{ 123 | wordItUp }}</p>

into:

<p>one two three</p>

View full plugin on GitHub.

You may not have heard of wiredep before, but it's likely you've used it if you've used the grunt-wiredep (formally grunt-bower-install) Grunt plugin which is a popular one that uses it, and was a precursor to wiredep.

Both the Node package and the Grunt plugin were built by Stephen Sawchuk, a friendly, talented developer from Michighan. I don't know very much about him, even though he has added me to the team that manages wiredep. He works on the Yeoman team and built grunt-wiredep for use in the awesome build systems that come with many Yeoman generators, and eventually extracted the parts out to create what is now known as wiredep and modified the original Grunt plugin to be a wrapper around wiredep.

Anyway, introduction done. On to the meat of the article:

Wiredep, Streams and Gulp, oh my!

I've been talking about streams a little bit lately and how it relates to Gulp. Well, streams can be pretty cool, and are a fundamental part of how Gulp works.

You might ask yourself, "Why isn't there a gulp-wiredep pulgin?" Before I answer, I'd liket to remind you of one of Gulp's tenents, taken from their website:

By preferring code over configuration, gulp keeps simple things simple and makes complex tasks manageable.

In other words: why create a dedicated gulp-wiredep plugin when you can just use wiredep directly in your Gulp build? Indeed, you can just use wiredep straight up in your Gulp build in its own task. But once you try to do more complex things, you may run into some issues in not being able to fully integrate wiredep with the other streams from Gulp.

That is, until you realize that wiredep supports streams! It wasn't documented until only recently (in part, thanks to my efforts, I might add ;-)), but I was digging into the source code of wiredep, trying to figure out something else, and I noticed that it had some code related to streams. I dug a little deeper, and indeed, wiredep has stream support for perfect integration with Gulp (and anything else that would use a stream).

For example, I had been using wiredep without streams like this:

/////////////////////
// Without Streams //
/////////////////////

var gulp    = require('gulp');
var wiredep = require('wiredep');

gulp.task('bower', function () {
  wiredep({
    src: './src/footer.html',
    directory: './bower_componets/',
    bowerJson: require('./bower.json'),
  });
});

which was all well and good until I needed another task that depended on the bower task from being completed. The simplest way to do that was to return a stream. Well, good thing wiredep support streams! Change the above code to this and then we're all good:

//////////////////
// With Streams //
//////////////////

var gulp    = require('gulp');
// note that we're grabbing the stream function
var wiredep = require('wiredep').stream;

gulp.task('bower', function () {
  gulp.src('./src/footer.html')
    .pipe(wiredep({
      directory: './bower_componets/',
      bowerJson: require('./bower.json'),
    }))
    .pipe(gulp.dest('./dest'));
});

BAM, just like that, we have full Gulp integration!

Conclusion

As many of you that have been getting into Gulp more have noticed, the solution for a lot of your Gulp needs aren't always a Gulp specific plugin. That's one of the cool things about Gulp: it's just code.

wiredep is one of those tools that has everything you need out of the box and there's no need for a Gulp specific plugin. Employ some of the techniques in this post and you too can benefit from the Wiredep magic of simple, auto-linking, Bower dependency management.