We hope you find this tutorial helpful. In addition to guides like this one, we provide simple cloud infrastructure for developers. Learn more →

How To install and Start Using Lithium on Ubuntu 12.04 VPS

Posted Feb 3, 2014 7.6k views PHP Frameworks Ubuntu

About Lithium

Lithium is a full stack PHP framework for developing web applications. Based on the Model-View-Controller (MVC) architecture, it is built for PHP 5.3+ and integrates with the latest storage technologies like MongoDB or CouchDB.

It is designed to offer both great project organization as well as the possibility to code out of the framework as you develop your own unique web application. Additionally, it features a robust plugin system that allows you to use your favorite components from outside the framework (such as Twig for templating or Doctrine2 for ORM).

In this tutorial we will look at how we can install Lithium on our VPS, as well as get started with a simple web application. For that I assume you already have your server set up and are running the LAMP stack (Apache, MySQL and PHP). If you don't already, there's a great tutorial on DigitalOcean that can get you set up.

Apache setup

Since we are using Apache as a webserver and Lithium makes heavy use of the .htaccess file for URL rewriting, we'll need to also make sure that Apache will in fact let it do that. If you haven't already done the following steps, you'll need to do them now.

Edit the virtual host file that is responsible for the folder where you will have the application (in our case, let's say the default Apache document root: /var/www):

sudo nano /etc/apache2/sites-available/default

Inside the block marked with this beginning:

<Directory /var/www/>

Make sure that instead of AllowOverride None you have AllowOverride All.

Next thing we need to do is enable mod_rewrite (again if you don't already have it enabled). To check if it's already enabled, use the following command:

apache2ctl -M

If you see "rewrite_module" in the list, you are fine. If not, use the following command to enable the module:

a2enmod rewrite 

After making any changes to either the virtual host file or enabling an Apache module, you have to restart Apache:

sudo service apache2 restart


Before we begin installing Lithium, let's install Git so we can use it to fetch the framework from GitHub. You can do this with the following 2 commands:

sudo apt-get update
sudo apt-get install git-core

Next, we can clone the Lithium git repository onto our server (while being in our web server's document root: /var/www for Apache):

git clone git://github.com/UnionOfRAD/framework.git site

This will clone the framework repository and place it in a folder called site. Now we can install Lithium as a submodule:

cd site
git submodule init
git submodule update

This will now clone the lithium library as well onto our server in the libraries/lithium/ folder. This will be needed for bootstrapping the application.

Command line

Lithium comes with a command line utility (li3) that helps with code generation, documentation, etc. But to make it usable from anywhere, we'll need to add the console library to the shell path. Open the .bash_profile file located in your home folder (if you don't already have one you can create it):

nano ~/.bash_profile 

And paste the following in it:


Make sure you replace the path with the correct path that leads to the console in your case. So in our case it would be:


After any such move, you should run the following command to make sure the bash command will take effect:

source ~/.bash_profile

And now test the command to make sure it is working by running it without any options to get its help information:


Database connection

Most web applications need a database to rely on for storage. With Lithium, you can use a wide range of database engines like MySQL, MariaDB, MongoDB, CouchDB etc. For the purpose of setting up our test appplication we will use MySQL, but you are free to experiment with whatever you feel more comfortable. There is more information here about setting it up with MongoDB.

The first thing we need is a database so make sure you have one. If you don't know how to work with MySQL and create your db, read this great tutorial on using MySQL.

To set up a database connection, first edit the bootstrap.php file located in the app/config folder of your application (site/):

nano /var/www/site/app/config/bootstrap.php

Inside this file, if commented, uncomment the following line:

require __DIR__ . '/bootstrap/connections.php';

Then edit the following file:

nano /var/www/site/app/config/bootstrap/connections.php

And uncomment the database configuration found under the following block:

* Uncomment this configuration to use MySQL as your default database.

You'll notice multiple blocks like this for different database engines. Additionally, set your MySQL connection information where appropriate.

Your application

It's time to visit the browser and see what we have so far. You can do so by navigating to your ip/site. There you should see your Lithium application up and running with some information about its status and the server configuration that needs to be made for it to work.

If you see the following message:

Magic quotes are enabled in your PHP configuration

You need to edit the php.ini file on your server:

sudo nano /etc/php5/apache2/php.ini

And paste the following line in it:

magic_quotes_gpc = Off

Then save the file and restart Apache:

sudo service apache2 restart


Since Lithium is a MVC framework, you'll see in the folder structure 3 important folders for that: controllers/, models/ and views/. Let's quickly create our first controller and print Hello world! onto the page with it.

Create a new file in the controllers/ folder called HelloController.php with the following content:


namespace app\controllers;

class HelloController extends \lithium\action\Controller {
 public function index() {
   echo "Hello World!";


You can save the file. What we did here was create a new controller class located in a carefully named file (based on the class name) and that extends the Lithium controller class. Inside, we created an index method that will get called if no parameters are passed when calling this controller. Inside this method we just print out the message.

To access this in the browser, you now have to navigate to your-ip/site/hello and you should see Hello World printed on the page.


In this tutorial, we've seen how to install Lithium PHP and make the necessary server configuration to make it work. We've seen how to connect it to a database (we have not used yet) and created our first controller that simply prints a message onto the page.

In the next tutorial, we will go a bit further and see how the MVC architecture works with Lithium. We'll use Views as well as Models (to illustrate the interaction with our MySQL storage engine).

Article Submitted by: Danny


Creative Commons License