Compila un Servicio Backend

Crea un proyecto en Laravel.

En primer lugar, crea un directorio para el proyecto Laravel. A continuación, ejecuta el siguiente comando para crear un nuevo proyecto de Laravel llamado laraproject:

composer create-project laravel/laravel laraproject

Instalar MongoDB Laravel.

Para comprobar que Laravel MongoDB se ejecuta en el servidor web, añade una página web a tu sitio web de Laravel. En tu proyecto, navega a /routes/web.php y añade la siguiente ruta:

Route::get('/info', function () {
    phpinfo();
});

Luego, ejecuta el siguiente comando en tu shell para iniciar tu aplicación:

php artisan serve

Una vez que la aplicación comience a ejecutarse, diríjase a http://:127.0.0.1 8000/info para ver la página PHPinfo. Desplácese hacia abajo o busque la entrada mongodb para verificar que la extensión PHP de MongoDB esté instalada.

Ejecuta el siguiente comando en tu shell para instalar Laravel MongoDB:

composer require mongodb/laravel-mongodb:^5.7

Configure tu conexión a MongoDB.

Abre el archivo config/database.php de tu proyecto y actualiza el arreglo connections como se muestra en el siguiente código:

'connections' => [
        'mongodb' => [
            'driver' => 'mongodb',
            'dsn' => '<connection string>',
            'database' => 'db',
        ],

Asegúrate de reemplazar el marcador de posición de la cadena de conexión en el código anterior con tu propia cadena de conexión antes de ejecutar la aplicación. Para aprender cómo ubicar tu cadena de conexión, consulta Crear una cadena de conexión en la guía de inicio rápido.

También puede configurar la conexión de base de datos predeterminada. En la parte superior del archivo config/database.php, cambie "default" por lo siguiente:

'default' => 'mongodb',

La aplicación Laravel ahora puede conectarse a la base de datos db en su clúster MongoDB.

Crea un endpoint para hacer ping a tu implementación.

Ejecute el siguiente comando de shell para configurar el enrutamiento de API:

php artisan install:api

En el archivo routes/api.php recién creado, agregue la siguiente ruta:

// Add the DB use statement to the top of the file.
use Illuminate\Support\Facades\DB;
Route::get('/ping', function (Request $request) {
    $connection = DB::connection('mongodb');
    $msg = 'MongoDB is accessible!';
    try {
        $connection->command(['ping' => 1]);
    } catch (\Exception $e) {
        $msg = 'MongoDB is not accessible. Error: ' . $e->getMessage();
    }
    return ['msg' => $msg];
});

Recarga la aplicación, luego verifica que http://127.0.0.1:8000/api/ping muestra el mensaje de ping exitoso.

Crear modelos Eloquent.

Laravel está integrado con Eloquent, un ORM que abstrae el backend de la base de datos para que puedas conectarte a diferentes bases de datos usando una interfaz común.

Eloquent proporciona una clase Model que actúa como interfaz entre su código y una colección específica. Las instancias de las clases Model representan filas de tablas en bases de datos relacionales. En MongoDB, son documentos de la colección.

Cree un modelo Eloquent llamado CustomerMongoDB ejecutando el siguiente comando desde la raíz del proyecto:

php artisan make:model CustomerMongoDB

Laravel crea la clase CustomerMongoDB en el directorio /models. Por defecto, los modelos utilizan la conexión de base de datos default, pero se puede especificar qué conexión utilizar añadiendo el nodo $connection a la clase. También puedes especificar el nombre de la colección añadiendo el nodo $collection.

Asegúrese de incluir la instrucción use para el modelo MongoDB Eloquent. Esto es necesario para establecer _id como la llave primaria.

Reemplaza el contenido del archivo CustomerMongoDB.php con el siguiente código:

use MongoDB\Laravel\Eloquent\Model;
class CustomerMongoDB extends Model
{
    // the selected database as defined in /config/database.php
    protected $connection = 'mongodb';
    // equivalent to $table for MySQL
    protected $collection = 'laracoll';
    // defines the schema for top-level properties (optional).
    protected $fillable = ['guid', 'first_name', 'family_name', 'email', 'address'];
}

Realiza operaciones CRUD.

Después de crear tus modelos, puedes realizar operaciones de datos.

Crea la siguiente ruta en tu archivo api.php:

Route::get('/create_eloquent_mongo/', function (Request $request) {
    $success = CustomerMongoDB::create([
        'guid'=> 'cust_1111',
        'first_name'=> 'John',
        'family_name' => 'Doe',
        'email' => 'j.doe@gmail.com',
        'address' => '123 my street, my city, zip, state, country'
    ]);
});

Después de insertar el documento, puede recuperarlo utilizando el método where() como se muestra en el siguiente código:

Route::get('/find_eloquent/', function (Request $request) {
    $customer = CustomerMongoDB::where('guid', 'cust_1111')->get();
});

Eloquent te permite encontrar datos mediante queries complejas con múltiples condiciones coincidentes.

También puede actualizar y borrar los datos que se muestran en las siguientes rutas:

Route::get('/update_eloquent/', function (Request $request) {
    $result = CustomerMongoDB::where('guid', 'cust_1111')->update( ['first_name' => 'Jimmy'] );
});
Route::get('/delete_eloquent/', function (Request $request) {
    $result = CustomerMongoDB::where('guid', 'cust_1111')->delete();
});

En este punto, su servicio back-end conectado a MongoDB está en ejecución, pero MongoDB proporciona más funcionalidad para respaldar sus operaciones.

Realiza operaciones en datos anidados.

Laravel MongoDB ofrece operaciones específicas de MongoDB para datos anidados. Sin embargo, agregar datos anidados también es intuitivo sin usar los métodos embedsMany() y embedsOne().

Como se mostró en el paso anterior, puede definir atributos de esquema de nivel superior. Sin embargo, definir estos atributos es más complicado si sus documentos incluyen matrices y documentos incrustados.

Puedes crear las estructuras de datos del modelo en PHP. En el siguiente ejemplo, el campo address es de tipo de objeto Realm. El campo email es un arreglo de cadenas de texto:

Route::get('/create_nested/', function (Request $request) {
    $message = "executed";
    $success = null;
    $address = new stdClass;
    $address->street = '123 my street name';
    $address->city = 'my city';
    $address->zip= '12345';
    $emails = ['j.doe@gmail.com', 'j.doe@work.com'];
    try {
        $customer = new CustomerMongoDB();
        $customer->guid = 'cust_2222';
        $customer->first_name = 'John';
        $customer->family_name= 'Doe';
        $customer->email= $emails;
        $customer->address= $address;
        $success = $customer->save(); // save() returns 1 or 0
    }
    catch (\Exception $e) {
        $message = $e->getMessage();
    }
    return ['msg' => $message, 'data' => $success];
});

Cuando accede al punto final /api/create_nested/, se crea un documento en MongoDB:

{
  "_id": {...},
  "guid": "cust_2222",
  "first_name": "John",
  "family_name": "Doe",
  "email": [
    "j.doe@gmail.com",
    "j.doe@work.com"
  ],
  "address": {
    "street": "123 my street name",
    "city": "my city",
    "zip": "12345"
  },
  "updated_at": {
    "$date": "2025-05-27T17:38:28.793Z"
  },
  "created_at": {
    "$date": "2025-05-27T17:38:28.793Z"
  }
}

Usa la API de query de MongoDB.

MongoDB ofrece la API de query para queries optimizadas.

Puedes empezar a crear una consulta usando un objeto collection. Eloquent expone todas las capacidades de la base de datos subyacente mediante consultas sin procesar, que Laravel envía a la base de datos sin ningún procesamiento del Generador de Consultas de Eloquent.

Puede realizar una consulta MongoDB nativa sin procesar desde el modelo como se muestra en el siguiente código:

$mongodbquery = ['guid' => 'cust_1111'];
// returns a "Illuminate\Database\Eloquent\Collection" Object
$results = CustomerMongoDB::whereRaw( $mongodbquery )->get();

También puede acceder al objeto de colección nativo de MongoDB y realizar una query que devuelva objetos como documentos nativos de MongoDB o cursores:

$mongodbquery = ['guid' => 'cust_1111', ];
$mongodb_native_collection = DB::connection('mongodb')->getCollection('laracoll');
$document = $mongodb_native_collection->findOne( $mongodbquery );
$cursor = $mongodb_native_collection->find( $mongodbquery );

El siguiente código demuestra múltiples maneras de realizar queries:

Route::get('/find_native/', function (Request $request) {
    // a simple MongoDB query that looks for a customer based on the guid
    $mongodbquery = ['guid' => 'cust_2222'];
    // Option #1
    // =========
    // use Eloquent's whereRaw() function
    // returns a "Illuminate\Database\Eloquent\Collection" Object
    $results = CustomerMongoDB::whereRaw( $mongodbquery )->get();
    // Option #2 & #3
    // ==============
    // use the native MongoDB driver Collection object and the Query API
    $mdb_collection = DB::connection('mongodb')->getCollection('laracoll');
    // find the first document that matches the query
    $mdb_bsondoc = $mdb_collection->findOne( $mongodbquery ); // returns a "MongoDB\Model\BSONDocument" Object
    // to convert the MongoDB Document to a Laravel Model, use the Model's newFromBuilder() method
    $cust = new CustomerMongoDB();
    $one_doc = $cust->newFromBuilder((array) $mdb_bsondoc);
    // find all documents because you pass an empty query
    $mdb_cursor = $mdb_collection->find(); // returns a "MongoDB\Driver\Cursor" object
    $cust_array = array();
    foreach ($mdb_cursor->toArray() as $bson) {
        $cust_array[] = $cust->newFromBuilder( $bson );
    }
    return ['msg' => 'executed', 'whereraw' => $results, 'document' => $one_doc, 'cursor_array' => $cust_array];
});

El siguiente código muestra cómo usar el método updateOne() para actualizar documentos:

Route::get('/update_native/', function (Request $request) {
    $mdb_collection = DB::connection('mongodb')->getCollection('laracoll');
    $match = ['guid' => 'cust_2222'];
    $update = ['$set' => ['first_name' => 'Henry', 'address.street' => '777 new street name'] ];
    $result = $mdb_collection->updateOne($match, $update );
    return ['msg' => 'executed', 'matched_docs' => $result->getMatchedCount(), 'modified_docs' => $result->getModifiedCount()];
});

El siguiente código demuestra cómo utilizar el método deleteOne() para borrar documentos:

Route::get('/delete_native/', function (Request $request) {
    $mdb_collection = DB::connection('mongodb')->getCollection('laracoll');
    $match = ['guid' => 'cust_2222'];
    $result = $mdb_collection->deleteOne($match );
    return ['msg' => 'executed', 'deleted_docs' =>
    $result->getDeletedCount() ];
});

Para obtener más información sobre cómo realizar operaciones CRUD, consulta las guías de Operaciones de guardar y Operaciones de lectura.

Utiliza el marco de agregación.

Una canalización de agregación es una tarea del marco de agregación de MongoDB. Puede usar este marco para realizar diversas tareas, como paneles de control en tiempo real y análisis de big data.

Una canalización de agregación consta de varias etapas, donde la salida de cada etapa es la entrada de la siguiente. Este paso utiliza el sample_mflix de los conjuntos de datos de ejemplo de Atlas. Laravel permite acceder a varias bases de datos MongoDB en la misma aplicación, así que añada la sample_mflix conexión de base de datos database.php a:

'mongodb_mflix' => [
            'driver' => 'mongodb',
            'dsn' => env('DB_URI'),
            'database' => 'sample_mflix',
        ],

A continuación, cree el endpoint de API /aggregate/ y defina un pipeline de agregación para recuperar datos de la colección movies, calcular la puntuación promedio de películas por género y devolver una lista.

Route::get('/aggregate/', function (Request $request) {
    $mdb_collection = DB::connection('mongodb_mflix')->getCollection('movies');
    $stage0 = ['$unwind' => ['path' => '$genres']];
    $stage1 = ['$group' => ['_id' => '$genres', 'averageGenreRating' => ['$avg' => '$imdb.rating']]];
    $stage2 = ['$sort' => ['averageGenreRating' => -1]];
    $aggregation = [$stage0, $stage1, $stage2];
    $mdb_cursor = $mdb_collection->aggregate( $aggregation );
    return ['msg' => 'executed', 'data' => $mdb_cursor->toArray() ];
});

Laravel MongoDB proporciona el Generador de agregación para construir pipelines de agregación con tipado seguro directamente desde tus modelos. Recomendamos usar el constructor de agregaciones para realizar agregaciones.

Utilice índices para optimizar el rendimiento de las consultas.

Puedes crear índices para respaldar tus consultas y mejorar el rendimiento. Para obtener más información sobre cómo crear índices mediante programación, consulte la sección Gestionar índices de la guía del Generador de esquemas.