refactor(api,generators,admin): honest row shapes, and a toggle that did nothing (#1060) (#1074)

* refactor(api,generators,admin): honest row shapes, and a toggle that did nothing (#1060)

PR 4. The ruler goes from 170 to 135 and all three modules reach zero.

Most of it is typing the producer rather than casting at the consumer.
AudienceQueryService::find_user_bookings() now declares publicly what it
returns instead of list<array<string, mixed>>, which is what left the REST
controller reading thirteen unverifiable keys. QRCodeGenerator's defaults and
parsed parameters are a declared shape all the way to the library call, and
its settings reads go through SettingsReader — the project's own rule for
ffc_settings, and also what makes them typed.

Declaring that shape turned up a toggle that never worked. The two writers of
qr_cache_enabled disagree on its type: the tab's form save stores int 1, while
the autosave endpoint — which is what flipping the switch actually calls —
stores a PHP boolean through RequestInput::is_truthy(). The check was
`1 === $value`, and `1 === true` is false, so turning the QR cache on from the
UI left it off. Reading through the existing typed accessor fixes it; the test
is verified failing against the old check.

SettingsReader gains get_string(), the typed accessor that was missing. It
refuses a non-scalar rather than casting — `(string) array()` is the literal
'Array' plus a notice. Its int and bool siblings keep their plain casts on
purpose: changing those changes what every existing caller gets back, which is
a wider decision than this PR.

Two smaller notes. The intersection `UserBookingRow&array{audiences: …}`
resolves to *NEVER* in PHPStan — two sealed array shapes cannot be
intersected — so the with-audiences shape repeats the keys; the duplication is
the cost of saying what the method returns. And a test fixture that omitted
`audiences` was fixed rather than the shape widened: the producer always sets
that key, so the fixture was describing a row production never emits.

get_post_meta() casts are handled by two private helpers in FormListColumns
rather than a shared class. The repository has 87 casts of that shape, but one
proven user is not duplication yet.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012XWx9qJdjZdAq8crxM9GCU

* style(qrcode): align the assignments phpcbf flagged (#1060)

The WPCS gate reported two Generic.Formatting.MultipleStatementAlignment
warnings on the error-level block. My local phpcs run had been made before
that block's last edit, so it passed on a tree that no longer existed —
re-running the CI's exact command (phpcs over the changed-file list)
reproduces it, and phpcbf fixes it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012XWx9qJdjZdAq8crxM9GCU

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: rpgmem

.github/workflows/ci.yml

@@ -55,7 +55,7 @@ jobs:
           vendor/bin/phpstan analyse -c phpstan-rows.neon.dist \
             --error-format=json --no-progress --memory-limit=2G > rows.json || true
       - name: Report the row-reading classes
-        run: php .github/scripts/phpstan-rows-report.php rows.json 170
+        run: php .github/scripts/phpstan-rows-report.php rows.json 135
 
   audit:
     name: Composer audit

CHANGELOG.md

@@ -28,11 +28,16 @@ The format follows [Keep a Changelog] (https://keepachangelog.com/en/1.1.0/).
 - **Formas de linha honestas em `frontend` e `core`** (#1060): `ActivityLogQuery` declara a linha do log derivada do `CREATE TABLE`, e `ReprintDetector` declara o formato do resultado que dois consumidores já liam às cegas. A régua de nível 9 baixou de 203 para 170 e os dois módulos ficaram em zero.
 - **`Core\ArrayValue`** (#1060): leitura de escalar sobre array sem tipo — JSON decodificado, configuração de formulário, payload de token. Substitui o idioma `(string) ( $data['k'] ?? '' )`, que não confere nada: dado um array ele produz a string `Array`, dado um objeto sem `__toString` é fatal. Não serve para `$_POST` (isso é o `RequestInput`) nem para linha de banco (isso é shape declarada).
 
+- **Formas de linha honestas em `api`, `generators` e `admin`** (#1060): o `QRCodeGenerator` passa a ler `ffc_settings` pelo `SettingsReader` — regra do próprio projeto — e seus parâmetros viraram uma shape tipada até a chamada da biblioteca; `find_user_bookings()` declara publicamente o que devolve, em vez de `array<string, mixed>`. A régua de nível 9 baixou de 170 para 135 e os três módulos ficaram em zero.
+- **`SettingsReader::get_string()`** (#1060): acessor tipado que faltava. Recusa valor não escalar em vez de convertê-lo — `(string) array()` é a string `Array` mais um notice. Os acessores de int e bool seguem com o cast simples: mudá-los mudaria o que todo chamador existente recebe.
+
 ### Removed
 
 - `Shortcodes::get_new_captcha_data()` (#1053): método público sem nenhum chamador em produção — o único consumidor era o próprio teste. A geração de desafio já é responsabilidade do contrato de captcha.
 
 ### Fixed
+- **O cache de QR Code nunca ligava pelo toggle** (#1060): os dois gravadores da chave `qr_cache_enabled` discordam do tipo — o save do formulário grava `int 1`, e o autosave, que é o que o interruptor chama de fato, grava um booleano. A checagem era `1 === $valor`, e `1 === true` é falso, então ligar o cache pela interface deixava-o desligado.
+
 - **`ReprintDetector::detect()` devolvia `date` com tipo diferente conforme o ramo** (#1060): inteiro (segundos unix) quando havia reimpressão, string vazia quando não. Só um consumidor lê a chave, e só no ramo de reimpressão, então o ramo vazio passou a devolver `0` — um contrato cujo tipo depende do ramo não pode ser verificado.
 
 - **Ids não-numéricos em reservas de público viravam `0`** (#1060): `audience_ids` e `user_ids` chegam dentro de um `$data` do chamador, e cada entrada era convertida direto com `(int)` — uma string solta ou `null` virava `0` e gravava uma linha de junção apontando para um público que não existe. Agora entradas não-numéricas são descartadas.

includes/admin/class-ffc-admin-user-columns.php

@@ -18,6 +18,8 @@
 
 namespace FreeFormCertificate\Admin;
 
+use FreeFormCertificate\Core\ArrayValue;
+
 if ( ! defined( 'ABSPATH' ) ) {
 	exit;
 }
@@ -237,9 +239,11 @@ private static function render_user_actions( int $user_id ): string {
 		// Get dashboard URL from User Access Settings (cached per request).
 		if ( null === self::$dashboard_url_cache ) {
 			$user_access_settings      = get_option( 'ffc_user_access_settings', array() );
-			self::$dashboard_url_cache = isset( $user_access_settings['redirect_url'] ) && ! empty( $user_access_settings['redirect_url'] )
-				? $user_access_settings['redirect_url']
-				: home_url( '/dashboard' );
+			self::$dashboard_url_cache = ArrayValue::string(
+				is_array( $user_access_settings ) ? $user_access_settings : array(),
+				'redirect_url',
+				home_url( '/dashboard' )
+			);
 		}
 		$dashboard_url = self::$dashboard_url_cache;
 

includes/admin/class-ffc-csv-exporter.php

@@ -18,6 +18,7 @@
 
 namespace FreeFormCertificate\Admin;
 
+use FreeFormCertificate\Core\ArrayValue;
 use FreeFormCertificate\Core\BatchedCsvExport;
 use FreeFormCertificate\Core\SourceRegistry;
 use FreeFormCertificate\Repositories\SubmissionRepository;
@@ -109,10 +110,11 @@ public static function cleanup_stale_export_jobs(): int {
 
 				// Read the payload BEFORE deleting so we can unlink the temp
 				// file the abandoned job left on disk.
-				$job = get_option( '_transient_' . $transient_key );
-				if ( is_array( $job ) && ! empty( $job['file'] ) && file_exists( $job['file'] ) ) {
+				$job  = get_option( '_transient_' . $transient_key );
+				$file = is_array( $job ) ? ArrayValue::string( $job, 'file' ) : '';
+				if ( '' !== $file && file_exists( $file ) ) {
 					// phpcs:ignore WordPress.WP.AlternativeFunctions.unlink_unlink -- Deletes the plugin's own temp export file by absolute path. WP_Filesystem would need credentials, and this runs on a cleanup path with no user present.
-					unlink( $job['file'] );
+					unlink( $file );
 				}
 
 				delete_transient( $transient_key );

includes/admin/class-ffc-form-list-columns.php

@@ -123,6 +123,38 @@ public static function add_columns( array $columns ): array {
 		return $new;
 	}
 
+	/**
+	 * Read a post meta value as a string.
+	 *
+	 * `get_post_meta()` returns mixed — a meta row can hold a serialised
+	 * array — and `(string)` on one is the literal `'Array'` plus a notice.
+	 * Local to this class on purpose: the repository has 87 casts of this
+	 * shape and a shared helper is worth extracting from two proven users,
+	 * not from one (#1060).
+	 *
+	 * @param int    $post_id Post ID.
+	 * @param string $key     Meta key.
+	 * @return string
+	 */
+	private static function meta_string( int $post_id, string $key ): string {
+		$value = get_post_meta( $post_id, $key, true );
+
+		return is_scalar( $value ) ? (string) $value : '';
+	}
+
+	/**
+	 * Read a post meta value as an integer.
+	 *
+	 * @param int    $post_id Post ID.
+	 * @param string $key     Meta key.
+	 * @return int
+	 */
+	private static function meta_int( int $post_id, string $key ): int {
+		$value = get_post_meta( $post_id, $key, true );
+
+		return is_numeric( $value ) ? (int) $value : 0;
+	}
+
 	/**
 	 * Resolve the on/off state of each toggleable feature for a form.
 	 *
@@ -132,7 +164,7 @@ public static function add_columns( array $columns ): array {
 	private static function get_feature_states( int $post_id ): array {
 		$config      = get_post_meta( $post_id, '_ffc_form_config', true );
 		$device_meta = get_post_meta( $post_id, '_ffc_device_limit', true );
-		$csv_enabled = (string) get_post_meta( $post_id, '_ffc_csv_public_enabled', true );
+		$csv_enabled = self::meta_string( $post_id, '_ffc_csv_public_enabled' );
 
 		return array(
 			'csv_public_enabled' => '1' === $csv_enabled,
@@ -227,12 +259,12 @@ public static function render_column( string $column_name, int $post_id ): void
 				break;
 
 			case 'ffc_csv_downloads':
-				$csv_enabled = (string) get_post_meta( $post_id, '_ffc_csv_public_enabled', true );
+				$csv_enabled = self::meta_string( $post_id, '_ffc_csv_public_enabled' );
 				if ( '1' !== $csv_enabled ) {
 					echo '<span class="ffc-empty-value">&mdash;</span>';
 				} else {
-					$dl_count = (int) get_post_meta( $post_id, '_ffc_csv_public_count', true );
-					$limit    = (int) get_post_meta( $post_id, '_ffc_csv_public_limit', true );
+					$dl_count = self::meta_int( $post_id, '_ffc_csv_public_count' );
+					$limit    = self::meta_int( $post_id, '_ffc_csv_public_limit' );
 					if ( $limit > 0 ) {
 						printf(
 							'%s / %s',
@@ -318,11 +350,12 @@ public static function search_by_id( \WP_Query $query ): void {
 		}
 
 		$search = $query->get( 's' );
-		if ( '' === $search || ! ctype_digit( trim( $search ) ) ) {
+		$search = is_scalar( $search ) ? trim( (string) $search ) : '';
+		if ( '' === $search || ! ctype_digit( $search ) ) {
 			return;
 		}
 
-		$query->set( 'post__in', array( absint( trim( $search ) ) ) );
+		$query->set( 'post__in', array( absint( $search ) ) );
 		$query->set( 's', '' );
 	}
 }

includes/api/class-ffc-user-audience-rest-controller.php

@@ -16,6 +16,8 @@
 
 namespace FreeFormCertificate\API;
 
+use FreeFormCertificate\Core\ArrayValue;
+
 if ( ! defined( 'ABSPATH' ) ) {
 	exit;
 }
@@ -170,18 +172,18 @@ public function get_user_audience_bookings( $request ) {
 
 				$bookings_formatted[] = array(
 					'id'               => (int) $booking['id'],
-					'environment_id'   => (int) ( $booking['environment_id'] ?? 0 ),
+					'environment_id'   => (int) $booking['environment_id'],
 					'environment_name' => $booking['environment_name'] ?? __( 'Unknown', 'ffcertificate' ),
 					'schedule_name'    => $booking['schedule_name'] ?? '',
 					'booking_date'     => $date_formatted,
-					'booking_date_raw' => $booking['booking_date'] ?? '',
+					'booking_date_raw' => $booking['booking_date'],
 					'start_time'       => $time_formatted,
 					'end_time'         => $end_time_formatted,
-					'description'      => $booking['description'] ?? '',
+					'description'      => $booking['description'],
 					'status'           => $status,
 					'status_label'     => $status_labels[ $status ] ?? $status,
 					'is_past'          => $is_past,
-					'audiences'        => $booking['audiences'] ?? array(),
+					'audiences'        => $booking['audiences'],
 				);
 			}
 
@@ -304,6 +306,23 @@ public function get_joinable_groups( $request ) {
 		}
 	}
 
+	/**
+	 * Read an integer route parameter.
+	 *
+	 * `WP_REST_Request::get_param()` returns mixed — the route's registered
+	 * type is a runtime validation, not something the analyser can see — and
+	 * `absint()` on an array is a TypeError rather than a rejected request.
+	 *
+	 * @param \WP_REST_Request<array<string, mixed>> $request Request.
+	 * @param string                                 $key     Parameter name.
+	 * @return int
+	 */
+	private static function param_int( $request, string $key ): int {
+		$value = $request->get_param( $key );
+
+		return is_numeric( $value ) ? absint( $value ) : 0;
+	}
+
 	/**
 	 * Recursively assemble a joinable-tree node from a raw audience row.
 	 *
@@ -319,13 +338,23 @@ public function get_joinable_groups( $request ) {
 	 * reference tallies the user's memberships in button-bearing nodes —
 	 * the on-screen "joined N of max" counter.
 	 *
-	 * @param array<string, mixed> $node  Audience row with 'children' array.
-	 * @param int                  $count Reference counter for joined self-join nodes.
-	 * @return array<string, mixed>|null  Assembled node, or null when it does not appear.
+	 * The parameter is `array<array-key, mixed>` rather than
+	 * `array<string, mixed>` because the recursive call feeds it an element of
+	 * the node's own `children`, whose key type nothing guarantees. Every read
+	 * below goes through `ArrayValue`, so a node missing a key yields a
+	 * default instead of a warning.
+	 *
+	 * @param array<array-key, mixed> $node  Audience row with 'children' array.
+	 * @param int                     $count Reference counter for joined self-join nodes.
+	 * @return array<string, mixed>|null     Assembled node, or null when it does not appear.
 	 */
 	private function build_joinable_node( array $node, int &$count ): ?array {
 		$children = array();
-		foreach ( $node['children'] as $child ) {
+		foreach ( ArrayValue::array( $node, 'children' ) as $child ) {
+			if ( ! is_array( $child ) ) {
+				continue;
+			}
+
 			$built = $this->build_joinable_node( $child, $count );
 			if ( $built ) {
 				$children[] = $built;
@@ -373,7 +402,7 @@ public function join_audience_group( $request ) {
 		try {
 			$ctx      = $this->resolve_user_context( $request );
 			$user_id  = $ctx['user_id'];
-			$group_id = absint( $request->get_param( 'group_id' ) );
+			$group_id = self::param_int( $request, 'group_id' );
 
 			if ( ! $user_id ) {
 				return new \WP_Error( 'not_logged_in', __( 'You must be logged in', 'ffcertificate' ), array( 'status' => 401 ) );
@@ -448,7 +477,7 @@ public function leave_audience_group( $request ) {
 			global $wpdb;
 			$ctx      = $this->resolve_user_context( $request );
 			$user_id  = $ctx['user_id'];
-			$group_id = absint( $request->get_param( 'group_id' ) );
+			$group_id = self::param_int( $request, 'group_id' );
 
 			if ( ! $user_id ) {
 				return new \WP_Error( 'not_logged_in', __( 'You must be logged in', 'ffcertificate' ), array( 'status' => 401 ) );

includes/audience/class-ffc-audience-query-service.php

@@ -78,6 +78,31 @@
  *     schedule_name: string|null,
  *     is_all_day?: numeric-string|null
  * }
+ * `UserBookingWithAudiences` repeats every key of `UserBookingRow` instead of
+ * intersecting with it: PHPStan resolves an intersection of two sealed array
+ * shapes to *NEVER*, so `UserBookingRow&array{audiences: …}` type-checks as a
+ * value that cannot exist. The duplication is the cost of saying what the
+ * method actually returns.
+ *
+ * @phpstan-type UserBookingWithAudiences array{
+ *     id: numeric-string,
+ *     environment_id: numeric-string,
+ *     booking_date: string,
+ *     start_time: string,
+ *     end_time: string,
+ *     booking_type: string,
+ *     description: string,
+ *     status: string|null,
+ *     created_by: numeric-string,
+ *     created_at: string|null,
+ *     cancelled_by: numeric-string|null,
+ *     cancelled_at: string|null,
+ *     cancellation_reason: string|null,
+ *     environment_name: string|null,
+ *     schedule_name: string|null,
+ *     is_all_day?: numeric-string|null,
+ *     audiences: list<array{name: string, color: string|null}>
+ * }
  * @phpstan-type BookingAudienceBadgeRow array{
  *     booking_id: numeric-string,
  *     name: string,
@@ -213,7 +238,7 @@ public static function find_user_joinable_audiences( int $user_id ): array {
 	 * @since 6.6.2
 	 * @param int                  $user_id WordPress user ID.
 	 * @param array<string, mixed> $filter  Optional filter (see shape above).
-	 * @return list<array<string, mixed>>
+	 * @return list<UserBookingWithAudiences>
 	 */
 	public static function find_user_bookings( int $user_id, array $filter = array() ): array {
 		if ( $user_id <= 0 ) {