Persistence (DAO)
This is the part that deals with the management of operations related to data access support.
1. Summary of useful methods of data manipulation
We have the “\muuska\dao\DAO” interface which takes care of the persistence. By default, it offers a set of methods that we are used to using.
– Method
- add
- Description : Add an object. If the object has the attributes “creationDate” or “lastModifiedDate”, the values will be filled in automatically. If the object class is defined in auto-increment, the value of the object identifier will be automatically filled in on the object. This method throws an exception if the object is not valid.
- Parameter :
- model : the object to add.
- saveConfig (optional) : it is an object of the class \muuska\dao\util\SaveConfig allowing to specify the data saving options.
- Return type : Boolean
- update
- Description : Modifies an existing object. If the object has an “lastModifiedDate” attribute, it’s value will be filled in automatically. This method signifies an exception if the object is not valid.
- Parameter :
- model : The object to modify.
- saveConfig (optional) : it is an object of class\muuska\dao\util\SaveConfig allowing to specify options for saving data.
- Return type : Boolean
- add
- save
- Description : Registers an object. If the object identifier is entered, it will make a modification otherwise, it will make the addition. This method is only functional for classes with an auto-increment identifier. This method throws an exception if the object is not valid.
- Parameter :
- model : The object to register
- saveConfig (optional) : it is an object of the \muuska\dao\util\SaveConfig class allowing to specify the data saving options
- Return type : Boolean
- updateMultipleRows
- Description : Edit information for multiple rows from row data from template data. This method throws an exception, the model data is not valid.
- Parameter :
- model : The object from which the data will be retrieved
- saveConfig (optional) : it is an object of class \muuska\dao\util\SaveConfig allowing to specify options for saving data.
- Return type :Boolean
- updateMultipleRowsFromArray
- Description : Modifies the information of multiple rows from the row data from the data present in an associative array. This method throws an exception the data is not valid.
- Parameter :
- data : associative table representing the data to modify.
- saveConfig (optional) : it is an object of class\muuska\dao\util\SaveConfig allowing to specify options for saving data.
- Return type : Boolean
- changeValue
- Description : Modifies the value of a specific attribute. Throws an exception if the object’s class does not have the specified attribute.
- Parameter :
- model : The object on which we want to change the value.
- field : The name of the attribute.
- value : The new value.
- Return type : Boolean
- changeValueOnMultipleRows
- Description : Changes the value of a specific attribute on multiple lines. Throws an exception if the object’s class does not have the specified attribute.
- Parameter :
- field : The name of the attribute.
- value : The new value.
- saveConfig (optional) : it is an object of class \muuska\dao\util\SaveConfig allowing to specify options for saving data.
- activate
- Description : Activate an object. Throws an exception if the object’s class does not have the attribute. “Active“.
- Parameter :
- model : The object to activate.
- Return type : Boolean
- deactivate
- Description : Disables an object. Throws an exception if the object’s class does not have the “active” attribute.
- Parameter :
- model : The object to deactivate.
- Return type : Boolean
- setModelNewPosition
- Description : Automatically changes the position of an object. By giving it the value of the position of the last object + 1
Throws an exception if the object’s class does not have the “position” attribute. - Parameter :
- model : The object to modify.
- Description : Automatically changes the position of an object. By giving it the value of the position of the last object + 1
- delete
- Description : Removes an object.
- Parameter :
- model : The object to delete.
- deleteConfig (optional) : it is an object of the \muuska\dao\util\DeleteConfig class used to specify the data deletion options.
- Return type : Boolean
- deleteMultipleRows
- Description : Deletes multiple records.
- Parameter :
- deleteConfig (optional) : it is an object of the class \muuska\dao\util\DeleteConfig allowing to specify the options for the deletion of data.
- clearData
- Description : Clears all data then resets DAO.
- Return type : Boolean
- getById
- Description : Retrieves an object by its identifier. Returns “null” if the object does not exist.
- Parameter :
- id : Object identifier.
- selectionConfig (optional) : it is an object of the \muuska\dao\util\SelectionConfig class used to specify data selection options.
- returnEmptyModelIfNotFound (optional) : Allows to specify that you want an empty template to be returned if no object is found. If you set this parameter to “true”, you will need to call the “isLoaded” method on the object definition to check if the object has been found. Default value “false”
- Return type : Object
- getUniqueModel
- Description : Collect a single item. Returns “null” if the object does not exist.
- Parameter :
- selectionConfig (optional) : it is an object of class \muuska\dao\util\SelectionConfig to specify data selection options.
- returnEmptyModelIfNotFound (optional) : Allows to specify that we want an empty model returned if no object was found. If you set this parameter to “true”, you will need to call the “isLoaded” method on the object definition to check if the object has been found. Default value “false”.
- getModelValue
- Description : Retrieves the value of a specific field.
- Parameter :
- selectionConfig (optional) : it is an object of class \muuska\dao\util\SelectionConfig to specify data selection options.
- field : The name of the field
- getData
- Description : Get a list of objects.
- Parameter :
- selectionConfig (optional) : it is an object of class \muuska\dao\util\SelectionConfig to specify data selection options.
- Return type : Collection of objects
- getDataTotal
- Description : Retrieves the number of data.
- Parameter :
- selectionConfig (optional) : it is an object of class \muuska\dao\util\SelectionConfig to specify data selection options.
- loadAssociatedObject
- Description : Load an external object
- Parameter :
- model : the current object
- field : The field with which the external object is associated.
- selectionConfig (optional) : it is an object of the \muuska\dao\util\SelectionConfig class used to specify data selection options.
- returnEmptyModelIfNotFound (optional)
- Return type : Object
- loadMultipleAssociatedObjects
- Description : Load the objects of a multiple association
- Parameter :
- model : the current object.
- associationName : The name of the multiple association.
- selectionConfig (optional) : it is an object of class \muuska\dao\util\SelectionConfig to specify data selection options.
- Return type : Collection of objects
- getParents
- Description : Returns the list of parent objects of the current object.
Throws an exception if the object’s class does not have the “parentId” attribute. - Parameter :
- model : the current object.
- selectionConfig (facultatif)
- Return type : Collection of objects
- Description : Returns the list of parent objects of the current object.
- getChildren
- Description : Returns the list of child objects of the current object.
Throws an exception if the object’s class does not have the “parentId” attribute. - Parameter :
- model : the current object.
- selectionConfig (facultatif)
- Return type : Collection of objects
- Description : Returns the list of child objects of the current object.
- getForeignDAO
- Description : Returns the DAO of an external object.
- Parameter :
- field : Control to which the external DAO is associated.
- Return type : DAO
- getMultipleAssociationDAO
- Description : Returns the DAO of a multiple association
- Parameter :
- associationName : The name of the multiple association.
- Return type : DAO
2. Data manipulation
For this part, we will create a “TestDao” controller. We are going to create a “test-dao” control.
a. Initialization
Creating the test-dao control
Go to your controller/front folder and create a TestDAOController class
[pastacode lang=”php” manual=”%3C%3Fphp%0Anamespace%20myapp%3B%0A%0Ause%20muuska%5Cproject%5CAbstractSubApplication%3B%0A%0Aclass%20FrontSubApplication%20extends%20AbstractSubApplication%0A%7B%0A%20%20%20%20public%20function%20createController(%5Cmuuska%5Ccontroller%5CControllerInput%20%24input)%20%7B%0A%20%20%20%20%20%20%20%20%24result%20%3D%20null%3B%0A%20%20%20%20%20%20%20%20if%20(%24input-%3EcheckName(‘hello-world’))%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%24result%20%3D%20new%20%5Cmyapp%5Ccontroller%5Cfront%5CHelloWorldController(%24input)%3B%0A%20%20%20%20%20%20%20%20%7Delseif%20(%24input-%3EcheckName(‘test-model’))%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%24result%20%3D%20new%20%5Cmyapp%5Ccontroller%5Cfront%5CTestModelController(%24input)%3B%0A%20%20%20%20%20%20%20%20%7Delseif%20(%24input-%3EcheckName(‘test-dao’))%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%24result%20%3D%20new%20%5Cmyapp%5Ccontroller%5Cfront%5CTestDAOController(%24input)%3B%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20return%20%24result%3B%0A%20%20%20%20%7D%0A%7D%0A” message=”” highlight=”” provider=”manual”/]
Enter the url http://localhost/muuska/en/test-dao to access it
Retrieving an instance of the DAO
To retrieve the instance of a DAO, add the following statement at the controller level :
[pastacode lang=”coffeescript” manual=”%24libraryDao%20%3D%20%24this-%3Einput-%3EgetDAO(LibraryDefinition%3A%3AgetInstance())%3B” message=”” highlight=”” provider=”manual”/]
The “getDAO” method takes as parameter the definition of the object from which we want to retrieve the DAO.
b. Registration
– The \muuska\dao\util\SaveConfig class
This class has several methods for defining recording options :
- setExludedFields
indicate the fields to be excluded during the registration.
- setSpecificFields
Indicate the specific fields to save.
- createAssociatedFieldSaveConfig
Creates and adds the record configuration of an associated object. It takes as parameter the name of the field on which the reference of the external object is defined.
- createMultipleSaveAssociation
Create a configuration for a multiple association
– Adding
[pastacode lang=”php” manual=”%24libraryDao%20%3D%20%24this-%3Einput-%3EgetDAO(LibraryDefinition%3A%3AgetInstance())%3B%0A%24library%20%3D%20new%20Library()%3B%0A%24library-%3EsetName(‘My%20library’)%3B%0A%24library-%3EsetOpeningTime(‘Monday’)%3B%0A%24library-%3EsetAccessibility(Accessibility%3A%3APUBLIC)%3B%0A%24library-%3EsetDescription(‘My%20library%20desc’)%3B%0A%0A%2F*Cr%C3%A9ation%20de%20l’adresse*%2F%0A%24address%20%3D%20AddressDefinition%3A%3AgetInstance()-%3EcreateModel()%3B%0A%24address-%3EsetPropertyValue(‘address’%2C%20’4500%20NY’)%3B%0A%24address-%3EsetPropertyValue(‘city’%2C%20’New%20york’)%3B%0A%24address-%3EsetPropertyValue(‘state’%2C%20’New%20york’)%3B%0A%24address-%3EsetPropertyValue(‘country’%2C%20’US’)%3B%0A%0A%2F*Cr%C3%A9ation%20de%20la%20sp%C3%A9cialit%C3%A9%20*%2F%0A%24specialityDao%20%3D%20%24this-%3Einput-%3EgetDAO(SpecialityDefinition%3A%3AgetInstance())%3B%0A%24speciality1%20%3D%20SpecialityDefinition%3A%3AgetInstance()-%3EcreateModel()%3B%0A%24speciality1-%3EsetPropertyValue(‘name’%2C%20’Art’)%3B%0A%0A%2F*Ajout%20de%20la%20sp%C3%A9cialit%C3%A9%20*%2F%0A%24specialityDao-%3Eadd(%24speciality1)%3B%0A%0A%24libSpeciality1%20%3D%20LibrarySpecialityDefinition%3A%3AgetInstance()-%3EcreateModel()%3B%0A%24libSpeciality1-%3EsetPropertyValue(‘specialityId’%2C%24speciality1-%3EgetPropertyValue(‘id’))%3B%0A%0A%24speciality2%20%3D%20SpecialityDefinition%3A%3AgetInstance()-%3EcreateModel()%3B%0A%24speciality2-%3EsetPropertyValue(‘name’%2C%20’Musique’)%3B%0A%0A%2F*Ajout%20de%20la%20sp%C3%A9cialit%C3%A9*%2F%0A%24specialityDao-%3Eadd(%24speciality2)%3B%0A%0A%24libSpeciality2%20%3D%20LibrarySpecialityDefinition%3A%3AgetInstance()-%3EcreateModel()%3B%0A%24libSpeciality2-%3EsetPropertyValue(‘specialityId’%2C%24speciality2-%3EgetPropertyValue(‘id’))%3B%0A%0A%2F*Modification%20de%20l’adresse%20de%20la%20biblioth%C3%A8que*%2F%0A%24library-%3EsetAssociated(‘addressId’%2C%20%24address)%3B%0A%0A%2F*Ajout%20des%20sp%C3%A9cialit%C3%A9s%20%C3%A0%20la%20biblioth%C3%A8que%20*%2F%0A%24library-%3EaddMultipleAssociated(‘specialities’%2C%20%24libSpeciality1)%3B%0A%24library-%3EaddMultipleAssociated(‘specialities’%2C%20%24libSpeciality2)%3B%0A%0A%2F*Cr%C3%A9ation%20du%20SaveConfig*%2F%0A%24saveConfig%20%3D%20%24this-%3Einput-%3EcreateSaveConfig()%3B%0A%0A%2F*On%20demande%20d’enregistrer%20l’adresse%20avant%20d’enregistrer%20la%20biblioth%C3%A8que*%2F%0A%24saveConfig-%3EcreateAssociatedFieldSaveConfig(‘addressId’)%3B%0A%0A%2F*Instruction%20pour%20associer%20les%20sp%C3%A9cialit%C3%A9s%20%C3%A0%20la%20biblioth%C3%A8que%20apr%C3%A8s%20son%20enregistre-ment*%2F%0A%24saveConfig-%3EcreateMultipleSaveAssociation(‘specialities’)%3B%0A%24libraryDao-%3Eadd(%24library%2C%20%24saveConfig)%3B%0A” message=”” highlight=”” provider=”manual”/]
Run the controller then check your database to verify the records.
– The modification
[pastacode lang=”php” manual=”protected%20function%20processUpdate()%20%7B%0A%20%20%20%20%24libraryDao%20%3D%20%24this-%3Einput-%3EgetDAO(LibraryDefinition%3A%3AgetInstance())%3B%0A%20%20%20%20%24library%20%3D%20%24libraryDao-%3EgetById(1)%3B%0A%20%20%20%20%24library-%3EsetName(‘My%20library%20updt’)%3B%0A%20%20%20%20%24library-%3EsetAccessibility(Accessibility%3A%3APRIVATE)%3B%0A%20%20%20%20%24libraryDao-%3Eupdate(%24library)%3B%0A%7D%0A” message=”” highlight=”” provider=”manual”/]
Run the controller then check your database to verify the records.
– Editing multiple
[pastacode lang=”php” manual=”protected%20function%20processMultipleUpdate()%20%7B%0A%20%20%20%20%24libraryDao%20%3D%20%24this-%3Einput-%3EgetDAO(LibraryDefinition%3A%3AgetInstance())%3B%0A%20%20%20%20%24library%20%3D%20new%20Library()%3B%0A%20%20%20%20%24library-%3EsetName(‘My%20library%20updt%20multiple’)%3B%0A%20%20%20%20%24library-%3EsetAccessibility(Accessibility%3A%3APRIVATE)%3B%0A%20%20%20%20%24saveConfig%20%3D%20%24this-%3Einput-%3EcreateSaveConfig()%3B%0A%20%20%20%20%0A%20%20%20%20%2F*Ajout%20des%20options%20pour%20la%20restriction*%2F%0A%20%20%20%20%24saveConfig-%3EaddRestrictionFieldFromParams(‘openingTime’%2C%20’Monday’)%3B%0A%20%20%20%20%0A%20%20%20%20%24libraryDao-%3EupdateMultipleRows(%24library%2C%20%24saveConfig)%3B%0A%7D%0A%09%0A” message=”” highlight=”” provider=”manual”/]
– Changing a value
[pastacode lang=”php” manual=”protected%20function%20processChangeValue()%20%7B%0A%20%20%20%20%24libraryDao%20%3D%20%24this-%3Einput-%3EgetDAO(LibraryDefinition%3A%3AgetInstance())%3B%0A%20%20%20%20%24saveConfig%20%3D%20%24this-%3Einput-%3EcreateSaveConfig()%3B%0A%20%20%20%20%0A%20%20%20%20%2F*Ajout%20des%20options%20pour%20la%20restriction*%2F%0A%20%20%20%20%24saveConfig-%3EaddRestrictionFieldFromParams(‘openingTime’%2C%20’Monday’)%3B%0A%20%20%20%20%0A%20%20%20%20%24libraryDao-%3EchangeValueOnMultipleRows(‘name’%2C%20’My%20library%20value%20changed’%2C%20%24saveConfig)%3B%0A%7D%0A” message=”” highlight=”” provider=”manual”/]
c. Selection
– The class “muuska\dao\util\SelectionConfig”
This class defines how the data will be recovered (the selection criteria, sort criteria, the limit of data to retrieve).
The following table describes the attributes of the class “muuska\dao\util\SelectionConfig”
- Attribut
- langEnabled
- Description : Indicate if you will retrieve the values of translatable fields
- Data type : boolean
- default : true
- allLangsEnabled
- Description : Indicate if you will retrieve the values of translatable fields in all available languages.
- Data type : boolean
- default : false
- lang
- Description : The language in which the data will be retrieved
(If the Model concerned takes multilingual into account) - Data type : String
- Description : The language in which the data will be retrieved
- dataCountingEnabled
- Description : Indicate if you will also get the total number of data.
- Data type : boolean
- default : false
- start
- Description : The index where data reading should begin. (The first index is 0).
- Data type : integer
- default : 0
- limit
- Description : The maximum number of data to recover. If this field is not specified, all data will be recovered.
- Data type : integer
- default : 0
- logicalOperator
- Description : The logical operator (AND or OR) to use between restrictions. The class “muuska\constant\operator\LogicalOperator” has constants for use for this attribute.
- Data type : integer
- default : 1 : AND_
- virtualDeletedEnabled
- Description : Specifies whether items that were removed virtually be selected.
- Data type : boolean
- default : false
- onlyActive
- Description : Indicates if only wants the active elements (Only if the Model to an “active” attribute).
- Data type : boolean
- default : false
- restrictionFields
- Description : List of fields where restrictions are applied.
The elements of this table are of type “muuska\dao\util\FieldRestriction”. - Data type : table
- Description : List of fields where restrictions are applied.
- sortOptions
- Description : List of fields where the sort options are configured.
The elements of this array are of type “muuska \ dao \ util \ SortOption. - Data type : table
- Description : List of fields where the sort options are configured.
- selectionAssociations
- Description : List of fields where the associated data selection options are configured.
The elements of this array are objects of the “muuska \ dao \ util \ SelectionAssociation” class. - Data type : table
- Description : List of fields where the associated data selection options are configured.
- langEnabled
– Standard selection
[pastacode lang=”php” manual=”protected%20function%20processSelect()%20%7B%0A%20%20%20%20%24libraryDao%20%3D%20%24this-%3Einput-%3EgetDAO(LibraryDefinition%3A%3AgetInstance())%3B%0A%20%20%20%20%24data%20%3D%20%24libraryDao-%3EgetData()%3B%0A%20%20%20%20var_dump(%24data)%3B%0A%7D%0A” message=”” highlight=”” provider=”manual”/]
– Selection with total number of data
[pastacode lang=”php” manual=”protected%20function%20processSelectWithTotal()%20%7B%0A%20%20%20%20%24libraryDao%20%3D%20%24this-%3Einput-%3EgetDAO(LibraryDefinition%3A%3AgetInstance())%3B%0A%20%20%20%20%24selectionConfig%20%3D%20%24this-%3Einput-%3EcreateSelectionConfig()%3B%0A%20%20%20%20%24selectionConfig-%3EsetDataCountingEnabled(true)%3B%0A%20%20%20%20%24selectionConfig-%3EsetLimit(1)%3B%0A%20%20%20%20%24data%20%3D%20%24libraryDao-%3EgetData(%24selectionConfig)%3B%0A%20%20%20%20var_dump(‘total%20without%20limit%20%3A%20’%2C%20%24data-%3EgetTotalWithoutLimit())%3B%0A%20%20%20%20var_dump(%24data)%3B%0A%7D%0A” message=”” highlight=”” provider=”manual”/]
Result
– Retrieving information on objects associated with the Model
Here is a list of methods in the class “core \ utilities \ dao \ SelectionConfig” for managing the objects associated with a Model.
- methods
- addSelectionAssociation
- Description : Adds an association configuration to the list (selectionAssociations)
- Parameter :
- selectionAssociation : it is a class object “muuska\dao\util\SelectionAssociation”.
- key (optional) : the key of the object in the list. If this value is not given then the name of the concerned field will be used as the key.
- hasAssociation
- Description : Checks if a key exists in the association list.
- Parameter :
- key : the key sought.
- Return type : boolean
- getSelectionAssociationByKey
- Description : Returns an association based on a key.
If the searched key does not exist, “null” will be returned. - Parameter :
- key : the key sought.
- getNewIfNotExist (optional) : Allows you to indicate whether you want a new object to be returned in case the one sought does not exist. (Default value: “false”).
- addToListIfNotExist (optional) : Used to indicate whether you want the new object to be created in case the one sought does not exist is added to the list. (Default value: “false”).
- Return type : Selection Association
- Description : Returns an association based on a key.
- setSelectionAssociationParams
- Description : Adds or Modifies (If it already exists) an association from the parameters.
- Parameter :
- fieldName : the name of the field on which there is the reference.
- joinType (optional) : The type of join to use. The class “muuska \ dao \ constant \ JoinType” has constants for use in this setting. (Default value: JoinType :: LEFT).
- retrievingEnabled (optional) : Indicates whether or not you want to retrieve the information of the associated object. (Default: true).
- langEnabled (optional) : Indicates whether to retrieve the values of the translatable fields. (Default: true).
- langEnabled (optional) : Indicates whether you want to retrieve the values of the translatable fields in all the available languages. (Default: false).
- addSelectionAssociation
Example
[pastacode lang=”php” manual=”protected%20function%20processSelectAssociation()%20%7B%0A%20%20%20%20%24libraryDao%20%3D%20%24this-%3Einput-%3EgetDAO(LibraryDefinition%3A%3AgetInstance())%3B%0A%20%20%20%20%24selectionConfig%20%3D%20%24this-%3Einput-%3EcreateSelectionConfig()%3B%0A%20%20%20%20%24selectionConfig-%3EsetSelectionAssociationParams(‘addressId’)%3B%0A%20%20%20%20%24data%20%3D%20%24libraryDao-%3EgetData(%24selectionConfig)%3B%0A%20%20%20%20foreach%20(%24data%20as%20%24object)%20%7B%0A%20%20%20%20%20%20%20%20var_dump(%24object-%3EgetAssociated(‘addressId’))%3B%0A%20%20%20%20%7D%0A%7D%0A” message=”” highlight=”” provider=”manual”/]
