Compila un Servicio Backend

Crear un proyecto Laravel.

Primero, crea un directorio para el proyecto Laravel. Luego, ejecuta el siguiente comando para crear un nuevo proyecto Laravel llamado laraproject:

composer create-project laravel/laravel laraproject

Instalar Laravel MongoDB.

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.

Ejecute el siguiente comando en su shell para instalar Laravel MongoDB:

composer require mongodb/laravel-mongodb:^5.6

Configure su conexión MongoDB.

Abra el archivo config/database.php de su proyecto y actualice la matriz 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.

Cree un punto final para hacer ping a su 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 back end de la base de datos para que puedas conectarte a diferentes bases de datos mediante 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 usan la conexión a la base de datos default, pero puedes especificar qué conexión usar añadiendo el miembro $connection a la clase. También puedes especificar el nombre de la colección añadiendo el miembro $collection.

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

Reemplace 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'];
}

Realizar operaciones CRUD.

Después de crear sus modelos, puede realizar operaciones con 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 eliminar 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.

Realizar operaciones sobre datos anidados.

Laravel MongoDB ofrece operaciones específicas de MongoDB para datos anidados. Sin embargo, añadir 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 un tipo de objeto. El campo email es una matriz de cadenas:

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"
  }
}

Utilice la API de consulta de MongoDB.

MongoDB proporciona la API de consulta para consultas 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 consulta que devuelva objetos como documentos o cursores nativos de MongoDB:

$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 formas de realizar consultas:

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 demuestra cómo utilizar 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 eliminar 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, consulte las guías Operaciones de escritura y Operaciones de lectura.

Utilice 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 punto final de API /aggregate/ y defina una canalización de agregación para recuperar datos de la colección movies, calcular la calificación promedio de películas para cada 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 Agregaciones para crear pipelines de agregación con seguridad de tipos directamente desde tus modelos. Recomendamos usar el Generador de Agregaciones para realizar agregaciones.

Utilice índices para optimizar el rendimiento de las consultas.

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