README

A comprehensive Laravel package for automatic social media publishing across 8 major platforms: Facebook, Twitter/X, LinkedIn, Instagram, TikTok, YouTube, Pinterest, and Telegram. Post to one platform or all platforms simultaneously with a unified API.

🌟 Features

8 Social Media Platforms: Facebook, Twitter/X, LinkedIn, Instagram, TikTok, YouTube, Pinterest, Telegram
Multi-User & Multi-Entity Support: Users, Companies, or any model can connect their own social media accounts and post on their behalf (polymorphic relationships)
OAuth Integration: Built-in OAuth flows for Facebook, LinkedIn, and Twitter
Unified API: Post to multiple platforms with a single command
Individual Platform Access: Direct access to each platform's specific features
Comprehensive Content Types: Text, Images, Videos, Documents, Stories, Carousels
Advanced Analytics: Facebook Page Insights, Twitter Analytics, LinkedIn Metrics
Production Ready: Error handling, retry logic, rate limiting, logging
Laravel Native: Perfect integration with Laravel ecosystem
Extensible: Easy to add new platforms and features

🚀 Installation

Requirements

PHP 8.1 or higher
Laravel 11.0 or higher
Composer

Install via Composer

composer require mantix/laravel-social-media-publisher

Publish Configuration and Migrations

# Publish configuration
php artisan vendor:publish --provider="mantix\LaravelSocialMediaPublisher\SocialShareServiceProvider" --tag=social-media-publisher-config

# Publish migrations
php artisan vendor:publish --provider="mantix\LaravelSocialMediaPublisher\SocialShareServiceProvider" --tag=social-media-publisher-migrations

# Run migrations
php artisan migrate

⚙️ Configuration

Environment Variables

Add the following OAuth credentials to your .env file. These are required for users to authenticate their own social media accounts:

# Facebook (OAuth 2.0)
FACEBOOK_CLIENT_ID=your_facebook_client_id
FACEBOOK_CLIENT_SECRET=your_facebook_client_secret

# Twitter/X (OAuth 2.0)
X_CLIENT_ID=your_x_client_id
X_CLIENT_SECRET=your_x_client_secret
X_API_KEY=your_x_api_key
X_API_SECRET_KEY=your_x_api_secret_key

# LinkedIn (OAuth 2.0)
LINKEDIN_CLIENT_ID=your_linkedin_client_id
LINKEDIN_CLIENT_SECRET=your_linkedin_client_secret

# Instagram (OAuth 2.0)
INSTAGRAM_CLIENT_ID=your_instagram_client_id
INSTAGRAM_CLIENT_SECRET=your_instagram_client_secret

# TikTok (OAuth 2.0)
TIKTOK_CLIENT_ID=your_tiktok_client_id
TIKTOK_CLIENT_SECRET=your_tiktok_client_secret

# YouTube (OAuth 2.0)
YOUTUBE_CLIENT_ID=your_youtube_client_id
YOUTUBE_CLIENT_SECRET=your_youtube_client_secret

# Pinterest (OAuth 2.0)
PINTEREST_CLIENT_ID=your_pinterest_client_id
PINTEREST_CLIENT_SECRET=your_pinterest_client_secret

# Telegram (Bot API - No OAuth required)
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
TELEGRAM_CHAT_ID=your_telegram_chat_id

OAuth Routes Setup

Important: OAuth callback routes are automatically registered by the package and excluded from CSRF protection. You only need to configure the callback URLs in each platform's developer portal.

OAuth Authorization Routes

You need to create authorization routes that redirect users to the OAuth provider. Add these to your routes/web.php:

use Illuminate\Support\Facades\Route;
use Mantix\LaravelSocialMediaPublisher\Services\FacebookService;
use Mantix\LaravelSocialMediaPublisher\Services\LinkedInService;
use Mantix\LaravelSocialMediaPublisher\Services\TwitterService;

// Facebook OAuth (no PKCE support)
Route::get('/auth/facebook', function () {
    $redirectUri = route('social-media.facebook.callback');
    $authUrl = FacebookService::getAuthorizationUrl($redirectUri);
    return redirect($authUrl);
})->name('social-media.facebook.authorize')->middleware('auth');

// LinkedIn OAuth (with optional PKCE)
Route::get('/auth/linkedin', function () {
    $redirectUri = route('social-media.linkedin.callback');
    
    // Option 1: Without PKCE (backward compatible)
    $authUrl = LinkedInService::getAuthorizationUrl($redirectUri);
    return redirect($authUrl);
    
    // Option 2: With PKCE (recommended for security)
    // $authData = LinkedInService::getAuthorizationUrl($redirectUri, [], null, true);
    // session(['linkedin_code_verifier' => $authData['code_verifier']]);
    // return redirect($authData['url']);
})->name('social-media.linkedin.authorize')->middleware('auth');

