MongoDB Level 1 compatibility

MongoDB Level 1 lets an Adminix module use an official MongoDB Eloquent model while the Laravel application's default connection and Adminix-owned storage remain SQL. It is an opt-in hybrid topology: SQL-only applications do not install a MongoDB dependency, and MongoDB as the default Laravel connection remains unsupported.

Install the optional integration

Keep Adminix installed normally, then add the official integration in the consuming application.

composer require mongodb/laravel-mongodb:^5.8

The application must also load a compatible ext-mongodb. Adminix does not require either package at runtime for SQL-only installations; Composer lists them only under suggest.

Configure a named MongoDB connection while keeping database.default on SQLite, MySQL, MariaDB, or PostgreSQL.

// config/database.php

'default' => env('DB_CONNECTION', 'pgsql'),

'connections' => [
    // Keep the application's normal SQL connection here.

    'mongodb' => [
        'driver' => 'mongodb',
        'dsn' => env('MONGODB_URI'),
        'database' => env('MONGODB_DATABASE', 'adminix'),
    ],
],

Create an application model that extends the official integration model and selects that connection.

namespace App\Models;

use MongoDB\Laravel\Eloquent\Model;

class MongoOrder extends Model
{
    protected $connection = 'mongodb';

    protected $collection = 'orders';

    protected $guarded = [];
}

Pass the model class, not a collection string, to Adminix.

use AlexKudrya\Adminix\AdminixPage;
use AlexKudrya\Adminix\Modules\List\ListField;
use AlexKudrya\Adminix\Modules\Module;
use App\Models\MongoOrder;

return AdminixPage::uri('mongo-orders')
    ->name('mongo-orders-page')
    ->addModule(
        Module::list()
            ->name('mongo-orders')
            ->dataSource(MongoOrder::class)
            ->primaryKey('id')
            ->criteria([['tenant_id', '=', 'param:0']])
            ->addFields(
                ListField::name('ID')->field('id'),
                ListField::name('Number')->field('number')->sortable(),
                ListField::name('Risk')->field('risk.score'),
            ),
    );

Opening /adminix/mongo-orders/{tenant} renders only the scoped MongoDB documents. Adminix converts string route identifiers at the model boundary, but the browser never supplies an authoritative BSON object, datasource, primary key, writable-field list, or tenant scope.

Run Doctor after configuring the page.

php artisan adminix:doctor --strict

Required Level 1 topology

Laravel's default database connection remains SQL.
Authentication and the normal Adminix guard remain SQL-backed.
Package migrations run only on the SQL default connection.
Standard notification, preference, saved-table-view, and other Adminix repositories remain SQL-backed.
MongoDB modules use an explicit MongoDB\Laravel\Eloquent\Model subclass whose connection is MongoDB.
Bare dataSource('collection') is not a Level 1 MongoDB datasource contract.

MongoDB as database.default, MongoDB-backed package migrations, and native MongoDB standard-storage providers are Level 2 work and remain unsupported.

Tested versions

The Level 1 compatibility matrix was verified on 2026-07-26.

Layer	Tested versions
PHP floor runtimes	PHP 8.2.32 and PHP 8.3.32
Laravel 12	Laravel 12.0.0 floor and Laravel 12.64.0 current
Laravel 13	Laravel 13.0.0 floor and Laravel 13.22.0 current
Official integration	`mongodb/laravel-mongodb` 5.8.2
PHP extension	`ext-mongodb` 2.3.3
MongoDB Server	MongoDB Server 8.0.28
Replica-set gate	One primary and two secondaries; commit and rollback verified

Laravel 12.0.0 is installed and runtime-loaded in the PHP 8.2 floor fixture. Because Orchestra Testbench 10.0 starts at Laravel 12.0.1, the focused SQL datasource, resource, validation, and Doctor regressions run on Laravel 12.0.1 in that same PHP 8.2 image. This test-harness patch boundary does not narrow Adminix's Laravel 12.0.0 Composer support.

The package's normal SQL suite remains independent of these optional versions. A future integration, extension, server, or framework version is not covered until the compatibility fixtures pass again.

BSON and resource writes

Level 1 covers native ObjectId identifiers, UTCDateTime, Decimal128, nested values, missing fields, nulls, arrays, and Unicode presentation. String ObjectIds are normalized only at HTTP, signed-context, queue, and presentation boundaries. Malformed, stale, foreign-tenant, or missing ObjectIds return controlled errors without an unscoped query or mutation.

Resource and modal create/update flows derive datasource, primary key, writable fields, static hidden values, and signed param:* context from the server-side module. Use model-qualified or explicitly connection-qualified database validation rules so Laravel does not query the SQL default connection for MongoDB uniqueness.

use App\Models\MongoOrder;
use Illuminate\Validation\Rule;

ResourceField::name('Number')
    ->field('number')
    ->required()
    ->setValidation([
        'required',
        Rule::unique(MongoOrder::class, 'number'),
    ]);

An unchanged MongoDB update is successful when the scoped document still exists. Adminix distinguishes a matched document from a missing document instead of treating a zero modified-count as not found.

Module capability matrix

“Supported” means the Level 1 integration and browser suites cover the module path shown below. “Custom only” means an application-owned provider or handler must own persistence. “Unsupported” means Adminix rejects the SQL-specific path with a controlled capability error.

