• Requirements
• Setting up the environment
• Running Lithium
• Fixing URLs

So Lithium is now officially out, and its 0.1 release can be freely downloaded from the official web site or by cloning the Lithium git repository. The good news is that although not many web hosts offer PHP 5.3, you can try it out youself, locally and with minimum effort.

Requirements ⇈

According to the Lithium Wiki, to develop applications with Lithium you need:

• A web server, like Apache or IIS
• PHP 5.3.0 or higher
• Git (not required, but all example projects are on git repos, so you may as well have it)

For this tutorial, more specifically, you need to download (just download, don't install anything!):

• mongoose, a tiny, standalone (as in one single file), cross-platform web server.
• PHP 5.3.0, not the installer, the zip package.
• Lithium (version 0.1, at the time of writing)
• The li3_docs plugin.

To get the li3_docs plugin you need to register on rad-dev.org, and clone the li3_docs git repository. If you don't have git installed or you don't want to read another awesome tutorial to install it and learn how to use it, I'll save you the hassle and let you download the plugin from here, for this time ony.

Note: This tutorial assumes that you are on Windows. If you are not, some things may be a bit different depending on your platform.

Setting up the environment ⇈

Choose a directory on your sistem (let's call it D:\lithium_test from now on). We'll do everything in here, and you can move it anywhere you like afterwards, even on a USB stick, without breaking anything.

1. Unzip Lithium in D:\lithium_test, so that it contains the following files and directories:
   • app/
   • libraries/
   • .htaccess (it won't actually be used in this tutorial)
2. Unzip PHP 5.3.0 somewhere and copy the following files to the D:\lithium_test folder:
   • php5.dll
   • php-cgi.exe
   • php.ini (just get php.ini-development from the PHP package and rename it)
3. Copy the mongoose-2.8.exe executable in D:\lithium_test and rename it to mongoose.exe for convenience.
4. Create a mongoose.conf file containing the following lines:

cgi_interp      php-cgi.exe
cgi_ext         php

If you did everything correctly, your D:\lithium_test directory should contain the following:

• app\
• libraries\
• .htaccess
• mongoose.exe
• mongoose.conf
• php-cgi.exe
• php.ini
• php5.dll

Running Lithium ⇈

Double click mongoose.exe and point your browser of choice to http://localhost:8080/app/webroot/index.php. You should see the Lithium temporary homepage (yes, I expected something fancier too):

Now, let's see if we can get the li3_docs plugin running as well:

1. Unzip li3_docs.zip and copy the li3_docs folder in D:\lithium_test\app\libraries\plugins.
2. Open D:\lithium_test\app\config\bootstrap.php and add the line: Libraries::add('plugin', 'li3_docs'); at the end. I actually found this commented out already (line 80).

Go to http://localhost:8080/app/webroot/index.php?url=docs, you should see something like this:

Congratulation, you're now running your first Lithium application!

Fixing URLs ⇈

Once the initial excitement wears off you'll notice that none of the links on the docs page works.

That's because the mongoose web server does not support URL rewriting (and Lithium needs it badly right now), so we have to change the way URLs are created. @nateabele gave me some tips on how to do this; it's very simple:

1. Create a directory called action in D:\lithium_test\app\extensions.
2. Create a file called Request.php, containing the following:

<?php
namespace app\extensions\action;

class Request extends \lithium\action\Request {

	protected function _base() {
		return  '?url=';
	}
}
?>

We're basically extending the \lithium\action\Request with a custom class, telling Lithium how to create the base URL.

After doing so, open D:\lithium_test\app\webroot\index.php and change:

echo lithium\action\Dispatcher::run();

into:

In this case, we're instructing the dispatcher to use our custom Request class instead of the default one.

Now everything should work as expected. Reload the docs page (http://localhost:8080/app/webroot/index.php?url=docs) and verify that the links work by navigating to Lithium, then action and finally Controller.

Now you can use Lithium to display its own API locally (if things didn't work out, there's always http://li3.rad-dev.org/docs).