- Documentación
- Paquete Laravel · Versión 0.1
- Introducción
Introducción
En esta página
El paquete quiet-social/laravel-social publica tus modelos Eloquent en Facebook, Instagram, LinkedIn, Threads y Pinterest. El post se describe una sola vez, en el modelo: el paquete lo envía cuando el modelo se guarda, lo sustituye mientras no haya salido, y lo cancela cuando el modelo se elimina o se despublica.
Un primer ejemplo
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\nEl artículo completo está en nuestro sitio.";
}
}
Guardar un artículo publicado envía su post, programado en published_at. Cambiar lo que muestra el post (la entradilla, el enlace, la portada…) antes de esa fecha sustituye el post programado; despublicar o eliminar el artículo lo cancela.
La clave API necesita los permisos publications:create, publications:read, publications:cancel y destinations:read, más media:create para la portada. Una clave que cubre todo un espacio de trabajo necesita además la marca para la que publicar: QUIET_SOCIAL_BRAND_ID, o #[SocialPost(brand: ...)] modelo por modelo (consulta Instalación y configuración).
Cómo trabaja
- Describir. Atributos PHP (
#[SocialPost],#[LinkedIn]…) o métodos públicos con nombres convencionales (socialContent(),linkedinContent()…) dicen lo que publica el modelo. - Sincronizar. Cada guardado o eliminación pone en cola un job que compara el post descrito con lo que ya se envió, mediante una huella, y envía, sustituye, cancela o no hace nada.
- Seguir. Los webhooks de Quiet Social mantienen al día el estado de cada post y emiten eventos de Laravel.
Todo pasa por el SDK PHP, instalado con el paquete, y por la API REST v1: el paquete no abre ninguna puerta que ella no abra, y sus permisos son los de la clave con la que se autentica.
Las páginas de esta documentación
- Instalación y configuración: requisitos, clave API y permisos, cada clave de configuración.
- Adoptar el paquete en una base existente: el comando
social:baseline, que hay que leer antes de equipar un modelo que ya tiene filas. - Describir un post: los atributos, las referencias, los destinos, los modos y las fechas.
- Métodos por convención y prioridades: la tabla de nombres, y cuál prevalece.
- Sincronización automática: la tabla de decisión, el bloqueo y la caché, la cola.
- Portadas: URL, ruta, disco, y lo que se rechaza.
- Publicar, cancelar y previsualizar a mano:
publishToSocial(),cancelSocialPublication(),toSocialPost(). - Eventos de Laravel: lo que se emite, y cuándo.
- Webhooks: la ruta, el secreto, los duplicados.
- Pruebas:
SocialPublisher::fake()y sus aserciones. - El constructor manual: publicar a mano, sin describir ningún modelo.
Un plugin de Filament construido sobre este paquete añade a tu panel la lista de publicaciones, un relation manager y un widget de reconexión; todavía no está publicado.
Limitaciones conocidas
- Las actualizaciones masivas no se siguen. Solo los eventos de Eloquent disparan la sincronización:
Article::query()->update([...])o una eliminación masiva no emiten ninguno. Llama apublishToSocial()en los modelos afectados, o guárdalos uno a uno. - Una imagen por post, y una por red. Ni galería, ni vídeo.
- X se declara, no se publica. Un modelo puede declarar X: mientras la API no publique allí, un destino implícito lo descarta, y un
to: ['x']explícito se rechaza (SocialPostRejected). - La fecha de publicación se ignora en los modos
draftyapproval: no se envía en ellos. - Todavía no hay primer comentario. Ninguna red lo publica: la API ignora el comentario común y rechaza el que se fija para una sola red.
- Un post que ya salió no se corrige. Una modificación hecha tras la publicación emite
SocialPostOutdated, y nada más.
Versiones
El paquete sigue el versionado semántico. Antes de la 1.0, una versión menor puede cambiar la API pública; el registro de cambios del paquete (CHANGELOG.md) dice qué ha cambiado. Esta documentación describe la versión 0.1, que funciona con la versión 1 de la API (/api/v1).
El código fuente se publica en GitHub, como espejo de solo lectura: allí las pull requests se cierran, las issues son bienvenidas. Su composer.json declara un repositorio path (../php-social), que sirve para desarrollar el paquete junto al SDK: Composer solo lee los repositorios del proyecto raíz, así que no afecta a una instalación con composer require.