are missing entries (registered payment gateways, suggestions, offline PMs, etc.), they will be added. * Various rules will be enforced (e.g., offline PMs and their relation with the offline PMs group). * * @param array $order_map The payment providers order map. * * @return array The updated payment providers order map. */ public function enhance_order_map( array $order_map ): array { // We don't exclude shells here, because we need to get the order of all the registered payment gateways. $payment_gateways = $this->get_payment_gateways( false ); // Make it a list keyed by the payment gateway ID. $payment_gateways = array_combine( array_map( fn( $gateway ) => $gateway->id, $payment_gateways ), $payment_gateways ); // Get the payment gateways order map. $payment_gateways_order_map = array_flip( array_keys( $payment_gateways ) ); // Get the payment gateways to suggestions map. $payment_gateways_to_suggestions_map = array_map( fn( $gateway ) => $this->extension_suggestions->get_by_plugin_slug( Utils::normalize_plugin_slug( $this->get_payment_gateway_plugin_slug( $gateway ) ) ), $payment_gateways ); /* * Initialize the order map with the current ordering. */ if ( empty( $order_map ) ) { $order_map = $payment_gateways_order_map; } $order_map = Utils::order_map_normalize( $order_map ); $handled_suggestion_ids = array(); /* * Go through the registered gateways and add any missing ones. */ // Use a map to keep track of the insertion offset for each suggestion ID. // We need this so we can place multiple PGs matching a suggestion right after it but maintain their relative order. $suggestion_order_map_id_to_offset_map = array(); foreach ( $payment_gateways_order_map as $id => $order ) { if ( isset( $order_map[ $id ] ) ) { continue; } // If there is a suggestion entry matching this payment gateway, // we will add the payment gateway right after it so gateways pop-up in place of matching suggestions. // We rely on suggestions and matching registered PGs being mutually exclusive in the UI. if ( ! empty( $payment_gateways_to_suggestions_map[ $id ] ) ) { $suggestion_id = $payment_gateways_to_suggestions_map[ $id ]['id']; $suggestion_order_map_id = $this->get_suggestion_order_map_id( $suggestion_id ); if ( isset( $order_map[ $suggestion_order_map_id ] ) ) { // Determine the offset for placing missing PGs after this suggestion. if ( ! isset( $suggestion_order_map_id_to_offset_map[ $suggestion_order_map_id ] ) ) { $suggestion_order_map_id_to_offset_map[ $suggestion_order_map_id ] = 0; } $suggestion_order_map_id_to_offset_map[ $suggestion_order_map_id ] += 1; // Place the missing payment gateway right after the suggestion, // with an offset to maintain relative order between multiple PGs matching the same suggestion. $order_map = Utils::order_map_place_at_order( $order_map, $id, $order_map[ $suggestion_order_map_id ] + $suggestion_order_map_id_to_offset_map[ $suggestion_order_map_id ] ); // Remember that we handled this suggestion - don't worry about remembering it multiple times. $handled_suggestion_ids[] = $suggestion_id; continue; } } // Add the missing payment gateway at the end. $order_map[ $id ] = empty( $order_map ) ? 0 : max( $order_map ) + 1; } $handled_suggestion_ids = array_unique( $handled_suggestion_ids ); /* * Place not yet handled suggestion entries right before their matching registered payment gateway IDs. * This means that registered PGs already in the order map force the suggestions * to be placed/moved right before them. We rely on suggestions and registered PGs being mutually exclusive. */ foreach ( array_keys( $order_map ) as $id ) { // If the id is not of a payment gateway or there is no suggestion for this payment gateway, ignore it. if ( ! array_key_exists( $id, $payment_gateways_to_suggestions_map ) || empty( $payment_gateways_to_suggestions_map[ $id ] ) ) { continue; } $suggestion = $payment_gateways_to_suggestions_map[ $id ]; // If the suggestion was already handled, skip it. if ( in_array( $suggestion['id'], $handled_suggestion_ids, true ) ) { continue; } // Place the suggestion at the same order as the payment gateway // thus ensuring that the suggestion is placed right before the payment gateway. $order_map = Utils::order_map_place_at_order( $order_map, $this->get_suggestion_order_map_id( $suggestion['id'] ), $order_map[ $id ] ); // Remember that we've handled this suggestion to avoid adding it multiple times. // We only want to attach the suggestion to the first payment gateway that matches the plugin slug. $handled_suggestion_ids[] = $suggestion['id']; } // Extract all the registered offline PMs and keep their order values. $offline_methods = array_filter( $order_map, array( $this, 'is_offline_payment_method' ), ARRAY_FILTER_USE_KEY ); if ( ! empty( $offline_methods ) ) { /* * If the offline PMs group is missing, add it before the last offline PM. */ if ( ! array_key_exists( self::OFFLINE_METHODS_ORDERING_GROUP, $order_map ) ) { $last_offline_method_order = max( $offline_methods ); $order_map = Utils::order_map_place_at_order( $order_map, self::OFFLINE_METHODS_ORDERING_GROUP, $last_offline_method_order ); } /* * Place all the offline PMs right after the offline PMs group entry. */ $target_order = $order_map[ self::OFFLINE_METHODS_ORDERING_GROUP ] + 1; // Sort the offline PMs by their order. asort( $offline_methods ); foreach ( $offline_methods as $offline_method => $order ) { $order_map = Utils::order_map_place_at_order( $order_map, $offline_method, $target_order ); ++$target_order; } } return Utils::order_map_normalize( $order_map ); } /** * Get the ID of the suggestion order map entry. * * @param string $suggestion_id The ID of the suggestion. * * @return string The ID of the suggestion order map entry. */ public function get_suggestion_order_map_id( string $suggestion_id ): string { return self::SUGGESTION_ORDERING_PREFIX . $suggestion_id; } /** * Check if the ID is a suggestion order map entry ID. * * @param string $id The ID to check. * * @return bool True if the ID is a suggestion order map entry ID, false otherwise. */ public function is_suggestion_order_map_id( string $id ): bool { return 0 === strpos( $id, self::SUGGESTION_ORDERING_PREFIX ); } /** * Get the ID of the suggestion from the suggestion order map entry ID. * * @param string $order_map_id The ID of the suggestion order map entry. * * @return string The ID of the suggestion. */ public function get_suggestion_id_from_order_map_id( string $order_map_id ): string { return str_replace( self::SUGGESTION_ORDERING_PREFIX, '', $order_map_id ); } /** * Reset the memoized data. Useful for testing purposes. * * @internal * @return void */ public function reset_memo(): void { $this->payment_gateways_memo = null; } /** * Handle payment gateways with non-standard registration behavior. * * @param array $payment_gateways The payment gateways list. * * @return array The payment gateways list with the necessary adjustments. */ private function handle_non_standard_registration_for_payment_gateways( array $payment_gateways ): array { /* * Handle the Mollie gateway's particular behavior: if there are no API keys or no PMs enabled, * the extension doesn't register a gateway instance. * We will need to register a mock gateway to represent Mollie in the settings page. */ $payment_gateways = $this->maybe_add_pseudo_mollie_gateway( $payment_gateways ); return $payment_gateways; } /** * Add the pseudo Mollie gateway to the payment gateways list if necessary. * * @param array $payment_gateways The payment gateways list. * * @return array The payment gateways list with the pseudo Mollie gateway added if necessary. */ private function maybe_add_pseudo_mollie_gateway( array $payment_gateways ): array { $mollie_provider = $this->get_gateway_provider_instance( 'mollie' ); // Do nothing if there is a Mollie gateway registered. if ( $mollie_provider->is_gateway_registered( $payment_gateways ) ) { return $payment_gateways; } // Get the Mollie suggestion and determine if the plugin is active. $mollie_suggestion = $this->get_extension_suggestion_by_id( ExtensionSuggestions::MOLLIE ); if ( empty( $mollie_suggestion ) ) { return $payment_gateways; } $mollie_suggestion = $this->enhance_extension_suggestion( $mollie_suggestion ); // Do nothing if the plugin is not active. if ( self::EXTENSION_ACTIVE !== $mollie_suggestion['plugin']['status'] ) { return $payment_gateways; } // Add the pseudo Mollie gateway to the list since the plugin is active but there is no Mollie gateway registered. $payment_gateways[] = $mollie_provider->get_pseudo_gateway( $mollie_suggestion ); return $payment_gateways; } /** * Enhance the payment gateway details with additional information from other sources. * * @param array $gateway_details The gateway details to enhance. * @param WC_Payment_Gateway $payment_gateway The payment gateway object. * @param string $country_code The country code for which the details are being enhanced. * This should be a ISO 3166-1 alpha-2 country code. * * @return array The enhanced gateway details. */ private function enhance_payment_gateway_details( array $gateway_details, WC_Payment_Gateway $payment_gateway, string $country_code ): array { // We discriminate between offline payment methods and gateways. $gateway_details['_type'] = $this->is_offline_payment_method( $payment_gateway->id ) ? self::TYPE_OFFLINE_PM : self::TYPE_GATEWAY; $plugin_slug = $gateway_details['plugin']['slug']; // The payment gateway plugin might use a non-standard directory name. // Try to normalize it to the common slug to avoid false negatives when matching. $normalized_plugin_slug = Utils::normalize_plugin_slug( $plugin_slug ); // If we have a matching suggestion, hoist details from there. // The suggestions only know about the normalized (aka official) plugin slug. $suggestion = $this->get_extension_suggestion_by_plugin_slug( $normalized_plugin_slug, $country_code ); if ( ! is_null( $suggestion ) ) { // Enhance the suggestion details. $suggestion = $this->enhance_extension_suggestion( $suggestion ); // The title, description, icon, and image from the suggestion take precedence over the ones from the gateway. // This is temporary until we update the partner extensions. // Do not override the title and description for certain suggestions because theirs are more descriptive // (like including the payment method when registering multiple gateways for the same provider). if ( ! in_array( $suggestion['id'], array( ExtensionSuggestions::PAYPAL_FULL_STACK, ExtensionSuggestions::PAYPAL_WALLET, ExtensionSuggestions::MOLLIE, ExtensionSuggestions::ANTOM, ExtensionSuggestions::MERCADO_PAGO, ExtensionSuggestions::AMAZON_PAY, ExtensionSuggestions::SQUARE_IN_PERSON, ExtensionSuggestions::PAYONEER, ), true ) ) { $gateway_details['title'] = $suggestion['title']; $gateway_details['description'] = $suggestion['description']; } $gateway_details['icon'] = $suggestion['icon']; $gateway_details['image'] = $suggestion['image']; if ( empty( $gateway_details['links'] ) ) { $gateway_details['links'] = $suggestion['links']; } if ( empty( $gateway_details['tags'] ) ) { $gateway_details['tags'] = $suggestion['tags']; } if ( empty( $gateway_details['plugin'] ) ) { $gateway_details['plugin'] = $suggestion['plugin']; } if ( empty( $gateway_details['_incentive'] ) && ! empty( $suggestion['_incentive'] ) ) { $gateway_details['_incentive'] = $suggestion['_incentive']; } // Attach the suggestion ID to the gateway details so we can reference it with precision. $gateway_details['_suggestion_id'] = $suggestion['id']; } // Get the gateway's corresponding plugin details. $plugin_data = PluginsHelper::get_plugin_data( $plugin_slug ); if ( ! empty( $plugin_data ) ) { // If there are no links, try to get them from the plugin data. if ( empty( $gateway_details['links'] ) ) { if ( is_array( $plugin_data ) && ! empty( $plugin_data['PluginURI'] ) ) { $gateway_details['links'] = array( array( '_type' => ExtensionSuggestions::LINK_TYPE_ABOUT, 'url' => esc_url( $plugin_data['PluginURI'] ), ), ); } elseif ( ! empty( $gateway_details['plugin']['_type'] ) && ExtensionSuggestions::PLUGIN_TYPE_WPORG === $gateway_details['plugin']['_type'] ) { // Fallback to constructing the WPORG plugin URI from the normalized plugin slug. $gateway_details['links'] = array( array( '_type' => ExtensionSuggestions::LINK_TYPE_ABOUT, 'url' => 'https://wordpress.org/plugins/' . $normalized_plugin_slug, ), ); } } } return $gateway_details; } /** * Check if the store has any enabled ecommerce gateways. * * We exclude offline payment methods from this check. * * @return bool True if the store has any enabled ecommerce gateways, false otherwise. */ private function has_enabled_ecommerce_gateways(): bool { $gateways = $this->get_payment_gateways(); $enabled_gateways = array_filter( $gateways, function ( $gateway ) { // Filter out offline gateways. return 'yes' === $gateway->enabled && ! $this->is_offline_payment_method( $gateway->id ); } ); return ! empty( $enabled_gateways ); } /** * Enhance a payment extension suggestion with additional information. * * @param array $extension The extension suggestion. * * @return array The enhanced payment extension suggestion. */ private function enhance_extension_suggestion( array $extension ): array { // Determine the category of the extension. switch ( $extension['_type'] ) { case ExtensionSuggestions::TYPE_PSP: $extension['category'] = self::CATEGORY_PSP; break; case ExtensionSuggestions::TYPE_EXPRESS_CHECKOUT: $extension['category'] = self::CATEGORY_EXPRESS_CHECKOUT; break; case ExtensionSuggestions::TYPE_BNPL: $extension['category'] = self::CATEGORY_BNPL; break; case ExtensionSuggestions::TYPE_CRYPTO: $extension['category'] = self::CATEGORY_CRYPTO; break; default: $extension['category'] = ''; break; } // Determine the PES's plugin status. // Default to not installed. $extension['plugin']['status'] = self::EXTENSION_NOT_INSTALLED; // Put in the default plugin file. $extension['plugin']['file'] = ''; if ( ! empty( $extension['plugin']['slug'] ) ) { // This is a best-effort approach, as the plugin might be sitting under a directory (slug) that we can't handle. // Always try the official plugin slug first, then the testing variations. $plugin_slug_variations = Utils::generate_testing_plugin_slugs( $extension['plugin']['slug'], true ); foreach ( $plugin_slug_variations as $plugin_slug ) { if ( PluginsHelper::is_plugin_installed( $plugin_slug ) ) { // Make sure we put in the actual slug and file path that we found. $extension['plugin']['slug'] = $plugin_slug; $extension['plugin']['file'] = PluginsHelper::get_plugin_path_from_slug( $plugin_slug ); // Remove the .php extension from the file path. The WP API expects it without it. if ( ! empty( $extension['plugin']['file'] ) && str_ends_with( $extension['plugin']['file'], '.php' ) ) { $extension['plugin']['file'] = substr( $extension['plugin']['file'], 0, -4 ); } $extension['plugin']['status'] = self::EXTENSION_INSTALLED; if ( PluginsHelper::is_plugin_active( $plugin_slug ) ) { $extension['plugin']['status'] = self::EXTENSION_ACTIVE; } break; } } } return $extension; } /** * Check if a payment extension suggestion has been hidden by the user. * * @param array $extension The extension suggestion. * * @return bool True if the extension suggestion is hidden, false otherwise. */ private function is_payment_extension_suggestion_hidden( array $extension ): bool { $user_payments_nox_profile = get_user_meta( get_current_user_id(), Payments::USER_PAYMENTS_NOX_PROFILE_KEY, true ); if ( empty( $user_payments_nox_profile ) ) { return false; } $user_payments_nox_profile = maybe_unserialize( $user_payments_nox_profile ); if ( empty( $user_payments_nox_profile['hidden_suggestions'] ) ) { return false; } return in_array( $extension['id'], array_column( $user_payments_nox_profile['hidden_suggestions'], 'id' ), true ); } /** * Apply order mappings to a base payment providers order map. * * @param array $base_map The base order map. * @param array $new_mappings The order mappings to apply. * This can be a full or partial list of the base one, * but it can also contain (only) new provider IDs and their orders. * * @return array The updated base order map, normalized. */ private function payment_providers_order_map_apply_mappings( array $base_map, array $new_mappings ): array { // Sanity checks. // Remove any null or non-integer values. $new_mappings = array_filter( $new_mappings, 'is_int' ); if ( empty( $new_mappings ) ) { $new_mappings = array(); } // If we have no existing order map or // both the base and the new map have the same length and keys, we can simply use the new map. if ( empty( $base_map ) || ( count( $base_map ) === count( $new_mappings ) && empty( array_diff( array_keys( $base_map ), array_keys( $new_mappings ) ) ) ) ) { $new_order_map = $new_mappings; } else { // If we are dealing with ONLY offline PMs updates (for all that are registered) and their group is present, // normalize the new order map to keep behavior as intended (i.e., reorder only inside the offline PMs list). $offline_pms = $this->get_offline_payment_methods_gateways(); // Make it a list keyed by the payment gateway ID. $offline_pms = array_combine( array_map( fn( $gateway ) => $gateway->id, $offline_pms ), $offline_pms ); if ( isset( $base_map[ self::OFFLINE_METHODS_ORDERING_GROUP ] ) && count( $new_mappings ) === count( $offline_pms ) && empty( array_diff( array_keys( $new_mappings ), array_keys( $offline_pms ) ) ) ) { $new_mappings = Utils::order_map_change_min_order( $new_mappings, $base_map[ self::OFFLINE_METHODS_ORDERING_GROUP ] + 1 ); } $new_order_map = Utils::order_map_apply_mappings( $base_map, $new_mappings ); } return Utils::order_map_normalize( $new_order_map ); } /** * Get the payment gateway provider instance. * * @param string $gateway_id The gateway ID. * * @return PaymentGateway The payment gateway provider instance. * Will return the general provider of no specific provider is found. */ private function get_gateway_provider_instance( string $gateway_id ): PaymentGateway { if ( isset( $this->instances[ $gateway_id ] ) ) { return $this->instances[ $gateway_id ]; } /** * The provider class for the gateway. * * @var PaymentGateway|null $provider_class */ $provider_class = null; if ( isset( $this->payment_gateways_providers_class_map[ $gateway_id ] ) ) { $provider_class = $this->payment_gateways_providers_class_map[ $gateway_id ]; } else { // Check for wildcard mappings. foreach ( $this->payment_gateways_providers_class_map as $gateway_id_pattern => $mapped_class ) { // Try to see if we have a wildcard mapping and if the gateway ID matches it. // Use the first found match. if ( false !== strpos( $gateway_id_pattern, '*' ) ) { $gateway_id_pattern = str_replace( '*', '.*', $gateway_id_pattern ); if ( preg_match( '/^' . $gateway_id_pattern . '$/', $gateway_id ) ) { $provider_class = $mapped_class; break; } } } } // If the gateway ID is not mapped to a provider class, return the generic provider. if ( is_null( $provider_class ) ) { if ( ! isset( $this->instances['generic'] ) ) { $this->instances['generic'] = new PaymentGateway(); } return $this->instances['generic']; } $this->instances[ $gateway_id ] = new $provider_class(); return $this->instances[ $gateway_id ]; } }