- Documentation
- Laravel package · Version 0.1
- Describing a post
Describing a post
On this page
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:
- a column present on the model, or an accessor;
- a loaded relation;
- 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 ordst_…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_ttlseconds. 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.draftandapprovalcreate 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.