Jaded available on GitHub

Jaded, the PHP library I've been working on is now available on GitHub.

I talked about using Jaded as a lightweight model layer back in November. I've since decided to rip out the controller and view stuff. It wasn't coming along as I'd hoped, and I've taken to using Zend to get things up and running quickly.

Besides the model library, there's also a pretty handy autoloader and a database wrapper around PHP's PDO library. Over time I will be adding some other useful classes, including some Zend plugins.

The Goal

I have pretty strong feelings about Agile. That is to say, I can't stand it. When someone mentions Agile to me all I think about are overpriced books, puffed up consultants and "coaches" and a whole slew of project management software tools that give Pro[du|je]ct Managers way too much noise vs. signal about how a project is really going. And all of it gets in the way of what I really love to do: sling great code.

But man, oh man, do I dig being agile.

There's already a pretty awesome article about the difference between "Agile" and "agile". It says just about everything I could write on the subject. Rather than rehash ideologies, I'm going to introduce a concept that has helped me towards gaining an agile mindset: the goal.

I've had the goal in my head for a while now. I never bothered writing it down anywhere until a presentation that I threw together in about 30 minutes to help my new team with their agile adoption. That presentation is the first time I've seen the goal presented and worded in that form (I don't take credit for the goal; it is the product of a lot of reading, attending other people's presentations, some experiences good and bad, and a healthy dose of my own biased worldview.) Here is the goal:

Deliver working, usable, high-quality software as quickly as possible.

The goal answers a simple question: why are we adopting agile? This isn't about the project or product. The business has already defined the rationale for that. The goal is about the rationale for wanting to be agile while accomplishing the project.

Nothing in the goal (or the Agile Manifesto, for that matter), speaks to a specific process or method. And that's where the power of the goal comes from. It speaks to what the team is trying to accomplish, while making the how a secondary concern. Focusing on the goal allows a team to easily see where their agility is being compromised:

• Is our software working? Is it ready to be put in the hands of our users? Are we making continual improvements to it?
• Is it usable? Does it meet our users' needs and goals? Does it provide value to the stakeholders?
• Does it have high-quality? Is the code clean, as bug-free as we can make it, and easy to fix when the bugs we missed inevitably appear?
• Are we delivering fast enough? Are we meeting the current needs of the business? Are we able to act on ideas and opportunities before our competition does?

If the answer to any of those questions becomes "no" at any time, then the process is broken. Fix it. You don't have to follow Scrum or any other Agile methodology to the letter. Process is highly context dependent. Only you and your team know what will get you to the goal.

If everyone can agree on the goal, the rest is downhill. The team will work out it's own way of getting there. I suggest Scrum as a starting point because, as a method, it's easy to understand. But I believe that a team that is really focused on the goal will probably leave the guardrails of Scrum and start building their own process fairly quickly.

There's a concept that I first heard from Alistair Cockburn but originally came from Japanese martial arts: Shuhari 守破離. The basic premise is that there are 3 stages to attaining mastery of a skill:

1. Shu — You imitate the form exactly. You do not deviate from the specified process, and you follow it to the letter.
2. Ha — You begin to innovate for yourself. You tweak the process to take advantage of your own special circumstances and strengths.
3. Ri — You no longer think in terms of forms or processes. There is a constant, smooth and uninterrupted flow of thought into action.

Everyone starts at Shu. Scrum is Shu, as is any other Agile method. Moving towards the goal helps a team move out of Shu and towards Ha. This is where agile beats out Agile. When you stop thinking about Agile or agile, and you simply act in the direction of the goal, you have attained Ri.

Git, TargetProcess and Hashtags

At $job, we're using TargetProcess for our user story and task management. One of the neat things you can do in TP is tag commits to a code repository in such a way that they will link to the task associated with that commit:

#123 This commit is linked to task number 123

In order to get this to work, the hashtag has to be the first thing on the first line of the commit message. Anyone using `git` as their source control should immediately see the problem with this...

...In git commit messages, any line starting with # is considered a comment and is stripped out of the commit message. Quite annoyingly, there's no way to change git's default comment delimiter. Since $job is using Subversion, this isn't a problem except for myself, the lowly git user hobbling along with git-svn.

The solution I've come up with is a two-pronged approach involving changing a default and adding a git-hook.

