Connect Module Laravel Package

Getting Started

This is a Streams Platform (PyroCMS) module, not a standalone Laravel package — it expects a host application already running streams-platform with the core streams addon. If you're on plain Laravel, stop here; the value proposition (Streams entries, field types, assignments) doesn't exist without the platform.

Minimal path:

1. composer require visiosoft/connect-module in the host app.
2. Install the addon so its service provider, routes, and migrations register: php artisan addon:install visiosoft.module.connect. Verify with php artisan addon:list and php artisan route:list --path=api — the routes you see there are the public surface of the module.
3. Run migrations (API key/token table, likely connect_keys or similar) and open the control panel; the module typically adds a "Connect" section for managing consumers and tokens.

Look first at: src/Http/Controllers/ (what's actually exposed and how requests are shaped), src/ConnectServiceProvider.php (bindings, route registration, event listeners), and config/ if present — that's where stream/field allow-lists usually live.

First use case: read-only exposure of a single Stream (e.g. a blog stream) to a partner site or a headless frontend. Mint one key, restrict it to one stream and a whitelist of fields, hit the endpoint with curl, confirm the payload shape before writing any consumer code.

Implementation Patterns

Per-consumer tokens, not a single shared key. Generate a key per integration (marketing site, mobile app, partner feed). When one leaks you revoke one. Treat the key table as a tenant boundary and include a label/notes field so you know who owns what.

Whitelist fields, never blacklist. Streams entries often carry internal fields (admin notes, draft flags, pricing). Configure exposure explicitly per stream in the module's config/control panel rather than returning whole entries and filtering downstream — the default serialization is usually everything.

Consume from another Laravel app with a small typed client rather than scattering Http::get() calls:

$response = Http::withToken(config('services.connect.key'))
    ->get(config('services.connect.url').'/api/streams/posts', [
        'limit' => 50,
        'page'  => 1,
    ])->throw()->json();

Wrap it in a repository class so you can swap to a queue/cache later without touching call sites.

Bridge into your own API. Rather than letting frontends call the Connect module directly, proxy through your own controllers. You get your auth model, your caching, your rate limits, and you can reshape the payload — the module's response contract isn't something you control.

Extend via events/listeners, not by editing vendor code. The "extensible" in the description usually means the module fires events around request handling or exposes a resolver binding. Register a listener in your own addon's service provider to transform output or add computed fields, and keep the module fork-free.

Static/build-time consumption is the strongest pattern for a 2-star dependency: run a scheduled job that pulls the stream every N minutes into local tables or a JSON file, and serve that. The module becomes a sync source, not a live runtime dependency.

Gotchas and Tips

• Pin the version and vendor a fork. Last release Jan 2024, 2 stars, no dependents. composer require visiosoft/connect-module:1.x.x with a committed composer.lock, and be ready to replace it with a Git fork in repositories if the maintainer goes quiet.
• Version-coupling with streams-platform is the real risk, not the package itself. A platform upgrade can break the module silently. Check composer.json constraints and test the API endpoints specifically after any core bump — the control panel may look fine while routes 500.
• CORS is not handled for you. If a browser calls the API directly you'll need to publish/adjust the host app's config/cors.php to include the API paths. Most people hit this as an opaque "blocked by CORS policy" with a 200 in the Laravel log.
• N+1 on relationships. Streams entries are heavy; relationship fields can trigger per-entry queries. Use limit aggressively, prefer small pages, and check storage/logs/laravel.log or enable query logging when a list endpoint takes seconds.
• Debug in this order: php artisan route:list --path=api (is it registered?) → key auth middleware vs. 401/403 → the listener/resolver that shapes the response → the Streams repository. Errors are frequently swallowed into a generic JSON message, so log the exception server-side.
• Extension point of last resort: the module's views and config are publishable/overridable. If a payload shape doesn't fit, override the controller binding in your own service provider rather than patching vendor/ — patched vendor code is the number one thing that makes a Streams upgrade unrecoverable.
• Don't expose write endpoints casually. If the module supports POST/PUT against streams, gate it behind its own key scope and a separate consumer, and audit what field types can be written — a writable field pointing at a file/relationship is a much bigger blast radius than a string.