Lithium Framework: Getting Started

Share this article

Lithium is a lean but mean PHP framework (machine?) built for PHP 5.3 and up. It is designed to provide a good toolset for starting your web application, but one that is not too confining.

Lithium uses the Model-View-Controller(MVC) architecture and this is what we are going to look at in this article. I will show you how it works and how you can define some of your application’s business and presentation logic using this framework. There are a few things we will do in this respect.

We will set up a Controller to route URL requests to. This Controller will get and process some information from the database with the help of a data Model. This information will then be displayed in the browser using a View. All standard MVC stuff, but a real pleasure to perform with Lithium.

I will assume you already have the framework set up on your server to the point that you can at least see the default app starting page if you navigate to the URL. Additionally, you’ll need a database populated with some information. I’ll use MySQL but Lithium supports a number of other storage systems like MongoDB or CouchDB.

I have set up a Git repository that you can clone if you want to follow along. The master branch contains the vanilla Lithium framework whereas the MVC branch contains the code from this article. Don’t forget to also init and update the lithium submodule. To connect your database, make a copy of the connections_default.php file located in the app/config/bootstrap folder and rename it connections.php. Then add your credentials inside that file.

Let’s begin.

The data

Before getting into the fun MVC stuff, let’s get a table into our database with some information. I will be working with dummy page data so my table (called pages) will contain an id column (INT, auto increment and primary key), a title column (varchar 255), a content column (text) and a created column (INT). And in this table I have 2 sample rows. If you want to follow along exactly, here is the table create statement:

