# SocialForge Documentation

Complete social media management platform built on Laravel 12

SocialForge is a self-hosted social media management platform that lets you schedule posts, monitor analytics, manage your inbox, and run AI-powered content campaigns — all from a single, beautiful dashboard. Built with Laravel 12, Livewire 3, and Tailwind CSS, it runs on any standard PHP hosting environment.

🌐
Multi-Platform Posting
Post to 7 social platforms simultaneously from one composer.
🕐
Smart Scheduling
AI-powered best time suggestions to maximise engagement.
📊
Analytics Dashboard
Track engagement, follower growth, and content performance.
👥
Team Collaboration
Invite team members and assign roles and permissions.
🔍
Social Listening
Monitor brand mentions and keywords across platforms.
🧪
A/B Testing
Test different post variations and let AI pick the winner.

### Supported Platforms

𝕏 Twitter / X f Facebook 📷 Instagram in LinkedIn ♪ TikTok ▶ YouTube P Pinterest

## What's Included

Your purchase includes everything needed to run SocialForge on your own server.

Item | Details
--- | ---
Laravel 12 Source Code | Full unencoded PHP source — no ionCube or encoding required.
Web Installer | 6-step browser-based installation wizard. No command line needed.
Admin Panel | Complete management dashboard built with Livewire 3 and Tailwind CSS.
REST API | License validation endpoints and social platform webhook handlers.
Documentation | This documentation covering installation, configuration, and all features.
Support | 6 months of priority email support via the support portal.
Updates | Free updates for 12 months from date of purchase.

## Server Requirements

### Minimum Requirements

Component | Requirement
--- | ---
PHP | 8.2 or higher
MySQL | 5.7+ or MariaDB 10.3+
Web Server | Apache 2.4+ or Nginx 1.18+
Memory | 256MB minimum (512MB recommended)
Storage | 500MB minimum (more for media uploads)
SSL | Recommended for production (required by some social APIs)

### Required PHP Extensions

Extension | Purpose
--- | ---
`BCMath` | Mathematical operations for precision arithmetic
`Ctype` | Character type checking
`cURL` | HTTP requests to social platform APIs
`Fileinfo` | File type detection for media uploads
`GD` | Image processing and thumbnail generation
`JSON` | Data encoding and decoding
`Mbstring` | Multi-byte string support for Unicode content
`OpenSSL` | Encryption for stored social tokens
`PDO` | Database abstraction layer
`PDO_MySQL` | MySQL/MariaDB driver
`Tokenizer` | PHP tokenizer (required by Laravel)
`XML` | XML processing for RSS feeds
`ZIP` | File compression for export features

ℹ️ Shared Hosting
Most shared hosting providers (cPanel / Plesk) already have all required extensions enabled by default. You can verify your extensions at phpinfo() or via the hosting control panel.

## Installation Guide

Follow these steps to install SocialForge on your server. No command line access is required for shared hosting.

1. 1
   Download & Upload Files

   Download the zip file from your CodeCanyon or Codester account. Upload it to your server via FTP (FileZilla) or cPanel File Manager.

   bash

       # Recommended folder structure
       public_html/          ← for main domain install
       public_html/social/   ← for subdirectory install

2. 2
   Extract Files

   Right-click the zip file in cPanel File Manager and select Extract. Ensure the `public/` folder contents are accessible from your web root. On most shared hosts, your web root is `public_html/`.

3. 3
   Set Folder Permissions

   Set write permissions on the storage and cache directories. This can be done via your FTP client or SSH.

   bash

       chmod 755 storage/
       chmod 755 bootstrap/cache/
       chmod -R 775 storage/
       chmod -R 775 bootstrap/cache/

4. 4
   Run the Installer

   Open your browser and navigate to your domain followed by `/install`. The 6-step wizard will guide you through database setup, admin account creation, and license activation.

   yourdomain.com/install
5. 5
   Set Up the Cron Job

   After installation, set up a cron job so scheduled posts publish on time. In cPanel go to Cron Jobs and add:

   cron

       * * * * * cd /path/to/socialforge && php artisan schedule:run >> /dev/null 2>&1

