Download the PHP package district5/mondoc without Composer

District5 - Mondoc

Composer...

Use composer to add this library as a dependency onto your project.

Usage...

Setting up connections...

The MondoConnections object is a singleton. Set this up somewhere in your code to initialise the connection, and within your services you can define protected static function getConnectionId(): string to return the correct identifier for the relevant model.

The data model

Additionally, in the model you can leverage the $mondocFieldAliases property to map fields from the database to the model to keep keys short in storage. This is optional, but can be useful in some cases. An example of this is shown below:

Optional traits...

• MondocVersionedModelTrait - Version your data easily.
  • You can easily version data within a model by using the \District5\Mondoc\Db\Model\Traits\MondocVersionedModelTrait trait. This trait introduces a _v variable in the model, which you can choose to increment when you choose.
  • You can detect if a model has a version by calling isVersionableModel() on the model.
• MondocRevisionNumberTrait - Adds an _rn property to a model to utilise as a revision number. This value is automatically set to 1 upon initial save of a model, and is incremented each time the model is updated. You can override this behaviour by manually assigning a value to the _rn property by calling setRevisionNumber method on your inheriting model. This is different from the versioned model trait, as the revision number is incremented each time the model is updated, regardless of the changes made.
  • You can detect if a model has a revision number by calling isRevisionNumberModel() on the model.
• MondocCreatedDateTrait - Adds a cd property to a model to utilise as a created date.
  • This value is automatically assigned to the current UTC date upon initial save of a model, or if an existing model is updated and the cd property has not been set. You can override this behaviour by assigning a value to the cd property.
• MondocModifiedDateTrait - Adds a md property to a model to utilise as an updated date.
  • This value is automatically assigned the current UTC date, but you can override this behaviour by assigning a value to the md property prior to saving.
• MondocCloneableTrait - Adds a clone method to the model, which will return a new instance of the model with the same properties as the original. Optionally, when calling ->clone you can pass a boolean to indicate if you want to persist the new model to the database. The optional second parameter is the object or class to clone to. For example, you can make a clone of MyModel and convert it to OtherModel by calling $myModel->clone( < save:bool > , OtherModel::class).
• MondocRetentionTrait - Adding this to your model exposes the setMondocRetentionChangeMeta and setMondocRetentionExpiry methods, which allows you to set the retention data for the model. This is useful for setting things such as the retention period and the retention policy.

Traits examples

The service layer

The logic for querying the database is always performed in the service layer. There's only a single required method, getCollectionName, which should return the name of the collection in the database.

Optionally, you can define a getConnectionId method to return the connection ID to use from the MondocConfig connection manager. This is useful if you're using multiple connections, for example, a connection for authentication and a connection for the main application.

All Mondoc native queries automatically convert DateTime objects to UTCDateTime objects when querying a collection.

Please note: in versions prior to 6.3.0 the PaginationTrait required you to pass the filter into each method call. This is no longer required, as the filter is carried through by the MondocPaginationHelper object now.

Nesting objects

You can nest objects in each other. The main model must extend \District5\Mondoc\Db\Model\MondocAbstractModel and have the sub models defined in the $mondocNested array.

Sub models must extend \District5\Mondoc\Db\Model\MondocAbstractSubModel.

When implementing $mondocNested, you declare a single nested model, or an array of nested models. For example:

Please note: in versions prior to 5.1.0 any nested property was required to have BSONDocument or BSONArray as part of the property definition. This is no longer required as the library will automatically inflate the class(es) correctly

Nested objects, regardless of depths, can also take advantage of the $mondocFieldAliases property to map fields from the database to the model. This keeps the keys short in storage, while allowing for longer, more descriptive keys in the model. For the above example, you could have the following:

Finding documents..

Model to array...

You can export a model to an array by calling asArray() on the model. This will return an array of the model's properties.

The properties returned by the asArray() method are the properties and types that have been set on the model, which means they're likely not able to be directly encoded to JSON. To get around this, you can call asJsonEncodableArray() on the model, which will return an array that can be encoded to JSON. Optionally, you can provide a list of fields to omit from the returned array.

Useful information...

