Overview
La librería PHP de MongoDB es una abstracción de alto nivel para la extensión PHP de MongoDB, que se puede utilizar para realizar la conexión a MongoDB y para la interacción con los datos almacenados en la implementación. Esta guía muestra cómo crear una aplicación para usar en la librería PHP de MongoDB para realizar la conexión a un clúster de MongoDB alojado en MongoDB Atlas y consultar datos en el clúster.
Tip
MongoDB Atlas es un servicio de base de datos gestionada en la nube que aloja las implementaciones de MongoDB. Se puede crear una implementación propia gratuita de MongoDB Atlas (sin necesidad de tarjeta de crédito) siguiendo los pasos de esta guía.
Siga esta guía para conectar una aplicación PHP de ejemplo a una implementación de MongoDB Atlas. Si prefiere conectarse a MongoDB con un controlador o lenguaje de programación diferente, consulte nuestra Lista de conductores oficiales.
Descargue e instale
Instalar la extensión PHP de MongoDB.
Ejecute el siguiente comando para instalar el mongodb Extensión PHP:
pie install mongodb/mongodb-extension
Tip
Especifique la versión de la extensión PHP
Para instalar una versión específica de la extensión de PHP, incluya el número de versión como se muestra en el siguiente comando:
pie install mongodb/mongodb-extension:^2.2.0
Para instalar una versión de una extensión de PHP anterior a la v1.21, Debes utilizar el comando pecl.
Crea un directorio de proyecto.
Desde su directorio raíz, ejecute el siguiente comando en su shell para crear un directorio llamado php-quickstart para este proyecto:
mkdir php-quickstart
Seleccione la pestaña correspondiente a su sistema operativo y ejecute los siguientes comandos para crear un archivo de aplicación quickstart.php en el directorio php-quickstart:
cd php-quickstart touch quickstart.php
cd php-quickstart type nul > quickstart.php
Instalar la biblioteca PHP MongoDB.
Para instalar la biblioteca PHP de MongoDB, ejecute el siguiente comando en su directorio php-quickstart:
composer require mongodb/mongodb
Después de instalar la librería, se debe incluir el archivo de Composer autoload.php al agregar el siguiente código en la parte superior del archivo quickstart.php:
require_once __DIR__ . '/vendor/autoload.php';
Una vez que hayas completado estos pasos, tendrás un nuevo directorio de proyecto, un nuevo archivo de aplicación y las dependencias de la biblioteca instaladas.
Cree una implementación de MongoDB
Se puede crear una implementación de nivel gratuito de MongoDB en MongoDB Atlas para almacenar y gestionar los datos. MongoDB Atlas aloja y gestiona la base de datos MongoDB en la nube.
Cree una implementación gratuita de MongoDB en Atlas.
Complete la guía de introducción a MongoDB para configurar una nueva cuenta de Atlas y cargar datos de muestra en una nueva implementación gratuita de MongoDB. Siga las instrucciones. Cloud Deployment Pestañas para crear su implementación de MongoDB Atlas en la nube.
Después de completar estos pasos, habrá una nueva implementación de nivel gratuito de MongoDB en Atlas, credenciales de usuario de base de datos y datos de muestra cargados en la base de datos.
Crear una cadena de conexión
Puede conectarse a su implementación de MongoDB proporcionando un URI de conexión, también llamado cadena de conexión, que instruye al controlador sobre cómo conectarse a una implementación de MongoDB y cómo comportarse mientras está conectado.
La cadena de conexión incluye el nombre de host o la dirección IP y el puerto de la implementación, el mecanismo de autenticación, las credenciales de usuario cuando sea aplicable, y las opciones de conexión.
Para conectarse a una instancia o implementación no alojada en Atlas, consulte Elija un objetivo de conexión.
Encuentra tu cadena de conexión de MongoDB Atlas.
Para recuperar la cadena de conexión de la implementación que creó en el paso anterior, inicie sesión en su cuenta de Atlas y navegue a la Clusters página, en la Database sección. Haga clic en el Connect botón para su nueva implementación.

