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 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 |
-----
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="/images/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="/images/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>
|