Bug Fixes

Author: PDowney

CHANGELOG.md

@@ -49,6 +49,10 @@
 - **Type Declarations**: Added PHP 7.4 parameter types and return types to all functions where deterministic. Functions returning union types (`array|WP_Error`, `string|false`, `true|WP_Error`) retain PHPDoc-only annotations since PHP 7.4 does not support union return types.
 - **Short Array Syntax**: Standardized all `array()` constructor calls to short `[]` syntax throughout the plugin.
 - **Null Coalescing Assignment**: Replaced explicit null check + assignment pattern with PHP 7.4 `??=` operator in `sse_should_exclude_file()` file size cache, and `?:` Elvis operator for the ternary fallback.
+- **PHPStan Array Shapes**: Added PHPStan `array{}` shape annotations to all functions accepting or returning associative arrays, resolving 10 level-6 "no value type specified in iterable type array" errors.
+- **Trailing Whitespace**: Removed trailing whitespace (tabs on blank lines) across `export.php`, `download.php`, `cleanup.php`, `admin-page.php`, and `security.php`.
+- **JS File Header**: Converted `admin.js` file header from JSDoc (`/** @package`, `@since`) to plain block comment to avoid TSDoc linter false positives.
+- **Bulk Cleanup Complexity**: Extracted per-file deletion logic from `sse_bulk_cleanup_exports_handler()` into `sse_cleanup_expired_export_file()` helper, reducing cyclomatic complexity from 13 to 8 and NPath complexity from 336 to under 200.
 
 ## 2.0.0 - March 1, 2026
 

includes/admin-page.php

