all repos — h3rald @ e01ac492551ca28b6695e7651cda797517ed9d9e

The sources of

New Lithium article.
Tue, 27 Oct 2009 16:04:38 +0100




A content/articles/getting-started-with-lithium.textile

@@ -0,0 +1,120 @@

+----- +permalink: getting-started-with-lithium +filters_pre: +- erb +- redcloth +title: Getting Started with Lithium +date: 2009-10-27 15:48:00 +01:00 +tags: +- li3 +- php +- tutorial +type: article +toc: true +summary: A quick tutorial on how to get Lithium up and running, in five minutes or less. +----- + +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. + +h3. 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, ad the time of writing) +* The "li3_docs plugin": + +To get the li3_docs plugin you need to "register": on, 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":/files/, 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. + +h3. 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. + +# 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) +# 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) +# Copy the mongoose-2.8.exe executable in **D:\lithium_test** and rename it to **mongoose.exe** for convenience. +# Create a **mongoose.conf** file containing the following lines: + +<% highlight :text do %> +cgi_interp php-cgi.exe +cgi_ext php +<% end %> + +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 + +h3. Running Lithium + +Double click **mongoose.exe** and point your browser of choice to "http://localhost:8080/app/webroot/index.php":http://localhost:8080/app/webroot/index.php. You should see the Lithium temporary homepage (yes, I expected something fancier too): + +!/img/pictures/lithium/temp_homepage.png! + +Now, let's see if we can get the li3_docs plugin running as well: + +# Unzip **** and copy the **li3_docs** folder in **D:\lithium_test\app\libraries\plugins**. +# 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":http://localhost:8080/app/webroot/index.php?url=docs, you should see something like this: + +!/img/pictures/lithium/li3_docs.png! + +Congratulation, you're now running your first Lithium application! + +h3. 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: + +# Create a directory called **action** in **D:\lithium_test\app\extensions**. +# Create a file called **Request.php**, containing the following: + +<% highlight :php do %> +<?php +namespace app\extensions\action; + +class Request extends \lithium\action\Request { + + protected function _base() { + return '?url='; + } +} +?> +<% end %> + +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: + + @echo lithium\action\Dispatcher::run(new app\extensions\action\Request());@ + +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":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 "": +