The tutorial is available as “New to Lithium” and is the first installment in what I hope can be a series of articles working with Lithium at the most basic levels through more moderate and advanced concepts. Be advised that this is only a draft. I’m making it available in the hopes that it generates feedback and serves the Lithium community in some constructive way. Feel free to provide critical feedback in the comments here or shoot me a line on Scribd where the document is currently published.

Read the first part of “New to Lithium” on Scribd

Download PDF Version

I should apologize: this post isn’t about actually providing these docs or explaining Lithium to newbies. Rather, it is an invitation for the Lithium community to join me in remembering the freshman class of our larger professional network. Strange as it may seem, my day job is actually in academics: I’m wrapping up a PhD in religious studies at Claremont Graduate University and have worked as a professor in teaching the more abstracted and secular approach to understanding religion and religious movements. And if there’s one thing I’ve learned in this field, it’s that the life blood of any social movement is the youths in the crowd, the converts, the rising generation. Those movements that lead these new initiates by the hand endure better than those that stand on the sideline while people transition.

I believe a key opportunity to capture more interest and users to the Lithium platform just surfaced: with the release of Lithium 0.10, MySQL and model associations are now supported to enough of a degree that a far wider net of PHP developers can transition over to what is more importantly concepts and structures Lithium provides that other frameworks don’t, or maybe don’t do very well. The time for a robust entrée to Lithium for this wider constituency of developers is now.

Billionaire entrepreneurs have made a mantra of the three most important aspects of a successful business plan: “Location, location, location.” If I were to translate this clichéd mantra for developer communities, it’d be “documentation, documentation, documentation.” (Sorry, Steve Ballmer, but it’s not developers that count: you don’t have developers without docs.)

I would like to try my hand at writing newbie docs, but I will make one confession: I already know that these will have to be rough drafts because of my own learning curve at play. But the real strength of open source communities is their collective writing process. So I’ll be forking the Lithium manual on GitHub and re-posting any updates I make to it here for your editorial comments. Screencasts are an especially effective medium for teaching processes and concepts; maybe I’ll be able to put some together as well. And last, but not least, I’d like to err on the side of trying when offering solutions in forums, chat rooms, and Q&A sites. If there’s a more elegant way to accomplish something, I’ll invite your critique. It’d be a tragedy if we held back in giving advice and in sharing solutions for fear of being called out or corrected in public view. When there’s such a fabulous tool coming out of a group of developers, I have to believe there’s something more to the community at work. I like to think that something includes a genuine camaraderie that anyone new to anything would appreciate, from one developer to another.

Titanium provides a useful platform for not only building desktop apps that are more consistent with the operating system’s UI, but also allows for cross-platform distribution to Mac, Windows, Linux, and even the major mobile platforms like iOS and Android. Because Titanium caters to web developers, it makes sense to combine the powers of Cappuccino and Titanium to leverage the strengths of both frameworks. Cappuccino ports sleek Cocoa concepts to its own JavaScript superclasses (Objective-J), making it possible to develop powerful web applications with the same feel and consistency as desktop applications. It has already succeeded well at bringing the powers of the desktop to the web browser; for one example, check out 280North’s 280 Slides application. (It’s essentially Keynote in the web browser.)

Combining the two frameworks was a simple two-step process. First, I got a Titanium desktop application project started. Second, I placed the contents of the main Cappuccino project into the Resources directory in the Titanium project directory, replacing the index.html file that comes with Titanium with the one used by Cappuccino. That was it. Now I can proceed to apply Titanium goodness where I like and base most of the application in Cappuccino. At this point, I’ll have to test for conflicts between the Titanium SDK and Objective-J, but so far, it’s been smooth as butter.

1. Prepare MAMP for MongoDB files

Create a new folder at Applications/MAMP/db/mongo with three additional subfolders named bin, data, and tmp. Provide these folders with chmod 0755 access permissions. These folders will be the main runtime location for Mongo once MAMP gets it running.