@@ -107,7 +107,7 @@ function sse_exporter_page_html(): void {
 		<form method="post" action="" class="sse-section-spacing">
 			<?php wp_nonce_field( 'sse_export_action', 'sse_export_nonce' ); ?>
 			<input type="hidden" name="action" value="sse_export_site">
-			
+
 			<table class="form-table sse-form-table">
 				<tbody>
 					<tr>
@@ -128,7 +128,7 @@ function sse_exporter_page_html(): void {
 					</tr>
 				</tbody>
 			</table>
-			
+
 			<?php submit_button( __( 'Export Site', 'enginescript-site-exporter' ) ); ?>
 		</form>
 		<hr>
@@ -175,7 +175,7 @@ function () use ( $message ) {
  * Shows a success notice to the user.
  *
  * @since 1.0.0
- * @param array $zip_result The zip file information.
+ * @param array{filename: string, filepath: string} $zip_result The zip file information.
  * @return void
  */
 function sse_show_success_notice( array $zip_result ): void {

includes/archive.php

@@ -13,9 +13,9 @@
  * Creates a site archive with database and files.
  *
  * @since 1.0.0
- * @param array $export_paths  Export directory paths.
- * @param array $database_file Database file information.
- * @return array|WP_Error Archive info on success, WP_Error on failure.
+ * @param array{export_dir: string, export_url: string, export_dir_name: string} $export_paths  Export directory paths.
+ * @param array{filename: string, filepath: string} $database_file Database file information.
+ * @return array{filename: string, filepath: string}|WP_Error Archive info on success, WP_Error on failure.
  */
 function sse_create_site_archive( array $export_paths, array $database_file ) {
 	if ( ! class_exists( 'ZipArchive' ) ) {

includes/cleanup.php

@@ -13,7 +13,7 @@
  * Cleans up temporary files.
  *
  * @since 1.0.0
- * @param array $files Array of file paths to delete.
+ * @param string[] $files Array of file paths to delete.
  * @return void
  */
 function sse_cleanup_files( array $files ): void {
@@ -81,15 +81,15 @@ function sse_schedule_bulk_cleanup(): void {
  */
 function sse_bulk_cleanup_exports_handler(): void {
 	sse_log( 'Bulk export cleanup handler triggered', 'info' );
-	
+
 	$upload_dir = wp_upload_dir();
 	$export_dir = trailingslashit( $upload_dir['basedir'] ) . SSE_EXPORT_DIR_NAME;
-	
+
 	if ( ! is_dir( $export_dir ) ) {
 		sse_log( 'Export directory does not exist, nothing to clean up', 'info' );
 		return;
 	}
-	
+
 	try {
 		$dir_iterator = new DirectoryIterator( $export_dir );
 	} catch ( RuntimeException $e ) {
@@ -111,34 +111,51 @@ function sse_bulk_cleanup_exports_handler(): void {
 		sse_log( 'No export files found in bulk cleanup', 'info' );
 		return;
 	}
-	
+
 	$cleaned_count = 0;
 	$cutoff_time   = time() - ( 5 * 60 ); // Files older than 5 minutes.
-	
+
 	foreach ( $files as $file_path ) {
-		$file_time = filemtime( $file_path );
-		
-		if ( $file_time && $file_time < $cutoff_time ) {
-			// File is older than 5 minutes, validate it's an export file.
-			$filename   = basename( $file_path );
-			$validation = sse_validate_basic_export_file( $filename );
-			
-			if ( ! is_wp_error( $validation ) ) {
-				if ( sse_safely_delete_file( $file_path ) ) {
-					sse_log( 'Bulk cleanup deleted export file: ' . $file_path, 'info' );
-					$cleaned_count++;
-				} else {
-					sse_log( 'Bulk cleanup failed to delete: ' . $file_path, 'error' );
-				}
-			} else {
-				sse_log( 'Bulk cleanup skipped invalid file: ' . $file_path . ' - ' . $validation->get_error_message(), 'warning' );
-			}
+		if ( sse_cleanup_expired_export_file( $file_path, $cutoff_time ) ) {
+			$cleaned_count++;
 		}
 	}
-	
+
 	sse_log( "Bulk cleanup completed. Deleted {$cleaned_count} export files.", 'info' );
 }
 
+/**
+ * Attempts to clean up a single expired export file.
+ *
+ * @since 2.0.0
+ * @param string $file_path   The file path to check and potentially delete.
+ * @param int    $cutoff_time Unix timestamp; files modified before this are eligible.
+ * @return bool True if the file was deleted, false otherwise.
+ */
+function sse_cleanup_expired_export_file( string $file_path, int $cutoff_time ): bool {
+	$file_time = filemtime( $file_path );
+
+	if ( ! $file_time || $file_time >= $cutoff_time ) {
+		return false;
+	}
+
+	$filename   = basename( $file_path );
+	$validation = sse_validate_basic_export_file( $filename );
+
+	if ( is_wp_error( $validation ) ) {
+		sse_log( 'Bulk cleanup skipped invalid file: ' . $file_path . ' - ' . $validation->get_error_message(), 'warning' );
+		return false;
+	}
+
+	if ( sse_safely_delete_file( $file_path ) ) {
+		sse_log( 'Bulk cleanup deleted export file: ' . $file_path, 'info' );
+		return true;
+	}
+
+	sse_log( 'Bulk cleanup failed to delete: ' . $file_path, 'error' );
+	return false;
+}
+
 /**
  * Handles scheduled deletion of export files.
  *
@@ -148,7 +165,7 @@ function sse_bulk_cleanup_exports_handler(): void {
  */
 function sse_delete_export_file_handler( string $file ): void {
 	sse_log( 'Scheduled deletion handler triggered for file: ' . $file, 'info' );
-	
+
 	// Validate that this is actually an export file before deletion.
 	$filename = basename( $file );
 

includes/download.php

@@ -143,7 +143,7 @@ function sse_set_download_headers( string $filename, int $filesize ): void {
 			$content_type = 'application/octet-stream';
 			break;
 	}
-	
+
 	// Security: Set headers to prevent XSS and ensure proper download behavior.
 	header( 'Content-Type: ' . $content_type );
 	header( 'Content-Disposition: attachment; filename="' . esc_attr( $filename ) . '"' );
@@ -153,7 +153,7 @@ function sse_set_download_headers( string $filename, int $filesize ): void {
 	header( 'Expires: 0' );
 	header( 'X-Content-Type-Options: nosniff' ); // Security: Prevent MIME sniffing.
 	header( 'X-Frame-Options: DENY' ); // Security: Prevent framing.
-	
+
 	// Disable output buffering for large files.
 	if ( ob_get_level() ) {
 		ob_end_clean();
@@ -176,18 +176,18 @@ function sse_validate_file_output_security( string $filepath ): string {
 		sse_log( 'Security: Blocked attempt to serve file with invalid extension: ' . pathinfo( $filepath, PATHINFO_EXTENSION ), 'security' );
 		wp_die( esc_html__( 'Access denied - invalid file type.', 'enginescript-site-exporter' ) );
 	}
-	
+
 	// Security: Ensure file is within our controlled directory before serving.
 	$upload_dir      = wp_upload_dir();
 	$export_dir      = trailingslashit( $upload_dir['basedir'] ) . SSE_EXPORT_DIR_NAME;
 	$real_export_dir = realpath( $export_dir );
 	$real_file_path  = realpath( $filepath );
-	
+
 	if ( false === $real_export_dir || false === $real_file_path || 0 !== strpos( $real_file_path, $real_export_dir ) ) {
 		sse_log( 'Security: File not within controlled export directory: ' . $filepath, 'security' );
 		wp_die( esc_html__( 'Access denied.', 'enginescript-site-exporter' ) );
 	}
-	
+
 	return $real_file_path;
 }
 
@@ -203,14 +203,14 @@ function sse_validate_file_output_security( string $filepath ): string {
 function sse_output_file_content( string $filepath, string $filename ): void {
 	// Security: Validate and resolve to realpath before any filesystem access.
 	$resolved_path = sse_validate_file_output_security( $filepath );
-	
+
 	// Security: Use resolved path (from realpath) for all filesystem operations to prevent SSRF/TOCTOU.
 	if ( function_exists( 'readfile' ) && is_readable( $resolved_path ) && is_file( $resolved_path ) ) {
 		readfile( $resolved_path ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_readfile -- Security validated export file download.
 		sse_log( 'Secure file download served via readfile: ' . $filename, 'info' );
 		exit; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- Required to terminate script after file download.
 	}
-	
+
 	sse_log( 'Failed to serve secure file download: ' . $filename, 'error' );
 	wp_die( esc_html__( 'Unable to serve file download.', 'enginescript-site-exporter' ) );
 }
@@ -219,13 +219,13 @@ function sse_output_file_content( string $filepath, string $filename ): void {
  * Serves a file download with enhanced security validation.
  *
  * @since 2.0.0
- * @param array $file_data Validated file information array.
+ * @param array{filename: string, filesize: int, filepath: string} $file_data Validated file information array.
  * @return void
  */
 function sse_serve_file_download( array $file_data ): void {
 	// Set download headers.
 	sse_set_download_headers( $file_data['filename'], $file_data['filesize'] );
-	
+
 	// Output file content (includes final security validation before readfile).
 	sse_output_file_content( $file_data['filepath'], $file_data['filename'] );
 }

includes/export.php

@@ -54,12 +54,12 @@ function sse_handle_export(): void {
 		}
 
 		sse_cleanup_files( [ $database_file['filepath'] ] );
-		
+
 		sse_schedule_export_cleanup( $zip_result['filepath'] );
-		
+
 		// Schedule a bulk cleanup sweep in case individual files were missed.
 		sse_schedule_bulk_cleanup();
-		
+
 		sse_show_success_notice( $zip_result );
 	} finally {
 		// Always release the lock and clean up user preferences.
@@ -100,7 +100,7 @@ function sse_validate_export_request(): bool { // phpcs:ignore WordPress.Securit
  * Sets up export directories and returns path information.
  *
  * @since 1.0.0
- * @return array|WP_Error Array of paths on success, WP_Error on failure.
+ * @return array{export_dir: string, export_url: string, export_dir_name: string}|WP_Error Array of paths on success, WP_Error on failure.
  */
 function sse_setup_export_directories() {
 	$upload_dir = wp_upload_dir();
@@ -235,7 +235,7 @@ function sse_get_safe_wp_cli_path() {
  *
  * @since 1.0.0
  * @param string $export_dir The directory to save the database dump.
- * @return array|WP_Error Array with file info on success, WP_Error on failure.
+ * @return array{filename: string, filepath: string}|WP_Error Array with file info on success, WP_Error on failure.
  */
 function sse_export_database( string $export_dir ) {
 	$site_name   = sanitize_file_name( get_bloginfo( 'name' ) );

includes/security.php

@@ -112,7 +112,7 @@ function sse_validate_file_extension( string $file_path ): bool {
 		sse_log( 'Rejected file access - invalid extension: ' . $file_extension, 'security' );
 		return false;
 	}
-	
+
 	return true;
 }
 
@@ -180,7 +180,7 @@ function sse_validate_filepath( string $file_path, string $base_dir ): bool {
  *
  * @since 2.0.0
  * @param string $filename The filename to validate.
- * @return array|WP_Error Result array with file data or WP_Error on failure.
+ * @return array{filepath: string, filename: string, filesize: int}|WP_Error Result array with file data or WP_Error on failure.
  */
 function sse_validate_export_file_for_download( string $filename ) {
 	$basic_validation = sse_validate_basic_export_file( $filename );
@@ -211,7 +211,7 @@ function sse_validate_export_file_for_download( string $filename ) {
  *
  * @since 2.0.0
  * @param string $filename The filename to validate.
- * @return array|WP_Error Result array with file data or WP_Error on failure.
+ * @return array{filepath: string, filename: string}|WP_Error Result array with file data or WP_Error on failure.
  */
 function sse_validate_basic_export_file( string $filename ) {
 	$basic_checks = sse_validate_filename_format( $filename );

js/admin.js

@@ -1,10 +1,10 @@
-/**
+/*
  * EngineScript Site Exporter — Admin Scripts
  *
  * Enqueued only on the Site Exporter admin page (tools_page_enginescript-site-exporter).
  *
- * @package EngineScript_Site_Exporter
- * @since   2.1.0
+ * Package: EngineScript_Site_Exporter
+ * Since:   2.1.0
  */
 
 ( function () {

readme.txt

@@ -125,6 +125,10 @@ along with this program.  If not, see <https://www.gnu.org/licenses/>.
 * **PHP 7.4**: Added type declarations (parameter and return types) to all functions
 * **PHP 7.4**: Standardized all `array()` to short `[]` syntax
 * **PHP 7.4**: Applied `??=` null coalescing assignment and `?:` Elvis operator
+* **PHP 7.4**: Added PHPStan `array{}` shape annotations to all functions with untyped array params/returns
+* **Code Quality**: Removed trailing whitespace across 5 include files
+* **Code Quality**: Converted `admin.js` file header to plain block comment (avoids TSDoc linter false positives)
+* **Code Quality**: Extracted `sse_cleanup_expired_export_file()` from bulk cleanup handler to reduce cyclomatic/NPath complexity
 
 = 2.0.0 =
 * **Critical Fix**: Fixed bug where automatic export file cleanup via WordPress cron was completely broken due to referer validation blocking cron-triggered deletions