danielcoulbourne / verbs-sync
Simple CLI tool to sync Laravel Verbs events from a remote source
Requires
- php: ^8.1
- guzzlehttp/guzzle: ^7.0
- hirethunk/verbs: ^0.7.0
- illuminate/console: ^8.0|^9.0|^10.0|^11.0
- illuminate/support: ^8.0|^9.0|^10.0|^11.0
Requires (Dev)
- orchestra/testbench: ^6.0|^7.0|^8.0|^9.0
- phpunit/phpunit: ^9.0|^10.0|^11.0
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 statusverbs_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.
This package is open-sourced software licensed under the MIT license.