2. Download MongoDB

Grab the latest Mac OS install package of MongoDB. My server setup called for OS X 64-bit, version 1.6.5. It’ll have a directory named bin. Drop the files from this folder into the /Applications/MAMP/db/mongo/bin folder you already created.

3. Download Mongo Driver for PHP

I’m running PHP 5.3 (why use MongoDB with any earlier version of PHP?), so I’ll need the mongo.so extension to get PHP and Mongo working together. This is available at the MongoDB GitHub repository, under the PHP 5.3 for Mac binary. After unpacking the downloaded file, place the mongo.so extension file in the /Applications/MAMP/bin/php5.3/lib/php/extensions folder.

4. Create Startup Routines for MAMP

Lastly, you’ll need to create the startup routines so that MAMP will launch Mongo along with MySQL and Apache. Create a new file at /Applications/MAMP/bin/startMongo.sh and place in it the following code:

1
2
# /bin/sh

/Applications/MAMP/db/mongo/bin/mongod --dbpath /Applications/MAMP/db/mongo/data --logpath /Applications/MAMP/db/mongo/mongodb.log --pidfilepath /Applications/MAMP/db/mongo/tmp/mongo.pid --fork --logappend

When called, this script will launch Mongo using the MAMP-relative paths rather than Mongo’s system defaults.

Create another file at /Applications/MAMP/bin/stopMongo.sh and place the shutdown method:

1
2
# /bin/sh

/bin/kill `cat /Applications/MAMP/db/mongo/tmp/mongo.pid`

This works like the previous script, except it kills the mongo.pid process, effectively shutting down Mongo.

To have MAMP automatically call these Mongo startup scripts, open the /Applications/MAMP/bin/start.sh and /Applications/MAMP/bin/stop.sh files, and insert the following lines above the startMysql.sh lines, respectively:

1
/Applications/MAMP/bin/startMongo.sh

1
/Applications/MAMP/bin/stopMongo.sh

Now MAMP will automatically launch Mongo upon startup.

The only thing left to do is tell PHP to run the mongo.so extension. If you’re running MAMP Pro, edit the php.ini file by selecting File > Edit Template > PHP 5.3 php.ini, otherwise you’ll need to lookup the path the php.ini file from the MAMP startup screen, under “phpInfo” and “Loaded Configuration File.”

Insert the following line in the php.ini file/template, save the file, then restart MAMP.

1
extension="/Applications/MAMP/bin/php5.3/lib/php/extensions/mongo.so"

Mongo should now run in the background on MAMP, which you can connect with from PHP using the main connection routines listed on the PHP site. Welcome to NoSQL on MAMP!

Create the Test Class

To launch Lithium’s unit test dashboard, simply add test after your application’s root path. Assuming our new app is named “basic,” you’d type something like http://localhost/basic/test as your URL. By default, the dashboard only displays Lithium’s core tests. Let’s add one for our own app to evaluate a model.

Create a model test file in app/tests/cases/models and name it after the model class you intend to simulate. In my case, I’m testing a table holding data on composers for a sheet music application, so I’ll name my file ComposerTest.php. Now, place some standard code in this file so that the test classes will execute the unit tests appropriately:

On line 3, we specify the namespace for this class, which corresponds to the path in the application where this test class appears. Lines 5 and 6 call two classes that will allow the ComposerTest class to connect to the database and/or run methods in the Composer model, which, of course, is my runtime model for all of my Composer methods in the live app. Line 8 names the class following a convention: we add “Test” to the end of the model name we’re testing and we extend from the core unit testing class available as lithium/test/Unit.php.

Go back to the unit test dashboard and your new test class should appear on the left under app > cases > models > ComposerTest. Click the link to run tests on ComposerTest, and the results should light up green with zero passes, fails, or exceptions.

Perform a Unit Test

