Download the PHP package moox/sync without Composer

Moox Sync

Moox Sync is a powerful package for synchronizing data across multiple platforms in Laravel applications. It enables you to keep records in sync between different Moox platforms or other Filament and Laravel platforms. It is designed to be easy to use and configurable, with a focus on security (for synchronizing users) and flexibility.

https://github.com/user-attachments/assets/877e52a8-3f7b-4527-ab75-03996155ec41

Quick Installation

These two commmands are all you need to install the package:

Curious what the install command does? See manual installation below.

Create Platforms

First, you need to create a platform, better two. You would be able to sync on the same platform (but different model of course), but that is not the main idea of Sync.

So, let's create platforms.

A platform should have a name, a domain (we'll search the IP for you) and a token, that can be generated by the button.

Now the platforms are created and we can see it in the list and use them for our first Sync.

Create Syncs

After creating platforms, you are able to create a Sync between platforms.

Choose the Source Platform and Model, the Target Platform and Model and enable Platform Relations, if the model supports it, see Platform Relations.

Now you can see your Syncs in the list.

Key Concept

It is crucial to understand, that Moox Sync is not a two-way sync that simply copies data from A to B. It is a one-way sync from Source to Target, but it is made to be central-managed and it is smart, extensible and secure.

SyncPlattformsJob

Platforms are automatically synced between all platforms. For the first time done with basic security only using the Sync Token from config, afterwards adding the platform-token to provide first class security including HMAC.

The SyncPlatformsJob can be enabled via config or .env. This should run on not more than ONE platform.

As an alternative to running the job periodically (minutely by default), you can manually start the Job by pressing the Sync Platforms button after making updates to platforms.

SyncListener

The SyncListener runs an Eloquent Event Listener for each Sync and catches up all model changes done with Eloquent. If you change data in models without using Eloquent, you may consider firing an event:

Note: For handling imports or changes done outside of Laravel, we recommend running the SyncBackupJob.

The SyncListener runs the PrepareSynJob.

The SyncListener needs to be activated in Moox Sync Configuration. That should be done on Source platforms only.

PrepareSyncJob

The PrepareSyncJob is invoked by the SyncListener. It prepares the data and triggers the SyncWebhook.

The PrepareSyncJob supports custom data handling like custom queries, data manipulation, so called Transformers, also available as Transformer Bindings, configured in Moox Sync Configuration. See Advanced Usage.

SyncWebhook

Act as the entry point on the target platform, receiving data from the source platform via the PrepareSyncJob. Validates the incoming data using HMAC and checks for any transformation or field mapping requirements specified in the sync configuration.

Triggers the SyncJob with the validated and transformed data.

The SyncWebhook needs to be activated in Moox Sync Configuration. It needs to be enabled on Target platforms only.

SyncJob

The SyncJob queues the actual sync by using the SyncService.

SyncService

The Sync writes the data on the Target platform. It supports Custom SyncHandlerand PlatformRelations. See Advanced Usage.

Advanced Usage

Transformer

Transformers are not implemented yet. We recommend using Transformer Bindings instead.

Transformer Bindings

While the (selectable in Sync) Transformer feature is not fully implemented, you can use Transformer Bindings for custom data transformation logic.

To create a custom transformer:

1. Create a new class that extends AbstractTransformer.
2. Implement the transformCustomFields method.
3. Register your transformer in the transformer_bindings config.

See WpUserTransformer in Moox Press on how to implement a Transformer binding.

SyncHandler

For complex models requiring custom sync logic, implement Sync Handlers:

1. Create a new class that extends AbstractSyncHandler.
2. Implement the syncModel and deleteModel methods.
3. Register your sync handler in the sync_bindings config.

See WpUserSyncHandler in Moox Press on how to implement your own SyncHandler.

PlatformRelations

The PlatformRelationService is an optional feature, you can set for every sync. It is a key component of Moox Sync that handles the relationships between models and platforms. It provides methods for syncing and retrieving platform associations for any model.

Key methods:

• syncPlatformsForModel($model, array $platformIds): Syncs the platforms for a given model.
• getPlatformsForModel($model): Retrieves the platforms associated with a given model.

How to implement PlatformRelations

To implement PlatformRelations, you need to configure the models_with_platform_relations in the Moox Sync config. This is a list of models that should have platform relations.

While the relations are automatically added to the model, you may want to add a field to your Filament Resource to manage the platforms for a given record.

SyncBackupJob

Not implemented yet!

The SyncBackupJob runs as a fallback, if the Eloquent listener is disabled or not invoked. It checks for changes in the database and syncs them to the target platform.

Security

Moox Sync implements robust security measures:

Webhook Authentication

The WebhookAuthMiddleware handles this authentication and verification process:

• The API token authenticates the source platform with a shared secret, so be changed in config, so even the initial platform sync is done securely
• After platforms are synced, the shared secret and platform token are used together to provide additional security
• The HMAC signature verifies the integrity of the payload.
• HTTPS (which you should enforce) protects against man-in-the-middle attacks

In addition, you are able to change the webhook url, so that guessing the webhook url becomes difficult.

Token Authentication

For API endpoints, Moox Sync uses token-based authentication via the PlatformTokenAuthMiddleware. Alternatively, you can use Sanctum to authenticate your API requests.

Config

Moox Sync is highly configurable via the sync.php config file. Here are the available options:

Logging

Setting up Sync involves the connection of two or more platforms, availability of APIs and running Jobs. This is why we added a logger to the package, that can be setup in Moox Core config. The flow of a working sync may look like this. Depending on the log level you get very detailed information about the data flow in Moox Sync. On production anything else than 0 should not be the default, but can perfectly used to implement or debug Moox Sync.

Manual Installation

Instead of using the install-command php artisan mooxsync:install you are able to install this package manually step by step:

Edit your PanelProvider to add both Plugins to your Navigation.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• All Contributors

License

The MIT License (MIT). Please see License File for more information.