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
3. Automatic Updates: When a child changes, it notifies its parents to recalculate their composite hashes
4. Event Driven: All updates trigger events that you can listen to

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

Example Scenario

Publishing System

Automatically sync changes to external systems by creating publishers:

Creating a Publisher

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

A model can notify multiple parent models:

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.