Create Docs and Update Readme (#5)

README.md

@@ -1,68 +1,25 @@
-# ModelMerge Laravel package
-
-[![Latest Stable Version](https://poser.pugx.org/alariva/modelmerge/v/stable?format=flat)](https://packagist.org/packages/alariva/modelmerge)
-[![Total Downloads](https://poser.pugx.org/alariva/modelmerge/downloads?format=flat)](https://packagist.org/packages/alariva/modelmerge)
-[![Latest Unstable Version](https://poser.pugx.org/alariva/modelmerge/v/unstable?format=flat)](https://packagist.org/packages/alariva/modelmerge)
-[![Build Status](https://travis-ci.org/alariva/laravel-modelmerge.svg?branch=master)](https://travis-ci.org/alariva/laravel-modelmerge)
-[![Maintainability](https://api.codeclimate.com/v1/badges/f8829aab2f787e403d3e/maintainability)](https://codeclimate.com/github/alariva/laravel-modelmerge/maintainability)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/f8829aab2f787e403d3e/test_coverage)](https://codeclimate.com/github/alariva/laravel-modelmerge/test_coverage)
-[![License](https://poser.pugx.org/alariva/modelmerge/license?format=flat)](https://packagist.org/packages/alariva/modelmerge)
-[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Falariva%2Flaravel-modelmerge.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Falariva%2Flaravel-modelmerge?ref=badge_shield)
+# EncoreDigitalGroup\MergeModels
 
 Easy merging for Eloquent Models.
 
-<p align="center">
-<img src="https://i.imgur.com/iT0vLSC.png" height="275">
-</p>
-
 ## Installation
 
 Via Composer
 
 ``` bash
-$ composer require alariva/modelmerge
+$ composer require encoredigitalgroup/mergemodels
 ```
 
 ## Usage
 
-```php
-    $modelA = SampleModel::make(['firstname' => 'John', 'age' => 33]);
-    $modelB = SampleModel::make(['firstname' => 'John', 'lastname' => 'Doe']);
-
-    $mergedModel = ModelMerge::setModelA($modelA)->setModelB($modelB)->merge();
-
-    $mergedModel->firstname; // John
-    $mergedModel->lastname; // Doe
-    $mergedModel->age; // 33
-```
-
-## Change log
-
-Please see the [changelog](changelog.md) for more information on what has changed recently.
-
-## Testing
-
-``` bash
-$ composer test
-```
-
-## Contributing
-
-Please see [contributing.md](contributing.md) for details and a todolist.
-
-## Security
-
-If you discover any security related issues, please email author email instead of using the issue tracker.
+- [How to Merge Models](./docs/HowToMergeModels.md)
 
 ## Credits
 
-- [Ariel Vallese](https://alariva.com)
-- Icons made by [Freepik](http://www.freepik.com) from [Flaticon](http://www.flaticon.com) is licensed by [CC 3.0 BY](http://creativecommons.org/licenses/by/3.0/)
-- Icons made by [Roundicons](https://www.flaticon.com/authors/roundicons) from [Flaticon](http://www.flaticon.com) is licensed by [CC 3.0 BY](http://creativecommons.org/licenses/by/3.0/)
-
-## License
-
-MIT. Please see the [license file](license.md) for more information.
+- [Ariel Vallese](https://alariva.com) (Original Package Developer)
+- [Encore Digital Group](https://EncoreDigitalGroup.com) (Maintainer)
 
+### Why does this package exist?
 
-[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Falariva%2Flaravel-modelmerge.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Falariva%2Flaravel-modelmerge?ref=badge_large)
+The original package had not been updated since 2020 and was not compatible with Laravel 11. Encore Digital Group forked this package and is now maintaining
+a copy as we required this functionality in several internal applications.

docs/HowToMergeModels.md

@@ -0,0 +1,35 @@
+# How to Use the `ModelMerge` Class
+
+The `MergeModels` facade is the primary way to interact with the `ModelMerge` class. This class provides a simple and flexible way to merge two models in a Laravel
+application.
+
+Below is an example script that merges two contacts into a single contact record.
+
+```php
+use EncoreDigitalGroup\MergeModels\MergeModels;
+use App\Models\Contact;
+
+$originalContact = Contact::find(1);
+$duplicateContact = Contact::find(2);
+
+MergeModels::setBaseModel($originalContact)->setDuplicateModel($duplicateContact)->unifyOnBase();
+```
+
+## What does this script do?
+
+1. We locate the original contact by its ID. In this case 1.
+2. We locate the duplicate contact by its ID. In this case 2.
+3. We use the MergeModels facade and inform the Merger that the base model is contact 1 and the duplicate model is contact 2.
+4. We then tell the Merger to unify these two contacts into a single record, in this case the base model (contact 1).
+
+## What about merging relationships?
+
+MergeModels supports merging HasMany relationships as well. Let's say that your contact model has a relationship defined for the contact's email. Since
+contacts can have multiple emails, it's a HasMany relationship named `emailAddresses`. To merge the duplicate contacts `emailAddresses` relationship
+into the base contact, we would adjust the Merger as follows:
+
+```php
+MergeModels::setBaseModel($baseContact)->setDuplicateModel($duplicateContact)->withRelationships(['emailAddresses'])->unifyOnBase();
+```
+
+Now all email addresses associated with the duplicate contact have been transferred to the base contact.