CREATE TABLE `pages` (
  `id` int(11) unsigned NOT NULL AUTO_INCREMENT,
  `title` varchar(255) DEFAULT NULL,
  `content` text,
  `created` int(11) DEFAULT NULL,
  PRIMARY KEY (`id`)

And here are my dummy rows:

INSERT INTO `pages` (`id`, `title`, `content`, `created`)
    (1, 'My awesome page title', 'Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.', 1397158745),
    (2, 'Some other page title', 'Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.', 1397158768);

Of course, you can use something else.

C stands for Controller

Controllers are probably the most important part of any MVC framework. Their role is to process requests routed to it by the application’s routing system.

If you look in the app/controllers/ folder of your application you’ll see that this is where we have to put ours. Let’s create there a new file called SiteController.php (each Controller class resides in its own file) and paste in the following class declaration to get started:


namespace app\controllers;

class SiteController extends \lithium\action\Controller {


As you can see we are extending the Lithium base controller class into our own called SiteController. Inside this class you create methods that perform the logic needed when they are requested from the URL. We’ll see this in action in a minute, but first, let’s understand how the routing works.

By default, when constructing the URL, we use arguments that map to the names of the Controller class (in our case, site), methods and parameters. If no method name is passed, Lithium will assume one by itself called index(). So if you navigate to, Lithium will look for this method and call it. Now let’s say we have a method called view() that takes 1 argument ($id). The URL to call that Controller method is, where view is the name of the method and 1 is the parameter that gets passed to this function. And if the method gets more parameters, you just pass them in the URL separated by slashes (/).

However, like I mentioned, this is the default behavior. For more control, you can define routes yourself in the /app/config/routes.php file. I won’t go into details but you can find more information on the appropriate documentation page.

Now let’s go ahead and create a page() method that will be in charge of displaying individual pages from my dummy database:

public function page() {

    // Mock page info.
    $title = 'My awesome page title';
    $content = 'My awesome page content. Yes indeed.';
    $created = '10 April 2014';

    // Prepare page info for passing to the View.
    $data = array(
      'title' => $title,
      'content' => $content,
      'created' => $created,

    // Pass the data to the View.


Above, we mock database page information and store it an array. We then pass this array to the set() method of the Controller class (that we inherit) and this gets sent on to the View. Alternatively, we can also return the $data array instead of using the set() method. But in both cases, the keys of the array represent the variable names that we can then access from our View file. Let’s see how that works.

V stands for View

Views are the presentation layer of an MVC framework. They are used to keep the business logic of the application separate and to allow for an easy theming of what gets displayed to the browser.

Let’s create a View to display our page information. In the app/views/ folder you need to create another folder named after the Controller class that uses it (in our case, site). Inside this folder, you have to create a file named after the method itself, appended with the .html.php extension. This is the Lithium naming convention for Views that makes it very easy for us to connect them to Controllers.

So for our page example, the new file will be at app/views/site/page.html.php.

Inside this file, paste the following:

<!-- Title -->
<h1><?=$title ?></h1>

<!-- Created date -->
<p><?=$created ?></p>

<!-- Main content -->
<div class="content">
  <?=$content ?>

As you probably already guessed, this is some basic markup into which we print the variables named after the array keys passed from the Controller. Lithium uses this syntax to print variables because it also runs them through its $h() function which is responsible for sanitizing HTML. This applies however only to when you print variables and not properties of the $this object.

To test out what we have so far, navigate to and you should see a nice page with the mock information displayed. You’ll also notice that our simple View is rendered inside a more complex layout (the default one that comes with the framework).

Layouts in Lithium are used to wrap content with commonly used markup such as headers and footers. They live in the app/layouts folder and they use $this->content() to render the View inside. Our View is rendered by default inside the default.html.php layout but you can specify another one if you want. You do this from the Controller that renders the View, either as a class property to be applied to all methods of that Controller, or inside the method itself like this:

public function page() {

    // Method logic ...

    $this->_render['layout'] = 'yourLayout';   

We will stick to the default one because it looks nice for our demonstration purposes.

M stands for Model

Now that the request and presentation logic are taken care of, its time to replace the mock page data with our dummy database content. We will use a Model to abstract and easily access this information.

Model classes are a very important part of an MVC framework because they define and handle the content in your database. They also make it easy for the application to perform CRUD (create, read, update, delete) operations on this data. Let’s see how they work in Lithium.

The first thing you need to do is create a class file in the app/models folder called Pages.php and inside paste the following:


namespace app\models;

class Pages extends \lithium\data\Model {


We are just extending the base Model class and making use of all its methods. The name of our Model class needs to match the database table that contains the relevant records. So if yours is not pages, make sure you adapt accordingly because Lithium will automatically pick up on this naming to make things easier for us.

Next, we need to include this file in our Controller class file, so paste the following below the namespace declaration:

use app\models\Pages;

It follows to remove the mock content from the page() method and make sure this function gets passed an $id parameter so that we know which page we need to retrieve. And we are left with the simple task of querying for the page record and passing the results to the View. So the revised page() method will look something like this:

public function page($id) {

    // Look for the first record that matches the passed criteria
    $record = Pages::first(array('conditions' => array('id' => $id)));
    $page = $record->data();

    // Prepare page info for passing to the View.
    $data = array(
      'title' => $page['title'],
      'content' => $page['content'],
      'created' => date('F j Y', $page['created']),

    // Pass the data to the View.


We are using the first() method of the Model parent class to query using conditions. The result is an object from which we retrieve the record data using the data() method. And that is in the form of an array keyed by the name of the table columns. The rest is like before except for the created field that we format using the PHP date() function since we are getting a UNIX timestamp from the database. And that’s pretty much it.

If we navigate to, we should see the page with the ID of 1. If we switch the last URL argument to 2, the page should load the second record. Neat.


In this tutorial we’ve seen how easy it is to understand and work with the Lithium MVC framework. We’ve learned how to define Controllers, Views and Models and how to use them together to create a neatly separated application process. We’ve also seen how helpful the Lithium conventions are to get us started. Without even knowing it we abstracted our database content and exposed it for very easy access.

I hope you learned something and are curious enough to go a bit more in depth and look at the other powerful features Lithium has to offer. What are some of the built in CRUD methods and how can you extend them? How can you define your own custom routes? How can you use multiple layouts and even render smaller elements within your Views? These are all great features Lithium offers us for our web application and are worth checking out.

Did I make you curious? Want to read more about this great framework?

Frequently Asked Questions (FAQs) about Lithium Framework

What are the key features of the Lithium Framework?

Lithium Framework, also known as li3, is a full-stack, open-source PHP framework. It is known for its flexibility and modularity, allowing developers to build applications with ease. Key features include its support for the MVC (Model-View-Controller) design pattern, which promotes code organization and separation of concerns. It also supports E_STRICT for error reporting, which helps developers write cleaner, bug-free code. Furthermore, it has a robust routing system, allowing for clean and SEO-friendly URLs. It also supports various databases, including MySQL, MongoDB, CouchDB, and more.

How does Lithium Framework compare to other PHP frameworks?

Lithium Framework stands out from other PHP frameworks due to its lightweight nature and flexibility. Unlike other frameworks that come with a lot of pre-built features, Lithium allows developers to add only what they need, reducing the overall size and complexity of the application. It also supports the latest PHP features, including namespaces and closures, which are not supported by many older frameworks. Furthermore, it has a strong focus on testability, with built-in testing tools and support for continuous integration.

How do I install and set up the Lithium Framework?

Installing and setting up the Lithium Framework is straightforward. You can download the framework from the official website or GitHub repository. Once downloaded, you need to extract the files to your web server’s root directory. You then need to configure your web server to point to the /webroot directory in the Lithium application. After that, you can access the application through your web browser. For more detailed instructions, refer to the official documentation.

What is the learning curve for the Lithium Framework?

The learning curve for the Lithium Framework can be steep for beginners, especially those who are new to PHP or MVC frameworks. However, it is well-documented, with a comprehensive guide and API documentation available on the official website. There are also numerous tutorials and resources available online to help you get started.

How is the performance of applications built with the Lithium Framework?

Applications built with the Lithium Framework are known for their high performance. This is due to the framework’s lightweight nature and efficient codebase. It also supports various caching mechanisms, allowing for improved performance and scalability. However, like any framework, the performance also depends on the quality of the code written by the developer.

What kind of applications can I build with the Lithium Framework?

The Lithium Framework is versatile and can be used to build a wide range of applications. This includes web applications, APIs, content management systems, e-commerce platforms, social networking sites, and more. Its flexibility and modularity make it suitable for both small and large-scale projects.

Is the Lithium Framework actively maintained?

Yes, the Lithium Framework is actively maintained by a dedicated team of developers. They regularly release updates and bug fixes to ensure the framework remains up-to-date and secure. You can follow the project on GitHub to stay updated on the latest developments.

How is the community support for the Lithium Framework?

The Lithium Framework has a vibrant and active community of developers. There are numerous forums, blogs, and social media groups where you can ask questions, share ideas, and get help. The official website also has a community section where you can find resources and contribute to the project.

Does the Lithium Framework support third-party libraries and plugins?

Yes, the Lithium Framework supports third-party libraries and plugins. This allows developers to extend the functionality of the framework and integrate it with other technologies. The framework also has a plugin architecture, allowing developers to create and share their own plugins.

What are some best practices for developing with the Lithium Framework?

Some best practices for developing with the Lithium Framework include following the MVC design pattern, writing clean and maintainable code, using the built-in testing tools, and regularly updating the framework to the latest version. It’s also recommended to take advantage of the framework’s modularity by only including the features you need in your application.

Daniel SiposDaniel Sipos
View Author

Daniel Sipos is a Drupal developer who lives in Brussels, Belgium. He works professionally with Drupal but likes to use other PHP frameworks and technologies as well. He runs, a Drupal blog where he writes articles and tutorials about Drupal development, theming and site building.

Share this article
Read Next
Get the freshest news and resources for developers, designers and digital creators in your inbox each week
Loading form