MongoDB Support
Overview
MongoDB is one of the most popular NoSQL document-oriented database, used for its high write load (useful for analytics or IoT) and high availability (easy to set replica sets with automatic failover). It can also shard the database easily for horizontal scalability and has a powerful query language for doing aggregation, text search or geospatial queries.
API Platform uses Doctrine MongoDB ODM 2 and in particular its aggregation builder to leverage all the possibilities of the database.
Doctrine MongoDB ODM 2 relies on the mongodb PHP extension and not the legacy mongo extension.
Enabling MongoDB support
If the mongodb PHP extension is not installed yet, install it beforehand.
If you are using the API Platform Distribution, modify the Dockerfile to add the extension:
// api/Dockerfile
...
pecl install \
apcu-${APCU_VERSION} \
+ mongodb \
; \
...
docker-php-ext-enable \
apcu \
opcache \
+ mongodb \
; \
...
Then rebuild the php
image:
docker-compose build php
Add a MongoDB image to the docker-compose file:
# docker-compose.yml
# ...
db-mongodb:
# In production, you may want to use a managed database service
image: mongo
environment:
- MONGO_INITDB_DATABASE=api
- MONGO_INITDB_ROOT_USERNAME=api-platform
# You should definitely change the password in production
- MONGO_INITDB_ROOT_PASSWORD=!ChangeMe!
volumes:
- db-data:/var/lib/mongodb/data:rw
# You may use a bind-mounted host directory instead, so that it is harder to accidentally remove the volume and lose all your data!
# - ./docker/db/data:/var/lib/mongodb/data:rw
ports:
- "27017:27017"
# ...
Once the extension is installed, to enable the MongoDB support, require the Doctrine MongoDB ODM bundle package using Composer:
docker-compose exec php composer req doctrine/mongodb-odm-bundle:^4.0.0@beta doctrine/mongodb-odm:^2.0.0@beta
Execute the contrib recipe to have it already configured.
Change the MongoDB environment variables to match your Docker image:
# api/.env
MONGODB_URL=mongodb://api-platform:!ChangeMe!@db-mongodb
MONGODB_DB=api
Change the configuration of API Platform to add the right mapping path:
# api/config/packages/api_platform.yaml
api_platform:
# ...
mapping:
paths: ['%kernel.project_dir%/src/Entity', '%kernel.project_dir%/src/Document']
# ...
Creating documents
Creating resources mapped to MongoDB documents is as simple as creating entities:
<?php
// api/src/Document/Product.php
namespace App\Document;
use ApiPlatform\Core\Annotation\ApiResource;
use Doctrine\Common\Collections\ArrayCollection;
use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
use Symfony\Component\Validator\Constraints as Assert;
/**
* @ApiResource
*
* @ODM\Document
*/
class Product
{
/**
* @ODM\Id(strategy="INCREMENT", type="integer")
*/
private $id;
/**
* @ODM\Field
* @Assert\NotBlank
*/
public $name;
/**
* @ODM\ReferenceMany(targetDocument=Offer::class, mappedBy="product", cascade={"persist"}, storeAs="id")
*/
public $offers;
public function __construct()
{
$this->offers = new ArrayCollection();
}
public function getId(): ?int
{
return $this->id;
}
public function addOffer(Offer $offer): void
{
$offer->product = $this;
$this->offers->add($offer);
}
public function removeOffer(Offer $offer): void
{
$offer->product = null;
$this->offers->removeElement($offer);
}
// ...
}
<?php
// api/src/Document/Offer.php
namespace App\Document;
use ApiPlatform\Core\Annotation\ApiResource;
use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;
use Symfony\Component\Validator\Constraints as Assert;
/**
* @ApiResource(iri="http://schema.org/Offer")
*
* @ODM\Document
*/
class Offer
{
/**
* @ODM\Id(strategy="INCREMENT", type="integer")
*/
private $id;
/**
* @ODM\Field
*/
public $description;
/**
* @ODM\Field(type="float")
* @Assert\NotBlank
* @Assert\Range(min=0, minMessage="The price must be superior to 0.")
* @Assert\Type(type="float")
*/
public $price;
/**
* @ODM\ReferenceOne(targetDocument=Product::class, inversedBy="offers", storeAs="id")
*/
public $product;
}
Some important information about the mapping:
- Identifier fields always need to be integer with an increment strategy. API Platform does not support the native ObjectId.
- When defining references, always use the id for storing them instead of the native DBRef. It allows API Platform to manage filtering on nested properties by using lookups.
Filtering
Doctrine MongoDB ODM filters are practically the same as Doctrine ORM filters.
See how to use them and how to create custom ones in the filters documentation.
Creating custom extensions
See how to create Doctrine MongoDB ODM custom extensions in the extensions documentation.
The Distribution: Create Powerful APIs with Ease
The API Component
- General Design Considerations
- The Serialization Process
- Overall Process
- Available Serializers
- The Serialization Context, Groups and Relations
- Using Serialization Groups
- Using Serialization Groups per Operation
- Changing the Serialization Context Dynamically
- Changing the Serialization Context on a Per-item Basis
- Name Conversion
- Decorating a Serializer and Adding Extra Data
- Entity Identifier Case
- Embedding the JSON-LD Context
- The Event System
- OpenAPI Specification Support (formerly Swagger)
- Pushing Related Resources Using HTTP/2
- Overriding Default Order
- Using External Vocabularies
- Extending JSON-LD context
- NelmioApiDocBundle Integration
- Configuration
The Schema Generator Component
- Configuration
- Customizing PHP Namespaces
- Forcing a Field Range
- Forcing a Field Cardinality
- Forcing a Relation Table Name
- Forcing (or Disabling) a Class Parent
- Forcing a Class to be Abstract
- Forcing a Nullable Property
- Forcing a Unique Property
- Making a Property Read Only
- Making a Property Write Only
- Forcing a Property to be in a Serialization Group
- Forcing an Embeddable Class to be Embedded
- Author PHPDoc
- Disabling Generators and Creating Custom Ones
- Skipping Accessor Method Generation
- Disabling the id Generator
- Generating UUIDs
- User submitted UUIDs
- Generating Custom IDs
- Disabling Usage of Doctrine Collection
- Changing the Field Visibility
- Generating @Assert\Type Annotations
- Forcing Doctrine Inheritance Mapping Annotation
- Interfaces and Doctrine Resolve Target Entity Listener
- Custom Schemas
- Checking GoodRelation Compatibility
- PHP File Header
- Full Configuration Reference