Laravel Integration Guide

Use the agency/content-connector package to turn any Laravel app into an HQ node.

Installation

composer require agency/content-connector

Setup

1. Publish config

php artisan vendor:publish --tag=content-connector-config

2. Run migrations

php artisan migrate

This creates the hub_tokens and content_post_mappings tables.

3. Create a token

php artisan connector:token hub-id --name=my-hub --scopes=posts:write,posts:media

4. Configure your Post model

The connector writes to your Post model's existing columns. By default it expects title, slug, body_html, meta_title, meta_description, and featured_image_path.

If your model uses different column names, the connector auto-detects and maps what it can.

Configuration

// config/content-connector.php
return [
    'post_model' => \App\Models\Post::class,
    'throttle' => ['max' => 120, 'minutes' => 1],
    'ip_whitelist' => [
        'enabled' => false,
        'allowed' => [],
    ],
    'media' => [
        'disk' => 'public',
        'path' => 'connector/media',
    ],
];

How It Works

The package auto-registers routes under /api/connector/ via its service provider. The PostSyncService bridges connector payloads to your Eloquent model:

• Writes only columns that exist on your table (schema-aware)
• Tracks hub_post_id ↔ node_post_id mapping for idempotency
• Auto-generates slugs on collision
• Flattens nested meta objects into model columns
• Maps featured_image to featured_image_path (or your column name)

Customization

Different table name

Override the post_model config to point to your custom model:

'post_model' => \App\Models\Article::class,

IP whitelisting

'ip_whitelist' => [
    'enabled' => true,
    'allowed' => ['203.0.113.0/24', '198.51.100.42'],
],

Media storage

Change the disk to S3 or any other Laravel-supported filesystem:

'media' => [
    'disk' => 's3',
    'path' => 'connector/media',
],

Testing

cd packages/agency/content-connector
composer install
vendor/bin/phpunit

Package Development

To contribute to the connector package:

1. Edit files in packages/agency/content-connector/
2. Run composer update agency/content-connector in hub/
3. Run hub tests: cd hub && vendor/bin/phpunit