File Content: CheckoutSchema.php <?php declare(strict_types=1); namespace Automattic\WooCommerce\StoreApi\Schemas\V1; use Automattic\WooCommerce\StoreApi\SchemaController; use Automattic\WooCommerce\StoreApi\Payments\PaymentResult; use Automattic\WooCommerce\StoreApi\Schemas\ExtendSchema; use Automattic\WooCommerce\Blocks\Domain\Services\CheckoutFields; use Automattic\WooCommerce\Blocks\Package; use Automattic\WooCommerce\StoreApi\Utilities\SanitizationUtils; use Automattic\WooCommerce\StoreApi\Schemas\V1\CartSchema; /** * CheckoutSchema class. */ class CheckoutSchema extends AbstractSchema { /** * The schema item name. * * @var string */ protected $title = 'checkout'; /** * The schema item identifier. * * @var string */ const IDENTIFIER = 'checkout'; /** * Billing address schema instance. * * @var BillingAddressSchema */ protected $billing_address_schema; /** * Shipping address schema instance. * * @var ShippingAddressSchema */ protected $shipping_address_schema; /** * Image Attachment schema instance. * * @var ImageAttachmentSchema */ protected $image_attachment_schema; /** * Cart schema instance. * * @var CartSchema */ protected $cart_schema; /** * Additional fields controller. * * @var CheckoutFields */ protected $additional_fields_controller; /** * Constructor. * * @param ExtendSchema $extend Rest Extending instance. * @param SchemaController $controller Schema Controller instance. */ public function __construct( ExtendSchema $extend, SchemaController $controller ) { parent::__construct( $extend, $controller ); $this->billing_address_schema = $this->controller->get( BillingAddressSchema::IDENTIFIER ); $this->shipping_address_schema = $this->controller->get( ShippingAddressSchema::IDENTIFIER ); $this->image_attachment_schema = $this->controller->get( ImageAttachmentSchema::IDENTIFIER ); $this->cart_schema = $this->controller->get( CartSchema::IDENTIFIER ); $this->additional_fields_controller = Package::container()->get( CheckoutFields::class ); } /** * Checkout schema properties. * * @return array */ public function get_properties() { $additional_field_schema = $this->get_additional_fields_schema(); return [ 'order_id' => [ 'description' => __( 'The order ID to process during checkout.', 'woocommerce' ), 'type' => 'integer', 'context' => [ 'view', 'edit' ], 'readonly' => true, ], 'status' => [ 'description' => __( 'Order status. Payment providers will update this value after payment.', 'woocommerce' ), 'type' => 'string', 'context' => [ 'view', 'edit' ], 'readonly' => true, ], 'order_key' => [ 'description' => __( 'Order key used to check validity or protect access to certain order data.', 'woocommerce' ), 'type' => 'string', 'context' => [ 'view', 'edit' ], 'readonly' => true, ], 'order_number' => [ 'description' => __( 'Order number used for display.', 'woocommerce' ), 'type' => 'string', 'context' => [ 'view', 'edit' ], 'readonly' => true, ], 'customer_note' => [ 'description' => __( 'Note added to the order by the customer during checkout.', 'woocommerce' ), 'type' => 'string', 'context' => [ 'view', 'edit' ], ], 'customer_id' => [ 'description' => __( 'Customer ID if registered. Will return 0 for guests.', 'woocommerce' ), 'type' => 'integer', 'context' => [ 'view', 'edit' ], 'readonly' => true, ], 'billing_address' => [ 'description' => __( 'Billing address.', 'woocommerce' ), 'type' => 'object', 'context' => [ 'view', 'edit' ], 'properties' => $this->billing_address_schema->get_properties(), 'arg_options' => [ 'sanitize_callback' => [ $this->billing_address_schema, 'sanitize_callback' ], 'validate_callback' => [ $this->billing_address_schema, 'validate_callback' ], ], 'required' => true, ], 'shipping_address' => [ 'description' => __( 'Shipping address.', 'woocommerce' ), 'type' => 'object', 'context' => [ 'view', 'edit' ], 'properties' => $this->shipping_address_schema->get_properties(), 'arg_options' => [ 'sanitize_callback' => [ $this->shipping_address_schema, 'sanitize_callback' ], 'validate_callback' => [ $this->shipping_address_schema, 'validate_callback' ], ], ], 'payment_method' => [ 'description' => __( 'The ID of the payment method being used to process the payment.', 'woocommerce' ), 'type' => 'string', 'context' => [ 'view', 'edit' ], // Validation may be based on cart contents which is not available here; this returns all enabled // gateways. Further validation occurs during the request. 'enum' => array_merge( [ '' ], array_values( WC()->payment_gateways->get_payment_gateway_ids() ) ), ], 'create_account' => [ 'description' => __( 'Whether to create a new user account as part of order processing.', 'woocommerce' ), 'type' => 'boolean', 'context' => [ 'view', 'edit' ], ], 'payment_result' => [ 'description' => __( 'Result of payment processing, or null if not yet processed.', 'woocommerce' ), 'type' => [ 'object', 'null' ], 'context' => [ 'view', 'edit' ], 'readonly' => true, 'properties' => [ 'payment_status' => [ 'description' => __( 'Status of the payment returned by the gateway. One of success, pending, failure, error.', 'woocommerce' ), 'readonly' => true, 'type' => 'string', ], 'payment_details' => [ 'description' => __( 'An array of data being returned from the payment gateway.', 'woocommerce' ), 'readonly' => true, 'type' => 'array', 'items' => [ 'type' => 'object', 'properties' => [ 'key' => [ 'type' => 'string', ], 'value' => [ 'type' => 'string', ], ], ], ], 'redirect_url' => [ 'description' => __( 'A URL to redirect the customer after checkout. This could be, for example, a link to the payment processors website.', 'woocommerce' ), 'readonly' => true, 'type' => 'string', ], ], ], 'additional_fields' => [ 'description' => __( 'Additional fields to be persisted on the order.', 'woocommerce' ), 'type' => 'object', 'context' => [ 'view', 'edit' ], 'properties' => $additional_field_schema, 'arg_options' => [ 'sanitize_callback' => [ $this, 'sanitize_additional_fields' ], 'validate_callback' => [ $this, 'validate_additional_fields' ], ], 'required' => $this->schema_has_required_property( $additional_field_schema ), ], self::EXTENDING_KEY => $this->get_extended_schema( self::IDENTIFIER ), ]; } /** * Return the response for checkout. * * @param object $item Results from checkout action. * @return array */ public function get_item_response( $item ) { $cart = property_exists( $item, 'cart' ) ? $item->cart : null; $payment_result = property_exists( $item, 'payment_result' ) ? $item->payment_result : null; return $this->get_checkout_response( $item->order, $payment_result, $cart ); } /** * Get the checkout response based on the current order and any payments. * * @param \WC_Order $order Order object. * @param PaymentResult|null $payment_result Payment result object. * @param \WC_Cart|null $cart Cart object. * @return array */ protected function get_checkout_response( \WC_Order $order, ?PaymentResult $payment_result = null, ?\WC_Cart $cart = null ) { $payment_result = $payment_result ? [ 'payment_status' => $payment_result->status, 'payment_details' => $this->prepare_payment_details_for_response( $payment_result->payment_details ), 'redirect_url' => $payment_result->redirect_url, ] : null; return [ 'order_id' => $order->get_id(), 'status' => $order->get_status(), 'order_key' => $order->get_order_key(), 'order_number' => $order->get_order_number(), 'customer_note' => $order->get_customer_note(), 'customer_id' => $order->get_customer_id(), 'billing_address' => (object) $this->billing_address_schema->get_item_response( $order ), 'shipping_address' => (object) $this->shipping_address_schema->get_item_response( $order ), 'payment_method' => $order->get_payment_method(), 'payment_result' => $payment_result, 'additional_fields' => (object) $this->get_additional_fields_response( $order ), '__experimentalCart' => $cart ? (object) $this->cart_schema->get_item_response( $cart ) : null, self::EXTENDING_KEY => $this->get_extended_data( self::IDENTIFIER ), ]; } /** * This prepares the payment details for the response so it's following the * schema where it's an array of objects. * * @param array $payment_details An array of payment details from the processed payment. * * @return array An array of objects where each object has the key and value * as distinct properties. */ protected function prepare_payment_details_for_response( array $payment_details ) { return array_map( function ( $key, $value ) { return (object) [ 'key' => $key, 'value' => $value, ]; }, array_keys( $payment_details ), $payment_details ); } /** * Get the additional fields response. * * @param \WC_Order $order Order object. * @return array */ protected function get_additional_fields_response( \WC_Order $order ) { $fields = wp_parse_args( $this->additional_fields_controller->get_all_fields_from_object( $order, 'other' ), $this->additional_fields_controller->get_all_fields_from_object( wc()->customer, 'other' ) ); $additional_field_schema = $this->get_additional_fields_schema(); foreach ( $fields as $key => $value ) { if ( ! isset( $additional_field_schema[ $key ] ) ) { unset( $fields[ $key ] ); continue; } // This makes sure we're casting checkboxes from "1" and "0" to boolean. In the frontend, "0" is treated as truthy. if ( isset( $additional_field_schema[ $key ]['type'] ) && 'boolean' === $additional_field_schema[ $key ]['type'] ) { $fields[ $key ] = (bool) $value; } else { $fields[ $key ] = $this->prepare_html_response( $value ); } } return (object) $fields; } /** * Get the schema for additional fields. * * @return array */ protected function get_additional_fields_schema() { return $this->generate_additional_fields_schema( $this->additional_fields_controller->get_fields_for_location( 'contact' ), $this->additional_fields_controller->get_fields_for_location( 'order' ) ); } /** * Generate the schema for additional fields. * * @param array[] ...$args One or more arrays of additional fields. * @return array */ protected function generate_additional_fields_schema( ...$args ) { $additional_fields = array_merge( ...$args ); $schema = []; foreach ( $additional_fields as $key => $field ) { $field_schema = [ 'description' => $field['label'], 'type' => 'string', 'context' => [ 'view', 'edit' ], 'required' => $this->additional_fields_controller->is_conditional_field( $field ) ? false : true === $field['required'], ]; if ( 'select' === $field['type'] ) { $field_schema['enum'] = array_map( function ( $option ) { return $option['value']; }, $field['options'] ); if ( true !== $field['required'] || $this->additional_fields_controller->is_conditional_field( $field ) ) { $field_schema['enum'][] = ''; } } if ( 'checkbox' === $field['type'] ) { $field_schema['type'] = 'boolean'; } if ( 'checkbox' === $field['type'] && true === $field['required'] ) { $field_schema['enum'][] = true; } $schema[ $key ] = $field_schema; } return $schema; } /** * Check if any additional field is required, so that the parent item is required as well. * * @param array $additional_fields_schema Additional fields schema. * @return bool */ protected function schema_has_required_property( $additional_fields_schema ) { return array_reduce( array_keys( $additional_fields_schema ), function ( $carry, $key ) use ( $additional_fields_schema ) { return $carry || true === $additional_fields_schema[ $key ]['required']; }, false ); } /** * Sanitize and format additional fields object. * * @param array $fields Values being sanitized. * @return array */ public function sanitize_additional_fields( $fields ) { $properties = $this->get_additional_fields_schema(); $sanitization_utils = new SanitizationUtils(); $fields = $sanitization_utils->wp_kses_array( array_reduce( array_keys( $fields ), function ( $carry, $key ) use ( $fields, $properties ) { if ( ! isset( $properties[ $key ] ) ) { return $carry; } $field_schema = $properties[ $key ]; $rest_sanitized = rest_sanitize_value_from_schema( wp_unslash( $fields[ $key ] ), $field_schema, $key ); $rest_sanitized = $this->additional_fields_controller->sanitize_field( $key, $rest_sanitized ); $carry[ $key ] = $rest_sanitized; return $carry; }, [] ) ); return $sanitization_utils->wp_kses_array( $fields ); } /** * Validate additional fields object. This does not validate required fields nor customer validation rules because * this may be a partial request. That will happen later when the full request is processed during POST. This only * validates against the schema. * * @see rest_validate_value_from_schema * * @param array $fields Value being sanitized. * @param \WP_REST_Request $request The Request. * @return true|\WP_Error */ public function validate_additional_fields( $fields, $request ) { $errors = new \WP_Error(); $fields = $this->sanitize_additional_fields( $fields ); $additional_field_schema = $this->get_additional_fields_schema(); // for PUT requests, we only want to validate the fields that are being updated. if ( $request->get_method() === 'PUT' ) { $additional_field_schema = array_intersect_key( $additional_field_schema, $fields ); } // on POST, loop over the schema instead of the fields. This is to ensure missing fields are validated. foreach ( $additional_field_schema as $key => $schema ) { if ( ! isset( $fields[ $key ] ) && true !== $schema['required'] ) { // Optional fields can go missing. continue; } $result = rest_validate_value_from_schema( $fields[ $key ] ?? null, $schema, $key ); if ( is_wp_error( $result ) && $result->has_errors() ) { $location = $this->additional_fields_controller->get_field_location( $key ); foreach ( $result->get_error_codes() as $code ) { $result->add_data( array( 'location' => $location, 'key' => $key, ), $code ); } $errors->merge_from( $result ); } } return $errors->has_errors() ? $errors : true; } } Submit