<?php
declare(strict_types=1);

namespace WebCalendar\WP\Admin;

defined( 'ABSPATH' ) || exit;

/**
 * Human-readable messages for PHP file-upload failures.
 *
 * Turns the terse PHP `UPLOAD_ERR_*` codes (and the "POST body too large"
 * case, where PHP silently discards `$_POST`/`$_FILES`) into messages that
 * state the current limits and how to work around them without server access.
 *
 * All methods are pure functions of their arguments — callers pass the ini
 * values (`ini_get('upload_max_filesize')`, etc.) and request context — so the
 * formatting is fully unit-testable.
 */
final class UploadError {

	/**
	 * Message for a PHP upload error code.
	 *
	 * @param int    $code       One of the UPLOAD_ERR_* constants.
	 * @param string $upload_max The `upload_max_filesize` ini value (e.g. "2M").
	 * @param string $post_max   The `post_max_size` ini value (e.g. "8M").
	 * @return string
	 */
	public static function for_code( int $code, string $upload_max = '', string $post_max = '' ): string {
		$upload_max = '' !== $upload_max ? $upload_max : '?';
		$post_max   = '' !== $post_max ? $post_max : '?';

		switch ( $code ) {
			case UPLOAD_ERR_INI_SIZE:
				return sprintf(
					/* translators: 1: upload_max_filesize, 2: post_max_size, 3: remediation guidance. */
					__( 'The file exceeds the server upload limit (%1$s per file, %2$s per request). %3$s', 'agenticdaisy-calendar' ),
					$upload_max,
					$post_max,
					self::remediation()
				);
			case UPLOAD_ERR_FORM_SIZE:
				return __( 'The file exceeds the maximum size allowed by the form.', 'agenticdaisy-calendar' );
			case UPLOAD_ERR_PARTIAL:
				return __( 'The file was only partially uploaded. Please try again.', 'agenticdaisy-calendar' );
			case UPLOAD_ERR_NO_FILE:
				return __( 'No file was selected. Please choose a file to import.', 'agenticdaisy-calendar' );
			case UPLOAD_ERR_NO_TMP_DIR:
				return __( 'Server configuration error: missing temporary upload directory.', 'agenticdaisy-calendar' );
			case UPLOAD_ERR_CANT_WRITE:
				return __( 'Server error: failed to write the uploaded file to disk.', 'agenticdaisy-calendar' );
			case UPLOAD_ERR_EXTENSION:
				return __( 'A server extension blocked the upload.', 'agenticdaisy-calendar' );
			default:
				return sprintf(
					/* translators: %d: PHP upload error code. */
					__( 'Upload failed with error code %d.', 'agenticdaisy-calendar' ),
					$code
				);
		}
	}

	/**
	 * Whether a POST request body exceeded `post_max_size`.
	 *
	 * When it does, PHP discards `$_POST` and `$_FILES` entirely, so the form
	 * looks like it was never submitted — this detects that case so a helpful
	 * message can be shown instead of a misleading "no file selected".
	 *
	 * @param string $request_method The HTTP method (e.g. `$_SERVER['REQUEST_METHOD']`).
	 * @param int    $content_length The request body size (`$_SERVER['CONTENT_LENGTH']`).
	 * @param int    $post_max_bytes `post_max_size` in bytes (see self::bytes()).
	 * @return bool
	 */
	public static function post_max_exceeded( string $request_method, int $content_length, int $post_max_bytes ): bool {
		return 'POST' === strtoupper( $request_method )
			&& $post_max_bytes > 0
			&& $content_length > $post_max_bytes;
	}

	/**
	 * Message for the "POST body too large" case.
	 *
	 * @param string $post_max The `post_max_size` ini value (e.g. "8M").
	 * @return string
	 */
	public static function post_max_message( string $post_max = '' ): string {
		return sprintf(
			/* translators: 1: post_max_size, 2: remediation guidance. */
			__( 'The upload was too large for this server (over the %1$s per-request limit). %2$s', 'agenticdaisy-calendar' ),
			'' !== $post_max ? $post_max : '?',
			self::remediation()
		);
	}

	/**
	 * Read a PHP size directive as a string, normalising the `false` that
	 * `ini_get()` returns for unknown directives to an empty string.
	 *
	 * @param string $directive e.g. "upload_max_filesize".
	 * @return string
	 */
	public static function ini_size( string $directive ): string {
		$value = ini_get( $directive );
		return is_string( $value ) ? $value : '';
	}

	/**
	 * Convert a PHP shorthand size ("2M", "8M", "1G", "512K", "1024") to bytes.
	 *
	 * @param string $shorthand The ini shorthand value.
	 * @return int Bytes (0 when unparseable/empty).
	 */
	public static function bytes( string $shorthand ): int {
		$shorthand = trim( $shorthand );
		if ( '' === $shorthand ) {
			return 0;
		}
		$value = (int) $shorthand;
		$unit  = strtolower( $shorthand[ strlen( $shorthand ) - 1 ] );

		return match ( $unit ) {
			'g'     => $value * 1024 * 1024 * 1024,
			'm'     => $value * 1024 * 1024,
			'k'     => $value * 1024,
			default => $value,
		};
	}

	/**
	 * Shared remediation guidance: how to raise the limit or avoid the upload.
	 *
	 * @return string
	 */
	private static function remediation(): string {
		return __( 'To fix it: raise upload_max_filesize and post_max_size — in php.ini, in a .user.ini file in the site root on php-fpm hosts, or in .htaccess on Apache — or ask your host. If you cannot change those, upload the file to your server (for example into wp-content/uploads) with SFTP or your host\'s File Manager and choose it under "Import a file already on the server" below, or run "wp webcal migrate <file.sql>" with WP-CLI. Both bypass the upload limit entirely.', 'agenticdaisy-calendar' );
	}
}