A very basic unit test performs a query to see whether the model connects to the database and can fetch records. I’m going to write a test function that allows me to see whether my model can perform a basic find query. In the ComposerTest class, I’ve written a function called testWhetherDbQueryWorks() that asserts whether a result set is null or populated with table data. It looks like this:

Simple enough. Lithium provides several other assertion methods, which are all described at the Unit class entry in the Lithium API.

Now, when I run the test in the dashboard, it ought to pass, provided I’ve set up my Composer class correctly.

Hope this helps for those beginners out there looking to try out Lithium. I’ll try adding more detailed information, or using screencasts, when I’ve got a little more time for documenting my experiences in Lithium.

So far, I’ve only had occasion to try out a few features, and the outcomes have already been promising. Here are differences I’ve picked up from how things are done in Cake.

Bootstrapping and Additional Libraries

Lithium’s way of bootstrapping the various libraries allow for various server configuration settings more easily than Cake. Rather than defining constants in the app/webroot/index.php file, server paths are stored in the app/config/boostrap.php file. Only two constants need changing if you adjust the folder structure on your server: LITHIUM_LIBRARY_PATH, which points to the core libraries directory, and LITHIUM_APP_PATH, which points to the application itself. Other core settings may be included in bootstrap.php; as good practice, I added

Lithium uses third-party libraries much more seamlessly than Cake. Before, the scripts would have to be included through a vendors folder and brought into the application using, essentially, an include-like function. What I had wanted was a little more flexibility for where third-party scripts could be stored, since the possibilities for what third-party scripts require, in terms of server configuration and installations, usually call for install paths very different from how Cake structures itself in the background. Lithium provides a configuration file, app/config/boostrap/libraries.php, which allows you to add libraries either with a require directive or by using its built-in Libraries class. I was able to drop the Doctrine ORM library in the app/libraries directory and bring it into my app with:

Easy enough!

Namespaces and MVC

How Lithium makes use of PHP 5.3′s namespaces improves the flexibility of building model and controller classes. In one app, I have a sheet music database that provides downloads to web users. On the home page, it provides a list of all the composers in the database and a list of the top ten most downloaded files. In Cake, to do this, the ComposersController class has two options to fetch those top ten downloads. One is to perform a requestAction call to the DownloadsController class. The other is to call its own model class and perform a bindModel on the Download model, then run a find method to pull the top ten downloads. This isn’t too difficult or bloated, code-wise, but notice how Lithium improves upon this scenario.

I simply add:

to the ComposersController class, then run the find method like so:

One advantage here is that I don’t have to directly instantiate the Download model class in the controller; I simply call its namespace with the use method, and all of its methods are available to the controller. I don’t have to worry about table associations if I don’t want to. And, well, the code just feels cleaner and yet still adheres to the MVC paradigm that keeps the various classes abstracted from one another.

Console

When it comes to Lithium’s console, it’s just a fun piece of work, and much easier to implement than Cake’s Bake script, in my opinion. Because Lithium makes more direct use with its li3 console app, the integration with your application comes pre-built and ready to go. What I’ve always appreciated about Ruby On Rails and Symfony is their use of the console to automate development processes. But I’ve also admired Cake for not being overly tied down to the console that you must create a particular shell environment to get the framework to install easily. In fact, in my earliest days of web frameworks experience, this factor pulled me over to Cake in the first place; I had spent hours trying to get Symfony to run correctly in my local console environment, but Cake just worked after dropping the main folder into my server root. I didn’t care what core features Symfony offered at the time because I could get right to work in Cake without any headache.

Lithium, on the other hand, improves upon both of these paradigms of console development, if you ask me. It maintains the same drag-and-drop installation capabilities as Cake, but comes packaged with console features that rival Ruby On Rails and Symfony. (I realize, though, that I’m speaking of a framework that is currently at 0.6, so some of this is my own predictions of what will come through at the 1.0 phase.)

Getting li3 to run required a simple adjustment to my .profile file. I simply added:

