mathieutu/laravel-json-syncer

Export and import your Eloquent models to/from JSON

1.5.0 2023-09-07 22:27 UTC

Requires

• php: >=8.2
• ext-json: *
• illuminate/database: ^v10.22.0
• illuminate/support: ^v10.22.0

Requires (Dev)

• orchestra/testbench: ^v8.10.1
• phpunit/phpunit: ^10.1
• squizlabs/php_codesniffer: ^3.7.2

MIT

• Mathieu TUDISCO

README

Installation

Require this package in your composer.json and update composer.

composer require mathieutu/laravel-json-syncer

Add the JsonExportable and/or JsonImportable interfaces and JsonExporter and/or JsonImporter traits to your models.

namespace App\Models;

//...
use MathieuTu\JsonSyncer\Contracts\JsonExportable;
use MathieuTu\JsonSyncer\Traits\JsonExporter;
// or/and
use MathieuTu\JsonSyncer\Contracts\JsonImportable;
use MathieuTu\JsonSyncer\Traits\JsonImporter;

class User extends Model implements JsonExportable, JsonImportable
{
    use JsonExporter;
    use JsonImporter;
    // ...
}

Configuration

Out of the box, the Importer and Exporter will automatically guess what attributes and relations to handle, but you can customize everything:

• JsonExporter: By default, it will export all the attributes in the $fillable properties, except those with *_id pattern, and all the HasOneOrMany relations of your model. You can change that by setting the $jsonExportableAttributes and $jsonExportableRelations properties or overwriting the getJsonExportableAttributes() and getJsonExportableRelations() methods.

• JsonImporter: By default, it will import all the attributes which are in the $fillable properties and all the HasOneOrMany relations of your model. You can change that by setting the $jsonImportableAttributes and $jsonImportableRelations properties or overwriting the getJsonImportableAttributes() and getJsonImportableRelations() methods.

Usage

Use the $model->exportToJson($jsonOptions = 0) to export the object, all its attributes and its children (via its relations).

Use Model::importFromJson($objectsToCreate) to import a json string or its array version.

Examples

(You can find all this examples in package tests)

How to export

If we consider this dataset in database :

{
    "foos (Foo models)": [{
        "id": 1,
        "author": "Mathieu TUDISCO",
        "username": "@mathieutu",
        "bars (HasMany relation with Bar models)": [
            {
                "id": 1,
                "name": "bar1",
                "foo_id": "1",
                "baz (HasOne relation with Baz model)": {
                    "id": 1,
                    "name": "bar1_baz",
                    "bar_id": "1"
                }
            },
            {
                "id": 2,
                "name": "bar2",
                "foo_id": "1",
                "baz (HasOne relation with Baz model)": {
                    "id": 2,
                    "name": "bar2_baz",
                    "bar_id": "2"
                }
            }
        ]
    }]
}

We can export it by:

Foo::first()->exportToJson(JSON_PRETTY_PRINT);

It will return:

{
    "author": "Mathieu TUDISCO",
    "username": "@mathieutu",
    "bars": [
        {
            "name": "bar1",
            "baz": {
                "name": "bar1_baz"
            }
        },
        {
            "name": "bar2",
            "baz": {
                "name": "bar2_baz"
            }
        }
    ]
}

How to import

And exactly the same for the opposite. We can import the json returned by the previous method, or another one. For the exact same app If we want to import this new very simple set of data:

{
    "username": "@mathieutu",
    "bars": {
        "name": "my unique simple bar!"
    }
}

We can import it with:

Foo::importFromJson($json);

And it will create all the entities in database:

dd(Foo::with('bars.baz')->first()->toArray());
/*
array:4 [
  "id" => 1
  "author" => null
  "username" => "@mathieutu"
  "bars" => array:1 [
    0 => array:4 [
      "id" => 1
      "name" => "my unique simple bar!"
      "foo_id" => "1"
      "baz" => null
    ]
  ]
]
*/

License

This JSON Syncer for Laravel is an open-sourced software licensed under the MIT license.

Contributing

Issues and PRs are obviously welcomed, as well for new features than documentation. Each piece of code added should be fully tested, but we can do that all together, so please don't be afraid by that.