6. 6
   Configure Social APIs

   Add your social media API credentials to the `.env` file or via Settings → Social Accounts in the admin panel. See the Configuration section for each platform's setup guide.

⚠️ Security Warning
Always delete or rename the `/install` folder from your server after installation is complete. Leaving it accessible is a significant security risk.

### Nginx Server Configuration

If you're using Nginx, use this configuration block:

nginx

    server {
        listen 80;
        server_name yourdomain.com www.yourdomain.com;
        root /var/www/socialforge/public;
        index index.php index.html;

        add_header X-Frame-Options "SAMEORIGIN";
        add_header X-Content-Type-Options "nosniff";

        location / {
            try_files $uri $uri/ /index.php?$query_string;
        }

        location ~ \.php$ {
            fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
            fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
            include fastcgi_params;
        }

        location ~ /\.(?!well-known).* {
            deny all;
        }
    }

## License Activation

### Finding Your License Key

After purchase your license key is included in the purchase confirmation email from CodeCanyon or Codester. It is also available in your account dashboard under Downloads. The key format is `XXXX-XXXX-XXXX-XXXX`.

### Activating During Installation

Step 1 of the installation wizard asks for your license key. Enter the key and click Validate & Continue. The wizard connects to the license server, verifies the key, and stores it securely in your database.

### Activating After Installation

If you skipped activation or need to re-enter your key, navigate to Settings → License in the admin panel. Enter your key and click Activate.

### Transferring to a New Domain

To move SocialForge to a new domain, go to Settings → License → Transfer Domain. This deactivates the key on the old domain and activates it on the current one. You can transfer up to 3 times per year.

### License Server Grace Period

If the license server is temporarily unreachable (e.g. during outages), SocialForge continues to function normally for up to 7 days. After that, a re-validation prompt will appear.

⚠️ One Domain Per License
Each license allows activation on 1 production domain. Localhost and staging domains are exempt. Purchase additional licenses for additional production domains.

## Environment Setup

All configuration is managed through the `.env` file in the project root. The installer creates this file automatically, but you may need to edit it for advanced configuration.

Variable | Example Value | Description
--- | --- | ---
`APP_NAME` | SocialForge | Application name shown in browser tabs and emails
`APP_ENV` | production | Environment. Use `production` on live servers
`APP_DEBUG` | false | Debug mode. Always false in production
`APP_URL` | https://yourdomain.com | Your full domain URL including protocol
`DB_HOST` | localhost | Database server hostname
`DB_DATABASE` | socialforge | Database name
`DB_USERNAME` | root | Database username
`DB_PASSWORD` | secret | Database password
`LICENSE_SERVER_URL` | https://license.socialforge.app | License validation server URL
`QUEUE_CONNECTION` | redis | Queue driver. Use `database` if Redis is unavailable
`CACHE_STORE` | redis | Cache driver. Use `file` if Redis is unavailable
`SESSION_DRIVER` | database | Session storage driver

ℹ️ Shared Hosting Tip
If Redis is not available on your host, set `QUEUE_CONNECTION=database` and `CACHE_STORE=file`. Performance will be slightly lower but everything will work correctly.

## Database Configuration

SocialForge requires a MySQL 5.7+ or MariaDB 10.3+ database. The installer creates all tables automatically during Step 5.

### Creating a Database (cPanel)

1. Log into cPanel and open MySQL Databases
2. Under Create New Database enter a name (e.g. `socialforge`) and click Create Database
3. Under MySQL Users create a new user with a strong password
4. Under Add User To Database grant the user ALL PRIVILEGES
5. Enter these credentials into the installer Step 3 or into your `.env` file

### Running Migrations Manually

If the installer's migration step fails, you can run migrations via SSH:

bash

    php artisan migrate --force

## Facebook & Instagram

ℹ️ Prerequisites

- A Facebook Developer account at developers.facebook.com
- A Business or Creator Facebook Page
- An Instagram Business or Creator account connected to your Facebook Page

### Creating Your Facebook App

1. Go to developers.facebook.com and click My Apps → Create App
2. Select Business as the app type and click Next
3. Enter your app name and contact email address
4. From the left menu, find Products and click + next to Facebook Login
5. Under Facebook Login → Settings, add your OAuth Redirect URI:

    https://yourdomain.com/auth/facebook/callback

