Wiki - 1 output

Notifications

Welcome into the it.rocks framework wiki.

Connected user

Annotation de classe @before_write
add

Annotation de classe @before_write

Close

Événement déclenché avant l’écriture d’un objet de la classe
```
/**
 * @before_write [callable]
 */
class A_Name
```
Cette annotation indique à l’objet lien de données qu’il devra appeler la méthode indiquée avant chaque écriture d’un objet de la classe.

Vous pouvez donc exécuter par exemple le calcul de données avant l’écriture par ce biais, ou tout autre traitement de votre choix.

Cette méthode peut être dans la même classe, ou dans une classe tierce.
- Si la méthode est dans la même classe, elle est appelée dans le contexte de l’objet qui va être écrit par le lien de données.
Le lien de donnée et les options qui vont être utilisées pour la lecture sont envoyées comme paramètres à la méthode.
- Si la méthode est dans une classe tierce, il doit s’agir d’une méthode statique dont le premier paramètre sera l’objet qui va être écrit, et les paramètre suivants le lien de données puis un tableau contenant les options qui vont être utilisées pour la lecture.
- La méthode doit être publique, bien qu’elle ne soit pas conçue pour être appelée autrement que par le contrôleur d’appel qui exploite @before_write.
- Convention PhpStorm : pour éviter l’alerte d’inspection unused element, utilisez l’annotation @noinspection PhpUnused @after_write

La méthode appelée retourne un tableau contenant les noms des propriétés à écrire dans le cas où l’écriture ait été restreinte par une option Only. Si vous avez modifié des valeurs à écrire mais qu’une restriction Only a été utilisée lors de l’appel à la méthode Data_Link::write (), il est nécessaire d’indiquer le nom des propriétés correspondantes. Dans le cas contraire l’écriture de ces valeurs n’aura pas lieu.

Valeurs de retour

- Aucune valeur de retour ou true : la chaîne d’appels des événements se poursuit normalement
- false : la chaîne d’appels sera interrompue, et l’objet ne sera pas enregistré (voir plus loin).

Exemples

Sans la même classe

Dans l’exemple ci-dessous, la méthode appelée est dans la même classe.
Un texte apparaîtra avant chaque enregistrement d’un objet de classe Car , à remplacer par tout traitement de votre choix.
```
namespace ITRocks\Examples\Before_Write;
 
use ITRocks\Framework\Dao\Data_Link;
use ITRocks\Framework\Dao\Option;
 
/**
 * A car business object example
 *
 * @before_write beforeWriteCar
 */
class Car
{
 
	/**
	 * @var string
	 */
	public $color;
 
	/**
	 * @noinspection PhpUnused @before_write
	 * @param $link    Data_Link
	 * @param $options Option[]
	 */
	public function beforeWriteCar(Data_Link $link, array $options)
	{
		// Do what you have to do before each write of a car here
		echo "Doing things inside Car" . BR;
	}
 
	/**
	 * @return string
	 */
	public function __toString() : string
	{
		return $this->color . SP . "car";
	}
 
}
```
Dans une classe tierce

Dans cet autre exemple, la méthode appelée est dans une autre classe, et obligatoirement statique.

La classe métier :
```
namespace ITRocks\Examples\Before_Write;
 
/**
 * A car business object example
 *
 * @before_write Before_Write_Class::beforeWriteCar
 */
class Car
{
 
	/**
	 * @var string
	 */
	public $color;
 
}
```
La méthode est appelée de manière statique dans la classe tierce Before_Write_Class :
```
namespace ITRocks\Examples\Before_Write;
 
use ITRocks\Framework\Dao\Data_Link;
use ITRocks\Framework\Dao\Option;
 
/**
 * This class stores things done before writes calls
 */
class Before_Write_Class
{
 
	/**
	 * @noinspection PhpUnused Car::@before_write
	 * @param $car     Car
	 * @param $link    Data_Link
	 * @param $options Option[]
	 */
	public static function beforeWriteCar(Car $car, Data_Link $link, array $options)
	{
		// Do what you have to do before each write of a car here
		echo "Doing things outside Car" . BR;
	}
 
}
```
Forcer l’écriture d’une valeur

