Généralement, dans un projet Kirby, vous aurez besoin de récupérer des données, peut être d'effectuer des traitements sur ces données puis d'afficher ces données. Si vous faites toutes ces opérations dans vos fichiers templates, ils risquent d'être difficilement lisibles et maintenables. En isolant les actions de requêtage et de traitement de vos données dans des fichiers différents des templates, vous organiserez mieux votre code et vous repecterez le pattern "separation of concerns".

Le requêtage et le traitement de vos données peuvent être effectués dans des fichiers PHP appelés "Controllers". Ces fichiers doivent être stockés dans le dossier /site/controllers/ et porter le nom du template dans lequel vous souhaitez renvoyer les données traitées.

Par exemple, les données traitées dans le "controller" /site/controllers/home.php ne seront disponibles que dans le template /site/templates/home.php

Un "controller" est un fichier PHP qui renvoie une fonction anonyme qui elle même renvoie un tableau associatif dans lequel se trouve les variables qui seront mis à disposition dans le template correspondant. Traduit en code, cela donne ceci :

<?php

// /site/controllers/home.php

return function () {
  // Ici je récupère et traite mes données ...
  // Puis je retourne ces données pour qu'elles soient disponible dans mon template
  return [
    'foo' => 'my first template variable',
    'bar' => 'my second template variable'
  ];
};

Les variables $foo et $bar seront alors disponibles dans le template /site/templates/home.php

Dans cette fonction anonyme, pour accéder aux objets Kirby $kirby, $site, $pages et $page il suffit des les passer en paramètres de la fonction anonyme de la façon suivante :

<?php

// /site/controllers/home.php

return function ( $site, $page ) {
  // Je récupère mes données
  $foo = $site->url();
  $bar = $page->title();
  // J'effectue d'éventuels traitements
  $bar = strtoupper( $bar );
  // Je retourne mes données traitées au template
  return [
    'site_url' => $foo,
    'page_title' => $bar
  ];
};

Dans cet exemple de code, les variables $site_url et $page_title seront disponibles dans le template /site/templates/home.php

Vous pouvez aussi utiliser un "controller" qui sera général à tous les templates. Ce "controller" général doit être nommé /site/controllers/site.php

Ce "controller" général ne s'applique qu'aux templates n'ayant pas de "controller" spécifique déclaré dans le dossier /site/controllers Si un "controller" spécifique à un template existe, le "controller" général ne sera pas pris en compte pour ce template.

Il existe cependant des solutions si vous souhaitez partager des logiques de traitements entre plusieurs templates tout en gardant le système des "controllers" liés à des templates spécifiques.