Aller au contenu
Quiet Social

Décrire un post

Un modèle décrit son post par le trait PublishesToSocial et des attributs PHP, par des méthodes publiques nommées par convention, ou par les deux. Cette page décrit les attributs, ce que désigne une référence, et où part le post.

L'attribut commun

#[SocialPost] décrit le post sur tous les réseaux :

Paramètre Nature Ce qu'il donne
content référence Le texte du post. Obligatoire.
title référence Un titre interne, montré dans le panel de Quiet Social seulement.
cover référence L'image : une URL, un chemin absolu, un chemin sur un disque, ou une Image du SDK. Voir Couvertures.
coverAlt référence Le texte alternatif de l'image.
coverDisk littéral Le disque d'un chemin de couverture relatif.
link référence Une URL absolue en http(s).
tags référence Un itérable de mots ou d'expressions, sans # : l'API fait de chacun un hashtag.
firstComment référence Un premier commentaire, là où un réseau en prend un (aucun pour l'instant).
publishAt référence Un DateTimeInterface ou une date en chaîne. Vide, passée ou à moins d'une minute : publié tout de suite.
when référence Ne publier que tant que cette valeur est vraie.
skip référence Ne publier nulle part tant que cette valeur est vraie.
brand référence La marque brd_…, à la place de QUIET_SOCIAL_BRAND_ID.
to littéral Des noms de réseau ou des identifiants de destination dst_….
mode littéral publish (par défaut), draft ou approval.

Ce que désigne une référence

Une référence désigne, dans cet ordre :

  1. une colonne présente sur le modèle, ou un accesseur ;
  2. une relation chargée ;
  3. une méthode publique sans paramètre obligatoire, appelée quand les étapes précédentes ont donné null.

Une colonne remplie l'emporte donc sur une méthode du même nom, et la méthode est appelée quand la colonne est nulle. Une méthode qui rend une relation donne ses modèles, pas la requête.

Une référence qui ne désigne rien sur un modèle lu en base lève InvalidSocialConfiguration. Les méthodes du framework ou de ce paquet (save(), delete()…) ne sont jamais appelées, ni les méthodes privées, protégées ou statiques, et un modèle strict (Model::shouldBeStrict()) n'est jamais lu sur un attribut absent.

Une valeur de texte peut être une chaîne, un objet Stringable ou un nombre ; une chaîne vide vaut null. Une valeur d'un autre type lève InvalidSocialConfiguration.

Les attributs de réseau

#[Facebook], #[Instagram], #[LinkedIn], #[Threads], #[Pinterest] et #[X] décrivent ce qui change sur un réseau. Leurs paramètres sont content, cover, coverAlt, link, tags, firstComment et skip (des références), et destination (un littéral : le nom d'une destination du réseau, comme un tableau Pinterest). #[Pinterest] prend aussi title, le titre de l'épingle. Deux sont refusés et rendent le post invalide (SocialPostRejected) : link sur #[Instagram], qui ne prend pas de lien, et firstComment sur #[Pinterest], qui ne prend pas de premier commentaire.

#[SocialPost(content: 'excerpt', cover: 'cover_path', link: 'url')]
#[Pinterest(title: 'title', destination: 'Recettes')]
#[Instagram(content: 'instagramCaption', skip: 'is_sponsored')]
class Recipe extends Model
{
    use PublishesToSocial;
}

Une valeur null au niveau d'un réseau laisse la valeur commune. Un attribut de réseau déclare aussi le réseau : voir les cibles implicites ci-dessous. Les attributs sont lus sur la classe du modèle, ou sur son plus proche parent qui en porte.

Les mêmes champs s'écrivent aussi en méthodes publiques : voir Méthodes par convention et priorités.

Où part le post

  • Cibles explicites. socialNetworks(), sinon #[SocialPost(to: [...])] : des noms de réseau ou des identifiants dst_…, gardés tels quels. Un réseau sans destination capable de publier fait refuser le post par l'API (SocialPostRejected).
  • Cibles implicites. Sans elles, le post part vers les réseaux que le modèle déclare, par un attribut de réseau ou une méthode de réseau, parmi ceux qui ont une destination capable de publier dans la marque. Ces destinations sont lues dans l'API et gardées en cache destinations_ttl secondes. S'il n'en reste aucun, rien n'est envoyé et un avertissement est journalisé.

Un modèle qui ne déclare aucun réseau, ou aucun contenu, lève InvalidSocialConfiguration.

Pour viser une destination précise d'un réseau qui en a plusieurs, nommez-la avec le paramètre destination de l'attribut du réseau, ou passez son identifiant dst_… dans to.

Modes et dates

  • publish (par défaut) envoie le post tout de suite, ou le programme à sa date de publication quand elle est à plus d'une minute.
  • draft et approval créent un brouillon, ou un post en attente de validation dans le panel. La date de publication n'est pas envoyée dans ces modes : l'API l'y ignore.

La date est lue comme un DateTimeInterface, ou comme une chaîne qu'une date sait lire (ISO 8601 de préférence). Une chaîne qui n'est pas une date rend le post invalide (SocialPostRejected).

La référence du post

Chaque post part avec la référence {classe de morph}:{clé} du modèle (App\Models\Article:42, ou article:42 avec un alias de morph). Elle revient dans les webhooks sous external_reference.