Core_Read_Interface.php
2 weeks ago
Decorator.php
2 weeks ago
Filter_Validation.php
2 weeks ago
Formatter_Interface.php
2 weeks ago
Implementation_Error.php
2 weeks ago
Interface.php
2 weeks ago
Query_Filters.php
2 weeks ago
Read_Interface.php
2 weeks ago
Setter_Interface.php
2 weeks ago
Update_Interface.php
2 weeks ago
Usage_Error.php
2 weeks ago
Void_Query_Exception.php
2 weeks ago
Usage_Error.php
305 lines
| 1 | <?php |
| 2 | |
| 3 | /** |
| 4 | * Class Tribe__Repository__Usage_Error |
| 5 | * |
| 6 | * @since 4.7.19 |
| 7 | * |
| 8 | * Thrown to indicate an error in the repository usage by a developer; this |
| 9 | * is meant to be used to help developers to use the repository. |
| 10 | */ |
| 11 | class Tribe__Repository__Usage_Error extends Exception { |
| 12 | |
| 13 | /** |
| 14 | * Do not ally dynamic set of properties on the repository; protected |
| 15 | * properties are read-only. |
| 16 | * |
| 17 | * @since 4.7.19 |
| 18 | * |
| 19 | * @param string $name The name of the property the client code is trying to set. |
| 20 | * @param Tribe__Repository__Interface $object The instance of the repository. |
| 21 | * |
| 22 | * @return Tribe__Repository__Usage_Error A ready to throw instance of the class. |
| 23 | */ |
| 24 | public static function because_properties_should_be_set_correctly( $name, $object ) { |
| 25 | $class = get_class( $object ); |
| 26 | |
| 27 | return new self( "Property {$name} should be set with a setter method, injected in the constructor and/or defined in an extending class." ); |
| 28 | } |
| 29 | |
| 30 | /** |
| 31 | * Clearly indicate that a filter is not defined on the repository in use. |
| 32 | * |
| 33 | * This is to allow for more clear comprehension of errors related to |
| 34 | * missing filters. |
| 35 | * |
| 36 | * @since 4.7.19 |
| 37 | * |
| 38 | * @param string $key The filter the client code is trying to use. |
| 39 | * @param Tribe__Repository__Interface $object The instance of the repository. |
| 40 | * |
| 41 | * @return Tribe__Repository__Usage_Error A ready to throw instance of the class. |
| 42 | */ |
| 43 | public static function because_the_read_filter_is_not_defined( $key, $object ) { |
| 44 | $class = get_class( $object ); |
| 45 | |
| 46 | return new self( "The class {$class} does not define a {$key} read filter: either implement it or try to use the provided filters." ); |
| 47 | } |
| 48 | |
| 49 | /** |
| 50 | * Indicates that a property is not defined on the repository. |
| 51 | * |
| 52 | * @since 4.7.19 |
| 53 | * |
| 54 | * @param string $name The name of the property the client code is trying to read. |
| 55 | * @param Tribe__Repository__Interface $object |
| 56 | * |
| 57 | * @return Tribe__Repository__Usage_Error A ready to throw instance of the class. |
| 58 | */ |
| 59 | public static function because_property_is_not_defined( $name, $object ) { |
| 60 | $class = get_class( $object ); |
| 61 | |
| 62 | return new self( "The {$class} class does not define a {$name} property; add it by decorating or extending this class." ); |
| 63 | } |
| 64 | |
| 65 | /** |
| 66 | * Indicates that a field cannot be updated by the repository class. |
| 67 | * |
| 68 | * @since 4.7.19 |
| 69 | * |
| 70 | * @param string $key |
| 71 | * @param Tribe__Repository__Update_Interface $object |
| 72 | * |
| 73 | * @return Tribe__Repository__Usage_Error A ready to throw instance of the class. |
| 74 | */ |
| 75 | public static function because_this_field_cannot_be_updated( $key, $object ) { |
| 76 | $class = get_class( $object ); |
| 77 | |
| 78 | return new self( "The {$class} class does not allow updating the {$key} field; allow it by decorating or extending this class." ); |
| 79 | } |
| 80 | |
| 81 | /** |
| 82 | * "Sugar" method to correct a typo in a public method name. |
| 83 | * Indicates that the `set` method of the Update repository is being used incorrectly. |
| 84 | * |
| 85 | * @since 4.12.6 |
| 86 | * |
| 87 | * @TODO: perhaps we should deprecate this at some point? |
| 88 | * |
| 89 | * @param Tribe__Repository__Update_Interface $object |
| 90 | * |
| 91 | * @return Tribe__Repository__Usage_Error A ready to throw instance of the class. |
| 92 | */ |
| 93 | public static function because_udpate_key_should_be_a_string( $object ) { |
| 94 | return self::because_update_key_should_be_a_string( $object ); |
| 95 | } |
| 96 | |
| 97 | /** |
| 98 | * Indicates that the `set` method of the Update repository is being used incorrectly. |
| 99 | * |
| 100 | * @since 4.7.19 |
| 101 | * |
| 102 | * @param Tribe__Repository__Update_Interface $object |
| 103 | * |
| 104 | * @return Tribe__Repository__Usage_Error A ready to throw instance of the class. |
| 105 | */ |
| 106 | public static function because_update_key_should_be_a_string( $object ) { |
| 107 | $class = get_class( $object ); |
| 108 | |
| 109 | return new self( 'The key used in the `set` method should be a string; if you want to set multiple fields at once use the `set_args` method.' ); |
| 110 | } |
| 111 | |
| 112 | /** |
| 113 | * Indicates that the client code is trying to use a single comparison operator with multiple values. |
| 114 | * |
| 115 | * @since 4.7.19 |
| 116 | * |
| 117 | * @param string|array $key |
| 118 | * @param array $value |
| 119 | * @param string $compare |
| 120 | * @param mixed $object |
| 121 | * |
| 122 | * @return Tribe__Repository__Usage_Error A ready to throw instance of the class. |
| 123 | */ |
| 124 | public static function because_single_value_comparisons_should_be_used_with_one_value( $key, array $value, $compare, $object ) { |
| 125 | $class = get_class( $object ); |
| 126 | $keys = is_array( $key ) ? implode( ', ', $key ) : $key; |
| 127 | $values = implode( ', ', $value ); |
| 128 | |
| 129 | return new self( "You are trying to use a single SQL comparison operator ({$compare}) with multiple values; [ keys: {$keys}, values: {$values}]." ); |
| 130 | } |
| 131 | |
| 132 | /** |
| 133 | * Indicates that the client code is calling the query building method without |
| 134 | * providing all the arguments the comparison operator requires. |
| 135 | * |
| 136 | * @since 4.7.19 |
| 137 | * |
| 138 | * @param string|array $key |
| 139 | * @param string $compare |
| 140 | * @param mixed $object |
| 141 | * |
| 142 | * @return Tribe__Repository__Usage_Error A ready to throw instance of the class. |
| 143 | */ |
| 144 | public static function because_this_comparison_operator_requires_fields_and_values( $key, $compare, $object ) { |
| 145 | $class = get_class( $object ); |
| 146 | $keys = is_array( $key ) ? implode( ', ', $key ) : $key; |
| 147 | |
| 148 | return new self( "You are trying to use a SQL comparison operator ({$compare}) that requires fields and values [ keys: {$keys}]." ); |
| 149 | } |
| 150 | |
| 151 | /** |
| 152 | * Indicates that the client code is using an high-level filtering method while |
| 153 | * trying to build a WHERE OR clause. |
| 154 | * |
| 155 | * @param array array $method |
| 156 | * @param mixed $object |
| 157 | * |
| 158 | * @return Tribe__Repository__Usage_Error A ready to throw instance of the class. |
| 159 | */ |
| 160 | public static function because_where_or_should_only_be_used_with_methods_that_add_where_clauses( array $method, $object ) { |
| 161 | $class = get_class( $object ); |
| 162 | $method = json_encode( $method ); |
| 163 | |
| 164 | return new self( "You are trying to build a WHERE OR clause using a method ({$class}::{$method}) that does not call the Tribe__Repository__Query_Filters::where method directly; call `where_clause` directly or call methods that call it." ); |
| 165 | } |
| 166 | |
| 167 | /** |
| 168 | * Indicates that the client code is trying to use a wpdb::prepare format with |
| 169 | * a regular `meta_query`. |
| 170 | * |
| 171 | * @param string|array $key |
| 172 | * @param string $type_or_format |
| 173 | * |
| 174 | * @return Tribe__Repository__Usage_Error A ready to throw instance of the class. |
| 175 | */ |
| 176 | public static function because_the_type_is_a_wpdb_prepare_format( $key, $type_or_format ) { |
| 177 | $keys = is_array( $key ) ? implode( ', ', $key ) : $key; |
| 178 | |
| 179 | return new self( "You are trying to use a `wpdb::prepare` format ({$type_or_format}) with a regular meta_query [ keys: {$keys}]." ); |
| 180 | } |
| 181 | |
| 182 | /** |
| 183 | * Indicates that the client code is trying to use a wpdb::prepare format with |
| 184 | * a regular `meta_query`. |
| 185 | * |
| 186 | * @param string|array $key |
| 187 | * @param string $type_or_format |
| 188 | * |
| 189 | * @return Tribe__Repository__Usage_Error A ready to throw instance of the class. |
| 190 | */ |
| 191 | public static function because_the_format_is_not_a_wpdb_prepare_one( $key, $type_or_format ) { |
| 192 | $keys = is_array( $key ) ? implode( ', ', $key ) : $key; |
| 193 | |
| 194 | return new self( "You are trying to use a format ({$type_or_format}) that is not a valid `wpdb::prepare` one with a query [ keys: {$keys}]." ); |
| 195 | } |
| 196 | |
| 197 | /** |
| 198 | * Indicates that the client code is trying to use a comparison operator not supported by a specific filter. |
| 199 | * |
| 200 | * @since 4.9.5 |
| 201 | * |
| 202 | * @param string $operator The not supported comparison operator. |
| 203 | * @param string $filter The filter in which the client code is trying to use the current operator. |
| 204 | * |
| 205 | * @return Tribe__Repository__Usage_Error A ready to throw instance of the class. |
| 206 | */ |
| 207 | public static function because_this_comparison_operator_is_not_supported( $operator, $filter ) { |
| 208 | return new self( "You are trying to use a comparison operator ({$operator}) that is not supported by this filter ({$filter})" ); |
| 209 | } |
| 210 | |
| 211 | /** |
| 212 | * Indicates that the client code is trying to use a comparison operator that requires a value of a specific type |
| 213 | * wrong. |
| 214 | * |
| 215 | * @since 4.9.5 |
| 216 | * |
| 217 | * @param string $operator The operator the client code is using. |
| 218 | * @param string $filter The filter the client code is using. |
| 219 | * @param string $type The required value type for this operator and this filter. |
| 220 | * |
| 221 | * @return Tribe__Repository__Usage_Error A ready to throw instance of the class. |
| 222 | */ |
| 223 | public static function because_this_comparison_operator_requires_an_value_of_type( $operator, $filter, $type ) { |
| 224 | return new self( "You are trying to use a comparison operator ({$operator}) in the filter {$filter} that requires a value of type {$type}." ); |
| 225 | } |
| 226 | |
| 227 | /** |
| 228 | * Indicates that the client code is trying to use a comparison operator that is not valid.. |
| 229 | * |
| 230 | * @since 4.9.6 |
| 231 | * |
| 232 | * @param string $operator The not supported comparison operator. |
| 233 | * |
| 234 | * @return Tribe__Repository__Usage_Error A ready to throw instance of the class. |
| 235 | */ |
| 236 | public static function because_this_comparison_operator_is_not_valid( $operator ) { |
| 237 | return new self( "You are trying to use a comparison operator ({$operator}) that is not valid." ); |
| 238 | } |
| 239 | |
| 240 | /** |
| 241 | * Indicates that the client code is trying to use a relation that is not valid.. |
| 242 | * |
| 243 | * @since 4.9.6 |
| 244 | * |
| 245 | * @param string $relation The not supported relation. |
| 246 | * |
| 247 | * @return Tribe__Repository__Usage_Error A ready to throw instance of the class. |
| 248 | */ |
| 249 | public static function because_this_relation_is_not_valid( $relation ) { |
| 250 | return new self( "You are trying to use a relation ({$relation}) that is not valid." ); |
| 251 | } |
| 252 | |
| 253 | /** |
| 254 | * Indicates that the client code is trying to set a query on the repository after the query ran. |
| 255 | * |
| 256 | * @since 4.9.9 |
| 257 | * |
| 258 | * @return Tribe__Repository__Usage_Error A ready to throw instance of the class. |
| 259 | */ |
| 260 | public static function because_query_cannot_be_set_after_it_ran() { |
| 261 | return new self( "You are trying to set the repository query after it ran!" ); |
| 262 | } |
| 263 | |
| 264 | /** |
| 265 | * Indicates the client code is trying to call a filter without the correct number of req. parameters. |
| 266 | * |
| 267 | * @since 4.10.2 |
| 268 | * |
| 269 | * @param string $filter The called filter. |
| 270 | * @param array $required_args The human-readable name of the required arguments. |
| 271 | * |
| 272 | * @return static A ready to throw instance of the class. |
| 273 | */ |
| 274 | public static function because_filter_requires_args( $filter, array $required_args ) { |
| 275 | return new static( |
| 276 | sprintf( |
| 277 | 'The "%s" filter requires %d arguments: %s', |
| 278 | $filter, |
| 279 | count( $required_args ), |
| 280 | implode( ', ', $required_args ) |
| 281 | ) |
| 282 | ); |
| 283 | } |
| 284 | |
| 285 | /** |
| 286 | * Indicates the client code is trying to call a filter with an invalid parameter. |
| 287 | * |
| 288 | * @since 4.10.2 |
| 289 | * |
| 290 | * @param string $filter The called filter. |
| 291 | * @param string $arg_name The human-readable name of the parameter. |
| 292 | * |
| 293 | * @return static A ready to throw instance of the class. |
| 294 | */ |
| 295 | public static function because_filter_arg_is_not_valid( $filter, $arg_name ) { |
| 296 | return new static( |
| 297 | sprintf( |
| 298 | 'The "%s" filter "%s" argument is not valid.', |
| 299 | $filter, |
| 300 | $arg_name |
| 301 | ) |
| 302 | ); |
| 303 | } |
| 304 | } |
| 305 |