6. Navigate to App Settings → Basic
7. Copy your App ID and App Secret

### Required Permissions

- pages_manage_posts
- pages_read_engagement
- instagram_basic
- instagram_content_publish
- instagram_manage_insights

### Environment Variables

.env

    META_APP_ID=your_app_id_here
    META_APP_SECRET=your_app_secret_here
    META_REDIRECT_URI=https://yourdomain.com/auth/facebook/callback

⚠️ App Review
Facebook requires App Review for permissions that access other users' data. For posting to your own pages and accounts, Developer Mode is sufficient — no review needed.

## Twitter / X

ℹ️ Prerequisites
A Twitter Developer account at developer.twitter.com with an app created under a Project.

### Setup Steps

1. Go to developer.twitter.com/portal and create a new Project then an App inside it
2. Under App Settings → User authentication settings, click Set up
3. Enable OAuth 2.0 and set App type to Web App
4. Add your callback / redirect URI:

    https://yourdomain.com/auth/twitter/callback

5. Copy your Client ID and Client Secret from the Keys and Tokens tab

### Environment Variables

.env

    TWITTER_CLIENT_ID=your_client_id
    TWITTER_CLIENT_SECRET=your_client_secret
    TWITTER_CALLBACK_URL=https://yourdomain.com/auth/twitter/callback

⚠️ Paid Plan Required
Twitter/X Basic plan ($100/month) is required for write access (posting tweets). The free tier only allows read access. Ensure your developer account is on the correct plan before connecting.

## LinkedIn

### Setup Steps

1. Go to developer.linkedin.com and click Create App
2. Fill in your app name, associated LinkedIn Company Page, and upload a logo
3. Under the Auth tab, copy your Client ID and Client Secret
4. Add your OAuth 2.0 Redirect URL:

    https://yourdomain.com/auth/linkedin/callback

5. Under the Products tab, request access to:
   - Sign In with LinkedIn using OpenID Connect
   - Share on LinkedIn
   - Marketing Developer Platform (for page analytics)

### Environment Variables

.env

    LINKEDIN_CLIENT_ID=your_client_id
    LINKEDIN_CLIENT_SECRET=your_client_secret
    LINKEDIN_CALLBACK_URL=https://yourdomain.com/auth/linkedin/callback

✓ Quick Approval
LinkedIn has the most straightforward API approval process. Most apps are reviewed and approved within 24–48 hours.

## TikTok

### Setup Steps

1. Go to developers.tiktok.com and sign in with your TikTok account
2. Click Manage Apps → Connect an App
3. Fill in your app details, description, and category
4. Under Login Kit, add your redirect URI:

    https://yourdomain.com/auth/tiktok/callback

5. Copy your Client Key and Client Secret from the app dashboard
6. Submit your app for review to enable content publishing

### Environment Variables

.env

    TIKTOK_CLIENT_KEY=your_client_key
    TIKTOK_CLIENT_SECRET=your_client_secret
    TIKTOK_CALLBACK_URL=https://yourdomain.com/auth/tiktok/callback

## YouTube / Google

### Setup Steps

1. Go to console.cloud.google.com and create a new project
2. Navigate to APIs & Services → Library
3. Search for and enable YouTube Data API v3
4. Go to APIs & Services → Credentials
5. Click Create Credentials → OAuth Client ID
6. Select Web Application as the application type
7. Add your authorised redirect URI:

    https://yourdomain.com/auth/google/callback

8. Copy your Client ID and Client Secret from the credentials page
9. Set up the OAuth Consent Screen with your app name and logo

### Environment Variables

.env

    GOOGLE_CLIENT_ID=your_client_id
    GOOGLE_CLIENT_SECRET=your_client_secret
    GOOGLE_CALLBACK_URL=https://yourdomain.com/auth/google/callback

## Dashboard Overview

The dashboard is your central hub. It surfaces the most important information at a glance — upcoming posts, recent analytics, and platform health.

### Dashboard Widgets

Widget | Description
--- | ---
Posts Today | Count of posts scheduled and published today
Total Followers | Combined follower count across all connected accounts
Engagement Rate | Average engagement across last 30 days
Upcoming Queue | Next 5 scheduled posts with platform icons
Recent Activity | Latest published posts and their performance
Account Health | Token expiry warnings and connection status

