Annotations

Les annotations permettent d’attribuer des fonctionnalités ou règles de gestions aux classes, méthodes et propriétés.

D’écriture inspirée des annotations PhpDocumentor, elles sont inscrites dans le bloc phpdoc qui précède la déclaration annotée.
Certaines annotations sont communes avec PhpDocumentor, et apportent du sens au code au delà de sa simplement documentation : c’est le cas par exemple de l’annotation @var qui indique le type d’une propriété, information utile à PhpDocumentor, à l’IDE pour la complétion automatique, et à it.rocks pour attribuer les règles de traitement de la propriété pour les accès AOP, les vues et autres traitements standard.

Exemple de déclaration utilisant des annotations : la classe ITRocks\Framework\User\Account

<?php
namespace ITRocks\Framework\User;
 
/**
 * An account can connect to an application (or to anything that needs authentication)
 *
 * It has a login, a password, and an email for password recovery automation.
 */
trait Account
{
 
	/**
	 * @mandatory
	 * @var string
	 */
	public $email;
 
	/**
	 * @mandatory
	 * @var string
	 */
	public $login;
 
	/**
	 * @mandatory
	 * @password sha1
	 * @var string
	 */
	public $password;
 
	/**
	 * @return string
	 */
	public function __toString()
	{
		return strval($this->login);
	}
 
}

Annotations des classes

  • @after_commit : défini une méthode à exécuter juste après l’enregistrement d’un objet
  • @after_read : défini une méthode à exécuter juste après la lecture d’un objet
  • @after_transform : défini une méthode à exécuter juste après la création par transformation d’un objet
  • @after_write : défini une méthode à exécuter juste après l’écriture d’un objet
  • @before_build_array : défini une méthode à exécuter juste avant la transformation d’un tableau de formulaire en objet
  • @before_delete : défini une méthode à exécuter juste avant la suppression d’un objet dans un lien de données
  • @before_write : défini une méthode à exécuter juste avant l’écriture d’un objet
  • @business : indique que la classe ou le trait décrit un objet métier
  • @default_feature : force la fonctionnalité par défaut à exécuter pour l’objet métier, si autre que output
  • @deprecated : indique que la classe est dépréciée et ne devrait plus être utilisée
  • @display_order : défini un ordre de base pour l’affichage des propriétés d’un objet
  • @duplicate : défini une méthode à exécuter juste après la duplication d’un objet
  • @extends : le trait est conçu pour hériter de cette liste de classe / traits
  • @feature : indique la ou les fonctionnalités disponibles pour l’objet métier
  • @filters : defini une méthode de filtrage pour la classe
  • @group : regroupe une liste de propriétés sous un nom et dans un ordre donnés
  • @groups_order : défini l’ordre d’importance des groupes définis par @group
  • @implements : le trait est conçu pour implémenter cette liste d’interfaces
  • @link : défini la classe courante comme étant une classe de lien, liée à la classe liée parente indiquée
  • @list : défini les propriétés de classe à afficher par défaut dans la liste donnée
  • @on_data_list : indique une méthode à exécuter lors de l’appel à Dao::select()
  • @override : redéfini des annotations pour une propriété donnée de la classe
  • @representative : indique la liste des propriétés dont les valeurs sont représentatives de l’objet
  • @set : indique le nom de la classe collection d’objets de cette classe
  • @sort : indique les propriétés pour l’ordre de tri par défaut des collections d’objets de cette classe
  • @stored : indique que la classe décrit un objet qui peut être stocké dans un lien de données
  • @unique : liste des propriétés qui constituent la clé primaire unique pour les classes @link
  • @use : indique que l’interface est prévue pour des classes qui utilisent cette liste de traits
  • @validate : indique une méthode appelée pour valider la valeur de l’objet (nécessite l’activation du plugin Validate)

Annotations des méthodes

  • @advice : indique que la méthode est un greffon AOP
  • @deprecated : indique que la méthode est dépréciée et ne devrait plus être utilisée
  • @return : la valeur retournée par la fonction sera du type indiqué

