Page Contents

Classe App

class App

La classe App est responsable de la gestion des chemins, la classe de localisation et la classe de chargement. Assurez-vous que vous suivez les Conventions des Fichiers et des Noms de Classe.

Packages

CakePHP est organisé autour de l’idée de packages, chaque classe appartient à un package ou dossier où d’autres classes se trouvent. Vous pouvez configurer chaque localisation de package dans votre application en utilisant App::build('APackage/SubPackage', $paths) pour informer le framework où chaque classe doit être chargée. Presque toute classe dans le framework CakePHP peut être échangée avec une des vôtres compatible. Si vous souhaitez utiliser votre propre classe à la place des classes que le framework fournit, ajoutez seulement la classe à vos dossiers libs émulant la localisation du répertoire à partir duquel CakePHP s’attend à le trouver.

Par exemple, si vous voulez utiliser votre propre classe HttpSocket, mettez la sous:

app/Lib/Network/Http/HttpSocket.php

Une fois ceci fait, cette App va charger votre fichier à la place du fichier de l’intérieur de CakePHP.

Chargement des classes

static App::uses(string $class, string $package)
Type renvoyé:

void

Les classes sont chargées toutes seules dans CakePHP, cependant avant que l’autoloader puisse trouver vos classes que vous avez besoin de dire à App, où il peut trouver les fichiers. En disant à App dans quel package une classe peut être trouvée, il peut bien situer le fichier et le charger la première fois qu’une classe est utilisée.

Quelques exemples pour les types courants de classes sont:

Console Commands

App::uses('AppShell', 'Console/Command');

Console Tasks

App::uses('BakeTask', 'Console/Command/Task');

Controllers

App::uses('PostsController', 'Controller');

Components

App::uses('AuthComponent', 'Controller/Component');

Models

App::uses('MyModel', 'Model');

Behaviors

App::uses('TreeBehavior', 'Model/Behavior');

Views

App::uses('ThemeView', 'View');

Helpers

App::uses('HtmlHelper', 'View/Helper');

Libs

App::uses('PaymentProcessor', 'Lib');

Vendors

App::uses('Textile', 'Vendor');

Utilities

App::uses('CakeText', 'Utility');

Donc au fond, le deuxième paramètre devrait simplement correspondre au chemin du dossier de la classe de fichier dans core ou app.

Note

Charger des vendors signifie généralement que vous chargez des packages qui ne suivent pas les conventions. Pour la plupart des packages vendor, l’utilisation de App::import() est recommandée.

Chargement des fichiers à partir des plugins

Le chargement des classes dans les plugins fonctionne un peu de la même façon que le chargement des classes app et des classes du coeur sauf que vous devez spécifier le plugin à partir du quel vous chargez:

// Charge la classe Comment dans app/Plugin/PluginName/Model/Comment.php
App::uses('Comment', 'PluginName.Model');

// Charge la classe class CommentComponent dans app/Plugin/PluginName/Controller/Component/CommentComponent.php
App::uses('CommentComponent', 'PluginName.Controller/Component');

Trouver des chemins vers les packages en utilisant App::path()

static App::path(string $package, string $plugin = null)
Type renvoyé:

array

Utilisé pour lire les informations sur les chemins stockés:

// retourne les chemins de model dans votre application
App::path('Model');

Ceci peut être fait pour tous les packages qui font partie de votre application. Vous pouvez aussi récupérer des chemins pour un plugin:

// retourne les chemins de component dans DebugKit
App::path('Component', 'DebugKit');
static App::paths()
Type renvoyé:

array

Récupère tous les chemins chargés actuellement à partir de App. Utile pour inspecter ou stocker tous les chemins que App connait. Pour un chemin vers un package spécifique, utilisez App::path().

static App::core(string $package)
Type renvoyé:

array

Utilisé pour trouver le chemin vers un package à l’intérieur de CakePHP:

// Récupère le chemin vers les moteurs de Cache.
App::core('Cache/Engine');
static App::location(string $className)
Type renvoyé:

string

Retourne le nom du package d’où une classe a été localisée.

Ajoutez des chemins dans App pour trouver des packages

static App::build(array $paths = array(), mixed $mode = App::PREPEND)
Type renvoyé:

void

Définit chaque localisation de package dans le système de fichier. Vous pouvez configurer des chemins de recherche multiples pour chaque package, ceux-ci vont être utilisés pour rechercher les fichiers, un dossier à la fois, dans l’ordre spécifié. Tous les chemins devraient être terminés par un séparateur de répertoire.