Modifiez la classe Car :
```
// (...)
/**
 * A car business object example
 *
 * @before_write Before_Write_Color_Class::beforeWriteCar
 */
class Car
// (...)
```
La classe statique dont on va appeler la méthode :
```
namespace ITRocks\Examples\Before_Write;
 
/**
 * This class stores things done before writes calls
 */
class Before_Write_Color_Class
{
 
	/**
	 * @noinspection PhpUnused Car::@before_write
	 * @param $car Car
	 * @return string[]
	 */
	public static function beforeWriteCar(Car $car) : array
	{
		$car->color = 'red';
		return ['color']
	}
 
}
```
Ici la classe tierce va systématiquement forcer la couleur de la voiture à “rouge” à chaque enregistrement.
La propriété modifiée est retournée, ainsi même si on enregistre une voiture avec une restriction Only et sans avoir inclus la propriété color la valeur forcée srea enregistrée. Un autre exemple de code concret se trouve dans le code du trait utilitaire Date_Logged fourni dans le Framework.

Écriture compacte

Si aucun nom de méthode n’est indiqué, la méthode appelée sera beforeWrite() de la classe.
Exemple de classe métier :
```
namespace ITRocks\Examples\Before_Write;
 
/**
 * A simple car business class example
 *
 * @before_write
 */
class Car
{
 
	/**
	 * @var string
	 */
	public $color;
 
	/**
	 * This will be called by the Dao before each write of a Car object
	 *
	 * @noinspection PhpUnused @before_write
	 */
	public function beforeWrite()
	{
		// Do what you have to do before each write of a car here
		echo 'Doing things inside Car' . BR;
	}
 
	/**
	 * @return string
	 */
	public function __toString() : string
	{
		return $this->color . SP . 'car';
	}
 
}
```
Appels multiples

On peut appeler plusieurs traitements, en répétant simplement l’annotation dans la classe métier.
Ici par exemple on va appeler les deux méthodes : celle dans la classe métier, et celle de la classe tierce, des précédents exemples :
```
// (...)
/**
 * A car business object example
 *
 * @before_write beforeWriteCar
 * @before_write Before_Write_Class::beforeWriteCar
 */
class Car
// (...)
```
Les traitements des deux méthodes étant appelés, les deux textes vont s’afficher dans l’ordre :
```
Doing things inside Car
Doing things outside Car
```
Interruption de la chaîne d’appels
Dans le cas d’appels multiples, la méthode appelée peut décider d’interrompre la chaîne d’appels. C’est la valeur de retour de la méthode appelée qui détermine si l’exécution se poursuit :
- false : l’exécution est interrompue
- toute autre valeur (y compris null ou toute valeur vide autre que false ) : l’exécution se poursuit
Attention : si une des méthodes appelée renvoie false , l’objet ne sera pas écrit en utilisant le lien de données et l’écriture sera donc annulée !

Exemple : on réécrit la méthode beforeWriteCar de la classe métier Car , qui sera la première exécutée dans notre exemple précédent :
```
	/**
	 * @noinspection PhpUnused @before_write
	 * @param $link    Data_Link
	 * @param $options Option[]
	 * @return boolean
	 */
	public function beforeWriteCar(Data_Link $data_link, array $options) : bool
	{
		// Do what you have to do before each write of a car here
		echo "Doing things inside Car only" . BR;
		return false;
	}
```
Seul le traitement de cette méthode sera appelé, et l’objet ne sera pas enregistré en base ; le seul texte affiché sera donc :
```
Doing things inside Car only
```
Voir aussi

- Utiliser les événements du framework
- @after_write – Événement déclenché après l’écriture d’un objet
- @before_create – Événement déclenché avant l’écriture d’un nouvel objet
- @before_delete – Événement déclenché avant la suppression d’un objet
- @before_read – Événement déclenché avant la lecture d’un objet
- @before_update – Événement déclenché avant l’écriture de mise à jour d’un objet déjà enregistré