To use a pre-determined ObjectId as the document _id, you can call setPresetObjectId against the model. This will force the model to absorb this ObjectId and not generate a new one upon insertion. For example:

Additionally, there's a method called assignDefaultVars which can be used to assign default values to the model's properties. This is useful for setting default values for properties. The call to assignDefaultVars occurs AFTER inflation has occurred, so it's important to note that the properties may already have values assigned. For example:

Converting between types

MongoDB uses BSON types for data. This library holds a MondocTypes helper, which can assist in the conversion of these native types.

Retention of data

When using the MondocRetentionTrait trait, you can set the retention data for a model by calling setMondocRetentionChangeMeta. There is no preset retention data, so you must set this yourself. This is useful for setting things such as the user's name who initiated the change, or similar for compliance and the retention policy. Additionally, the method setMondocRetentionExpiry method is exposed, and can be used to set the expiry date for the retention data. The library does not automatically delete the data when the retention period has expired, but you can use the MondocRetentionService to query for data that has expired, using either getPaginatorForExpiredRetentionForClassName or getPaginatorForExpiredRetentionForObject, and then subsequently the getRetentionPage method.

Exposed methods in the MondocRetentionService:

• create - Create a new retention model. This is called automatically by Mondoc when a model contains the MondocRetentionTrait trait.
• createStub - Create a new retention model, but don't save it. This is useful for creating a retention model that you want to save at a later date. This is used when inserting multiple models.
• getLatestRetentionModelForModel - Get the latest retention model for a given (previously saved) model.
• countRetentionModelsForClassName - Count the number of retention models for a given class name.
• countRetentionModelsForModel - Count the number of retention models for a given (previously saved) model.
• getRetentionHistoryPaginationHelperForClassName - Get a pagination helper for the retention history for a given class name.
• getRetentionHistoryPaginationHelperForModel - Get a pagination helper for the retention history for a given (previously saved) model.
• addIndexes - Add the indexes to the retention collection. This is NOT called automatically by Mondoc, and must be called manually by your application.
• hasIndexes - Check if the indexes have been added to the retention collection. This is a helper method to allow you to check if the indexes have been added, and if not, you can call addIndexes to add them.
• getPaginatorForExpiredRetentionForClassName - Get a pagination helper for the retention history for a given class name, where the retention has expired.
• getPaginatorForExpiredRetentionForObject - Get a pagination helper for the retention history for a given (previously saved) model, where the retention has expired.
• getRetentionPage - Get a page of retention models from the pagination helper. This is the method you use after retrieving a pagination helper via getPaginatorForExpiredRetentionForClassName or getPaginatorForExpiredRetentionForObject.

Within a MondoRetentionModel, the following methods are available:

• toOriginalModel - Get the original model that the retention data is associated with. This will return the model inflated with the data that was saved at the time of the retention data being saved.
• getSourceModelData - Get the data that was saved at the time of the retention data being saved. This will return the data as it was saved at the time of the retention data being saved, in array format.
• getSourceObjectId - Get the ObjectId of the original model that the retention data is associated with.
• getSourceObjectIdString - Get the ObjectId of the original model that the retention data is associated with, as a string.
• getSourceClassName - Get the class name of the original model that the retention data is associated with.
• getRetentionData - Get the retention data that was saved at the time of the retention data being saved, as set by the original call to setMondocRetentionChangeMeta, contained in the MondocRetentionTrait.
• getRetentionExpiry - Get the retention expiry date that was saved at the time of the retention data being saved, as set by the original call to setMondocRetentionExpiry, contained in the MondocRetentionTrait.
• hasRetentionExpired - Check if this retention model has expired. This will return true if the retention data has expired, and false if it has not.

A working example of using the retention trait is shown below:

Query building

Query building is handled by the MondocBuilder library https://github.com/district-5/php-mondoc-builder.

The query builder does not take into account for the model's properties, but rather the database's properties. This means that it will not listen or adhere to any field mappings that have been set on the model.

For example, this map would require the query builder to use the n key, not name:

Testing

You can run PHPUnit against the library by running composer install and then running phpunit. Before doing so, you'll need to assign the MONGO_CONNECTION_STRING environment variable to a valid MongoDB connection string.