Mixpost Laravel Package

Getting Started

Mixpost is a self-hosted Buffer alternative shipped as a Laravel package: it adds routes, migrations, models, queue jobs, and an Inertia/Vue admin UI to an existing Laravel app. Treat it as a mini-application mounted inside your app, not as a library of composable helpers.

Minimum path to a first scheduled post:

1. Confirm prerequisites: PHP 8.1+, a supported Laravel version, MySQL/PostgreSQL, a queue worker, and the scheduler running. For video/media thumbnails, install FFmpeg on the host.
2. Install and scaffold:

   composer require inovector/mixpost
   php artisan mixpost:install
   php artisan migrate
   php artisan storage:link
   

   If you use Mixpost Pro, set MIXPOST_LICENSE_KEY before visiting the UI.
3. Open config/mixpost.php first. It controls the mount path (often MIXPOST_PATH, default /mixpost), middleware/auth, enabled social providers, queue connection, media disk, and other package behavior. This is the file you will revisit most.
4. Create OAuth apps with each network (Facebook, X/Twitter, LinkedIn, Instagram, Pinterest, YouTube, TikTok, depending on the version) and put credentials in config/services.php / .env. Copy the callback URL exactly as the package generates it—normally based on APP_URL plus the Mixpost path.
5. Run php artisan route:list --path=mixpost to see the mounted routes, then visit the UI, connect one account, and schedule a post a few minutes in the future.
6. Start php artisan queue:work and ensure php artisan schedule:run fires every minute. Without both, posts remain "scheduled" forever.

Where to look first when behavior is unclear: config/mixpost.php, the package migrations (core models are Post, Account, Media, Tag), Inovector\Mixpost\Models, and the package source under vendor/inovector/mixpost/src. Do not start by editing vendor views; most integration work belongs in config, middleware, and your own app code.

First real use case: mount Mixpost at an admin-only path, connect a single Facebook page or X account, schedule one text post plus one image post, and verify the full draft → scheduled → published lifecycle before inviting users.

Implementation Patterns

Embed it behind your existing auth and admin policy. The package uses your application's users but cannot know your roles. Set the path to something like admin/social, keep web + auth middleware, and add your own authorization middleware or Gate around the Mixpost route group. Link to it from your admin navigation rather than exposing it publicly.

Use the UI as the authoring surface, not a reimplementation target. Mixpost's value is the calendar, queue, media library, and account management. Rebuilding those in your app is wasted effort. Integrate by linking users into Mixpost and keeping your own domain workflows elsewhere.

Automate content creation through the package models, carefully. For product launches, blog announcements, or internal alerts, create scheduled posts from your own domain events. Use the Mixpost Eloquent models and inspect the migrations/form requests for required fields and per-account publishing records. Keep creation in a small service class so package upgrades are easier to absorb. If the package exposes actions/services used by its controllers, prefer reusing those over raw inserts.

Isolate publishing jobs on a dedicated queue. Configure Mixpost to use its own queue connection/name (for example mixpost) so slow social API calls, media processing, and retries do not starve your application jobs. Run a separate worker for that queue and monitor failed_jobs.

Register a custom social provider when you need an internal or niche network. Mixpost has a provider abstraction used by its built-in networks. The pattern is to implement the provider contract, wire OAuth/account retrieval/publishing methods, and register the provider in config/mixpost.php. Verify the exact abstract class and config shape against the installed version before committing; this is a powerful but version-sensitive extension point.

Use events and jobs rather than patching vendor code. If you need notifications on publish success/failure, listen to the package's events or observe post status changes. For audit trails, add your own table and write to it from listeners instead of modifying Mixpost tables.

Promote environments with separate social apps. Use different OAuth credentials for local, staging, and production. Local OAuth is painful because most networks require public HTTPS callbacks; use a tunnel or a staging domain. Keep APP_URL correct per environment—Mixpost derives callback URLs from it.

Plan for localization and branding early. Publish and override language files if your users are non-English. Branding is more constrained because the UI is compiled Inertia/Vue; prefer config-level naming/colors and avoid forking the frontend unless you are prepared to maintain it.

Gotchas and Tips

• Scheduler plus queue is the #1 failure mode. Posts stuck in "Scheduled" almost always mean the scheduler is not running, the queue worker is stopped, or the post time is outside the window the command polls. Check php artisan schedule:list, the queue connection in config/mixpost.php, and failed_jobs.
• OAuth callback mismatch is the #2 failure mode. Changing APP_URL, the Mixpost path, or using a proxy can invalidate redirect URIs. Re-copy the callback URL from the package after any path change.
• Provider approval is a business blocker, not a code problem. Instagram and Facebook often require business verification and app review; X/Twitter API tiers change frequently. Budget time for platform onboarding and expect provider API volatility.
• Media needs to be reachable. Some networks fetch media by public URL, so a private S3 bucket or misconfigured storage:link can break publishing even though the UI preview looks fine. Confirm the media disk and public URL configuration.
• FFmpeg failures are easy to miss. Video thumbnails and conversions can fail silently if FFmpeg is absent or the PHP process cannot execute it. Check logs and run a video post end-to-end.
• Clear caches after config changes. php artisan config:clear and route:clear after changing the path, middleware, providers, or queue settings. Cached config is a common source of "my change did nothing."
• Authorization is your responsibility. Any authenticated user may reach the mounted routes unless you add middleware. Do not assume Mixpost enforces your admin roles.
• Timezone and DST bugs look like scheduling bugs. Posts are typically stored in UTC and rendered in a user/workspace timezone. Verify the timezone setting and test a schedule that crosses a DST boundary.
• Pro and free capabilities differ. Workspaces, team features, and analytics are Pro-oriented; don't design your integration around them unless the license is in place. Check feature availability against the installed version, not just the marketing site.
• Upgrades require reading the guide. Run migrations, republish assets if instructed, and re-check config keys. Pin the package version in composer.json for production and upgrade deliberately.
• Frontend customization is expensive. Because the UI is Inertia/Vue and ships compiled, small view changes can require publishing and rebuilding assets. Prefer configuration and extension points; fork only with a maintenance plan.
• Debug from the database and logs, not just the UI. Failed posts often store provider error responses; Laravel logs and failed_jobs show the underlying exception. Reproduce with a single account and a simple text post before adding media or threads.
• Multi-tenant scoping matters if you use workspaces. Do not assume accounts and posts are globally visible. Scope any custom queries and listeners to the same workspace/user boundaries the package uses.