Skip to content
Quiet Social

Images

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

An image goes with a post, or with one network through for(), along with its alternative text. The SDK uploads it before creating the publication, and downloads a remote image without ever letting a URL reach your own network.

Four sources

use QuietSocial\Sdk\Image;

Image::fromPath('/srv/app/storage/pie.jpg', alt: 'A squash pie');            // a local file
Image::fromUrl('https://cdn.example.com/pie.jpg', alt: 'A squash pie');      // downloaded when the publication is created
Image::fromContents($bytes, 'pie.jpg', alt: 'A squash pie');                 // bytes already in memory
Image::existing('med_01k4b8z6u3w0j7q9x1z3a5c7e9', alt: 'A squash pie');      // a media the API already stores

The alternative text is sent to the networks that accept one: Facebook, Instagram, LinkedIn, Threads and Pinterest, which limits it to 500 characters.

A path with a stream wrapper (phar://, http://, php://…) is refused by fromPath(), which throws InvalidPost: a remote image goes through fromUrl(). A file is read once, the first time it is needed.

Upload and reuse

Every image but existing() is uploaded by create() before the publication is created, then attached by its med_… id. The API accepts JPEG, PNG and WebP up to 8 MiB, and converts each image into a JPEG the five networks accept (see Media).

To upload once and reuse the media:

$media = $client->media()->upload(Image::fromPath('/srv/app/storage/pie.jpg'));

$post = Post::make('Back in stock.')->image(Image::existing($media->id, alt: 'A squash pie'));

The upload carries an idempotency key derived from the bytes and the brand: within 24 hours, the same bytes return the media already stored, even if it was deleted in between. media()->find(), media()->list() and media()->delete() complete the resource.

One image per post, and one per network: there is no gallery, no video.

Remote images are fetched with care

An image URL often comes from content a user typed. Fetched blindly, it could make your server reach its own network: an internal admin service, the metadata address of a cloud host. Image::fromUrl() therefore:

  • downloads without your API credentials, and without any proxy;
  • checks the URL and each redirect before fetching it, and refuses a private, local, link-local, shared, multicast or reserved address (IPv6 included), a host name that resolves to one or to nothing, localhost, a host that is not plain ASCII (give an international name in its xn-- form) and a numeric host in a non-canonical form (127.1, 0x7f.1);
  • connects to the very address it checked, so that a DNS answer that changes in between (DNS rebinding) changes nothing;
  • follows three redirects at most, refuses a redirect from https to http, and allows 30 seconds for the whole download;
  • stops reading a response larger than the limit of the transport, 20 MiB by default (see Testing and transports).

A refused or failed download throws a SocialException with the code image_download_failed, and nothing is created. When the image host answers 5xx or 429, it is a ServiceUnavailable, which can be retried.

In local development

For an image served by your development machine, allowPrivateNetwork: true accepts a private or local address for that URL; its redirects are still checked.

Image::fromUrl('http://localhost:8000/pie.jpg', allowPrivateNetwork: true);

Reserve it for local development, never for a URL that comes from a user. The guard exists precisely for those URLs.