Download the PHP package apptank/horusync without Composer

Please note: This library currently is in testing stage until publish the version 1.0.0.

Horus Sync

This library provides an easy way to manage data synchronization between a remote database on a server and a local database on a mobile device. It defines a set of synchronizable entities by specifying their parameters and relationships with other entities.

Features

• Data Synchronization: Enables synchronization of the defined entities' data between the local database and the remote database.
• Schema Migration: Allows retrieval of the schema for synchronizable entities and their relationships.
• Integrity Validation: Ensures the integrity of synchronized data.
• Authentication and Permissions: Defines an authenticated user and the permissions associated with the entities.
• Upload Files: Allows uploading files to the server.
• Middlewares: Supports defining custom middlewares for synchronization routes.
• UUID Support: Allows specifying whether UUIDs or Int will be used as the primary key for entities.
• Foreign Key Support: Supports defining foreign keys in synchronizable entities with cascading delete functionality.
• UserActingAs Support: Indicates if a user has permission to act as another user and access the entities where permissions have been granted.
• Support for Synchronizable Entity Types: Supports defining entities as writable or readable, depending on whether they can be edited or not.

📦 Installation

This library must be used with Laravel version 11 or higher.

Use the following command to install the package using Composer:

🔨 Usage

All synchronizable models with editable records must inherit from WritableEntitySynchronizable, defining the properties they contain. If you want a read-only entity, you should inherit from ReadableEntitySynchronizable.

You can use an artisan command to generate a synchronizable model for you. You just need to specify the path where the model should be stored. The following example will create a model in App/Models/Sync/MyModelSync:

If you want to create a read-only entity, you can add the --readable option to the artisan command.

🚀 Quick Start

1. Initialization

It is necessary to initialize the Horus container in the AppServiceProvider of Laravel by passing an array with the hierarchical map of entities.

You can optionally

• Define the database connection name
• Whether UUIDs or Int will be used as the primary key.
• Define a prefix for the tables of entities in the database.
• Enable or disable the validation of access to entities. Improve performance by disabling this option.
• Prefix for the tables of entities in the database.
• Define the entity restrictions.

2. Run Migrations

Once the Horus container has been initialized, you need to run the synchronization tables migrations.

⬆️ Enable upload files

To enable the upload files feature, you need setup a file handler in horus initialization, implementing the IFileHandler interface.

In your writable entity synchronizable model, you can define the file attribute using the SyncParameter::createReferenceFile method.

Local File Handler example

The following example shows how to implement a file handler for local file storage using Laravel's storage system.

Prune files

If you want to delete files that are no longer referenced by any entity, you can use the following command:

• expirationDays: The number of days after which files will be deleted.

↔️ Middlewares

If you want to implement custom middlewares for the synchronization routes, you can do so in your Service Provider as follows:

🔒 Authentication and Permissions

The following code shows how to configure user authentication and the permissions associated with entities. Using the UserAuth class, you define an authenticated user along with the entities they have access to and the corresponding permissions.

(Recommend) Setup entity granted on validate entity was granted to void sync issues.

⛔ Entity Restrictions

If you want to apply a restriction to an entity, you can use the next restriction classes:

• MaxCountEntityRestriction: Restricts the number of records that can be synchronized for an entity to specific user.
• FilterEntityRestriction: This restriction allows you to filter the records from an entity can be obtained given a set of parameters. This is useful when you want to limit the data that can be downloaded to client based on certain criteria.
• LimitCountEntityParentRetrieveRestriction: This restriction allows you to limit the number of parent records that can be retrieved by user owner for a specific entity.
• LimitCountEntityChildrenRetrieveRestriction: This restriction allows you to limit the number of children records that can be retrieved from a parent entity by user owner for a specific entity.
• ExternalEntityFilterRestriction: This restriction allows you to apply complex filtering logic to entities after they are retrieved from the database. It supports filtering based on custom callable functions and transforming specific entity parameters using value transformers. This is useful when you need advanced filtering that cannot be expressed through simple parameter filters.

Setup after initialization

By default, the setup is set the Config class in the Horus initialization, but if you want to change the restrictions after you can use the next code:

🍒 Shared entities

If you want to share records from specific entities, you can use the method setSharedEntities or setupOnSharedEntities in the Horus instance like this:

(Recommend) This way, only setup the shared entities when Horus needs it.

✉️ Events

If you want to listen to events that occur during synchronization, you can use the following code:

Insert Event

Update Event

Delete Event