PHPackages                             fenixthelord/laravel-facebook-automation - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. fenixthelord/laravel-facebook-automation

ActiveLibrary

fenixthelord/laravel-facebook-automation
========================================

Automated Facebook Page product publishing, first-comment links, private replies, webhooks, AI copywriting, queues, scheduling, and a Filament 5 control panel for Laravel.

v0.1.0-beta.3(yesterday)01↑2900%MITPHPPHP ^8.3CI passing

Since Jul 28Pushed yesterdayCompare

[ Source](https://github.com/fenixthelord/laravel-facebook-automation)[ Packagist](https://packagist.org/packages/fenixthelord/laravel-facebook-automation)[ Docs](https://github.com/fenixthelord/laravel-facebook-automation)[ RSS](/packages/fenixthelord-laravel-facebook-automation/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (7)Versions (4)Used By (0)

Laravel Facebook Automation
===========================

[](#laravel-facebook-automation)

[العربية](README.ar.md)

A reusable Laravel + Filament 5 package for Facebook Page automation.

It can prepare product posts before their publish time, generate safe marketing copy with OpenAI or a deterministic template, publish product images, place the product URL in the first Page comment, process Page webhooks, send a private Messenger reply, and optionally add a public reply below the customer comment.

> Status: public beta. Use a review workflow and a test Page before enabling full automatic publishing.

Features
--------

[](#features)

- Automatic product selection with repeat protection.
- Scheduled preparation before the publish time.
- Review mode or fully automatic mode.
- OpenAI Responses API copy generation.
- Deterministic template fallback when OpenAI is disabled or unavailable.
- Public-caption policy that removes prices, old prices, discounts, URLs, and “no specifications” placeholders.
- Price and product details in the private reply only.
- Product URL in the first Page comment.
- Signed Meta webhook verification.
- Private Messenger replies from Page comments.
- Optional public comment replies.
- Wildcard reply rule: any customer comment can trigger the private reply.
- Idempotent queue jobs and duplicate-post protection.
- Filament resources for posts, reply rules, reply logs, and settings.
- Feature switches for every major automation capability.
- Generic product integration through configuration or a custom provider.
- Laravel package auto-discovery.

Requirements
------------

[](#requirements)

- PHP 8.3+
- Laravel 12 or 13
- Filament 5
- A database-backed queue for production is recommended
- A Meta app connected to a Facebook Page

Installation
------------

[](#installation)

```
composer require fenixthelord/laravel-facebook-automation:^0.1@beta
```

Run the installer:

```
php artisan facebook-automation:install --migrate
```

For a non-standard product schema, publish a ready-to-edit provider starter too:

```
php artisan facebook-automation:install --migrate --provider
```

The package service provider is discovered automatically by Laravel.

Environment variables
---------------------

[](#environment-variables)

Add these values to `.env`:

```
FACEBOOK_AUTOMATION_ENABLED=true

FACEBOOK_APP_ID=
FACEBOOK_APP_SECRET=
FACEBOOK_PAGE_ID=
FACEBOOK_PAGE_ACCESS_TOKEN=
FACEBOOK_VERIFY_TOKEN=
FACEBOOK_GRAPH_VERSION=v25.0

FACEBOOK_AUTOMATION_MODE=review
FACEBOOK_AUTOMATION_TIMEZONE=Asia/Damascus
FACEBOOK_AUTOMATION_TIMES=09:00,12:00,15:00,18:00,21:00
FACEBOOK_AUTOMATION_PREPARE_MINUTES=30
FACEBOOK_AUTOMATION_GRACE_MINUTES=15
FACEBOOK_AUTOMATION_REPEAT_DAYS=30
FACEBOOK_AUTOMATION_MAX_IMAGES=4
FACEBOOK_AUTOMATION_QUEUE=facebook
FACEBOOK_AUTOMATION_FILAMENT_PANELS=admin

OPENAI_API_KEY=
OPENAI_MODEL=gpt-5-mini
```

Then clear cached configuration:

```
php artisan optimize:clear
php artisan queue:restart
```

Meta permissions
----------------

[](#meta-permissions)

The exact permissions available depend on your Meta app use case and review state. The package features normally require:

```
pages_show_list
pages_read_engagement
pages_manage_metadata
pages_manage_posts
pages_manage_engagement
pages_messaging

```

The Page access token must belong to the configured Page and include the permissions needed by the features you enable.

Never commit or publish Meta tokens.

Webhook
-------

[](#webhook)

The package registers:

```
GET|POST /facebook-automation/webhook

```

Default callback URL:

```
https://your-domain.test/facebook-automation/webhook

```

Use the same value from `FACEBOOK_VERIFY_TOKEN` when configuring the Meta webhook.

Subscribe the Page webhook to the `feed` field so comment events reach the package.

Signature validation uses `X-Hub-Signature-256` and `FACEBOOK_APP_SECRET`. It is enabled by default.

Queue worker
------------

[](#queue-worker)

Production:

```
php artisan queue:work \
  --queue=facebook,default \
  --sleep=2 \
  --tries=3 \
  --timeout=180
```

Supervisor example:

```
[program:facebook-automation]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/app/artisan queue:work --queue=facebook,default --sleep=2 --tries=3 --timeout=180
user=www-data
numprocs=1
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
redirect_stderr=true
stdout_logfile=/var/www/app/storage/logs/facebook-automation-worker.log
stopwaitsecs=3600
```

Shared hosting Cron example:

```
* * * * * cd /home/USER/app && php artisan schedule:run >> storage/logs/facebook-automation-scheduler.log 2>&1
* * * * * flock -n /tmp/facebook-automation-queue.lock -c "cd /home/USER/app && php artisan queue:work --queue=facebook,default --stop-when-empty --sleep=1 --tries=3 --timeout=180 --max-time=240 >> storage/logs/facebook-automation-queue.log 2>&1"
```

Do not paste the five Cron stars into the cPanel **Command** field. cPanel provides the schedule fields separately.

Scheduler
---------

[](#scheduler)

The package registers these Laravel scheduled commands automatically:

```
facebook-automation:prepare
facebook-automation:publish-due

```

Both run every minute when:

```
'facebook-automation.schedule.register' => true
```

Example with a publish time of `10:00` and `prepare_minutes=30`:

```
09:30  product selected and post generated
09:30  post appears in Filament for optional review
10:00  latest saved version is published automatically
10:00  Page adds the product-link comment

```

In `review` mode, the post remains a draft. In `automatic` mode, it publishes at the scheduled time.

Filament panel
--------------

[](#filament-panel)

The package automatically registers itself in the configured panel IDs:

```
FACEBOOK_AUTOMATION_FILAMENT_PANELS=admin
```

Pages:

```
Facebook Automation
├── Product Posts
├── Auto Replies
├── Reply Log
└── Settings

```

To register the plugin manually instead, disable automatic registration:

```
FACEBOOK_AUTOMATION_FILAMENT=false
```

Then add it to a panel provider:

```
use Fenixthelord\FacebookAutomation\FacebookAutomationPlugin;

public function panel(\Filament\Panel $panel): \Filament\Panel
{
    return $panel
        ->plugin(FacebookAutomationPlugin::make());
}
```

Product integration
-------------------

[](#product-integration)

A package cannot safely guess every application's product schema. This package provides two integration modes.

### Option A: configuration-only integration

[](#option-a-configuration-only-integration)

Publish the config:

```
php artisan vendor:publish --tag=facebook-automation-config
```

Configure the model and mapping in `config/facebook-automation.php`:

```
'products' => [
    'model' => App\Models\Product::class,

    'columns' => [
        'title' => 'name',
        'sku' => 'sku',
        'short_description' => 'short_description',
        'description' => 'description',
        'price' => 'price',
        'old_price' => 'old_price',
        'quantity' => 'quantity',
        'condition' => 'condition_label',
        'stock_label' => 'stock_label',
        'featured' => 'is_featured',
        'active' => null,
        'published' => null,
        'url' => null,
    ],

    'scopes' => [
        'eligible' => null,
        'published' => 'published',
        'available' => 'available',
    ],

    'relations' => [
        'images' => 'images',
        'category' => 'category',
    ],

    'images' => [
        'disk' => 'public',
        'path_column' => 'path',
        'url_column' => 'url',
        'primary_column' => 'is_primary',
        'sort_column' => 'sort_order',
    ],

    'url' => [
        'route_name' => 'products.show',
        'route_parameter' => 'product',
        'route_key_column' => 'slug',
    ],
],
```

The default provider loads the configured image and category relations, excludes recently published products, and maps the model to package-owned product data.

### Option B: custom provider

[](#option-b-custom-provider)

For an unusual schema, implement:

```
Fenixthelord\FacebookAutomation\Contracts\ProductProvider
```

A complete starter exists at:

```
stubs/CustomProductProvider.php.stub

```

Register it in the published config:

```
'products' => [
    'provider' => App\Facebook\CustomProductProvider::class,
],
```

### Model contract

[](#model-contract)

A product model may also implement:

```
Fenixthelord\FacebookAutomation\Contracts\FacebookPostable
```

and return a `ProductData` object from:

```
public function toFacebookAutomationProductData(): ProductData
```

Content safety policy
---------------------

[](#content-safety-policy)

The package enforces these rules again immediately before publishing:

- No price in the public post.
- No old price or discount line in the public post.
- No external URL in the public post.
- No “no specifications are recorded” placeholder.
- No required keyword such as “write price”.
- The CTA asks for any comment.
- Price and product URL remain available in the private message.
- The product URL is published in the first Page comment.

This protects template-generated content, AI-generated content, and manually edited drafts.

Feature switches
----------------

[](#feature-switches)

All switches are available in Filament and through config:

```
'features' => [
    'automatic_posts' => true,
    'ai_generation' => true,
    'template_fallback' => true,
    'private_replies' => true,
    'public_replies' => true,
    'link_comment' => true,
    'validate_webhook_signature' => true,
    'allow_text_only_when_images_fail' => false,
],
```

Credentials remain in `.env`; the Filament settings page stores non-secret operational settings only.

Commands
--------

[](#commands)

Check the installation:

```
php artisan facebook-automation:doctor --facebook
```

Prepare a due scheduled post:

```
php artisan facebook-automation:prepare
```

Generate a specific product immediately without publishing:

```
php artisan facebook-automation:prepare --force --product=123
```

Generate and publish a specific product:

```
php artisan facebook-automation:prepare --force --product=123 --publish
```

Queue prepared posts whose time has arrived:

```
php artisan facebook-automation:publish-due
```

Programmatic usage
------------------

[](#programmatic-usage)

Using the facade:

```
use FacebookAutomation;

$post = FacebookAutomation::createForProduct(
    productId: 123,
    scheduledFor: now()->addHour()->toImmutable(),
    autoPublish: true,
);
```

Using dependency injection:

```
use Fenixthelord\FacebookAutomation\Services\FacebookAutomationManager;

public function publish(FacebookAutomationManager $automation)
{
    return $automation->createForProduct(
        productId: request('product_id'),
        scheduledFor: now()->toImmutable(),
        autoPublish: true,
    );
}
```

Events
------

[](#events)

```
FacebookPostPrepared
FacebookPostPublished
FacebookReplySent

```

Listeners can use these events for analytics, notifications, or audit logs.

Troubleshooting
---------------

[](#troubleshooting)

### Post generation provider is `template`

[](#post-generation-provider-is-template)

OpenAI was disabled, the API key was missing, or the API request failed. Inspect:

```
generation_meta.generation_error

```

### Facebook error 190 / subcode 463

[](#facebook-error-190--subcode-463)

The Page access token expired or was invalidated. Generate a valid Page token, update `.env`, then run:

```
php artisan optimize:clear
php artisan queue:restart
```

### Permission error 200

[](#permission-error-200)

The Page token does not contain the permission required by the attempted feature. Confirm the Meta use case, Page access, app review state, and token scopes.

### Jobs remain pending

[](#jobs-remain-pending)

A scheduler only dispatches jobs. A queue worker must also run.

```
php artisan queue:work --queue=facebook,default
```

### Webhook returns 403

[](#webhook-returns-403)

Confirm:

```
FACEBOOK_VERIFY_TOKEN=
FACEBOOK_APP_SECRET=
```

and verify that Meta uses the exact callback URL generated by:

```
php artisan route:list --name=facebook-automation
```

Testing
-------

[](#testing)

```
composer install
composer check
```

The test suite uses Orchestra Testbench.

Publishing this package
-----------------------

[](#publishing-this-package)

See [PUBLISHING.md](PUBLISHING.md) for complete GitHub, version tag, Packagist, and webhook instructions.

First beta tag:

```
git tag -a v0.1.0-beta.1 -m "First public beta"
git push origin v0.1.0-beta.1
```

Packagist install command after submission:

```
composer require fenixthelord/laravel-facebook-automation:^0.1@beta
```

Security
--------

[](#security)

- Keep all secrets in `.env`.
- Never print tokens in logs.
- Rotate any token exposed in a screenshot or commit.
- Keep webhook signature validation enabled.
- Give the Meta token only the permissions required by enabled features.

Licence
-------

[](#licence)

MIT. See [LICENSE](LICENSE).

---

بدء سريع بالعربية
-----------------

[](#بدء-سريع-بالعربية)

```
composer require fenixthelord/laravel-facebook-automation:^0.1@beta
php artisan facebook-automation:install --migrate
```

ضع مفاتيح Meta في `.env`، واضبط Product model من `config/facebook-automation.php`، ثم شغّل:

```
php artisan facebook-automation:doctor --facebook
php artisan queue:work --queue=facebook,default --tries=3 --timeout=180
```

البكج يسجل جدولة التحضير والنشر تلقائياً. على السيرفر يجب أن يكون `schedule:run` والـQueue Worker شغالين باستمرار أو عبر Cron.

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance100

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity36

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

3

Last Release

1d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/7e58b5b78540441e8aa5b4c953b33f54d699e7ffa7eaf3aae6f1c1a1633118d7?d=identicon)[DextePHP](/maintainers/DextePHP)

---

Top Contributors

[![fenixthelord](https://avatars.githubusercontent.com/u/7693624?v=4)](https://github.com/fenixthelord "fenixthelord (3 commits)")

---

Tags

laravelautomationfacebookopenaiwebhookecommercemetaMessengersocial mediafilament

###  Code Quality

TestsPHPUnit

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/fenixthelord-laravel-facebook-automation/health.svg)

```
[![Health](https://phpackages.com/badges/fenixthelord-laravel-facebook-automation/health.svg)](https://phpackages.com/packages/fenixthelord-laravel-facebook-automation)
```

###  Alternatives

[rawilk/profile-filament-plugin

Profile & MFA starter kit for filament.

3914.8k](/packages/rawilk-profile-filament-plugin)[backstage/mails

View logged mails and events in a beautiful Filament UI.

16321.5k](/packages/backstage-mails)[stephenjude/filament-jetstream

A Laravel starter kit built with Filament inspired by Jetstream.

17760.2k3](/packages/stephenjude-filament-jetstream)[stephenjude/filament-two-factor-authentication

Filament Two Factor Authentication: Google 2FA + Passkey Authentication

84215.9k9](/packages/stephenjude-filament-two-factor-authentication)[marcelweidum/filament-passkeys

Use passkeys in your filamentphp app

6649.5k2](/packages/marcelweidum-filament-passkeys)[slimani/filament-media-manager

A media manager plugin for Filament.

126.9k](/packages/slimani-filament-media-manager)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)