Wiki - 1 output

Déclare une classe étendue par le trait ou l’interface.

/**
 * @extends Class_Name
 */
trait Extension_Trait

Cette annotation permet de déclarer les classes (ou traits ou interfaces) à étendre pour lesquelles le trait ou l’interface est conçue.

Cette déclaration n’a rien de limitative : le trait ou l’interface pourront être utilisés pour étendre d’autres traits, interfaces ou classes, sans avoir à compléter cette déclaration.

L’annotation peut être utilisée plusieurs fois pour le même trait / interface, pour indiquer qu’elle est conçue pour l’extension de plusieurs classes.

Paramètre

- Nom de la classe pour laquelle le trait ou l’interface est conçue.
- La classe doit être accessible depuis la définition : pensez à rajouter la clause use de fichier si nécessaire.
- Convention PhpStorm : Si la clause use de fichier ne sert qu’à la définition de @extends, PhpStorm détectera la clause use comme inutile. Pour éviter cela, et déclarer une référence à ce nom de classe, complétez la déclaration de classe avec l’annotation @see Class_Name.

Exemples

Déclaration simple

Le trait Person_Having_Name du framework est conçu pour être ajouté à toute classe utilisant Has_Name : il n’inclue pas de clause use de classe pour éviter tout conflit lors de l’assemblage de classe finale, mais l’annotation @extends permet de déclarer qu’il est conçu pour des objets qui utilisent également Has_Name :

<?php
namespace ITRocks\Framework\Address;
 
use ITRocks\Framework\Traits\Has_Name;
 
/**
 * Base trait for traits on Person applied on classes having Has_Name
 *
 * @extends Has_Name
 * @representative name
 */
trait Person_Having_Name
{
	use Person;
 
	//-------------------------------------------------------------------------------- setDefaultName
	/**
	 * Sets default name to first name + last name
	 */
	public function setDefaultName()
	{
		/** @var $self self|Has_Name */
		$self = $this;
		$name = trim($self->first_name . SP . $self->last_name);
		if (strlen($name)) {
			$self->name = $name;
		}
	}
 
}

Dans builder.php, on pourra donc enrichir par exemple la classe User en lui ajoutant un nom d’utilisateur avec Has_Name, plus Person_Having_Name pour cumuler prénom, nom de famille, et nom complet dont on peut changer le contenu ;

use ITRocks\Framework;
 
return [
	Framework\User::class => [
		Framework\Address\Person_Having_Name,
		Framework\Traits\Has_Name
	]
];

Cette déclaration a un effet principalement de documentation, afin que le mainteneur de l’application soit informé par le développeur d’origine qu’il est normal que dans le code on fasse référence à la propriété $name déclarée dans Has_Name alors qu’aucune utilisation du trait n’est déclarée en PHP pur.

Déclaration pour installation de fonctionnalité

Il est intéressant d’utiliser l’annotation @extends pour déclarer un trait qui enrichit une classe existante, cet enrichissement constituant une fonctionnalité utilisateur installable à part entière.

L’exemple ci-dessous déclare que toutes les classes qui utiliseront Person intégreront la civilité de cette personne, en plus de son nom et prénom.

<?php
namespace ITRocks\Framework\Address;
 
/**
 * @extends Person
 * @feature Person with civility
 * @see Person_Plugin
 */
trait Has_Civility
{
 
	//------------------------------------------------------------------------------------- $civility
	/**
	 * @link Object
	 * @var Civility
	 */
	public $civility;
 
}

Lors de l’installation de la fonctionnalité utilisateur, la section suivante sera ajoutée à builder.php, pas la simple association de l’annotation de classe @feature et de @extends :

	Framework\Address\Person::class => [
		Framework\Address\Has_Civility::class
	]