to my .profile (I have the Lithium core installed in my /usr/lib directory) and was able to call li3 in the terminal, and was in business. After following the Console Tutorial on the Lithium site, I had a numbers game up in minutes. In short, I created my own console class in the app/extensions/command directory and then ran it quite easily by pointing to the application with cd, and from there calling li3 numbers (numbers was the name of the console class). I didn’t have to add any flags to the command line, just simply browsed to the app folder, and li3 knew what to do from there. Now, obviously the numbers game is a trivial way of learning the capabilities of a shell environment for a framework. But the integration is such that I’ll be able to customize console commands to perform unit tests, populate the datasource with schematics, manage sessions, perform cron jobs, build custom classes automagically, and so on.

Datasources

I’ll admit that the hardest chapter to write for my Beginning CakePHP book was the one on datasources. This was simply because the documentation was sparse on even how to get datasources working, let alone explain a normative way for optimally doing so in the Cake environment. Since then, the documentation has gotten much better. Nevertheless, the datasource schema for bridging various sources favors a kind of database model, meaning, you still use the $useDbConfig property and define that value in the config/database.php file to attach a datasource to your Cake app.

Lithium, on the other hand, assumes wildly different ways of sourcing data to your app. In fact, it comes pre-built to handle cutting-edge datasources like MongoDB and CouchDB which require a little more flexibility to leverage their feature sets. It handles these sources not as databases per se, or as PDO abstractions, but as connections. This semantic difference actually amplifies the capabilities of the datasource structure because it further abstracts the way data is pulled, manipulated, and otherwise handled by the framework. Web services like the dozens Google and Facebook applications are providing all could interact with a Lithium app the same way a database would, without attaching duct tape here and there in your code base. This makes for leaner code, and above all, improves performance significantly.

Concluding Thoughts

Dedicating two months to Lithium after years on the CakePHP platform has made me a convert for one basic reason. In the end, they both will get it done, and will get it done well. But, to be honest, the experience feels different, and however else the pieces fall into place that make the two frameworks semantically and structurally different doesn’t really matter when push comes to shove. As a developer, I just want to enjoy coding and I want it to be lean and clean.

So it really has begun to feel a lot like my experiences on the Mac and PC platforms. On the one hand, the Apple paradigm fights vigorously to streamline the feature set and to zero-in on each feature as a unique contribution to the user experience. They are ready to scrap features if they have to in order to maintain an intuitive and clean experience because they know that in the end, the user has to come away with a positive and simple interaction with their software. But the Microsoft paradigm has always been one of amplifying the feature set as much as possible and creating a platform that cannot be brushed aside. They want to drag-race the competition and compete as a total platform, one that out-does everyone else’s feature set, though only recently are they working harder to focus on the user experience. (Check out The Marketing Playbook by John Zagula and Rich Tong for a detailed explanation of how Microsoft thinks about platform plays behind the scenes and demolishing competition through Windows integration.)

Cake has started to feel less clean and more like Zend Framework feels; chock full of features, but lacking in performance and rigorous streamlining of the core feature set. I give kudos to Garrett Woodworth, Nate Abele, Joel Perras, Alexander Morland, and David Persson for their vision for Lithium and encourage you to give their new rising-star framework a go.

Using this class is simple. Just download and place the CPDateHelper.j file in your Cappuccino app directory. Then include the class using:

Anywhere in your Cappuccino app, just provide CPDateHelper with a date string and a formatting string and it will return a formatted date string. For example:

In this example, formattedDateString will contain:

CPDateHelper also returns the formatted date string as a CPString object, so you can use CPString methods on it right out of the box.

Again, jump on over to the GitHub project to download the source or

Download CPDateHelper.zip

I don’t expect to live to 2100, so it shouldn’t matter. But, unfortunately, in programming world, remembering this caveat on the leap year could result in a bug, or worse, world cataclysm like we saw didn’t see with Y2K.