Ajouter des chemins de controller supplémentaires pourraient par exemple modifier où CakePHP regarde pour les controllers. Cela vous permet de séparer votre application à travers le système de fichier.

Utilisation:

//Va configurer un nouveau chemin de recherche pour le package Model
App::build(array('Model' => array('/a/full/path/to/models/')));

//Va configurer le chemin comme le seule chemin valide pour chercher les models
App::build(array('Model' => array('/path/to/models/')), App::RESET);

//Va configurer les chemins de recherche multiple pour les helpers
App::build(array('View/Helper' => array('/path/to/helpers/', '/another/path/')));

Si reset est défini à true, tous les plugins chargés seront oubliés et ils devront être rechargés.

Exemples:

App::build(array('controllers' => array('/full/path/to/controllers/')))
//devient
App::build(array('Controller' => array('/full/path/to/Controller/')))

App::build(array('helpers' => array('/full/path/to/views/helpers/')))
//devient
App::build(array('View/Helper' => array('/full/path/to/View/Helper/')))

Modifié dans la version 2.0: App::build() ne va plus fusionner les chemins de app avec les chemins du coeur.

Ajoutez de nouveaux packages vers une application

App::build() peut être utilisé pour ajouter de nouvelles localisations de package. Ceci est utile quand vous voulez ajouter de nouveaux packages de niveaux supérieurs ou, des sous-packages à votre application:

App::build(array(
    'Service' => array('%s' . 'Service' . DS)
), App::REGISTER);

Le %s dans les packages nouvellement enregistrés, sera remplacé par le chemin APP. Vous devez inclure un trailing / dans les packages enregistrés. Une fois que les packages sont enregistrés, vous pouvez utiliser App::build() pour ajouter/préfixer/remettre les chemins comme dans tout autre package.

Modifié dans la version 2.1: Les packages enregistrés a été ajouté dans 2.1

Trouver les objets que CakePHP connaît

static App::objects(string $type, mixed $path = null, boolean $cache = true)
Type renvoyé:

mixed Retourne un tableau d'objets du type donné ou à false si incorrect

Vous pouvez trouver quels objets App connaît en utilisant App::objects('Controller') par exemple pour trouver quels controllers de l’application App connaît.

Exemple d’utilisation:

//retourne array('DebugKit', 'Blog', 'User');
App::objects('plugin');

//retourne array('PagesController', 'BlogController');
App::objects('Controller');

Vous pouvez aussi chercher seulement dans les objets de plugin en utilisant la syntaxe de plugin avec les points:

// retourne array('MyPluginPost', 'MyPluginComment');
App::objects('MyPlugin.Model');

Modifié dans la version 2.0.

  1. Retourne array() au lieu de false pour les résultats vides ou les types invalides.

  2. Ne retourne plus les objets du coeur, App::objects('core') retournera array().

  3. Retourne le nom de classe complet.

Localiser les plugins

static App::pluginPath(string $plugin)
Type renvoyé:

string

Les Plugins peuvent être localisés aussi avec App. En utilisant App::pluginPath('DebugKit'); par exemple, vous donnera le chemin complet vers le plugin DebugKit:

$path = App::pluginPath('DebugKit');

Localiser les thèmes

static App::themePath(string $theme)
Type renvoyé:

string

Les Thèmes peuvent être trouvés App::themePath('purple');, vous donnerait le chemin complet vers le thème purple.

Inclure les fichiers avec App::import()

static App::import(mixed $type = null, string $name = null, mixed $parent = true, array $search = array(), string $file = null, boolean $return = false)
Type renvoyé:

boolean

Au premier coup d’œil, App::import a l’air compliqué, cependant pour la plupart des utilisations, seuls 2 arguments sont nécessaires.

Note

Cette méthode est équivalente à faire un require sur le fichier. Il est important de réaliser que la classe doit ensuite être initialisée.

// La même chose que require('Controller/UsersController.php');
App::import('Controller', 'Users');

// Nous avons besoin de charger la classe
$Users = new UsersController;

// Si nous voulons que les associations de model, les components, etc
soient chargées
$Users->constructClasses();

Toutes les classes qui sont chargées dans le passé utilisant App::import(“Core”, $class) devront être chargées en utilisant App::uses() se référant au bon package. Ce changement a fourni de grands gains de performances au framework.

