contents/articles/getting-started-with-lithium.html
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 |
-----
title: "Getting Started with Lithium"
content-type: article
timestamp: 1256654880
tags: "li3|php|tutorial"
-----
<p>So <a href="http://li3.rad-dev.org/">Lithium</a> is now officially out, and its 0.1 release can be freely <a href="http://rad-dev.org/lithium/versions">downloaded</a> from the official web site or by cloning the Lithium git repository. The good news is that although not many web hosts offer <span class="caps">PHP</span> 5.3, you can try it out youself, locally and with minimum effort.</p>
<h3>Requirements</h3>
<p>According to the <a href="http://rad-dev.org/wiki/guides/setup">Lithium Wiki</a>, to develop applications with Lithium you need:</p>
<ul>
<li>A web server, like Apache or <span class="caps">IIS</span></li>
<li><span class="caps">PHP</span> 5.3.0 or higher</li>
<li>Git (not required, but all example projects are on git repos, so you may as well have it)</li>
</ul>
<p>For this tutorial, more specifically, you need to download (just download, don’t install anything!):</p>
<ul>
<li><a href="http://code.google.com/p/mongoose/">mongoose</a>, a tiny, standalone (as <em>in one single file</em>), cross-platform web server.</li>
<li><a href="http://www.php.net/downloads.php#v5"><span class="caps">PHP</span> 5.3.0</a>, not the installer, the zip package.</li>
<li><a href="http://rad-dev.org/lithium/versions">Lithium</a> (version 0.1, at the time of writing)</li>
<li>The <a href="http://rad-dev.org/li3_docs">li3_docs plugin</a>.</li>
</ul>
<p>To get the li3_docs plugin you need to <a href="http://rad-dev.org/users/add">register</a> 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 <a href="http://spheredev.org/wiki/Git_for_the_lazy">another awesome tutorial</a> to install it and learn how to use it, I’ll save you the hassle and let you download the plugin from <a href="/files/li3_docs.zip">here</a>, for this time ony.</p>
<p><b>Note:</b> This tutorial assumes that you are on Windows. If you are not, some things may be a bit different depending on your platform.</p>
<h3>Setting up the environment</h3>
<p>Choose a directory on your sistem (let’s call it <b>D:\lithium_test</b> from now on). We’ll do everything in here, and you can move it anywhere you like afterwards, even on a <span class="caps">USB</span> stick, without breaking anything.</p>
<ol>
<li>Unzip Lithium in <b>D:\lithium_test</b>, so that it contains the following files and directories:
<ul>
<li>app/</li>
<li>libraries/</li>
<li>.htaccess (it won’t actually be used in this tutorial)</li>
</ul></li>
<li>Unzip <span class="caps">PHP</span> 5.3.0 somewhere and copy the following files to the <b>D:\lithium_test</b> folder:
<ul>
<li>php5.dll</li>
<li>php-cgi.exe</li>
<li>php.ini (just get php.ini-development from the <span class="caps">PHP</span> package and rename it)</li>
</ul></li>
<li>Copy the mongoose-2.8.exe executable in <b>D:\lithium_test</b> and rename it to <b>mongoose.exe</b> for convenience.</li>
<li>Create a <b>mongoose.conf</b> file containing the following lines:</li>
</ol>
<div class='text'><pre><code>cgi_interp php-cgi.exe
cgi_ext php</code></pre></div><p>If you did everything correctly, your <b>D:\lithium_test</b> directory should contain the following:</p>
<ul>
<li>app\</li>
<li>libraries\</li>
<li>.htaccess</li>
<li>mongoose.exe</li>
<li>mongoose.conf</li>
<li>php-cgi.exe</li>
<li>php.ini</li>
<li>php5.dll</li>
</ul>
<h3>Running Lithium</h3>
<p>Double click <b>mongoose.exe</b> and point your browser of choice to <a href="http://localhost:8080/app/webroot/index.php">http://localhost:8080/app/webroot/index.php</a>. You should see the Lithium temporary homepage (yes, I expected something fancier too):</p>
<p><img src="/img/pictures/lithium/temp_homepage.png" alt="" /></p>
<p>Now, let’s see if we can get the li3_docs plugin running as well:</p>
<ol>
<li>Unzip <b>li3_docs.zip</b> and copy the <b>li3_docs</b> folder in <b>D:\lithium_test\app\libraries\plugins</b>.</li>
<li>Open <b>D:\lithium_test\app\config\bootstrap.php</b> and add the line: <code>Libraries::add('plugin', 'li3_docs');</code> at the end. I actually found this commented out already (line 80).</li>
</ol>
<p>Go to <a href="http://localhost:8080/app/webroot/index.php?url=docs">http://localhost:8080/app/webroot/index.php?url=docs</a>, you should see something like this:</p>
<p><img src="/img/pictures/lithium/li3_docs.png" alt="" /></p>
<p>Congratulation, you’re now running your first Lithium application!</p>
<h3>Fixing URLs</h3>
<p>Once the initial excitement wears off you’ll notice that none of the links on the docs page works.</p>
<p>That’s because the mongoose web server does not support <span class="caps">URL</span> rewriting (and Lithium needs it badly right now), so we have to change the way URLs are created. <a href="http://twitter.com/nateabele">@nateabele</a> gave me <a href="http://pastium.org/view/3a966c1446fcbd1d4f5a94d882256987">some tips</a> on how to do this; it’s very simple:</p>
<ol>
<li>Create a directory called <b>action</b> in <b>D:\lithium_test\app\extensions</b>.</li>
<li>Create a file called <b>Request.php</b>, containing the following:</li>
</ol>
<div class='php'><pre><code><?php
namespace app\extensions\action;
class Request extends \lithium\action\Request {
protected function _base() {
return '?url=';
}
}
?></code></pre></div><p>We’re basically extending the <code>\lithium\action\Request</code> with a custom class, telling Lithium how to create the base <span class="caps">URL</span>.</p>
<p>After doing so, open <b>D:\lithium_test\app\webroot\index.php</b> and change:</p>
<p><code>echo lithium\action\Dispatcher::run();</code></p>
<p>into:</p>
<code>echo lithium\action\Dispatcher::run(new app\extensions\action\Request());</code>
<p>In this case, we’re instructing the dispatcher to use our custom Request class instead of the default one.</p>
<p>Now everything should work as expected. Reload the docs page (<a href="http://localhost:8080/app/webroot/index.php?url=docs">http://localhost:8080/app/webroot/index.php?url=docs</a>) and verify that the links work by navigating to <code>Lithium</code>, then <code>action</code> and finally <code>Controller</code>.</p>
<p>Now you can use Lithium to display its own <span class="caps">API</span> locally (if things didn’t work out, there’s always <a href="http://li3.rad-dev.org/docs">http://li3.rad-dev.org/docs</a>).</p>
|