Annotations des propriétés

  • @after_add_element : indique la méthode à appeler après qu’un nouvel élément de Collection / Map soit enregistré
  • @alias : défini un alias au nom de la propriété, destiné à l’affichage
  • @before_add_element : indique la méthode à appeler avant qu’un nouvel élément de Collection / Map soit enregistré
  • @before_remove_element : indique la méthode à appeler avant qu’un élément de Collection / Map soit supprimé
  • @binary : la valeur sera stockée sous forme binaire dans le lien de données
  • @block : permet de regrouper les propriétés dans un même bloc
  • @calculated : la propriété contient une donnée calculée
  • @component : la propriété est un composant indissociable de son composé
  • @composite : la propriété indique l’objet composite dont l’objet est composant
  • @conditions : la propriété n’est accessible que si ces conditions sont respectées
  • @dao : la valeur de la propriété sera toujours stockée en utilisant le lien de données indiqué
  • @default : indique la méthode à appeler pour calculer la valeur par défaut de la propriété
  • @deprecated : la propriété est dépréciée et ne devrait plus être utilisée
  • @display_order : défini l’ordre d’affichage des propriétés
  • @editor : autorise l’utilisation d’un éditeur de texte en ligne
  • @feature : décrit une fonctionnalité de l’objet métier basée sur des modifications d’annotations de la propriété
  • @filters : la liste des valeurs possibles est filtrée en fonction de la valeur de ces autres propriétés
  • @foreign : indique quelle propriété de l’objet lié contient l’objet de classe courante
  • @foreignlink : indique le nom de la propriété dans la table de lien virtuelle qui contient l’objet lié
  • @getter : la méthode indiquée doit être utilisée pour lire la valeur de la propriété
  • @group : indique dans quel groupe la propriété doit être classée
  • @impacts : déclare quelles sont les propriétés impactées par toutes modifications sur la valeur de la propriété
  • @integrated : l’objet lié est à intégrer dans l’objet courant dans les vues
  • @length : la valeur de la propriété doit faire exactement ce nombre de caractères
  • @link : pour une propriété objet(s) stocké(s), précise le type de lien
  • @mandatory : la valeur de la propriété est obligatoire pour que l’objet soit valide
  • @max_length : longueur maximale en nombre de caractères pour la valeur de la propriété
  • @max_value : valeur maximale pour la valeur de la propriété
  • @min_length : longueur maximale en nombre de caractères pour la valeur de la propriété
  • @min_value : valeur minimale pour la valeur de la propriété
  • @multiline : la propriété de type texte string peut contenir des caractères retour à la ligne
  • @null : la valeur de la propriété vide est à conserver avec la valeur null
  • @output : la valeur de la propriété sera affichée et modifiée sous forme de chaîne de caractères
  • @override : indique que la propriété est une surcharge de la même propriété dans une classe parente
  • @password : la propriété sert à stocker un mot de passe
  • @placeholder : defini un placeholder pour la propriété
  • @precision : nombre de chiffres après la virgule autorisés pour un nombre à virgule
  • @read_only : la valeur de la propriété est disponible en lecture seule
  • @remover : défini la méthode à appeler pour retirer l’objet composant d’une classe composite
  • @replace_filter : la propriété est utilisée pour filtrer les objets proposés pour le supprime et remplace
  • @replaces : la propriété remplace une autre propriété d’une classe parente
  • @representative : indique la liste des propriétés de l’objet tiers dont les valeurs sont représentatives
  • @search_range : indiquer la valeur false pour cette annotation désactive les possibités de recherche de plages min-max
  • @set_store_name : force le nom de l’espace de stockage (table) à utiliser pour la table de lien implicite
  • @setter : la méthode indiquée doit être utilisée pour écrire la valeur de la propriété
  • @show_seconds : la valeur de la propriété de type Date_Type s’affichera avec les secondes
  • @signed : la valeur numérique peut être négative
  • @storage : force le nom du champ stocké dans le lien de données pour la propriété
  • @store : l’objet valeur de cette propriété sera stockée sous forme sérialisée
  • @textile : la valeur texte sera stockée sous format mis en forme textile
  • @tooltip : défini le tooltip d’une propriété de champ de formulaire
  • @user : défini l’accessibilité de la propriété pour l’utilisateur final : lecture seule, invisible
  • @user_change : indique une méthode à exécuter lorsque la valeur de propriété est modifiée par un utilisateur
  • @user_default : indique une méthode qui retourne la valeur par défaut de la propriété dans les formulaires
  • @user_getter : la méthode indiquée doit être utilisée pour lire la valeur destinée à l’affichage
  • @validate : indique une méthode appelée pour valider la valeur de la propriété (nécessite l’activation du plugin Validate)
  • @values : les valeurs possibles pour une propriété de type chaîne de caractères string
  • @var : défini le type de donnée pour la propriété
  • @widget : indique quelle classe widget utiliser pour afficher / modifier la valeur de l’objet
Montrer l'historique