## Compose & Schedule

The post composer lets you craft content for multiple platforms simultaneously, with per-platform overrides and live preview.

### Key Features

- Multi-platform selection — choose one or multiple platforms per post
- Per-platform overrides — customize caption, media, or hashtags per platform
- Live preview — see how your post looks on each platform before publishing
- AI caption generator — generate captions with Google Gemini AI
- Hashtag manager — save and reuse hashtag groups
- Media upload — drag-and-drop images and videos with auto-thumbnail
- Schedule or post now — pick a date/time or publish immediately
- Best time suggestions — AI-recommended posting times based on engagement history

## Bulk Scheduling

Upload and schedule multiple posts at once using a CSV file — ideal for campaigns and content batches.

### CSV Format

csv

    platform,caption,scheduled_at,image_url
    twitter,Check out our new feature! #launch,2026-04-01 09:00:00,https://example.com/img.jpg
    facebook,We just launched something exciting…,2026-04-01 10:00:00,

### Steps

1. Navigate to Compose → Bulk Schedule
2. Download the CSV template
3. Fill in your posts and save the file
4. Upload the CSV — SocialForge validates each row and shows a preview
5. Confirm to schedule all valid posts

## Post Calendar

The visual calendar shows all scheduled and published posts in a monthly, weekly, or daily view.

### Calendar Features

- Drag-and-drop rescheduling — drag a post to a new time slot
- Platform colour coding — each platform has a distinct colour
- Click to edit — click any post to open the composer with pre-filled content
- Month / Week / Day views — toggle between views with keyboard shortcut `M`, `W`, `D`
- Filter by platform — show/hide specific platforms
- Quick add — click an empty slot to open the composer for that time

## Analytics

Track content performance across all connected platforms with detailed charts and exportable reports.

### Available Metrics

Metric | Description
--- | ---
Followers | Follower count over time with gain/loss trend
Impressions | Total post reach and impressions
Engagements | Likes, comments, shares, and saves
Engagement Rate | Engagements as % of impressions
Link Clicks | Clicks on links in posts and bio
Top Posts | Best performing posts ranked by engagement

Analytics are fetched automatically on a daily schedule via the queue. You can also trigger a manual sync from Analytics → Sync Now.

## Inbox & Replies

The unified inbox aggregates comments, direct messages, and mentions from all connected platforms into a single stream.

### Inbox Features

- Unified stream — all platforms in one inbox, sortable by date or platform
- Sentiment analysis — AI-powered positive / neutral / negative classification
- Reply templates — save and reuse common responses
- Read / Resolved states — mark messages as handled
- Filters — filter by platform, sentiment, or unread status
- Notifications — real-time browser notifications for new messages

## Social Listening

Monitor keywords, brand mentions, and competitor activity across platforms without manual searching.

### Setting Up Keywords

1. Navigate to Listening → Keywords
2. Click Add Keyword and enter your term (e.g. your brand name)
3. Select which platforms to monitor
4. Set a sentiment alert threshold if desired
5. Save — SocialForge begins monitoring immediately

### Keyword Ideas

- Your brand name and common misspellings
- Your product names
- Industry hashtags
- Competitor names (for competitive intelligence)

## A/B Testing

Test two variations of a post to discover which performs better. SocialForge uses AI to analyse results and recommend a winner.

### Running an A/B Test

1. Open the Compose screen and click A/B Test
2. Write Variation A (your control post)
3. Click + Add Variation B and write an alternative caption or use different media
4. Set the test duration (24 hours recommended)
5. Schedule both posts — SocialForge publishes them simultaneously
6. After the test period, view results under Analytics → A/B Tests
7. The AI analysis explains which variation won and why

## Team Members

Invite collaborators to manage social accounts with role-based access control.

### Available Roles

Role | Permissions
--- | ---
Owner | Full access — billing, settings, team management
Admin | All features except billing and license management
Editor | Create, edit, and schedule posts. View analytics
Viewer | Read-only access — view posts and analytics only

### Inviting a Team Member