Module type	Level 1 status	Boundary
`chart_line`	Unsupported	SQL date expressions; use a native custom module/provider.
`chart_bar`	Supported	Simple per-criteria counts; SQL expression charts are not included.
`counter`	Supported	MongoDB model count with scoped criteria.
`metric`	Unsupported	SQL partition, trend, and date expressions.
`progress_bar`	Supported	The application handler owns progress persistence.
`import`	Custom only	The application import handler owns MongoDB writes.
`media_browser`	Supported	Filesystem-backed; no MongoDB query.
`tenant_switcher`	Custom only	The application tenant provider owns persistence.
`dashboard`	Supported	PHP-only composition; each nested module keeps its own status.
`panel`	Supported	PHP-only composition; each nested module keeps its own status.
`text`	Supported	Static presentation.
`audit_panel`	Custom only	Use an application audit provider for non-SQL persistence.
`clock`	Supported	Presentation-only.
`list`	Supported	Criteria, filters, quick filters, lenses, sorting, pagination, CSV, nested/missing values, count summaries, referenced relations, soft deletes, scoped bulk/custom actions; see unsupported list features below.
`detail`	Supported	Read-only MongoDB model fetch.
`resource`	Supported	Scoped fetch/update, validation, signed context, ObjectId routing, and unchanged updates.
`new_resource`	Supported	Create with server-derived writable and hidden fields.
`link`	Supported	Routing-only.
`adminix_link`	Supported	Adminix routing-only.
`display_value`	Supported	Static presentation.
`modal_resource`	Supported	Modal fetch and scoped save with string ObjectId transport.
`modal_new_resource`	Supported	Modal create with authoritative backend validation.
`modal_toggler`	Supported	Presentation-only; the target modal keeps its own status.
`callback_action`	Supported	The application callback/webhook handler owns external writes.
`maintenance_banner`	Supported	Presentation-only.
`health_status`	Supported	The application health handler owns external checks.

List support does not include built-in raw search, embedded relations, built-in clone, or built-in reorder. Use scoped filters instead of raw search, referenced relationships instead of embedded relation modules, application actions instead of clone, and reorderUsing() for application-owned MongoDB ordering.

Non-module surfaces

Surface	Level 1 status	Boundary
`global_search`	Unsupported	Built-in global search uses raw SQL expressions.
`async_select`	Unsupported	Built-in async search uses SQL search expressions.
`auth`	Supported	The Level 1 guard remains on the SQL default connection.
`package_migrations`	Supported	Package migrations run against SQL only.
`notification_storage`	Unsupported	Standard notification storage requires SQL.
`preference_storage`	Unsupported	Standard preference storage requires SQL.
`table_view_storage`	Unsupported	Standard saved views and repair require SQL.
`tenant_storage`	Custom only	Use an application tenant provider.
`audit_storage`	Custom only	Use an application audit provider.
`standard_storage`	Unsupported	Standard Adminix repositories remain SQL-only.
`custom_storage`	Custom only	Existing application provider contracts own persistence.
`smart_schema`	Unsupported	Smart generation requires relational schema metadata.

The storage rows marked unsupported refer to MongoDB storage. They are supported in the required Level 1 topology because those standard stores remain on SQL.

Reorder, transactions, and replica sets

Built-in reorder and clone inspect relational schema and are not exposed for a MongoDB model. For MongoDB reorder, configure reorderUsing() and implement tenant scope, authorization, concurrency, locking/version checks, and persistence in the consuming application. Adminix still verifies the signed visible ID set before calling the handler.

MongoDB Level 1 custom reorder on a mobile viewport

Single-document CRUD does not require a transaction. Any custom operation that requires atomic multi-document writes must use a replica set or sharded cluster. The release gate uses a three-node replica set; a single-node replica set is only a faster local browser/smoke topology.

Doctor findings

Doctor reports MongoDB boundaries without running destructive probes:

ADMINIX_MONGODB_CAPABILITY_UNSUPPORTED: a configured module path uses an unsupported SQL-specific capability;
ADMINIX_MONGODB_DATASOURCE_AMBIGUOUS: a bare string datasource is ambiguous on a MongoDB default;
ADMINIX_MONGODB_INTEGRATION_MISSING: the configured MongoDB connection cannot resolve the official integration or extension;
ADMINIX_MONGODB_STANDARD_STORAGE_SQL_REQUIRED: standard Adminix storage is configured against a MongoDB default.

For an explicit MongoDB model, Doctor skips relational table, column, index, summary-field, and group-field findings that do not describe schema-flexible storage.

Verify, upgrade, and roll back

Package contributors run the optional dependency matrix and real three-node integration gate with:

composer test:mongodb
npm run e2e:mongodb

The browser fixture uses a protected SQL-backed guard and exercises MongoDB list, full-page resource, modal, validation, soft-delete, custom reorder, ObjectId error, notification, keyboard, dark-mode, and mobile flows.

When upgrading mongodb/laravel-mongodb, ext-mongodb, MongoDB Server, Laravel, or PHP, rerun the dependency matrix, multi-node integration suite, browser E2E, and the complete SQL database matrix before changing the tested-version table.

To roll back Level 1 usage:

remove MongoDB-backed page modules or point them to a supported SQL Eloquent model;
deploy and verify the SQL-backed panel path;
remove the optional integration only after the application no longer loads MongoDB models;
keep Adminix migrations and standard storage on SQL throughout the rollback.

composer remove mongodb/laravel-mongodb

Rolling back the optional model path does not require an Adminix migration because Level 1 never moves package-owned storage away from SQL.

Last modified: 26 July 2026