README

A modular, highly-independent Meta (Facebook & Instagram) API SDK and integration package for Laravel.

This package provides a unified interface for interacting with the Meta Graph API, supporting everything from simple automated posts to complex Lead Ads webhooks, without forcing unnecessary database tables into your application.

🌟 Key Features

Facebook Page Publishing: Publish Text, Images, Videos, Carousels, Stories, and Reels (including 3-step chunked upload).
Instagram Publishing: Publish Images, Videos, Carousels, Stories, and Reels (using async container polling). (Note: Meta API requires media for IG, no text-only posts).
Lead Ads & Webhooks: Integrated webhook support for real-time events.
Visual Sandbox: Built-in UI to test tokens, fetch leads, and test posts directly.

🚀 1. Installation

Install the package globally via Composer:

composer require meta-engine/laravel-meta:dev-main

(For Laravel 10.x, 11.x, and 12.x)

⚙️ 2. Configuration

Publish the package configuration file to your application's config/ directory:

php artisan vendor:publish --tag=meta-config

Next, open your application's .env file and add the required Meta credentials:

# Required for App Secret Proof (Security) and core API requests
META_GRAPH_VERSION=v19.0
META_APP_ID=your_meta_app_id
META_APP_SECRET=your_meta_app_secret
META_APPSECRET_PROOF_ENABLED=true

# (Optional) The token generated for your System User
META_SYSTEM_USER_TOKEN=your_long_lived_system_user_token

# (Optional) Enable the visual testing UI (Keep false in production!)
META_SANDBOX_ENABLED=true

🔑 3. Getting Your Token & Permissions

If you do not have a META_SYSTEM_USER_TOKEN yet, you must generate one from the Meta Business Settings.

The token must be a System User Access Token (never a temporary user token) to ensure your server can make automated background requests without expiring.

👉 Click here to read the full Step-by-Step Token & Permissions Guide

🧪 4. Testing Your Integration

This package ships with built-in tools to instantly verify if your connection and token are valid.

Option A: The Visual Sandbox UI (Recommended)

If you added META_SANDBOX_ENABLED=true to your .env, you can test your integration directly from your browser!

Start your local server (php artisan serve).
Go to http://localhost:8000/meta/sandbox.
You will see a beautiful dashboard where you can:
- Validate your token and instantly see what permissions it holds.
- Fetch a test Lead ID directly from Meta.
- Publish a test post to a Facebook Page.

Option B: The Artisan CLI Test

If you prefer the command line, run the built-in diagnostic tool:

php artisan meta:test-token

You will receive a clear pass/fail report confirming if your App ID, Secret, and Token are correctly communicating with the Graph API.

⚡ 5. 1-Click CRM Integration

Want to build a Meta Dashboard directly into your own application? We've automated the entire backend for you!

By simply running:

php artisan meta:install-crm

The package will instantly scaffold the Database Migrations, Models, and a full API Controller directly into your application.

What about the UI? Because every app uses a different frontend stack, we leave the UI to you! See our CRM Integration Guide for a simple checklist of the views you need to build to hook into the generated backend.

🏗️ 6. Architecture & Usage Modes

This package natively supports two usage modes depending on your application's architecture:

Direct API Mode (No Database Required)

Your Application directly calls Meta APIs through our services.

Perfect for simple integrations (e.g., just fetching a single lead).
No migrations required (META_DATABASE_ENABLED=false).

// Example: Direct API Lead Retrieval
$lead = Meta::leads()->get('123456789');

// Map the data to your own application tables manually
Lead::create([
    'name' => $lead->getName(),
    'email' => $lead->getEmail(),
]);

Persistent Integration Mode (Advanced)

Provides a robust synchronization layer using local database tables.

Webhook storage and processing.
Event dispatching (e.g., MetaLeadReceived).
Automated Queue scheduling and retries for failed posts.
Requires running package migrations (META_DATABASE_ENABLED=true).

📚 Advanced Documentation

Detailed documentation for specific modules can be found in the docs/ folder:

Developed by ManishNlet77. Open source under the MIT License.

meta-engine / laravel-meta

Package info

Security

Statistics