Incentive.php
356 lines
| 1 | <?php |
| 2 | declare( strict_types=1 ); |
| 3 | |
| 4 | namespace Automattic\WooCommerce\Internal\Admin\Suggestions\Incentives; |
| 5 | |
| 6 | /** |
| 7 | * Abstract class for payment extension suggestion incentive provider classes. |
| 8 | * |
| 9 | * Caching derived store-context values |
| 10 | * |
| 11 | * Providers cache the store-context values they derive, since deriving them costs DB |
| 12 | * queries. A value cached beyond a single request outlives the logic that derived it, so |
| 13 | * correcting that logic later doesn't reach the stores already holding a value - unless |
| 14 | * the cache expires, or the value records which version of the logic produced it. |
| 15 | * |
| 16 | * Transients get this from their expiration. `WooPayments::has_wcpay()` caches in an |
| 17 | * option instead, and pairs it with a second option holding the logic version, re-deriving |
| 18 | * a value an older version produced. Its logic only ever narrows what qualifies, so it |
| 19 | * skips re-deriving a cached `no` - a shortcut that doesn't carry over to logic that |
| 20 | * widens what qualifies, or to a value richer than yes/no. |
| 21 | * |
| 22 | * That pairing also lets the WooPayments plugin, which writes the same value option from |
| 23 | * its own copy of the logic, ship before or after core. |
| 24 | */ |
| 25 | abstract class Incentive { |
| 26 | const PREFIX = 'woocommerce_admin_pes_incentive_'; |
| 27 | |
| 28 | /** |
| 29 | * The user meta name for storing dismissed incentives. |
| 30 | * |
| 31 | * @var string |
| 32 | */ |
| 33 | protected string $dismissed_meta_name = self::PREFIX . 'dismissed'; |
| 34 | |
| 35 | /** |
| 36 | * The suggestion ID this incentive provider is for. |
| 37 | * |
| 38 | * @var string |
| 39 | */ |
| 40 | protected string $suggestion_id; |
| 41 | |
| 42 | /** |
| 43 | * Constructor. |
| 44 | * |
| 45 | * @param string $suggestion_id The suggestion ID this incentive provider is for. |
| 46 | */ |
| 47 | public function __construct( string $suggestion_id ) { |
| 48 | $this->suggestion_id = $suggestion_id; |
| 49 | } |
| 50 | |
| 51 | /** |
| 52 | * Get the details of all the incentives. |
| 53 | * |
| 54 | * The incentives are filtered based on the country code, incentive type, if provided, and their visibility. |
| 55 | * |
| 56 | * @param string $country_code The business location country code to get incentives for. |
| 57 | * @param string $incentive_type Optional. The type of incentive to check for. |
| 58 | * |
| 59 | * @return array The incentives list with details for each incentive. |
| 60 | */ |
| 61 | public function get_all( string $country_code, string $incentive_type = '' ): array { |
| 62 | $incentives = array_filter( |
| 63 | $this->get_incentives( $country_code ), |
| 64 | fn( $incentive ) => $this->validate_incentive( $incentive ) |
| 65 | ); |
| 66 | |
| 67 | if ( ! empty( $incentive_type ) ) { |
| 68 | $incentives = array_filter( |
| 69 | $incentives, |
| 70 | function ( $incentive ) use ( $incentive_type ) { |
| 71 | return $incentive['type'] === $incentive_type; |
| 72 | } |
| 73 | ); |
| 74 | } |
| 75 | |
| 76 | return array_values( $incentives ); |
| 77 | } |
| 78 | |
| 79 | /** |
| 80 | * Get an incentive by promo ID. |
| 81 | * |
| 82 | * The incentives are filtered based on the country code, incentive type, if provided, and their visibility. |
| 83 | * |
| 84 | * @param string $promo_id The incentive promo ID. |
| 85 | * @param string $country_code The business location country code to get incentives for. |
| 86 | * @param string $incentive_type Optional. The type of incentive to search for. |
| 87 | * |
| 88 | * @return ?array The incentive details. Returns null if there is no incentive available. |
| 89 | */ |
| 90 | public function get_by_promo_id( string $promo_id, string $country_code, string $incentive_type = '' ): ?array { |
| 91 | $incentives = array_filter( |
| 92 | $this->get_all( $country_code, $incentive_type ), |
| 93 | function ( $incentive ) use ( $promo_id ) { |
| 94 | return $incentive['promo_id'] === $promo_id; |
| 95 | } |
| 96 | ); |
| 97 | |
| 98 | if ( empty( $incentives ) ) { |
| 99 | return null; |
| 100 | } |
| 101 | |
| 102 | // Get the first found incentive, in the unlikely case there are multiple incentives with the same promo ID. |
| 103 | return reset( $incentives ); |
| 104 | } |
| 105 | |
| 106 | /** |
| 107 | * Get an incentive by ID. |
| 108 | * |
| 109 | * The incentives are filtered based on the country code, incentive type, if provided, and their visibility. |
| 110 | * |
| 111 | * @param string $incentive_id The incentive ID. |
| 112 | * @param string $country_code The business location country code to get incentives for. |
| 113 | * |
| 114 | * @return ?array The incentive details. Returns null if there is no incentive available. |
| 115 | */ |
| 116 | public function get_by_id( string $incentive_id, string $country_code ): ?array { |
| 117 | $incentives = array_filter( |
| 118 | $this->get_all( $country_code ), |
| 119 | function ( $incentive ) use ( $incentive_id ) { |
| 120 | return $incentive['id'] === $incentive_id; |
| 121 | } |
| 122 | ); |
| 123 | |
| 124 | if ( empty( $incentives ) ) { |
| 125 | return null; |
| 126 | } |
| 127 | |
| 128 | // Get the first found incentive, in the unlikely case there are multiple incentives with the same ID. |
| 129 | return reset( $incentives ); |
| 130 | } |
| 131 | |
| 132 | /** |
| 133 | * Check if an incentive should be visible. |
| 134 | * |
| 135 | * @param string $id The incentive ID to check for visibility. |
| 136 | * @param string $country_code The business location country code to get incentives for. |
| 137 | * @param bool $skip_extension_active_check Whether to skip the check for the extension plugin being active. |
| 138 | * |
| 139 | * @return boolean Whether the incentive should be visible. |
| 140 | */ |
| 141 | public function is_visible( string $id, string $country_code, bool $skip_extension_active_check = false ): bool { |
| 142 | // The extension plugin must not be active, unless we are asked to skip the check. |
| 143 | if ( ! $skip_extension_active_check && $this->is_extension_active() ) { |
| 144 | return false; |
| 145 | } |
| 146 | |
| 147 | // The current WP user must have the required capabilities. |
| 148 | if ( ! $this->user_has_caps() ) { |
| 149 | return false; |
| 150 | } |
| 151 | |
| 152 | // An incentive must be available. |
| 153 | if ( empty( $this->get_by_id( $id, $country_code ) ) ) { |
| 154 | return false; |
| 155 | } |
| 156 | |
| 157 | // If the incentive has been dismissed in all contexts, don't show it. |
| 158 | // We don't know the full list of contexts, so we can't assume anything beyond `all`. |
| 159 | if ( $this->is_dismissed( $id, 'all' ) ) { |
| 160 | return false; |
| 161 | } |
| 162 | |
| 163 | return true; |
| 164 | } |
| 165 | |
| 166 | /** |
| 167 | * Dismiss an incentive. |
| 168 | * |
| 169 | * @param string $id The incentive ID to dismiss. |
| 170 | * @param string $context Optional. The context ID in which the incentive is dismissed. |
| 171 | * This can be used to dismiss the same incentive in different contexts. |
| 172 | * If no context ID is provided, the incentive will be dismissed for all contexts. |
| 173 | * @param ?int $timestamp Optional The timestamp when the incentive was dismissed. |
| 174 | * Defaults to the current time. |
| 175 | * |
| 176 | * @return bool True if the incentive was not previously dismissed and now it is. |
| 177 | * False if the incentive was already dismissed, or we failed to persist the dismissal data. |
| 178 | */ |
| 179 | public function dismiss( string $id, string $context = 'all', ?int $timestamp = null ): bool { |
| 180 | // If it is already dismissed, don't dismiss it again. |
| 181 | if ( $this->is_dismissed( $id, $context ) ) { |
| 182 | return false; |
| 183 | } |
| 184 | |
| 185 | $all_dismissed_incentives = $this->get_all_dismissed_incentives(); |
| 186 | if ( empty( $all_dismissed_incentives[ $this->suggestion_id ] ) ) { |
| 187 | $all_dismissed_incentives[ $this->suggestion_id ] = array(); |
| 188 | ksort( $all_dismissed_incentives ); |
| 189 | } |
| 190 | |
| 191 | $all_dismissed_incentives[ $this->suggestion_id ][] = array( |
| 192 | 'id' => $id, |
| 193 | 'context' => $context, |
| 194 | 'timestamp' => $timestamp ?? time(), |
| 195 | ); |
| 196 | |
| 197 | /** |
| 198 | * Fires when a payments extension suggestion incentive is dismissed. |
| 199 | * |
| 200 | * @param string $id The incentive ID. |
| 201 | * @param string $suggestion_id The suggestion ID the incentive belongs to. |
| 202 | * @param string $context The context ID in which the incentive is dismissed. |
| 203 | * Defaults to 'all'. |
| 204 | * |
| 205 | * @since 9.9.0 |
| 206 | */ |
| 207 | do_action( 'woocommerce_admin_payments_extension_suggestion_incentive_dismissed', $id, $this->suggestion_id, $context ); |
| 208 | |
| 209 | return $this->save_all_dismissed_incentives( $all_dismissed_incentives ); |
| 210 | } |
| 211 | |
| 212 | /** |
| 213 | * Check if an incentive has been manually dismissed. |
| 214 | * |
| 215 | * @param string $id The incentive ID to check for dismissal. |
| 216 | * @param string $context Optional. The context ID in which to check for dismissal. |
| 217 | * If no context ID is provided, we check for dismissal in all contexts. |
| 218 | * |
| 219 | * @return boolean Whether the incentive has been manually dismissed. |
| 220 | */ |
| 221 | public function is_dismissed( string $id, string $context = '' ): bool { |
| 222 | if ( empty( $id ) ) { |
| 223 | return false; |
| 224 | } |
| 225 | |
| 226 | $all_dismissed_incentives = $this->get_all_dismissed_incentives(); |
| 227 | |
| 228 | // If there are no dismissed incentives for the suggestion, return early. |
| 229 | $dismissed_incentives = $all_dismissed_incentives[ $this->suggestion_id ] ?? array(); |
| 230 | if ( empty( $dismissed_incentives ) ) { |
| 231 | return false; |
| 232 | } |
| 233 | |
| 234 | // Check if the incentive is dismissed in the given context. |
| 235 | if ( in_array( |
| 236 | $id, |
| 237 | array_column( |
| 238 | array_filter( |
| 239 | $dismissed_incentives, |
| 240 | // All context dismissals are always included. |
| 241 | fn( $dismissed_incentive ) => 'all' === $dismissed_incentive['context'] || $context === $dismissed_incentive['context'] |
| 242 | ), |
| 243 | 'id' |
| 244 | ), |
| 245 | true |
| 246 | ) ) { |
| 247 | return true; |
| 248 | } |
| 249 | |
| 250 | return false; |
| 251 | } |
| 252 | |
| 253 | /** |
| 254 | * Get the dismissals (contexts) for an incentive. |
| 255 | * |
| 256 | * @param string $id The incentive ID. |
| 257 | * |
| 258 | * @return array The contexts in which the incentive has been dismissed. |
| 259 | */ |
| 260 | public function get_dismissals( string $id ): array { |
| 261 | $all_dismissed_incentives = $this->get_all_dismissed_incentives(); |
| 262 | |
| 263 | // If there are no dismissed incentives for the suggestion, return early. |
| 264 | $dismissed_incentives = $all_dismissed_incentives[ $this->suggestion_id ] ?? array(); |
| 265 | if ( empty( $dismissed_incentives ) ) { |
| 266 | return array(); |
| 267 | } |
| 268 | |
| 269 | $dismissals = array_values( |
| 270 | array_filter( |
| 271 | $dismissed_incentives, |
| 272 | fn( $dismissed_incentive ) => $id === $dismissed_incentive['id'] |
| 273 | ) |
| 274 | ); |
| 275 | |
| 276 | return array_map( |
| 277 | fn( $dismissed_incentive ) => array( |
| 278 | 'timestamp' => $dismissed_incentive['timestamp'], |
| 279 | 'context' => $dismissed_incentive['context'], |
| 280 | ), |
| 281 | $dismissals |
| 282 | ); |
| 283 | } |
| 284 | |
| 285 | /** |
| 286 | * Get all the dismissed incentives grouped by suggestion. |
| 287 | * |
| 288 | * @return array The dismissed incentives grouped by suggestion. |
| 289 | */ |
| 290 | protected function get_all_dismissed_incentives(): array { |
| 291 | $all_dismissed_incentives = get_user_meta( get_current_user_id(), $this->dismissed_meta_name, true ); |
| 292 | if ( empty( $all_dismissed_incentives ) ) { |
| 293 | $all_dismissed_incentives = array(); |
| 294 | } |
| 295 | |
| 296 | return $all_dismissed_incentives; |
| 297 | } |
| 298 | |
| 299 | /** |
| 300 | * Save all the dismissed incentives list. |
| 301 | * |
| 302 | * @param array $dismissed_incentives The dismissed incentives data. |
| 303 | * |
| 304 | * @return bool Whether the dismissed incentives were saved successfully. |
| 305 | */ |
| 306 | protected function save_all_dismissed_incentives( array $dismissed_incentives ): bool { |
| 307 | return (bool) update_user_meta( get_current_user_id(), $this->dismissed_meta_name, $dismissed_incentives ); |
| 308 | } |
| 309 | |
| 310 | /** |
| 311 | * Check if the current user has the required capabilities to view incentives. |
| 312 | * |
| 313 | * @return bool Whether the current user has the required capabilities view incentives. |
| 314 | */ |
| 315 | protected function user_has_caps(): bool { |
| 316 | return current_user_can( 'manage_woocommerce' ); |
| 317 | } |
| 318 | |
| 319 | /** |
| 320 | * Validate an incentive details. |
| 321 | * |
| 322 | * It will check if the incentive details have the required keys. |
| 323 | * |
| 324 | * @param array $incentive The incentive details. |
| 325 | * |
| 326 | * @return bool Whether the incentive data is valid. |
| 327 | */ |
| 328 | protected function validate_incentive( array $incentive ): bool { |
| 329 | // The incentive must have an ID, a promo ID, and a type. |
| 330 | $required_keys = array( 'id', 'promo_id', 'type' ); |
| 331 | foreach ( $required_keys as $key ) { |
| 332 | if ( empty( $incentive[ $key ] ) ) { |
| 333 | return false; |
| 334 | } |
| 335 | } |
| 336 | |
| 337 | return true; |
| 338 | } |
| 339 | |
| 340 | /** |
| 341 | * Check if the corresponding extension suggestion plugin is active. |
| 342 | * |
| 343 | * @return boolean Whether the corresponding extension suggestion plugin is active. |
| 344 | */ |
| 345 | abstract protected function is_extension_active(): bool; |
| 346 | |
| 347 | /** |
| 348 | * Get eligible incentives. |
| 349 | * |
| 350 | * @param string $country_code The business location country code to get incentives for. |
| 351 | * |
| 352 | * @return array List of eligible incentives. |
| 353 | */ |
| 354 | abstract protected function get_incentives( string $country_code ): array; |
| 355 | } |
| 356 |