17.17 Mise à jour d'attribut sur des collections de documents

17.17.1 Présentation

Afin de modifier une valeur d'attribut sur un ensemble de document vous pouvez utiliser une itération sur la liste en question comme le montre l'exemple ci- dessous

$s = new \SearchDoc('', 'TST_MYFAMILY');
$s->setObjectReturn();
$s->setOrder('initid');
$s->setSlice(1000);
$dl=$s->search()->getDocumentList();
foreach ($dl as $doc) {
    $doc->setValue('tst_example','my new value');
    $err=$doc->store();
}

Plus le nombre de documents est important, plus le temps de modification sera conséquent. L'utilisateur ayant déclenché ce programme risque de perdre patience.

La classe UpdateAttribute permet de réaliser un traitement équivalent de manière optimisée.

$s = new \SearchDoc('', 'TST_MYFAMILY');
$s->setObjectReturn();
$s->setOrder('initid');
$s->setSlice(1000);
$dl=$s->search()->getDocumentList();
$ua = new \UpdateAttribute();
$ua->useCollection($dl);
$ua->setValue('tst_example','my new value');
$err=$ua->getError();

Ceci ne réalise pas tout à fait la même action. En effet dans la version optimisée les post-traitement spécifiques et internes ne sont pas réalisés. Cela veut dire que le titre, le profil, les attributs calculés ne sont pas mis à jour.

En contrepartie, le temps de traitement est bien moindre. Sur une mise à jour "classique" pour un temps de réponse d'environ 45 secondes pour 1000 documents, la version optimisée réalise le traitement en moins de 2 secondes.

17.17.2 Paramétrage général

17.17.2.1 Réviser les documents

Les documents peuvent être révisés avant la modification. Cela est indiqué par la méthode ::addRevision().

$ua = new \UpdateAttribute();
$ua->useCollection($dl);
$ua->addRevision('my revision');
$ua->setValue('tst_example','my new value');

La révision est faite sur les documents qui seront modifiés. Dans le cas du setValue si la valeur est déjà celle que l'on veut mettre, la révision ne sera pas effectuée. De manière générale si le document ne subit pas de modification, il ne sera pas révisé.

L'activation de ce paramètre va entraîner un temps de réponse plus important car cela entraîne de nombreuses écritures supplémentaires pour les révisions.

17.17.2.2 Recalculer le profil

Si vos documents sont lié à un profil dynamique et que la modification est faite sur un attribut lié au profil, vous devez ajouter l'appel à la méthode ::useProfileUpdating().

$ua = new \UpdateAttribute();
$ua->useCollection($dl);
$ua->useProfileUpdating();
$ua->setValue('tst_redactor','MY_NEWREDACTOR');

17.17.2.3 Ajouter un commentaire d'historique

Un commentaire spécifique, avec la méthode ::addHistoryComment() peut être ajouté dans l'historique sur chacun des documents. À la différence de la révision, il est appliqué sur tous les documents qu'il soit changé ou non.

$ua = new \UpdateAttribute();
$ua->useCollection($dl);
$ua->addHistoryComment("my message");
$ua->setValue('tst_example','my new value');

17.17.2.4 Activer le mode transactionnel

Le mode transactionnel, permet d'éviter de faire un traitement partiel en cas d'erreur. Par défaut ce mode n'est pas activé.

$ua = new \UpdateAttribute();
$ua->useCollection($dl);
$ua->useTransaction(true);
$ua->setValue('tst_example','my new value');

S'il y a une exception levée ou si ::getError() n'est pas vide le traitement sera abandonné.

17.17.2.5 Récupérer les statuts

Lorsque le traitement est fini, le statut de chacun des documents est donné par la méthode ::getResults(). Cela donne une table avec pour chacun des éléments, des indications sur ce qui a été fait, l'index du tableau est l'initid du document.

• [changed] => est à vrai si le document a subit une modification
• [revisionError] => message d'erreur de la révision (si révision)
• [profilingError] => message d'erreur du recalcul de profil
• [profiled] => est à vrai si le document a été reprofilé
• [revised] => est à vrai si le document a été révisé
• [historyUpdated] => est à vrai si l'historique a été mis à jour

$ua = new \UpdateAttribute();
$ua->useCollection($dl);
$ua->setValue('tst_example','my new value');
$status=$ua->getResults();
$changed=$unChanged=0;
foreach ($status as $initid=>$aStatus) {
    if ($aStatus->changed) $changed++;
    else $unChanged++;
}
printf("%d document changed, %d document unchanged\n", $changed,$unChanged);

17.17.2.6 Estimation des temps de réponse

Ces temps sont donnés à titre indicatif pour le traitement de 1000 documents. Ces temps peuvent fluctuer en fonction de votre configuration serveur et de la configuration de la famille.

17.17.3 Fonctions de modifications

Les quatre fonctions de modification permettent de réaliser des modifications sur un attribut en particulier pour l'ensemble des documents donné.

17.17.3.1 setValue

