- Documentation
- SDK PHP · Version 0.1
- Publier
Publier
Sur cette page
Un Post décrit ce qu'il faut publier, une fois pour tous les réseaux, et publications()->create() le publie sur les cibles données. Cette page couvre la description d'un post, la programmation, les modes, les surcharges par réseau, l'idempotence et le suivi d'une publication.
Décrire un post
Chaque méthode rend un nouveau post et laisse l'original intact : un post de base se partage et se décline sans risque.
use QuietSocial\Sdk\Image;
use QuietSocial\Sdk\Network;
use QuietSocial\Sdk\NetworkPost;
use QuietSocial\Sdk\Post;
$post = Post::make('Notre recette de tarte aux courges est en ligne.')
->title('Tarte aux courges, octobre') // interne : visible dans le panel, jamais publié
->link('https://exemple.fr/recettes/42')
->tags('Recette végétarienne', 'Automne') // deviennent #RecetteVégétarienne #Automne
->image(Image::fromPath(__DIR__.'/tarte.jpg', alt: 'Une tarte aux courges sur une table en bois'))
->scheduleAt(new DateTimeImmutable('2026-10-15 09:00', new DateTimeZone('Europe/Paris')))
->timezone('Europe/Paris')
->reference('article:42')
->for(Network::LinkedIn, fn (NetworkPost $linkedin) => $linkedin
->content('La recette que nos lecteurs réclamaient toute l\'année.')
->tags('Cuisine'))
->for(Network::Pinterest, fn (NetworkPost $epingle) => $epingle
->title('Tarte aux courges')
->destination('Recettes'))
->for(Network::Instagram, fn (NetworkPost $instagram) => $instagram->tags());
$publication = $client->publications()->create($post, to: ['linkedin', 'pinterest', 'instagram']);
| Méthode | Ce qu'elle règle |
|---|---|
content() |
Le texte. |
title() |
Un titre interne, visible dans le panel et jamais publié. |
link() |
Un lien. Une URL absolue en http ou https, sans identifiants ni espaces. |
tags() |
Des mots ou des expressions, sans # : l'API fait de chacun un hashtag (Recette végétarienne devient #RecetteVégétarienne). Un nouvel appel remplace la liste. |
image() |
Une image, avec son texte alternatif (voir Images). |
firstComment() |
Un premier commentaire. Aucun réseau n'en publie encore : l'API l'ignore pour l'instant. |
scheduleAt() |
La date de publication, tout DateTimeInterface. |
timezone() |
Le fuseau d'affichage de la publication, comme Europe/Paris. |
mode() |
Ce que l'API en fait (voir plus bas). |
reference() |
Votre propre identifiant de ce dont parle le post, comme article:42 : enregistré comme external_reference de la publication, et source de la clé d'idempotence. |
brand() |
La marque brd_…, pour une clé qui couvre tout l'espace. |
for() |
Ce qui change sur un réseau (voir plus bas). |
Un post mal formé (un lien relatif, un tag qui n'est pas une chaîne, un champ qu'un réseau ne prend pas) lève InvalidPost dès l'appel de la méthode, avant tout envoi. Les règles de chaque réseau sont appliquées par l'API, qui répond par ValidationFailed (voir Erreurs).
Programmer
scheduleAt() prend tout DateTimeInterface et garde son décalage : la date ci-dessus part sous la forme 2026-10-15T09:00:00+02:00 (ISO 8601). Sans date, la publication part au prochain passage du planificateur, dans la minute. L'API refuse une date passée, même pour un brouillon.
Les modes
Mode |
Effet | Statut après create() |
|---|---|---|
Mode::Publish (défaut) |
Publiée à la date programmée, ou tout de suite s'il n'y en a pas. | scheduled |
Mode::Draft |
Gardée en brouillon : rien ne part avant un appel à publish(). |
draft |
Mode::Approval |
Soumise à validation dans le panel. Une fois validée, libérée par publish(). |
pending_approval |
use QuietSocial\Sdk\Mode;
$brouillon = $client->publications()->create($post->mode(Mode::Draft), to: ['linkedin']);
// Plus tard : la libérer, tout de suite ou à une date.
$client->publications()->publish($brouillon->id, at: new DateTimeImmutable('2026-10-16 08:00', new DateTimeZone('Europe/Paris')));
Un brouillon ou une publication soumise à validation ne garde aucune date : elle se choisit à l'appel de publish().
Surcharges par réseau
for() change ce que reçoit un réseau. La fonction reçoit un NetworkPost et le rend, modifié. Un champ laissé tel quel prend la valeur commune.
Méthode de NetworkPost |
Note |
|---|---|
content() |
Remplace le texte. |
title() |
Le titre de l'épingle. Pinterest seulement : sur tout autre réseau, InvalidPost. |
link() |
Remplace le lien. Instagram ne prend pas de lien : en poser un lève InvalidPost, et l'API y retire le lien commun. |
tags() |
Remplace les tags communs. tags() sans argument les retire sur ce réseau. |
image() |
Remplace l'image commune. |
firstComment() |
Refusé sur Pinterest. Aucun réseau ne publie encore de premier commentaire, et l'API refuse celui qui est posé pour un seul réseau. |
destination() |
Publie sur ce réseau vers la seule destination de ce nom (voir Ciblage). |
Un réseau réglé par for() mais absent de to: est ignoré : déclarer tous les réseaux une fois dans un post de base partagé est sans effet de bord.
Idempotence
Publier deux fois est le pire défaut d'une API de publication, et une requête restée sans réponse est renvoyée. Chaque create() porte donc une clé d'idempotence (voir Idempotence dans la référence de l'API).
- Avec une référence, la clé est la référence suivie du SHA-256 du corps de la requête. Renvoyer le même post (après un délai dépassé, depuis un job relancé) rend la première publication au lieu d'en créer une seconde.
- Un post modifié reçoit une nouvelle clé, et devient une nouvelle publication, même avec la même référence : la référence dit de quoi parle le post, ce n'est pas une contrainte d'unicité.
- L'API retient une clé 24 heures. Le même post renvoyé plus tard est créé de nouveau.
- Sans référence, chaque appel reçoit une clé aléatoire : un appel relancé publie de nouveau. Posez une référence dès que le même post peut partir deux fois.
create($post, to: [...], idempotencyKey: 'ma-propre-cle')remplace la clé dérivée. L'API refuse une clé connue envoyée avec un autre corps (ValidationFailed, codeidempotency_key_reused).
$post = Post::make('Notre nouvelle recette est en ligne.')->reference('article:42');
$premiere = $client->publications()->create($post, to: ['linkedin']);
$encore = $client->publications()->create($post, to: ['linkedin']); // dans les 24 heures : la même publication
$premiere->id === $encore->id; // true
$post->fingerprint($to) rend un SHA-256 de tout ce que le post publierait, et où, pour savoir si un post a changé depuis son dernier envoi. Ce n'est pas la clé d'idempotence, qui se calcule sur le corps une fois les cibles résolues et les images envoyées.
Suivre une publication
$publications = $client->publications();
$publication = $publications->find('pub_01k4b8y5t2v9h6p8w0y2z4b6c8');
$publication->status; // draft, scheduled, processing, published, partially_published, failed, cancelled…
foreach ($publication->targets as $cible) {
$cible->network; // linkedin
$cible->status; // published, failed…
$cible->externalUrl; // l'adresse du post sur le réseau, une fois publié
$cible->errorMessage; // la raison d'un échec
}
$page = $publications->list(['status' => 'failed', 'reference' => 'article:42'], page: 1, perPage: 25);
foreach ($page->items as $echouee) {
$publications->retry($echouee->id); // renvoie les cibles en échec
}
$page->hasMore(); // true si une autre page suit
$publications->cancel('pub_01k4b8y5t2v9h6p8w0y2z4b6c8');
list() accepte les filtres brand, status et reference ; toute autre clé lève InvalidArgumentException. Les valeurs d'une cible (content, tags, linkUrl, media…) sont les valeurs effectives : ce que reçoit la destination une fois les surcharges appliquées. Chaque objet de réponse garde dans raw() le contenu dont il est tiré. Les statuts sont décrits dans Publications.
Une transition que le statut interdit (publier une publication déjà partie, annuler une publication déjà publiée) lève ValidationFailed avec le code transition_not_allowed. Les transitions ne portent pas de clé d'idempotence : chacune refuse l'état qu'elle produit, et un second appel ne peut pas agir deux fois.