13.6.3.34 Doc::setState()

13.6.3.34.1 Description

string setState ( string $newstate,
                  string $comment     = '',
                    bool $force       = false,
                    bool $withcontrol = true,
                    bool $wm1         = true,
                    bool $wm2         = true,
                    bool $wneed       = true,
                    bool $wm0         = true,
                    bool $wm3         = true,
                string & $msg         = '' )

La méthode setState permet de changer l'état du document si celui-ci est associé à un cycle de vie.

13.6.3.34.1.1 Avertissements

Aucun.

13.6.3.34.2 Liste des paramètres

(string) newstate

newstate est le nom de l'état (de destination) dans lequel on souhaite mettre le document.

(string) comment

comment permet de spécifier un commentaire facultatif qui est inscrit dans l'historique du document suite à son changement d'état.

Par défaut comment est une chaîne vide, et aucun message additionnel n'est inscrit dans l'historique du document.

(bool) force

force permet de forcer le changement d'état pour le cas ou l'état demandé n'est pas associé à une transition valide du cycle de vie.

Par défaut force est à false, et le nouvel état demandé (de destination) doit alors avoir une transition valide avec l'état actuel (de départ) du document.

(bool) withcontrol

withcontrol permet de désactiver le contrôle des droits sur les transitions du cycle.

Par défaut withcontrol est à true, et le contrôle des droits sur les transitions du cycle est appliqué.

(bool) wm1

wm1 permet de spécifier si la méthode m1 de la transition doit être appliquée.

Par défaut wm1 est à true, et la méthode m1 de la transition est appliquée.

(bool) wm2

wm2 permet de spécifier si la méthode m2 de la transition doit être appliquée.

Par défaut wm2 est à true, et la méthode m2 de la transition est appliquée.

(bool) wneed

wneed permet de spécifier si le contrôle des attributs obligatoire du document doit être appliqué.

Par défaut wneed est à true, et le contrôle des attributs obligatoire du document est appliqué.

(bool) wm0

wm0 permet de spécifier si la méthode m0 de la transition doit être appliquée.

Par défaut wm0 est à true, et la méthode m0 de la transition est appliquée.

(bool) wm3

wm3 permet de spécifier si la méthode m3 de la transition doit être appliquée.

Par défaut wm3 est à true, et la méthode m3 de la transition est appliquée.

[out] (string) msg

msg est une référence facultative à une chaîne de caractères qui est retournée par la méthode et qui contient les messages retournées par les méthodes m1, m2 et l'émission des mails déclarés sur le cycle.

13.6.3.34.3 Valeur de retour

La méthode retourne une chaîne vide s'il n'y a pas d'erreurs, ou une chaîne non-vide contenant un message d'erreur si la transition n'a pas pu être réalisée.

13.6.3.34.4 Erreurs / Exceptions

La méthode retourne un message d'erreur si :

• L'état newstate demandé est vide ;
• Le document n'a pas de cycle de vie ;
• Le cycle de vie associé au document n'existe pas ;
• Le cycle de vie associé au document est corrompu (ex. syntaxe PHP invalide) ;
• L'état newstate de destination n'existe pas ou n'est pas associé à une transition valide et que force est à false ;
• L'état newstate de destination n'existe pas ou n'est pas associé à une transition valide et que l'utilisateur n'est pas le super-utilisateur admin ;
• wm0 est à true et la méthode m0 n'existe pas ;
• wm0 est à true et l'exécution de la méthode m0 à retournée un message d'erreur ;
• wm1 est à true et la méthode m1 n'existe pas ;
• wm1 est à true et l'exécution de la méthode m1 à retournée un message d'erreur ;
• wneed est à true et le contrôle des attributs obligatoire à retourné un message d'erreur (ex. des attributs obligatoires ne sont pas remplis) ;
• La revision ou l'inscription du document en base de données ont retourné un message d'erreur ;
• wm2 est à true et la méthode m2 n'existe pas ;
• wm3 est à true et la méthode m3 n'existe pas ;
• Le changement d'affectation du document déclaré sur le cycle à retourné un message d'erreur.

13.6.3.34.5 Historique

Aucun.

13.6.3.34.6 Exemples

• Exemple #1

/*
 * Mettre la facture dans l'état Archivé
 */
$err = $facture->setState('ST_ARCHIVED');
if ($err != '') {
    throw new Exception(
        sprintf("La facture n'a pu être archivée: %s", $err)
    );
}

13.6.3.34.7 Notes

Pour qu'il y ait changement d'état, il faut que l'état newstate de destination demandé ait une transition valide depuis l'état de départ actuel du document.

S'il n'y a pas de transitons entre l'état de départ actuel du document et le nouvel état newstate demandé, alors une erreur est remontée.

Dans ce cas, si vous voulez quand même mettre le document dans l'état newstate, alors il faut utiliser le paramètre force avec la valeur true.

13.6.3.34.8 Voir aussi

• Famille de cycle de vie
• Implémentation d'un cycle de vie