eventespresso /
event-espresso-core
Duplicate code is one of the most pungent code smells. A rule that is often used is to re-structure code once it is duplicated in three or more places.
Common duplication problems, and corresponding solutions are:
Complex classes like EE_Base_Class often do a lot of different things. To break such a class down, we need to identify a cohesive component within that class. A common approach to find such a component is to look for fields/methods that share the same prefixes, or suffixes. You can also have a look at the cohesion graph to spot any un-connected, or weakly-connected components.
Once you have determined the fields that belong together, you can apply the Extract Class refactoring. If the component makes sense as a sub-class, Extract Subclass is also a candidate, and is often faster.
While breaking up the class, it is a good idea to analyze how other classes use EE_Base_Class, and based on these observations, apply Extract Interface, too.
| 1 | <?php |
||
| 30 | abstract class EE_Base_Class |
||
| 31 | { |
||
| 32 | |||
| 33 | /** |
||
| 34 | * This is an array of the original properties and values provided during construction |
||
| 35 | * of this model object. (keys are model field names, values are their values). |
||
| 36 | * This list is important to remember so that when we are merging data from the db, we know |
||
| 37 | * which values to override and which to not override. |
||
| 38 | * |
||
| 39 | * @var array |
||
| 40 | */ |
||
| 41 | protected $_props_n_values_provided_in_constructor; |
||
| 42 | |||
| 43 | /** |
||
| 44 | * Timezone |
||
| 45 | * This gets set by the "set_timezone()" method so that we know what timezone incoming strings|timestamps are in. |
||
| 46 | * This can also be used before a get to set what timezone you want strings coming out of the object to be in. NOT |
||
| 47 | * all EE_Base_Class child classes use this property but any that use a EE_Datetime_Field data type will have |
||
| 48 | * access to it. |
||
| 49 | * |
||
| 50 | * @var string |
||
| 51 | */ |
||
| 52 | protected $_timezone; |
||
| 53 | |||
| 54 | |||
| 55 | |||
| 56 | /** |
||
| 57 | * date format |
||
| 58 | * pattern or format for displaying dates |
||
| 59 | * |
||
| 60 | * @var string $_dt_frmt |
||
| 61 | */ |
||
| 62 | protected $_dt_frmt; |
||
| 63 | |||
| 64 | |||
| 65 | |||
| 66 | /** |
||
| 67 | * time format |
||
| 68 | * pattern or format for displaying time |
||
| 69 | * |
||
| 70 | * @var string $_tm_frmt |
||
| 71 | */ |
||
| 72 | protected $_tm_frmt; |
||
| 73 | |||
| 74 | |||
| 75 | |||
| 76 | /** |
||
| 77 | * This property is for holding a cached array of object properties indexed by property name as the key. |
||
| 78 | * The purpose of this is for setting a cache on properties that may have calculated values after a |
||
| 79 | * prepare_for_get. That way the cache can be checked first and the calculated property returned instead of having |
||
| 80 | * to recalculate. Used by _set_cached_property() and _get_cached_property() methods. |
||
| 81 | * |
||
| 82 | * @var array |
||
| 83 | */ |
||
| 84 | protected $_cached_properties = array(); |
||
| 85 | |||
| 86 | /** |
||
| 87 | * An array containing keys of the related model, and values are either an array of related mode objects or a |
||
| 88 | * single |
||
| 89 | * related model object. see the model's _model_relations. The keys should match those specified. And if the |
||
| 90 | * relation is of type EE_Belongs_To (or one of its children), then there should only be ONE related model object, |
||
| 91 | * all others have an array) |
||
| 92 | * |
||
| 93 | * @var array |
||
| 94 | */ |
||
| 95 | protected $_model_relations = array(); |
||
| 96 | |||
| 97 | /** |
||
| 98 | * Array where keys are field names (see the model's _fields property) and values are their values. To see what |
||
| 99 | * their types should be, look at what that field object returns on its prepare_for_get and prepare_for_set methods) |
||
| 100 | * |
||
| 101 | * @var array |
||
| 102 | */ |
||
| 103 | protected $_fields = array(); |
||
| 104 | |||
| 105 | /** |
||
| 106 | * @var boolean indicating whether or not this model object is intended to ever be saved |
||
| 107 | * For example, we might create model objects intended to only be used for the duration |
||
| 108 | * of this request and to be thrown away, and if they were accidentally saved |
||
| 109 | * it would be a bug. |
||
| 110 | */ |
||
| 111 | protected $_allow_persist = true; |
||
| 112 | |||
| 113 | /** |
||
| 114 | * @var boolean indicating whether or not this model object's properties have changed since construction |
||
| 115 | */ |
||
| 116 | protected $_has_changes = false; |
||
| 117 | |||
| 118 | /** |
||
| 119 | * @var EEM_Base |
||
| 120 | */ |
||
| 121 | protected $_model; |
||
| 122 | |||
| 123 | |||
| 124 | |||
| 125 | /** |
||
| 126 | * basic constructor for Event Espresso classes, performs any necessary initialization, and verifies it's children |
||
| 127 | * play nice |
||
| 128 | * |
||
| 129 | * @param array $fieldValues where each key is a field (ie, array key in the 2nd |
||
| 130 | * layer of the model's _fields array, (eg, EVT_ID, |
||
| 131 | * TXN_amount, QST_name, etc) and values are their values |
||
| 132 | * @param boolean $bydb a flag for setting if the class is instantiated by the |
||
| 133 | * corresponding db model or not. |
||
| 134 | * @param string $timezone indicate what timezone you want any datetime fields to |
||
| 135 | * be in when instantiating a EE_Base_Class object. |
||
| 136 | * @param array $date_formats An array of date formats to set on construct where first |
||
| 137 | * value is the date_format and second value is the time |
||
| 138 | * format. |
||
| 139 | * @throws EE_Error |
||
| 140 | */ |
||
| 141 | protected function __construct($fieldValues = array(), $bydb = false, $timezone = '', $date_formats = array()) |
||
| 200 | |||
| 201 | |||
| 202 | |||
| 203 | /** |
||
| 204 | * Gets whether or not this model object is allowed to persist/be saved to the database. |
||
| 205 | * |
||
| 206 | * @return boolean |
||
| 207 | */ |
||
| 208 | public function allow_persist() |
||
| 212 | |||
| 213 | |||
| 214 | |||
| 215 | /** |
||
| 216 | * Sets whether or not this model object should be allowed to be saved to the DB. |
||
| 217 | * Normally once this is set to FALSE you wouldn't set it back to TRUE, unless |
||
| 218 | * you got new information that somehow made you change your mind. |
||
| 219 | * |
||
| 220 | * @param boolean $allow_persist |
||
| 221 | * @return boolean |
||
| 222 | */ |
||
| 223 | public function set_allow_persist($allow_persist) |
||
| 227 | |||
| 228 | |||
| 229 | |||
| 230 | /** |
||
| 231 | * Gets the field's original value when this object was constructed during this request. |
||
| 232 | * This can be helpful when determining if a model object has changed or not |
||
| 233 | * |
||
| 234 | * @param string $field_name |
||
| 235 | * @return mixed|null |
||
| 236 | * @throws \EE_Error |
||
| 237 | */ |
||
| 238 | public function get_original($field_name) |
||
| 248 | |||
| 249 | |||
| 250 | |||
| 251 | /** |
||
| 252 | * @param EE_Base_Class $obj |
||
| 253 | * @return string |
||
| 254 | */ |
||
| 255 | public function get_class($obj) |
||
| 259 | |||
| 260 | |||
| 261 | |||
| 262 | /** |
||
| 263 | * Overrides parent because parent expects old models. |
||
| 264 | * This also doesn't do any validation, and won't work for serialized arrays |
||
| 265 | * |
||
| 266 | * @param string $field_name |
||
| 267 | * @param mixed $field_value |
||
| 268 | * @param bool $use_default |
||
| 269 | * @throws \EE_Error |
||
| 270 | */ |
||
| 271 | public function set($field_name, $field_value, $use_default = false) |
||
| 347 | |||
| 348 | |||
| 349 | |||
| 350 | /** |
||
| 351 | * This sets the field value on the db column if it exists for the given $column_name or |
||
| 352 | * saves it to EE_Extra_Meta if the given $column_name does not match a db column. |
||
| 353 | * |
||
| 354 | * @see EE_message::get_column_value for related documentation on the necessity of this method. |
||
| 355 | * @param string $field_name Must be the exact column name. |
||
| 356 | * @param mixed $field_value The value to set. |
||
| 357 | * @return int|bool @see EE_Base_Class::update_extra_meta() for return docs. |
||
| 358 | * @throws \EE_Error |
||
| 359 | */ |
||
| 360 | public function set_field_or_extra_meta($field_name, $field_value) |
||
| 371 | |||
| 372 | |||
| 373 | |||
| 374 | /** |
||
| 375 | * This retrieves the value of the db column set on this class or if that's not present |
||
| 376 | * it will attempt to retrieve from extra_meta if found. |
||
| 377 | * Example Usage: |
||
| 378 | * Via EE_Message child class: |
||
| 379 | * Due to the dynamic nature of the EE_messages system, EE_messengers will always have a "to", |
||
| 380 | * "from", "subject", and "content" field (as represented in the EE_Message schema), however they may |
||
| 381 | * also have additional main fields specific to the messenger. The system accommodates those extra |
||
| 382 | * fields through the EE_Extra_Meta table. This method allows for EE_messengers to retrieve the |
||
| 383 | * value for those extra fields dynamically via the EE_message object. |
||
| 384 | * |
||
| 385 | * @param string $field_name expecting the fully qualified field name. |
||
| 386 | * @return mixed|null value for the field if found. null if not found. |
||
| 387 | * @throws \EE_Error |
||
| 388 | */ |
||
| 389 | public function get_field_or_extra_meta($field_name) |
||
| 399 | |||
| 400 | |||
| 401 | |||
| 402 | /** |
||
| 403 | * See $_timezone property for description of what the timezone property is for. This SETS the timezone internally |
||
| 404 | * for being able to reference what timezone we are running conversions on when converting TO the internal timezone |
||
| 405 | * (UTC Unix Timestamp) for the object OR when converting FROM the internal timezone (UTC Unix Timestamp). This is |
||
| 406 | * available to all child classes that may be using the EE_Datetime_Field for a field data type. |
||
| 407 | * |
||
| 408 | * @access public |
||
| 409 | * @param string $timezone A valid timezone string as described by @link http://www.php.net/manual/en/timezones.php |
||
| 410 | * @return void |
||
| 411 | * @throws \EE_Error |
||
| 412 | */ |
||
| 413 | public function set_timezone($timezone = '') |
||
| 429 | |||
| 430 | |||
| 431 | |||
| 432 | /** |
||
| 433 | * This just returns whatever is set for the current timezone. |
||
| 434 | * |
||
| 435 | * @access public |
||
| 436 | * @return string timezone string |
||
| 437 | */ |
||
| 438 | public function get_timezone() |
||
| 442 | |||
| 443 | |||
| 444 | |||
| 445 | /** |
||
| 446 | * This sets the internal date format to what is sent in to be used as the new default for the class |
||
| 447 | * internally instead of wp set date format options |
||
| 448 | * |
||
| 449 | * @since 4.6 |
||
| 450 | * @param string $format should be a format recognizable by PHP date() functions. |
||
| 451 | */ |
||
| 452 | public function set_date_format($format) |
||
| 458 | |||
| 459 | |||
| 460 | |||
| 461 | /** |
||
| 462 | * This sets the internal time format string to what is sent in to be used as the new default for the |
||
| 463 | * class internally instead of wp set time format options. |
||
| 464 | * |
||
| 465 | * @since 4.6 |
||
| 466 | * @param string $format should be a format recognizable by PHP date() functions. |
||
| 467 | */ |
||
| 468 | public function set_time_format($format) |
||
| 474 | |||
| 475 | |||
| 476 | |||
| 477 | /** |
||
| 478 | * This returns the current internal set format for the date and time formats. |
||
| 479 | * |
||
| 480 | * @param bool $full if true (default), then return the full format. Otherwise will return an array |
||
| 481 | * where the first value is the date format and the second value is the time format. |
||
| 482 | * @return mixed string|array |
||
| 483 | */ |
||
| 484 | public function get_format($full = true) |
||
| 488 | |||
| 489 | |||
| 490 | |||
| 491 | /** |
||
| 492 | * cache |
||
| 493 | * stores the passed model object on the current model object. |
||
| 494 | * In certain circumstances, we can use this cached model object instead of querying for another one entirely. |
||
| 495 | * |
||
| 496 | * @param string $relationName one of the keys in the _model_relations array on the model. Eg |
||
| 497 | * 'Registration' associated with this model object |
||
| 498 | * @param EE_Base_Class $object_to_cache that has a relation to this model object. (Eg, if this is a Transaction, |
||
| 499 | * that could be a payment or a registration) |
||
| 500 | * @param null $cache_id a string or number that will be used as the key for any Belongs_To_Many |
||
| 501 | * items which will be stored in an array on this object |
||
| 502 | * @throws EE_Error |
||
| 503 | * @return mixed index into cache, or just TRUE if the relation is of type Belongs_To (because there's only one |
||
| 504 | * related thing, no array) |
||
| 505 | */ |
||
| 506 | public function cache($relationName = '', $object_to_cache = null, $cache_id = null) |
||
| 551 | |||
| 552 | |||
| 553 | |||
| 554 | /** |
||
| 555 | * For adding an item to the cached_properties property. |
||
| 556 | * |
||
| 557 | * @access protected |
||
| 558 | * @param string $fieldname the property item the corresponding value is for. |
||
| 559 | * @param mixed $value The value we are caching. |
||
| 560 | * @param string|null $cache_type |
||
| 561 | * @return void |
||
| 562 | * @throws \EE_Error |
||
| 563 | */ |
||
| 564 | protected function _set_cached_property($fieldname, $value, $cache_type = null) |
||
| 571 | |||
| 572 | |||
| 573 | |||
| 574 | /** |
||
| 575 | * This returns the value cached property if it exists OR the actual property value if the cache doesn't exist. |
||
| 576 | * This also SETS the cache if we return the actual property! |
||
| 577 | * |
||
| 578 | * @param string $fieldname the name of the property we're trying to retrieve |
||
| 579 | * @param bool $pretty |
||
| 580 | * @param string $extra_cache_ref This allows the user to specify an extra cache ref for the given property |
||
| 581 | * (in cases where the same property may be used for different outputs |
||
| 582 | * - i.e. datetime, money etc.) |
||
| 583 | * It can also accept certain pre-defined "schema" strings |
||
| 584 | * to define how to output the property. |
||
| 585 | * see the field's prepare_for_pretty_echoing for what strings can be used |
||
| 586 | * @return mixed whatever the value for the property is we're retrieving |
||
| 587 | * @throws \EE_Error |
||
| 588 | */ |
||
| 589 | protected function _get_cached_property($fieldname, $pretty = false, $extra_cache_ref = null) |
||
| 603 | |||
| 604 | |||
| 605 | |||
| 606 | /** |
||
| 607 | * If the cache didn't fetch the needed item, this fetches it. |
||
| 608 | * @param string $fieldname |
||
| 609 | * @param bool $pretty |
||
| 610 | * @param string $extra_cache_ref |
||
| 611 | * @return mixed |
||
| 612 | */ |
||
| 613 | protected function _get_fresh_property($fieldname, $pretty = false, $extra_cache_ref = null) |
||
| 628 | |||
| 629 | |||
| 630 | |||
| 631 | /** |
||
| 632 | * set timezone, formats, and output for EE_Datetime_Field objects |
||
| 633 | * |
||
| 634 | * @param \EE_Datetime_Field $datetime_field |
||
| 635 | * @param bool $pretty |
||
| 636 | * @param null $date_or_time |
||
| 637 | * @return void |
||
| 638 | * @throws \EE_Error |
||
| 639 | */ |
||
| 640 | protected function _prepare_datetime_field( |
||
| 660 | |||
| 661 | |||
| 662 | |||
| 663 | /** |
||
| 664 | * This just takes care of clearing out the cached_properties |
||
| 665 | * |
||
| 666 | * @return void |
||
| 667 | */ |
||
| 668 | protected function _clear_cached_properties() |
||
| 672 | |||
| 673 | |||
| 674 | |||
| 675 | /** |
||
| 676 | * This just clears out ONE property if it exists in the cache |
||
| 677 | * |
||
| 678 | * @param string $property_name the property to remove if it exists (from the _cached_properties array) |
||
| 679 | * @return void |
||
| 680 | */ |
||
| 681 | protected function _clear_cached_property($property_name) |
||
| 687 | |||
| 688 | |||
| 689 | |||
| 690 | /** |
||
| 691 | * Ensures that this related thing is a model object. |
||
| 692 | * |
||
| 693 | * @param mixed $object_or_id EE_base_Class/int/string either a related model object, or its ID |
||
| 694 | * @param string $model_name name of the related thing, eg 'Attendee', |
||
| 695 | * @return EE_Base_Class |
||
| 696 | * @throws \EE_Error |
||
| 697 | */ |
||
| 698 | protected function ensure_related_thing_is_model_obj($object_or_id, $model_name) |
||
| 706 | |||
| 707 | |||
| 708 | |||
| 709 | /** |
||
| 710 | * Forgets the cached model of the given relation Name. So the next time we request it, |
||
| 711 | * we will fetch it again from the database. (Handy if you know it's changed somehow). |
||
| 712 | * If a specific object is supplied, and the relationship to it is either a HasMany or HABTM, |
||
| 713 | * then only remove that one object from our cached array. Otherwise, clear the entire list |
||
| 714 | * |
||
| 715 | * @param string $relationName one of the keys in the _model_relations array on the model. |
||
| 716 | * Eg 'Registration' |
||
| 717 | * @param mixed $object_to_remove_or_index_into_array or an index into the array of cached things, or NULL |
||
| 718 | * if you intend to use $clear_all = TRUE, or the relation only |
||
| 719 | * has 1 object anyways (ie, it's a BelongsToRelation) |
||
| 720 | * @param bool $clear_all This flags clearing the entire cache relation property if |
||
| 721 | * this is HasMany or HABTM. |
||
| 722 | * @throws EE_Error |
||
| 723 | * @return EE_Base_Class | boolean from which was cleared from the cache, or true if we requested to remove a |
||
| 724 | * relation from all |
||
| 725 | */ |
||
| 726 | public function clear_cache($relationName, $object_to_remove_or_index_into_array = null, $clear_all = false) |
||
| 802 | |||
| 803 | |||
| 804 | |||
| 805 | /** |
||
| 806 | * update_cache_after_object_save |
||
| 807 | * Allows a cached item to have it's cache ID (within the array of cached items) reset using the new ID it has |
||
| 808 | * obtained after being saved to the db |
||
| 809 | * |
||
| 810 | * @param string $relationName - the type of object that is cached |
||
| 811 | * @param \EE_Base_Class $newly_saved_object - the newly saved object to be re-cached |
||
| 812 | * @param string $current_cache_id - the ID that was used when originally caching the object |
||
| 813 | * @return boolean TRUE on success, FALSE on fail |
||
| 814 | * @throws \EE_Error |
||
| 815 | */ |
||
| 816 | public function update_cache_after_object_save( |
||
| 845 | |||
| 846 | |||
| 847 | |||
| 848 | /** |
||
| 849 | * Fetches a single EE_Base_Class on that relation. (If the relation is of type |
||
| 850 | * BelongsTo, it will only ever have 1 object. However, other relations could have an array of objects) |
||
| 851 | * |
||
| 852 | * @param string $relationName |
||
| 853 | * @return EE_Base_Class |
||
| 854 | */ |
||
| 855 | public function get_one_from_cache($relationName) |
||
| 865 | |||
| 866 | |||
| 867 | |||
| 868 | /** |
||
| 869 | * Fetches a single EE_Base_Class on that relation. (If the relation is of type |
||
| 870 | * BelongsTo, it will only ever have 1 object. However, other relations could have an array of objects) |
||
| 871 | * |
||
| 872 | * @param string $relationName |
||
| 873 | * @throws \EE_Error |
||
| 874 | * @return EE_Base_Class[] NOT necessarily indexed by primary keys |
||
| 875 | */ |
||
| 876 | public function get_all_from_cache($relationName) |
||
| 908 | |||
| 909 | |||
| 910 | |||
| 911 | /** |
||
| 912 | * Returns the next x number of EE_Base_Class objects in sequence from this object as found in the database |
||
| 913 | * matching the given query conditions. |
||
| 914 | * |
||
| 915 | * @param null $field_to_order_by What field is being used as the reference point. |
||
| 916 | * @param int $limit How many objects to return. |
||
| 917 | * @param array $query_params Any additional conditions on the query. |
||
| 918 | * @param null $columns_to_select If left null, then an array of EE_Base_Class objects is returned, otherwise |
||
| 919 | * you can indicate just the columns you want returned |
||
| 920 | * @return array|EE_Base_Class[] |
||
| 921 | * @throws \EE_Error |
||
| 922 | */ |
||
| 923 | View Code Duplication | public function next_x($field_to_order_by = null, $limit = 1, $query_params = array(), $columns_to_select = null) |
|
| 935 | |||
| 936 | |||
| 937 | |||
| 938 | /** |
||
| 939 | * Returns the previous x number of EE_Base_Class objects in sequence from this object as found in the database |
||
| 940 | * matching the given query conditions. |
||
| 941 | * |
||
| 942 | * @param null $field_to_order_by What field is being used as the reference point. |
||
| 943 | * @param int $limit How many objects to return. |
||
| 944 | * @param array $query_params Any additional conditions on the query. |
||
| 945 | * @param null $columns_to_select If left null, then an array of EE_Base_Class objects is returned, otherwise |
||
| 946 | * you can indicate just the columns you want returned |
||
| 947 | * @return array|EE_Base_Class[] |
||
| 948 | * @throws \EE_Error |
||
| 949 | */ |
||
| 950 | View Code Duplication | public function previous_x( |
|
| 966 | |||
| 967 | |||
| 968 | |||
| 969 | /** |
||
| 970 | * Returns the next EE_Base_Class object in sequence from this object as found in the database |
||
| 971 | * matching the given query conditions. |
||
| 972 | * |
||
| 973 | * @param null $field_to_order_by What field is being used as the reference point. |
||
| 974 | * @param array $query_params Any additional conditions on the query. |
||
| 975 | * @param null $columns_to_select If left null, then an array of EE_Base_Class objects is returned, otherwise |
||
| 976 | * you can indicate just the columns you want returned |
||
| 977 | * @return array|EE_Base_Class |
||
| 978 | * @throws \EE_Error |
||
| 979 | */ |
||
| 980 | View Code Duplication | public function next($field_to_order_by = null, $query_params = array(), $columns_to_select = null) |
|
| 992 | |||
| 993 | |||
| 994 | |||
| 995 | /** |
||
| 996 | * Returns the previous EE_Base_Class object in sequence from this object as found in the database |
||
| 997 | * matching the given query conditions. |
||
| 998 | * |
||
| 999 | * @param null $field_to_order_by What field is being used as the reference point. |
||
| 1000 | * @param array $query_params Any additional conditions on the query. |
||
| 1001 | * @param null $columns_to_select If left null, then an EE_Base_Class object is returned, otherwise |
||
| 1002 | * you can indicate just the column you want returned |
||
| 1003 | * @return array|EE_Base_Class |
||
| 1004 | * @throws \EE_Error |
||
| 1005 | */ |
||
| 1006 | View Code Duplication | public function previous($field_to_order_by = null, $query_params = array(), $columns_to_select = null) |
|
| 1018 | |||
| 1019 | |||
| 1020 | |||
| 1021 | /** |
||
| 1022 | * Overrides parent because parent expects old models. |
||
| 1023 | * This also doesn't do any validation, and won't work for serialized arrays |
||
| 1024 | * |
||
| 1025 | * @param string $field_name |
||
| 1026 | * @param mixed $field_value_from_db |
||
| 1027 | * @throws \EE_Error |
||
| 1028 | */ |
||
| 1029 | public function set_from_db($field_name, $field_value_from_db) |
||
| 1051 | |||
| 1052 | |||
| 1053 | |||
| 1054 | /** |
||
| 1055 | * verifies that the specified field is of the correct type |
||
| 1056 | * |
||
| 1057 | * @param string $field_name |
||
| 1058 | * @param string $extra_cache_ref This allows the user to specify an extra cache ref for the given property |
||
| 1059 | * (in cases where the same property may be used for different outputs |
||
| 1060 | * - i.e. datetime, money etc.) |
||
| 1061 | * @return mixed |
||
| 1062 | * @throws \EE_Error |
||
| 1063 | */ |
||
| 1064 | public function get($field_name, $extra_cache_ref = null) |
||
| 1068 | |||
| 1069 | |||
| 1070 | |||
| 1071 | /** |
||
| 1072 | * This method simply returns the RAW unprocessed value for the given property in this class |
||
| 1073 | * |
||
| 1074 | * @param string $field_name A valid fieldname |
||
| 1075 | * @return mixed Whatever the raw value stored on the property is. |
||
| 1076 | * @throws EE_Error if fieldSettings is misconfigured or the field doesn't exist. |
||
| 1077 | */ |
||
| 1078 | public function get_raw($field_name) |
||
| 1085 | |||
| 1086 | |||
| 1087 | |||
| 1088 | /** |
||
| 1089 | * This is used to return the internal DateTime object used for a field that is a |
||
| 1090 | * EE_Datetime_Field. |
||
| 1091 | * |
||
| 1092 | * @param string $field_name The field name retrieving the DateTime object. |
||
| 1093 | * @return mixed null | false | DateTime If the requested field is NOT a EE_Datetime_Field then |
||
| 1094 | * @throws \EE_Error |
||
| 1095 | * an error is set and false returned. If the field IS an |
||
| 1096 | * EE_Datetime_Field and but the field value is null, then |
||
| 1097 | * just null is returned (because that indicates that likely |
||
| 1098 | * this field is nullable). |
||
| 1099 | */ |
||
| 1100 | public function get_DateTime_object($field_name) |
||
| 1120 | |||
| 1121 | |||
| 1122 | |||
| 1123 | /** |
||
| 1124 | * Gets a Money object for the specified field. Please note that this should only be |
||
| 1125 | * used for fields corresponding to EE_Money_Fields, and it will always return a money object, |
||
| 1126 | * or else it will throw an exception. |
||
| 1127 | * |
||
| 1128 | * @param $field_name |
||
| 1129 | * @return mixed |
||
| 1130 | * @throws InvalidEntityException |
||
| 1131 | * @throws EE_Error |
||
| 1132 | */ |
||
| 1133 | public function getMoneyObject($field_name) |
||
| 1157 | |||
| 1158 | |||
| 1159 | |||
| 1160 | /** |
||
| 1161 | * To be used in template to immediately echo out the value, and format it for output. |
||
| 1162 | * Eg, should call stripslashes and whatnot before echoing |
||
| 1163 | * |
||
| 1164 | * @param string $field_name the name of the field as it appears in the DB |
||
| 1165 | * @param string $extra_cache_ref This allows the user to specify an extra cache ref for the given property |
||
| 1166 | * (in cases where the same property may be used for different outputs |
||
| 1167 | * - i.e. datetime, money etc.) |
||
| 1168 | * @return void |
||
| 1169 | * @throws \EE_Error |
||
| 1170 | */ |
||
| 1171 | public function e($field_name, $extra_cache_ref = null) |
||
| 1175 | |||
| 1176 | |||
| 1177 | |||
| 1178 | /** |
||
| 1179 | * Exactly like e(), echoes out the field, but sets its schema to 'form_input', so that it |
||
| 1180 | * can be easily used as the value of form input. |
||
| 1181 | * |
||
| 1182 | * @param string $field_name |
||
| 1183 | * @return void |
||
| 1184 | * @throws \EE_Error |
||
| 1185 | */ |
||
| 1186 | public function f($field_name) |
||
| 1190 | |||
| 1191 | |||
| 1192 | |||
| 1193 | /** |
||
| 1194 | * Gets a pretty view of the field's value. $extra_cache_ref can specify different formats for this. |
||
| 1195 | * The $extra_cache_ref will be passed to the model field's prepare_for_pretty_echoing, so consult the field's class |
||
| 1196 | * to see what options are available. |
||
| 1197 | * @param string $field_name |
||
| 1198 | * @param string $extra_cache_ref This allows the user to specify an extra cache ref for the given property |
||
| 1199 | * (in cases where the same property may be used for different outputs |
||
| 1200 | * - i.e. datetime, money etc.) |
||
| 1201 | * @return mixed |
||
| 1202 | * @throws \EE_Error |
||
| 1203 | */ |
||
| 1204 | public function get_pretty($field_name, $extra_cache_ref = null) |
||
| 1208 | |||
| 1209 | |||
| 1210 | |||
| 1211 | /** |
||
| 1212 | * This simply returns the datetime for the given field name |
||
| 1213 | * Note: this protected function is called by the wrapper get_date or get_time or get_datetime functions |
||
| 1214 | * (and the equivalent e_date, e_time, e_datetime). |
||
| 1215 | * |
||
| 1216 | * @access protected |
||
| 1217 | * @param string $field_name Field on the instantiated EE_Base_Class child object |
||
| 1218 | * @param string $dt_frmt valid datetime format used for date |
||
| 1219 | * (if '' then we just use the default on the field, |
||
| 1220 | * if NULL we use the last-used format) |
||
| 1221 | * @param string $tm_frmt Same as above except this is for time format |
||
| 1222 | * @param string $date_or_time if NULL then both are returned, otherwise "D" = only date and "T" = only time. |
||
| 1223 | * @param boolean $echo Whether the dtt is echoing using pretty echoing or just returned using vanilla get |
||
| 1224 | * @return string|bool|EE_Error string on success, FALSE on fail, or EE_Error Exception is thrown |
||
| 1225 | * if field is not a valid dtt field, or void if echoing |
||
| 1226 | * @throws \EE_Error |
||
| 1227 | */ |
||
| 1228 | protected function _get_datetime($field_name, $dt_frmt = '', $tm_frmt = '', $date_or_time = '', $echo = false) |
||
| 1241 | |||
| 1242 | |||
| 1243 | |||
| 1244 | /** |
||
| 1245 | * below are wrapper functions for the various datetime outputs that can be obtained for JUST returning the date |
||
| 1246 | * portion of a datetime value. (note the only difference between get_ and e_ is one returns the value and the |
||
| 1247 | * other echoes the pretty value for dtt) |
||
| 1248 | * |
||
| 1249 | * @param string $field_name name of model object datetime field holding the value |
||
| 1250 | * @param string $format format for the date returned (if NULL we use default in dt_frmt property) |
||
| 1251 | * @return string datetime value formatted |
||
| 1252 | * @throws \EE_Error |
||
| 1253 | */ |
||
| 1254 | public function get_date($field_name, $format = '') |
||
| 1258 | |||
| 1259 | |||
| 1260 | |||
| 1261 | /** |
||
| 1262 | * @param $field_name |
||
| 1263 | * @param string $format |
||
| 1264 | * @throws \EE_Error |
||
| 1265 | */ |
||
| 1266 | public function e_date($field_name, $format = '') |
||
| 1270 | |||
| 1271 | |||
| 1272 | |||
| 1273 | /** |
||
| 1274 | * below are wrapper functions for the various datetime outputs that can be obtained for JUST returning the time |
||
| 1275 | * portion of a datetime value. (note the only difference between get_ and e_ is one returns the value and the |
||
| 1276 | * other echoes the pretty value for dtt) |
||
| 1277 | * |
||
| 1278 | * @param string $field_name name of model object datetime field holding the value |
||
| 1279 | * @param string $format format for the time returned ( if NULL we use default in tm_frmt property) |
||
| 1280 | * @return string datetime value formatted |
||
| 1281 | * @throws \EE_Error |
||
| 1282 | */ |
||
| 1283 | public function get_time($field_name, $format = '') |
||
| 1287 | |||
| 1288 | |||
| 1289 | |||
| 1290 | /** |
||
| 1291 | * @param $field_name |
||
| 1292 | * @param string $format |
||
| 1293 | * @throws \EE_Error |
||
| 1294 | */ |
||
| 1295 | public function e_time($field_name, $format = '') |
||
| 1299 | |||
| 1300 | |||
| 1301 | |||
| 1302 | /** |
||
| 1303 | * below are wrapper functions for the various datetime outputs that can be obtained for returning the date AND |
||
| 1304 | * time portion of a datetime value. (note the only difference between get_ and e_ is one returns the value and the |
||
| 1305 | * other echoes the pretty value for dtt) |
||
| 1306 | * |
||
| 1307 | * @param string $field_name name of model object datetime field holding the value |
||
| 1308 | * @param string $dt_frmt format for the date returned (if NULL we use default in dt_frmt property) |
||
| 1309 | * @param string $tm_frmt format for the time returned (if NULL we use default in tm_frmt property) |
||
| 1310 | * @return string datetime value formatted |
||
| 1311 | * @throws \EE_Error |
||
| 1312 | */ |
||
| 1313 | public function get_datetime($field_name, $dt_frmt = '', $tm_frmt = '') |
||
| 1317 | |||
| 1318 | |||
| 1319 | |||
| 1320 | /** |
||
| 1321 | * @param string $field_name |
||
| 1322 | * @param string $dt_frmt |
||
| 1323 | * @param string $tm_frmt |
||
| 1324 | * @throws \EE_Error |
||
| 1325 | */ |
||
| 1326 | public function e_datetime($field_name, $dt_frmt = '', $tm_frmt = '') |
||
| 1330 | |||
| 1331 | |||
| 1332 | |||
| 1333 | /** |
||
| 1334 | * Get the i8ln value for a date using the WordPress @see date_i18n function. |
||
| 1335 | * |
||
| 1336 | * @param string $field_name The EE_Datetime_Field reference for the date being retrieved. |
||
| 1337 | * @param string $format PHP valid date/time string format. If none is provided then the internal set format |
||
| 1338 | * on the object will be used. |
||
| 1339 | * @return string Date and time string in set locale or false if no field exists for the given |
||
| 1340 | * @throws \EE_Error |
||
| 1341 | * field name. |
||
| 1342 | */ |
||
| 1343 | public function get_i18n_datetime($field_name, $format = '') |
||
| 1351 | |||
| 1352 | |||
| 1353 | |||
| 1354 | /** |
||
| 1355 | * This method validates whether the given field name is a valid field on the model object as well as it is of a |
||
| 1356 | * type EE_Datetime_Field. On success there will be returned the field settings. On fail an EE_Error exception is |
||
| 1357 | * thrown. |
||
| 1358 | * |
||
| 1359 | * @param string $field_name The field name being checked |
||
| 1360 | * @throws EE_Error |
||
| 1361 | * @return EE_Datetime_Field |
||
| 1362 | */ |
||
| 1363 | protected function _get_dtt_field_settings($field_name) |
||
| 1374 | |||
| 1375 | |||
| 1376 | |||
| 1377 | |||
| 1378 | /** |
||
| 1379 | * NOTE ABOUT BELOW: |
||
| 1380 | * These convenience date and time setters are for setting date and time independently. In other words you might |
||
| 1381 | * want to change the time on a datetime_field but leave the date the same (or vice versa). IF on the other hand |
||
| 1382 | * you want to set both date and time at the same time, you can just use the models default set($fieldname,$value) |
||
| 1383 | * method and make sure you send the entire datetime value for setting. |
||
| 1384 | */ |
||
| 1385 | /** |
||
| 1386 | * sets the time on a datetime property |
||
| 1387 | * |
||
| 1388 | * @access protected |
||
| 1389 | * @param string|Datetime $time a valid time string for php datetime functions (or DateTime object) |
||
| 1390 | * @param string $fieldname the name of the field the time is being set on (must match a EE_Datetime_Field) |
||
| 1391 | * @throws \EE_Error |
||
| 1392 | */ |
||
| 1393 | protected function _set_time_for($time, $fieldname) |
||
| 1397 | |||
| 1398 | |||
| 1399 | |||
| 1400 | /** |
||
| 1401 | * sets the date on a datetime property |
||
| 1402 | * |
||
| 1403 | * @access protected |
||
| 1404 | * @param string|DateTime $date a valid date string for php datetime functions ( or DateTime object) |
||
| 1405 | * @param string $fieldname the name of the field the date is being set on (must match a EE_Datetime_Field) |
||
| 1406 | * @throws \EE_Error |
||
| 1407 | */ |
||
| 1408 | protected function _set_date_for($date, $fieldname) |
||
| 1412 | |||
| 1413 | |||
| 1414 | |||
| 1415 | /** |
||
| 1416 | * This takes care of setting a date or time independently on a given model object property. This method also |
||
| 1417 | * verifies that the given fieldname matches a model object property and is for a EE_Datetime_Field field |
||
| 1418 | * |
||
| 1419 | * @access protected |
||
| 1420 | * @param string $what "T" for time, 'B' for both, 'D' for Date. |
||
| 1421 | * @param string|DateTime $datetime_value A valid Date or Time string (or DateTime object) |
||
| 1422 | * @param string $fieldname the name of the field the date OR time is being set on (must match a |
||
| 1423 | * EE_Datetime_Field property) |
||
| 1424 | * @throws \EE_Error |
||
| 1425 | */ |
||
| 1426 | protected function _set_date_time($what = 'T', $datetime_value, $fieldname) |
||
| 1451 | |||
| 1452 | |||
| 1453 | |||
| 1454 | /** |
||
| 1455 | * This will return a timestamp for the website timezone but ONLY when the current website timezone is different |
||
| 1456 | * than the timezone set for the website. NOTE, this currently only works well with methods that return values. If |
||
| 1457 | * you use it with methods that echo values the $_timestamp property may not get reset to its original value and |
||
| 1458 | * that could lead to some unexpected results! |
||
| 1459 | * |
||
| 1460 | * @access public |
||
| 1461 | * @param string $field_name This is the name of the field on the object that contains the date/time |
||
| 1462 | * value being returned. |
||
| 1463 | * @param string $callback must match a valid method in this class (defaults to get_datetime) |
||
| 1464 | * @param mixed (array|string) $args This is the arguments that will be passed to the callback. |
||
| 1465 | * @param string $prepend You can include something to prepend on the timestamp |
||
| 1466 | * @param string $append You can include something to append on the timestamp |
||
| 1467 | * @throws EE_Error |
||
| 1468 | * @return string timestamp |
||
| 1469 | */ |
||
| 1470 | public function display_in_my_timezone( |
||
| 1501 | |||
| 1502 | |||
| 1503 | |||
| 1504 | /** |
||
| 1505 | * Deletes this model object. |
||
| 1506 | * This calls the `EE_Base_Class::_delete` method. Child classes wishing to change default behaviour should |
||
| 1507 | * override |
||
| 1508 | * `EE_Base_Class::_delete` NOT this class. |
||
| 1509 | * |
||
| 1510 | * @return boolean | int |
||
| 1511 | * @throws \EE_Error |
||
| 1512 | */ |
||
| 1513 | public function delete() |
||
| 1537 | |||
| 1538 | |||
| 1539 | |||
| 1540 | /** |
||
| 1541 | * Calls the specific delete method for the instantiated class. |
||
| 1542 | * This method is called by the public `EE_Base_Class::delete` method. Any child classes desiring to override |
||
| 1543 | * default functionality for "delete" (which is to call `permanently_delete`) should override this method NOT |
||
| 1544 | * `EE_Base_Class::delete` |
||
| 1545 | * |
||
| 1546 | * @return bool|int |
||
| 1547 | * @throws \EE_Error |
||
| 1548 | */ |
||
| 1549 | protected function _delete() |
||
| 1553 | |||
| 1554 | |||
| 1555 | |||
| 1556 | /** |
||
| 1557 | * Deletes this model object permanently from db (but keep in mind related models my block the delete and return an |
||
| 1558 | * error) |
||
| 1559 | * |
||
| 1560 | * @return bool | int |
||
| 1561 | * @throws \EE_Error |
||
| 1562 | */ |
||
| 1563 | public function delete_permanently() |
||
| 1583 | |||
| 1584 | |||
| 1585 | |||
| 1586 | /** |
||
| 1587 | * When this model object is deleted, it may still be cached on related model objects. This clears the cache of |
||
| 1588 | * related model objects |
||
| 1589 | * |
||
| 1590 | * @throws \EE_Error |
||
| 1591 | */ |
||
| 1592 | public function refresh_cache_of_related_objects() |
||
| 1612 | |||
| 1613 | |||
| 1614 | |||
| 1615 | /** |
||
| 1616 | * Saves this object to the database. An array may be supplied to set some values on this |
||
| 1617 | * object just before saving. |
||
| 1618 | * |
||
| 1619 | * @access public |
||
| 1620 | * @param array $set_cols_n_values keys are field names, values are their new values, |
||
| 1621 | * if provided during the save() method (often client code will change the fields' |
||
| 1622 | * values before calling save) |
||
| 1623 | * @throws \EE_Error |
||
| 1624 | * @return int , 1 on a successful update, the ID of the new entry on insert; 0 on failure or if the model object |
||
| 1625 | * isn't allowed to persist (as determined by EE_Base_Class::allow_persist()) |
||
| 1626 | */ |
||
| 1627 | public function save($set_cols_n_values = array()) |
||
| 1737 | |||
| 1738 | |||
| 1739 | |||
| 1740 | /** |
||
| 1741 | * Updates the foreign key on related models objects pointing to this to have this model object's ID |
||
| 1742 | * as their foreign key. If the cached related model objects already exist in the db, saves them (so that the DB |
||
| 1743 | * is consistent) Especially useful in case we JUST added this model object ot the database and we want to let its |
||
| 1744 | * cached relations with foreign keys to it know about that change. Eg: we've created a transaction but haven't |
||
| 1745 | * saved it to the db. We also create a registration and don't save it to the DB, but we DO cache it on the |
||
| 1746 | * transaction. Now, when we save the transaction, the registration's TXN_ID will be automatically updated, whether |
||
| 1747 | * or not they exist in the DB (if they do, their DB records will be automatically updated) |
||
| 1748 | * |
||
| 1749 | * @return void |
||
| 1750 | * @throws \EE_Error |
||
| 1751 | */ |
||
| 1752 | protected function _update_cached_related_model_objs_fks() |
||
| 1769 | |||
| 1770 | |||
| 1771 | |||
| 1772 | /** |
||
| 1773 | * Saves this model object and its NEW cached relations to the database. |
||
| 1774 | * (Meaning, for now, IT DOES NOT WORK if the cached items already exist in the DB. |
||
| 1775 | * In order for that to work, we would need to mark model objects as dirty/clean... |
||
| 1776 | * because otherwise, there's a potential for infinite looping of saving |
||
| 1777 | * Saves the cached related model objects, and ensures the relation between them |
||
| 1778 | * and this object and properly setup |
||
| 1779 | * |
||
| 1780 | * @return int ID of new model object on save; 0 on failure+ |
||
| 1781 | * @throws \EE_Error |
||
| 1782 | */ |
||
| 1783 | public function save_new_cached_related_model_objs() |
||
| 1819 | |||
| 1820 | |||
| 1821 | |||
| 1822 | /** |
||
| 1823 | * for getting a model while instantiated. |
||
| 1824 | * |
||
| 1825 | * @return \EEM_Base | \EEM_CPT_Base |
||
| 1826 | */ |
||
| 1827 | public function get_model() |
||
| 1838 | |||
| 1839 | |||
| 1840 | |||
| 1841 | /** |
||
| 1842 | * @param $props_n_values |
||
| 1843 | * @param $classname |
||
| 1844 | * @return mixed bool|EE_Base_Class|EEM_CPT_Base |
||
| 1845 | * @throws \EE_Error |
||
| 1846 | */ |
||
| 1847 | protected static function _get_object_from_entity_mapper($props_n_values, $classname) |
||
| 1857 | |||
| 1858 | |||
| 1859 | |||
| 1860 | /** |
||
| 1861 | * This is called by child static "new_instance" method and we'll check to see if there is an existing db entry for |
||
| 1862 | * the primary key (if present in incoming values). If there is a key in the incoming array that matches the |
||
| 1863 | * primary key for the model AND it is not null, then we check the db. If there's a an object we return it. If not |
||
| 1864 | * we return false. |
||
| 1865 | * |
||
| 1866 | * @param array $props_n_values incoming array of properties and their values |
||
| 1867 | * @param string $classname the classname of the child class |
||
| 1868 | * @param null $timezone |
||
| 1869 | * @param array $date_formats incoming date_formats in an array where the first value is the |
||
| 1870 | * date_format and the second value is the time format |
||
| 1871 | * @return mixed (EE_Base_Class|bool) |
||
| 1872 | * @throws \EE_Error |
||
| 1873 | */ |
||
| 1874 | protected static function _check_for_object($props_n_values, $classname, $timezone = null, $date_formats = array()) |
||
| 1911 | |||
| 1912 | |||
| 1913 | |||
| 1914 | /** |
||
| 1915 | * Gets the EEM_*_Model for this class |
||
| 1916 | * |
||
| 1917 | * @access public now, as this is more convenient |
||
| 1918 | * @param $classname |
||
| 1919 | * @param null $timezone |
||
| 1920 | * @throws EE_Error |
||
| 1921 | * @return EEM_Base |
||
| 1922 | */ |
||
| 1923 | protected static function _get_model($classname, $timezone = null) |
||
| 1940 | |||
| 1941 | |||
| 1942 | |||
| 1943 | /** |
||
| 1944 | * Gets the model instance (eg instance of EEM_Attendee) given its classname (eg EE_Attendee) |
||
| 1945 | * |
||
| 1946 | * @param string $model_classname |
||
| 1947 | * @param null $timezone |
||
| 1948 | * @return EEM_Base |
||
| 1949 | */ |
||
| 1950 | protected static function _get_model_instance_with_name($model_classname, $timezone = null) |
||
| 1957 | |||
| 1958 | |||
| 1959 | |||
| 1960 | /** |
||
| 1961 | * If a model name is provided (eg Registration), gets the model classname for that model. |
||
| 1962 | * Also works if a model class's classname is provided (eg EE_Registration). |
||
| 1963 | * |
||
| 1964 | * @param null $model_name |
||
| 1965 | * @return string like EEM_Attendee |
||
| 1966 | */ |
||
| 1967 | private static function _get_model_classname($model_name = null) |
||
| 1976 | |||
| 1977 | |||
| 1978 | |||
| 1979 | /** |
||
| 1980 | * returns the name of the primary key attribute |
||
| 1981 | * |
||
| 1982 | * @param null $classname |
||
| 1983 | * @throws EE_Error |
||
| 1984 | * @return string |
||
| 1985 | */ |
||
| 1986 | protected static function _get_primary_key_name($classname = null) |
||
| 1998 | |||
| 1999 | |||
| 2000 | |||
| 2001 | /** |
||
| 2002 | * Gets the value of the primary key. |
||
| 2003 | * If the object hasn't yet been saved, it should be whatever the model field's default was |
||
| 2004 | * (eg, if this were the EE_Event class, look at the primary key field on EEM_Event and see what its default value |
||
| 2005 | * is. Usually defaults for integer primary keys are 0; string primary keys are usually NULL). |
||
| 2006 | * |
||
| 2007 | * @return mixed, if the primary key is of type INT it'll be an int. Otherwise it could be a string |
||
| 2008 | * @throws \EE_Error |
||
| 2009 | */ |
||
| 2010 | public function ID() |
||
| 2020 | |||
| 2021 | |||
| 2022 | |||
| 2023 | /** |
||
| 2024 | * Adds a relationship to the specified EE_Base_Class object, given the relationship's name. Eg, if the current |
||
| 2025 | * model is related to a group of events, the $relationName should be 'Event', and should be a key in the EE |
||
| 2026 | * Model's $_model_relations array. If this model object doesn't exist in the DB, just caches the related thing |
||
| 2027 | * |
||
| 2028 | * @param mixed $otherObjectModelObjectOrID EE_Base_Class or the ID of the other object |
||
| 2029 | * @param string $relationName eg 'Events','Question',etc. |
||
| 2030 | * an attendee to a group, you also want to specify which role they |
||
| 2031 | * will have in that group. So you would use this parameter to |
||
| 2032 | * specify array('role-column-name'=>'role-id') |
||
| 2033 | * @param array $extra_join_model_fields_n_values You can optionally include an array of key=>value pairs that |
||
| 2034 | * allow you to further constrict the relation to being added. |
||
| 2035 | * However, keep in mind that the columns (keys) given must match a |
||
| 2036 | * column on the JOIN table and currently only the HABTM models |
||
| 2037 | * accept these additional conditions. Also remember that if an |
||
| 2038 | * exact match isn't found for these extra cols/val pairs, then a |
||
| 2039 | * NEW row is created in the join table. |
||
| 2040 | * @param null $cache_id |
||
| 2041 | * @throws EE_Error |
||
| 2042 | * @return EE_Base_Class the object the relation was added to |
||
| 2043 | */ |
||
| 2044 | public function _add_relation_to( |
||
| 2088 | |||
| 2089 | |||
| 2090 | |||
| 2091 | /** |
||
| 2092 | * Removes a relationship to the specified EE_Base_Class object, given the relationships' name. Eg, if the current |
||
| 2093 | * model is related to a group of events, the $relationName should be 'Events', and should be a key in the EE |
||
| 2094 | * Model's $_model_relations array. If this model object doesn't exist in the DB, just removes the related thing |
||
| 2095 | * from the cache |
||
| 2096 | * |
||
| 2097 | * @param mixed $otherObjectModelObjectOrID |
||
| 2098 | * EE_Base_Class or the ID of the other object, OR an array key into the cache if this isn't saved |
||
| 2099 | * to the DB yet |
||
| 2100 | * @param string $relationName |
||
| 2101 | * @param array $where_query |
||
| 2102 | * You can optionally include an array of key=>value pairs that allow you to further constrict the |
||
| 2103 | * relation to being added. However, keep in mind that the columns (keys) given must match a column |
||
| 2104 | * on the JOIN table and currently only the HABTM models accept these additional conditions. Also |
||
| 2105 | * remember that if an exact match isn't found for these extra cols/val pairs, then a NEW row is |
||
| 2106 | * created in the join table. |
||
| 2107 | * @return EE_Base_Class the relation was removed from |
||
| 2108 | * @throws \EE_Error |
||
| 2109 | */ |
||
| 2110 | public function _remove_relation_to($otherObjectModelObjectOrID, $relationName, $where_query = array()) |
||
| 2127 | |||
| 2128 | |||
| 2129 | |||
| 2130 | /** |
||
| 2131 | * Removes ALL the related things for the $relationName. |
||
| 2132 | * |
||
| 2133 | * @param string $relationName |
||
| 2134 | * @param array $where_query_params like EEM_Base::get_all's $query_params[0] (where conditions) |
||
| 2135 | * @return EE_Base_Class |
||
| 2136 | * @throws \EE_Error |
||
| 2137 | */ |
||
| 2138 | public function _remove_relations($relationName, $where_query_params = array()) |
||
| 2155 | |||
| 2156 | |||
| 2157 | |||
| 2158 | /** |
||
| 2159 | * Gets all the related model objects of the specified type. Eg, if the current class if |
||
| 2160 | * EE_Event, you could call $this->get_many_related('Registration') to get an array of all the |
||
| 2161 | * EE_Registration objects which related to this event. Note: by default, we remove the "default query params" |
||
| 2162 | * because we want to get even deleted items etc. |
||
| 2163 | * |
||
| 2164 | * @param string $relationName key in the model's _model_relations array |
||
| 2165 | * @param array $query_params like EEM_Base::get_all |
||
| 2166 | * @return EE_Base_Class[] Results not necessarily indexed by IDs, because some results might not have primary keys |
||
| 2167 | * @throws \EE_Error |
||
| 2168 | * or might not be saved yet. Consider using EEM_Base::get_IDs() on these results if |
||
| 2169 | * you want IDs |
||
| 2170 | */ |
||
| 2171 | public function get_many_related($relationName, $query_params = array()) |
||
| 2198 | |||
| 2199 | |||
| 2200 | |||
| 2201 | /** |
||
| 2202 | * Instead of getting the related model objects, simply counts them. Ignores default_where_conditions by default, |
||
| 2203 | * unless otherwise specified in the $query_params |
||
| 2204 | * |
||
| 2205 | * @param string $relation_name model_name like 'Event', or 'Registration' |
||
| 2206 | * @param array $query_params like EEM_Base::get_all's |
||
| 2207 | * @param string $field_to_count name of field to count by. By default, uses primary key |
||
| 2208 | * @param bool $distinct if we want to only count the distinct values for the column then you can trigger |
||
| 2209 | * that by the setting $distinct to TRUE; |
||
| 2210 | * @return int |
||
| 2211 | */ |
||
| 2212 | public function count_related($relation_name, $query_params = array(), $field_to_count = null, $distinct = false) |
||
| 2216 | |||
| 2217 | |||
| 2218 | |||
| 2219 | /** |
||
| 2220 | * Instead of getting the related model objects, simply sums up the values of the specified field. |
||
| 2221 | * Note: ignores default_where_conditions by default, unless otherwise specified in the $query_params |
||
| 2222 | * |
||
| 2223 | * @param string $relation_name model_name like 'Event', or 'Registration' |
||
| 2224 | * @param array $query_params like EEM_Base::get_all's |
||
| 2225 | * @param string $field_to_sum name of field to count by. |
||
| 2226 | * By default, uses primary key (which doesn't make much sense, so you should probably |
||
| 2227 | * change it) |
||
| 2228 | * @return int |
||
| 2229 | */ |
||
| 2230 | public function sum_related($relation_name, $query_params = array(), $field_to_sum = null) |
||
| 2234 | |||
| 2235 | |||
| 2236 | |||
| 2237 | /** |
||
| 2238 | * Gets the first (ie, one) related model object of the specified type. |
||
| 2239 | * |
||
| 2240 | * @param string $relationName key in the model's _model_relations array |
||
| 2241 | * @param array $query_params like EEM_Base::get_all |
||
| 2242 | * @return EE_Base_Class (not an array, a single object) |
||
| 2243 | * @throws \EE_Error |
||
| 2244 | */ |
||
| 2245 | public function get_first_related($relationName, $query_params = array()) |
||
| 2281 | |||
| 2282 | |||
| 2283 | |||
| 2284 | /** |
||
| 2285 | * Does a delete on all related objects of type $relationName and removes |
||
| 2286 | * the current model object's relation to them. If they can't be deleted (because |
||
| 2287 | * of blocking related model objects) does nothing. If the related model objects are |
||
| 2288 | * soft-deletable, they will be soft-deleted regardless of related blocking model objects. |
||
| 2289 | * If this model object doesn't exist yet in the DB, just removes its related things |
||
| 2290 | * |
||
| 2291 | * @param string $relationName |
||
| 2292 | * @param array $query_params like EEM_Base::get_all's |
||
| 2293 | * @return int how many deleted |
||
| 2294 | * @throws \EE_Error |
||
| 2295 | */ |
||
| 2296 | View Code Duplication | public function delete_related($relationName, $query_params = array()) |
|
| 2306 | |||
| 2307 | |||
| 2308 | |||
| 2309 | /** |
||
| 2310 | * Does a hard delete (ie, removes the DB row) on all related objects of type $relationName and removes |
||
| 2311 | * the current model object's relation to them. If they can't be deleted (because |
||
| 2312 | * of blocking related model objects) just does a soft delete on it instead, if possible. |
||
| 2313 | * If the related thing isn't a soft-deletable model object, this function is identical |
||
| 2314 | * to delete_related(). If this model object doesn't exist in the DB, just remove its related things |
||
| 2315 | * |
||
| 2316 | * @param string $relationName |
||
| 2317 | * @param array $query_params like EEM_Base::get_all's |
||
| 2318 | * @return int how many deleted (including those soft deleted) |
||
| 2319 | * @throws \EE_Error |
||
| 2320 | */ |
||
| 2321 | View Code Duplication | public function delete_related_permanently($relationName, $query_params = array()) |
|
| 2331 | |||
| 2332 | |||
| 2333 | |||
| 2334 | /** |
||
| 2335 | * is_set |
||
| 2336 | * Just a simple utility function children can use for checking if property exists |
||
| 2337 | * |
||
| 2338 | * @access public |
||
| 2339 | * @param string $field_name property to check |
||
| 2340 | * @return bool TRUE if existing,FALSE if not. |
||
| 2341 | */ |
||
| 2342 | public function is_set($field_name) |
||
| 2346 | |||
| 2347 | |||
| 2348 | |||
| 2349 | /** |
||
| 2350 | * Just a simple utility function children can use for checking if property (or properties) exists and throwing an |
||
| 2351 | * EE_Error exception if they don't |
||
| 2352 | * |
||
| 2353 | * @param mixed (string|array) $properties properties to check |
||
| 2354 | * @throws EE_Error |
||
| 2355 | * @return bool TRUE if existing, throw EE_Error if not. |
||
| 2356 | */ |
||
| 2357 | protected function _property_exists($properties) |
||
| 2375 | |||
| 2376 | |||
| 2377 | |||
| 2378 | /** |
||
| 2379 | * This simply returns an array of model fields for this object |
||
| 2380 | * |
||
| 2381 | * @return array |
||
| 2382 | * @throws \EE_Error |
||
| 2383 | */ |
||
| 2384 | public function model_field_array() |
||
| 2394 | |||
| 2395 | |||
| 2396 | |||
| 2397 | /** |
||
| 2398 | * Very handy general function to allow for plugins to extend any child of EE_Base_Class. |
||
| 2399 | * If a method is called on a child of EE_Base_Class that doesn't exist, this function is called |
||
| 2400 | * (http://www.garfieldtech.com/blog/php-magic-call) and passed the method's name and arguments. Instead of |
||
| 2401 | * requiring a plugin to extend the EE_Base_Class (which works fine is there's only 1 plugin, but when will that |
||
| 2402 | * happen?) they can add a hook onto 'filters_hook_espresso__{className}__{methodName}' (eg, |
||
| 2403 | * filters_hook_espresso__EE_Answer__my_great_function) and accepts 2 arguments: the object on which the function |
||
| 2404 | * was called, and an array of the original arguments passed to the function. Whatever their callback function |
||
| 2405 | * returns will be returned by this function. Example: in functions.php (or in a plugin): |
||
| 2406 | * add_filter('FHEE__EE_Answer__my_callback','my_callback',10,3); function |
||
| 2407 | * my_callback($previousReturnValue,EE_Base_Class $object,$argsArray){ |
||
| 2408 | * $returnString= "you called my_callback! and passed args:".implode(",",$argsArray); |
||
| 2409 | * return $previousReturnValue.$returnString; |
||
| 2410 | * } |
||
| 2411 | * require('EE_Answer.class.php'); |
||
| 2412 | * $answer= EE_Answer::new_instance(array('REG_ID' => 2,'QST_ID' => 3,'ANS_value' => The answer is 42')); |
||
| 2413 | * echo $answer->my_callback('monkeys',100); |
||
| 2414 | * //will output "you called my_callback! and passed args:monkeys,100" |
||
| 2415 | * |
||
| 2416 | * @param string $methodName name of method which was called on a child of EE_Base_Class, but which |
||
| 2417 | * @param array $args array of original arguments passed to the function |
||
| 2418 | * @throws EE_Error |
||
| 2419 | * @return mixed whatever the plugin which calls add_filter decides |
||
| 2420 | */ |
||
| 2421 | public function __call($methodName, $args) |
||
| 2440 | |||
| 2441 | |||
| 2442 | |||
| 2443 | /** |
||
| 2444 | * Similar to insert_post_meta, adds a record in the Extra_Meta model's table with the given key and value. |
||
| 2445 | * A $previous_value can be specified in case there are many meta rows with the same key |
||
| 2446 | * |
||
| 2447 | * @param string $meta_key |
||
| 2448 | * @param mixed $meta_value |
||
| 2449 | * @param mixed $previous_value |
||
| 2450 | * @return bool|int # of records updated (or BOOLEAN if we actually ended up inserting the extra meta row) |
||
| 2451 | * @throws \EE_Error |
||
| 2452 | * NOTE: if the values haven't changed, returns 0 |
||
| 2453 | */ |
||
| 2454 | public function update_extra_meta($meta_key, $meta_value, $previous_value = null) |
||
| 2475 | |||
| 2476 | |||
| 2477 | |||
| 2478 | /** |
||
| 2479 | * Adds a new extra meta record. If $unique is set to TRUE, we'll first double-check |
||
| 2480 | * no other extra meta for this model object have the same key. Returns TRUE if the |
||
| 2481 | * extra meta row was entered, false if not |
||
| 2482 | * |
||
| 2483 | * @param string $meta_key |
||
| 2484 | * @param mixed $meta_value |
||
| 2485 | * @param boolean $unique |
||
| 2486 | * @return boolean |
||
| 2487 | * @throws \EE_Error |
||
| 2488 | */ |
||
| 2489 | public function add_extra_meta($meta_key, $meta_value, $unique = false) |
||
| 2516 | |||
| 2517 | |||
| 2518 | |||
| 2519 | /** |
||
| 2520 | * Deletes all the extra meta rows for this record as specified by key. If $meta_value |
||
| 2521 | * is specified, only deletes extra meta records with that value. |
||
| 2522 | * |
||
| 2523 | * @param string $meta_key |
||
| 2524 | * @param mixed $meta_value |
||
| 2525 | * @return int number of extra meta rows deleted |
||
| 2526 | * @throws \EE_Error |
||
| 2527 | */ |
||
| 2528 | public function delete_extra_meta($meta_key, $meta_value = null) |
||
| 2542 | |||
| 2543 | |||
| 2544 | |||
| 2545 | /** |
||
| 2546 | * Gets the extra meta with the given meta key. If you specify "single" we just return 1, otherwise |
||
| 2547 | * an array of everything found. Requires that this model actually have a relation of type EE_Has_Many_Any_Relation. |
||
| 2548 | * You can specify $default is case you haven't found the extra meta |
||
| 2549 | * |
||
| 2550 | * @param string $meta_key |
||
| 2551 | * @param boolean $single |
||
| 2552 | * @param mixed $default if we don't find anything, what should we return? |
||
| 2553 | * @return mixed single value if $single; array if ! $single |
||
| 2554 | * @throws \EE_Error |
||
| 2555 | */ |
||
| 2556 | public function get_extra_meta($meta_key, $single = false, $default = null) |
||
| 2584 | |||
| 2585 | |||
| 2586 | |||
| 2587 | /** |
||
| 2588 | * Returns a simple array of all the extra meta associated with this model object. |
||
| 2589 | * If $one_of_each_key is true (Default), it will be an array of simple key-value pairs, keys being the |
||
| 2590 | * extra meta's key, and teh value being its value. However, if there are duplicate extra meta rows with |
||
| 2591 | * the same key, only one will be used. (eg array('foo'=>'bar','monkey'=>123)) |
||
| 2592 | * If $one_of_each_key is false, it will return an array with the top-level keys being |
||
| 2593 | * the extra meta keys, but their values are also arrays, which have the extra-meta's ID as their sub-key, and |
||
| 2594 | * finally the extra meta's value as each sub-value. (eg |
||
| 2595 | * array('foo'=>array(1=>'bar',2=>'bill'),'monkey'=>array(3=>123))) |
||
| 2596 | * |
||
| 2597 | * @param boolean $one_of_each_key |
||
| 2598 | * @return array |
||
| 2599 | * @throws \EE_Error |
||
| 2600 | */ |
||
| 2601 | public function all_extra_meta_array($one_of_each_key = true) |
||
| 2624 | |||
| 2625 | |||
| 2626 | |||
| 2627 | /** |
||
| 2628 | * Gets a pretty nice displayable nice for this model object. Often overridden |
||
| 2629 | * |
||
| 2630 | * @return string |
||
| 2631 | * @throws \EE_Error |
||
| 2632 | */ |
||
| 2633 | public function name() |
||
| 2649 | |||
| 2650 | |||
| 2651 | |||
| 2652 | /** |
||
| 2653 | * in_entity_map |
||
| 2654 | * Checks if this model object has been proven to already be in the entity map |
||
| 2655 | * |
||
| 2656 | * @return boolean |
||
| 2657 | * @throws \EE_Error |
||
| 2658 | */ |
||
| 2659 | public function in_entity_map() |
||
| 2668 | |||
| 2669 | |||
| 2670 | |||
| 2671 | /** |
||
| 2672 | * refresh_from_db |
||
| 2673 | * Makes sure the fields and values on this model object are in-sync with what's in the database. |
||
| 2674 | * |
||
| 2675 | * @throws EE_Error if this model object isn't in the entity mapper (because then you should |
||
| 2676 | * just use what's in the entity mapper and refresh it) and WP_DEBUG is TRUE |
||
| 2677 | */ |
||
| 2678 | public function refresh_from_db() |
||
| 2700 | |||
| 2701 | |||
| 2702 | |||
| 2703 | /** |
||
| 2704 | * Because some other plugins, like Advanced Cron Manager, expect all objects to have this method |
||
| 2705 | * (probably a bad assumption they have made, oh well) |
||
| 2706 | * |
||
| 2707 | * @return string |
||
| 2708 | */ |
||
| 2709 | public function __toString() |
||
| 2718 | |||
| 2719 | |||
| 2720 | |||
| 2721 | /** |
||
| 2722 | * Clear related model objects if they're already in the DB, because otherwise when we |
||
| 2723 | * UN-serialize this model object we'll need to be careful to add them to the entity map. |
||
| 2724 | * This means if we have made changes to those related model objects, and want to unserialize |
||
| 2725 | * the this model object on a subsequent request, changes to those related model objects will be lost. |
||
| 2726 | * Instead, those related model objects should be directly serialized and stored. |
||
| 2727 | * Eg, the following won't work: |
||
| 2728 | * $reg = EEM_Registration::instance()->get_one_by_ID( 123 ); |
||
| 2729 | * $att = $reg->attendee(); |
||
| 2730 | * $att->set( 'ATT_fname', 'Dirk' ); |
||
| 2731 | * update_option( 'my_option', serialize( $reg ) ); |
||
| 2732 | * //END REQUEST |
||
| 2733 | * //START NEXT REQUEST |
||
| 2734 | * $reg = get_option( 'my_option' ); |
||
| 2735 | * $reg->attendee()->save(); |
||
| 2736 | * And would need to be replace with: |
||
| 2737 | * $reg = EEM_Registration::instance()->get_one_by_ID( 123 ); |
||
| 2738 | * $att = $reg->attendee(); |
||
| 2739 | * $att->set( 'ATT_fname', 'Dirk' ); |
||
| 2740 | * update_option( 'my_option', serialize( $reg ) ); |
||
| 2741 | * //END REQUEST |
||
| 2742 | * //START NEXT REQUEST |
||
| 2743 | * $att = get_option( 'my_option' ); |
||
| 2744 | * $att->save(); |
||
| 2745 | * |
||
| 2746 | * @return array |
||
| 2747 | * @throws \EE_Error |
||
| 2748 | */ |
||
| 2749 | public function __sleep() |
||
| 2769 | |||
| 2770 | |||
| 2771 | |||
| 2772 | /** |
||
| 2773 | * restore _props_n_values_provided_in_constructor |
||
| 2774 | * PLZ NOTE: this will reset the array to whatever fields values were present prior to serialization, |
||
| 2775 | * and therefore should NOT be used to determine if state change has occurred since initial construction. |
||
| 2776 | * At best, you would only be able to detect if state change has occurred during THIS request. |
||
| 2777 | */ |
||
| 2778 | public function __wakeup() |
||
| 2782 | |||
| 2783 | |||
| 2784 | |||
| 2785 | } |
||
| 2786 | |||
| 2788 |
Loading history...
This check marks implicit conversions of arrays to boolean values in a comparison. While in PHP an empty array is considered to be equal (but not identical) to false, this is not always apparent.
Consider making the comparison explicit by using
empty(..)or! empty(...)instead.