- Documentación
- SDK PHP · Versión 0.1
- Imágenes
Imágenes
En esta página
Una imagen acompaña a un post, o a una sola red mediante for(), junto con su texto alternativo. El SDK la envía a la API antes de crear la publicación, y descarga una imagen remota sin dejar nunca que una URL alcance tu propia red.
Cuatro fuentes
use QuietSocial\Sdk\Image;
Image::fromPath('/srv/app/storage/tarta.jpg', alt: 'Una tarta de calabaza'); // un archivo local
Image::fromUrl('https://cdn.ejemplo.es/tarta.jpg', alt: 'Una tarta de calabaza'); // descargada al crear la publicación
Image::fromContents($bytes, 'tarta.jpg', alt: 'Una tarta de calabaza'); // bytes ya en memoria
Image::existing('med_01k4b8z6u3w0j7q9x1z3a5c7e9', alt: 'Una tarta de calabaza'); // un medio que la API ya guarda
El texto alternativo se transmite a las redes que lo admiten: Facebook, Instagram, LinkedIn, Threads y Pinterest, que lo limita a 500 caracteres.
fromPath() rechaza una ruta con un protocolo (phar://, http://, php://…) y lanza InvalidPost: una imagen remota pasa por fromUrl(). Un archivo se lee una sola vez, la primera vez que hace falta.
Envío y reutilización
Toda imagen que no sea existing() la envía create() antes de crear la publicación, y luego se adjunta por su identificador med_…. La API acepta JPEG, PNG y WebP hasta 8 MiB, y convierte cada imagen en un JPEG que aceptan las cinco redes (ver Medios).
Para enviar una vez y reutilizar el medio:
$media = $client->media()->upload(Image::fromPath('/srv/app/storage/tarta.jpg'));
$post = Post::make('De nuevo en la tienda.')->image(Image::existing($media->id, alt: 'Una tarta de calabaza'));
El envío lleva una clave de idempotencia derivada de los bytes y de la marca: durante 24 horas, los mismos bytes devuelven el medio ya guardado, aunque se haya eliminado entretanto. media()->find(), media()->list() y media()->delete() completan el recurso.
Una imagen por post, y una por red: no hay galería ni vídeo.
Las imágenes remotas se descargan con cuidado
La dirección de una imagen suele venir de un contenido que alguien escribió. Seguida a ciegas, podría hacer que tu servidor alcanzara su propia red: un servicio de administración interno, la dirección de metadatos de un proveedor en la nube. Por eso Image::fromUrl():
- descarga sin tus credenciales de API, y sin ningún proxy;
- comprueba la dirección y cada redirección antes de seguirla, y rechaza una dirección privada, local, de enlace local, compartida, de multidifusión o reservada (IPv6 incluido), un nombre que lleve a una de ellas o que no se resuelva,
localhost, un host que no sea ASCII simple (da un nombre internacional en su formaxn--) y un host numérico en una forma no canónica (127.1,0x7f.1); - se conecta a la misma dirección que comprobó: una respuesta DNS que cambie entretanto (DNS rebinding) no cambia nada;
- sigue tres redirecciones como máximo, rechaza una redirección de
httpsahttp, y concede 30 segundos a la descarga completa; - deja de leer una respuesta mayor que el límite del transporte, 20 MiB por defecto (ver Pruebas y transportes).
Una descarga rechazada o fallida lanza una SocialException con el código image_download_failed, y no se crea nada. Cuando el host de la imagen responde 5xx o 429, es una ServiceUnavailable, que se puede reintentar.
En desarrollo local
Para una imagen servida por tu equipo de desarrollo, allowPrivateNetwork: true acepta una dirección privada o local para esa URL; sus redirecciones se siguen comprobando.
Image::fromUrl('http://localhost:8000/tarta.jpg', allowPrivateNetwork: true);
Resérvalo al desarrollo local, nunca a una URL que venga de un usuario. La protección existe precisamente para esas URL.