I recently landed this bug and had to write a way out of it. Here’s my solution in PHP, JavaScript, and Cappuccino.

1
2
3
4
5
6
7
8
9
10
11
function isLeapYear($aYear) {

    if (($aYear % 4) == 0) {

        if (($aYear % 100) == 0 && (($aYear % 400) != 0) {

            return false;

        } else {

            return true;

        }

    } else {

        return false;

    }

}

1
2
3
4
5
6
7
8
9
10
11
function isLeapYear(aYear) {

    if ((aYear % 4) == 0) {

        if ((aYear % 100) == 0 && ((aYear % 400) != 0) {

            return false;

        } else {

            return true;

        }

    } else {

        return false;

    }

}

1
2
3
4
5
6
7
8
9
10
11
+ (BOOL)isLeapYear:(int)aYear {

    if ((aYear % 4) == 0) {

        if ((aYear % 100) == 0 && ((aYear % 400) != 0) {

            return NO;

        } else {

            return YES;

        }

    } else {

        return NO;

    }

}

feature but in my localhost environment, I use MAMP. Upgrading PHP proved a little tricky, but actually very easy. The tricky part was figuring out how to make it work, but on the whole, it’s not too bad.

First, run the

function in a PHP script on your localhost or go to PHPMyAdmin and hunt down the configuration page. You should see a large chunk of configuration markup at or near the top:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
'./configure' '--with-mysql=/Applications/MAMP/Library' 

'--with-apxs2=/Applications/MAMP/Library/bin/apxs' 

'--with-gd' '--with-jpeg-dir=/Applications/MAMP/Library'

'--with-png-dir=/Applications/MAMP/Library' '--with-zlib' 

'--with-freetype-dir=/Applications/MAMP/Library' 

'--prefix=/Applications/MAMP/bin/php5' '--exec-prefix=/Applications/MAMP/bin/php5' 

'--sysconfdir=/Applications/MAMP/conf/php5' '--with-soap' 

'--with-config-file-path=/Applications/MAMP/conf/php5'

'--enable-track-vars' '--enable-bcmath' '--enable-ftp' '--enable-gd-native-ttf' 

'--with-bz2=/usr' '--with-ldap' '--with-mysqli=/Applications/MAMP/Library/bin/mysql_config' 

'--with-sqlite' '--with-ttf' '--with-t1lib=/Applications/MAMP/Library' 

'--enable-mbstring=all' '--with-curl=/Applications/MAMP/Library' '--enable-dbx' 

'--enable-sockets' '--enable-bcmath' '--with-imap=shared,/Applications/MAMP/Library/lib/imap-2006i' 

'--enable-soap' '--with-kerberos' '--enable-calendar' 

'--with-pgsql=shared,/Applications/MAMP/Library/pg' '--enable-dbase' 

'--enable-exif' '--with-libxml-dir=/Applications/MAMP/Library' 

'--with-gettext=shared,/Applications/MAMP/Library' '--with-xsl=/Applications/MAMP/Library' 

'--with-pdo-mysql=shared,/Applications/MAMP/Library' '--with-pdo-pgsql=shared,/Applications/MAMP/Library/pg' 

'--with-mcrypt=shared,/Applications/MAMP/Library' '--with-openssl'

Copy and paste this whole chunk into your text editor and remove the single quotes (search and replace should do it). Look for the flag

and replace it with:

1
--with-pdo-mysql=/Applications/MAMP/Library

If you don’t do this, you might end up with an

error.

Finally, add the following flag to the end:

1
--without-iconv

After you have downloaded the latest PHP release of your choosing from PHP Sources Snapshots,

to the downloaded directory in Terminal. Paste your reformatted configuration string (all of it, including the beginning

command) and run it.

After the configuration phase is finished, run:

1
2
$ make

$ sudo make install

Relaunch MAMP, and you’re good to go.

For you CakePHP users out there, now you can play with Cake3 releases (which apparently will be optimized for PHP 5.3+).