Introduction

Temma in 3 minutes

Temma is a Model-View-Controller (MVC for short), designed to facilitate and accelerate website development.

The framework takes care of incoming requests, saving you from re-developing the lowest layers of your applications over and over again, leaving you to focus on the “business code”, the most important part.

Installation

Prerequisite

To use Temma, you need web hosting using the PHP interpreter version 7.3 or higher.

Temma can use all the databases supported by the PDO extension, as well as the noSQL Redis database, and the Memcached cache server.

Download Temma

To download and use Temma, you can clone the GitHub repository:

$ git clone https://github.com/Amaury/Temma mon_projet

You can also download and unzip the archive: https://github.com/Amaury/Temma/archive/master.zip

Download Smarty

Unless you are using Temma to build an API without generating an HTML page, you will need the Smarty templating engine.

Smarty can optionally be installed through the package system of your operating system. If not, download the latest version of Smarty, then unzip the archive. Get the contents of the libs/ subdirectory, and place it in a folder named smarty3, which you will have created in the lib/ directory of your project.

Install Temma

Once the Git repository is cloned, set the permissions on the directories:

$ cd mon_projet; chmod 755 log tmp

Then, you have to know if you are using the Apache configuration or the configuration by .htaccess files.

.htaccess files

The .htaccess files are necessary in case of shared hosting.
If so, you don't have to do anything. The necessary files are already present at the root and in the directory www/.

Apache server

The Apache configuration should be used if you have your own dedicated server.
You will find an example file in the etc/ directory, to adapt according to your needs.

You will also need to delete the existing .htaccess files:

$ cd mon_projet; rm -f .htaccess www/.htaccess

Configure Temma

In the etc/ directory, you can find two files used to illustrate the configuration of a Temma project:

  • temma-mini.json: Minimal file containing basic directives.
  • temma-full.json: File showing all the available options.

Refer to the configuration documentation for the different options. You must rename one of the two files, to give it the name temma.json, and adapt it to your needs.

Warning: if your project does not have a correct etc/temma.json file, it will not work.

Basic Principles

Temma facilitates the development of sites made up of URLs such as:

http://www.site.com/controller/action/p1/p2/p3

URLs are split into 3 parts:

  • The name of the controller, an object that will be instantiated upon receipt of the request.
  • The name of the action, a method of this object that will be called.
  • A variable number of parameters that this method will be able to use.

By default, the framework will generate a page by interpreting the templates/controller/action.tpl template file

Obviously, it is possible to modify the default behaviors. A controller can choose to read data received in POST instead of − or in addition to − those received in GET parameter. An action can define a specific template to use, or even define a completely different type of view (which will generate JSON or XML instead of HTML, for example).

Development Example

For this example, we'll create a very simple website with two pages. The first will display a list of articles, the second will display the requested article.

Configuration

The first thing to do is to create the project configuration file. This is the etc/temma.json file. Temma installation provides sample files, but here is the content of the one we'll be using:

{
    "application": {
        "dataSources": {
            "db": "mysql://user:passwd@localhost/mybase"
        },
        "rootController": "Articles"
    },
    "loglevels": {
        "Temma/Base": "ERROR",
        "Temma/Web": "WARN"
    },
    "autoimport": {
        "siteName": "Demo site"
    }
}
  • Line 4 : Configuration of the connection to the database.
  • Line 6 : The rootController directive is used to define the root controller of the site, that is to say the one that will respond when we connect to the address http://www.monsite.com/.
  • Line 9 and 10 : We define the minimum levels of errors that will be recorded in the log/temma.log file.
  • Line 13 : We define a template variable containing the name of the site.

Database

First of all, we will create a table in the database. You need to run the following query on your database:

CREATE TABLE articles (
    id     INT UNSIGNED AUTO_INCREMENT,
    title  TINYTEXT,
    text   MEDIUMTEXT,
    author TINYTEXT,
    PRIMARY KEY (id)
);

And we can add data to it:

INSERT INTO articles (title, text, author)
VALUES ('Frist article',  'Text of the first article',  'John'),
       ('Second article', 'Text of the second article', 'Bob'),
       ('Third article',  'Text of the third article',  'John');

Controller

We will write our first controller. A controller is an object that receives connections and manages them to send data back.
Controllers have actions, and each action can be assigned parameters.

