Menu

Maslosoft Mangan Logo Maslosoft Mangan Documentation
MongoDB Object Persister

Edit

Active Document

Active document is a model approach that allows to invoke model operations directly on it's instance.

Mangan has pre-composed class, which have all required active document methods: Document along with it's a bit lighter counterpart for embedded documents: EmbeddedDocument

The methods available in Document

Toggle getters and setters

Method Documentation
getCollection()

Get working mongo collection instance.

Should not be called manually in most cases.

getCollectionName()

This method must return collection name for use with this model. By default it uses full class name, with slashes replaced by dots.

If CollectionName annotation is defined, it will collection name defined by this annotation.

getDbCriteria()

Returns the Criteria associated with this model.

setDbCriteria()

Set new criteria, previous criteria will be destroyed.

getDefaultLanguage()

Get default language used for I18N operations.

If not previously set, will fall back to en.

setDefaultLanguage()

Set default language used for I18N operations. This language will be used if the setLang method was not called.

The value should be language code, for example en

getErrors()

Get validation errors. To obtain results, first validate() method must be called.

setErrors()

Set errors. Usually should not be called manually.

getLang()

Get current working language code

setLang()

Set language code. This changes current model language. After setting language model attributes will store values in different locale.

Language code must be previously set by setLanguages. When trying to set undefined language code, method will do nothing. When setting already choosen language code, method will also ignore this call. Example method calls:

// Set available languages
$model->setLanguages(['en', 'pl']);

// Will ignore as en is by default
$model->setLang('en');

// Will set pl as language
$model->setLang('pl');

// Will ignore as ru is not available
$model->setLang('ru')

For initial call, when there are no data set yet, $triggetEvents can be set to false to improve performance.

getLanguages()

Get available languages

setLanguages()

Set available languages. This method accepts one parameter, array contaning language codes prefably in short ISO form.

Example valid array and method calls:

$languages = ['en', 'pl', 'ru'];
$model->setLanguages($languages);
$model2->setLanguages(['en']);

For initial call, when there are no data set yet, $triggetEvents can be set to false to improve performance.

getOwner()

Get document owner.

This might return null if there is no owner.

setOwner()

Set class owner

getRawI18N()

Get i18n values with all languages. This returns all language values of all class fields. Class field names are keys for arrays of language values, with language codes as a keys.

Example returned variable:

[
        'name' => [
            'en' => 'January',
            'pl' => 'Styczeń'
        ],
        'description' => [
            'en' => 'First mothn of a year'
            'pl' => 'Pierwszy miesiąc roku'
        ]
]
setRawI18N()

Set i18n values in all languages. This method must keep $values for further use, by method getRawI18N.

getRoot()

Get document root. This will traverse through objects hierarchy, untill owner-less document is found.

This might return same object instance if there is no owner.

The return value is guaranteed to be document instance.

getScenario()

Get current scenario

setScenario()

Set current scenario

__construct()

Constructor

addAspect()

Add aspect

count()

Counts all documents satisfying the specified condition.

countByAttributes()

Counts all documents found by attribute values.

Example:

$attributes = [
        'name' => 'John',
        'title' => 'dr'
];
delete()

Deletes the databse document corresponding to this Document.

deleteAll()

Deletes documents with the specified criteria.

Optional $criteria can be used to filter out which documents should be deleted.

See find() for detailed explanation about $criteria.

deleteAllByPk()

Deletes documents with the specified primary keys.

Additional $criteria can be used to filter out which documents should be deleted.

See find() for detailed explanation about $criteria.

deleteByPk()

Deletes document with the specified primary key.

Additional $criteria can be used to filter out which document should be deleted.

See find() for detailed explanation about $criteria.

deleteOne()

Deletes one document with the specified primary keys.

Optional $criteria can be used to filter out which document should be deleted.

Does not raise beforeDelete event

See find() for detailed explanation about $criteria

exists()

Checks whether there is document satisfying the specified condition.

find()

Finds a single Document with the specified condition.

findAll()

Finds all documents satisfying the specified condition.

findAllByAttributes()

Finds all documents with the specified attributes.

findAllByPk()

Finds all documents with the specified primary keys. In MongoDB world every document has '_id' unique field, so with this method that field is in use as PK by default. See {@link find()} for detailed explanation about $condition.

findAndModify()

Find and modify single document atomically.

By default this function will return updated document, ie document with applied Modifier operations.

To return document before applied updates, set parameter $returnUpdated to false.

This function will raise events and signals before operation on current model.

The events and signals after operation will be performed on the returned model, depending on $returnUpdated parameter.

findByAttributes()

Finds document with the specified attributes. Attributes should be specified as key-value pairs. This allows easier syntax for simple queries.

Example:

$attributes = [
        'name' => 'John',
        'title' => 'dr'
];
findByPk()

Finds document with the specified primary key. Primary key by default is defined by _id field. But could be any other. For simple (one column) keys use it's value.

For composite use key-value with column names as keys and values for values.

Example for simple pk:

$pk = '51b616fcc0986e30026d0748'

Composite pk:

$pk = [
        'mainPk' => 1,
        'secondaryPk' => 2
];
hasAspect()

Check if has aspect

insert()

Inserts a document into the collection based on this active document attributes.

Note, validation is not performed in this method. You may call validate() to perform the validation.

After the record is inserted to DB successfully, its scenario will be set to be 'update'.

model()

Returns the empty model of the specified Document class. It is provided for invoking class-level methods, espacially userfull for finders.

Example usage:

$user = User::model()->findByPk('5612470866a19540308b4568');
refresh()

Repopulates this active document with the latest data.

removeAspect()

Remove aspect

replace()

Replaces the current document.

NOTE: This will overwrite entire document.

Any filtered out properties will be removed as well.

The record is inserted as a documnent into the database collection, if exists it will be replaced.

Validation will be performed before saving the record. If the validation fails, the record will not be saved. You can call getErrors() to retrieve the validation errors.

If the validation fails, the record will not be saved to database.

save()

Saves the current document.

The document is inserted into collection if it is not already saved. The check whether to update or insert document is dony by primary key.

Validation will be performed before saving the record. If the validation fails, the record will not be saved. You can call getErrors() to retrieve the validation errors.

If the record is saved its scenario will be set to be 'update'. And if its primary key is of type of MongoId, it will be set after save.

If the validation fails, the record will not be saved to database.

update()

Updates the document represented by this active document. All loaded attributes will be saved to the database. Note, validation is not performed in this method. You may call validate() to perform the validation.

meaning all attributes that are loaded from DB will be saved.

updateAll()

Atomic, in-place update method.

updateOne()

Updates one document with the specified criteria and attributes

This is more raw update:

  • Does not raise any events or signals
  • Does not perform any validation

meaning all attributes that are loaded from DB will be saved.

upsert()

Updates or inserts the current document. This will try to update existing fields. Will keep already stored data if present in document.

If document does not exist, a new one will be inserted.

validate()

Validate model attributes according to current scenario (if applicable)

The getErrors() method can be used to obtains validation messages.

withCursor()

Whenever to use cursor