La méthode ::setValue() permet de changer de manière systématique la valeur d'un attribut. Si la valeur d'un document est déjà celle choisie, alors le document n'est pas modifié.

Si l'attribut est dans un tableau, c'est toute la colonne qui est modifiée. Il est possible d'indiquer un tableau de valeur dans la cas d'un attribut multiple ou d'un attribut qui est dans un tableau.

17.17.3.2 replaceValue

La méthode ::replaceValue() permet de changer une valeur par une autre.

Si la valeur à changer n'est pas présente, le document ne sera pas changé.

Pour les attributs multiples, le test de remplacement se fait sur chacune des valeurs du multiple. De même, pour les multiples dans les tableaux, le test de remplacement se fera sur les valeurs finales.

$ua = new \UpdateAttribute();
$ua->useCollection($dl);
$ua->replaceValue('tst_example','my old value','my new value');

17.17.3.3 removeValue

La méthode ::removeValue() permet de supprimer une certaine valeur d'un attribut. Cela ne permet pas de supprimer la valeur de l'attribut de manière systématique. Si la valeur à supprimer n'est pas présente le document ne sera pas changé.

Comme pour ::replaceValue(), pour les attribut multiple, le test de suppression se fait chacune des valeurs du multiple.

$ua = new \UpdateAttribute();
$ua->useCollection($dl);
$ua->removeValue('tst_example','value to remove');

Lorsque l'attribut est dans un tableau, cela laissera un vide dans le tableau où la valeur se située.

17.17.3.4 addValue

La méthode ::addValue() ne fonctionne qu'avec les attributs "multiples". Elle permet d'ajouter une nouvelle valeur à la liste des valeurs de l'attribut. Si l'attribut est déclaré multiple alors seuls les documents n'ayant pas encore cette valeur seront changés. Si c'est un attribut simple qui est dans un tableau alors une nouvelle rangée sera ajoutée au tableau.

Si c'est un attribut multiple qui est dans un tableau alors la valeur sera ajoutée à tous les éléments du multiple.

$ua = new \UpdateAttribute();
$ua->useCollection($dl);
$ua->addValue('tst_multiple','value to add');

17.17.4 Éxécution en tâche de fond

Comme ces tâches peuvent être longues, il est possible de les lancer en tâche de fond. Cela est fait en remplaçant l'appel des fonctions de modification par leur équivalent en tâche de fond.

• ::bgSetValue()
• ::bgReplaceValue()
• ::bgRemoveValue()
• ::bgAddValue()

$ua = new \UpdateAttribute();
$ua->useCollection($dl);
$fileStatus=$ua->bgAddValue('tst_multiple','value to add');

À la différence des fonctions lancées en synchrone, cette fonction retourne un chemin vers un fichier qui sera mis à jour au fur et à mesure de l'avancement par le processus lancé en tâche de fond. L'exploitation de ce fichier se fait via la classe UpdateAttributeStatus. Elle permet de contrôler l'avancement de la tâche.

$sua= new UpdateAttributeStatus($statusFile);
while (! $sua->isFinished()) {
    print_r($sua->getLastMessage());
    sleep(1);
}
if ($err=$sua->getError()) {
    print "Process failed : ".$err;
} else {
    $status=$sua->getResults();
    $changed=$unChanged=0;
 
    foreach ($status as $initid=>$aStatus) {
        if ($aStatus->changed) $changed++;
        else $unChanged++;
    }
    printf("%d document changed, %d document unchanged\n", $changed,$unChanged);
}

La méthode ::getLastMessage() retourne un objet UpdateAttributeStatusLine avec les informations suivantes :

• date : date d'exécution (format ISO 8601)
• processCode : nom de la méthode utilisée
• message : message d'information

Extrait du fichier de status :

2012-06-28T16:16:30 setValue BEGIN
2012-06-28T16:16:30 setValue traitement
[219656,220655,220656,220657,220658,220659,220660,220661,220662,220663,220664,22066
5,220666,220667,220668,220669,220670,22067
1,220672,220673,220674,220675,220676,220677,220678,220679,220680,220681]
2012-06-28T16:16:30 executeRevision traitement des révisions pour 28 documents
2012-06-28T16:16:32 executeRevision 10/28 révisions effectuées
2012-06-28T16:16:34 executeRevision 20/28 révisions effectuées
2012-06-28T16:16:35 executeRevision 28/28 révisions effectuées
2012-06-28T16:16:35 executeRevision traitement des révisions effectué
2012-06-28T16:16:35 executeSetValue traitement d'affectation de valeur pour 28
documents
2012-06-28T16:16:35 executeSetValue argument tst_redactor=>1181
2012-06-28T16:16:35 executeSetValue 28 documents mis à jour
2012-06-28T16:16:35 executeProfiling 10/28 mise à jour de profils effectués
2012-06-28T16:16:36 executeProfiling 20/28 mise à jour de profils effectués
2012-06-28T16:16:36 executeProfiling 28/28 mise à jour de profils effectués
...
2012-06-28T16:16:36 setValue END