Wiki - 1 output

/**
 * @default getPropertyDefault
 * @default Another_Class::getPropertyDefault
 * @default self::getPropertyDefault
 * @default static::getPropertyDefault
 */
public $property;

L’annotation @default, appliquée à une propriété, permet de demander l’appel d’une méthode renvoyant une valeur pour défaut pour cette propriété au moment de la construction de l’objet.

C’est une facilité syntaxique équivalent à un appel dans le constructeur, en plus court.

Paramètres de la méthode appelée

La méthode appelée peut, optionnellement, embarquer le paramètre suivant :
Interfaces\Reflection_Property $property : le nommage est sans importance. La classe de l’objet qui sera envoyé en paramètre devra être cette interface, et pas une de ses implémentations, pour assurer la compatibilité d’appel avec PHP\Reflection_Property ou un Reflection\Reflection_Property (ou toute autre implémentation).

Ce paramètre sera utile si votre méthode d’assignation de valeur par défaut est indépendante de la propriété, mais a besoin des caractéristiques de cette propriété pour calculer la valeur par défaut.

Valeur de retour de la méthode appelée

La valeur retournée par la méthode sera la valeur affectée à la propriété comme valeur par défaut.

Exemples

Exemple minimal

class A_Class
{
 
	/**
	 * @default getPropertyDefault
	 * @var string
	 */
	public $property;
 
	public function getPropertyDefault()
	{
		return 'Robert';
	}
 
}

Lors de l’appel d’une méthode dans la classe courante, la méthode doit être non statique et sera appelée dans le contexte de l’objet courant.

Le code ci-dessus est équivalent à :

class A_Class
{
 
	/**
	 * @var string
	 */
	public $property;
 
	public function __construct()
	{
		if (!isset($this->property)) {
			$this->property = $this->getPropertyDefault();
		}
	}
 
	public function getPropertyDefault()
	{
		return 'Robert';
	}
 
}

S’agissant d’une valeur statique ici, le cas est donné pour l’exemple. Le plus simple aurait bien sûr était d’écrire cet autre équivalent :

class A_Class
{
 
	/**
	 * @var string
	 */
	public $property = 'Robert';
 
}

Exemples avec des méthodes externes communes

Des méthodes statiques externes peuvent être appelées pour indiquer une valeur par défaut calculée.

L’exemple le plus courant, pour qu’une propriété prenne comme valeur la date du jour par défaut :

use ITRocks\Framework\Tools\Date_Time;
 
class A_Class
{
 
	/**
	 * @default Date_Time::today
	 * @link DateTime
	 * @var Date_Time
	 */
	public $my_date;
 
}

Également couramment utilisé, pour avoir la date+heure courante au moment de la création de l’objet : Date_Time::now .

Exemple d’appel hors classe (le plus complet)

Soit une classe :

class A_Class
{
 
	/**
	 * @default Another_Class::getDefault
	 * @var string
	 */
	public $property;
 
}

Lorsqu’un objet est instancié pour cette classe, la méthode suivante de Another_Class sera appelée :

use ITRocks\Framework\Locale\Loc;
use ITRocks\Framework\Reflection\Interfaces\Reflection_Property;
 
class Another_Class
{
 
	public static getDefault(Reflection_Property $property)
	{
		// exemple d'implémentation de création dynamique d'une valeur par défaut
		// appelé pour $property, renverra traduit en français cette valeur :
		// 'une propriété par défaut'
		// traductions nécessaires :
		// ['a default :0' => 'une :0 par défaut', 'property' => 'propriété']
		return Loc::tr('a default :0', [Display::propertyToDisplay($property->name)]);
	}
 
}

Cas particuliers

L’appel à la méthode n’a lieu que lors de la construction d’un objet lorsque $property est vide : si $property contient une valeur, issue par exemple d’une dé-sérialisation, d’une lecture depuis une base de données, ou d’une affectation de valeur par défaut programmée en php (public $property = 'another_default_value';), la méthode ne sera pas appelée.

Limitations

Si vous appliquez l’annotation @default a une propriété qui a déjà une valeur par défaut en PHP, et que cette valeur n’est pas null, celle-ci sera la valeur par défaut et la méthode ne sera jamais appelée.

Exemples :

class Default_Extended
{
 
	/**
	 * @var integer
	 */
	public $age = 18;
 
	/**
	 * @var integer
	 */
	public $null_age = null;
 
}
 
/**
 * @override age @default Default_Simple::defaultAge
 * @override null_age @default Default_Simple::defaultAge
 */
class Default_Simple extends Default_Extended
{
 
	/**
	 * @return integer
	 */
	protected function defaultAge()
	{
		return 43;
	}
 
}
 
$object = new Default_Simple();
echo $object->age . BRLF;
echo $object->null_age . BRLF;

Le résultat sera :

18
43

La valeur par défaut de $age étant 18 (non null) à l’origine, elle prévaut sur @default, même après un @override. La valeur par défaut retenue est donc 18 .

Par contre la valeur par défaut de $null_age est null : la récupération dynamique de valeur par défaut du @override est donc prioritaire, qu’elle soit définie directement dans la déclaration de la propriété ou par un @override. La valeur par défaut retenue est donc 43 .