- Documentation
- Laravel package · Version 0.1
- Introduction
Introduction
On this page
The quiet-social/laravel-social package publishes your Eloquent models to Facebook, Instagram, LinkedIn, Threads and Pinterest. Describe the post once, on the model: the package sends it when the model is saved, replaces it while it has not left, and cancels it when the model is deleted or unpublished.
First example
use Illuminate\Database\Eloquent\Model;
use QuietSocial\Social\Attributes\LinkedIn;
use QuietSocial\Social\Attributes\SocialPost;
use QuietSocial\Social\Concerns\PublishesToSocial;
#[SocialPost(
content: 'excerpt',
link: 'url',
cover: 'cover_path',
publishAt: 'published_at',
when: 'is_published',
to: ['facebook', 'linkedin'],
)]
#[LinkedIn(content: 'linkedinTeaser')]
class Article extends Model
{
use PublishesToSocial;
public function linkedinTeaser(): string
{
return $this->excerpt."\n\nThe full article is on our website.";
}
}
Saving a published article sends its post, scheduled at published_at. Changing what the post shows (the excerpt, the link, the cover…) before that date replaces the scheduled post; unpublishing or deleting the article cancels it.
The API key needs the rights publications:create, publications:read, publications:cancel and destinations:read, plus media:create for the cover. A key that covers a whole workspace also needs the brand to publish for: QUIET_SOCIAL_BRAND_ID, or #[SocialPost(brand: ...)] per model (see Installation and configuration).
How it works
- Describe. PHP attributes (
#[SocialPost],#[LinkedIn]…) or public methods named by convention (socialContent(),linkedinContent()…) say what the model publishes. - Synchronise. Each save or deletion queues a job that compares the post described with what was already sent, through a fingerprint, and sends, replaces, cancels or does nothing.
- Follow. Quiet Social webhooks keep the status of each post up to date, and raise Laravel events.
Everything goes through the PHP SDK, installed with the package, and through the REST API v1: the package opens no door the API does not open, and its rights are those of the key that authenticates it.
The pages of this documentation
- Installation and configuration: requirements, API key and rights, every configuration key.
- Adopting the package on an existing database: the
social:baselinecommand, to read before equipping a model that already has rows. - Describing a post: attributes, references, targets, modes and dates.
- Methods by convention and priorities: the table of names, and which one wins.
- Automatic synchronisation: the decision table, the lock and the cache, the queue.
- Covers: URL, path, disk, and what is refused.
- Publishing, cancelling and previewing by hand:
publishToSocial(),cancelSocialPublication(),toSocialPost(). - Laravel events: what is raised, and when.
- Webhooks: the route, the secret, duplicates.
- Testing:
SocialPublisher::fake()and its assertions. - The manual builder: publishing by hand, without describing a model.
A Filament plugin built on this package adds a publication list, a relation manager and a reconnection widget to your panel; it is not published yet.
Known limitations
- Mass updates are not followed. Only Eloquent events trigger the synchronisation:
Article::query()->update([...])or a mass delete fires none. CallpublishToSocial()on the models concerned, or save them one by one. - One image per post, and one per network. No gallery, no video.
- X can be declared, not published. A model may declare X: while the API does not publish there, an implicit target leaves it out, and an explicit
to: ['x']is refused (SocialPostRejected). - The publication date is ignored in
draftandapprovalmodes: it is not sent there. - No first comment yet. No network publishes one: the API ignores the common one and refuses one set for a single network.
- A post that left is not corrected. A change made after publication raises
SocialPostOutdated, and nothing else.
Versions
The package follows semantic versioning. Before 1.0, a minor version may change the public API; the package changelog (CHANGELOG.md) says what changed. This documentation describes version 0.1, which works with version 1 of the API (/api/v1).
The source code is published on GitHub, as a read-only mirror: pull requests are closed there, issues are welcome. Its composer.json declares a path repository (../php-social), used to develop the package next to the SDK: Composer reads repositories only from the root project, so it does not affect an installation with composer require.