Wiki - 1 output

/**
 * @setter
 * @setter setProperty
 * @setter Another_Class::setProperty
 * @setter self::setProperty
 * @setter static::setProperty
 */
public $property;

L’annotation @setter, appliquée à une propriété, permet de demander l’appel d’une méthode à chaque fois que le programme veut écrire la valeur de la propriété, en remplacement de cette écriture.

Si aucun nom de méthode setter n’est indiqué, c’est la méthode setProperty() qui sera implicitement considérée comme setter. Remplacer Property dans le nom de la méthode par le nom de la propriété, normalisé en nom de méthode. Autre exemple : pour une propriété $property_name , le nom de la méthode setter par défaut sera setPropertyName() .

Paramètres de la méthode appelée

• $value ou $nom_propriete (remplacer par le nom de la propriété), contenant la valeur affectée. Si $nom_propriete est un nom réservé pour les paramètres parmi ceux de cette liste, elle ne pourra pas être utilisée ici, préférez $value dans ce cas.
• $object : l’objet dont on affecte la propriété. Notamment utile en cas d’appel à une méthode externe à l’objet.
• $property : la propriété affectée, objet de classe Reflection_Property.
• $property_name : le nom de la propriété affectée.
• $stored : la valeur de la propriété avant affectation. Ce paramètre peut être passé par référence : si la valeur est modifiée, c’est la valeur stockée de la propriété qui sera modifiée.
• $type : le type de la propriété affectée, objet de classe Type (peut représenter un tableau).
• element_type : le type élémentaire de la propriété affectée, objet de classe Type (représentera le type de l’élément si la propriété est de type tableau []).
• $type_name : le nom du type de la propriété affectée, valeur de l’annotation var (peut contenir les caractères []).
• $element_type_name : le nom de l’élément pour la propriété affectée, valeur de l’annotation var (sans [] si multiple).
• $class_name : le nom de la classe pour la propriété affectée, valeur de l’annotation var (sans [] si multiple).
• $joinpoint : le point de jointure de classe Write_Property, à usage interne, les setters étant gérés par le module AOP du Framework.

Valeur de retour de la méthode appelée

Si la méthode appelée retourne une valeur, cette valeur sera stockée comme nouvelle valeur de la propriété.

Exemple

Dans ce wiki lorsqu’on modifie le titre d’un article, le logiciel recalcule l’URI qui permettra d’y accéder.
Nous voulons que lorsqu’on affecte – par exemple – la valeur “Nom de l’article” à Article::$title, Article::$uri prenne automatiquement la valeur “nom-de-l-article”.

Le code de la classe Article utilise donc un @setter dans cette optique :

class Article
{
 
	/**
	 * @setter
	 * @var string
	 */
	public $title;
 
	/**
	 * @var string
	 */
	public $uri;
 
	/**
	 * @param $title string
	 * @return string
	 */
	protected function setTitle($title)
	{
		$this->title = $title;
		$this->uri = strUri($title);
	}
 
}

• Soit $article un objet de classe Article , si dans le logiciel on modifie la valeur de sa propriété $title , par exemple en appelant $article->title = "Nom de l'article", la valeur ne sera en fait pas modifiée et la méthode setTitle sera appelée à la place de cette affectation. L’écriture $article->title = "Nom de l'article" équivaudra à $article->setTitle("Nom de l'article") .
• La méthode setter peut – et même doit, en terme de bonnes pratiques – rester privée : elle n’est pas conçue pour être appelée explicitement dans le programme, mais implicitement au moment d’une affectation.
• Le paramètre de la méthode setter, ici $title , sera la valeur que le développeur a utilisé pour son affectation.
• Dans la méthode, on réalise l’affectation manuellement avec $this->title = $title . En effet lorsqu’on appelle un setter, celui-ci remplace l’affectation, que nous ne sommes au final pas obligé de réaliser. Ici on veut bien stocker le titre dans $this->title , simplement on souhaite faire autre chose. A noter que l’affectation dans le setter n’est pas récursif : le setter ne sera pas rappelé dans ce contexte, ni dans toute autre fonction appelée par le setter, pour la propriété $title de l’objet $this .