Introduction

Tout Temma en 3 minutes

Temma est un environnement de développement Modèle-Vue-Contrôleur (MVC en abrégé), pensé pour faciliter et accélérer les développements de sites web.

Le framework prend en charge les requêtes entrantes, vous évitant de redévelopper encore et encore les couches les plus basses de vos applications, vous laissant vous concentrer sur le «code métier», la partie la plus importante.

Installation

Prérequis

Pour utiliser Temma, vous avez besoin d'un hébergement Web exploitant l'interpréteur PHP en version 8.0 ou supérieure.

Temma peut utiliser toutes les bases de données supportées par l'extension PDO, ainsi que la base noSQL Redis, et le serveur de cache Memcached.

Télécharger Temma

Pour télécharger et utiliser Temma, vous pouvez cloner le dépôt GitHub : 

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

Vous pouvez aussi télécharger et décompresser l'archive : https://github.com/Amaury/Temma/archive/master.zip

Télécharger Smarty

Si vous utilisez Temma pour créer une API sans génération de page HTML, vous n'aurez pas besoin du moteur de templates Smarty. Dans le cas inverse, Temma a besoin de Smarty en version 4 ou plus (si vous utilisez PHP 8.1, il vous faudra Smarty 4.1).

Veuillez télécharger l'archive (format ZIP ou TAR.GZ) de la dernière version de Smarty.

En décompressant l'archive, vous verrez un sous-répetoire libs/. Renommez-le smarty4 puis déplacez-le dans le répertoire lib/ de votre projet.

Installer Temma

Une fois le dépôt Git cloné, définissez les droits sur les répertoires : 

$ cd mon_projet; chmod 755 log tmp

Ensuite, il faut savoir si vous utilisez la configuration Apache ou la configuration par fichiers .htaccess.

Fichiers .htaccess

Les fichiers .htaccess sont nécessaires en cas d'hébergement mutualisé.
Si c'est votre cas, vous n'avez rien à faire. Les fichiers nécessaires sont déjà présents à la racine et dans le répertoire www/.

Serveur Apache

La configuration Apache est à utiliser si vous avez votre propre serveur dédié.
Vous trouverez un fichier d'exemple dans le répertoire etc/, à adapter en fonction de vos besoins.

Il vous faudra en plus effacer les fichiers .htaccess existants : 

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

Configurer Temma

Dans le répertoire etc/, vous pourrez trouver deux fichiers servant à illustrer la configuration d'un projet Temma :

  • temma-mini.json : Fichier minimal contenant les directives de base.
  • temma-full.json : Fichier présentant toutes les options disponibles.

Référez-vous à la documentation de la configuration pour connaître les différentes options. Vous devez renommer un des deux fichiers, pour lui donner le nom temma.json, et l'adapter à vos besoins.

Attention : si votre projet ne comporte pas un fichier etc/temma.json correct, il ne pourra pas fonctionner.

Principes de base

Temma facilite le développement de sites constitués d'URL du type : 

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

Les URL sont découpées en 3 parties :

  • Le nom du contrôleur, un objet qui va être instancié à la réception de la requête.
  • Le nom de l'action, une méthode de cet objet qui va être appelée.
  • Un nombre variable de paramètres, que cette méthode va pouvoir utiliser.

Par défaut, le framework générera une page en interprétant le fichier de template templates/controller/action.tpl

Evidemment, il est possible de modifier les comportements par défaut. Un contrôleur peut choisir de lire des données reçues en POST au lieu − ou en plus − de celles reçues en paramètre GET. Une action peut définir un template spécifique à utiliser, voire même définir un type de vue complètement différent (qui génèrera du JSON ou du XML au lieu du HTML, par exemple).

Exemple de développement

Pour cet exemple, nous allons créer un site web très simple, avec deux pages. La première va afficher une liste d'articles, la seconde va afficher l'article demandé.

Configuration

La première chose à faire est de créer le fichier de configuration du projet. Il s'agit du fichier etc/temma.json. L'installation de Temma fournit des exemples de fichiers, mais voici le contenu de celui que nous allons utiliser : 

{
    "application": {
        "dataSources": {
            "db": "mysql://user:passwd@localhost/mybase"
        },
        "rootController": "Articles"
    },
    "loglevels": {
        "Temma/Base": "ERROR",
        "Temma/Web": "WARN"
    },
    "autoimport": {
        "siteName": "Site de démo"
    }
}
  • Ligne 4 : Configuration de la connexion à la base de données.
  • Ligne 6 : La directive rootController sert à définir le contrôleur racine du site, c'est-à-dire celui qui répondra quand on se connectera à l'adresse http://www.monsite.com/.
  • Ligne 9 et 10 : On définit les niveaux minimal des erreurs qui seront enregistrées dans le fichier log/temma.log.
  • Ligne 13 : On définit une variable de template contenant le nom du site.

Base de données

Avant tout, nous allons créer une table dans la base de données. Vous devez exécuter la requête suivante sur votre base : 

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

Et nous pouvons y ajouter des données :

INSERT INTO articles (title, text, author)
VALUES ('Premier article',   'Texte du premier article',   'John'),
       ('Second article',    'Texte du second article',    'Bob'),
       ('Troisième article', 'Texte du troisième article', 'John');

Contrôleur

Nous allons écrire notre premier contrôleur. Un contrôleur est un objet qui reçoit les connexions et les gère pour envoyer des données en retour.
Les contrôleurs ont des actions, et chaque action peut recevoir des paramètres.

Notre contrôleur se nommera Articles. Il va contenir deux méthodes principales :

  • liste(), pour afficher la liste des articles.
  • voir(), pour afficher un article seul.

