Aller au contenu
Quiet Social

Images

Une image accompagne un post, ou un seul réseau par for(), avec son texte alternatif. Le SDK l'envoie à l'API avant de créer la publication, et télécharge une image distante sans jamais laisser une URL atteindre votre propre réseau.

Quatre sources

use QuietSocial\Sdk\Image;

Image::fromPath('/srv/app/storage/tarte.jpg', alt: 'Une tarte aux courges');        // un fichier local
Image::fromUrl('https://cdn.exemple.fr/tarte.jpg', alt: 'Une tarte aux courges');   // téléchargée à la création de la publication
Image::fromContents($octets, 'tarte.jpg', alt: 'Une tarte aux courges');           // des octets déjà en mémoire
Image::existing('med_01k4b8z6u3w0j7q9x1z3a5c7e9', alt: 'Une tarte aux courges');    // un média que l'API garde déjà

Le texte alternatif est transmis aux réseaux qui en acceptent un : Facebook, Instagram, LinkedIn, Threads et Pinterest, qui le limite à 500 caractères.

Un chemin avec un protocole (phar://, http://, php://…) est refusé par fromPath(), qui lève InvalidPost : une image distante passe par fromUrl(). Un fichier est lu une seule fois, la première fois qu'on en a besoin.

Envoi et réutilisation

Toute image autre qu'existing() est envoyée par create() avant la création de la publication, puis attachée par son identifiant med_…. L'API accepte le JPEG, le PNG et le WebP jusqu'à 8 Mio, et convertit chaque image en un JPEG que les cinq réseaux acceptent (voir Médias).

Pour envoyer une fois et réutiliser le média :

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

$post = Post::make('De retour en boutique.')->image(Image::existing($media->id, alt: 'Une tarte aux courges'));

L'envoi porte une clé d'idempotence tirée des octets et de la marque : pendant 24 heures, les mêmes octets rendent le média déjà enregistré, même s'il a été supprimé entre-temps. media()->find(), media()->list() et media()->delete() complètent la ressource.

Une image par post, et une par réseau : il n'y a ni galerie, ni vidéo.

Les images distantes sont téléchargées avec précaution

L'adresse d'une image vient souvent d'un contenu saisi par quelqu'un. Suivie à l'aveugle, elle pourrait faire atteindre à votre serveur son propre réseau : un service d'administration interne, l'adresse de métadonnées d'un hébergeur. Image::fromUrl() donc :

  • télécharge sans vos identifiants d'API, et sans aucun proxy ;
  • vérifie l'adresse et chaque redirection avant de la suivre, et refuse une adresse privée, locale, de lien local, partagée, de multidiffusion ou réservée (IPv6 compris), un nom qui y mène ou qui ne se résout pas, localhost, un hôte qui n'est pas en ASCII simple (donnez un nom international sous sa forme xn--) et un hôte numérique sous une forme non canonique (127.1, 0x7f.1) ;
  • se connecte à l'adresse même qu'il a vérifiée : une réponse DNS qui change entre-temps (rebinding DNS) ne change rien ;
  • suit trois redirections au plus, refuse une redirection de https vers http, et accorde 30 secondes au téléchargement entier ;
  • cesse de lire une réponse plus grosse que la limite du transport, 20 Mio par défaut (voir Tests et transports).

Un téléchargement refusé ou en échec lève une SocialException de code image_download_failed, et rien n'est créé. Quand l'hôte de l'image répond 5xx ou 429, c'est une ServiceUnavailable, qu'on peut réessayer.

En développement local

Pour une image servie par votre poste de développement, allowPrivateNetwork: true accepte une adresse privée ou locale pour cette URL ; ses redirections restent vérifiées.

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

Réservez-le au développement local, jamais à une URL venue d'un utilisateur. La garde existe précisément pour ces URL-là.