From fb5fbbd9f00c53de6dd8468873594e7e67057c8d Mon Sep 17 00:00:00 2001 From: Marc Beinder <50760632+onairmarc@users.noreply.github.com> Date: Sun, 16 Jun 2024 22:33:12 -0500 Subject: [PATCH] Create Docs and Update Readme (#5) --- README.md | 59 ++++++---------------------------------- docs/HowToMergeModels.md | 35 ++++++++++++++++++++++++ 2 files changed, 43 insertions(+), 51 deletions(-) create mode 100644 docs/HowToMergeModels.md diff --git a/README.md b/README.md index e7149ad..24e4182 100644 --- a/README.md +++ b/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. -

- -

- ## 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) \ No newline at end of file +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. \ No newline at end of file diff --git a/docs/HowToMergeModels.md b/docs/HowToMergeModels.md new file mode 100644 index 0000000..da86cfc --- /dev/null +++ b/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. \ No newline at end of file