// Twitter/X OAuth (with PKCE - recommended)
Route::get('/auth/twitter', function () {
    $redirectUri = route('social-media.x.callback');
    
    // PKCE is enabled by default for Twitter/X
    $authData = TwitterService::getAuthorizationUrl($redirectUri);
    
    // Store code verifier in session for callback
    if (is_array($authData)) {
        session(['twitter_code_verifier' => $authData['code_verifier']]);
        return redirect($authData['url']);
    }
    
    // Fallback if PKCE is disabled
    return redirect($authData);
})->name('social-media.twitter.authorize')->middleware('auth');

// Add similar routes for other platforms...

Note: The callback routes (/auth/facebook/callback, /auth/linkedin/callback, etc.) are automatically registered by the package and excluded from CSRF protection. You don't need to define them manually.

Customizing OAuth Callbacks

The package includes a default OAuthController that handles callbacks. To customize the behavior, you can:

Publish the controller (if needed in future versions):

php artisan vendor:publish --tag=social-media-publisher-controller

Configure redirect route after OAuth success/error:
```
SOCIAL_MEDIA_OAUTH_REDIRECT_ROUTE=dashboard
```
Extend the controller in your application if you need custom logic.

Default OAuth Controller Behavior

The default controller:

Automatically saves connections to the social_media_connections table
Requires authenticated users (uses auth()->user())
Redirects to the configured route (default: dashboard) with success/error messages
Handles errors gracefully with logging

OAuth Callback URLs Configuration

Important: You must configure these callback URLs in each platform's developer portal. The callback URLs must match exactly your route URLs (e.g., https://yourdomain.com/auth/facebook/callback).

Facebook

Go to Facebook Developers
Select your app → Settings → Basic
Add your callback URL to "Valid OAuth Redirect URIs"
Example: https://yourdomain.com/auth/facebook/callback

Twitter/X

Go to Twitter Developer Portal
Select your app → Settings → User authentication settings
Add your callback URL to "Callback URI / Redirect URL"
Example: https://yourdomain.com/auth/x/callback

Go to LinkedIn Developers
Select your app → Auth tab
Add your callback URL to "Authorized redirect URLs for your app"
Example: https://yourdomain.com/auth/linkedin/callback

Instagram