1. Go to Settings → Team Members
2. Click Invite Member
3. Enter their email address and select a role
4. They receive an invitation email with a sign-up link

## Account Management

Manage all connected social media accounts from Settings → Social Accounts.

### Connecting an Account

1. Navigate to Settings → Social Accounts
2. Click Connect Account and choose a platform
3. You will be redirected to the platform's OAuth page
4. Grant the required permissions and you will be redirected back
5. The account now appears in your account list

### Token Refresh

Social tokens expire periodically. SocialForge automatically refreshes tokens in the background. If a token cannot be refreshed, you will receive an email notification and an in-app warning. Simply reconnect the account to resolve it.

## File Structure

SocialForge follows standard Laravel conventions. Key directories and their purposes:

tree

    socialforge/
    ├── app/
    │   ├── Http/
    │   │   ├── Controllers/     # HTTP request handlers (thin — logic in Services)
    │   │   └── Middleware/      # Request middleware (auth, 2FA, license check)
    │   ├── Livewire/            # Real-time Livewire components
    │   ├── Models/              # Eloquent database models
    │   ├── Services/            # Business logic services
    │   │   ├── Social/          # Per-platform posting services
    │   │   ├── AI/              # AI caption & image generation
    │   │   └── Media/           # Upload, thumbnail, storage services
    │   ├── Jobs/                # Queued jobs (posting, analytics sync, AI)
    │   ├── Enums/               # PHP 8.1 enums (Platform, PostStatus, etc.)
    │   └── Notifications/       # Email & database notifications
    ├── config/                  # Application configuration files
    ├── database/
    │   ├── migrations/          # Database schema files (run in order)
    │   └── seeders/             # Optional demo data seeders
    ├── install/                 # Web installer wizard (delete after install)
    ├── public/                  # Web root — point your domain here
    │   ├── storage/             # Symlink to storage/app/public/
    │   └── build/               # Compiled Vite CSS & JS assets
    ├── resources/
    │   ├── views/               # Blade template files
    │   │   ├── livewire/        # Livewire component views
    │   │   ├── components/      # Reusable Blade components
    │   │   └── emails/          # Email notification templates
    │   ├── css/                 # Source CSS (Tailwind)
    │   └── js/                  # Source JavaScript (Alpine.js)
    ├── routes/
    │   ├── web.php              # Web routes (dashboard, auth, social)
    │   └── api.php              # API routes (webhooks, license)
    ├── storage/
    │   ├── app/public/          # User uploaded files (images, videos)
    │   ├── framework/           # Framework cache (sessions, views, cache)
    │   └── logs/                # Application log files
    ├── .env                     # Environment configuration (never commit!)
    ├── .env.example             # Environment template
    └── artisan                  # Laravel CLI tool

## Customization Guide

### 1. Changing the Color Scheme

Edit `resources/css/app.css` to change the primary color used throughout the UI:

css

    /* resources/css/app.css */
    :root {
        --color-primary: #1d4ed8;       /* Primary blue */
        --color-sidebar: #1b2a4a;       /* Sidebar background */
        --color-accent:  #f5a623;       /* Amber accent (buttons) */
    }

After editing, recompile assets with:

    npm run build

### 2. Adding a New Social Platform

1. Add the platform to the `Platform` enum in `app/Enums/Platform.php`
2. Create an OAuth controller in `app/Http/Controllers/SocialAuth/` following the existing pattern
3. Create a posting service in `app/Services/Social/`
4. Add the OAuth callback route to `routes/web.php`
5. Add the platform logo/icon to `resources/views/components/sf-icon.blade.php`
6. Add API credentials to `.env`

### 3. Modifying Email Templates

All email templates are Blade files located in `resources/views/emails/`. They use the standard Laravel Markdown mail format and can be edited freely.

### 4. Adding Custom Dashboard Widgets

Create a new Livewire component and register it on the dashboard:

bash

    php artisan make:livewire Dashboard/MyCustomWidget

Then include it in `resources/views/livewire/dashboard/dashboard-home.blade.php`:

blade

    @livewire('dashboard.my-custom-widget')

## Upgrade Guide

Follow these steps to safely upgrade to a new version of SocialForge.

⚠️ Always Backup First
Always back up your database and `.env` file before upgrading. Upgrades cannot be automatically reversed.

