REST API: differentiate between checkbox and toggle boolean settings

Toggle settings serialise to 'Yes'/'No' while checkbox settings serialise
to '1'/'' to match how each field type is stored. Rename the unreleased
schema format string 'yes_no' -> 'yes-no' for consistency with the existing
'hex-color' format, and add a dedicated 'checkbox' format with its own
prepare/response handling. Adds PHPUnit coverage for both formats.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jakejackson1

src/Helper/Helper_Options_Fields.php

@@ -347,7 +347,7 @@ public function get_registered_fields() {
 						'desc2'      => esc_html__( 'Add rules to dynamically enable or disable the PDF. When disabled, PDFs do not show up in the admin area, cannot be viewed, and will not be attached to notifications.', 'gravity-pdf' ),
 						'schema'     => [
 							'type'   => 'boolean',
-							'format' => 'yes_no',
+							'format' => 'yes-no',
 						],
 					],
 
@@ -645,7 +645,7 @@ public function get_registered_fields() {
 							'description' => __( 'Force the PDF to be temporarily saved to the filesystem during form submission (deprecated). Use the gfpdf_post_save_pdf hook instead.', 'gravity-pdf' ),
 							'default'     => false,
 							'required'    => false,
-							'format'      => 'yes_no',
+							'format'      => 'yes-no',
 							'arg_options' => [
 								'sanitize_callback' => 'rest_sanitize_request_arg',
 							],

src/Rest/Rest_Form_Settings.php

@@ -837,10 +837,15 @@ protected function prepare_item_for_database( $request ) {
 			}
 
 			/* Handle Toggle values */
-			if ( $this->has_property_type( 'boolean', $property['type'] ) && ( $property['format'] ?? '' ) === 'yes_no' ) {
+			if ( $this->has_property_type( 'boolean', $property['type'] ) && ( $property['format'] ?? '' ) === 'yes-no' ) {
 				$value = $value === true ? 'Yes' : 'No';
 			}
 
+			/* Handle checkbox values */
+			if ( $this->has_property_type( 'boolean', $property['type'] ) && ( $property['format'] ?? '' ) === 'checkbox' ) {
+				$value = $value === true ? '1' : '';
+			}
+
 			$prepared_pdf[ $id ] = $value;
 		}
 
@@ -1092,12 +1097,17 @@ protected function get_section_schema( $settings, $group ) {
 					break;
 
 				case 'checkbox':
+					$schema[ $id ]['type']                             = 'boolean';
+					$schema[ $id ]['format']                           = 'checkbox';
+					$schema[ $id ]['default']                          = in_array( $default, [ 'Yes', '1', 1, 'true', true ], true );
+					$schema[ $id ]['arg_options']['sanitize_callback'] = 'rest_sanitize_request_arg';
+					break;
+
 				case 'toggle':
 					$schema[ $id ]['type']                             = 'boolean';
-					$schema[ $id ]['format']                           = 'yes_no';
+					$schema[ $id ]['format']                           = 'yes-no';
 					$schema[ $id ]['default']                          = in_array( $default, [ 'Yes', '1', 'true', true ], true );
 					$schema[ $id ]['arg_options']['sanitize_callback'] = 'rest_sanitize_request_arg';
-
 					break;
 			}
 

tests/phpunit/integration/Rest/Test_Rest_Form_Settings.php

@@ -822,7 +822,7 @@ public function test_get_item_schema() {
 		$this->assertContains( 'landscape', $args['orientation']['enum'] );
 
 		$this->assertSame( 'boolean', $args['rtl']['type'] );
-		$this->assertSame( 'yes_no', $args['rtl']['format'] );
+		$this->assertSame( 'yes-no', $args['rtl']['format'] );
 
 		$this->assertContains( 'Standard', $args['format']['enum'] );
 		$this->assertContains( 'PDFX1A', $args['format']['enum'] );
@@ -1213,4 +1213,94 @@ public function test_get_schema_for_template() {
 		$this->assertArrayNotHasKey( 'notification', $schema['properties'] );
 		$this->assertArrayNotHasKey( 'conditionalLogic', $schema['properties'] );
 	}
+
+	/**
+	 * Register an additional checkbox settings field so the REST schema generates a checkbox-format boolean.
+	 *
+	 * @param array $fields The existing advanced settings fields.
+	 *
+	 * @return array
+	 */
+	public function add_checkbox_field( $fields ) {
+		$fields['my_checkbox'] = [
+			'id'   => 'my_checkbox',
+			'name' => 'My Checkbox',
+			'type' => 'checkbox',
+			'std'  => false,
+		];
+
+		return $fields;
+	}
+
+	/**
+	 * Toggle and checkbox boolean fields must expose distinct schema formats so the API can serialise them
+	 * back to their respective storage values ('Yes'/'No' vs '1'/'').
+	 */
+	public function test_checkbox_and_toggle_schema_format() {
+		add_filter( 'gfpdf_form_settings_advanced', [ $this, 'add_checkbox_field' ] );
+
+		$schema = $this->api->get_item_schema();
+		$args   = $schema['properties'];
+
+		/* Toggle fields are flagged with the 'yes-no' format */
+		$this->assertSame( 'boolean', $args['rtl']['type'] );
+		$this->assertSame( 'yes-no', $args['rtl']['format'] );
+
+		/* Checkbox fields are flagged with the 'checkbox' format */
+		$this->assertSame( 'boolean', $args['my_checkbox']['type'] );
+		$this->assertSame( 'checkbox', $args['my_checkbox']['format'] );
+		$this->assertFalse( $args['my_checkbox']['default'] );
+	}
+
+	/**
+	 * A checkbox field stores '1' when enabled and '' when disabled, whereas a toggle field stores 'Yes'/'No'.
+	 */
+	public function test_checkbox_value_round_trip() {
+		add_filter( 'gfpdf_form_settings_advanced', [ $this, 'add_checkbox_field' ] );
+
+		/* Re-register the routes so the dispatched schema picks up the new checkbox field */
+		$this->api->register_routes();
+
+		wp_set_current_user( self::$admin_id );
+
+		/* Enabled checkbox is stored as '1', toggle as 'Yes' */
+		$request = new WP_REST_Request( 'POST', '/gravity-pdf/v1/form/' . $this->form_id );
+		$request->add_header( 'content-type', 'application/x-www-form-urlencoded' );
+		$request->set_body_params( [
+			'name'        => 'Label',
+			'template'    => 'rubix',
+			'rtl'         => true,
+			'my_checkbox' => true,
+		] );
+
+		$response = rest_get_server()->dispatch( $request );
+		$data     = $response->get_data();
+
+		$this->assertSame( 201, $response->get_status() );
+		$this->assertTrue( $data['my_checkbox'] );
+
+		$pdf = \GPDFAPI::get_pdf( $this->form_id, $data['id'] );
+		$this->assertSame( '1', $pdf['my_checkbox'] );
+		$this->assertSame( 'Yes', $pdf['rtl'] );
+
+		/* Disabled checkbox is stored as '', toggle as 'No' */
+		$request = new WP_REST_Request( 'POST', '/gravity-pdf/v1/form/' . $this->form_id );
+		$request->add_header( 'content-type', 'application/x-www-form-urlencoded' );
+		$request->set_body_params( [
+			'name'        => 'Label',
+			'template'    => 'rubix',
+			'rtl'         => false,
+			'my_checkbox' => false,
+		] );
+
+		$response = rest_get_server()->dispatch( $request );
+		$data     = $response->get_data();
+
+		$this->assertSame( 201, $response->get_status() );
+		$this->assertFalse( $data['my_checkbox'] );
+
+		$pdf = \GPDFAPI::get_pdf( $this->form_id, $data['id'] );
+		$this->assertSame( '', $pdf['my_checkbox'] );
+		$this->assertSame( 'No', $pdf['rtl'] );
+	}
 }