S'y ajoutera la méthode __invoke() dont le seul rôle est de recevoir des connexions sur la racine du site et de les rediriger vers la liste des articles.

Dans le répertoire controllers/ de votre projet, créez un fichier nommé Articles.php. 

<?php

/** Contrôleur de gestion des articles. */
class Articles extends \Temma\Web\Controller {
    /** Indique que le framework doit créer automatiquement la DAO. */
    protected $_temmaAutoDao = true;

    /** Action racine (aucune action explicite). */
    public function __invoke() {
        // redirection vers la liste des articles
        $this->_redirect('/article/liste');
    }

    /** Action qui affiche la liste des articles. */
    public function liste() {
        // récupération de la liste d'articles depuis la base de données
        $articles = $this->_dao->search();

        // la liste est rendue disponible pour le template
        $this['articles'] = $articles;
    }

    /**
     * Action qui affiche le contenu complet d'un article.
     * @param  int  $id  L'identifiant de l'article.
     */
    public function voir(int $id) {
        // récupération du contenu de l'article depuis la base de données
        $article = $this->_dao->get($id);

        // on vérifie si l'article demandé existe ou non
        if (!$article) {
            // il n'existe pas, on redirige vers la liste
            $this->redirect('/article/list');
        } else {
            // il existe, on transmet les données au template
            $this['article'] = $article;
        }
    }
}
  • Ligne 4 : Les contrôleurs doivent hériter de l'objet \Temma\Web\Controller.
  • Ligne 6 : Le contrôleur contient un attribut protégé nommé _temmaAutoDao, qui indique à Temma qu'il doit créer automatiquement une DAO (Data Access Object, object d'accès à la base de données), qui servira à lire ou écrire dans la base de données. Cet objet est automatiquement configuré pour accéder à la table articles (d'après le nom du contrôleur).
    Pour le moment, sachez juste que cet objet propose une méthode search() qui retourne la liste de toutes les entrées de la table articles, et une méthode get() qui retourne un élément à partir de son identifiant.
  • Ligne 9 : L'action racine est exécutée lorsqu'aucune action n'est spécifiquement demandée. Comme ce contrôleur a été défini comme étant le contrôleur racine (rootController dans le fichier etc/temma.json), il s'agit donc de l'action qui sera appelée lorsqu'on accède à la racine du site.
    • Cette action répond aux deux URLs suivantes :
      http://www.mon-site.com/
      http://www.mon-site.com/articles
    • Ligne 11 : L'internaute est redirigé vers la page qui affiche la liste des articles.
  • Ligne 15 : Action liste, qui affiche la liste des articles.
    • Cette action répond à l'URL : http://www.mon-site.com/articles/liste
    • Ligne 17 : L'objet DAO est utilisé pour récupérer les données de tous les articles.
    • Ligne 20 : On copie la valeur de la variable $articles dans la variable de template articles. Le template utilisé sera (implicitement) le fichier templates/article/list.tpl.
  • Ligne 27 : Action voir, qui affiche le contenu d'un article dont l'identifiant est fourni en paramètre sur l'URL.
    • Cette action répond à l'URL : http://www.mon-site.com/articles/voir/2
    • Ligne 29 : L'objet DAO est utilisé pour récupérer les données de l'article à partir de son identifiant.
    • Ligne 31 : Si l'article n'existe pas, on redirige vers la liste des articles.
    • Ligne 34 : Si l'article existe, on l'enregistre en variable de template. Le template utilisé sera (implicitement) le fichier templates/article/voir.tpl.

Templates

Temma utilise le moteur de templates Smarty, qui est très répandu et dont la syntaxe est très facile à comprendre.

Pour la page qui affiche la liste des articles, on va créer le fichier templates/article/liste.tpl : 

<html>
<head>
    <title>{$conf.siteName|escape}</title>
</head>
<body>
    <ul>
        {* boucle sur la liste des articles *}
        {foreach $articles as $article}

            {* ajout d'un lien vers l'article *}
            <li><a href="/article/voir/{$article.id}">
                {$article.title|escape}
            </a></li>

        {/foreach}
    </ul>
</body>
</html>
  • Ligne 3 : Le nom du site est placé dans la balise <title>. Il est échappé, pour convertir les événtuels caractères spéciaux en entités HTML.
  • Ligne 8 : Boucle sur les éléments de la liste d'articles.
  • Lignes 11 à 13 : Création du lien vers la page d'un article. Le titre de l'article est échappé, pour convertir les caractères spéciaux en entités HTML.

Pour la page qui affiche un article, on créera le fichier templates/article/voir.tpl : 

<html>
<head>
    <title>{$conf.siteName|escape}</title>
</head>
<body>
    {* affichage du titre de l'article *}
    <h1>{$article.title|escape}</h1>

    {* affichage de l'auteur de l'article *}
    <h2>par {$article.author|escape}</h2>

    <p>
        {* affichage du texte de l'article *}
        {$article.text}
    </p>
</body>
</html>
  • Ligne 3 : Le nom du site est placé dans la balise <title>, et ses caractères spéciaux sont échappés.
  • Ligne 7 : Le titre de l'article est placé dans une balise H1, et ses caractères spéciaux sont échappés.
  • Ligne 10 : Le nom de l'auteur est placé dans une balise H2, et ses caractères spéciaux sont échappés.
  • Ligne 14 : Le texte de l'article est placé dans un paragraphe (balise P), et son contenu n'est pas échappé (c'est déjà du HTML).

Pour aller plus loin

Documentation complète de Temma