README

A Laravel package that allows applications using Verbs to sync events from a remote source.

Overview

Verbs Sync is a simple CLI tool that enables a Laravel application using the Verbs package to pull events from another Verbs-powered application. This tool focuses on a straightforward pull-based syncing model where your application acts as the destination, pulling events from a remote source.

Features

Pull Verbs events from a remote source application
API token authentication for secure communication
Selective event filtering
Event deduplication to prevent duplicate processing
Comprehensive logging
Simple command-line interface

Installation

You can install the package via composer:

composer require danielcoulbourne/verbs-sync

After installing, publish the configuration file:

php artisan vendor:publish --provider="DanielCoulbourne\VerbsSync\VerbsSyncServiceProvider"

Run the migrations:

php artisan migrate

Quick Setup

Install the package
Publish the configuration
Set your source URL and API token in your .env file
Run the sync command

Configuration

Configuration File

The package's configuration file (config/verbs-sync.php) contains the following settings:

source: Configuration for the remote source (URL and API token)
events: Configuration for which events to sync (include/exclude)
options: Syncing behavior options (batch size, retries)

Environment Variables

Configure the package using these environment variables:

VERBS_SYNC_SOURCE_URL=https://source-app.example.com
VERBS_SYNC_API_TOKEN=your-secure-token
VERBS_SYNC_INCLUDE_EVENTS=*
VERBS_SYNC_EXCLUDE_EVENTS=
VERBS_SYNC_BATCH_SIZE=100
VERBS_SYNC_RETRY_ATTEMPTS=3

Usage

To sync events from the source application:

php artisan verbs:sync

Options

--since=TIMESTAMP: Only pull events since this timestamp (ISO-8601 format)
--types=type1,type2: Comma-separated list of event types to pull
--limit=100: Maximum number of events to pull per batch
--dry-run: Show what would be synced without actually syncing

Examples

Sync all events:

php artisan verbs:sync

Sync only specific event types:

php artisan verbs:sync --types=user.created,user.updated

Sync events since a specific time:

php artisan verbs:sync --since="2023-06-01T00:00:00Z"

Preview what would be synced:

php artisan verbs:sync --dry-run

How It Works

The verbs:sync command makes a request to the source application's Verbs API
It fetches events based on your filters (event types, time range, etc.)
For each event, it:
- Checks if the event has already been synced (to avoid duplicates)
- Stores a record of the event in the local database
- Processes the event through your local Verbs system
Events are marked with synced: true metadata to prevent infinite loops

Database Tables

The package creates two tables:

verbs_sync_events: Tracks synced events with their source, type, and status
verbs_sync_logs: Records sync operations for monitoring and troubleshooting

Integrating with Scheduled Tasks

For regular syncing, you can add the command to your Laravel scheduler:

// In app/Console/Kernel.php
protected function schedule(Schedule $schedule)
{
    // Sync events every hour
    $schedule->command('verbs:sync')->hourly();
    
    // Or with options
    $schedule->command('verbs:sync --types=user.created,order.placed --limit=200')
        ->dailyAt('02:00');
}

Testing

This package includes a comprehensive test suite. To run the tests:

composer test

Test Coverage

The test suite covers:

Behavior tests for core functionality
Command option processing
Event filtering and deduplication
Error handling scenarios
End-to-end flow simulation

Troubleshooting

If you encounter issues with event syncing:

Use the --dry-run option to see what would be synced
Check your Laravel logs for errors
Ensure your API token is configured correctly
Verify network connectivity to the source application
Check that event types are not excluded in configuration

License

This package is open-sourced software licensed under the MIT license.

danielcoulbourne / verbs-sync

Maintainers

Details