Si aún no tienes un usuario de base de datos configurado, MongoDB te pedirá que crees y configures un nuevo usuario.
Haga clic en el botón Drivers en la sección Connect to your application y seleccione "PHP" en el menú de selección Driver y la versión que mejor coincida con la versión que instaló en el menú de selección Version.
Asegúrate de que la opción View full code sample esté desmarcada para ver solo la cadena de conexión.
Actualice los marcadores de posición de contraseña.
Pega esta cadena de conexión en un archivo en tu editor de texto preferido y reemplaza el marcador de posición <db_password> con la contraseña de tu usuario de base de datos. La cadena de conexión ya está completada con el nombre de usuario de tu usuario de base de datos.
Guarda este archivo en una ubicación segura para usarlo en el siguiente paso.
Tras completar estos pasos, hay una cadena de conexión que corresponde al clúster de Atlas.
Ejecuta una query de muestra
Después de recuperar la cadena de conexión para su implementación de MongoDB Atlas, se puede conectar a la implementación desde la aplicación PHP y realizar queries en los conjuntos de datos de muestra de Atlas.
Edite su archivo de aplicación PHP.
Copie y pegue el siguiente código en el archivo quickstart.php, que hace un query en la colección movies en la base de datos sample_mflix:
require __DIR__ . '/../vendor/autoload.php'; $uri = getenv('MONGODB_URI') ?: throw new RuntimeException( 'Set the MONGODB_URI environment variable to your Atlas URI', ); $client = new MongoDB\Client($uri); $collection = $client->sample_mflix->movies; $filter = ['title' => 'The Shawshank Redemption']; $result = $collection->findOne($filter); if ($result) { echo json_encode($result, JSON_PRETTY_PRINT); } else { echo 'Document not found'; }
Asigna la cadena de conexión.
Se debe asignar la variable de entorno MONGODB_URI a la cadena de conexión que se copió del paso Crear una cadena de conexión de esta guía. Puede asignar esta variable ejecutando un comando de shell o creando un archivo .env en la aplicación, como se muestra en las siguientes pestañas:
export MONGODB_URI=<connection string>
MONGODB_URI=<connection string>
Ejecute su aplicación PHP.
En el directorio de su proyecto, ejecute el siguiente comando de shell para iniciar la aplicación:
php quickstart.php
La salida de la línea de comandos contiene detalles sobre el documento de película recuperado:
{ "_id": { "$oid": "..." }, ... "rated": "R", "metacritic": 80, "title": "The Shawshank Redemption", ... }
Si encuentra un error o no ve salida, asegúrese de haber asignado la cadena de conexión adecuada a la variable de entorno MONGODB_URI y de haber cargado los datos de muestra.
Después de completar estos pasos, tendrá una aplicación PHP que se conecta a su implementación de MongoDB, ejecuta una query sobre los datos de muestra y devuelve un documento coincidente.
Próximos pasos
¡Felicidades por completar el tutorial de inicio rápido!
Nota
Si hay problemas en este paso, se deben enviar comentarios utilizando la pestaña Rate this page situada a la derecha o en la parte inferior derecha de esta página.
Puede encontrar soporte para preguntas generales mediante la etiqueta Stack Overflow de MongoDB o la comunidad de Reddit de MongoDB.
En este tutorial, creaste una aplicación PHP que se conecta a una implementación de MongoDB alojada en MongoDB Atlas y recupera un documento que coincide con un query.
Aprende más sobre la biblioteca PHP de MongoDB a partir de los siguientes recursos:
Se debe aprender cómo configurar la conexión a MongoDB en la sección Conexión a MongoDB.
Aprende a realizar operaciones de lectura y escritura en la sección Operaciones CRUD.
Solución de problemas
Esta sección aborda los problemas que podrías tener al instalar la biblioteca PHP y sus dependencias.
Encabezados de PHP no encontrados
Es posible que vea un error de archivo de encabezado que se asemeje al siguiente código al instalar la biblioteca PHP:
/private/tmp/pear/install/mongodb/php_phongo.c:24:10: fatal error: 'php.h' file not found #include <php.h> ^~~~~~~
Este error indica que el sistema de compilación de PHP no puede encontrar los encabezados necesarios. Todas las extensiones de PHP requieren encabezados para compilar. Esos encabezados deben corresponder al tiempo de ejecución de PHP para el cual se utilizará la extensión. El comando phpize, que es invocado por pecl y pie, suele garantizar que la extensión se compile con los encabezados correctos.
Si instalas un entorno de ejecución de PHP, los encabezados correspondientes no siempre están disponibles automáticamente. En muchas distribuciones de Linux, los encabezados a menudo se publican en un paquete php-dev o php-devel por separado. En macOS, el entorno de ejecución de PHP por defecto no incluye los encabezados. Los usuarios normalmente deben instalar PHP y sus encabezados utilizando Homebrew.
Múltiples entornos de ejecución de PHP instalados
Si su sistema tiene varias versiones de PHP instaladas, cada versión tendrá sus propios comandos pecl, pie y phpize. Además, cada entorno de ejecución de PHP puede tener archivos php.ini separados para cada interfaz de programación de aplicaciones de servidor (SAPI), como FPM y CLI. Si ha instalado la extensión, pero no está disponible en tiempo de ejecución, asegúrese de utilizar el comando pecl o pie correcto y modifique el archivo php.ini adecuado.
Para ver qué archivo php.ini utiliza un entorno de ejecución de PHP, consulta la salida de phpinfo() para ese SAPI en particular. Además, puedes usar php_ini_loaded_file() y php_ini_scanned_files() para determinar qué archivos INI han sido cargados por PHP.
Para depurar problemas cuando la extensión no está cargada, puede usar el script detect-extension proporcionado en el directorio de herramientas. Puede ejecutar este script desde la CLI o incluirlo en un script disponible para su servidor web. La herramienta detecta posibles problemas e instrucciones de instalación para su sistema. Si ha instalado la biblioteca usando Composer, puede llamar al script desde el directorio del proveedor como se muestra en el siguiente código:
php vendor/mongodb/mongodb/tools/detect-extension.php
Si se desea comprobar la configuración de una SAPI de servidor web, se debe incluir el archivo en un script disponible para el servidor web y abrirlo en el navegador. Es necesario envolver el script en las etiquetas <pre> para dar formato correctamente a su salida, como se muestra en el siguiente código:
<pre> require(...); </pre>
Cargando una DLL incompatible en Windows
Los binarios de Windows están disponibles para varias combinaciones de una versión de PHP, configuración de seguridad de subprocesos (TS o NTS) y tipo de arquitectura (x86 o x64). La falta de selección del binario correcto provoca un error al intentar cargar la DLL de la extensión en tiempo de ejecución, como se muestra en el siguiente ejemplo de salida:
PHP Warning: PHP Startup: Unable to load dynamic library 'mongodb'
Asegúrese de haber descargado una DLL que corresponda a las siguientes propiedades de ejecución de PHP:
Versión de PHP (
PHP_VERSION)Seguridad de hilos (
PHP_ZTS)Arquitectura (
PHP_INT_SIZE)
Además de las constantes precedentes, estas propiedades también se pueden deducir de phpinfo(). Si el sistema tiene múltiples entornos de ejecución de PHP instalados, se debe consultar la salida phpinfo() para el entorno correcto.
También puede utilizar el script detect-extension descrito en la sección anterior para determinar la DLL correcta para su entorno PHP.
