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