Owlstack Laravel Laravel Package

Getting Started

1. Install and let auto-discovery work.

composer require owlstack/owlstack-laravel

The service provider (FopostSocialServiceProvider) and the FopostSocial facade alias are registered through composer.json → extra.laravel, so there is no config/app.php editing. Confirm the package really is owlstack/owlstack-laravel in composer.json before installing — the repository is fopost/fopost-social-laravel, the namespace is Fopost\Social\Laravel\, and the config file is fopost-social.php. Three different names for one package; use composer show to see what you actually got.

2. Publish the config and fill in credentials.

php artisan vendor:publish --tag=fopost-social-config

Every credential and setting lives in config/fopost-social.php and is fed from .env. Never call a platform API with a token passed as an argument — add the key to config instead. Open the published file first; it is the authoritative list of env key names and per-platform options, and it is the only "documentation" that is guaranteed current.

3. Look at these three places, in order:

4. First use case — a single Telegram message from tinker:

use Fopost\Social\Laravel\Facades\FopostSocial;

FopostSocial::telegram()
    ->message('Deploy finished ✅')   // verify method names in src/SendTo.php
    ->send();

The facade is a static proxy to the 'fopost-social' container binding, which resolves to SendTo. Once that round-trips, move the same call into a job (below) and you have a production path.

Implementation Patterns

Inject SendTo, don't call the facade from application code. The facade is fine for tinker, seeders, and one-liners. In services and jobs, type-hint SendTo (or Publisher) as a constructor dependency — it is registered as a singleton, so you get the same instance the facade uses, and your class becomes trivially swappable in tests.

final class AnnounceRelease
{
    public function __construct(private readonly SendTo $sendTo) {}

    public function handle(Release $release): void
    {
        $this->sendTo->twitter()->message($release->summary)->send();
    }
}

Always wrap publishing in a queued job. The wrapper is deliberately thin and provides no queueing of its own; network latency and platform rate limits belong on a worker, not in an HTTP request. Dispatch the job from a model observer or a domain event so controllers stay clean.

final class PublishToSocial implements ShouldQueue
{
    use Queueable, InteractsWithQueue;

    public int $tries = 3;
    public array $backoff = [30, 120, 600];

    public function __construct(
        public readonly string $platform,
        public readonly string $content,
    ) {}

    public function handle(Publisher $publisher): void
    {
        $publisher->for($this->platform)->publish($this->content);
    }
}

One job per platform, not one job for all platforms. Fan-out inside a single job means a Telegram 400 kills the LinkedIn post. Dispatch PublishToSocial once per platform (or use Bus::batch()), and add WithoutOverlapping keyed on account+platform so a retry storm cannot double-post.

React to delivery outcomes through the bridged events. Core emits PostPublished and PostFailed; LaravelEventDispatcher re-dispatches them through Laravel's dispatcher. That is your only reliable hook for success/failure — do not infer success from the absence of an exception. Use listeners for audit rows, Slack alerts, or flipping a Post::status column.

Event::listen(PostFailed::class, function (PostFailed $event) {
    Log::warning('social.publish.failed', ['platform' => $event->platform]);
});

Chain from existing Laravel features, not the other way around. Model observers, Schedule::call(), and existing domain events are the natural entry points. Publish on Post::created() with a published_at guard, or schedule a daily digest with ->daily() and let the job do the fan-out.

Custom platforms belong in the core. If you need a platform the wrapper does not expose, register it with PlatformRegistry (the singleton the provider exposes) rather than adding a method to SendTo. Anything Laravel-specific — artisan commands, middleware, queue jobs — is fair game to write in your own app.

Gotchas and Tips

Fake the transport, not Http::fake(). Core has its own HttpClient singleton, so Laravel's Http::fake() will most likely not intercept the outbound calls. Bind a stub in a test service provider instead:

$this->app->singleton(HttpClient::class, fn () => new FakeHttpClient(/* canned responses */));

Also Event::fake() before asserting PostPublished / PostFailed — that is the cleanest assertion of "did this publish" without touching the network.

Config is read at boot. FopostConfig, platform instances, Publisher, and SendTo are singletons built by the service provider. Mutating credentials at runtime with config(['fopost-social…' => …]) after the provider has run will not reach the already-constructed platform objects. Configure via .env and php artisan config:cache at deploy time.

Missing credentials fail late, not early. The container resolves fine with empty tokens; you find out when the API rejects you inside a queued job at 2 a.m. Add a small artisan command or a boot-time assertion that walks config('fopost-social') and fails loudly for platforms you actually use.

Do not normalize content in the wrapper. Character limits, image dimensions, aspect ratios, and markdown dialect differences are core's responsibility. If a post looks wrong on X but fine on Telegram, the fix is in fopost-social-core, not in a str_limit() in your job.

Rate limits and 429s. The wrapper does not implement throttle awareness. Handle it at the job layer: $tries, $backoff, and WithoutOverlapping per account. Do not retry a 4xx payload error — classify exceptions in failed() and mark the record dead.

Keep wrapper and core in lockstep. With zero dependents and a recent, fast-moving release cadence, pin exact versions in composer.json and bump wrapper + core in the same commit. A thin wrapper on a mismatched core is the most likely source of breakage.

The terminal method is not documented outside the source. AGENTS.md lists telegram(), twitter(), facebook(), etc., but not the final publish call, its signature, or its return type. Read src/SendTo.php and mirror the examples/laravel-12/ app rather than guessing from blog posts.

Naming when debugging. Errors mention Fopost\Social\Laravel\, the vendor directory will be whatever the composer name resolves to, and stack traces point into fopost/social-core. Grep for fopost and SendTo, not owlstack, when tracing behaviour.

Extension points, in order of preference: (1) Laravel listeners on the bridged events; (2) PlatformRegistry for custom platforms; (3) wrapping SendTo in your own service if you need cross-cutting behaviour like metrics or redaction. Forking the wrapper should be the last resort — anything platform-specific is an upstream PR to fopost-social-core.