Go to Facebook Developers (Instagram uses Facebook's platform)
Select your app → Products → Instagram → Basic Display
Add your callback URL to "Valid OAuth Redirect URIs"
Example: https://yourdomain.com/auth/instagram/callback

TikTok

Go to TikTok Developers
Select your app → Basic Information
Add your callback URL to "Redirect URI"
Example: https://yourdomain.com/auth/tiktok/callback

YouTube

Go to Google Cloud Console
Select your project → APIs & Services → Credentials
Edit your OAuth 2.0 Client ID
Add your callback URL to "Authorized redirect URIs"
Example: https://yourdomain.com/auth/youtube/callback

Go to Pinterest Developers
Select your app → Settings
Add your callback URL to "Redirect URIs"
Example: https://yourdomain.com/auth/pinterest/callback

Configuration File

The published config/social-media-publisher.php file contains all configuration options:

return [
    // Facebook Configuration (OAuth 2.0)
    'facebook_client_id'     => env('FACEBOOK_CLIENT_ID'),
    'facebook_client_secret'  => env('FACEBOOK_CLIENT_SECRET'),
    'facebook_api_version'   => env('FACEBOOK_API_VERSION', 'v20.0'),
    
    // Twitter/X Configuration (OAuth 2.0)
    'x_client_id'        => env('X_CLIENT_ID'),
    'x_client_secret'    => env('X_CLIENT_SECRET'),
    'x_api_key'          => env('X_API_KEY'),
    'x_api_secret_key'   => env('X_API_SECRET_KEY'),
    
    // ... other platform configurations
    
    // General settings
    'enable_logging' => env('SOCIAL_MEDIA_LOGGING', true),
    'timeout' => env('SOCIAL_MEDIA_TIMEOUT', 30),
    'retry_attempts' => env('SOCIAL_MEDIA_RETRY_ATTEMPTS', 3),
    
    // OAuth settings
    'oauth_redirect_route' => env('SOCIAL_MEDIA_OAUTH_REDIRECT_ROUTE', 'dashboard'),
];

🎯 Quick Start

Basic Usage

Note: All posting requires OAuth 2.0 connections. Users must authenticate their social media accounts through OAuth before posting. This is the only supported authentication method (except Telegram which uses Bot API).

use Mantix\LaravelSocialMediaPublisher\Exceptions\SocialMediaException;

// Post to multiple platforms (requires OAuth connections)
$user = User::find(1);

// Text-only posts
$result = SocialMedia::shareText($user, ['facebook', 'twitter'], 'Hello World!');

// Posts with URL
$result = SocialMedia::shareUrl($user, ['facebook', 'twitter', 'linkedin'], 'Hello World!', 'https://example.com');

// Share images
$result = SocialMedia::shareImage($user, ['instagram', 'pinterest'], 'Check this out!', 'https://example.com/image.jpg');

// Share videos
$result = SocialMedia::shareVideo($user, ['youtube', 'tiktok'], 'Watch this!', 'https://example.com/video.mp4');

Multi-User & Multi-Entity Support

The package supports polymorphic relationships, allowing any model (User, Company, etc.) to have social media connections:

use Mantix\LaravelSocialMediaPublisher\Facades\SocialMedia;

// Post on behalf of a User
$user = User::find(1);
$result = SocialMedia::shareUrl($user, ['facebook', 'twitter'], 'Hello World!', 'https://example.com');

// Post on behalf of a Company
$company = Company::find(1);
$result = SocialMedia::shareUrl($company, ['facebook', 'linkedin'], 'Company Update!', 'https://example.com');

// Get owner-specific platform service
$facebookService = SocialMedia::platform('facebook', $user);
$facebookService->shareUrl('Hello', 'https://example.com');

// Or using class name and ID
$result = SocialMedia::shareUrl(Company::class, ['facebook'], 'Update', 'https://example.com', $companyId);

Note: All posting requires OAuth 2.0 connections. Users must authenticate their social media accounts through OAuth before posting. OAuth is the only supported authentication method (except Telegram which uses Bot API).

Using the HasSocialMediaConnections Trait

For easier integration, you can use the HasSocialMediaConnections trait on your custom models. This trait provides convenient methods for accessing social media connections:

use Illuminate\Database\Eloquent\Model;
use Mantix\LaravelSocialMediaPublisher\Traits\HasSocialMediaConnections;

class User extends Model
{
    use HasSocialMediaConnections;
    
    // ... rest of your model
}

class Company extends Model
{
    use HasSocialMediaConnections;
    
    // ... rest of your model
}

Once the trait is added, you can use the following methods:

$user = User::find(1);

// Get all social media connections
$connections = $user->social_media_connections;

// Get platform-specific connections
$linkedinConnection = $user->social_connection_linkedin;
$facebookConnection = $user->social_connection_facebook;
$instagramConnection = $user->social_connection_instagram;
$xConnection = $user->social_connection_x;

// Get active connection for a specific platform
$facebookConnection = $user->getSocialConnection('facebook');

// Check if user has active connection for a platform
if ($user->hasSocialConnection('linkedin')) {
    // User has an active LinkedIn connection
    $linkedinService = SocialMedia::platform('linkedin', $user);
    $linkedinService->shareUrl('Hello LinkedIn!', 'https://example.com');
}

// Use in queries
$usersWithFacebook = User::whereHas('social_media_connections', function ($query) {
    $query->where('platform', 'facebook')->where('is_active', true);
})->get();

Available Trait Methods:

social_media_connections(): MorphMany - Get all social media connections
social_connection_linkedin(): HasOne - Get latest LinkedIn connection
social_connection_instagram(): HasOne - Get latest Instagram connection
social_connection_facebook(): HasOne - Get latest Facebook connection
social_connection_x(): HasOne - Get latest X (Twitter) connection
getSocialConnection(string $platform): ?SocialMediaConnection - Get active connection for platform
hasSocialConnection(string $platform): bool - Check if model has active connection

Individual Platform Access

Note: All platform services require OAuth connections. Use SocialMedia::platform() with an owner to get a service instance.

use Mantix\LaravelSocialMediaPublisher\Facades\SocialMedia;

// Get platform service for a user with OAuth connection
$user = User::find(1);

// Facebook
$facebookService = SocialMedia::platform('facebook', $user);
$facebookService->shareText('Hello Facebook!');
$facebookService->shareUrl('Hello Facebook!', 'https://example.com');
$facebookService->shareImage('Check this image!', 'https://example.com/image.jpg');

// Twitter
$twitterService = SocialMedia::platform('twitter', $user);
$twitterService->shareText('Hello Twitter!');
$twitterService->shareUrl('Hello Twitter!', 'https://example.com');

// LinkedIn
$linkedinService = SocialMedia::platform('linkedin', $user);
$linkedinService->shareText('Hello LinkedIn!');
$linkedinService->shareUrl('Hello LinkedIn!', 'https://example.com');
$linkedinService->shareToCompanyPage('Company update!', 'https://example.com');

📖 Usage

Multi-User OAuth Flow

1. Get Authorization URL

Basic OAuth (Without PKCE)

use Mantix\LaravelSocialMediaPublisher\Services\FacebookService;
use Mantix\LaravelSocialMediaPublisher\Services\LinkedInService;

// Facebook OAuth (no PKCE support)
$redirectUri = route('social-media.facebook.callback');
$authUrl = FacebookService::getAuthorizationUrl($redirectUri);
return redirect($authUrl);

// LinkedIn OAuth (without PKCE - backward compatible)
$redirectUri = route('social-media.linkedin.callback');
$authUrl = LinkedInService::getAuthorizationUrl($redirectUri);
return redirect($authUrl);

OAuth with PKCE (Recommended for LinkedIn and Twitter/X)

use Mantix\LaravelSocialMediaPublisher\Services\LinkedInService;
use Mantix\LaravelSocialMediaPublisher\Services\TwitterService;

// LinkedIn OAuth with PKCE
$redirectUri = route('social-media.linkedin.callback');
$authData = LinkedInService::getAuthorizationUrl(
    $redirectUri,
    ['r_liteprofile', 'r_emailaddress', 'w_member_social'], // scopes
    null,  // state (auto-generated if null)
    true,  // enable PKCE
    null   // code_verifier (auto-generated if null)
);

// Store code verifier in session for callback
session(['linkedin_code_verifier' => $authData['code_verifier']]);

// Redirect to authorization URL
return redirect($authData['url']);

// Twitter/X OAuth with PKCE (enabled by default)
$redirectUri = route('social-media.x.callback');
$authData = TwitterService::getAuthorizationUrl($redirectUri);

// Store code verifier in session
if (is_array($authData)) {
    session(['twitter_code_verifier' => $authData['code_verifier']]);
    return redirect($authData['url']);
}

2. OAuth Callbacks (Automatic)

The package automatically handles OAuth callbacks! When users authorize your app, they'll be redirected back to your application, and the connection will be automatically saved to the social_media_connections table.

The default OAuthController handles:

Token exchange
Connection saving
Error handling
Redirects with success/error messages

No additional code needed - just configure the callback URLs in each platform's developer portal (see below).

3. Refresh Access Tokens

For Platforms with Refresh Tokens (LinkedIn, Twitter/X)

use Mantix\LaravelSocialMediaPublisher\Services\LinkedInService;
use Mantix\LaravelSocialMediaPublisher\Services\TwitterService;
use Mantix\LaravelSocialMediaPublisher\Models\SocialMediaConnection;

// Refresh LinkedIn token
$connection = SocialMediaConnection::where('platform', 'linkedin')
    ->where('owner_id', $userId)
    ->first();

if ($connection && $connection->refresh_token) {
    $refreshToken = $connection->getDecryptedRefreshToken();
    
    try {
        $newTokens = LinkedInService::refreshAccessToken($refreshToken);
        
        // Update connection with new tokens
        $connection->update([
            'access_token' => $newTokens['access_token'],
            'refresh_token' => $newTokens['refresh_token'] ?? $refreshToken,
            'expires_at' => now()->addSeconds($newTokens['expires_in'] ?? 3600),
        ]);
    } catch (\Exception $e) {
        // Handle refresh failure - may need to re-authenticate
    }
}

// Refresh Twitter/X token
$connection = SocialMediaConnection::where('platform', 'twitter')
    ->where('owner_id', $userId)
    ->first();

if ($connection && $connection->refresh_token) {
    $refreshToken = $connection->getDecryptedRefreshToken();
    $newTokens = TwitterService::refreshAccessToken($refreshToken);
    
    $connection->update([
        'access_token' => $newTokens['access_token'],
        'refresh_token' => $newTokens['refresh_token'] ?? $refreshToken,
        'expires_at' => now()->addSeconds($newTokens['expires_in'] ?? 7200),
    ]);
}

For Platforms with Token Extension (Facebook, Instagram)

use Mantix\LaravelSocialMediaPublisher\Services\FacebookService;
use Mantix\LaravelSocialMediaPublisher\Services\InstagramService;

// Extend Facebook token (short-lived to long-lived)
$connection = SocialMediaConnection::where('platform', 'facebook')
    ->where('owner_id', $userId)
    ->first();

if ($connection) {
    $shortLivedToken = $connection->getDecryptedAccessToken();
    
    try {
        // Extend to long-lived token (60 days)
        $longLivedTokens = FacebookService::extendAccessToken($shortLivedToken);
        // OR use the alias for consistency
        // $longLivedTokens = FacebookService::refreshAccessToken($shortLivedToken);
        
        $connection->update([
            'access_token' => $longLivedTokens['access_token'],
            'expires_at' => now()->addSeconds($longLivedTokens['expires_in'] ?? 5184000), // 60 days
        ]);
    } catch (\Exception $e) {
        // Handle extension failure
    }
}

// Extend Instagram token (same as Facebook)
$connection = SocialMediaConnection::where('platform', 'instagram')
    ->where('owner_id', $userId)
    ->first();

if ($connection) {
    $shortLivedToken = $connection->getDecryptedAccessToken();
    $longLivedTokens = InstagramService::extendAccessToken($shortLivedToken);
    
    $connection->update([
        'access_token' => $longLivedTokens['access_token'],
        'expires_at' => now()->addSeconds($longLivedTokens['expires_in'] ?? 5184000),
    ]);
}

Note: Facebook and Instagram don't use refresh tokens. When a long-lived token expires (after 60 days), users must re-authenticate.

4. Disconnect from Platform

use Mantix\LaravelSocialMediaPublisher\Services\FacebookService;
use Mantix\LaravelSocialMediaPublisher\Services\LinkedInService;
use Mantix\LaravelSocialMediaPublisher\Models\SocialMediaConnection;

// Disconnect for a user
$user = User::find($userId);
$connection = SocialMediaConnection::forOwner($user)
    ->where('platform', 'facebook')
    ->first();

// Or disconnect for a company
$company = Company::find($companyId);
$connection = SocialMediaConnection::forOwner($company)
    ->where('platform', 'facebook')
    ->first();

if ($connection) {
    // Revoke access token
    FacebookService::disconnect($connection->getDecryptedAccessToken());
    
    // Delete connection
    $connection->delete();
}

Unified API

The SocialMedia facade provides a unified interface for publishing to multiple platforms:

Share to Multiple Platforms

Note: All methods require an owner with OAuth connections. The owner is always the first parameter.

use Mantix\LaravelSocialMediaPublisher\Facades\SocialMedia;

// Post to specific platforms (requires owner with OAuth connections)
$user = User::find(1);

// Text-only posts
$result = SocialMedia::shareText($user, ['facebook', 'twitter'], 'Hello World!');

// Posts with URL
$result = SocialMedia::shareUrl($user, ['facebook', 'twitter', 'linkedin'], 'Content', 'https://example.com');

// Share images to visual platforms
$result = SocialMedia::shareImage($user, ['instagram', 'pinterest'], 'Caption', 'https://example.com/image.jpg');

// Share videos to video platforms
$result = SocialMedia::shareVideo($user, ['youtube', 'tiktok'], 'Caption', 'https://example.com/video.mp4');

Share to All Platforms

// Post to all available platforms (requires owner with OAuth connections)
$user = User::find(1);
$allPlatforms = SocialMedia::getAvailablePlatforms();

// Text-only posts to all platforms
$result = SocialMedia::shareText($user, $allPlatforms, 'Hello World!');

// Posts with URL to all platforms
$result = SocialMedia::shareUrl($user, $allPlatforms, 'Content', 'https://example.com');

// Share images to all platforms
$result = SocialMedia::shareImage($user, $allPlatforms, 'Caption', 'https://example.com/image.jpg');

// Share videos to all platforms
$result = SocialMedia::shareVideo($user, $allPlatforms, 'Caption', 'https://example.com/video.mp4');

Platform-Specific Access

// Access individual platforms (requires owner with OAuth connection)
$user = User::find(1);
$facebookService = SocialMedia::platform('facebook', $user);
$twitterService = SocialMedia::platform('twitter', $user);
$linkedinService = SocialMedia::platform('linkedin', $user);

// Use platform-specific methods
$result = SocialMedia::platform('linkedin', $user)->shareToCompanyPage('Content', 'https://example.com');
$result = SocialMedia::platform('instagram', $user)->shareCarousel('Caption', ['img1.jpg', 'img2.jpg']);
$result = SocialMedia::platform('facebook', $user)->shareText('Text-only post!');

Individual Platforms

Note: All platform services require OAuth connections. Use SocialMedia::platform($platform, $owner) to get a service instance for a specific owner.

Each platform service provides specific methods:

Facebook

use Mantix\LaravelSocialMediaPublisher\Facades\SocialMedia;

// Get service for a user (requires OAuth connection)
$user = User::find(1);
$facebook = SocialMedia::platform('facebook', $user);

// Basic publishing
$facebook->shareText('Text-only post!');
$facebook->shareUrl('Content', 'https://example.com');
$facebook->shareImage('Caption', 'https://example.com/image.jpg');
$facebook->shareVideo('Caption', 'https://example.com/video.mp4');

// Analytics
$insights = $facebook->getPageInsights(['page_impressions', 'page_engaged_users']);
$pageInfo = $facebook->getPageInfo();

Twitter/X

use Mantix\LaravelSocialMediaPublisher\Facades\SocialMedia;

// Get service for a user (requires OAuth connection)
$user = User::find(1);
$twitter = SocialMedia::platform('twitter', $user);

// Publishing
$twitter->shareText('Text-only tweet!');
$twitter->shareUrl('Content', 'https://example.com');
$twitter->shareImage('Caption', 'https://example.com/image.jpg');
$twitter->shareVideo('Caption', 'https://example.com/video.mp4');

// Analytics
$timeline = $twitter->getTimeline(10);
$userInfo = $twitter->getUserInfo();

use Mantix\LaravelSocialMediaPublisher\Facades\SocialMedia;

// Get service for a user (requires OAuth connection)
$user = User::find(1);
$linkedin = SocialMedia::platform('linkedin', $user);

// Personal posts
$linkedin->shareText('Text-only post!');
$linkedin->shareUrl('Content', 'https://example.com');
$linkedin->shareImage('Caption', 'https://example.com/image.jpg');
$linkedin->shareVideo('Caption', 'https://example.com/video.mp4');

// Company page posts
$linkedin->shareToCompanyPage('Content', 'https://example.com');

// User info
$userInfo = $linkedin->getUserInfo();

Instagram

use Mantix\LaravelSocialMediaPublisher\Facades\SocialMedia;

// Get service for a user (requires OAuth connection)
$user = User::find(1);
$instagram = SocialMedia::platform('instagram', $user);

// Posts
$instagram->shareImage('Caption', 'https://example.com/image.jpg');
$instagram->shareVideo('Caption', 'https://example.com/video.mp4');

// Carousel posts
$instagram->shareCarousel('Caption', ['img1.jpg', 'img2.jpg', 'img3.jpg']);

// Stories
$instagram->shareStory('Caption', 'https://example.com');

// Analytics
$accountInfo = $instagram->getAccountInfo();
$recentMedia = $instagram->getRecentMedia(25);

TikTok

use Mantix\LaravelSocialMediaPublisher\Facades\SocialMedia;

// Get service for a user (requires OAuth connection)
$user = User::find(1);
$tiktok = SocialMedia::platform('tiktok', $user);

// Video publishing
$tiktok->shareVideo('Caption', 'https://example.com/video.mp4');

// Analytics
$userInfo = $tiktok->getUserInfo();
$userVideos = $tiktok->getUserVideos(20);

YouTube

use Mantix\LaravelSocialMediaPublisher\Facades\SocialMedia;

// Get service for a user (requires OAuth connection)
$user = User::find(1);
$youtube = SocialMedia::platform('youtube', $user);

// Video uploads
$youtube->shareVideo('Title', 'https://example.com/video.mp4');

// Community posts
$youtube->createCommunityPost('Content', 'https://example.com');

// Analytics
$channelInfo = $youtube->getChannelInfo();
$channelVideos = $youtube->getChannelVideos(25);
$videoAnalytics = $youtube->getVideoAnalytics('video_id');

use Mantix\LaravelSocialMediaPublisher\Facades\SocialMedia;

// Get service for a user (requires OAuth connection)
$user = User::find(1);
$pinterest = SocialMedia::platform('pinterest', $user);

// Pins
$pinterest->shareUrl('Caption', 'https://example.com');
$pinterest->shareImage('Caption', 'https://example.com/image.jpg');
$pinterest->shareVideo('Caption', 'https://example.com/video.mp4');

// Boards
$pinterest->createBoard('Board Name', 'Description');

// Analytics
$userInfo = $pinterest->getUserInfo();
$boards = $pinterest->getBoards(25);
$boardPins = $pinterest->getBoardPins('board_id', 25);
$pinAnalytics = $pinterest->getPinAnalytics('pin_id');

use Mantix\LaravelSocialMediaPublisher\Facades\SocialMedia;

// Get service for a user (requires OAuth connection)
$user = User::find(1);
$telegram = SocialMedia::platform('telegram', $user);

// Messages
$telegram->shareText('Text-only message!');
$telegram->shareUrl('Content', 'https://example.com');
$telegram->shareImage('Caption', 'https://example.com/image.jpg');
$telegram->shareVideo('Caption', 'https://example.com/video.mp4');
$telegram->shareDocument('Caption', 'https://example.com/document.pdf');

// Bot updates
$updates = $telegram->getUpdates();

Platform-Specific Features

Facebook Analytics

use Mantix\LaravelSocialMediaPublisher\Facades\SocialMedia;

$user = User::find(1);
$facebook = SocialMedia::platform('facebook', $user);

// Get page insights
$insights = $facebook->getPageInsights([
    'page_impressions',
    'page_engaged_users',
    'page_fan_adds'
]);

// Get insights for specific date range
$insights = $facebook->getPageInsights(
    ['page_impressions', 'page_engaged_users'],
    ['since' => '2024-01-01', 'until' => '2024-01-31']
);

Instagram Carousels

use Mantix\LaravelSocialMediaPublisher\Facades\SocialMedia;

$user = User::find(1);
$instagram = SocialMedia::platform('instagram', $user);

// Create carousel with multiple images
$images = [
    'https://example.com/image1.jpg',
    'https://example.com/image2.jpg',
    'https://example.com/image3.jpg'
];
$result = $instagram->shareCarousel('Check out our products!', $images);

LinkedIn Company Pages

use Mantix\LaravelSocialMediaPublisher\Facades\SocialMedia;

$user = User::find(1);
$linkedin = SocialMedia::platform('linkedin', $user);

// Post to company page (requires organization URN)
$linkedin->shareToCompanyPage('Company update: We\'re hiring!', 'https://example.com/careers');

YouTube Community Posts

use Mantix\LaravelSocialMediaPublisher\Facades\SocialMedia;

$user = User::find(1);
$youtube = SocialMedia::platform('youtube', $user);

// Create community post
$youtube->createCommunityPost('What would you like to see in our next video?', 'https://example.com/poll');

Pinterest Boards

use Mantix\LaravelSocialMediaPublisher\Facades\SocialMedia;

$user = User::find(1);
$pinterest = SocialMedia::platform('pinterest', $user);

// Create board
$pinterest->createBoard('My Recipes', 'Collection of amazing recipes', 'PUBLIC');

// Get board pins
$pins = $pinterest->getBoardPins('board_id', 25);

🔧 Advanced Features

Error Handling

The package provides comprehensive error handling:

use Mantix\LaravelSocialMediaPublisher\Facades\SocialMedia;
use Mantix\LaravelSocialMediaPublisher\Exceptions\SocialMediaException;

try {
    $user = User::find(1);
    $result = SocialMedia::shareUrl($user, ['facebook', 'twitter'], 'Content', 'https://example.com');
    
    // Check results
    if ($result['error_count'] > 0) {
        foreach ($result['errors'] as $platform => $error) {
            echo "Error on {$platform}: {$error}\n";
        }
    }
    
} catch (SocialMediaException $e) {
    echo "Social media error: " . $e->getMessage();
}

Retry Logic

The package automatically retries failed requests with exponential backoff:

// Configure timeout
config(['social_media_publisher.timeout' => 60]);

Logging

All operations are automatically logged:

// Enable/disable logging
config(['social_media_publisher.enable_logging' => true]);

// Check Laravel logs for detailed information
tail -f storage/logs/laravel.log

Input Validation

The package validates all inputs:

// Validates URLs
// Validates text length
// Validates required parameters
// Throws SocialMediaException for invalid inputs

🧪 Testing

Run Tests

# Run all tests
./vendor/bin/phpunit

# Run specific test suite
./vendor/bin/phpunit tests/Unit/
./vendor/bin/phpunit tests/Feature/

# Run with coverage
./vendor/bin/phpunit --coverage-html coverage/

Test Configuration

// In your test setup
config([
    'social_media_publisher.facebook_access_token' => 'test_token',
    'social_media_publisher.facebook_page_id' => 'test_page_id',
    // ... other test configurations
]);

Mocking APIs

use Illuminate\Support\Facades\Http;

Http::fake([
    'https://graph.facebook.com/v20.0/*' => Http::response(['id' => '123'], 200),
    'https://api.twitter.com/2/*' => Http::response(['data' => ['id' => '456']], 200),
]);

📚 Examples

Check the examples/ directory for comprehensive usage examples:

Basic Usage: Single platform, multi-platform, error handling
Advanced Usage: Content scheduling, analytics, bulk operations
Platform-Specific: Facebook analytics, Instagram carousels, LinkedIn company pages
Integration: Laravel commands, queue jobs, event listeners
Testing: Unit tests, feature tests, API mocking

Quick Examples

# Run basic examples
php examples/basic-usage/single-platform.php
php examples/basic-usage/multi-platform.php
php examples/basic-usage/error-handling.php

# Run platform-specific examples
php examples/platform-specific/facebook-examples.php
php examples/platform-specific/instagram-examples.php

📖 API Reference

SocialMedia Facade

Method	Description	Parameters
`shareText($owner, $platforms, $caption, $ownerId = null)`	Share text-only content to multiple platforms	`mixed $owner, array $platforms, string $caption, ?int $ownerId`
`shareUrl($owner, $platforms, $caption, $url, $ownerId = null)`	Share content with URL to multiple platforms	`mixed $owner, array $platforms, string $caption, string $url, ?int $ownerId`
`shareImage($owner, $platforms, $caption, $image_url, $ownerId = null)`	Share image to multiple platforms	`mixed $owner, array $platforms, string $caption, string $image_url, ?int $ownerId`
`shareVideo($owner, $platforms, $caption, $video_url, $ownerId = null)`	Share video to multiple platforms	`mixed $owner, array $platforms, string $caption, string $video_url, ?int $ownerId`
`platform($platform, $owner = null, $ownerId = null, $connectionType = 'profile')`	Get platform service for owner	`string $platform, mixed $owner, ?int $ownerId, ?string $connectionType`
`getAvailablePlatforms()`	Get list of available platforms	-

Platform Facades

Each platform facade provides methods specific to that platform. See the individual platform documentation above for detailed method signatures.

SocialMediaManager

Method	Description	Parameters
`getAvailablePlatforms()`	Get list of available platforms	-
`isPlatformAvailable($platform)`	Check if platform is available	`string $platform`
`getPlatformService($platform)`	Get platform service class	`string $platform`

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/mantix/laravel-social-media-publisher.git

# Install dependencies
composer install

# Run tests
./vendor/bin/phpunit

# Run examples
php examples/basic-usage/single-platform.php

Pull Request Process

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass
Submit a pull request

📄 License

This package is licensed under the MIT License.

🆘 Support

Documentation: GitHub Wiki
Issues: GitHub Issues
Discussions: GitHub Discussions
Email: support@mantix.nl

🙏 Acknowledgments

Laravel Framework
All social media platform APIs
The open-source community

Made with ❤️ by mantix

mantix / laravel-social-media-publisher

Maintainers

Details

README

🌟 Features

📋 Table of Contents

🚀 Installation

Requirements

Install via Composer

Publish Configuration and Migrations

⚙️ Configuration

Environment Variables

OAuth Routes Setup

OAuth Authorization Routes

Customizing OAuth Callbacks

Default OAuth Controller Behavior

OAuth Callback URLs Configuration

Facebook

Twitter/X

LinkedIn

Instagram

TikTok

YouTube

Pinterest

Configuration File

🎯 Quick Start

Basic Usage

Multi-User & Multi-Entity Support

Using the HasSocialMediaConnections Trait

Individual Platform Access

📖 Usage

Multi-User OAuth Flow

1. Get Authorization URL

Basic OAuth (Without PKCE)

OAuth with PKCE (Recommended for LinkedIn and Twitter/X)

2. OAuth Callbacks (Automatic)

3. Refresh Access Tokens

For Platforms with Refresh Tokens (LinkedIn, Twitter/X)

For Platforms with Token Extension (Facebook, Instagram)

4. Disconnect from Platform

Unified API

Share to Multiple Platforms

Share to All Platforms

Platform-Specific Access

Individual Platforms

Facebook

Twitter/X

LinkedIn

Instagram

TikTok

YouTube

Pinterest

Telegram

Platform-Specific Features

Facebook Analytics

Instagram Carousels

LinkedIn Company Pages

YouTube Community Posts

Pinterest Boards

🔧 Advanced Features

Error Handling

Retry Logic

Logging

Input Validation

🧪 Testing

Run Tests

Test Configuration

Mocking APIs

📚 Examples

Quick Examples

📖 API Reference

SocialMedia Facade

Platform Facades

SocialMediaManager

🤝 Contributing

Development Setup

Pull Request Process

📄 License

🆘 Support

🙏 Acknowledgments