> */ public function fields() { return array( array( 'id' => 'amount', 'type' => 'number', 'label' => __( 'Orders from', 'admin-powerups-for-woocommerce' ), /* translators: %s: currency code. */ 'description' => sprintf( __( 'Order total, including tax and shipping, in %s.', 'admin-powerups-for-woocommerce' ), function_exists( 'get_woocommerce_currency' ) ? get_woocommerce_currency() : '' ), 'default' => 500, 'min' => 0, 'step' => 'any', ), array( 'id' => 'highlight', 'type' => 'toggle', 'label' => __( 'Highlight in the Orders list', 'admin-powerups-for-woocommerce' ), 'description' => __( 'Adds a “High value” badge next to the order number.', 'admin-powerups-for-woocommerce' ), 'default' => true, ), array( 'id' => 'recipients', 'type' => 'text', 'label' => __( 'Email when paid', 'admin-powerups-for-woocommerce' ), /* translators: %s: site admin email. */ 'description' => sprintf( __( 'Comma-separated addresses. Empty = %s. Sent once per order. Wording and on/off: WooCommerce → Settings → Emails → High-value order.', 'admin-powerups-for-woocommerce' ), get_option( 'admin_email' ) ), 'default' => '', ), ); } /** * Sanitize a setting. Recipients keep valid addresses only; a value that isn't text keeps the * saved recipients. * * @since 1.0.0 * @param array $field Field schema. * @param mixed $value Raw value. * @return mixed */ protected function sanitize_field( array $field, $value ) { if ( 'recipients' === $field['id'] ) { if ( ! is_string( $value ) ) { return $this->recipients(); } $emails = array_filter( array_map( 'sanitize_email', array_map( 'trim', explode( ',', $value ) ) ), 'is_email' ); return implode( ', ', array_unique( $emails ) ); } if ( 'amount' === $field['id'] ) { return is_numeric( $value ) && is_finite( (float) $value ) ? max( 0, (float) $value ) : $field['default']; } return parent::sanitize_field( $field, $value ); } /** * {@inheritDoc} * * @return array> */ public function data() { return array_merge( parent::data(), array( Cleanup::option( 'email-settings', self::EMAIL_SETTINGS, __( 'Email wording', 'admin-powerups-for-woocommerce' ), __( 'Subject, heading and on/off for the High-value order email (WooCommerce → Settings → Emails).', 'admin-powerups-for-woocommerce' ), 'settings' ), Cleanup::order_meta( 'alerted', self::SENT, __( 'Alert sent markers', 'admin-powerups-for-woocommerce' ), __( 'Marks orders whose alert went out, so it isn’t sent twice. Deleting them lets a paid order alert again if its status changes.', 'admin-powerups-for-woocommerce' ) ), array( 'id' => 'alert-locks', 'kind' => 'cache', 'label' => __( 'Alert locks', 'admin-powerups-for-woocommerce' ), 'description' => __( 'Short-lived rows that stop two requests sending the same alert. Only left behind if a request stopped half way.', 'admin-powerups-for-woocommerce' ), 'count' => array( self::class, 'count_locks' ), 'delete' => array( self::class, 'delete_locks' ), ), ) ); } /** * {@inheritDoc} WooCommerce reads the email's settings each time it builds the mailer: make * sure they exist and are autoloaded while the power-up is on, so that costs no query. */ public function activate() { if ( false === get_option( self::EMAIL_SETTINGS ) ) { add_option( self::EMAIL_SETTINGS, array( 'enabled' => 'yes' ), '', true ); } else { wp_set_option_autoload( self::EMAIL_SETTINGS, true ); } } /** * {@inheritDoc} The email's settings autoload only while the power-up is on (the registry * flips them, also when WooCommerce is below the minimum version and no activate() runs). */ public function autoload_options() { return array( self::EMAIL_SETTINGS ); } /** * {@inheritDoc} */ public function deactivate() { wp_set_option_autoload( self::EMAIL_SETTINGS, false ); } /** * {@inheritDoc} */ public function boot() { add_filter( 'woocommerce_email_classes', array( $this, 'register_email' ) ); add_filter( 'apwc_resendable_emails', array( $this, 'resendable' ) ); add_action( 'woocommerce_payment_complete', array( $this, 'paid' ) ); add_action( 'woocommerce_order_status_processing', array( $this, 'paid' ) ); add_action( 'woocommerce_order_status_completed', array( $this, 'paid' ) ); if ( is_admin() ) { add_filter( 'woocommerce_shop_order_list_table_order_css_classes', array( $this, 'row_classes' ), 10, 2 ); add_action( 'woocommerce_shop_order_list_table_custom_column', array( $this, 'hpos_badge' ), 10, 2 ); add_filter( 'post_class', array( $this, 'legacy_row_classes' ), 10, 3 ); add_action( 'manage_shop_order_posts_custom_column', array( $this, 'legacy_badge' ), 20, 2 ); add_action( 'admin_enqueue_scripts', array( $this, 'enqueue' ) ); } } /** * Saved recipients (comma-separated; empty = site admin email). * * @since 1.0.0 * @return string */ public function recipients() { $recipients = $this->setting( 'recipients' ); return is_string( $recipients ) ? $recipients : ''; } /** * Register the email with WooCommerce. The only place the Email class is loaded: WC_Email * exists by now (this filter runs while WooCommerce builds its mailer). * * @since 1.0.0 * @param array $emails Email classes. * @return array */ public function register_email( $emails ) { $email = new Email(); $email->apwc_recipients_source = fn() => $this->recipients(); $emails['APWC_High_Value_Order'] = $email; return $emails; } /** * It can be resent from the order screen and the Email log. * * @since 1.0.0 * @param string[] $ids Email IDs. * @return string[] */ public function resendable( $ids ) { $ids[] = self::EMAIL_ID; return $ids; } /** * Whether an order is high value. * * @since 1.0.0 * @param WC_Order $order Order. * @return bool */ public function is_high_value( WC_Order $order ) { // The amount is in the store currency; orders in another currency (multi-currency plugins) // aren't compared unless a filter converts them. $high = (float) $this->setting( 'amount' ) > 0 && $order->get_currency() === get_woocommerce_currency() && (float) $order->get_total() >= (float) $this->setting( 'amount' ); /** * Filter whether an order counts as high value (badge and email). Orders in a currency other * than the store's are false by default: convert and compare here if you need them. * * @since 1.0.0 * @param bool $high High value. * @param WC_Order $order Order. */ return (bool) apply_filters( 'apwc_high_value_order', $high, $order ); } /** * An order was paid: send the alert once. * * @since 1.0.0 * @param int $order_id Order ID. * @return void */ public function paid( $order_id ) { $order = wc_get_order( $order_id ); if ( ! $order instanceof WC_Order || 'shop_order' !== $order->get_type() || $order->get_meta( self::SENT ) || ! $order->is_paid() || ! $this->is_high_value( $order ) ) { return; } // Claim the order atomically first: a gateway webhook and the shopper's return can run these // hooks at the same moment in two requests. Only one of them gets the lock (Support\Lock: // INSERT IGNORE); a lock left by a request that died is taken over after LOCK_TTL seconds. $lock = self::LOCK_PREFIX . $order->get_id(); $value = Lock::acquire( $lock, self::LOCK_TTL ); if ( '' === $value ) { return; } // The lock only lives while one request marks the order. A request that loaded the order // before that finished still sees no marker, and would get the (released) lock: check the // marker in the database, past the order object and its cache. if ( $this->sent_marker_saved( $order->get_id() ) ) { Lock::release( $lock, $value ); return; } $order->update_meta_data( self::SENT, (string) time() ); $order->save_meta_data(); Lock::release( $lock, $value ); $email = WooEmails::get( self::EMAIL_ID ); $sent = $email instanceof Email && $email->trigger( $order, $this->recipients() ); if ( $sent ) { $order->add_order_note( /* translators: %s: recipients. */ sprintf( __( 'High-value order alert sent to %s.', 'admin-powerups-for-woocommerce' ), $email->get_recipient() ) ); } /** * Fires when a paid order is found to be high value (once per order). * * @since 1.0.0 * @param WC_Order $order Order. * @param bool $sent Whether the email went out. */ do_action( 'apwc_high_value_order_paid', $order, $sent ); } /** * Whether the "alert sent" marker is saved for an order, read straight from the order meta * table (never from a cached order). * * @since 1.0.0 * @param int $order_id Order ID. * @return bool */ private function sent_marker_saved( int $order_id ): bool { global $wpdb; if ( Orders::hpos() ) { $table = OrderUtil::get_table_for_order_meta(); $column = 'order_id'; } else { $table = $wpdb->postmeta; $column = 'post_id'; } // phpcs:ignore WordPress.DB.DirectDatabaseQuery -- must bypass the order cache (race check). $found = $wpdb->get_var( $wpdb->prepare( "SELECT 1 FROM %i WHERE %i = %d AND meta_key = %s AND meta_value <> '' LIMIT 1", $table, $column, $order_id, self::SENT ) ); return null !== $found; } /** * How many alert lock rows are stored (Data section). * * @since 1.0.0 * @return int */ public static function count_locks(): int { global $wpdb; return (int) $wpdb->get_var( $wpdb->prepare( 'SELECT COUNT(*) FROM %i WHERE option_name LIKE %s', $wpdb->options, $wpdb->esc_like( self::LOCK_PREFIX ) . '%' ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery -- counts raw lock rows; never cached. } /** * Delete a batch of alert lock rows (Data section, uninstall). * * @since 1.0.0 * @return int How many are left. */ public static function delete_locks(): int { global $wpdb; $wpdb->query( $wpdb->prepare( 'DELETE FROM %i WHERE option_name LIKE %s LIMIT %d', $wpdb->options, $wpdb->esc_like( self::LOCK_PREFIX ) . '%', Cleanup::BATCH ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery -- removes raw lock rows; never cached. return self::count_locks(); } /** * Row class on the HPOS Orders list. * * @since 1.0.0 * @param string[] $classes Classes. * @param WC_Order $order Order. * @return string[] */ public function row_classes( $classes, $order ) { if ( $order instanceof WC_Order && $this->setting( 'highlight' ) && $this->is_high_value( $order ) ) { $classes[] = 'apwc-high-value'; } return $classes; } /** * Badge on the HPOS Orders list, whatever the screen ID (WooCommerce can serve the list as * `admin_page_wc-orders`). This action fires before WooCommerce prints the order number, so * the badge waits for the screen's column action that follows it in the same cell. * * @since 1.0.0 * @param string $column Column. * @param WC_Order $order Order. * @return void */ public function hpos_badge( $column, $order ) { if ( 'order_number' !== $column ) { return; } $screen = function_exists( 'get_current_screen' ) ? get_current_screen() : null; if ( ! $screen ) { $this->badge( $column, $order ); return; } $hook = 'manage_' . $screen->id . '_custom_column'; $after = function () use ( &$after, $hook, $column, $order ) { remove_action( $hook, $after, 20 ); $this->badge( $column, $order ); }; add_action( $hook, $after, 20 ); } /** * Badge after the order number. * * @since 1.0.0 * @param string $column Column. * @param WC_Order $order Order. * @return void */ public function badge( $column, $order ) { if ( 'order_number' === $column && $order instanceof WC_Order && $this->setting( 'highlight' ) && $this->is_high_value( $order ) ) { printf( '%s', esc_html__( 'High value', 'admin-powerups-for-woocommerce' ) ); } } /** * Row class on the legacy (posts) Orders list. * * @since 1.0.0 * @param string[] $classes Classes. * @param string[] $css Extra classes. * @param int $post_id Post ID. * @return string[] */ public function legacy_row_classes( $classes, $css, $post_id ) { if ( 'shop_order' !== get_post_type( $post_id ) || ! $this->setting( 'highlight' ) ) { return $classes; } $order = wc_get_order( $post_id ); // Already cached by the list table. return $order ? $this->row_classes( $classes, $order ) : $classes; } /** * Badge after the order number (legacy list). * * @since 1.0.0 * @param string $column Column. * @param int $post_id Post ID. * @return void */ public function legacy_badge( $column, $post_id ) { if ( 'order_number' === $column ) { $this->badge( $column, wc_get_order( $post_id ) ); } } /** * Badge styles on the Orders list. * * @since 1.0.0 * @return void */ public function enqueue() { if ( Screen::is_order_list() && $this->setting( 'highlight' ) ) { wp_enqueue_style( 'apwc-modules', Assets::url( 'assets/css/modules.css' ), array(), Assets::ver( 'assets/css/modules.css' ) ); } } }