Download the PHP package ameax/laravel-hash-change-detector without Composer

Laravel Hash Change Detector

Detect changes in your Laravel models through hash-based tracking and automatically publish updates to external systems. Perfect for maintaining data synchronization across multiple platforms, APIs, or services.

Key Features:

• 🔄 Two-way sync for regular Eloquent models (Laravel + external changes)
• 👁️ One-way tracking for read-only models (database views, external tables)
• 🔍 Direct database detection for changes made outside Laravel
• 📤 Automatic publishing to external systems when changes are detected
• 🔗 Relationship tracking with parent-child hash propagation

Table of Contents

• Installation
• Quick Start
• Basic Usage
  • Making a Model Hashable
  • Tracking Related Models
• Model Types and Detection Strategies
• Direct Database Detection
• Publishing System
• Advanced Usage
• Commands
• Testing

Installation

Publish and run migrations:

Optionally publish the config:

Optional: API Documentation with Swagger

If you want to use the included API controllers with automatic Swagger documentation:

The API controllers include comprehensive OpenAPI attributes for automatic documentation generation with l5-swagger. See Swagger Integration Guide for details.

Quick Start

1. Make Your Model Hashable

That's it! Your model now automatically:

• Creates a hash when saved
• Updates the hash when attributes change
• Triggers events when changes are detected

Basic Usage

Making a Model Hashable

To track changes in a model, implement the Hashable interface and use the InteractsWithHashes trait:

Tracking Related Models

When you have parent-child relationships, the child models should also be hashable and define their parent relationships:

How It Works

1. Individual Hashes: Each model has its own hash based on getHashableAttributes()
2. Composite Hashes: Parent models also have a composite hash that includes hashes from all tracked relations (defined in getHashCompositeDependencies())
3. Automatic Updates: When a model changes, it notifies related models defined in getHashRelationsToNotifyOnChange() to recalculate their hashes
4. Collection Support: Automatically handles HasMany and BelongsToMany relationships, updating all models in the collection
5. Event Driven: All updates trigger events that you can listen to

Understanding the Two Relationship Methods

The package uses two methods to define relationships:

getHashCompositeDependencies()

Defines which related models should be included when calculating this model's composite hash.

• Used to track dependencies that affect this model's state
• Example: An Order includes its OrderItems in its composite hash

getHashRelationsToNotifyOnChange()

Defines which related models should be notified when this model changes.

• Used to propagate changes up the relationship chain
• Supports both single models (BelongsTo, HasOne) and collections (HasMany, BelongsToMany)
• Example: When an OrderItem changes, it notifies its parent Order

Model Types and Detection Strategies

The package supports two types of models, each with different use cases:

1. Regular Models (Two-Way Sync)

Standard Eloquent models that can be modified both through Laravel AND external systems:

When to use:

• Models primarily managed through Laravel but occasionally updated externally
• E-commerce products (admin panel + inventory systems)
• User profiles (app + customer service tools)
• Orders (website + imports from other systems)

Features:

• ✅ Full Eloquent functionality (create, update, delete)
• ✅ Automatic hash updates via model events
• ✅ Direct database detection for external changes
• ✅ Can track relationships

2. Read-Only Models (One-Way Sync)

Models that are NEVER modified through Laravel, only tracked for external changes:

When to use:

• Database views
• External system tables (shared databases)
• Analytics/reporting tables (populated by ETL)
• Legacy tables you shouldn't modify
• Tables updated by database triggers/procedures

Features:

• ✅ Read operations via Eloquent
• ❌ No write operations (blocked)
• ❌ No model event overhead
• ✅ Direct database detection only
• ✅ Better performance for large datasets

Choosing the Right Approach

Direct Database Detection

Direct database detection finds changes made outside of Laravel (SQL updates, triggers, external apps, etc.).

Setting Up Detection

Add to your scheduler in app/Console/Kernel.php:

How Direct Detection Works

1. Calculates hashes in the database using SQL functions
2. Compares with stored hashes to find changes
3. Updates changed records and triggers events
4. Detects deletions by finding orphaned hash records

Deletion Detection

The package automatically detects when models are deleted:

Immediate Detection (Eloquent Deletions)

When models are deleted through Eloquent ($model->delete()), deletion publishers are triggered immediately:

• The HashableModelDeleted event fires before the hash is removed
• All configured DeletePublishers are notified instantly
• No need to wait for scheduled detection

Scheduled Detection (Direct Database Deletions)

For deletions made outside Laravel (DELETE FROM orders WHERE id = 123):

• The scheduled detect-changes command finds orphaned hash records
• Updates all dependent models that referenced the deleted model
• Triggers deletion events for configured DeletePublishers
• Cleans up orphaned hash and publish records

Both methods ensure your external systems are notified when data is removed.

Example Scenario

Publishing System

Automatically sync changes to external systems by creating publishers:

Creating Publishers for Create/Update Operations

Creating Publishers for Delete Operations

For handling model deletions, implement the DeletePublisher interface:

Combined Publisher (Handles Both Operations)

You can create a publisher that handles both create/update and delete operations:

Registering Publishers

In a service provider:

Or via command:

Retry Failed Publishes

Add to your scheduler:

Advanced Usage

Working with Read-Only Models

For read-only models (see Model Types above), you need to initialize hashes since there are no Eloquent events:

Then use normal detection:

Mixed Model Environment

You can use both model types in the same application:

Nested Relations

Track nested relationships using dot notation:

Multiple Parents & Collections

A model can notify multiple parent models, including collections:

The package automatically handles both single models and collections, updating all dependent models when changes occur.

Circular Dependency Protection

The package includes built-in protection against infinite loops in circular relationships:

Protection Mechanisms:

1. Cycle Detection: Models currently being processed are tracked to prevent re-entry
2. Depth Limiting: Maximum update chain depth of 10 levels
3. Automatic Recovery: Processing stack is cleared after each update chain

Best Practices:

• Design your relationships to minimize circular dependencies
• Use one-way notifications where possible (child → parent)
• Consider using composite dependencies instead of bidirectional notifications

Custom Hash Algorithm

In your config file:

Syncing from External APIs

When receiving data from external APIs, you can update models without triggering publishers:

Key Features:

• Updates hash to reflect current state
• Marks specified publishers as "synced" without triggering them
• Prevents infinite sync loops between systems
• Fires HashUpdatedWithoutPublishing event instead of HashChanged

Handling Deletions

Listen for deletion events:

Commands

Complete Example

Here's a full example with Order and OrderItem models:

API Endpoints

The package provides a comprehensive REST API for managing hash detection and publishing:

Setup

Include the API routes in your application:

Available Endpoints

Model Hash Information

Force Publish (Without Hash Change)

Publish History

Publisher Management

Operations

Statistics

API Usage Examples

Testing

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email the maintainers directly instead of using the issue tracker.

Credits

• Michael Schmidt
• All Contributors

License

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