Firstly, the default --cleanup option on a `git-commit` command strips trailing and leading whitespace lines and all commentary (lines starting with #). So I aliased `git commit` to only worry about the whitespace lines, by adding this to my .gitconfig:

[alias]
    cmt = "commit --cleanup=whitespace""

So now git will leave lines starting with "#" alone. This means I have strip them out myself. This is accomplished with a git commit-msg hook that looks like this:

# Use TargetProcess hashtags to link commits to tasks
# use this in conjunction with --cleanup=whitespace
sed -e 's/^#.*//' -e 's/^@\(#.*\)/\1/' -i $1

The first sed expression strips out comment lines. The second one translates any line that starts with "@#" into one starting with "#". The trick is that it does it after the comment line stripping. So now I can do commits that look like this:

git cmt

# The editor opens and I can type:

@#123 This commit is linked to task number 123
# This is a comment line that will get stripped out
#  So it this

When the commit goes through, voila! A commit message starting with a hashtag that can be picked up by TargetProcess.

Edit 2010-12-16: After experimentation and verification, it turns out the TP can pick up the task id hashtag anywhere in the commit message. So all the above is not really necessary. It's interesting from an educational perspective, though.

Private Git repository with Dropbox

I recently began working on a project that needs a remotely-accessible private git repository. The project needs to be done on the cheap, and we don't have the budget to pay for a private github or assembla repository. We're already using Dropbox to handle project documentation and such, so it became a natural fit for sharing code as well.

I already have the Dropbox client installed and set up on my development machine. Here is how to set up the repo:

cd /path/to/Dropbox
mkdir myproject
cd myproject
git --bare init

This initializes a "bare" repo; a repo without a working directory. In other words, you can't edit and commit to it directly. The repo is now your "remote", hosted on Dropbox, and accessible through the local filesystem.

Create a working clone from the remote repo:

cd /path/to/myproject-working
git clone /path/to/Dropbox/myproject .

This will complain about cloning an empty repo, which is fine. Now follow the normal git development cycle:

echo "Read this!" > README
git add README
git commit -m "Initial commit"

When you're done making changes and committing, it's time to push to the remote repo in Dropbox:

git push /path/to/Dropbox/myproject --all

The `--all` flag is necessary on the first commit to the remote. It can be left off of all subsequent commits.

That's it! Now the repo is available on any computer linked to the Dropbox account, and can be checked out using the normal `git clone`, work, commit, `git push` cycle.

If you want other developers to have access, simply share the repo directory with their Dropbox accounts as you would any other directory. They can clone it and push to it just like any other git repository.

Here's another trick if you don't have the Dropbox daemon (dropboxd) running all the time on your development machine. Put the following script in "/path/to/Dropbox/myproject/hooks". Name the script "dropbox-push"

#!/bin/sh

dropbox running
if [ $? -eq 1 ]; then
 echo "Dropbox started by another process."
 exit 0
fi

dropbox start
until [ "`dropbox status`" = "Idle" ]; do
 sleep 1
done
dropbox stop

Now make the post-receive hook runnable:

mv post-receive.sample post-receive

Edit the "post-receive" file, and add the following lines:

cd `dirname $0`
./dropbox-push

Save the file. Now whenever you (or another developer) pushes to the repo, it will check to see if the Dropbox daemon is running, and if not, will start it and let it run until the code is synced, then stop the daemon. Since the hook itself is in under Dropbox, it will be synced and will be run for all other developers pushing to the Dropbox repo as well.

So there it is, a free, private git repository; at least, until the repository gets larger than the Dropbox free 2GB limit.

JadedPHP controllers

In my last post about JadedPHP, I talked about the model layer. Today, it's all about the controller layer.

Jaded controllers are built around the Intercepting Filter Pattern. In brief, when the Dispatcher sends a request to a controller for processing, the request is actually dispatched to a chain of filters which can modify it or check it for necessary attributes (has it been authenticated, etc.) before passing it on to the actual request handler.

A controller class extends the Jaded_Controller class, and needs to define a process() method.

class MyController extends Jaded_Controller
{
    protected function process(Jaded_Request $oRequest, Jaded_Response $oResponse)
    {
        $oResponse->assign('myVar', 'this is the assigned value');
        $oResponse->assign('requestVar', $oRequest->getParam('reqParam'));
    }
}

Here is a simple controller that assigns some values to a response variable. One of the assignments, myVar, is given by the controller. The other is taken from the passed in request object. If the name parameter was never set in the request, the getParam() call will return null.

$oController = new MyController();
$oRequest = new Jaded_Request();
$oResponse = new Jaded_Response();

// The way we get to the process() method is through the dispatch() method
$oController->dispatch($oRequest, $oResponse);

print_r($oResponse->getAssigns());
/*
Prints:
Array
(
    [myVar] => 'this is the assigned value'
    [requestVar] => 
)

*/

The requestVar is null because we never populated it. Here is a controller filter that will populate it for us:

class RequestFillerFilter extends Jaded_Controller_Filter_PreProcessor
{
    protected function preProcess(Jaded_Request $oRequest, Jaded_Response $oResponse)
    {
        $oRequest->setParam('requestVar', 123);
    }
}

//Now we modify the dispatching code from above
$oController = new MyController();
$oRequest = new Jaded_Request();
$oResponse = new Jaded_Response();

// Create the filter, wrapping the controller that will process the request
$oFilter = new RequestFillerFilter($oController);

// Filters are actually controllers themselves, and are dispatched the same way
$oFilter->dispatch($oRequest, $oResponse);

print_r($oResponse->getAssigns());
/*
Prints:
Array
(
    [myVar] => 'this is the assigned value'
    [requestVar] => 123
)

*/

requestVar was set in the request object before it was passed to the controller, so it was there for the controller to access.

Here's an example of a post-processing filter, that will handle our output for us:

class Print_RFilter extends Jaded_Controller_Filter_PostProcessor
{
    protected function postProcess(Jaded_Request $oRequest, Jaded_Response $oResponse)
    {
        print_r($oResponse->getAssigns());
    }
}

//And here is the usage
$oController = new MyController();
$oRequest = new Jaded_Request();
$oResponse = new Jaded_Response();

// Filters expect a controller as a construction param,
// but since filters are controllers, we can chain them like this:
$oFilter = new Print_RFilter( new RequestFillerFilter( $oController));
$oFilter->dispatch($oRequest, $oResponse);

/*
Prints:
Array
(
    [myVar] => 'this is the assigned value'
    [requestVar] => 123
)

*/

Notice that the dispatcher no longer needs to call print_r() itself, because the post filter will do it instead.

It gets unwieldy to have to keep wrapping controllers in filters, especially if a set of controllers always gets wrapped in the same filters. Jaded provides a Chain filter that let's you string together commonly used filters to simplify wrapping controllers in filters.

class CommonFilterChain extends Jaded_Controller_Filter_Chain
{
    protected $aFilters = array(
        'Print_RFilter',
        'RequestFillerFilter',
    );
}

$oController = new MyController();
$oRequest = new Jaded_Request();
$oResponse = new Jaded_Response();

$oFilter = new CommonFilterChain($oController);
$oFilter->dispatch($oRequest, $oResponse);

/*
Prints:
Array
(
    [myVar] => 'this is the assigned value'
    [requestVar] => 123
)

*/

It doesn't matter in this example, but filters listed in a chain are wrapped with the first listed filter as the outermost, and the last filter as the innermost. This is relevant when using a Jaded_Controller_Filter which defines both preProcess() and postProcess() methods.

The other interesting thing to note about chains is that they are filters themselves, so it is possible to have a chain filter listed inside another chain filter.

My goal in JadedPHP is to provide filters that perform tasks common to a web application and wrap them in easy to use chains. This way, the dispatcher can detect that a request is an HTTP request, and automatically wrap it in filters that will initialize the session, put the request method and parameters into a request object, set up an HTML or AJAX renderer, check for authentication and other necessary tasks.

The example source code is available here.

New domains

I just registered joshadell.com and everymansoftware.com. Right now, they both redirect to this blog. everymansoftware.com will probably continue to point here for a while. I intend to get some stuff up on joshadell.com about projects, maybe some live demos, who knows?

After attending indieconf yesterday, I was bitten by the bug to start making my name my "brand" and doing a little more self-promotion, blogging, and contributing to the web community.

I'm using DreamHost in case anyone is interested.

Models can be so Jaded

I am currently working on a PHP framework which I've been calling JadedPHP. It's purpose it to provide a lightweight MVC framework for some of my personal projects. Basically, I'm after a learning experience that provides useful output for me. If someone else gets use out of it as well, that's just icing on the cake.

My feelings on PHP frameworks in general are that they abstract way too much of the application's structure from the developer. I like to dig in and really know what's going on with the code that's running my code. Jaded is an attempt to build as little "automagic" into the framework as possible, and thus maximize the flexibility given to the developer to borrow bits and pieces as needed, and to override the rest if necessary.

The model layer is pretty solid so far. Models in Jaded are broken into 3 parts: a definition, a store, and a container.

The definition, oddly enough, defines the model. This means it lists the available fields of the model, which of those fields are key fields that uniquely identify the record held by the model, and any default values for those fields. Basically, the definition gives the model's structure, what it looks like.

A model store is the actual storage mechanism for the model. It implements basic CRUD operations, and is a place to define additional data manipulation tasks. The base class for model stores does not specify what the storage mechanism is. It could be a database, a CSV or XML file, or some volatile cache. It is up to concrete stores to actually implement the CRUD operations for a given model. (In reality, Jaded comes with basic database store that performs one model -> one row mapping using Jaded's PDO wrapper class.)

Finally, there is the model container itself. The container defines which definition and store the model will use. It is also responsible for holding the individual field values for a given record. It provides basic getter and setter functions, as well as the ability to fill a model from an array of values or spit out an array containing the values.

So how does this look? Let's pretend we have a database table that looks like this:

CREATE TABLE ducks (
    duckid int NOT NULL AUTO_INCREMENT,
    type int NOT NULL,
    name varchar(20) NULL,
    sound varchar(10) NULL,
    PRIMARY KEY duckid (duckid)
);

The definition for a Duck model would look something like this:

class DuckDefinition extends Jaded_Model_Definition
{
    const TypeMallard = 0;
    const TypeWood = 1;

    /**
     * Maps a name that calling code can use to an internal field name
     * Note that they do not have to match, and there can be multiple
     * aliases to a single internal name.
     */
    protected $aFieldMap = array(
        "duckid" => "duckid",
        "type"   => "type",
        "name"   => "name",
        "noise"  => "sound",
        "sound"  => "sound"
    );

    /**
     * The key fields for this model
     * Fields that uniquely identify it
     * A key of "auto" means the key is automatically set by the store,
     * else use "key"
     */
    protected $aKeyFields = array(
        "duckid" => "auto"
    );

    /**
     * Defaults for any fields
     */
    protected $aDefaultValues = array(
        "type"  => self::TypeMallard,
        "sound" => "quack"
    );
}

And now the store. In this case, I'm cheating and using the built-in basic database store:

class DuckStore extends Jaded_Model_Store_Database
{
    protected $sTable = "ducks";

    /**
     * This bit is simply the connection name used by Jaded's database wrapper
     */
    protected $sDbId = "duck_database";
}

And finally, a model container that wraps it all up:

class Duck extends Jaded_Model
{
    protected $sDefaultDefinition = "DuckDefinition";
    protected $sDefaultStore      = "DuckStore";
}

And now a bit of usage:

$oDuck = new Duck();
echo $oDuck->getType();    // prints "0"
echo $oDuck->getSound();   // prints "quack"

$oDuck->setName("Donald");
$oDuck->create();
$iDuckId = $oDuck->getDuckId();

$oDuck2 = new Duck();
$oDuck2->setDuckId($iDuckId);
$oDuck2->load();
echo $oDuck2->getName();   // prints "Donald"

// Now let's pretend we need to migrate all ducks to a CSV file, and we have a store for that
class DuckCSV extends Duck
{
    protected $sDefaultStore      = "DuckCSVStore";
}

$oDuck3 = new DuckCSV($oDuck2);
$oDuck->update();

Note how when we need to store the model in a different storage medium, we can just change the store type, and keep the definition and any methods that might have been built into the Duck class.

If the model's are stored in a database one row per model object, Jaded has a lot of functionality built in. But it also provides the flexibility to build model's that have the same definition, but have a store that pushes to/pulls from an RSS feed, or Twitter, or a stock ticker, or any other data source. For only a little extra setup, you get a lot of options.

There will probably be a GitHub repository soon, and another post or two as I start to use Jaded in more projects.