1. 1
   Back Up Your Database

       mysqldump -u root -p socialforge > backup_$(date +%Y%m%d).sql

2. 2
   Back Up Your .env File

   Copy your `.env` file to a safe location before overwriting any files.

3. 3
   Upload New Files

   Download the new version zip and upload to your server. Overwrite all files except:

   - `.env` — keep your existing environment file
   - `storage/` — keep your uploaded media files
4. 4
   Run Migrations

       php artisan migrate --force

5. 5
   Clear All Caches

       php artisan config:clear
       php artisan cache:clear
       php artisan view:clear
       php artisan optimize

## Frequently Asked Questions

Yes! SocialForge works on any shared hosting that supports PHP 8.2+ and MySQL. cPanel and Plesk hosting providers work perfectly. The web-based installer handles everything without needing SSH access.
No. The browser-based installation wizard guides you through every step — database setup, admin account creation, and license activation. No command line access is required for a standard shared hosting install.
Each license covers one production domain. Localhost and local development environments are exempt. Purchase additional licenses for additional production domains. Development and staging domains can be added by contacting support.
Add a cron job via cPanel → Cron Jobs (set to run every minute): `* * * * * cd /home/username/public_html && php artisan schedule:run >> /dev/null 2>&1`
Twitter/X, Facebook, Instagram, LinkedIn, TikTok, YouTube, and Pinterest. Additional platforms may be added in future updates.
See the Upgrade Guide section. Always back up your database before upgrading. The process takes about 5 minutes.
Yes. The frontend is built with Tailwind CSS and Blade templates — both are fully customizable. See the Customization Guide for details on changing colors and adding widgets.
The software continues to work normally. You just won't receive official support responses or new version updates after the support period expires. You can purchase a support extension at any time.
Yes. You can invite unlimited team members and assign them Owner, Admin, Editor, or Viewer roles. Each role has a carefully defined set of permissions.
Go to Settings → License → Transfer Domain. This deactivates the license on the old domain and activates it on the new one. You may transfer up to 3 times per year.
A SaaS version with full multi-tenant support, subscription billing via Stripe, and per-client workspaces is planned for a future release. Join the mailing list to be notified.
Back up two things: your MySQL database (via phpMyAdmin export or `mysqldump`) and the `storage/app/` folder which contains all uploaded media. Your `.env` file should also be backed up separately.

## Changelog

v1.0.0 March 2026 Latest
New Features

- Multi-platform post composer with live platform previews
- Smart scheduling with AI best-time suggestions
- Drag-and-drop visual content calendar (month/week/day views)
- Bulk post scheduling via CSV upload
- Full analytics dashboard with charts and export
- Unified social inbox — comments, DMs, and mentions in one stream
- Sentiment analysis on incoming messages (positive/neutral/negative)
- Social listening and keyword monitoring
- A/B testing for posts with AI winner analysis
- Team member management with role-based access control
- Social account management for 7 platforms
- 6-step browser-based installation wizard
- License activation and domain management system
- AI caption generator powered by Google Gemini
- Emoji picker and reusable hashtag groups
- Link preview cards in composer
- Media upload with auto-thumbnail generation (images & videos)
- Two-factor authentication (Google Authenticator)
- Email notifications for token expiry, post failures, and daily summary

## Getting Support

We're here to help. Before opening a ticket, please check the FAQ and confirm you're running the latest version.

### Response Times

Request Type | Response Time
--- | ---
Bug Reports | Within 24 hours
General Questions | Within 48 hours
Feature Requests | Within 72 hours (reviewed for roadmap)

### What Support Covers

- ✓ Installation assistance
- ✓ Configuration and setup help
- ✓ Bug reports and confirmed fixes
- ✓ General usage questions

### What Support Does Not Cover

- ✗ Custom development or code modifications
- ✗ Third-party API issues (Facebook, Twitter, etc.)
- ✗ Server configuration and hosting environment setup
- ✗ Data migration from other platforms

ℹ️ Before Contacting Support
Please check the FAQ section and make sure you are running the latest version of SocialForge. Include your PHP version, Laravel version, and a description of the steps to reproduce the issue.
Contact Support →