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.


1Installation

Veuillez vous référer à la page de documentation de l'installation pour savoir comment installer Temma.


2Principes 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.

Le code suivant sera alors exécuté :

Controller::action(p1, p2, p3)

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).


3Exemple 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é.

3.1Configuration

La première chose à faire est de créer le fichier de configuration du projet. Il s'agit du fichier etc/temma.php.

Référez-vous à la documentation de la configuration pour connaître les différentes options.

L'installation de Temma fournit des exemples de fichiers, mais voici le contenu de celui que nous allons utiliser :

<?php

return [
    'application' => [
        'dataSources' => [
            // configuration de la base de données
            'db' => 'mysql://user:passwd@localhost/mybase'
        ],
        // configuration du contrôleur racine
        'rootController' => 'Articles'
    ],
    // seuils d'écriture des logs
    'loglevels' => [
        'Temma/Base' => 'ERROR',
        'Temma/Web'  => 'WARN',
        'default'    => 'WARN',
    ],
    // variables de template importées automatiquement
    'autoimport' => [
        'siteName' => 'Site de démo'
    ]
];
  • Ligne 7 : Configuration de la connexion à la base de données.
  • Ligne 10 : 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 14 à 16 : On définit les niveaux minimaux des erreurs qui seront enregistrées dans le fichier log/temma.log.
  • Ligne 19 : On définit une variable de template contenant le nom du site.

3.2Base 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');

3.3Contrô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.php), 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 34 : Si l'article n'existe pas, on redirige vers la liste des articles.
    • Ligne 37 : Si l'article existe, on l'enregistre en variable de template. Le template utilisé sera (implicitement) le fichier templates/article/voir.tpl.

3.4Templates

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).

4Pour aller plus loin

Documentation complète de Temma