Modifié dans la version 2.0.

  • Cette méthode ne regarde plus les classes de façon récursive, elle utilise strictement les valeurs pour les chemins définis dans App::build().

  • Elle ne sera pas capable de charger App::import('Component', 'Component'), utilisez App::uses('Component', 'Controller');.

  • Utilisez App::import('Lib', 'CoreClass'); pour charger les classes du coeur n’est plus possible.

  • Importer un fichier non existant, fournir un mauvais type ou un mauvais nom de package, ou des valeurs null pour les paramètres $name et $file entraînera une valeur de retour à false.

  • App::import('Core', 'CoreClass') n’est plus supporté, utilisez App::uses() à la place et laissez la classe d’autochargement faire le reste.

  • Charger des fichiers de Chargement ne regarde pas de façon récursive dans le dossier vendors, il ne convertira plus aussi le fichier avec des underscores comme il le faisait dans le passé.

Surcharger les classes dans CakePHP

Vous pouvez surcharger presque toute classe dans le framework, les exceptions sont les classes App et Configure. Quelque soit le moment où vous souhaitez effectuer l’écrasement, ajoutez seulement votre classe dans votre dossier app/Lib en imitant la structure interne du framework. Quelques exemples suivants

  • Pour écraser la classe Dispatcher, créer app/Lib/Routing/Dispatcher.php.

  • Pour écraser la classe CakeRoute, créer app/Lib/Routing/Route/CakeRoute.php.

  • Pour écraser la classe Model, créer app/Lib/Model/Model.php.

Quand vous chargez les fichiers remplacés, les fichiers de app/Lib seront chargés à la place des classes intégrées au coeur.

Charger des fichiers Vendor

Vous pouvez utiliser App::uses() pour charger des classes provenant des répertoires vendors. Elle suit les mêmes conventions que pour le chargement des autres fichiers:

// Charge la classe Geshi dans app/Vendor/Geshi.php
App::uses('Geshi', 'Vendor');

Pour charger les classes se trouvant dans des sous-répertoires, vous devrez ajouter ces chemins avec App::build():

// Charge la classe ClassInSomePackage dans app/Vendor/SomePackage/ClassInSomePackage.php
App::build(array('Vendor' => array(APP . 'Vendor' . DS . 'SomePackage' . DS)));
App::uses('ClassInSomePackage', 'Vendor');

Vos fichiers vendor ne suivent peut-être pas les conventions, ont une classe qui diffère du nom de fichier ou ne contiennent pas de classes. Vous pouvez charger ces fichiers en utilisant App::import(). Les exemples suivants montrent comment charger les fichiers de vendor à partir d’un certain nombre de structures de chemin. Ces fichiers vendor pourraient être localisés dans n’importe quel dossier vendor.

Pour charger app/Vendor/geshi.php:

App::import('Vendor', 'geshi');

Note

Le nom du fichier geshi doit être en minuscule puisque CakePHP ne le trouvera pas sinon.

Pour charger app/Vendor/flickr/flickr.php:

App::import('Vendor', 'flickr/flickr');

Pour charger app/Vendor/some.name.php:

App::import('Vendor', 'SomeName', array('file' => 'some.name.php'));

Pour charger app/Vendor/services/well.named.php:

App::import('Vendor', 'WellNamed', array('file' => 'services' . DS . 'well.named.php'));

Cela ne ferait pas de différence si vos fichiers vendor étaient à l’intérieur du répertoire /vendors. CakePHP le trouvera automatiquement.

Pour charger vendors/vendorName/libFile.php:

App::import('Vendor', 'aUniqueIdentifier', array('file' => 'vendorName' .DS . 'libFile.php'));

Les Méthodes Init/Load/Shutdown de App

static App::init()
Type renvoyé:

void

Initialise le cache pour App, enregistre une fonction shutdown (fermeture).

static App::load(string $className)
Type renvoyé:

boolean

Méthode pour la gestion automatique des classes. Elle cherchera chaque package de classe défini en utilisant App::uses() et avec cette information, elle va transformer le nom du package en un chemin complet pour charger la classe. Le nom de fichier pour chaque classe devrait suivre le nom de classe. Par exemple, si une classe est nommée MyCustomClass le nom de fichier devrait être MyCustomClass.php.

static App::shutdown()
Type renvoyé:

void

Destructeur de l’Objet. Ecrit le fichier de cache si les changements ont été faits à $_map.