Documentation : Contrôleurs

Présentation

Les contrôleurs sont des objets PHP qui doivent satisfaire 4 critères :

  • Hériter de l'objet \Temma\Controller.
  • Leur nom doit contenir le suffixe «Controller» (en respectant la casse).
  • Être contenu dans un fichier dont le nom est exactement celui de l'objet, suffixé par «.php».
  • Être accessible dans un répertoire directement dans le chemin d'inclusion du projet, idéalement dans le répertoire controllers/.

Le nom de chaque action susceptible d'être appelée doit être préfixé par «exec», suivi d'une majuscule.

Racine, proxy et défaut

Il est possible de définir un contrôleur racine, un contrôleur proxy et un contrôleur par défaut (cf. configuration) :

  • Le contrôleur racine (directive rootController) est appelé lorsque aucun contrôleur n'a été explicitement demandé. Il sert à définir le contrôleur qui gère la page d'accueil du site.
  • Le contrôleur proxy (directive proxyController) est systématiquement appelé, même si le contrôleur appelé existe. Il sert à contourner complètement le framework, pour créer votre propre gestion de toutes les URL.
  • Le contrôleur par défaut (directive defaultController) est appelé lorsque le contrôleur demandé n'existe pas. Il permet de définir un contrôleur qui gère des URL qui ne sont pas connues d'avance.

Un contrôleur peut aussi contenir une action racine, une action proxy et une action par défaut :

  • L'action racine s'appelle execIndex(). Elle est utilisée quand aucune action n'a été explicitement demandée.
  • L'action proxy s'appelle execProxy(). Si elle existe, elle est systématiquement appelée, même si l'action demandée existe.
  • L'action par défaut se définit en utilisant la méthode magique __call(). Elle offre la possibilité à un contrôleur de gérer des URL qui ne sont pas connues à l'avance, en plus de ses actions spécifiées.

Par exemple, si l'objet UserController contient les méthodes execIndex(), execShow() et __call(). Il pourra être appelé avec les URL suivantes :

  • http://monsite.com/user => utilise l'action racine
  • http://monsite.com/user/show => utilise l'action show
  • http://monsite.com/user/list => utilise l'action par défaut

Si cet objet contenait une méthode execProxy(), celle-ci serait appelée dans tous les cas.

Initialisation

Un contrôleur peut contenir une méthode nommée init() (qui ne prend aucun paramètre).

Elle sera appelée automatiquement avant que l'action soit appelée, ce qui peut servir à initialiser le contrôleur. Il est ainsi possible d'initialiser des attributs privés du contrôleur, en instanciant des objets qui pourront être utilisés dans toutes les actions.

Cette méthode peut ne rien retourner, auquel cas l'exécution se poursuit normalement. Elle peut aussi retourner les mêmes valeurs que les méthodes d'action (cf. Plugins), ce qui peut modifier l'exécution de l'action, des post-plugins et de la vue.

Finalisation

Un contrôleur peut contenir une méthode nommée finalize() (qui ne prend aucun paramètre).

Elle sera appelée automatiquement après que l'action ait été appelée, ce qui peut servir à initialiser le contrôleur. Il est ainsi possible d'initialiser des attributs privés du contrôleur, en instanciant des objets qui pourront être utilisés dans toutes les actions.

Cette méthode peut ne rien retourner, auquel cas l'exécution se poursuit normalement. Elle peut aussi retourner les mêmes valeurs que les méthodes d'action (cf. Plugins), ce qui peut modifier l'exécution des post-plugins et de la vue.

Méthodes des contrôleurs

Les contrôleurs proposent des méthodes spécifiques utilisables dans le code des actions.

$this->set(string, mixed)
Sert à définir une variable à passer aux plugins et/ou au template. Si le nom de la variable commence par un underscore, la variable ne sera pas passée au template.

$this->get(string)
Retourne le contenu d'une variable de template préalablement définie.

$this->template(string)
Si on utilise la vue par défaut (\Temma\Views\Smarty), cette méthode redéfinit le chemin vers le template à utiliser. Par défaut, le template utilisé doit être un fichier dont le nom est celui de l'action (et le suffixe ".tpl"), placé dans un répertoire dont le nom est celui du contrôleur.

$this->redirect(string)
Si on souhaite faire une redirection (et donc ne pas utiliser une vue), cette méthode définit l'URL de redirection.

$this->redirect301(string)
Idem à la méthode précédente, mais effectue une redirection 301 (permanente) et non pas 302 (temporaire).

$this->httpError(int)
Si on rencontre une erreur qui doit être traitée de manière générique, cette méthode permet de spécifier le code d'erreur HTTP (4XX, 5XX).

$this->view(string)
Sert à définir la vue qui sera utilisée. Par défaut, il s'agit de \Temma\Views\Smarty.

$this->subProcess(string, string)
Permet d'exécuter une action d'un autre contrôleur. Voir plus bas.

Attributs des contrôleurs

$this->_dao
Si le contrôleur le demande, Temma va automatiquement instancier un objet DAO pour faciliter la communication avec la base de données.
Plus d'informations sur la documentation des DAO.

$this->_db
Si la configuration contient des paramètres de connexion à une base de données, cet attribut contient une instance de \FineDatabase.
Vous trouverez plus d'information sur la documentation du modèle.

$this->_session
À moins que la configuration n'ait prévu de désactiver la gestion des sessions, cet attribut contient une instance de \FineSession.
Plus d'information sur la documentation de la persistance.

$this->_cache
Si la configuration prévoit une connexion à un serveur de cache, cet attribut contient une instance de \FineCache.
Plus d'information sur la documentation de la persistance.

$this->_request
Cet attribut contient une instance de type \Temma\Request. Cela permet de récupérer, voire modifier, les différentes composantes de la requête.

$this->_config
Cet attribut contient une instance de \Temma\Config. Le contrôleur peut ainsi accéder (en lecture seule) aussi bien aux paramètres de l'application Temma qu'aux paramètres étendus.
Plus d'information sur la documentation de la configuration.

$this->_temmaAutoDao
Cet attribut est différent des autres. Il n'est pas positionné par le framework. C'est à vous de l'utiliser à la création du contrôleur, pour demander à Temma de créer automatiquement l'objet DAO qui facilite l'accès à la base de données.
Plus d'informations sur la documentation des DAO.

Sous-traitement

Un contrôleur peut transmettre l'exécution de la requête courante à un autre contrôleur. Pour cela, il suffit d'utiliser la méthode subProcess(). Il est même possible de modifier la requête à l'avance, pour l'adapter au sous-contrôleur :

class HomepageController extends \Temma\Controller {
    public function execIndex() {
        // on modifie le premier paramètre de l'action
        $this->_request->setParam(0, 'display');

        // on appelle l'action "publish" du contrôleur "UserController"
        $this->subProcess('UserController', 'publish');

        // on peut récupérer une variable de template définie par le sous-contrôleur...
        $name = $this->get('name');

        // ...puis écraser cette valeur de manière conditionnelle
        if (strlen($name) < 3)
            $this->set('name', 'nom par défaut');
    }
}
						

Dans cet exemple, le contrôleur qui gère la page d'accueil du site effectue une sous-requête équivalente à une connexion à l'adresse /user/publish/display puis effectue un traitement conditionnel sur les données générées.