Skip to content
Quiet Social

Describing a post

This documentation is translated from French. Should the two versions differ, the French version prevails.

A model describes its post through the PublishesToSocial trait and PHP attributes, through public methods named by convention, or both. This page describes the attributes, what a reference names, and where the post goes.

The common attribute

#[SocialPost] describes the post on every network:

Parameter Kind What it gives
content reference The text of the post. Required.
title reference An internal title, shown in the Quiet Social panel only.
cover reference The image: a URL, an absolute path, a path on a disk, or an SDK Image. See Covers.
coverAlt reference The alternative text of the image.
coverDisk literal The disk of a relative cover path.
link reference An absolute http(s) URL.
tags reference An iterable of words or phrases, without #: the API turns each into a hashtag.
firstComment reference A first comment, where a network takes one (none does yet).
publishAt reference A DateTimeInterface or a date string. Empty, past or within a minute: published now.
when reference Publish only while this value is truthy.
skip reference Publish nowhere while this value is truthy.
brand reference The brd_… brand, instead of QUIET_SOCIAL_BRAND_ID.
to literal Network names or dst_… destination identifiers.
mode literal publish (default), draft or approval.

What a reference names

A reference names, in this order:

  1. a column present on the model, or an accessor;
  2. a loaded relation;
  3. a public method without required parameters, called when the previous steps gave null.

A filled column therefore wins over a method of the same name, and the method is called when the column is null. A method that returns a relation gives its models, not the query.

A reference that names nothing on a model read from the database throws InvalidSocialConfiguration. Methods of the framework or of this package (save(), delete()…) are never called, nor private, protected or static methods, and a strict model (Model::shouldBeStrict()) is never read for a missing attribute.

A text value may be a string, a Stringable object or a number; an empty string counts as null. A value of any other type throws InvalidSocialConfiguration.

Network attributes

#[Facebook], #[Instagram], #[LinkedIn], #[Threads], #[Pinterest] and #[X] describe what changes on one network. Their parameters are content, cover, coverAlt, link, tags, firstComment and skip (references), and destination (a literal: the name of one destination of the network, such as a Pinterest board). #[Pinterest] also takes title, the title of the Pin. Two of them are refused, and make the post invalid (SocialPostRejected): link on #[Instagram], which takes no link, and firstComment on #[Pinterest], which takes no first comment.

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

A null value at the network level leaves the common value. A network attribute also declares the network: see implicit targets below. Attributes are read on the model class, or on its nearest parent that has them.

The same fields can also be written as public methods: see Methods by convention and priorities.

Where the post goes

  • Explicit targets. socialNetworks(), otherwise #[SocialPost(to: [...])]: network names or dst_… identifiers, kept as given. A network without a destination able to publish makes the API refuse the post (SocialPostRejected).
  • Implicit targets. Without them, the post goes to the networks the model declares, through a network attribute or a network method, among those that have a destination able to publish in the brand. These destinations are read from the API and cached for destinations_ttl seconds. When none is left, nothing is sent and a warning is logged.

A model that declares no network at all, or no content, throws InvalidSocialConfiguration.

To target one specific destination of a network that has several, name it with the destination parameter of the network attribute, or pass its dst_… identifier in to.

Modes and dates

  • publish (the default) sends the post now, or schedules it at its publication date when that date is more than a minute ahead.
  • draft and approval create a draft, or a post waiting for approval in the panel. The publication date is not sent in these modes: the API ignores it there.

The date is read as a DateTimeInterface, or as a string a date can parse (ISO 8601 preferably). A string that is not a date makes the post invalid (SocialPostRejected).

The reference of the post

Each post is sent with the {morph class}:{key} reference of the model (App\Models\Article:42, or article:42 with a morph alias). It comes back in webhooks as external_reference.