Documentation FuelPHP 1.7.3

Serveur WEB :

• tout type de serveur Web : FuelPHP a été testé sur Apache, IIS, et Nginx ;
• fonctionne sur tous les systèmes d'exploitation majeurs incluant les *nix et Windows.

Version PHP :

• une version 5.3.3 ou supérieure est requise.

Extensions PHP :

FuelPHP utilise des fonctionnalités que PHP définit comme extensions. Pour éviter tout problème de compatibilité possible, FuelPHP utilise seulement les extensions natives du code PHP, qui sont documentées sur le site officiel de PHP. Si les extensions utilisées font partie d'un dépôt PECL (qui doivent être installées manuellement par un administrateur système), FuelPHP les utilisera quand il les détectera ; sinon il fonctionnera sans.

Voici une liste des extensions utilisées, et des classes qui les utilisent :

PHPUnit :

• PHPUnit version 3.7 ou supérieure est requis si vous voulez lancer des tests unitaires.

Recommandé :

• serveur Web - Apache 2.4+, fonctionnant sous *nix.
• mod_rewrite - pour retirer index.php de l'URL.

Si votre temps est précieux, et que vous souhaitez des choses fonctionnelles au bout de quelques secondes au lieu de quelques minutes, vous pouvez utiliser notre installateur rapide. En utilisant la bibliothèque curl, vous pouvez installer une version de base de « Oil », à partir de laquelle vous pouvez créer une nouvelle installation complète de FuelPHP.

# installation rapide de Oil depuis le web
curl get.fuelphp.com/oil | sh
# maintenant que Oil est installé, création d'un projet de blog
# dans un dossier nommé Sites
cd Sites/
oil create blog

Pour de plus amples informations, consultez la partie détail installation rapideInstallation rapide.

Si vous ne pouvez pas utiliser la méthode d'installation rapide, vous pouvez aussi installer FuelPHP manuellement, vous trouverez les instructions détaillées sur la partie détail installation manuelleInstallation manuelle .

1. Lecture sur les composantsModèle vue contrôleur (MVC) d'une application FuelPHP.
2. ConfigurationConfiguration de votre nouvelle installation de FuelPHP.
3. Apprentissage de l'usage des modulesLes modules et des packagesLes packages.
4. Lecture sur les contrôleursLes contrôleurs.

Ceci fonctionne uniquement sur les systèmes *nix (Linux, OS X, Unix,etc.).

Notre installeur rapide est une interface dépouillée pour le package « oil ». Il permet de créer un nouveau projet avec une commande. Vous n'avez plus besoin d'utiliser « php » dans votre commande « oil ». Pour installer l'installeur rapide, ouvrez simplement un terminal et lancez la commande suivante :

curl get.fuelphp.com/oil | sh

Cette commande vous demandera votre mot de passe, car il installe le script dans /usr/bin.

Vous pouvez maintenant utiliser juste « oil » au lieu de « php oil » dans vos projets.

Si vous avez installé le script « oil » avant la version 1.6, vous devez le réinstaller pour qu'il lance aussi Composer.

Pour créer un nouveau projet, lancez simplement :

$ oil create <nom du projet>

Ceci va créer un dossier dans le dossier courant avec le nom de projet donné.Il va ensuite cloner le dépôt et tous les sous-modules dans le dossier.

Ceci va aussi lancer la commande « oil refine install », laquelle donne les droits d'écriture aux dossiers nécessaires, et la commande « php composer.phar », mises à jour pour remonter les dépendances définies dans Composer.

cd dossier/ou/se/trouve/votre/racine/virtualhost
git clone git://github.com/fuel/fuel.git .
./composer.phar update

N'oubliez-pas le « . » à la fin de la commande git. Sinon, cela vous créera un dossier nommé fuel à la racine de votre dossier virtualhost.

cd dossier/ou/se/trouve/votre/racine/virtualhost
git clone git://github.com/fuel/fuel.git -b 1.8/develop .
./composer.phar update --prefer-source

N'oubliez-pas le « . » à la fin de la commande git. Sinon, cela vous créera un dossier nommé fuel à la racine de votre dossier virtualhost.

Autre solution : vous pouvez utiliser « Composer » pour tout installer en une seule opération :

composer create-project fuel/fuel:dev-1.8/develop --prefer-source .

Les différentes étapes de téléchargement sont les suivantes :

1. Téléchargez le fichier zip du framework FuelPHP ;
2. Décompressez le fichier téléchargé, pour extraire les sources ;
3. Exécutez la commande « php composer.phar update » pour installer toutes les dépendances ;
4. Déplacez les fichiers sur votre serveur, selon les recommandations suivantes :

• le répertoire « public » du dossier source correspond au contenu du répertoire de votre site ou de votre application tel que défini dans votre serveur Web ; par exemple «  public_html », « public », « htdocs »,etc. Il faut donc déplacer ce contenu à l'emplacement requis, qui peut aussi être un sous-répertoire de votre « webroot » ; pourvu que ce soit la destination de votre utilisation de FuelPHP ;
• il est recommandé que le dossier « public » de votre installation FuelPHP soit différent de celui utilisé, par défaut, par votre serveur Web. Cette recommandation répond à des questions de sécurité ;
• il faudra aussi éditer le fichier index.php pour modifier les chemins d'accès des dossiers app, core, et packages, afin qu'ils pointent sur les chemins propres à votre installation :

/
 docs/
 fuel/
  app/
  core/
  packages/
 public/
  .htaccss
  assets/
  index.php
 oil

Après l'installation, assurez-vous que les permissions soient correctes sur les dossiers auxquels le framework doit accéder. Il existe une tâche « oil » qui permet de positionner les droits en écriture sur les dossiers de base :

php oil refine install
    Made writable: APPPATH/cache
    Made writable: APPPATH/logs
    Made writable: APPPATH/tmp
    Made writable: APPPATH/config

Comme expliqué au point 3.3Téléchargement du fichier zippé, pour des questions de sécurité, il est fortement recommandé de ne pas installer FuelPHP dans le dossier document root de votre serveur Web.

Cependant, il y a des cas où vous voudriez faire cela, par exemple pour un environnement de développement local où le module dynamique Apache mass virtual hosting est utilisé pour configurer rapidement des nouveaux environnements de développement sans la nécessité de redémarrer le serveur Web.

Dans un tel cas, installez FuelPHP dans un dossier que vous avez désigné comme dossier d'installation racine. Une fois cela effectué, allez dans le dossier public, déplacez tout un cran au-dessus, et supprimez-le. La seule utilité de ce dossier est de fournir un point d'ancrage pour les DocumentRoot de votre serveur Web. Vous n'en avez plus besoin puisque vous avez installé FuelPHP dans un dossier qui est DocumentRoot.

Après le déplacement, changez l'emplacement de l'application, des packages, et du cœur du framework dans le fichier index.php.

define('APPPATH', realpath(__DIR__.'/fuel/app/').DIRECTORY_SEPARATOR);
define('PKGPATH', realpath(__DIR__.'/fuel/packages/').DIRECTORY_SEPARATOR);
define('COREPATH', realpath(__DIR__.'/fuel/core/').DIRECTORY_SEPARATOR);

Cela ne fait pas de différence, la procédure reste exactement la même.

Dans ce cas cependant, votre application pourrait être un petit peu plus compliquée en raison de la structure de dossiers impactée. Mais vous ne pouvez pas juste y mettre un simple fichier .htaccess, vous voudrez probablement toujours accéder à d'autres éléments installés dans cette même structure de dossier.

En supposant que vous avez installé FuelPHP dans le dossier « /sous/dossier/profond » dans votre DocumentRoot, vous devriez normalement avoir accès à votre application en utilisant l'URL « http:/exemple.org/sous/dossier/profond ».

5-2-1. Apache▲

<IfModule mod_rewrite.c>
    RewriteEngine on
    # envoie la requête au sous-dossier, si ce n'est pas un vrai fichier, un vrai dossier, ou si c'est une requête racine
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d [OR]
    RewriteCond $1 ^$
    RewriteRule ^(.*)$ /sous/dossier/profond [R=301,L]
</IfModule>

<IfModule mod_rewrite.c>
    RewriteEngine on
    # envoie la requête au sous-dossier, si ce n'est pas un vrai fichier, un vrai dossier, ou si c'est une requête racine
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d [OR]
    RewriteCond $1 ^$
    RewriteRule ^(.*)$ /sous/dossier/profond [QSA,L]
</IfModule>

5-2-2. Nginx▲

