- Documentation
- PHP SDK · Version 0.1
- Publishing
Publishing
On this page
A Post describes what to publish, once for every network, and publications()->create() publishes it to the given targets. This page covers describing a post, scheduling, modes, per-network overrides, idempotency and following a publication.
Describe a post
Every method returns a new post and leaves the original untouched, so a base post can be shared and varied safely.
use QuietSocial\Sdk\Image;
use QuietSocial\Sdk\Network;
use QuietSocial\Sdk\NetworkPost;
use QuietSocial\Sdk\Post;
$post = Post::make('Our new squash pie recipe is online.')
->title('Squash pie, October') // internal, shown in the panel, never published
->link('https://example.com/recipes/42')
->tags('Vegetarian recipe', 'Autumn') // become #VegetarianRecipe #Autumn
->image(Image::fromPath(__DIR__.'/pie.jpg', alt: 'A squash pie on a wooden table'))
->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('The recipe our readers asked for all year.')
->tags('Cooking'))
->for(Network::Pinterest, fn (NetworkPost $pin) => $pin
->title('Squash pie')
->destination('Recipes'))
->for(Network::Instagram, fn (NetworkPost $instagram) => $instagram->tags());
$publication = $client->publications()->create($post, to: ['linkedin', 'pinterest', 'instagram']);
| Method | What it sets |
|---|---|
content() |
The text. |
title() |
An internal title, shown in the panel and never published. |
link() |
A link. It must be an absolute http or https URL, without credentials nor spaces. |
tags() |
Words or phrases, without #: the API turns each into a hashtag (Vegetarian recipe becomes #VegetarianRecipe). Calling it again replaces the list. |
image() |
One image, with its alternative text (see Images). |
firstComment() |
A first comment. No network publishes one yet: the API ignores it for now. |
scheduleAt() |
The publication date, any DateTimeInterface. |
timezone() |
The timezone the publication is displayed in, such as Europe/Paris. |
mode() |
What the API does with it (see below). |
reference() |
Your own identifier for what the post is about, such as article:42: stored as the external_reference of the publication, and the source of the idempotency key. |
brand() |
The brd_… brand, for a key that covers the whole workspace. |
for() |
What changes on one network (see below). |
A malformed post (a relative link, a tag that is not a string, a field a network does not take) throws InvalidPost as soon as the method is called, before anything is sent. The rules of each network are applied by the API, which answers with ValidationFailed (see Errors).
Scheduling
scheduleAt() takes any DateTimeInterface and keeps its offset: the date above is sent as 2026-10-15T09:00:00+02:00 (ISO 8601). Without a date, the publication leaves at the next pass of the scheduler, within a minute. The API refuses a date in the past, even for a draft.
Modes
Mode |
What happens | Status after create() |
|---|---|---|
Mode::Publish (default) |
Published at the scheduled date, or now when there is none. | scheduled |
Mode::Draft |
Kept as a draft: nothing leaves until publish() is called. |
draft |
Mode::Approval |
Submitted for approval in the panel. Once approved, released with publish(). |
pending_approval |
use QuietSocial\Sdk\Mode;
$draft = $client->publications()->create($post->mode(Mode::Draft), to: ['linkedin']);
// Later: release it, now or at a date.
$client->publications()->publish($draft->id, at: new DateTimeImmutable('2026-10-16 08:00', new DateTimeZone('Europe/Paris')));
A draft or a publication submitted for approval keeps no date: it is chosen when calling publish().
Per-network overrides
for() changes what one network receives. The closure receives a NetworkPost and returns it, changed. A field left alone takes the common value.
NetworkPost method |
Note |
|---|---|
content() |
Replaces the text. |
title() |
The title of the Pin. Pinterest only: on any other network it throws InvalidPost. |
link() |
Replaces the link. Instagram takes no link: setting one throws InvalidPost, and the API drops the common link there. |
tags() |
Replaces the common tags. tags() without arguments removes them on this network. |
image() |
Replaces the common image. |
firstComment() |
Refused on Pinterest. No network publishes a first comment yet, and the API refuses one set for a single network. |
destination() |
Publishes on this network to the destination with this name only (see Targeting). |
A network configured with for() but absent from to: is ignored: declaring every network once in a shared base post is harmless.
Idempotency
Publishing twice is the worst thing a publishing API can do, and a request that times out is sent again. Every create() therefore carries an idempotency key (see Idempotency in the API reference).
- With a reference, the key is the reference followed by the SHA-256 of the request body. Sending the same post again (after a timeout, from a retried job) returns the first publication instead of creating a second one.
- A changed post gets a new key, and is a new publication, even with the same reference: the reference names what the post is about, it is not a uniqueness constraint.
- The API remembers a key for 24 hours. The same post sent again later is created again.
- Without a reference, each call gets a random key: a retried call publishes again. Set a reference whenever the same post may be sent twice.
create($post, to: [...], idempotencyKey: 'my-own-key')replaces the derived key. The API refuses a known key sent with another body (ValidationFailed, codeidempotency_key_reused).
$post = Post::make('Our new recipe is online.')->reference('article:42');
$first = $client->publications()->create($post, to: ['linkedin']);
$again = $client->publications()->create($post, to: ['linkedin']); // within 24 hours: the same publication
$first->id === $again->id; // true
$post->fingerprint($to) returns a SHA-256 of everything the post would publish, and where, to tell whether a post changed since you last sent it. It is not the idempotency key, which is computed on the body once targets are resolved and images uploaded.
Following a publication
$publications = $client->publications();
$publication = $publications->find('pub_01k4b8y5t2v9h6p8w0y2z4b6c8');
$publication->status; // draft, scheduled, processing, published, partially_published, failed, cancelled…
foreach ($publication->targets as $target) {
$target->network; // linkedin
$target->status; // published, failed…
$target->externalUrl; // the URL of the post on the network, once published
$target->errorMessage; // why it failed
}
$page = $publications->list(['status' => 'failed', 'reference' => 'article:42'], page: 1, perPage: 25);
foreach ($page->items as $failed) {
$publications->retry($failed->id); // sends again the targets that failed
}
$page->hasMore(); // true when another page follows
$publications->cancel('pub_01k4b8y5t2v9h6p8w0y2z4b6c8');
list() takes the filters brand, status and reference; any other key throws InvalidArgumentException. The values of a target (content, tags, linkUrl, media…) are the effective ones: what the destination receives once the overrides are applied. Every response object keeps the payload it was built from in raw(). The statuses are described in Publications.
A transition the status forbids (publishing a publication already gone, cancelling one already published) throws ValidationFailed with the code transition_not_allowed. Transitions carry no idempotency key: each refuses the state it produces, so sending one twice cannot act twice.