Covers
On this page
The cover of a post is its image: an SDK Image, a URL, an absolute path below an allowed directory, or a path on a disk. The package reads it when the post is sent, with safeguards against what a model should not be able to publish.
The four forms
| Cover | How it is read |
|---|---|
An SDK Image |
As is, with its own alternative text. |
An http(s):// URL |
Downloaded by the SDK when the post is sent. Private and local addresses are refused, unless allow_private_network_images is true. |
| An absolute path | Read only below one of cover_roots, and only if it is an image. |
| Any other string | A path on the disk coverDisk, otherwise cover_disk, otherwise your default disk. |
#[SocialPost(content: 'excerpt', cover: 'cover_path', coverAlt: 'cover_alt', coverDisk: 'public')]
class Article extends Model
{
use PublishesToSocial;
}
The safeguards
- Allowed directories. An absolute path is read only below
storage_path('app/public')orpublic_path()(thecover_rootskey, which you can widen by publishing the configuration), and only if the file is an image: a path stored in a model cannot make the package send/etc/hostsor your.env.storage/app/privateis not a default root: publishing from that directory must be a deliberate choice. - Size. A cover larger than
cover_max_bytes(20 MiB) is refused before it is read. - Private network. A URL pointing to a private, local or reserved address is refused, so that an address typed by a user cannot reach your own network.
QUIET_SOCIAL_ALLOW_PRIVATE_NETWORK_IMAGES=truelifts this refusal on a development machine that serves its images onhttp://localhost, never in production. The details of the download are in the documentation of the PHP SDK.
When a cover is missing
- A file or path that cannot be found, lies outside the allowed directories, is too large or is not an image makes the post invalid:
rejectedlink andSocialPostRejected. - A disk that does not answer is a temporary failure, retried.
- A URL that is refused, or that its server will not give, fails the post:
SocialPostFailed, and afailedlink sent again on the next change. A server error or a rate limit on its host is retried.
Alternative text and networks
coverAlt is the alternative text. Each network can have its own cover (#[Pinterest(cover: …)], pinterestCover()) and its own alternative text; a network alternative text without a network cover describes the common image on that network. A post carries one image, and at most one per network.
The fingerprint of a cover
The fingerprint of a cover file is computed from its path, its size and its modification date, without reading it: checking that a post has not changed does not cost a file read. Replacing the file changes its size or its date, and therefore the post.