server {
    server_name fuelphp.local;

    # on s'assure que Nginx peut écrire dans ces fichiers
    access_log /var/www/fuelphp/nginxlogs/access.log;
    error_log /var/www/fuelphp/nginxlogs/error.log;
    root /var/www/fuelphp/public;

   location/{
        index index.php;
        try_files $uri $uri/ /index.php$is_args$args;
    }

    location ~ \.php$ {
        include /etc/nginx/fastcgi_params;
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;
        fastcgi_param FUEL_ENV "production";
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}

Par défaut, l'environnement est configuré en mode développement. FuelPHP utilise l'environnement pour définir quels sont les paramètres de la base de données à utiliser. Mais l'environnement sert aussi à d'autres fins.

Pour configurer l'environnement, insérez la ligne suivante dans votre fichier .htaccess :

SetEnv FUEL_ENV production

Pour Nginx, il faut utiliser la déclaration « fastcgi param » , comme montrée dans l'exemple ci-dessus. Les options disponibles sont détaillées dans la classe Constants de la classe Fuel.

Le framework FuelPHP est conçu avec, à l'esprit, une configuration au-dessus des conventions. Ceci donne en résultat une plateforme hautement personnalisable sur laquelle vous bâtissez votre application.

Les fichiers de configuration sont stockés dans le dossier app/config. La configuration de base de l'application est faite dans app/config/config.php. La configuration chargée peut être spécifique à un environnement, plus d'informations dans la partie 5Configuration.

Pour écraser les paramètres d'une fonction spécifique, il suffit de créer soit un nouveau fichier dans app/config, soit copier le fichier correspondant depuis core/config vers app/config.

Ce sont les options qui peuvent être définies dans le fichier de configuration de base, app/config/config.php. Ce fichier est vide après l'installation de FuelPHP. Toutes les options par défaut, comme définies ci-dessous, sont définies dans le fichier correspondant dans le dossier core/config. Quand vous voulez surcharger une option, par défaut, ajoutez une clé au tableau dans votre fichier de configuration, et modifiez la valeur. Sinon, copiez la section depuis le fichier core dans le fichier de l'application, et modifiez-le.

FuelPHP utilise la notation « dot-notation » lors de la gestion des tableaux. C'est un moyen pratique pour accéder à des éléments de tableaux multidimensionnels. Cette notation, utilisée dans la documentation, fournit une référence simple à taper. Par exemple :

// quand vous voyez "always_load.packages = array()", c'est un raccourci pour :
array("always_load" => array("packages" => array(...) ) );

L'interaction avec les fichiers de configuration s'effectue avec la classe Config. Les fichiers de configuration peuvent aussi être générés via OilGénération de code avec Oil.

MVC (Modèle Vue Contrôleur) est une approche pour séparer le code en fonction du rôle qu'il joue dans votre application. Dans un flux d'application, on commence avec un contrôleur qui est chargé. Ce contrôleur exécute une méthode accédant aux données en utilisant des modèles. Une fois ce travail effectué, le contrôleur décide quelle vue charger, laquelle contient la sortie que vos visiteurs vont obtenir.

Les classes de contrôleur sont localisées dans « chemin_appli/classes/controller ».

FuelPHP décide quel contrôleur charger en fonction de l'URL demandée et quelle méthode y appliquer. C'est là que votre application commence à travailler. Le contrôleur décide des actions à effectuer, quoi faire des entrées utilisateur, quelles données manipuler et quelle vue à montrer à l'utilisateur. Cependant, le contrôleur ne fait rien de ces actions lui-même, il demande aux modèles et aux classes de faire le travail.

7-2-1. Qu'est-ce qu'un contrôleur ?▲

7-2-2. Créer un contrôleur▲

class Controller_Example extends Controller
{

    public function action_index()
    {
        $data['css'] = Asset::css(array('reset.css','960.css','main.css'));
        return Response::forge(View::forge('welcome/index'));
    }
}

7-2-3. Les méthodes HTTP préfixées action▲

class Controller_Example extends Controller
{
    public function get_index()
    {
        // Ceci sera appelé lors d'une méthode HTTP GET.
    }

    public function post_index()
    {
        // Ceci sera appelé lors d'une méthode HTTP POST.
    }
}

7-2-4. Les contrôleurs dans des sous-dossiers▲

7-2-5. Les espaces de noms contrôleur▲

7-2-6. Utilisation de plus de paramètres depuis l'URL▲

public function action_name_to_upper($name_1, $name_2)
{
    $data['name_1'] = strtoupper($name_1);
    $data['name_2'] = strtoupper($name_2);
    return View::forge('test/name_to_upper', $data);
}

7-2-7. Retourner le résultat▲

7-2-8. Méthodes spéciales contrôleur▲

7-2-9. action_index()▲

7-2-10. before()▲

7-2-11. after($reponse)▲

7-2-12. router($methode,$parametres)▲

7-2-13. Extension des autres contrôleurs▲

class Controller_Exemple extends Controller_Bienvenue
{

    // vos méthodes

}

7-2-14. Créer des contrôleurs de base▲

class Controller_Admin extends Controller
{

    public function before()
    {
        // vérifie si administrateur
    }

    // vos méthodes

    public function action_index()
    {
        // charge le tableau de bord
    }

    public function action_login()
    {
        // logue l'utilisateur
    }
}

class Controller_Admin_User extends Controller_Admin
{

    public function action_index()
    {
        // Remplace le tableau de bord avec le listing de l'index utilisateur
    }

    public function action_edit($id)
    {
        // édition des utilisateurs
    }
}

Les classes de modèle sont localisées dans chemin_appli/classes/model

7-3-1. Que sont les modèles ?▲

7-3-2. Comment sont utilisés les modèles ?▲

7-3-3. Créer un modèle▲

namespace Model;

class Bienvenue extends \Model {

    public static function get_results()
    {
        // interactions avec la base de données
    }

}

7-3-4. Accéder à un modèle▲

use \Model\Bienvenue;

class Controller_ Bienvenue extends Controller
{
    public function action_index()
    {
        $resultat = Bienvenue::get_results();
    }
}

7-3-5. Écrivez vos propres modèles▲

7-3-6. Écrire des requêtes SQL▲

DB::query('SELECT * FROM users WHERE id = 5');

7-3-7. Utiliser le constructeur de requêtes▲

DB::select('title','content')->from('articles')->execute()->get('title');

7-3-8. Utiliser le modèle CRUD pour créer des modèles▲

// trouve tous les articles
$entry = Model_Article::find_all();

// trouve tous les articles de la catégorie 1 classés par date la plus récente
$entry = Model_Article::find(array(
    'where' => array('category_id', 1),
    'order_by' => array('date' => 'desc')
));

7-3-9. Utiliser ORM pour créer des modèles▲

// recherche de tous les articles
$entry = Model_Article::find('all');

// recherche de tous les articles de la catégorie 1 classés par date descendante
$entry = Model_Article::find('all', array(
    'where' => array('category_id', 1),
    'order_by' => array('date', 'desc')
));

Les classes de vue sont localisées dans chemin_appli/classes/views.

Les vues contiennent votre code HTML, lequel ne devrait jamais se trouver dans vos contrôleurs ou une autre classe qui n'est pas destinée à créer une sortie. En séparant votre rendu de votre logique, vous garantissez que, quand vous décidez de changer votre disposition, vous avez seulement à changer les vues, et ne pas vous occuper des contrôleurs. Ainsi, les vues ne devraient contenir que les commandes PHP : echo et foreach.

7-4-1. Qu'est-ce qu'une vue ?▲

7-4-2. Créer une vue▲

<html>
    <head>
        <title><?php echo $titre; ?></title>
    </head>
    <body>
        Bienvenue, <?php echo $username; ?>.
    </body>
</html>

7-4-3. Utiliser des vues▲

<html>
    <head>
        <title><?php echo $titre; ?></title>
    </head>
    <body>
        Bienvenue, <?php echo $username; ?>.
    </body>
</html>

class Controller_Home extends Controller
{
    public function action_index()
    {
        $data = array(); //stocke les variables qui iront dans les vues

        $data['username'] = 'Joe14';
        $data['titre'] = 'Home';

        //assigne la vue à la sortie du navigateur
        return View::forge('home/index', $data);
    }
}

class Controller_Home extends Controller
{
    public function action_index()
    {
        //création de la vue
        $vue = View::forge('home/index');

        //assignation des variables pour la vue
        $vue->username = 'Joe14';
        $vue->titre = 'Home';

        // une autre façon d'assigner les variables pour la vue
        $vue->set('username', 'Joe14');
        $vue->set('titre', 'Home');

        //assignation de la vue à la sortie du navigateur
        return $vue;
    }
}

7-4-4. Sécurité▲

class Controller_Exemple extends Controller
{
    public function action_index()
    {
        $vue = \View::forge('exemple');

        // ajoute filtré, sorties: <strong> pas du gras car filtrage de </strong>
        $vue->title = '<strong>npas du gras car filtré</strong>';

        // ajoute non filtré, sorties: <strong> gras à cause du non filtrage</strong>
        $vue->set('titre', '<strong> ras à cause du non filtrage</strong>', false);

        // ou utiliser la méthode set_safe(), laquelle est identique à  set() mais est à 'false' par défaut
        $vue->set_safe('titre', '<strong> gras à cause du filtrage</strong>');

        return $vue;
    }
}

7-4-5. Rendu « paresseux »▲

7-4-6. Vues de niche▲

7-4-7. Exemple de vues▲

<html>
    <head>
        <?php echo $head; ?>
    </head>
    <body>
        <?php echo $header; ?>
        <?php echo $content; ?>
        <?php echo $footer; ?>
    </body>
</html>

<title><?php echo $titre; ?></title>

<div class="logo"></div>
<div class="texte de logo"><?php echo $titre_site; ?></div>

<h1><?php echo $titre; ?></h1>
<div class="accueil_utilisateur">Bienvenue <?php echo $username; ?></div>

<div class="footer">
    &copy; Copyright <?php echo date('Y');?> <?php echo $titre_site; ?>
</div>

7-4-8. Méthode 1 (utilisant les vues de l'exemple ci-dessus et le rendu « paresseux »)▲

class Controller_Home extends Controller
{
    public function action_index()
    {
        // create the layout view
        $vue = View::forge('layout');

        // assignation variables globales, toutes les vues y ont donc accès
        $vue->set_global('username', 'Joe14');
        $vue->set_global('titre', 'Home');
        $vue->set_global('titre_site', 'Mon site Web');

        //assignation vues comme variables, rendu paresseux
        $vue->head = View::forge('head');
        $vue->header = View::forge('header');
        $vue->content = View::forge('content');
        $vue->footer = View::forge('footer');

        // returne l'objet vue à la requete
        return $vue;
    }
}

7-4-9. Méthode 2 ( utilisant les vues de l'exemple ci-dessus et le rendu forcé)▲

class Controller_Home extends Controller
{
    public function action_index()
    {
        //assignation variables
        $data = array();
        $data['titre'] = 'Home';
        $data['titre_site'] = 'Mon site Web';
        $data['username'] = 'Joe14';

        //assignation vues comme variables, rendu forcé
        $vues = array();
        $vues['head'] = View::forge('head', $data)->render();
        $vues['header'] = View::forge('header', $data)->render();
        $vues['content'] = View::forge('content', $data)->render();
        $vues['footer'] = View::forge('footer', $data)->render();

        // retourne le rendu HTML à la requête
        return View::forge('layout', $vues)->render();
    }
}

7-4-10. Méthode 3 ( utilisant les vues de l'exemple ci-dessus, sans donnée globale, et avec le rendu « paresseux »)▲

class Controller_Home extends Controller
{
    public function action_index()
    {
        // creationde la couche vue
        $vue = View::forge('layout');

        //variables locales de la vue, rendu paresseux
        $vue->head = View::forge('head', array('titre' => 'Home'));
        $vue->header = View::forge('header', array('titre_site' => 'Mon site Web'));
        $vue->content = View::forge('content', array('username' => 'Joe14', 'titre' => 'Home'));
        $view->footer = View::forge('footer', array('titre_site' => 'Mon site Web'));

        // retourne l'objet vue à la requête
        return $vue;
    }
}

Les classes de présentation sont localisées dans chemin_appli/classes/presenter.

Quand votre application s'enrichit avec de nouveaux objets, elle devient plus complexe. Vous découvrirez, alors, qu'il devient plus difficile de dissocier ce qui appartient au contrôleur, de ce qui appartient à la vue. La logique de votre application peut devenir compliquée à discerner. C'est là qu'intervient la présentation : c'est le lien entre votre contrôleur et vos vues.

7-5-1. Qu'est-ce qu'une présentation ?▲

7-5-2. Créer une présentation▲

class Presenter_Index extends Presenter
{
}

<h1><?php echo $titre; ?></h1>

<ul>
<?php
    foreach ($articles as $a)
    {
        echo '<li>'.$a->titre.'</li>';
    }
?>
</ul>

$presentation = Presenter::forge('index');

class Presenter_Index extends Presenter
{

    public function view()
    {
        $this->title = 'Test cette présentation';

        $this->articles = Model_Articles::find('all');
    }
}

7-5-3. Passage de fonctions à des vues▲

// Dans la présentation
class Presenter_Index extends Presenter
{

    public function view()
    {
        $this->echo_upper = function($string) { echo strtoupper($string); };
    }
}

// Ce que vous pouvez ensuite utiliser dans votre vue:
$echo_upper('this string'); // Outputs: "THIS STRING"

7-5-4. Sécurité▲

7-5-5. Usage avancé▲

// va appeler une autre method() au-dessus de la présentation
$presentation = Presenter::forge('index', 'autre_methode');

// utilisation de la vue 'autre/index' au lieu de 'index'
$presentation = Presenter::forge('index', 'autre_methode', null, 'autre/index');

// vous pouvez aussi passer directement un objet vue
$vue = View::forge('autre/index');
$presentation = Presenter::forge('index', 'autre_methode', null, $vue);

Quand une erreur 404 se produit pendant une requête HMVC, une HttpNotFoundException est levée. Si non traitée, elle va déclencher le chargement de la page 404 par défaut du framework. Cependant, vous pouvez prévenir ceci en gérant votre propre page 404 :

try
{
    \Request::forge('this_will_fail');
}
catch (HttpNotFoundException $e)
{
    // Gestion exception
}

Si vous voulez accéder à d'autres requêtes, vous pouvez les traverser en utilisant deux méthodes : $request->parent() et $request->children(). Le parent est la requête durant laquelle la requête courante a été créée (null pour la requête principale). Les enfants sont toutes les requêtes créées durant la requête courante.

Pour générer un squelette de contrôleur avec des actions et des vues prédéfinies, utilisez la commande suivante :

$ php oil g controller posts action1 action2 action3
    Created view: APPPATH/views/posts/action1.php
    Created view: APPPATH/views/posts/action2.php
    Created view: APPPATH/views/posts/action3.php
    Created controller: APPPATH/classes/controller/posts.php

Ceci va produire un contrôleur ressemblant à ça :

class Controller_Posts extends Controller_Template
{

    public function action_action1()
    {
        $this->template->title = 'Posts  Action1';
        $this->template->content = View::forge('posts/action1');
    }

    public function action_action2()
    {
        $this->template->title = 'Posts  Action2';
        $this->template->content = View::forge('posts/action2');
    }

    public function action_action3()
    {
        $this->template->title = 'Posts  Action3';
        $this->template->content = View::forge('posts/action3');
    }

}

/* Fin de fichier posts.php */

Pour générer un simple modèle en énumérant les champs, et bénéficier de la migration automatique des paramètres, il faut exécuter les commandes suivantes :

$ php oil g model post title:varchar[50] body:text user_id:int
    Created model: APPPATH/classes/model/post.php
    Created migration: APPPATH/migrations/001_create_posts.php

Ceci va créer un modèle simple qui utilise Orm, donc assurez-vous que le package est activé dans votre fichier de configuration. Il ressemblera à :

class Model_Post extends Orm\Model {

    protected static $_properties = array(
        'id',
        'title',
        'body',
        'created_at',
        'updated_at'
    );

    protected static $_observers = array(
        'Orm\Observer_CreatedAt' => array(
            'events' => array('before_insert'),
            'mysql_timestamp' => false,
        ),
        'Orm\Observer_UpdatedAt' => array(
            'events' => array('before_save'),
            'mysql_timestamp' => false,
        ),
    );

}

/* Fin de fichier post.php */

Pas très extraordinaire, mais la migration est la partie utilisée ici :

namespace Fuel\Migrations;

class Create_posts
{
    public function up()
    {
        \DBUtil::create_table('posts', array(
            'id' => array('constraint' => 11, 'type' => 'int', 'auto_increment' => true),
            'title' => array('constraint' => 50, 'type' => 'varchar'),
            'body' => array('type' => 'text'),
            'user_id' => array('constraint' => 11, 'type' => 'int'),
            'created_at' => array('type' => 'datetime'),

        ), array('id'));
    }

    public function down()
    {
        \DBUtil::drop_table('posts');
    }
}

Si vous ne souhaitez pas générer une migration, fournissez simplement -no-migration :

$ php oil g model post title:varchar[50] body:text user_id:int --no-migration
    Created model: APPPATH/classes/model/post.php

Par défaut, le nom de classe est généré singulièrement (il représente un post), mais la table correspondante est générée de façon plurielle (contient des posts multiples). Vous pouvez faire utiliser à la table le même nom que le modèle en utilisant -singular.

FuelPHP v1.1 a ajouté un modèle simple basé sur le modèle CRUD lequel offre une fonctionnalité similaire à l'utilisation d'ORM, sans surcharge des données relationnelles. Vous pouvez avoir le modèle généré par l'ajout de --crud.

$ php oil g model post title:varchar[50] body:text user_id:int created_at:datetime --crud
    Created model: APPPATH/classes/model/post.php
    Created migration: APPPATH/migrations/001_create_posts.php

Ceci va créer un modèle simple qui utilise Fuel\Core\Model_Crud. Il ressemblera à ça :

class Model_Post extends \Model_Crud
{
    protected static $_properties = array(
        'id',
        'title',
        'body',
        'user_id',
        'created_at',
        'updated_at'
    );

    protected static $_table_name = 'posts';

}

Ajoutez -no-timestamp pour exclure les champs reated/updated et les observateurs.

$ php oil g model post title:varchar[50] body:text user_id:int --no-timestamp

class Model_Post extends \Orm\Model
{
  protected static $_properties = array(
    'id',
    'title',
    'body',
    'user_id'
  );

}
namespace Fuel\Migrations;

class Create_posts
{
  public function up()
  {
    \DBUtil::create_table('posts', array(
      'id' => array('constraint' => 11, 'type' => 'int', 'auto_increment' => true),
      'title' => array('constraint' => 50, 'type' => 'varchar'),
      'body' => array('type' => 'text'),
      'user_id' => array('constraint' => 11, 'type' => 'int'),

    ), array('id'));
  }

  public function down()
  {
    \DBUtil::drop_table('posts');
  }
}

Quand vous utilisez les champs de TimeStamp dans n'importe quel modèle ORM ou CRUD (\Model_Crud) vous pouvez choisir vos propres noms de champ. Il suffit d'utiliser les options --created-at et -updated-at pour fixer vos propres noms de champ.

Par défaut, quand vous activez les timestamps, ceux-ci sont stockés en temps UNIX, dans un entier. Si vous préférez le format MySQL DATETIME, vous pouvez utiliser l'option -mysql-timestamp.

$ php oil g model post title:varchar[50] body:text user_id:int --mysql-timestamp --created-at=my_created

Ce qui donnera :

<?php

class Model_Post extends \Orm\Model
{
    protected static $_properties = array(
        'id',
        'title',
        'body',
        'user_id',
        'my_created',
        'updated_at'
    );

    protected static $_observers = array(
        'Orm\Observer_CreatedAt' => array(
            'events' => array('before_insert'),
            'mysql_timestamp' => true,
            'property' => 'my_created',
        ),
        'Orm\Observer_UpdatedAt' => array(
            'events' => array('before_save'),
            'mysql_timestamp' => true,
        ),
    );
}
<?php

namespace Fuel\Migrations;

class Create_posts
{
    public function up()
    {
        \DBUtil::create_table('posts', array(
            'id' => array('constraint' => 11, 'type' => 'int', 'auto_increment' => true),
            'title' => array('constraint' => 50, 'type' => 'varchar'),
            'body' => array('type' => 'text'),
            'user_id' => array('constraint' => 11, 'type' => 'int'),
            'my_created' => array('constraint' => 11, 'type' => 'int'),
            'updated_at' => array('constraint' => 11, 'type' => 'int'),

        ), array('id'));
    }

    public function down()
    {
        \DBUtil::drop_table('posts');
    }
}

FuelPHP v1.5 a ajouté un modèle Model_Soft, basé sur le modèle ORM. Il suffit d'ajouter -soft-delete pour utiliser Model_Soft.

$ php oil g model post title:varchar[50] body:text user_id:int --soft-delete

Ce qui donnera :

<?php

class Model_Post extends \Orm\Model_Soft
{
    protected static $_properties = array(
        'id',
        'title',
        'body',
        'user_id',
        'created_at',
        'updated_at',
        'deleted_at',
    );

    protected static $_observers = array(
        'Orm\Observer_CreatedAt' => array(
            'events' => array('before_insert'),
            'mysql_timestamp' => false,
        ),
        'Orm\Observer_UpdatedAt' => array(
            'events' => array('before_update'),
            'mysql_timestamp' => false,
        ),
    );

    protected static $_soft_delete = array(
        'mysql_timestamp' => false,
    );
}
<?php

namespace Fuel\Migrations;

class Create_posts
{
    public function up()
    {
        \DBUtil::create_table('posts', array(
            'id' => array('constraint' => 11, 'type' => 'int', 'auto_increment' => true, 'unsigned' => true),
            'title' => array('constraint' => 50, 'type' => 'varchar'),
            'body' => array('type' => 'text'),
            'user_id' => array('constraint' => 11, 'type' => 'int'),
            'created_at' => array('constraint' => 11, 'type' => 'int', 'null' => true),
            'updated_at' => array('constraint' => 11, 'type' => 'int', 'null' => true),
            'deleted_at' => array('constraint' => 11, 'type' => 'int', 'null' => true),

        ), array('id'));
    }

    public function down()
    {
        \DBUtil::drop_table('posts');
    }
}

Si vous souhaitez changer le nom du champ deleted_at, utilisez l'option -deleted-at pour fixer votre propre nom de champ.

$ php oil g model post title:varchar[50] body:text user_id:int --soft-delete --deleted-at=mydeleted

Ajoutez -temporal pour utiliser Model_Temporal.

$ php oil g model post title:varchar[50] body:text user_id:int --temporal

Ce qui vous donnera :

<?php

class Model_Post extends \Orm\Model_Temporal
{
    protected static $_properties = array(
        'id',
        'temporal_start',
        'temporal_end',
        'title',
        'body',
        'user_id',
    );


    protected static $_temporal = array(
        'mysql_timestamp' => false,
    );

    protected static $_primary_key = array('id', 'temporal_start', 'temporal_end');
    protected static $_table_name = 'posts';

}
<?php

namespace Fuel\Migrations;

class Create_posts
{
    public function up()
    {
        \DBUtil::create_table('posts', array(
            'id' => array('constraint' => 11, 'type' => 'int', 'auto_increment' => true, 'unsigned' => true),
            'temporal_start' => array('constraint' => 11, 'type' => 'int'),
            'temporal_end' => array('constraint' => 11, 'type' => 'int'),
            'title' => array('constraint' => 50, 'type' => 'varchar'),
            'body' => array('type' => 'text'),
            'user_id' => array('constraint' => 11, 'type' => 'int'),

        ), array('id'));
    }

    public function down()
    {
        \DBUtil::drop_table('posts');
    }
}

Veuillez noter que temporal_start et temporal_end ne sont pas ajoutés à la clé primaire du tableau de migration. Vous devez les ajouter manuellement. Le paramètre --no-timestamp est fixé à true par défaut. Ce qui signifie que la création de champs created_at and updated_at et les observateurs connexes sont omis. Vous pouvez contourner ce comportement par défaut avec -no-timestamp=0 pour les retrouver.

Si vous souhaitez changer le nom des champs temporal_start ou temporal_end, utilisez les options --temporal-start ou -temporal-end pour fixer vos propres noms de champ.

$ php oil g model post title:varchar[50] body:text user_id:int --temporal --temporal-start=mystart --temporal-end=myend

Pour générer un modèle Model_Nestedset, il faut ajoutez -nestedset.

$ php oil g model post title:varchar[50] body:text user_id:int --nestedset

Ce qui vous donnera :

<?php

class Model_Post extends \Orm\Model_Nestedset
{
    protected static $_properties = array(
        'id',
        'left_id',
        'right_id',
        'title',
        'body',
        'user_id',
    );

    protected static $_table_name = 'posts';
}
<?php

namespace Fuel\Migrations;

class Create_posts
{
    public function up()
    {
        \DBUtil::create_table('posts', array(
            'id' => array('constraint' => 11, 'type' => 'int', 'auto_increment' => true, 'unsigned' => true),
            'left_id' => array('constraint' => 11, 'type' => 'int', 'unsigned' => true),
            'right_id' => array('constraint' => 11, 'type' => 'int', 'unsigned' => true),
            'title' => array('constraint' => 50, 'type' => 'varchar'),
            'body' => array('type' => 'text'),
            'user_id' => array('constraint' => 11, 'type' => 'int'),

        ), array('id'));
    }

    public function down()
    {
        \DBUtil::drop_table('posts');
    }
}

--no-timestamp est fixé à true par défaut, ce qui signifie la création des champs created_at et updated_at et leurs observateurs respectifs sont omis. Vous pouvez contourner ce comportement par défaut avec--no-timestamp=0 pour les retrouver.

Si vous souhaitez changer les noms de champ title, tree_id, left_id, right_id, utilisez une des options --title, --tre-id, --left-id, --right-id pour fixer vos propres noms de champ.

$ php oil g model post title:varchar[50] body:text user_id:int --nestedset --title=mytitle --tree-id=mytreeid --left-id=myleftid --right-id=myrightid

Optionnellement, vous pouvez avoir à générer une classe présentation pour accompagner la vue.

$ php oil g controller posts action1 action2 action3 --with-presenter

Les commandes suivantes illustrent comment utiliser la commande refine pour lancer des tâches de migration utiles, en supposant que le système est actuellement en migration. La tâche de migration peut recevoir en paramètre une version donnée ou up/down pour migration à une version d'écart.

$ php oil refine migrate
    Currently on migration: 5.

$ php oil refine migrate --version=4
    Migrated to version: 4.

$ php oil refine migrate --version=5
    Migrated to version: 5.

$ php oil refine migrate:down
    Migrated to version: 4.

$ php oil refine migrate:up
    Migrated to version: 5.

Les types de champs suivant sont supportés : string[n], varchar[n], int[n], enum[value1, value2], decimal[n, n], float[n, n], text, blob, datetime, date, timestamp et time.

Vous pouvez générer des migrations sans créer un modèle. Cela pourrait être utilisé pour renommer une table, ou ajouter des champs à une table d'une façon, qui sera facile à déployer dans d'autres environnements.

$ php oil generate migration rename_table_users_to_accounts
    Building magic migration: rename_table
    Created migration: APPPATH/migrations/002_rename_table_users_to_accounts.php

Les Magic_Migrations sont un certain nombre de migrations « magiques », lesquelles vous construisent automatiquement une migration basée sur un préfixe de votre nom de migration.

$ php oil generate migration create_users name:text email:string[50] password:string[125]
$ php oil generate migration rename_table_users_to_accounts
$ php oil generate migration add_bio_to_accounts bio:text
$ php oil generate migration delete_bio_from_accounts bio:text
$ php oil generate migration rename_field_name_to_username_in_accounts
$ php oil generate migration drop_accounts

L'échafaudage est vraiment la partie la plus passionnante de la génération de code Oil. Cette approche est empruntée à Rails qui y a apporté de nombreuses améliorations. L'idée n'étant pas seulement de créer des squelettes MVC et de migrations, mais de les peupler avec du code CRUD par défaut, le code fonctionne donc après avoir écrit la commande.

$ php oil g scaffold monkey name:string description:text
    Created model: APPPATH/classes/model/monkey.php
    Created migration: APPPATH/migrations/003_create_monkeys.php
    Created controller: APPPATH/classes/controller/monkeys.php
    Created view: APPPATH/views/monkeys/index.php
    Created view: APPPATH/views/monkeys/view.php
    Created view: APPPATH/views/monkeys/create.php
    Created view: APPPATH/views/monkeys/edit.php
    Created view: APPPATH/views/monkeys/_form.php

$ php oil refine migrate
Migrated to latest version: 3.

Comme vous pouvez le voir, une grande partie du code est générée par cette commande incluant une commande exécutée dans la seconde commande. Le contrôleur ressemble à ceci :

class Controller_Monkey extends Controller_Template
{

    public function action_index()
    {
        $data['monkeys'] = Model_Monkey::find('all');
        $this->template->title = "Monkeys";
        $this->template->content = View::forge('monkey/index', $data);

    }

    public function action_view($id = null)
    {
        $data['monkey'] = Model_Monkey::find($id);

        $this->template->title = "Monkey";
        $this->template->content = View::forge('monkey/view', $data);

    }

    public function action_create($id = null)
    {
        if (Input::method() == 'POST')
        {
            $monkey = Model_Monkey::forge(array(
                'name' => Input::post('name'),
                'description' => Input::post('description'),
            ));

            if ($monkey and $monkey->save())
            {
                Session::set_flash('success', 'Added monkey #'.$monkey->id.'.');

                Response::redirect('monkey');
            }

            else
            {
                Session::set_flash('error', 'Could not save monkey.');
            }
        }

        $this->template->title = "Monkeys";
        $this->template->content = View::forge('monkey/create');

    }

    public function action_edit($id = null)
    {
        $monkey = Model_Monkey::find($id);

        if (Input::method() == 'POST')
        {
            $monkey->name = Input::post('name');
            $monkey->description = Input::post('description');

            if ($monkey->save())
            {
                Session::set_flash('success', 'Updated monkey #' . $id);

                Response::redirect('monkey');
            }

            else
            {
                Session::set_flash('error', 'Could not update monkey #' . $id);
            }
        }

        else
        {
            $this->template->set_global('monkey', $monkey, false);
        }

        $this->template->title = "Monkeys";
        $this->template->content = View::forge('monkey/edit');

    }

    public function action_delete($id = null)
    {
        if ($monkey = Model_Monkey::find($id))
        {
            $monkey->delete();

            Session::set_flash('success', 'Deleted monkey #'.$id);
        }

        else
        {
            Session::set_flash('error', 'Could not delete monkey #'.$id);
        }

        Response::redirect('monkey');

    }
}

Vous pouvez échanger l'échafaudage avec l'administration et générer un contrôleur qui étend Controller_Admin au lieu de Controller_Template. À la première utilisation de cette commande un squelette administration sera généré. Pour étendre ce squelette, utilisez l'argument skip force. Pour générer dans des sous-dossiers nommez le préfixe avec le nom de modèle en conséquence.

$ php oil g admin project_entry title:string abstract:text full_text:text project_id:int is_draft:int order:int -s
    Creating migration: APPPATH/migrations/012_create_project_entries.php
    Creating model: APPPATH/classes/model/project/entry.php
    Creating controller: APPPATH/classes/controller/admin/project/entry.php
    Creating view: APPPATH/views/admin/project/entry/index.php
    Creating view: APPPATH/views/admin/project/entry/view.php
    Creating view: APPPATH/views/admin/project/entry/create.php
    Creating view: APPPATH/views/admin/project/entry/edit.php
    Creating view: APPPATH/views/admin/project/entry/_form.php

Vous pouvez aussi utiliser Oil pour générer le squelette d'une nouvelle tâche.

$ php oil g task newtask cmd1 cmd2

Ce qui générera :

<?php

namespace Fuel\Tasks;

class Newtask
{
    public static function run($args = NULL)
    {
        echo "\n===========================================";
        echo "\nLancer une tache par DEFAUT [Newtask:Run]";
        echo "\n-------------------------------------------\n\n";

        /***********************************
         Mettez les DÉTAILS DE LA TÂCHE ICI
         ***********************************/
    }

    public static function cmd1($args = NULL)
    {
        echo "\n===========================================";
        echo "\nLancement tache [Newtask:Cmd1]";
        echo "\n-------------------------------------------\n\n";

        /***********************************
         Mettez les DÉTAILS DE LA TÂCHE ICI
         ***********************************/
    }

    public static function cmd2($args = NULL)
    {
        echo "\n===========================================";
        echo "\nLancement tache [Newtask:Cmd2]";
        echo "\n-------------------------------------------\n\n";

        /***********************************
         Mettez les  DÉTAILS DE LA TÂCHE ICI
         ***********************************/
    }
}
/* End of file tasks/newtask.php */

Pour générer une configuration, utilisez la commande suivante :

$ php oil g config sample hello:world
    Created config: APPPATH/config/sample.php

Ce qui produira une configuration ressemblant à ceci :

return array (
    'hello' => 'world',
);

/* Fin de fichier echantillon.php */

Pour combiner une configuration depuis COREPATH/config si COREPATH/config n'en a pas :

$ php oil g config package
    Created config: APPPATH/config/package.php

Ceci produira une configuration ressemblant à cela :

return array (
    'sources' =>
    array (
        0 => 'github.com/fuel-packages',
    ),
);

Pour combiner la configuration depuis COREPATH/config et COREPATH/config vers APPPATH/config, il faut exécuter la commande suivante :

$ php oil g config form --overwrite
    Created config: APPPATH/config/form.php

Ceci produira une configuration ressemblant à cela :

return array (
    'prep_value' => true,
    'auto_id' => true,
    'auto_id_prefix' => '',
    'form_method' => 'post',
);

/* Fin de fichier formulaire.php */

Pour générer un package, utilisez la commande suivante :

$ php oil g package sample
    Creating file: PKGPATH/sample/classes/sample.php
    Creating file: PKGPATH/sample/config/sample.php
    Creating file: PKGPATH/sample/bootstrap.php

Le chemin par défaut où est généré le package est PKGPATH, mais il peut être modifié dans la configuration package_paths en passant l'option --path=package_path ou -p=package_path à la commande.

9-19-1. Générer un package « driver-based »▲

$ php oil g package sample -d
    Creating file: PKGPATH/sample/classes/sample.php
    Creating file: PKGPATH/sample/classes/sample/driver.php
    Creating file: PKGPATH/sample/config/sample.php
    Creating file: PKGPATH/sample/bootstrap.php

$ php oil g package sample -d=driver1,driver2
    Creating file: PKGPATH/sample/classes/sample.php
    Creating file: PKGPATH/sample/classes/sample/driver.php
    Creating file: PKGPATH/sample/classes/sample/driver1.php
    Creating file: PKGPATH/sample/classes/sample/driver2.php
    Creating file: PKGPATH/sample/config/sample.php
    Creating file: PKGPATH/sample/bootstrap.php

9-19-2. Générer un package avec des fichiers VCS▲

$ php oil g package sample -v
    Creating file: PKGPATH/sample/composer.json
    Creating file: PKGPATH/sample/README.md
    Creating file: PKGPATH/sample/classes/sample.php
    Creating file: PKGPATH/sample/config/sample.php
    Creating file: PKGPATH/sample/bootstrap.php

9-19-3. Les modules de package▲

$ php oil g module blog

$ php oil g module blog

$ php oil g module blog --folders=classes/model,classes/controller,config,lang

Les tâches sont des classes qui peuvent être exécutées en ligne de commande, ou planifiées dans un job cron. Elles sont généralement utilisées pour des processus en arrière-plan (background), des tâches chronométrées, et des tâches de maintenance. Les tâches peuvent appeler des modèles ou d'autres classes comme pour les contrôleurs.

Dans FuelPHP, les contrôleurs sont placés dans le dossier fuel/app/tasks. Ci-dessous, un exemple de tâche « exemple » :

namespace Fuel\Tasks;

class Exemple
{

    public function run($message = 'Hello!')
    {
        echo $message;
    }
}

Ceci sera appelé via l'utilitaire refine dans Oil :

$ php oil refine exemple "Bonjour"

Quand le nom de la tâche est utilisé dans la commande, la méthode « run() » est appelée.

Vous pouvez ajouter plus de méthodes à votre tâche pour fractionner un groupe de tâches en tâches plus spécifiques pouvant être appelées séparément.

public function current_date()
{
    echo date('Y-m-d');
}

Nous pouvons appeler cette méthode en utilisant :

$ php oil refine example:current_date

Un module est un groupe d'éléments MVC indépendants. L'utilisation de modules permet la réutilisation possible et l'encapsulation de votre code. Un module réside habituellement dans un sous-dossier nommé modules. Il est suggéré de profiter des modules chaque fois que vous travaillez sur un gros projet, quand vous pensez que le code de base fera plus que quelques lignes de code. Cela vous aidera à ranger soigneusement les choses.

Un module peut agir indépendamment, par exemple un module de blog ou d'album. Vous pouvez router directement vers le module controllers, sans avoir à accéder au code global. Les modules peuvent aussi être utilisés dans un réel contexte HMVC, là où les contrôleurs appellent d'autres contrôleurs, lesquels vont produire (une partie) le résultat souhaité pour générer le résultat de la page demandée.

Pour pouvoir utiliser des modules, vous devez dire à FuelPHP où ceux-ci sont stockés. Par défaut, ils sont dans le dossier modules de votre application. Pour définir le chemin d'accès à vos modules, il vous faut modifier la ligne « modules_path » du fichier config.php de votre application. Vous pouvez aussi définir plusieurs chemins d'accès, si vous le faites, ils seront utilisés pour la recherche des modules dans l'ordre que vous aurez définis.

/**
* Pour vous permettre de découper votre application en modules pouvant                   * être routés par le premier segment URI, vous devez définir leur chemin de *base ici.
**/
'module_paths' => array(
    APPPATH.'modules'.DS,               // chemin des modules d'application
    APPPATH.'..'.DS.'globalmods'.DS     // chemin global vers vos modules
),

Quand vous définissez vos chemins, assurez-vous qu'ils finissent par « DS », le séparateur de dossier de FuelPHP.

Un des problèmes souvent rencontrés en travaillant avec du code développé indépendamment, c'est l'éventualité des collisions de noms de classes. Par exemple, beaucoup de modules sont fournis avec un contrôleur admin. Pour éviter les collisions dans FuelPHP, chaque module n'est défini que dans son propre espace de noms, lequel doit être nommé à l'identique du nom du dossier du module.

<?php
/**
 * contrôleur du module dans le module Monmodule
 */

namespace Monmodule;

class Controller_Widget
{

    // placez le code de votre contrôleur ici, tout comme pour un contrôleur d'application
}

Si vous avez déplacé vos contrôleurs dans un namespace comme expliqué ici, vous devez utiliser le même setup pour vos contrôleurs de module. Dans l'exemple, ci-dessus, le namespace sera Mymodule\Controller, le Widget classname.

Il faut commencer la création d'un module par la création d'un répertoire pour celui-ci, dans le dossier des modules défini dans la configuration. Les noms de dossiers déterminent les noms de module, et le namespace pour les classes de celui-ci. Ce nom est également utilisé dans l'URI, si vous voulez router les contrôleurs de module, ou comme partie d'une requête en cas d'appel HMVC.

Comme un module peut être vu comme une partie contenue dans votre propre application, vous remarquerez que la structure de dossier d'un module est très familière, c'est la même que la structure d'un dossier application. La structure de dossier suivante est prise en charge pour un module :

• classes

  • contrôleur
  • modèle
  • vue
• configuration
• langue
• tâches
• vues

Que ce soit un fichier de configuration ou de vue, un chargement de fichier de module transversal doit avoir le module préfixé du nom de fichier :

// Chargement transversal de configuration
\Config::load('autremodule::myconfig');

// Chargement transversal d'une vue
\View::forge('autremodule::subdir/view');
Lance une tâche depuis le module :
$ php oil refine <nom_du_module>::<nom_tache>:<nom_methode>

Quand vous utilisez des modules en mode routé, vous pouvez ajouter des routes personnalisées pour votre module en incluant un fichier routes.php dans votre dossier de configuration modules. Ces routes seront chargées quand FuelPHP détectera que le premier segment URI fera référence à un module, et seules les routes de ce module seront chargées. Ces routes seront ajoutées au début du tableau de routes de sorte qu'une possible route (n'importe laquelle) dans les routes principales de la configuration ne soit pas traitée avant celles du module.

Cela implique que les routes module peuvent être utilisées pour le routage global ou pour les autres modules. En d'autres termes, la partie gauche devrait toujours inclure le module courant comme premier segment d'URI. Pour la partie droite, vous pouvez utiliser tout ce qui est défini dans les sections ci-dessus. C'est très bien d'avoir une route de module dans un contrôleur d'application ou dans un autre module.

En plus d'utiliser les modules pour séparer logiquement les parties indépendantes de votre application, vous pouvez utiliser les contrôleurs de module dans un contexte HMVC, là où vos contrôleurs d'application appellent un ou plusieurs contrôleurs de module pour créer le résultat final d'une requête URI.

Lisez la documentation des requêtes HMVC pour en découvrir plus.

Il est possible d'utiliser une classe de module en dehors de celui-ci. Pour que cela fonctionne, FuelPHP a besoin d'être configuré pour autocharger la classe quand vous y faites référence, dans votre code. Ceci signifie que vous devez indiquer à FuelPHP où trouver le module. Il y a deux façons de le faire. Vous pouvez précharger le module en spécifiant le module à charger dans le réglage 'always_load', 'modules' du fichier config.php de votre application.

'always_load' => array(

    /**
     * Ces modules sont toujours chargés au démarrage de Fuel. Vous pouvez          *les spécifier de la manière suivante:
     *
     * array('module_name');
     *
     * Un chemin doit être réglé dans les chemins de module pour que ça      * fonctionne.
     */
    'modules'   => array('mymodule'),

Vous pouvez également ajouter manuellement le module au démarrage, avant que vous utilisiez une des méthodes statiques :

// rend le module Mymodule accessible
Module::load('mymodule');
Vous appelez ensuite la classe de module comme ceci :
\Mymodule\Myclass::mymethod('params');

Installer des packages peut être fait manuellement ou via OilInstaller des packages avec Oil. Pour installer un package, il faut télécharger manuellement ses sources, et le copier dans le dossier des packages, qui est par défaut : fuel/packages.

Pour être en mesure d'utiliser un package installé, vous devez l'ajouter à always_load dans votre fichier app/config/config.php ou utiliser Package::load().

Les packages peuvent être téléchargés et installés manuellement. Grâce à la commande package, ces opérations peuvent être plus rapides. Cela fonctionne en recherchant les packages dans une liste de sources définies dans fuel/core/config/package.php qui peut être éditée comme tout autre fichier de configuration ou copiée depuis le dossier fuel/app/config.

Oil est intelligent, il va donc vérifier si vous avez Git installé sur votre ordinateur avant de faire quoi que ce soit. Si vous avez Git d'installé, Oil va installer un package comme un dépôt Git au lieu de directement télécharger les fichiers, rendant plus faciles les mises à jour, les nouvelles versions et le suivi de changement personnalisés dans le package.

12-2-1. Installation▲

$ php oil package install test-package
Downloading package: git://github.com/philsturgeon/fuel-test-package.git
remote: Counting objects: 13, done.
remote: Compressing objects: 100% (11/11), done.
remote: Total 13 (delta 3), reused 0 (delta 0)
Receiving objects: 100% (13/13), 10.85 KiB, done.
Resolving deltas: 100% (3/3), done.

Cloning into /Users/phil/Sites/fuel/fuel/packages/test-package...

$ php oil package install test-package --direct
    Downloading package: http://github.com/philsturgeon/fuel-test-package/zipball/master
    DOCROOT/fuel/packages/test-package/LICENSE.txt
    DOCROOT/fuel/packages/test-package/README
    DOCROOT/fuel/packages/test-package/classes/association.php
    DOCROOT/fuel/packages/test-package/classes/belongsto.php
    DOCROOT/fuel/packages/test-package/classes/exception.php
    DOCROOT/fuel/packages/test-package/classes/hasmany.php
    DOCROOT/fuel/packages/test-package/classes/hasone.php
    DOCROOT/fuel/packages/test-package/classes/model.php

12-2-2. Désinstallation▲

$ php oil package uninstall test-package
Uninstalling package "test-package"

Pour simplifier la compréhension des sources de votre application, il est mieux de structurer votre package comme ceci :

/packages
    /package
        /bootstrap.php
        /classes
            /vos.php
            /classes.php
            /ici.php
        /config
            /packageconfig.php
        /et cetera

Chaque package devrait avoir un fichier bootstrap.php placé à la base de celui-ci. Il faut utiliser le bootstrap pour ajouter le namespace du package (globalement si vous le voulez), puis y ajouter les classes pour de meilleures performances.

// ajout namespace, nécessaire si vous voulez que l'autoloader puisse trouver les classes
Autoloader::add_namespace('Mypackage', __DIR__.'/classes/');

// Ajout comme namespace de noyau
Autoloader::add_core_namespace('Mypackage');

// Ajout comme namespace de noyau (les classes sont aliasés au global, ainsi utilisables sans préfixe de namespace)
// fixe le second argument à true pour préfixer et pouvoir écraser les classes de noyau
Autoloader::add_core_namespace('Mypackage', true);

// et ajoute les classes, c'est utile pour :
// - optimisation : aucun chemin de recherche nécessaire
// - nécessaire pour pouvoir utiliser comme namespace de noyau
// - si vous voulez casser les règles de recherche de chemin de l'autoloader
Autoloader::add_classes(array(
    'Mypackage\\Classname' => __DIR__.'/classes/classname.php',
    'Mypackage\\Anotherclass' => __DIR__.'/classes/anotherclass.php',
));

Une fois vos classes en place, vous pouvez commencer à les utiliser.

// Si aliasé au global utilisez juste :
$instance = new Myclass;

// Quand non aliasé au global
$instance = new Mynamespace\Myclass;

Dans FuelPHP, il y a quatre routes réservées : _root_, _403_, _404_ et _500_.

• _root_ : La route par défaut quand aucune URI n'est spécifiée ;
• _403_ : la route utilisée quand une application lance une HttpNoAccessException qui n'est pas interceptée ;
• _404_ : la route utilisée quand une application lance une HttpNotFoundException qui n'est pas interceptée ;
• _500_ : la route utilisée quand une application lance une HttpServerErrorException qui n'est pas interceptée.

La classe requête lance une HttpNotFoundException, quand vous demandez une URI (une route) que votre application ne peut pas résoudre.

Si no _404_ route est défini, le framework utilise son propre handler d'erreur pour afficher un message « Page non trouvée ». Si no _403_ ou _500_ route est défini, ces exceptions restent non interceptées, et sont gérées comme toute autre exception que votre application devrait lever.

return array(
    '_root_'  => 'welcome/index',
    '_404_'   => 'welcome/404',
);

La route à gauche est comparée à la requête URI. Si une correspondance est trouvée,la requête est routée à l'URI sur la droite.

Ceci vous permet de faire des choses comme ci-dessous :

return array(
    'about'   => 'site/about',
    'contact' => 'contact/form',
    'admin'   => 'admin/login',
);

Vous pouvez inclure n'importe quel regex dans vos routes. La partie gauche est comparée à la requête URI, et la partie droite est le remplacement pour la gauche. Vous pouvez donc utiliser des références arrière dans la partie droite depuis le regex sur la gauche. Il y a aussi des déclarations spécifiques qui vous permettent de tout faire correspondre, ou seulement un segment :

• :any - cela fait correspondre quelque chose de ce point dans l'URI ;
• :segment - cela fait correspondre seulement un segment dans l'URI, mais ce segment peut être n'importe quoi ;
• :num - ceci fait correspondre n'importe quel nombre ;
• :alpha - ceci fait correspondre n'importe quel caractère alphabétique, incluant l'UTF-8 ;
• :alnum - ceci fait correspondre n'importe quel caractère alphanumérique, incluant l'UTF-8.

Voici quelques exemples :

return array(
    'blog/(:any)'      => 'blog/entry/$1', // Routes /blog/entry_name to /blog/entry/entry_name
    '(:segment)/about' => 'site/about/$1', // Routes /en/about to /site/about/en
    '(\d{2})/about'    => 'site/about/$1', // Routes /12/about to /site/about/12
);

Vous pouvez aussi avoir nommé les paramètres dans vos routes. Ceci vous permet de donner les noms dans vos segments URI, lesquels peuvent être accédés depuis l'intérieur de vos actions.

Exemple :

return array(
    'blog/:year/:month/:id' => 'blog/entry', // Routes /blog/2010/11/entry_name to /blog/entry
);

Dans l'exemple ci-dessus, on intercepte le nom blog/2010/11/entry. Il devrait ensuite router cette requête vers votre action 'entry' dans votre contrôleur 'blog'. Les paramètres nommés seront accessibles comme suit :

$this->param('year');
$this->param('month');
$this->param('id');

Notez que comme un paramètre nommé est une expression rationnelle (regex), chaque paramètre nommé est considéré comme une référence arrière. Donc dans une route comme ':name/(\d{2})',la référence arrière pour votre segment à deux chiffres est $2 et pas $1.

Vous pouvez router vos URL vers des contrôleurs et actions basées sur le mot clé HTTP utilisé pour les appeler. Ceci rend facile et rapide la conception de contrôleur RESTful.

Exemple :

return array(
    // Routes GET /blog to /blog/all and POST /blog to /blog/create
    'blog' => array(array('GET', new Route('blog/all')), array('POST', new Route('blog/create'))),
);

Vous pouvez utiliser les paramètres nommés et les regex dans vos URL :

return array(
    'blog/(:any)' => array(array('GET', new Route('blog/show/$1'))),
);

Vous pouvez aussi spécifier si cette route est prise en charge pour seulement HTTP, ou également HTTPS, en passant false ou true comme troisième paramètre :

// route seulement valide s'il s'agit d'une requête https
return array(
    'blog/(:any)' => array(array('GET', new Route('blog/show/$1'), true)),
);

L'idée de route inversée se présente comme ceci : supposez que vous ayez une zone d'administration et que vous avez une route paramétrée pour elle. Dans vos vues, vous voudriez en utilisant une ancre HTML que cette zone d'administration soit accessible via le lien 'admin/start/overview'. Maintenant, vous décidez de déplacer des choses autour et finir par bouger cette page spécifique vers 'admin/overview'. À la suite de cela maintenant, vous devez mettre à jour les liens dans toutes les vues.

Lorsque vous utilisez le routage inverse avec ces noms de route vous pouvez lier une ancre à une route nommée, de sorte que lors de changements de route, les liens dans vos vues suivent automatiquement le changement.

Exemple de route :

return array(
    'admin/start/overview' => array('admin/overview', 'name' => 'admin_overview'), // ajoute une route nommée pour la page admin/overview
);

Exemple d'ancre :

// produit <a href="http://your_base_url/admin/start/overview">Overview</a>
echo Html::anchor(Router::get('admin_overview'), 'Overview');

Notez que cela ne fonctionne actuellement que pour les routes qui sont définies dans app/config/routes.php, pas pour les routes de module.

Une route n'a pas à se résoudre à une méthode de contrôleur. FuelPHP prend également en charge les routes inline, lesquelles sont définies comme une « closure » qui remplace la méthode du contrôleur. Comme les méthodes de contrôleur, les routes inline doivent retourner un objet de réponse, soit en en fabriquant un manuellement, ou soit suite à l'exécution d'une requête fabriquée.

Exemple de route :

return array(
    'secret/mystuff' => function () {
        // cette route fonctionne seulement en développement
        if (\Fuel::$env == \Fuel::DEVELOPMENT)
        {
            return \Request::forge('secret/mystuff/keepout', false)->execute();
        }
        else
        {
            throw new HttpNotFoundException('Cette page est seulement accessible en développement.');
        }
};

Pour en savoir plus sur le routage de modulesRoutage de module

Par défaut, FuelPHP favorise l'encodage de sortie par le filtrage d'entrée. Il y a deux raisons à cela :

1. Plus de souci sur la provenance de vos données, et filtrage ou non, l'encodage de sortie sera assuré lors de la transmission au client ;
2. Cela veut aussi dire que toute entrée est stockée en brut, sans aucun traitement ; donc en cas de problème, vous avez toujours vos données originales.

Cela signifie aussi que vous n'aurez pas de problèmes quand vous aurez besoin de données en format brut, sans aucune mise en forme. Un exemple commun : les données produites par les éditeurs HTLM tels que TinyCME ou ckeditor, utilisés dans beaucoup d'applications avec édition de contenu par l'utilisateur final. Dans ce cas, vous voudrez peut-être lancer le filtrage XSS sur ces variables d'entrées pour filtrer toute mauvaise surprise qui pourrait être glissée puisque c'est un exemple typique de données non voulues dans la sortie encodée.

Puisque l'encodage de sortie ne peut se passer que sur les chaînes, vous devez prêter attention aux objets que vous voulez passer à vos vues. Assurez-vous que votre objet contient une méthode __toString(), sur laquelle l'encodage peut s'exécuter. Il faut aussi ajouter votre classe d'objet à la classe whitelist dans la configuration de sécurité, sans oublier le namespace. Vous pouvez aussi la passer à la vue avec le flag $encode positionné à false. Il est possible d'utiliser la méthode auto_encode pour désactiver temporairement l'encodage de sortie sur une base par vue.

Vous pouvez consulter la section sur la sécurité des vues pour voir comment mieux sécuriser vos vues.

14-1-1. Protection CSRF▲

// in plain HTML
<input type="hidden" name="<?php echo \Config::get('security.csrf_token_key');?>" value="<?php echo \Security::fetch_token();?>" />

// utilisation de la classe du formulaire
echo \Form::csrf();

// utilisation d'une instance de formulaire, va aussi rajouter la règle de validation dans le bloc de champs
$form = \Form::forge();
$form->add_csrf();

// contrôle si le formulaire a été soumis
if ($_POST)
{
    // contrôle la validité du jeton CSRF
    if ( ! \Security::check_token())
    {
        // attaque CSRF ou jeton CSRF expiré
    }
    else
    {
        // jeton valide, on peut traiter les entrées formulaire
    }
}

14-1-2. Filtrage XSS▲

14-1-3. Filtrage d'entrée▲

/**
 * réglages de sécurité
 */
'security' => array(
    'input_filter' => array(),
)

14-1-4. Injection SQL▲

Le système interne de gestion d'erreurs de FuelPHP est basé sur les exceptions. Ceci permet de les intercepter dans votre code. Votre application peut donc gérer les exceptions levées, et l'utilisateur peut continuer à utiliser l'application.

FuelPHP altère également le comportement par défaut de PHP, quand une erreur PHP se présente (qui ne sont pas des exceptions) depuis les anciennes fonctions procédurales. Au lieu de continuer après toutes les erreurs fatales, FuelPHP va envoyer une PhpErrorException sur toutes ces erreurs. Ceci vous forcera à résoudre toutes les erreurs, même une E_NOTICE que vous auriez éventuellement ignorée. Il vous permettra également d'intercepter les erreurs PHP. Par exemple, pour intercepter les erreurs de syntaxe dans les fichiers de vue quand celles-ci ont été créées par des non-programmeurs.

Vous pouvez échanger ce comportement en ajoutant les types d'erreurs PHP (comme E_NOTICE ou E_STRICT) à la clé errors.continue_on dans vos fichiers config/config.php d'application. Les erreurs définies ici autoriseront vos scripts à continuer. Aucune exception ne sera levée pour ces erreurs, vous pouvez donc ne plus les intercepter.

15-2-1. Erreur 404▲

15-2-2. Lancer un 404▲

throw new HttpNotFoundException;

// génère la requête, l'exécute, et envoie la sortie.
try
{
    $reponse = Request::forge()->execute()->response();
}
catch (HttpNotFoundException $e)
{
    $route = array_key_exists('_404_', Router::$routes) ? Router::$routes['_404_']->translation : Config::get('routes._404_');
    if ($route)
    {
        // ajoute 'false' à la requête fabriquée, désactive le moteur de routage
        $reponse = Request::forge($route, false)->execute()->response();
    }
    else
    {
        throw $e;
    }
}

15-2-3. Manipulation 404▲

// À l'intérieur du contrôleur_Welcome

/**
 * l'action 404 pour l'application.
 *
 * @access  public
 * @return  void
 */
public function action_404()
{
    $messages = array('Aw, crap!', 'Bloody Hell!', 'Uh Oh!', 'Nope, not here.', 'Huh?');
    $data['title'] = $messages[array_rand($messages)];

    // fixe un header HTTP 404 sur la sortie
    return Response::forge(Presenter::forge('welcome/404', $data), 404);
}

15-2-4. Tout intercepter▲

// À l'intérieur de votre contrôleur 404

public function action_my404()
{
    $original_uri = \Input::uri();
    $result = \DB::select()->from('pages')->where('uri', $original_uri)->execute();
    if(count($result) === 1)
    {
        // affiche cette page de quelque manière de votre choix
    }
    else
    {
        // affiche votre page générale 404
        $messages = array('Aw, crap!', 'Bloody Hell!', 'Uh Oh!', 'Nope, not here.', 'Huh?');
        $data['title'] = $messages[array_rand($messages)];
        return Response::forge(View::forge('welcome/404', $data), 404);
    }
}

15-2-5. Lancer une erreur 500▲

throw new HttpServerErrorException;

15-2-6. Lancer une erreur 403▲

throw new HttpNoAccessException;

15-2-7. Erreurs en mode CLI▲

Les tests unitaires sont des tests automatiques écrits, pour s'assurer qu'une unité de code (typiquement une fonction ou une méthode) fait ce pour quoi elle a été conçue. Ces tests aident également les développeurs à ne pas casser du code qui fonctionnait jusqu'à présent. Les tests unitaires sont également le cœur de métier de la discipline de « Test Driven Development » (TDD).

Vous aurez besoin d'avoir PHPUnit installé en local si vous voulez exécuter les tests fournis avec FuelPHP, et si vous voulez utiliser Oil pour exécuter vos tests. Si vous n'avez pas déjà installé PHPUnit, merci de vous référer à la documentation d'installation de PHPUnit à :https://phpunit.de/manual/current/en/installation.html.

Si vous n'êtes pas intéressé par l'exécution de tests unitaires avec FuelPHP, alors il n'y a aucune nécessité pour vous d'installer PHPUnit.

Dans l'utilitaire de ligne de commande inclus dans FuelPHP, Oil est déjà configuré pour exécuter vos tests unitaires. Vous pouvez exécuter tous les tests dans votre projet FuelPHP à partir de la ligne de commande en utilisant Oil comme suit :

$ php oil test

Tests Running...This may take a few moments.
PHPUnit 3.6.10 by Sebastian Bergmann.

Configuration read from /home/user/sites/example/fuel/core/phpunit.xml

...............................................................  63/251 ( 25%)
............................................................... 126/251 ( 50%)
............................................................... 189/251 ( 75%)
..............................................................

Time: 6 seconds, Memory: 22.25Mb

OK (251 tests, 206 assertions)

Dans FuelPHP, les scripts d'exécution des tests sont situés dans le dossier Fuel/app/tests et ses sous-répertoires. Si ce répertoire est inexistant, il faudra le créer. Par convention, les fichiers de tests sont placés dans le même sous-chemin de Fuel/app/tests tout comme la classe testée se trouve dans Fuel/app/classes, donc un test pour la classe Fuel/app/cours/modèle/login.php serait dans le fichier Fuel/app/tests/modèle/login.php.

Les tests sont des classes qui étendent la classe de TestCase. TestCase est l'extension FuelPHP de la classe PHPUnit_Framework_TestCase de PHPUnit, vous serez donc en mesure d'utiliser toutes les assertions et les méthodes habituelles de PHPUnit dans votre test. Par convention, les classes de test sont nommées après la classe qu'elles testent, préfixées par test_, donc un test pour la classe Model_Login serait nommé Test_Model_Login.

class Test_Model_Login extends TestCase
{
    public function test_foo()
    {
    }
}

Vous pouvez trouver plus d'informations sur l'écriture des tests dans la documentation de PHPUnit :

http://www.phpunit.de/manual/current/en/writing-tests-for-phpunit.html.

Si vous voulez exécuter uniquement un sous-ensemble de tests pendant la programmation, vous pouvez utiliser des groupes de tests. Pour cela, il faut lancer php oil test avec le switch de commande --group=.

$ php oil test --group=App

Cette commande va exécuter uniquement les tests du groupe 'App'. Vous pouvez attribuer une classe de test à un ou plusieurs groupes de tests avec l'attribut @group de docblock.

/**
 * @group App
 * @group Login
 */
class Test_Model_Login extends TestCase
{
    public function test_foo()
    {
    }
}

Si vous avez besoin de personnaliser le contenu du fichier phpunit.xml, copiez Fuel/core/phpunit.xml dans le répertoire Fuel/app. FuelPHP va reconnaître votre nouveau fichier de configuration à la place de l'ancien dans Fuel/core.

Si vous développez un grand système dans FuelPHP, la pratique recommandée est de développer des modules. Mais comme les chemins de module sont configurables, ceux-ci doivent être configurés dans phpunit.xml pour que les tests soient reconnus et exécutés. Par exemple, si vous développez des modules dans Fuel/app/modules, vous voudrez ajouter cette suite de tests dans votre configuration phpunit :

Si vous avez renommé votre répertoire FuelPHP, les variables système (document root, core path, etc.) définies dans le fichier phpunit.xml deviennent de mauvaises références. Bien que les modifications apportées aux chemins dans le script Oil de votre racine aideront les autres commandes de Oil, PHPUnit charge son propre environnement, donc un répertoire de Fuel renommé brisera les tests. Pour corriger cela, vous éditez la copie de phpunit.xml dans votre app/Directory, puis mettre à jour les chemins des variables du serveur pour tenir compte de votre nouvelle structure de fichier.

Le profileur fournit des informations relatives de profilage et de débogage sans ajouter beaucoup de lignes à votre code. Vous avez seulement besoin de basculer un paramètre de configuration sur true, qui vous donne accès à un outil automatisé pour aider à créer une expérience d'examen rapide et plus cohérente. Pour simplifier son utilisation, le profileur fournit l'emplacement du code avant l'examen.

Le profileur vous fournit une interface à onglets, dans laquelle vous pouvez trouver les informations suivantes :

• Console : c'est l'onglet par défaut qui donne des informations sur les erreurs, les entrées de log, l'utilisation de la mémoire et les temps d'exécution ;
• Load time : il s'agit du temps de charge. Il permet d'afficher les détails d'exécution dans le corps de l'onglet ;
• Database : cet onglet porte sur le nombre de requêtes exécutées, le temps d'exécution, et si pris en charge, une analyse de la requête ;
• Memory : c'est la crête de mémoire totale utilisée par la requête ;
• Files : il s'agit des noms complets (« full qualified ») des fichiers PHP inclus, et leur taille ;
• Config: c'est le contenu de la configuration stockée, à la fin de la requête ;
• Session : cet onglet indique le contenu de la session stockée, à la fin de la requête ;
• GET : il y est indiqué le contenu du tableau $_GET ;
• POST : il y est indiqué le contenu du tableau $_POST.

Un écran typique de profil ressemble à ceci :

Au bas de l'écran de profileur, vous trouverez trois options :

• Bottom : option, par défaut, dans laquelle le profileur est une surcouche. En cliquant sur cette option, le profileur se positionnera à la fin des sorties. Ce qui vous permet de visualiser toutes les sorties, le profileur va aller après la fin de votre sortie. Cliquez à nouveau et elle se déplacera en arrière ;
• Height : cette option permet de basculer entre un grand panneau (comme dans la capture d'écran) ou un petit panneau de profileur ;
• Details : change les détails de profileur. Si éteint, seule la barre d'onglet sera visible.

Le profilage de votre application est désactivé par défaut. Vous pouvez configurer FuelPHP pour activer le profileur via le fichier config/config.php de votre application :

'profiling'  => true,

Après l'activation du profileur, vous le verrez apparaître en bas de la fenêtre de votre navigateur.

Le profilage de base de données est désactivé par défaut également. Celui-ci est activé par base de données définie, et est activée en réglant l'option «profilage» à true au niveau de la configuration de base de données que vous souhaitez profiler dans votre config /<environnement>/db.php.

'profiling'  => true,

Consultez la documentation de la classe Profiler pour voir comment vous pouvez interagir avec le profileur.