API « editer_objet »

L’ajout, la modification et la publication des instances d’objets éditoriaux sont simplifiés par une interface de programmation (ou API) constituée de 3 fonctions génériques qui peuvent servir pour manipuler tous les objets de SPIP.

  • Apparu en : SPIP 3.0

Insérer

Une nouvelle instance d’un objet éditorial est créée en base par

include_spip('action/editer_objet');
$id_objet = objet_inserer($objet, $id_parent);

objet_inserer prend 2 arguments :

  • $objet est le nom de l’objet inséré (article, breve,...)
  • $id_parent (facultatif) est l’id du parent de l’objet (id_rubrique pour un article ou une breve, id_groupe pour un mot...)

La fonction peut prendre un troisième argument optionnel : un tableau contenant les valeurs associées à chaque champ.

Les pipelines pre_insertion et post_insertion sont appelés automatiquement par la fonction.

Si, pour l’objet demandé, une fonction spécifique xxx_inserer existe dans action/editer_xxx, elle sera automatiquement appelée par objet_inserer à la place du traitement générique.

La fonction retourne l’id de l’enregistrement ajouté en base, ou 0 en cas d’échec.

Modifier

Pour modifier une instance d’un objet en base, on utilise la fonction : objet_modifier

include_spip('action/editer_objet');
objet_modifier($objet, $id_objet, $set);

Les 3 arguments :

  • $objet indique le nom de l’objet modifié
  • $id_objet donne l’id de l’objet modifié
  • $set est un tableau associatif champ=>valeur des champs modifiés

La fonction appelle automatiquement les pipelines pre_edition et post_edition.

Si pour l’objet demandé, une fonction spécifique xxx_modifier existe dans action/editer_xxx, elle sera automatiquement appelée par objet_modifier à la place du traitement générique.

La fonction retourne une chaîne vide si tout s’est bien passé ou l’erreur en cas d’échec.

La fonction objet_modifier vérifie les droits de l’auteur de la session en cours à faire l’action, via un appel à autoriser('modifier', $objet, $id_objet). Si elle est appelée par une tâche anonyme, il sera nécessaire d’accorder une autorisation exceptionnelle comme indiquée dans API « autoriser ».

Publier

Pour la publication d’un objet (modification du statut ou de la date), il convient d’appeler la même fonction objet_modifier de la même façon que pour la modification.

Cette fonction délègue à objet_instituer la mise à jour des champs qui concernent le statut de l’objet. Il est ainsi possible de modifier le contenu d’un objet et de le publier en un seul appel.

Si une fonction xxx_instituer existe dans action/editer_xxx elle sera automatiquement appelée par objet_instituer à la place du traitement générique.

La fonction objet_instituer vérifie les droits de l’auteur de la session en cours à faire l’action, via un appel à autoriser('instituer', $objet, $id_objet). Si elle est appelée par une tâche anonyme, il sera nécessaire d’accorder une autorisation exceptionnelle comme indiquée dans API « autoriser ».

Auteur cerdic Publié le : Mis à jour : 23/07/23

Traductions : English, français