PHPackages                             crucialdigital/metamorph - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. crucialdigital/metamorph

ActiveLibrary[HTTP & Networking](/categories/http)

crucialdigital/metamorph
========================

Package of data models managements

3.0.0(1y ago)31.7kMITPHPPHP ^8.1|8.2|8.3

Since Apr 4Pushed 2mo ago2 watchersCompare

[ Source](https://github.com/crucialdigital/metamorph)[ Packagist](https://packagist.org/packages/crucialdigital/metamorph)[ Docs](https://github.com/crucialdigital/metamorph)[ RSS](/packages/crucialdigital-metamorph/feed)WikiDiscussions master Synced today

READMEChangelog (6)Dependencies (17)Versions (9)Used By (0)

Crucial Digital Metamorph
=========================

[](#crucial-digital-metamorph)

[![Latest Version on Packagist](https://camo.githubusercontent.com/0fa3b9c2a2b1990269ac6dc4bed740921f4b47b3c5ae1bcbf0e783928de97bb8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6372756369616c6469676974616c2f6d6574616d6f7270682e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/crucialdigital/metamorph)[![GitHub Tests Action Status](https://camo.githubusercontent.com/a4cb31490a989deecb0e4f67cf3a1bf7bfbf291f0f36ceb7aac987338fb2c74f/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f776f726b666c6f772f7374617475732f6372756369616c6469676974616c2f6d6574616d6f7270682f72756e2d74657374733f6c6162656c3d7465737473)](https://github.com/crucialdigital/metamorph/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/f38aaede741d3102abb1d92d187834c79f8c98750f1c25c25def93981e20592b/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f776f726b666c6f772f7374617475732f6372756369616c6469676974616c2f6d6574616d6f7270682f466978253230504850253230636f64652532307374796c652532306973737565733f6c6162656c3d636f64652532307374796c65)](https://github.com/crucialdigital/metamorph/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/166090127b3a67c4c76557a14bd154068659fffd094d545dedc452964f122fb1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6372756369616c6469676974616c2f6d6574616d6f7270682e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/crucialdigital/metamorph)

**Metamorph** is a Laravel package (v3.x) that provides a complete, schema-driven REST API layer on top of **MongoDB**. Instead of hand-writing controllers, form requests, and routes for every resource, you describe your data models once — in a JSON file — and Metamorph automatically exposes a fully functional CRUD API with filtering, pagination, search, file upload, export, and policy enforcement.

Key features
------------

[](#key-features)

FeatureDescription**JSON Data Models**Declare form structure, field types, and validation rules in a single `.json` file**Auto CRUD API**`POST / GET / PUT / PATCH / DELETE` endpoints generated automatically per entity**Advanced Querying**25+ filter operators (`=`, `like`, `in`, `between`, `geoWithin`, …) with `and`/`or` grouping**Soft Delete & Restore**Built-in support for `withTrashed`, `onlyTrashed`, `restore`, and `forceDelete`**File & Photo Upload**Automatic upload handling, storage, and thumbnail generation via Intervention Image**Data Export**Export any entity to CSV, XLSX, XLS, ODS, or PDF via Maatwebsite Excel**Dynamic Relations**Eager-load any Eloquent relation on the fly using the `relations` query parameter**Repository Pattern**Override the default query builder per entity with a custom `DataRepositoryBuilder`**Middleware & Policies**Apply global or per-model middleware and Laravel Gate policies from the config file**Artisan Scaffolding**Generate models, repositories, and data model stubs with a single command**Cache Service**Optional tenant-aware, per-entity result caching with Redis or tag-based invalidationRequirements
------------

[](#requirements)

- PHP **^8.1**
- Laravel **^10 | ^11 | ^12**
- MongoDB driver — [`mongodb/laravel-mongodb`](https://github.com/mongodb/laravel-mongodb) **^5.4**
- A configured MongoDB connection in your Laravel application

> **Note** — This package is designed exclusively for **API development with Laravel and MongoDB**. It does not support SQL databases.

Table of contents
-----------------

[](#table-of-contents)

- [Installation](#installation)
- [Usage](#usage)
    - [Step 1 — Scaffold files with Artisan](#step-1--scaffold-files-with-artisan)
    - [Step 2 — The Eloquent Model (BaseModel)](#step-2--the-eloquent-model-basemodel)
    - [Step 3 — The Data Repository](#step-3--the-data-repository)
    - [Step 4 — The JSON Data Model](#step-4--the-json-data-model)
    - [Step 5 — Register in config/metamorph.php](#step-5--register-in-configmetamorphphp)
    - [Step 6 — Sync data models to the database](#step-6--sync-data-models-to-the-database)
    - [Make API requests](#make-api-requests)
        - [1. Entity CRUD — master/{entity}](#1-entity-crud--masterentity)
        - [2. Search & List — search/{entity}](#2-search--list--searchentity)
        - [3. Bulk Resource Lookup — many/search](#3-bulk-resource-lookup--manysearch)
        - [4. Data Export — exports/{entity}/{form}](#4-data-export--exportsentityform)
        - [5. Form Management — forms](#5-form-management--forms)
        - [6. Form Inputs — form-inputs](#6-form-inputs--form-inputs)
        - [7. Form Data (Draft Workflow) — form-data](#7-form-data-draft-workflow--form-data)
        - [8. Resources — resources](#8-resources--resources)
- [Advanced](#advanced)
    - [Global Middleware](#global-middleware)
    - [Model Middleware](#model-middleware)
    - [Policies](#policies)
    - [Cache Service](#cache-service)
    - [File & Photo Upload](#file--photo-upload)
- [Changelog](#changelog)
- [Contributing](#contributing)
- [Security Vulnerabilities](#security-vulnerabilities)
- [Credits](#credits)
- [License](#license)

Installation
------------

[](#installation)

### Prerequisites

[](#prerequisites)

Before installing Metamorph, make sure your Laravel application has:

- A **MongoDB** instance accessible from your server
- The **PHP MongoDB extension** installed (`ext-mongodb`)
- The **`mongodb/laravel-mongodb`** package configured as your default or secondary database connection

If you have not set up the MongoDB driver yet, follow the [official Laravel MongoDB documentation](https://www.mongodb.com/docs/drivers/php/laravel-mongodb/).

---

### 1. Install via Composer

[](#1-install-via-composer)

```
composer require crucialdigital/metamorph
```

The service provider `MetamorphServiceProvider` is automatically registered via Laravel's package discovery — no manual registration needed.

---

### 2. Configure MongoDB connection

[](#2-configure-mongodb-connection)

In your `.env` file, add (or update) the MongoDB connection variables:

```
DB_CONNECTION=mongodb
DB_HOST=127.0.0.1
DB_PORT=27017
DB_DATABASE=your_database_name
DB_USERNAME=
DB_PASSWORD=
```

Then ensure `config/database.php` includes a MongoDB connection entry:

```
// config/database.php
'connections' => [

    'mongodb' => [
        'driver'   => 'mongodb',
        'host'     => env('DB_HOST', '127.0.0.1'),
        'port'     => env('DB_PORT', 27017),
        'database' => env('DB_DATABASE', 'homestead'),
        'username' => env('DB_USERNAME', ''),
        'password' => env('DB_PASSWORD', ''),
        'options'  => [],
    ],

],

'default' => env('DB_CONNECTION', 'mongodb'),
```

---

### 3. Publish the configuration file

[](#3-publish-the-configuration-file)

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

This creates `config/metamorph.php` in your application with all available options and their default values. See [Step 5 — Register in config/metamorph.php](#step-5--register-in-configmetamorphphp) for a full reference.

---

### 4. Run the install command *(optional)*

[](#4-run-the-install-command-optional)

```
php artisan metamorph:install
```

This command creates the required directories (`database/models`, `app/Repositories`) if they do not already exist and verifies that the MongoDB connection is reachable.

---

### Package dependencies

[](#package-dependencies)

Metamorph automatically pulls the following packages via Composer:

PackageVersionPurpose`mongodb/laravel-mongodb``^5.4`MongoDB Eloquent driver`intervention/image``^2.7`Photo resizing & thumbnail generation`maatwebsite/excel``^3.1`CSV / XLSX / PDF data export`spatie/laravel-package-tools``^1.13`Package service provider utilitiesUsage
-----

[](#usage)

The typical workflow for adding a new resource to your API has four steps:

```
1. Scaffold  →  2. Configure JSON data model  →  3. Register in config  →  4. Sync to database

```

---

### Step 1 — Scaffold files with Artisan

[](#step-1--scaffold-files-with-artisan)

The fastest way to get started is the all-in-one command:

```
# Creates the Eloquent model, its DataRepository AND the JSON data model in one shot
php artisan metamorph:make-model Post -R
```

This generates **three files**:

FilePathPurposeEloquent Model`app/Models/Post.php`MongoDB Eloquent model extending `BaseModel`Repository`app/Repositories/PostRepository.php`Custom query builderData Model`database/models/post.json`JSON form definitionYou can also scaffold each file individually:

```
# Model only
php artisan metamorph:make-model Post

# Repository only (model name is required)
php artisan metamorph:make-repository PostRepository --model=Post

# JSON data model only
php artisan metamorph:make-data-model Post
```

---

### Step 2 — The Eloquent Model (`BaseModel`)

[](#step-2--the-eloquent-model-basemodel)

Every Metamorph model must extend `CrucialDigital\Metamorph\Models\BaseModel` and implement two abstract methods:

```