/app/class-ms-model.php

  1. <?php 
  2. /** 
  3. * Abstract class for all Models. 
  4. * 
  5. * All models will extend or inherit from the MS_Model class. 
  6. * Methods of this class will prepare objects for the database and 
  7. * manipulate data to be used in a MS_Controller. 
  8. * 
  9. * @since 1.0.0 
  10. * 
  11. * @package Membership2 
  12. */ 
  13. class MS_Model extends MS_Hooker { 
  14.  
  15. /** 
  16. * ID of the model object. 
  17. * 
  18. * @since 1.0.0 
  19. * 
  20. * @var int|string 
  21. */ 
  22. protected $id; 
  23.  
  24. /** 
  25. * Model name. 
  26. * 
  27. * @since 1.0.0 
  28. * 
  29. * @var string 
  30. */ 
  31. protected $name; 
  32.  
  33. /** 
  34. * Stores the caching state of the object. 
  35. * This value is ONLY modified by MS_Factory::set_singleton(), so if it is 
  36. * true it means that this object can be accessed via MS_Factory::load() 
  37. * 
  38. * @since 1.0.0 
  39. * 
  40. * @var bool 
  41. */ 
  42. public $_in_cache = false; 
  43.  
  44. /** 
  45. * An array containing the serialized array which is stored in the DB. 
  46. * 
  47. * This data can be used to determine which fields have been changed since 
  48. * the object was loaded from DB. 
  49. * 
  50. * This field is populated by MS_Factory::populate() 
  51. * 
  52. * @var array 
  53. */ 
  54. public $_saved_data = array(); 
  55.  
  56. /** 
  57. * MS_Model Contstuctor 
  58. * 
  59. * @since 1.0.0 
  60. */ 
  61. public function __construct() { 
  62.  
  63. /** 
  64. * Actions to execute when constructing the parent Model. 
  65. * 
  66. * @since 1.0.0 
  67. * @param object $this The MS_Model object. 
  68. */ 
  69. do_action( 'ms_model_construct', $this ); 
  70.  
  71. /** 
  72. * Set field value, bypassing the __set validation. 
  73. * 
  74. * Used for loading from db. 
  75. * 
  76. * @since 1.0.0 
  77. * 
  78. * @param string $field 
  79. * @param mixed $value 
  80. */ 
  81. public function set_field( $field, $value ) { 
  82. // Don't deserialize values of "private" fields. 
  83. if ( '_' !== $field[0] ) { 
  84.  
  85. // Only set values of existing fields, don't create a new field. 
  86. if ( property_exists( $this, $field ) ) { 
  87. $this->$field = $value; 
  88.  
  89. /** 
  90. * Resets the fields value to the value that is stored in the DB. 
  91. * 
  92. * @since 1.0.1.0 
  93. * 
  94. * @param string $field Name of the field. 
  95. * @return mixed The reset value. 
  96. */ 
  97. public function reset_field( $field ) { 
  98. $result = null; 
  99.  
  100. // Don't modify values of "private" fields. 
  101. if ( '_' !== $field[0] ) { 
  102.  
  103. // Only reset values of existing fields. 
  104. if ( property_exists( $this, $field ) 
  105. && isset( $this->_saved_data[$field] ) 
  106. ) { 
  107. $this->$field = $this->_saved_data[$field]; 
  108. $result = $this->$field; 
  109.  
  110. return $result; 
  111.  
  112. /** 
  113. * Called before saving model. 
  114. * 
  115. * @since 1.0.0 
  116. */ 
  117. public function before_save() { 
  118. do_action( 'ms_model_before_save', $this ); 
  119.  
  120. /** 
  121. * Abstract method to save model data. 
  122. * 
  123. * @since 1.0.0 
  124. */ 
  125. public function save() { 
  126. throw new Exception( 'Method to be implemented in child class' ); 
  127.  
  128. /** 
  129. * Set the singleton instance if it is not yet defined. 
  130. * 
  131. * @since 1.0.0 
  132. */ 
  133. public function store_singleton() { 
  134. if ( $this->_in_cache ) { return; } 
  135. MS_Factory::set_singleton( $this ); 
  136.  
  137. /** 
  138. * Called after saving model data. 
  139. * 
  140. * @since 1.0.0 
  141. */ 
  142. public function after_save() { 
  143. do_action( 'ms_model_after_save', $this ); 
  144.  
  145. /** 
  146. * Get object properties. 
  147. * 
  148. * @since 1.0.0 
  149. * 
  150. * @return array of fields. 
  151. */ 
  152. public function get_object_vars() { 
  153. return get_object_vars( $this ); 
  154.  
  155. /** 
  156. * Validate dates used within models. 
  157. * 
  158. * @since 1.0.0 
  159. * 
  160. * @param string $date Date as a PHP date string 
  161. * @param string $format Date format. 
  162. */ 
  163. public function validate_date( $date, $format = 'Y-m-d' ) { 
  164. $valid = null; 
  165.  
  166. $d = new DateTime( $date ); 
  167. if ( $d && $d->format( $format ) == $date ) { 
  168. $valid = $date; 
  169.  
  170. return apply_filters( 
  171. 'ms_model_validate_date',  
  172. $valid,  
  173. $date,  
  174. $format,  
  175. $this 
  176. ); 
  177.  
  178. /** 
  179. * Validate time periods array structure. 
  180. * 
  181. * @since 1.0.0 
  182. * 
  183. * @param string $period Membership period to validate 
  184. * @param int $default_period_unit Number of periods (e.g. number of days) 
  185. * @param string $default_period_type (e.g. days, weeks, years) 
  186. */ 
  187. public function validate_period( $period, $default_period_unit = 0, $default_period_type = MS_Helper_Period::PERIOD_TYPE_DAYS ) { 
  188.  
  189. $default = array( 
  190. 'period_unit' => $default_period_unit,  
  191. 'period_type' => $default_period_type,  
  192. ); 
  193.  
  194. if ( ! empty( $period['period_unit'] ) 
  195. && ! empty( $period['period_type'] ) 
  196. ) { 
  197. $period['period_unit'] = $this->validate_period_unit( $period['period_unit'] ); 
  198. $period['period_type'] = $this->validate_period_type( $period['period_type'] ); 
  199. } else { 
  200. $period = $default; 
  201.  
  202. return apply_filters( 
  203. 'ms_model_validate_period',  
  204. $period,  
  205. $this 
  206. ); 
  207.  
  208. /** 
  209. * Validate period unit. 
  210. * 
  211. * @since 1.0.0 
  212. * 
  213. * @param string $period_unit The period quantity to validate. 
  214. * @param int $default The default value when not validated. Default to 1. 
  215. */ 
  216. public function validate_period_unit( $period_unit, $default = 1 ) { 
  217. $period_unit = intval( $period_unit ); 
  218.  
  219. if ( $period_unit <= 0 ) { 
  220. $period_unit = $default; 
  221.  
  222. return apply_filters( 
  223. 'ms_model_validate_period_unit',  
  224. $period_unit,  
  225. $this 
  226. ); 
  227.  
  228. /** 
  229. * Validate period type. 
  230. * 
  231. * @since 1.0.0 
  232. * 
  233. * @param string $period_type The period type to validate. 
  234. * @param int $default The default value when not validated. Default to days. 
  235. */ 
  236. public function validate_period_type( $period_type, $default = MS_Helper_Period::PERIOD_TYPE_DAYS ) { 
  237. $valid_types = MS_Helper_Period::get_period_types(); 
  238. if ( ! isset( $valid_types[$period_type] ) ) { 
  239. $period_type = $default; 
  240.  
  241. return apply_filters( 
  242. 'ms_model_validate_period_type',  
  243. $period_type,  
  244. $this 
  245. ); 
.