README

Metamorph is a Laravel package that implements a data model system based on mongodb. This package provides a powerful system for managing dynamically models for api development.

Before going any further, consider that this package is intended for API development with Laravel and Mongodb

Installation
Usage
Advanced
Changelog
Contributing
Security Vulnerabilities
Credits
License

Installation

You can install the package via composer:

composer require crucialdigital/metamorph

You must now publish the config file with:

php artisan vendor:publish --tag="metamorph-config"

Usage

Creating Model Repository and data model

Create your data model files with artisan command:

php artisan metamorph:make-model Post -R

This command will create three files:

Eloquent model file

app/Models/Post.php

Is Laravel Eloquent model extends from CrucialDigital\Metamorph\BaseModel.php class. You are free to create your model with Laravel syntax and extends CrucialDigital\Metamorph\BaseModel.php. Consider implement label() and search() method responsible respectively for labeling form resource and define field on witch query with default search term

php artisan make:model Post

Model repository file

app/Repositories/PostRepositories.php

Is the repository class responsible for creating the model query builder. You can also create repositories with artisan command

php artisan metamorph:make-repository PostRepository --model=Post

Data model form file

database/models/post.json

The json file describes the form that handles the model with all its inputs. The json file structure looks like:

{
    "name": "Post form",
    "ref": "post",
    "entity": "post",
    "readOnly": true,
    "inputs": [
        {
            "field": "name",
            "type": "text",
            "name": "Name",
            "description": "Name of the role",
            "placeholder": "Enter the name of the role",
            "required": true,
            "readOnly": true
        },
        {
            "field": "created_by",
            "type": "resource",
            "entity": "user",
            "name": "Create by",
            "description": "Role create by",
            "placeholder": "Select user",
            "required": false,
            "hidden": true,
            "readOnly": true
        }
    ],
    "columns": [
        "name",
        "user.name"
    ]
}

where required fields are entity and inputs.

Each entry of inputs must have at least:

* field: The input field
* name: The label of the input
* type: The input type in list below
    * text
    * number
    * tel
    * email
    * date
    * datetime
    * radio
    * boolean
    * select
    * textarea
    * url
    * selectresource
    * resource
    * geopoint

For input of type select, options is required and is an array of object with label and value

For input of type selectresource and resource, entity filed is required. The entity must be unique for the model around your application

Other field are :

required: boolean
hidden: boolean
readOnly: boolean
rules: string (Laravel request rules pipe separated)
description: string
placeholder: string
min: int
max: int
unique: boolean
filters: See table below

You are free to add any other field to the input that you can use in your frontend application

Configure data model into metamorph config file

To configure how metamorph maps model with repository, data model form, controller and routes, you have to indicate in metamorph config file in models and repositories sections respectively the Eloquent model and model repository.

Example :

// config/metamorph.php
[
    ....
    'repositories' => [
         'post' => \App\Repositories\PostRepository::class,
         'user' => \App\Repositories\UserRepository::class
    ],
    'models' => [
         'post' => \App\Models\Post::class,
         'user' => \App\Models\User::class
    ]
    ...
]

Run your data models

After creating your data models in .json files, you have to persist into your database with artisan command.

php artisan metamorph:models

This artisan command persists data models into the database. Every time you modify .json file in database\models, update data with this command. You can specify the name of the .json file with --name parameter

Consider configuring the mongodb database connection before.

Make API requests

Metamorph provides various endpoint de Create, Read, Update en Delete. Available endpoint are :

Model entry list request parameters

NOTE
field : value of filters can be nested relation field i.e: comments.user._id
coordinator : one of and, or to indicate using where(...) / orWhere(...)
group : is used to group filter criteria into sub-query; the value must start with one of and_ or_

Advanced

Global Middleware

To define global middleware for all metamorph routes, in metamorph config file, config/metamorph.php fill the middlewares array with your middlewares

//config/metamorph.php
...
'middlewares' => ['auth:sanctum', 'verified'],
...

If you are using Laravel Sanctum for authentification, don't forget to add the middleware auth:sanctum to avoid trouble with Metamorph authorisation system

Model Middleware

Beyond global middleware you can't define individual middleware for every model route and for each controller action in metamorph config file, config/metamorph.php fill the model_middlewares array with your middlewares

//config/metamorph.php
...
'model_middlewares' => [
    'post' => [
        'App\Http\Middleware\EnsureUserIsOwner::class' => '*', //Protect all CRUD action with the middleware for posts
        'isOwner' => ['destroy', 'update'] //Prevent non owner from deleting and updating posts
    ]
],
...

Policies

To authorize model controller action with police authorization, in metamorph config file, config/metamorph.php fill the policies array with the policy actions associate with your models

//config/metamorph.php
...
'policies' => [
    'post' => ['viewany', 'view', 'create', 'update', 'delete'],
    'user' => ['viewany', 'view', 'create', 'update', 'delete'],
    ...
 ],
...

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

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

crucialdigital / metamorph

Maintainers

Details