Our controller will be called Articles. It will contain two main methods, list() (to display the list of articles) and see() (to display a single article). There will be added the index() method whose only role is to receive connections on the root of the site and to redirect them to the list of articles.

In the controllers/ directory of your project, create a file named Articles.php.

<?php

/** Articles management controller. */
class Articles extends \Temma\Web\Controller {
    /** Tell the framework to automatically create the DAO. */
    protected $_temmaAutoDao = true;

    /** Root action (no explicit action). */
    public function __invoke() {
        // redirection to the list of articles
        $this->_redirect('/article/list');
    }

    /** Action that displays the list of articles. */
    public function list() {
        // retrieving the list of items from the database
        $articles = $this->_dao->search();

        // the list is made available for the template
        $this['articles'] = $articles;
    }

    /**
     * Action that displays the full content of an article.
     * @param  int  $id  Article's identifier.
     */
    public function show(int $id) {
        // retrieval of article content from the database
        $article = $this->_dao->get($id);

        // we check if the requested item exists or not
        if (!$article) {
            // it does not exist, redirect to the list
            $this->redirect('/article/list');
        } else {
            // it exists, data are sent to the template
            $this['article'] = $article;
        }
    }
}
  • Line 4: Controllers must inherit from the \Temma\Web\Controller object.
  • Line 6 : The controller contains a protected attribute named _temmaAutoDao, which tells Temma that it should automatically create a DAO (Data Access Object), which will be used to read or write to the database. This object is automatically configured to access the articles table (based on the controller name).
    For now, just know that this object offers a search() method which returns the list of all entries in the articles table, and a get() method which returns an element from its identifier.
  • Line 9: The root action is executed when no action is specifically requested. As this controller has been defined as the root controller (rootController in the etc/temma.json file), this is therefore the action that will be called when accessing the site root.
    • This action responds to the following two URLs:
      http://www.my-site.com/
      http://www.my-site.com/articles
    • Line 11: The Internet user is redirected to the page which displays the list of articles.
  • Line 15: The list action, which displays the list of items.
    • This action responds to the URL: http://www.myn-site.com/articles/list
    • Line 17: The DAO object is used to retrieve data for all items.
    • Line 20: We copy the value of the $articles variable into the articles template variable. The used template will (implicitly) be the templates/article/list.tpl file.
  • Line 27: The show action, which displays the content of an article whose identifier is provided as a parameter on the URL.
    • This action responds to the URL: http://www.my-site.com/articles/show/2
    • Line 29: The DAO object is used to retrieve item data from its identifier.
    • Line 31: If the article does not exist, we redirect to the list of articles.
    • Line 34: If the article exists, we save it as a template variable. The used template will (implicitly) be the templates/article/voir.tpl file.

Templates

Temma uses the Smarty template engine, which is very popular and has a very easy to understand syntax.

For the page that displays the list of articles, we will create the file templates/article/list.tpl:

<html>
<head>
    <title>{$conf.siteName|escape}</title>
</head>
<body>
    <ul>
        {* loop on the list of articles *}
        {foreach $articles as $article}

            {* add a link to the article *}
            <li><a href="/articles/show/{$article.id}">
                {$article.title|escape}
            </a></li>

        {/foreach}
    </ul>
</body>
</html>
  • Line 3: The name of the site is placed in the <title> tag. It is escaped, to convert any special characters into HTML entities.
  • Line 8: Loop through the items in the article list.
  • Lines 11 to 13: Creation of the link to the page of an article. The title of the article is escaped, to convert special characters to HTML entities.

For the page that displays an article, we will create the file templates/article/voir.tpl:

<html>
<head>
    <title>{$conf.siteName|escape}</title>
</head>
<body>
    {* display the article's title *}
    <h1>{$article.title|escape}</h1>

    {* display the article's author *}
    <h2>par {$article.author|escape}</h2>

    <p>
        {* display the article's content *}
        {$article.text}
    </p>
</body>
</html>
  • Line 3: The site name is placed in the <title> tag, and its special characters are escaped.
  • Line 7: The title of the article is placed in an H1 tag, and its special characters are escaped.
  • Line 10: The author's name is placed in an H2 tag, and its special characters are escaped.
  • Line 14: The text of the article is placed in a paragraph (P tag), and its content is not escaped (it is already HTML).

Further reading