/**
 * 全体注册用户单文件头像系统。
 *
 * 功能：
 * - 适用于所有 WordPress 注册用户，不限制角色；
 * - 每个账号始终只有一个固定 PNG 头像文件；
 * - 文件名由登录用户名的 SHA-256 哈希确定；
 * - 没有上传头像时，生成 36 色之一的默认头像；
 * - 上传新头像时直接覆盖同一个文件；
 * - 恢复默认头像时重新生成彩色默认头像并覆盖；
 * - 不创建媒体附件，不进入媒体库；
 * - 删除账号时自动删除对应头像文件；
 * - 支持后台个人资料页面；
 * - 支持前台短代码：[qmc_avatar_form]
 */


/* =========================================================
 * 一、基础设置
 * =========================================================
 */

/*
 * 默认透明头像在 uploads 目录中的相对路径。
 *
 * 对应网址：
 * https://qimuchuan.life/wp-content/uploads/2026/07/默认头像.png
 */
if ( ! defined( 'QMCFA_TEMPLATE_RELATIVE_PATH' ) ) {
	define(
		'QMCFA_TEMPLATE_RELATIVE_PATH',
		'2026/07/默认头像.png'
	);
}


/*
 * 用户头像保存目录：
 *
 * wp-content/uploads/qmc-avatars/
 */
if ( ! defined( 'QMCFA_DIRECTORY_NAME' ) ) {
	define(
		'QMCFA_DIRECTORY_NAME',
		'qmc-avatars'
	);
}


/*
 * 所有头像统一处理为 256 × 256 PNG。
 */
if ( ! defined( 'QMCFA_IMAGE_SIZE' ) ) {
	define(
		'QMCFA_IMAGE_SIZE',
		256
	);
}


/*
 * 上传文件最大 2 MB。
 */
if ( ! defined( 'QMCFA_MAX_FILE_SIZE' ) ) {
	define(
		'QMCFA_MAX_FILE_SIZE',
		2 * MB_IN_BYTES
	);
}


/*
 * 上传原图最大边长。
 */
if ( ! defined( 'QMCFA_MAX_DIMENSION' ) ) {
	define(
		'QMCFA_MAX_DIMENSION',
		4096
	);
}


/*
 * 记录用户当前头像类型。
 *
 * 可选值：
 * default
 * custom
 */
if ( ! defined( 'QMCFA_MODE_META_KEY' ) ) {
	define(
		'QMCFA_MODE_META_KEY',
		'_qmc_file_avatar_mode'
	);
}


/*
 * 旧头像代码曾使用的媒体附件字段。
 *
 * 如果该字段仍存在，新系统在用户保存头像时，
 * 会尝试安全清理对应的旧媒体附件。
 */
if ( ! defined( 'QMCFA_LEGACY_META_KEY' ) ) {
	define(
		'QMCFA_LEGACY_META_KEY',
		'_qmc_avatar_attachment_id'
	);
}


/* =========================================================
 * 二、用户与路径辅助函数
 * =========================================================
 */

/**
 * 判断是否为有效的 WordPress 注册用户。
 *
 * 管理员、编辑、作者、投稿者、订阅者等
 * 所有有效注册用户都返回 true。
 */
function qmcfa_is_member( $user ) {

	if ( ! $user instanceof WP_User ) {
		return false;
	}

	return (
		$user->exists()
		&& (int) $user->ID > 0
	);
}


/**
 * 根据 WordPress 头像函数可能收到的参数解析用户。
 */
function qmcfa_resolve_user( $id_or_email ) {

	if ( $id_or_email instanceof WP_User ) {
		return $id_or_email;
	}


	if ( $id_or_email instanceof WP_Comment ) {

		if ( (int) $id_or_email->user_id > 0 ) {
			return get_user_by(
				'id',
				(int) $id_or_email->user_id
			);
		}

		if (
			is_email(
				$id_or_email->comment_author_email
			)
		) {
			return get_user_by(
				'email',
				$id_or_email->comment_author_email
			);
		}

		return false;
	}


	if ( $id_or_email instanceof WP_Post ) {
		return get_user_by(
			'id',
			(int) $id_or_email->post_author
		);
	}


	if ( is_numeric( $id_or_email ) ) {
		return get_user_by(
			'id',
			absint( $id_or_email )
		);
	}


	if (
		is_string( $id_or_email )
		&& is_email( $id_or_email )
	) {
		return get_user_by(
			'email',
			$id_or_email
		);
	}


	if ( is_object( $id_or_email ) ) {

		if ( ! empty( $id_or_email->user_id ) ) {
			return get_user_by(
				'id',
				absint( $id_or_email->user_id )
			);
		}

		if ( ! empty( $id_or_email->ID ) ) {
			return get_user_by(
				'id',
				absint( $id_or_email->ID )
			);
		}
	}

	return false;
}


/**
 * 规范化登录用户名。
 *
 * 该算法与旧版保持一致，
 * 所以现有头像文件名不会改变。
 */
function qmcfa_normalize_login( $user_login ) {

	$user_login = (string) $user_login;

	if ( function_exists( 'mb_strtolower' ) ) {
		return mb_strtolower(
			$user_login,
			'UTF-8'
		);
	}

	return strtolower( $user_login );
}


/**
 * 根据登录用户名生成固定文件索引。
 */
function qmcfa_get_login_hash( $user_login ) {

	return hash(
		'sha256',
		'qmc-single-avatar:'
			. qmcfa_normalize_login(
				$user_login
			)
	);
}


/**
 * 对网址相对路径中的每一级进行编码。
 */
function qmcfa_encode_relative_url( $relative_path ) {

	$parts = explode(
		'/',
		str_replace(
			'\\',
			'/',
			$relative_path
		)
	);

	$parts = array_map(
		'rawurlencode',
		$parts
	);

	return implode(
		'/',
		$parts
	);
}


/**
 * 获取指定用户名对应的头像路径与网址。
 */
function qmcfa_get_paths_for_login( $user_login ) {

	$uploads = wp_upload_dir(
		null,
		false
	);

	if ( ! empty( $uploads['error'] ) ) {
		return new WP_Error(
			'qmcfa_upload_directory_error',
			$uploads['error']
		);
	}


	$directory = trailingslashit(
		$uploads['basedir']
	) . QMCFA_DIRECTORY_NAME;


	if (
		! is_dir( $directory )
		&& ! wp_mkdir_p( $directory )
	) {
		return new WP_Error(
			'qmcfa_create_directory_failed',
			'无法创建用户头像目录。'
		);
	}


	/*
	 * 防止目录直接显示文件列表。
	 */
	$index_file = trailingslashit(
		$directory
	) . 'index.php';

	if ( ! file_exists( $index_file ) ) {
		@file_put_contents(
			$index_file,
			"<?php\n// Silence is golden.\n"
		);
	}


	$hash = qmcfa_get_login_hash(
		$user_login
	);

	$filename =
		'avatar-'
		. $hash
		. '.png';


	$avatar_path = trailingslashit(
		$directory
	) . $filename;


	$avatar_url = trailingslashit(
		$uploads['baseurl']
	) . QMCFA_DIRECTORY_NAME
		. '/'
		. rawurlencode( $filename );


	$template_path = path_join(
		$uploads['basedir'],
		QMCFA_TEMPLATE_RELATIVE_PATH
	);


	$template_url = trailingslashit(
		$uploads['baseurl']
	) . qmcfa_encode_relative_url(
		QMCFA_TEMPLATE_RELATIVE_PATH
	);


	return array(
		'directory'     => $directory,
		'filename'      => $filename,
		'path'          => $avatar_path,
		'url'           => $avatar_url,
		'template_path' => $template_path,
		'template_url'  => $template_url,
	);
}


/**
 * 获取指定用户对应的头像路径。
 */
function qmcfa_get_user_paths( $user ) {

	if ( ! qmcfa_is_member( $user ) ) {
		return new WP_Error(
			'qmcfa_invalid_user',
			'用户信息无效。'
		);
	}

	return qmcfa_get_paths_for_login(
		$user->user_login
	);
}


/**
 * 在头像目录中创建唯一临时文件路径。
 */
function qmcfa_create_temp_path( $directory ) {

	for ( $attempt = 0; $attempt < 10; $attempt++ ) {

		$filename =
			'.qmc-avatar-temp-'
			. wp_generate_password(
				20,
				false,
				false
			)
			. '.png';

		$path = trailingslashit(
			$directory
		) . $filename;

		if ( ! file_exists( $path ) ) {
			return $path;
		}
	}

	return false;
}


/* =========================================================
 * 三、36 种固定颜色
 * =========================================================
 */

/**
 * 根据登录用户名确定 0 至 35 的颜色编号。
 */
function qmcfa_get_color_index( $user_login ) {

	$hash = hash(
		'sha256',
		'qmc-avatar-color:'
			. qmcfa_normalize_login(
				$user_login
			)
	);

	$number = hexdec(
		substr(
			$hash,
			0,
			8
		)
	);

	return (int) ( $number % 36 );
}


/**
 * HSL 转 RGB 的辅助函数。
 */
function qmcfa_hue_component(
	$p,
	$q,
	$t
) {
	if ( $t < 0 ) {
		$t += 1;
	}

	if ( $t > 1 ) {
		$t -= 1;
	}

	if ( $t < 1 / 6 ) {
		return $p
			+ (
				$q - $p
			) * 6 * $t;
	}

	if ( $t < 1 / 2 ) {
		return $q;
	}

	if ( $t < 2 / 3 ) {
		return $p
			+ (
				$q - $p
			) * (
				2 / 3 - $t
			) * 6;
	}

	return $p;
}


/**
 * 把 HSL 颜色转换为 RGB。
 */
function qmcfa_hsl_to_rgb(
	$hue,
	$saturation,
	$lightness
) {
	$h = (
		(float) $hue % 360
	) / 360;

	$s = max(
		0,
		min(
			1,
			(float) $saturation
		)
	);

	$l = max(
		0,
		min(
			1,
			(float) $lightness
		)
	);


	if ( 0.0 === $s ) {
		$value = (int) round(
			$l * 255
		);

		return array(
			$value,
			$value,
			$value,
		);
	}


	$q = $l < 0.5
		? $l * ( 1 + $s )
		: $l + $s - $l * $s;

	$p = 2 * $l - $q;


	$r = qmcfa_hue_component(
		$p,
		$q,
		$h + 1 / 3
	);

	$g = qmcfa_hue_component(
		$p,
		$q,
		$h
	);

	$b = qmcfa_hue_component(
		$p,
		$q,
		$h - 1 / 3
	);


	return array(
		(int) round( $r * 255 ),
		(int) round( $g * 255 ),
		(int) round( $b * 255 ),
	);
}


/**
 * 获取用户固定的 RGB 颜色。
 *
 * 共 36 种色相，每种相隔 10 度。
 */
function qmcfa_get_user_rgb( $user_login ) {

	$index = qmcfa_get_color_index(
		$user_login
	);

	$hue = $index * 10;

	return qmcfa_hsl_to_rgb(
		$hue,
		0.82,
		0.45
	);
}


/* =========================================================
 * 四、原子覆盖头像文件
 * =========================================================
 */

/**
 * 使用准备好的临时文件安全替换正式头像。
 *
 * 新文件处理成功后才会替换旧文件。
 */
function qmcfa_atomic_replace(
	$prepared_path,
	$destination_path
) {
	if (
		! is_string( $prepared_path )
		|| ! file_exists( $prepared_path )
	) {
		return new WP_Error(
			'qmcfa_missing_prepared_file',
			'处理后的头像文件不存在。'
		);
	}


	$backup_path = '';

	if ( file_exists( $destination_path ) ) {

		$backup_path =
			$destination_path
			. '.backup-'
			. wp_generate_password(
				12,
				false,
				false
			);

		if (
			! @rename(
				$destination_path,
				$backup_path
			)
		) {
			return new WP_Error(
				'qmcfa_backup_failed',
				'无法备份原头像文件。'
			);
		}
	}


	if (
		! @rename(
			$prepared_path,
			$destination_path
		)
	) {
		if (
			$backup_path
			&& file_exists( $backup_path )
		) {
			@rename(
				$backup_path,
				$destination_path
			);
		}

		return new WP_Error(
			'qmcfa_replace_failed',
			'无法保存新的头像文件。'
		);
	}


	if (
		$backup_path
		&& file_exists( $backup_path )
	) {
		wp_delete_file(
			$backup_path
		);
	}


	$permissions = defined(
		'FS_CHMOD_FILE'
	)
		? FS_CHMOD_FILE
		: 0644;

	@chmod(
		$destination_path,
		$permissions
	);

	clearstatcache(
		true,
		$destination_path
	);

	return true;
}


/* =========================================================
 * 五、生成彩色默认头像
 * =========================================================
 */

/**
 * 使用 GD 生成彩色默认头像。
 */
function qmcfa_generate_default_with_gd(
	$template_path,
	$output_path,
	$rgb
) {
	if (
		! function_exists( 'imagecreatefrompng' )
		|| ! function_exists( 'imagepng' )
	) {
		return new WP_Error(
			'qmcfa_gd_unavailable',
			'服务器没有启用 GD 图片扩展。'
		);
	}


	$source = @imagecreatefrompng(
		$template_path
	);

	if ( ! $source ) {
		return new WP_Error(
			'qmcfa_template_load_failed',
			'无法读取默认透明头像。'
		);
	}


	$size = QMCFA_IMAGE_SIZE;

	$destination = imagecreatetruecolor(
		$size,
		$size
	);

	if ( ! $destination ) {
		imagedestroy( $source );

		return new WP_Error(
			'qmcfa_canvas_failed',
			'无法创建头像画布。'
		);
	}


	imagealphablending(
		$destination,
		false
	);

	imagesavealpha(
		$destination,
		true
	);


	$transparent = imagecolorallocatealpha(
		$destination,
		0,
		0,
		0,
		127
	);

	imagefill(
		$destination,
		0,
		0,
		$transparent
	);


	$source_width = imagesx(
		$source
	);

	$source_height = imagesy(
		$source
	);


	$copied = imagecopyresampled(
		$destination,
		$source,
		0,
		0,
		0,
		0,
		$size,
		$size,
		$source_width,
		$source_height
	);

	imagedestroy( $source );


	if ( ! $copied ) {
		imagedestroy( $destination );

		return new WP_Error(
			'qmcfa_resize_failed',
			'默认头像缩放失败。'
		);
	}


	$red   = (int) $rgb[0];
	$green = (int) $rgb[1];
	$blue  = (int) $rgb[2];

	/*
	 * 按透明度缓存颜色，
	 * 从而保留图案的抗锯齿边缘。
	 */
	$color_cache = array();


	for ( $y = 0; $y < $size; $y++ ) {

		for ( $x = 0; $x < $size; $x++ ) {

			$pixel = imagecolorat(
				$destination,
				$x,
				$y
			);

			$alpha = (
				$pixel >> 24
			) & 0x7F;


			if ( $alpha >= 127 ) {
				continue;
			}


			if (
				! isset(
					$color_cache[ $alpha ]
				)
			) {
				$color_cache[ $alpha ] =
					imagecolorallocatealpha(
						$destination,
						$red,
						$green,
						$blue,
						$alpha
					);
			}


			imagesetpixel(
				$destination,
				$x,
				$y,
				$color_cache[ $alpha ]
			);
		}
	}


	$saved = imagepng(
		$destination,
		$output_path,
		9
	);

	imagedestroy( $destination );


	if ( ! $saved ) {
		return new WP_Error(
			'qmcfa_png_save_failed',
			'彩色默认头像保存失败。'
		);
	}

	return true;
}


/**
 * 使用 Imagick 生成彩色默认头像。
 *
 * 仅在 GD 不可用时使用。
 */
function qmcfa_generate_default_with_imagick(
	$template_path,
	$output_path,
	$rgb
) {
	if ( ! class_exists( 'Imagick' ) ) {
		return new WP_Error(
			'qmcfa_imagick_unavailable',
			'服务器没有可用的图片处理扩展。'
		);
	}


	try {
		$image = new Imagick(
			$template_path
		);

		$image->setImageFormat(
			'png'
		);

		$image->setImageAlphaChannel(
			Imagick::ALPHACHANNEL_ACTIVATE
		);

		$image->cropThumbnailImage(
			QMCFA_IMAGE_SIZE,
			QMCFA_IMAGE_SIZE
		);


		$iterator = $image->getPixelIterator();

		foreach ( $iterator as $row ) {

			foreach ( $row as $pixel ) {

				$alpha = $pixel->getColorValue(
					Imagick::COLOR_ALPHA
				);

				if ( $alpha <= 0.001 ) {
					continue;
				}


				$pixel->setColor(
					sprintf(
						'rgb(%d,%d,%d)',
						(int) $rgb[0],
						(int) $rgb[1],
						(int) $rgb[2]
					)
				);

				$pixel->setColorValue(
					Imagick::COLOR_ALPHA,
					$alpha
				);
			}

			$iterator->syncIterator();
		}


		$image->setImageFormat(
			'png'
		);

		$saved = $image->writeImage(
			$output_path
		);

		$image->clear();
		$image->destroy();


		if ( ! $saved ) {
			return new WP_Error(
				'qmcfa_imagick_save_failed',
				'彩色默认头像保存失败。'
			);
		}

		return true;

	} catch ( Exception $exception ) {

		return new WP_Error(
			'qmcfa_imagick_exception',
			$exception->getMessage()
		);
	}
}


/**
 * 为指定注册用户生成彩色默认头像。
 */
function qmcfa_generate_default_avatar( $user_id ) {

	$user = get_userdata(
		absint( $user_id )
	);

	if ( ! qmcfa_is_member( $user ) ) {
		return new WP_Error(
			'qmcfa_invalid_member',
			'当前用户不是有效的注册用户。'
		);
	}


	$paths = qmcfa_get_user_paths(
		$user
	);

	if ( is_wp_error( $paths ) ) {
		return $paths;
	}


	if (
		! file_exists(
			$paths['template_path']
		)
	) {
		return new WP_Error(
			'qmcfa_missing_template',
			'没有找到默认头像 PNG：'
				. $paths['template_path']
		);
	}


	$temp_path = qmcfa_create_temp_path(
		$paths['directory']
	);

	if ( ! $temp_path ) {
		return new WP_Error(
			'qmcfa_temp_path_failed',
			'无法创建临时头像文件。'
		);
	}


	$rgb = qmcfa_get_user_rgb(
		$user->user_login
	);


	if (
		function_exists( 'imagecreatefrompng' )
		&& function_exists( 'imagepng' )
	) {
		$result =
			qmcfa_generate_default_with_gd(
				$paths['template_path'],
				$temp_path,
				$rgb
			);
	} else {
		$result =
			qmcfa_generate_default_with_imagick(
				$paths['template_path'],
				$temp_path,
				$rgb
			);
	}


	if ( is_wp_error( $result ) ) {

		if ( file_exists( $temp_path ) ) {
			wp_delete_file(
				$temp_path
			);
		}

		return $result;
	}


	$replaced = qmcfa_atomic_replace(
		$temp_path,
		$paths['path']
	);

	if ( is_wp_error( $replaced ) ) {

		if ( file_exists( $temp_path ) ) {
			wp_delete_file(
				$temp_path
			);
		}

		return $replaced;
	}


	update_user_meta(
		$user->ID,
		QMCFA_MODE_META_KEY,
		'default'
	);

	return true;
}


/* =========================================================
 * 六、处理用户上传头像
 * =========================================================
 */

/**
 * 判断表单是否实际上传了文件。
 */
function qmcfa_has_uploaded_file( $field_name ) {

	if (
		empty( $_FILES[ $field_name ] )
		|| empty(
			$_FILES[ $field_name ]['name']
		)
	) {
		return false;
	}

	if (
		isset(
			$_FILES[ $field_name ]['error']
		)
		&& UPLOAD_ERR_NO_FILE
			=== (int)
				$_FILES[ $field_name ]['error']
	) {
		return false;
	}

	return true;
}


/**
 * 清理旧头像代码产生的媒体附件。
 *
 * 只有能确认附件属于该用户时才删除。
 */
function qmcfa_cleanup_legacy_attachment(
	$user_id
) {
	$user_id = absint( $user_id );

	$attachment_id = absint(
		get_user_meta(
			$user_id,
			QMCFA_LEGACY_META_KEY,
			true
		)
	);

	if ( ! $attachment_id ) {
		return;
	}


	$can_delete = false;

	if (
		'attachment'
		=== get_post_type(
			$attachment_id
		)
		&& wp_attachment_is_image(
			$attachment_id
		)
	) {
		$post_author = absint(
			get_post_field(
				'post_author',
				$attachment_id
			)
		);

		$owner_meta = absint(
			get_post_meta(
				$attachment_id,
				'_qmc_avatar_owner_user_id',
				true
			)
		);

		if (
			$post_author === $user_id
			|| $owner_meta === $user_id
		) {
			$can_delete = true;
		}
	}


	if ( $can_delete ) {
		wp_delete_attachment(
			$attachment_id,
			true
		);
	}


	delete_user_meta(
		$user_id,
		QMCFA_LEGACY_META_KEY
	);
}


/**
 * 验证、裁剪并保存用户上传的头像。
 */
function qmcfa_save_uploaded_avatar(
	$user_id,
	$field_name
) {
	$user = get_userdata(
		absint( $user_id )
	);

	if ( ! qmcfa_is_member( $user ) ) {
		return new WP_Error(
			'qmcfa_invalid_user_upload',
			'当前账号不能上传头像。'
		);
	}


	if (
		! qmcfa_has_uploaded_file(
			$field_name
		)
	) {
		return new WP_Error(
			'qmcfa_no_file',
			'没有选择头像文件。'
		);
	}


	$file = $_FILES[ $field_name ];


	if (
		isset( $file['error'] )
		&& UPLOAD_ERR_OK
			!== (int) $file['error']
	) {
		return new WP_Error(
			'qmcfa_upload_error',
			'头像上传失败，请重新选择文件。'
		);
	}


	if (
		empty( $file['size'] )
		|| (int) $file['size']
			> QMCFA_MAX_FILE_SIZE
	) {
		return new WP_Error(
			'qmcfa_file_too_large',
			'头像文件不能超过 2 MB。'
		);
	}


	if (
		empty( $file['tmp_name'] )
		|| ! is_uploaded_file(
			$file['tmp_name']
		)
	) {
		return new WP_Error(
			'qmcfa_invalid_upload',
			'没有检测到有效的上传文件。'
		);
	}


	$allowed_mimes = array(
		'jpg|jpeg|jpe' => 'image/jpeg',
		'png'          => 'image/png',
		'webp'         => 'image/webp',
	);


	$file_check = wp_check_filetype_and_ext(
		$file['tmp_name'],
		$file['name'],
		$allowed_mimes
	);


	$allowed_types = array(
		'image/jpeg',
		'image/png',
		'image/webp',
	);


	if (
		empty( $file_check['type'] )
		|| ! in_array(
			$file_check['type'],
			$allowed_types,
			true
		)
	) {
		return new WP_Error(
			'qmcfa_invalid_file_type',
			'只允许上传 JPG、PNG 或 WebP 图片。'
		);
	}


	$image_info = function_exists(
		'wp_getimagesize'
	)
		? wp_getimagesize(
			$file['tmp_name']
		)
		: @getimagesize(
			$file['tmp_name']
		);


	if ( ! is_array( $image_info ) ) {
		return new WP_Error(
			'qmcfa_not_an_image',
			'上传的文件不是有效图片。'
		);
	}


	$width = isset( $image_info[0] )
		? absint( $image_info[0] )
		: 0;

	$height = isset( $image_info[1] )
		? absint( $image_info[1] )
		: 0;


	if (
		! $width
		|| ! $height
		|| $width > QMCFA_MAX_DIMENSION
		|| $height > QMCFA_MAX_DIMENSION
	) {
		return new WP_Error(
			'qmcfa_invalid_dimensions',
			'图片宽度和高度必须小于 4096 像素。'
		);
	}


	$paths = qmcfa_get_user_paths(
		$user
	);

	if ( is_wp_error( $paths ) ) {
		return $paths;
	}


	$temp_path = qmcfa_create_temp_path(
		$paths['directory']
	);

	if ( ! $temp_path ) {
		return new WP_Error(
			'qmcfa_temp_file_failed',
			'无法创建临时头像文件。'
		);
	}


	$editor = wp_get_image_editor(
		$file['tmp_name']
	);

	if ( is_wp_error( $editor ) ) {
		return $editor;
	}


	/*
	 * 居中裁剪成统一正方形。
	 */
	$resized = $editor->resize(
		QMCFA_IMAGE_SIZE,
		QMCFA_IMAGE_SIZE,
		true
	);

	if ( is_wp_error( $resized ) ) {
		return $resized;
	}


	/*
	 * 最终统一保存成 PNG。
	 */
	$saved = $editor->save(
		$temp_path,
		'image/png'
	);


	if ( is_wp_error( $saved ) ) {

		if ( file_exists( $temp_path ) ) {
			wp_delete_file(
				$temp_path
			);
		}

		return $saved;
	}


	$prepared_path = isset(
		$saved['path']
	)
		? $saved['path']
		: $temp_path;


	if ( ! file_exists( $prepared_path ) ) {
		return new WP_Error(
			'qmcfa_missing_saved_image',
			'处理后的头像文件不存在。'
		);
	}


	$replaced = qmcfa_atomic_replace(
		$prepared_path,
		$paths['path']
	);


	if ( is_wp_error( $replaced ) ) {

		if ( file_exists( $prepared_path ) ) {
			wp_delete_file(
				$prepared_path
			);
		}

		return $replaced;
	}


	if (
		$temp_path !== $prepared_path
		&& file_exists( $temp_path )
	) {
		wp_delete_file(
			$temp_path
		);
	}


	update_user_meta(
		$user->ID,
		QMCFA_MODE_META_KEY,
		'custom'
	);


	qmcfa_cleanup_legacy_attachment(
		$user->ID
	);


	return true;
}


/**
 * 处理上传、恢复默认或不修改。
 */
function qmcfa_process_avatar_change(
	$user_id,
	$field_name,
	$restore_default
) {
	if (
		qmcfa_has_uploaded_file(
			$field_name
		)
	) {
		$result =
			qmcfa_save_uploaded_avatar(
				$user_id,
				$field_name
			);

		return is_wp_error( $result )
			? $result
			: 'updated';
	}


	if ( $restore_default ) {

		$result =
			qmcfa_generate_default_avatar(
				$user_id
			);

		if ( is_wp_error( $result ) ) {
			return $result;
		}


		qmcfa_cleanup_legacy_attachment(
			$user_id
		);

		return 'restored';
	}


	return 'unchanged';
}


/* =========================================================
 * 七、确保所有注册用户拥有头像文件
 * =========================================================
 */

/**
 * 如果头像文件不存在，自动生成彩色默认头像。
 */
function qmcfa_ensure_avatar_file( $user ) {

	if ( ! qmcfa_is_member( $user ) ) {
		return new WP_Error(
			'qmcfa_invalid_avatar_user',
			'头像用户无效。'
		);
	}


	$paths = qmcfa_get_user_paths(
		$user
	);

	if ( is_wp_error( $paths ) ) {
		return $paths;
	}


	if ( file_exists( $paths['path'] ) ) {
		return $paths;
	}


	$generated =
		qmcfa_generate_default_avatar(
			$user->ID
		);

	if ( is_wp_error( $generated ) ) {
		return $generated;
	}


	return qmcfa_get_user_paths(
		$user
	);
}


/* =========================================================
 * 八、接管 WordPress 头像地址
 * =========================================================
 */

add_filter(
	'pre_get_avatar_data',
	'qmcfa_replace_avatar_data',
	20,
	2
);

function qmcfa_replace_avatar_data(
	$args,
	$id_or_email
) {
	$user = qmcfa_resolve_user(
		$id_or_email
	);


	/*
	 * 只处理能够对应到注册账号的用户。
	 *
	 * 未登录访客评论仍保留 WordPress 原有头像逻辑。
	 */
	if ( ! qmcfa_is_member( $user ) ) {
		return $args;
	}


	$paths = qmcfa_ensure_avatar_file(
		$user
	);


	if ( is_wp_error( $paths ) ) {

		$fallback_paths =
			qmcfa_get_user_paths(
				$user
			);

		if (
			! is_wp_error(
				$fallback_paths
			)
		) {
			$args['url'] =
				$fallback_paths[
					'template_url'
				];

			$args['found_avatar'] = true;
		}

		return $args;
	}


	$version = file_exists(
		$paths['path']
	)
		? (int) filemtime(
			$paths['path']
		)
		: time();


	/*
	 * 文件地址不变，但 v 参数会随修改时间变化，
	 * 避免浏览器或 CDN 一直显示旧头像。
	 */
	$args['url'] = add_query_arg(
		'v',
		$version,
		set_url_scheme(
			$paths['url'],
			'https'
		)
	);

	$args['found_avatar'] = true;

	return $args;
}


/* =========================================================
 * 九、注册与角色变化时生成头像
 * =========================================================
 */

/**
 * 新账号注册后生成默认头像。
 */
add_action(
	'user_register',
	'qmcfa_generate_avatar_on_registration',
	20,
	1
);

function qmcfa_generate_avatar_on_registration(
	$user_id
) {
	$user = get_userdata(
		absint( $user_id )
	);

	if ( qmcfa_is_member( $user ) ) {
		qmcfa_generate_default_avatar(
			$user->ID
		);
	}
}


/**
 * 用户角色发生变化时检查头像文件。
 *
 * 不限制新角色是什么。
 */
add_action(
	'set_user_role',
	'qmcfa_generate_avatar_after_role_change',
	20,
	3
);

function qmcfa_generate_avatar_after_role_change(
	$user_id,
	$role,
	$old_roles
) {
	$user = get_userdata(
		absint( $user_id )
	);

	if ( ! qmcfa_is_member( $user ) ) {
		return;
	}


	$paths = qmcfa_get_user_paths(
		$user
	);

	if (
		! is_wp_error( $paths )
		&& ! file_exists(
			$paths['path']
		)
	) {
		qmcfa_generate_default_avatar(
			$user->ID
		);
	}
}


/* =========================================================
 * 十、后台个人资料头像表单
 * =========================================================
 */

/**
 * 允许个人资料表单上传文件。
 */
add_action(
	'user_edit_form_tag',
	'qmcfa_add_profile_form_enctype'
);

function qmcfa_add_profile_form_enctype() {

	echo ' enctype="multipart/form-data"';
}


add_action(
	'show_user_profile',
	'qmcfa_show_profile_fields',
	20
);

add_action(
	'edit_user_profile',
	'qmcfa_show_profile_fields',
	20
);

function qmcfa_show_profile_fields( $user ) {

	if ( ! qmcfa_is_member( $user ) ) {
		return;
	}


	$mode = get_user_meta(
		$user->ID,
		QMCFA_MODE_META_KEY,
		true
	);

	?>
	<h2>账号头像</h2>

	<table
		class="form-table"
		role="presentation"
	>

		<tr>
			<th scope="row">
				当前头像
			</th>

			<td>
				<div style="
					display:flex;
					align-items:center;
					gap:16px;
				">
					<?php
					echo get_avatar(
						$user->ID,
						96,
						'',
						$user->display_name
					);
					?>

					<p class="description">
						<?php
						if ( 'custom' === $mode ) {
							echo '当前正在使用你上传的头像。';
						} else {
							echo '当前正在使用系统分配的 36 色默认头像。';
						}
						?>
					</p>
				</div>
			</td>
		</tr>


		<tr>
			<th scope="row">
				<label for="qmcfa_avatar_file">
					上传新头像
				</label>
			</th>

			<td>
				<input
					type="file"
					id="qmcfa_avatar_file"
					name="qmcfa_avatar_file"
					accept="image/jpeg,image/png,image/webp"
				>

				<p class="description">
					支持 JPG、PNG 和 WebP，
					最大 2 MB。
					图片会居中裁剪成正方形。
					保存后直接覆盖旧头像，
					不会进入媒体库。
				</p>
			</td>
		</tr>


		<?php if ( 'custom' === $mode ) : ?>
			<tr>
				<th scope="row">
					恢复默认头像
				</th>

				<td>
					<label>
						<input
							type="checkbox"
							name="qmcfa_restore_default"
							value="1"
						>

						恢复系统分配的彩色默认头像
					</label>
				</td>
			</tr>
		<?php endif; ?>

	</table>

	<?php
	wp_nonce_field(
		'qmcfa_save_profile_'
			. $user->ID,
		'qmcfa_profile_nonce'
	);
}


/**
 * 保存后台个人资料中的头像。
 */
add_action(
	'personal_options_update',
	'qmcfa_save_profile_avatar'
);

add_action(
	'edit_user_profile_update',
	'qmcfa_save_profile_avatar'
);

function qmcfa_save_profile_avatar(
	$user_id
) {
	$user_id = absint( $user_id );


	if (
		! $user_id
		|| ! current_user_can(
			'edit_user',
			$user_id
		)
	) {
		return;
	}


	$user = get_userdata(
		$user_id
	);

	if ( ! qmcfa_is_member( $user ) ) {
		return;
	}


	if (
		empty(
			$_POST['qmcfa_profile_nonce']
		)
		|| ! wp_verify_nonce(
			sanitize_text_field(
				wp_unslash(
					$_POST[
						'qmcfa_profile_nonce'
					]
				)
			),
			'qmcfa_save_profile_'
				. $user_id
		)
	) {
		return;
	}


	$restore_default = ! empty(
		$_POST['qmcfa_restore_default']
	);


	$result = qmcfa_process_avatar_change(
		$user_id,
		'qmcfa_avatar_file',
		$restore_default
	);


	if ( is_wp_error( $result ) ) {
		wp_die(
			esc_html(
				$result->get_error_message()
			),
			'头像保存失败',
			array(
				'response'  => 400,
				'back_link' => true,
			)
		);
	}
}


/* =========================================================
 * 十一、前台头像设置短代码
 * =========================================================
 */

/*
 * 使用方法：
 *
 * 在 WordPress 页面中加入：
 *
 * [qmc_avatar_form]
 */
add_shortcode(
	'qmc_avatar_form',
	'qmcfa_frontend_form_shortcode'
);

function qmcfa_frontend_form_shortcode() {

	if ( ! is_user_logged_in() ) {
		return '<p>请先登录后设置头像。</p>';
	}


	$user = wp_get_current_user();

	if ( ! qmcfa_is_member( $user ) ) {
		return '<p>当前账号不能使用此头像设置。</p>';
	}


	$mode = get_user_meta(
		$user->ID,
		QMCFA_MODE_META_KEY,
		true
	);


	$status = isset(
		$_GET['qmcfa_avatar_status']
	)
		? sanitize_key(
			wp_unslash(
				$_GET['qmcfa_avatar_status']
			)
		)
		: '';


	$messages = array(
		'updated' =>
			'头像已经更新。',

		'restored' =>
			'已恢复系统分配的彩色默认头像。',

		'unchanged' =>
			'头像没有发生变化。',

		'error' =>
			'头像处理失败，请重新尝试。',
	);


	$error_message = '';

	if ( 'error' === $status ) {

		$error_message = get_transient(
			'qmcfa_avatar_error_'
				. $user->ID
		);

		delete_transient(
			'qmcfa_avatar_error_'
				. $user->ID
		);
	}


	ob_start();


	if ( isset( $messages[ $status ] ) ) {
		?>
		<div
			class="qmcfa-avatar-message<?php
				echo 'error' === $status
					? ' is-error'
					: '';
			?>"
		>
			<?php
			echo esc_html(
				$error_message
					? $error_message
					: $messages[ $status ]
			);
			?>
		</div>
		<?php
	}

	?>
	<div class="qmcfa-avatar-form-wrap">

		<div class="qmcfa-avatar-current">

			<?php
			echo get_avatar(
				$user->ID,
				120,
				'',
				$user->display_name
			);
			?>

			<div>
				<strong>当前头像</strong>

				<p>
					<?php
					if ( 'custom' === $mode ) {
						echo '正在使用你上传的头像。';
					} else {
						echo '正在使用系统分配的 36 色默认头像。';
					}
					?>
				</p>
			</div>

		</div>


		<form
			method="post"
			enctype="multipart/form-data"
			action="<?php
				echo esc_url(
					admin_url(
						'admin-post.php'
					)
				);
			?>"
		>
			<input
				type="hidden"
				name="action"
				value="qmcfa_save_front_avatar"
			>

			<?php
			wp_nonce_field(
				'qmcfa_save_front_avatar_'
					. $user->ID,
				'qmcfa_front_nonce'
			);
			?>


			<p>
				<label for="qmcfa_front_file">
					<strong>上传新头像</strong>
				</label>
			</p>

			<p>
				<input
					type="file"
					id="qmcfa_front_file"
					name="qmcfa_front_file"
					accept="image/jpeg,image/png,image/webp"
				>
			</p>

			<p class="qmcfa-avatar-description">
				支持 JPG、PNG 和 WebP，
				最大 2 MB。
				图片会被居中裁剪成正方形，
				并直接覆盖当前头像文件。
				不会进入媒体库。
			</p>


			<?php if ( 'custom' === $mode ) : ?>
				<p>
					<label>
						<input
							type="checkbox"
							name="qmcfa_restore_default"
							value="1"
						>

						恢复系统分配的彩色默认头像
					</label>
				</p>
			<?php endif; ?>


			<p>
				<button type="submit">
					保存头像
				</button>
			</p>

		</form>

	</div>


	<style>
		.qmcfa-avatar-form-wrap {
			max-width: 620px;
		}

		.qmcfa-avatar-current {
			display: flex;
			align-items: center;
			gap: 18px;
			margin-bottom: 24px;
		}

		.qmcfa-avatar-current img {
			object-fit: cover;
		}

		.qmcfa-avatar-current p {
			margin: 6px 0 0;
		}

		.qmcfa-avatar-description {
			color: #666;
			font-size: 14px;
			line-height: 1.7;
		}

		.qmcfa-avatar-message {
			margin: 0 0 20px;
			padding: 11px 14px;

			color: #085d3a;
			background: #ecfdf3;

			border: 1px solid #abefc6;
			border-radius: 4px;
		}

		.qmcfa-avatar-message.is-error {
			color: #912018;
			background: #fee4e2;
			border-color: #fecdca;
		}
	</style>
	<?php

	return ob_get_clean();
}


/**
 * 处理前台头像保存。
 */
add_action(
	'admin_post_qmcfa_save_front_avatar',
	'qmcfa_handle_frontend_save'
);

function qmcfa_handle_frontend_save() {

	if ( ! is_user_logged_in() ) {
		wp_die(
			'请先登录。',
			'无法保存头像',
			array(
				'response' => 403,
			)
		);
	}


	$user = wp_get_current_user();

	if ( ! qmcfa_is_member( $user ) ) {
		wp_die(
			'当前账号不能执行此操作。',
			'无法保存头像',
			array(
				'response' => 403,
			)
		);
	}


	check_admin_referer(
		'qmcfa_save_front_avatar_'
			. $user->ID,
		'qmcfa_front_nonce'
	);


	$restore_default = ! empty(
		$_POST['qmcfa_restore_default']
	);


	$result = qmcfa_process_avatar_change(
		$user->ID,
		'qmcfa_front_file',
		$restore_default
	);


	if ( is_wp_error( $result ) ) {

		set_transient(
			'qmcfa_avatar_error_'
				. $user->ID,
			$result->get_error_message(),
			MINUTE_IN_SECONDS
		);

		$status = 'error';

	} else {
		$status = $result;
	}


	$redirect_url = wp_get_referer();

	if ( ! $redirect_url ) {
		$redirect_url = home_url( '/' );
	}


	$redirect_url = remove_query_arg(
		'qmcfa_avatar_status',
		$redirect_url
	);

	$redirect_url = add_query_arg(
		'qmcfa_avatar_status',
		$status,
		$redirect_url
	);


	wp_safe_redirect(
		$redirect_url
	);

	exit;
}


/* =========================================================
 * 十二、删除账号时清理头像文件
 * =========================================================
 */

/**
 * 根据登录用户名删除头像文件。
 */
function qmcfa_delete_avatar_for_login(
	$user_login
) {
	$paths = qmcfa_get_paths_for_login(
		$user_login
	);

	if ( is_wp_error( $paths ) ) {
		return;
	}


	if ( file_exists( $paths['path'] ) ) {
		wp_delete_file(
			$paths['path']
		);
	}


	/*
	 * 清理极少数意外遗留的备份文件。
	 */
	$backup_files = glob(
		$paths['path']
			. '.backup-*'
	);

	if ( is_array( $backup_files ) ) {

		foreach ( $backup_files as $backup_file ) {

			if ( is_file( $backup_file ) ) {
				wp_delete_file(
					$backup_file
				);
			}
		}
	}
}


/**
 * 普通 WordPress 删除用户。
 */
add_action(
	'delete_user',
	'qmcfa_cleanup_deleted_user',
	10,
	3
);

function qmcfa_cleanup_deleted_user(
	$user_id,
	$reassign,
	$user
) {
	if ( ! $user instanceof WP_User ) {
		$user = get_userdata(
			absint( $user_id )
		);
	}

	if ( ! $user ) {
		return;
	}


	qmcfa_delete_avatar_for_login(
		$user->user_login
	);

	qmcfa_cleanup_legacy_attachment(
		$user->ID
	);
}


/**
 * WordPress 多站点删除用户。
 */
add_action(
	'wpmu_delete_user',
	'qmcfa_cleanup_multisite_user',
	10,
	1
);

function qmcfa_cleanup_multisite_user(
	$user_id
) {
	$user = get_userdata(
		absint( $user_id )
	);

	if ( ! $user ) {
		return;
	}


	qmcfa_delete_avatar_for_login(
		$user->user_login
	);

	qmcfa_cleanup_legacy_attachment(
		$user->ID
	);
}

/**
 * 全体注册用户单文件头像系统。
 *
 * 功能：
 * - 适用于所有 WordPress 注册用户，不限制角色；
 * - 每个账号始终只有一个固定 PNG 头像文件；
 * - 文件名由登录用户名的 SHA-256 哈希确定；
 * - 没有上传头像时，生成 36 色之一的默认头像；
 * - 上传新头像时直接覆盖同一个文件；
 * - 恢复默认头像时重新生成彩色默认头像并覆盖；
 * - 不创建媒体附件，不进入媒体库；
 * - 删除账号时自动删除对应头像文件；
 * - 支持后台个人资料页面；
 * - 支持前台短代码：[qmc_avatar_form]
 */


/* =========================================================
 * 一、基础设置
 * =========================================================
 */

/*
 * 默认透明头像在 uploads 目录中的相对路径。
 *
 * 对应网址：
 * https://qimuchuan.life/wp-content/uploads/2026/07/默认头像.png
 */
if ( ! defined( 'QMCFA_TEMPLATE_RELATIVE_PATH' ) ) {
	define(
		'QMCFA_TEMPLATE_RELATIVE_PATH',
		'2026/07/默认头像.png'
	);
}


/*
 * 用户头像保存目录：
 *
 * wp-content/uploads/qmc-avatars/
 */
if ( ! defined( 'QMCFA_DIRECTORY_NAME' ) ) {
	define(
		'QMCFA_DIRECTORY_NAME',
		'qmc-avatars'
	);
}


/*
 * 所有头像统一处理为 256 × 256 PNG。
 */
if ( ! defined( 'QMCFA_IMAGE_SIZE' ) ) {
	define(
		'QMCFA_IMAGE_SIZE',
		256
	);
}


/*
 * 上传文件最大 2 MB。
 */
if ( ! defined( 'QMCFA_MAX_FILE_SIZE' ) ) {
	define(
		'QMCFA_MAX_FILE_SIZE',
		2 * MB_IN_BYTES
	);
}


/*
 * 上传原图最大边长。
 */
if ( ! defined( 'QMCFA_MAX_DIMENSION' ) ) {
	define(
		'QMCFA_MAX_DIMENSION',
		4096
	);
}


/*
 * 记录用户当前头像类型。
 *
 * 可选值：
 * default
 * custom
 */
if ( ! defined( 'QMCFA_MODE_META_KEY' ) ) {
	define(
		'QMCFA_MODE_META_KEY',
		'_qmc_file_avatar_mode'
	);
}


/*
 * 旧头像代码曾使用的媒体附件字段。
 *
 * 如果该字段仍存在，新系统在用户保存头像时，
 * 会尝试安全清理对应的旧媒体附件。
 */
if ( ! defined( 'QMCFA_LEGACY_META_KEY' ) ) {
	define(
		'QMCFA_LEGACY_META_KEY',
		'_qmc_avatar_attachment_id'
	);
}


/* =========================================================
 * 二、用户与路径辅助函数
 * =========================================================
 */

/**
 * 判断是否为有效的 WordPress 注册用户。
 *
 * 管理员、编辑、作者、投稿者、订阅者等
 * 所有有效注册用户都返回 true。
 */
function qmcfa_is_member( $user ) {

	if ( ! $user instanceof WP_User ) {
		return false;
	}

	return (
		$user->exists()
		&& (int) $user->ID > 0
	);
}


/**
 * 根据 WordPress 头像函数可能收到的参数解析用户。
 */
function qmcfa_resolve_user( $id_or_email ) {

	if ( $id_or_email instanceof WP_User ) {
		return $id_or_email;
	}


	if ( $id_or_email instanceof WP_Comment ) {

		if ( (int) $id_or_email->user_id > 0 ) {
			return get_user_by(
				'id',
				(int) $id_or_email->user_id
			);
		}

		if (
			is_email(
				$id_or_email->comment_author_email
			)
		) {
			return get_user_by(
				'email',
				$id_or_email->comment_author_email
			);
		}

		return false;
	}


	if ( $id_or_email instanceof WP_Post ) {
		return get_user_by(
			'id',
			(int) $id_or_email->post_author
		);
	}


	if ( is_numeric( $id_or_email ) ) {
		return get_user_by(
			'id',
			absint( $id_or_email )
		);
	}


	if (
		is_string( $id_or_email )
		&& is_email( $id_or_email )
	) {
		return get_user_by(
			'email',
			$id_or_email
		);
	}


	if ( is_object( $id_or_email ) ) {

		if ( ! empty( $id_or_email->user_id ) ) {
			return get_user_by(
				'id',
				absint( $id_or_email->user_id )
			);
		}

		if ( ! empty( $id_or_email->ID ) ) {
			return get_user_by(
				'id',
				absint( $id_or_email->ID )
			);
		}
	}

	return false;
}


/**
 * 规范化登录用户名。
 *
 * 该算法与旧版保持一致，
 * 所以现有头像文件名不会改变。
 */
function qmcfa_normalize_login( $user_login ) {

	$user_login = (string) $user_login;

	if ( function_exists( 'mb_strtolower' ) ) {
		return mb_strtolower(
			$user_login,
			'UTF-8'
		);
	}

	return strtolower( $user_login );
}


/**
 * 根据登录用户名生成固定文件索引。
 */
function qmcfa_get_login_hash( $user_login ) {

	return hash(
		'sha256',
		'qmc-single-avatar:'
			. qmcfa_normalize_login(
				$user_login
			)
	);
}


/**
 * 对网址相对路径中的每一级进行编码。
 */
function qmcfa_encode_relative_url( $relative_path ) {

	$parts = explode(
		'/',
		str_replace(
			'\\',
			'/',
			$relative_path
		)
	);

	$parts = array_map(
		'rawurlencode',
		$parts
	);

	return implode(
		'/',
		$parts
	);
}


/**
 * 获取指定用户名对应的头像路径与网址。
 */
function qmcfa_get_paths_for_login( $user_login ) {

	$uploads = wp_upload_dir(
		null,
		false
	);

	if ( ! empty( $uploads['error'] ) ) {
		return new WP_Error(
			'qmcfa_upload_directory_error',
			$uploads['error']
		);
	}


	$directory = trailingslashit(
		$uploads['basedir']
	) . QMCFA_DIRECTORY_NAME;


	if (
		! is_dir( $directory )
		&& ! wp_mkdir_p( $directory )
	) {
		return new WP_Error(
			'qmcfa_create_directory_failed',
			'无法创建用户头像目录。'
		);
	}


	/*
	 * 防止目录直接显示文件列表。
	 */
	$index_file = trailingslashit(
		$directory
	) . 'index.php';

	if ( ! file_exists( $index_file ) ) {
		@file_put_contents(
			$index_file,
			"<?php\n// Silence is golden.\n"
		);
	}


	$hash = qmcfa_get_login_hash(
		$user_login
	);

	$filename =
		'avatar-'
		. $hash
		. '.png';


	$avatar_path = trailingslashit(
		$directory
	) . $filename;


	$avatar_url = trailingslashit(
		$uploads['baseurl']
	) . QMCFA_DIRECTORY_NAME
		. '/'
		. rawurlencode( $filename );


	$template_path = path_join(
		$uploads['basedir'],
		QMCFA_TEMPLATE_RELATIVE_PATH
	);


	$template_url = trailingslashit(
		$uploads['baseurl']
	) . qmcfa_encode_relative_url(
		QMCFA_TEMPLATE_RELATIVE_PATH
	);


	return array(
		'directory'     => $directory,
		'filename'      => $filename,
		'path'          => $avatar_path,
		'url'           => $avatar_url,
		'template_path' => $template_path,
		'template_url'  => $template_url,
	);
}


/**
 * 获取指定用户对应的头像路径。
 */
function qmcfa_get_user_paths( $user ) {

	if ( ! qmcfa_is_member( $user ) ) {
		return new WP_Error(
			'qmcfa_invalid_user',
			'用户信息无效。'
		);
	}

	return qmcfa_get_paths_for_login(
		$user->user_login
	);
}


/**
 * 在头像目录中创建唯一临时文件路径。
 */
function qmcfa_create_temp_path( $directory ) {

	for ( $attempt = 0; $attempt < 10; $attempt++ ) {

		$filename =
			'.qmc-avatar-temp-'
			. wp_generate_password(
				20,
				false,
				false
			)
			. '.png';

		$path = trailingslashit(
			$directory
		) . $filename;

		if ( ! file_exists( $path ) ) {
			return $path;
		}
	}

	return false;
}


/* =========================================================
 * 三、36 种固定颜色
 * =========================================================
 */

/**
 * 根据登录用户名确定 0 至 35 的颜色编号。
 */
function qmcfa_get_color_index( $user_login ) {

	$hash = hash(
		'sha256',
		'qmc-avatar-color:'
			. qmcfa_normalize_login(
				$user_login
			)
	);

	$number = hexdec(
		substr(
			$hash,
			0,
			8
		)
	);

	return (int) ( $number % 36 );
}


/**
 * HSL 转 RGB 的辅助函数。
 */
function qmcfa_hue_component(
	$p,
	$q,
	$t
) {
	if ( $t < 0 ) {
		$t += 1;
	}

	if ( $t > 1 ) {
		$t -= 1;
	}

	if ( $t < 1 / 6 ) {
		return $p
			+ (
				$q - $p
			) * 6 * $t;
	}

	if ( $t < 1 / 2 ) {
		return $q;
	}

	if ( $t < 2 / 3 ) {
		return $p
			+ (
				$q - $p
			) * (
				2 / 3 - $t
			) * 6;
	}

	return $p;
}


/**
 * 把 HSL 颜色转换为 RGB。
 */
function qmcfa_hsl_to_rgb(
	$hue,
	$saturation,
	$lightness
) {
	$h = (
		(float) $hue % 360
	) / 360;

	$s = max(
		0,
		min(
			1,
			(float) $saturation
		)
	);

	$l = max(
		0,
		min(
			1,
			(float) $lightness
		)
	);


	if ( 0.0 === $s ) {
		$value = (int) round(
			$l * 255
		);

		return array(
			$value,
			$value,
			$value,
		);
	}


	$q = $l < 0.5
		? $l * ( 1 + $s )
		: $l + $s - $l * $s;

	$p = 2 * $l - $q;


	$r = qmcfa_hue_component(
		$p,
		$q,
		$h + 1 / 3
	);

	$g = qmcfa_hue_component(
		$p,
		$q,
		$h
	);

	$b = qmcfa_hue_component(
		$p,
		$q,
		$h - 1 / 3
	);


	return array(
		(int) round( $r * 255 ),
		(int) round( $g * 255 ),
		(int) round( $b * 255 ),
	);
}


/**
 * 获取用户固定的 RGB 颜色。
 *
 * 共 36 种色相，每种相隔 10 度。
 */
function qmcfa_get_user_rgb( $user_login ) {

	$index = qmcfa_get_color_index(
		$user_login
	);

	$hue = $index * 10;

	return qmcfa_hsl_to_rgb(
		$hue,
		0.82,
		0.45
	);
}


/* =========================================================
 * 四、原子覆盖头像文件
 * =========================================================
 */

/**
 * 使用准备好的临时文件安全替换正式头像。
 *
 * 新文件处理成功后才会替换旧文件。
 */
function qmcfa_atomic_replace(
	$prepared_path,
	$destination_path
) {
	if (
		! is_string( $prepared_path )
		|| ! file_exists( $prepared_path )
	) {
		return new WP_Error(
			'qmcfa_missing_prepared_file',
			'处理后的头像文件不存在。'
		);
	}


	$backup_path = '';

	if ( file_exists( $destination_path ) ) {

		$backup_path =
			$destination_path
			. '.backup-'
			. wp_generate_password(
				12,
				false,
				false
			);

		if (
			! @rename(
				$destination_path,
				$backup_path
			)
		) {
			return new WP_Error(
				'qmcfa_backup_failed',
				'无法备份原头像文件。'
			);
		}
	}


	if (
		! @rename(
			$prepared_path,
			$destination_path
		)
	) {
		if (
			$backup_path
			&& file_exists( $backup_path )
		) {
			@rename(
				$backup_path,
				$destination_path
			);
		}

		return new WP_Error(
			'qmcfa_replace_failed',
			'无法保存新的头像文件。'
		);
	}


	if (
		$backup_path
		&& file_exists( $backup_path )
	) {
		wp_delete_file(
			$backup_path
		);
	}


	$permissions = defined(
		'FS_CHMOD_FILE'
	)
		? FS_CHMOD_FILE
		: 0644;

	@chmod(
		$destination_path,
		$permissions
	);

	clearstatcache(
		true,
		$destination_path
	);

	return true;
}


/* =========================================================
 * 五、生成彩色默认头像
 * =========================================================
 */

/**
 * 使用 GD 生成彩色默认头像。
 */
function qmcfa_generate_default_with_gd(
	$template_path,
	$output_path,
	$rgb
) {
	if (
		! function_exists( 'imagecreatefrompng' )
		|| ! function_exists( 'imagepng' )
	) {
		return new WP_Error(
			'qmcfa_gd_unavailable',
			'服务器没有启用 GD 图片扩展。'
		);
	}


	$source = @imagecreatefrompng(
		$template_path
	);

	if ( ! $source ) {
		return new WP_Error(
			'qmcfa_template_load_failed',
			'无法读取默认透明头像。'
		);
	}


	$size = QMCFA_IMAGE_SIZE;

	$destination = imagecreatetruecolor(
		$size,
		$size
	);

	if ( ! $destination ) {
		imagedestroy( $source );

		return new WP_Error(
			'qmcfa_canvas_failed',
			'无法创建头像画布。'
		);
	}


	imagealphablending(
		$destination,
		false
	);

	imagesavealpha(
		$destination,
		true
	);


	$transparent = imagecolorallocatealpha(
		$destination,
		0,
		0,
		0,
		127
	);

	imagefill(
		$destination,
		0,
		0,
		$transparent
	);


	$source_width = imagesx(
		$source
	);

	$source_height = imagesy(
		$source
	);


	$copied = imagecopyresampled(
		$destination,
		$source,
		0,
		0,
		0,
		0,
		$size,
		$size,
		$source_width,
		$source_height
	);

	imagedestroy( $source );


	if ( ! $copied ) {
		imagedestroy( $destination );

		return new WP_Error(
			'qmcfa_resize_failed',
			'默认头像缩放失败。'
		);
	}


	$red   = (int) $rgb[0];
	$green = (int) $rgb[1];
	$blue  = (int) $rgb[2];

	/*
	 * 按透明度缓存颜色，
	 * 从而保留图案的抗锯齿边缘。
	 */
	$color_cache = array();


	for ( $y = 0; $y < $size; $y++ ) {

		for ( $x = 0; $x < $size; $x++ ) {

			$pixel = imagecolorat(
				$destination,
				$x,
				$y
			);

			$alpha = (
				$pixel >> 24
			) & 0x7F;


			if ( $alpha >= 127 ) {
				continue;
			}


			if (
				! isset(
					$color_cache[ $alpha ]
				)
			) {
				$color_cache[ $alpha ] =
					imagecolorallocatealpha(
						$destination,
						$red,
						$green,
						$blue,
						$alpha
					);
			}


			imagesetpixel(
				$destination,
				$x,
				$y,
				$color_cache[ $alpha ]
			);
		}
	}


	$saved = imagepng(
		$destination,
		$output_path,
		9
	);

	imagedestroy( $destination );


	if ( ! $saved ) {
		return new WP_Error(
			'qmcfa_png_save_failed',
			'彩色默认头像保存失败。'
		);
	}

	return true;
}


/**
 * 使用 Imagick 生成彩色默认头像。
 *
 * 仅在 GD 不可用时使用。
 */
function qmcfa_generate_default_with_imagick(
	$template_path,
	$output_path,
	$rgb
) {
	if ( ! class_exists( 'Imagick' ) ) {
		return new WP_Error(
			'qmcfa_imagick_unavailable',
			'服务器没有可用的图片处理扩展。'
		);
	}


	try {
		$image = new Imagick(
			$template_path
		);

		$image->setImageFormat(
			'png'
		);

		$image->setImageAlphaChannel(
			Imagick::ALPHACHANNEL_ACTIVATE
		);

		$image->cropThumbnailImage(
			QMCFA_IMAGE_SIZE,
			QMCFA_IMAGE_SIZE
		);


		$iterator = $image->getPixelIterator();

		foreach ( $iterator as $row ) {

			foreach ( $row as $pixel ) {

				$alpha = $pixel->getColorValue(
					Imagick::COLOR_ALPHA
				);

				if ( $alpha <= 0.001 ) {
					continue;
				}


				$pixel->setColor(
					sprintf(
						'rgb(%d,%d,%d)',
						(int) $rgb[0],
						(int) $rgb[1],
						(int) $rgb[2]
					)
				);

				$pixel->setColorValue(
					Imagick::COLOR_ALPHA,
					$alpha
				);
			}

			$iterator->syncIterator();
		}


		$image->setImageFormat(
			'png'
		);

		$saved = $image->writeImage(
			$output_path
		);

		$image->clear();
		$image->destroy();


		if ( ! $saved ) {
			return new WP_Error(
				'qmcfa_imagick_save_failed',
				'彩色默认头像保存失败。'
			);
		}

		return true;

	} catch ( Exception $exception ) {

		return new WP_Error(
			'qmcfa_imagick_exception',
			$exception->getMessage()
		);
	}
}


/**
 * 为指定注册用户生成彩色默认头像。
 */
function qmcfa_generate_default_avatar( $user_id ) {

	$user = get_userdata(
		absint( $user_id )
	);

	if ( ! qmcfa_is_member( $user ) ) {
		return new WP_Error(
			'qmcfa_invalid_member',
			'当前用户不是有效的注册用户。'
		);
	}


	$paths = qmcfa_get_user_paths(
		$user
	);

	if ( is_wp_error( $paths ) ) {
		return $paths;
	}


	if (
		! file_exists(
			$paths['template_path']
		)
	) {
		return new WP_Error(
			'qmcfa_missing_template',
			'没有找到默认头像 PNG：'
				. $paths['template_path']
		);
	}


	$temp_path = qmcfa_create_temp_path(
		$paths['directory']
	);

	if ( ! $temp_path ) {
		return new WP_Error(
			'qmcfa_temp_path_failed',
			'无法创建临时头像文件。'
		);
	}


	$rgb = qmcfa_get_user_rgb(
		$user->user_login
	);


	if (
		function_exists( 'imagecreatefrompng' )
		&& function_exists( 'imagepng' )
	) {
		$result =
			qmcfa_generate_default_with_gd(
				$paths['template_path'],
				$temp_path,
				$rgb
			);
	} else {
		$result =
			qmcfa_generate_default_with_imagick(
				$paths['template_path'],
				$temp_path,
				$rgb
			);
	}


	if ( is_wp_error( $result ) ) {

		if ( file_exists( $temp_path ) ) {
			wp_delete_file(
				$temp_path
			);
		}

		return $result;
	}


	$replaced = qmcfa_atomic_replace(
		$temp_path,
		$paths['path']
	);

	if ( is_wp_error( $replaced ) ) {

		if ( file_exists( $temp_path ) ) {
			wp_delete_file(
				$temp_path
			);
		}

		return $replaced;
	}


	update_user_meta(
		$user->ID,
		QMCFA_MODE_META_KEY,
		'default'
	);

	return true;
}


/* =========================================================
 * 六、处理用户上传头像
 * =========================================================
 */

/**
 * 判断表单是否实际上传了文件。
 */
function qmcfa_has_uploaded_file( $field_name ) {

	if (
		empty( $_FILES[ $field_name ] )
		|| empty(
			$_FILES[ $field_name ]['name']
		)
	) {
		return false;
	}

	if (
		isset(
			$_FILES[ $field_name ]['error']
		)
		&& UPLOAD_ERR_NO_FILE
			=== (int)
				$_FILES[ $field_name ]['error']
	) {
		return false;
	}

	return true;
}


/**
 * 清理旧头像代码产生的媒体附件。
 *
 * 只有能确认附件属于该用户时才删除。
 */
function qmcfa_cleanup_legacy_attachment(
	$user_id
) {
	$user_id = absint( $user_id );

	$attachment_id = absint(
		get_user_meta(
			$user_id,
			QMCFA_LEGACY_META_KEY,
			true
		)
	);

	if ( ! $attachment_id ) {
		return;
	}


	$can_delete = false;

	if (
		'attachment'
		=== get_post_type(
			$attachment_id
		)
		&& wp_attachment_is_image(
			$attachment_id
		)
	) {
		$post_author = absint(
			get_post_field(
				'post_author',
				$attachment_id
			)
		);

		$owner_meta = absint(
			get_post_meta(
				$attachment_id,
				'_qmc_avatar_owner_user_id',
				true
			)
		);

		if (
			$post_author === $user_id
			|| $owner_meta === $user_id
		) {
			$can_delete = true;
		}
	}


	if ( $can_delete ) {
		wp_delete_attachment(
			$attachment_id,
			true
		);
	}


	delete_user_meta(
		$user_id,
		QMCFA_LEGACY_META_KEY
	);
}


/**
 * 验证、裁剪并保存用户上传的头像。
 */
function qmcfa_save_uploaded_avatar(
	$user_id,
	$field_name
) {
	$user = get_userdata(
		absint( $user_id )
	);

	if ( ! qmcfa_is_member( $user ) ) {
		return new WP_Error(
			'qmcfa_invalid_user_upload',
			'当前账号不能上传头像。'
		);
	}


	if (
		! qmcfa_has_uploaded_file(
			$field_name
		)
	) {
		return new WP_Error(
			'qmcfa_no_file',
			'没有选择头像文件。'
		);
	}


	$file = $_FILES[ $field_name ];


	if (
		isset( $file['error'] )
		&& UPLOAD_ERR_OK
			!== (int) $file['error']
	) {
		return new WP_Error(
			'qmcfa_upload_error',
			'头像上传失败，请重新选择文件。'
		);
	}


	if (
		empty( $file['size'] )
		|| (int) $file['size']
			> QMCFA_MAX_FILE_SIZE
	) {
		return new WP_Error(
			'qmcfa_file_too_large',
			'头像文件不能超过 2 MB。'
		);
	}


	if (
		empty( $file['tmp_name'] )
		|| ! is_uploaded_file(
			$file['tmp_name']
		)
	) {
		return new WP_Error(
			'qmcfa_invalid_upload',
			'没有检测到有效的上传文件。'
		);
	}


	$allowed_mimes = array(
		'jpg|jpeg|jpe' => 'image/jpeg',
		'png'          => 'image/png',
		'webp'         => 'image/webp',
	);


	$file_check = wp_check_filetype_and_ext(
		$file['tmp_name'],
		$file['name'],
		$allowed_mimes
	);


	$allowed_types = array(
		'image/jpeg',
		'image/png',
		'image/webp',
	);


	if (
		empty( $file_check['type'] )
		|| ! in_array(
			$file_check['type'],
			$allowed_types,
			true
		)
	) {
		return new WP_Error(
			'qmcfa_invalid_file_type',
			'只允许上传 JPG、PNG 或 WebP 图片。'
		);
	}


	$image_info = function_exists(
		'wp_getimagesize'
	)
		? wp_getimagesize(
			$file['tmp_name']
		)
		: @getimagesize(
			$file['tmp_name']
		);


	if ( ! is_array( $image_info ) ) {
		return new WP_Error(
			'qmcfa_not_an_image',
			'上传的文件不是有效图片。'
		);
	}


	$width = isset( $image_info[0] )
		? absint( $image_info[0] )
		: 0;

	$height = isset( $image_info[1] )
		? absint( $image_info[1] )
		: 0;


	if (
		! $width
		|| ! $height
		|| $width > QMCFA_MAX_DIMENSION
		|| $height > QMCFA_MAX_DIMENSION
	) {
		return new WP_Error(
			'qmcfa_invalid_dimensions',
			'图片宽度和高度必须小于 4096 像素。'
		);
	}


	$paths = qmcfa_get_user_paths(
		$user
	);

	if ( is_wp_error( $paths ) ) {
		return $paths;
	}


	$temp_path = qmcfa_create_temp_path(
		$paths['directory']
	);

	if ( ! $temp_path ) {
		return new WP_Error(
			'qmcfa_temp_file_failed',
			'无法创建临时头像文件。'
		);
	}


	$editor = wp_get_image_editor(
		$file['tmp_name']
	);

	if ( is_wp_error( $editor ) ) {
		return $editor;
	}


	/*
	 * 居中裁剪成统一正方形。
	 */
	$resized = $editor->resize(
		QMCFA_IMAGE_SIZE,
		QMCFA_IMAGE_SIZE,
		true
	);

	if ( is_wp_error( $resized ) ) {
		return $resized;
	}


	/*
	 * 最终统一保存成 PNG。
	 */
	$saved = $editor->save(
		$temp_path,
		'image/png'
	);


	if ( is_wp_error( $saved ) ) {

		if ( file_exists( $temp_path ) ) {
			wp_delete_file(
				$temp_path
			);
		}

		return $saved;
	}


	$prepared_path = isset(
		$saved['path']
	)
		? $saved['path']
		: $temp_path;


	if ( ! file_exists( $prepared_path ) ) {
		return new WP_Error(
			'qmcfa_missing_saved_image',
			'处理后的头像文件不存在。'
		);
	}


	$replaced = qmcfa_atomic_replace(
		$prepared_path,
		$paths['path']
	);


	if ( is_wp_error( $replaced ) ) {

		if ( file_exists( $prepared_path ) ) {
			wp_delete_file(
				$prepared_path
			);
		}

		return $replaced;
	}


	if (
		$temp_path !== $prepared_path
		&& file_exists( $temp_path )
	) {
		wp_delete_file(
			$temp_path
		);
	}


	update_user_meta(
		$user->ID,
		QMCFA_MODE_META_KEY,
		'custom'
	);


	qmcfa_cleanup_legacy_attachment(
		$user->ID
	);


	return true;
}


/**
 * 处理上传、恢复默认或不修改。
 */
function qmcfa_process_avatar_change(
	$user_id,
	$field_name,
	$restore_default
) {
	if (
		qmcfa_has_uploaded_file(
			$field_name
		)
	) {
		$result =
			qmcfa_save_uploaded_avatar(
				$user_id,
				$field_name
			);

		return is_wp_error( $result )
			? $result
			: 'updated';
	}


	if ( $restore_default ) {

		$result =
			qmcfa_generate_default_avatar(
				$user_id
			);

		if ( is_wp_error( $result ) ) {
			return $result;
		}


		qmcfa_cleanup_legacy_attachment(
			$user_id
		);

		return 'restored';
	}


	return 'unchanged';
}


/* =========================================================
 * 七、确保所有注册用户拥有头像文件
 * =========================================================
 */

/**
 * 如果头像文件不存在，自动生成彩色默认头像。
 */
function qmcfa_ensure_avatar_file( $user ) {

	if ( ! qmcfa_is_member( $user ) ) {
		return new WP_Error(
			'qmcfa_invalid_avatar_user',
			'头像用户无效。'
		);
	}


	$paths = qmcfa_get_user_paths(
		$user
	);

	if ( is_wp_error( $paths ) ) {
		return $paths;
	}


	if ( file_exists( $paths['path'] ) ) {
		return $paths;
	}


	$generated =
		qmcfa_generate_default_avatar(
			$user->ID
		);

	if ( is_wp_error( $generated ) ) {
		return $generated;
	}


	return qmcfa_get_user_paths(
		$user
	);
}


/* =========================================================
 * 八、接管 WordPress 头像地址
 * =========================================================
 */

add_filter(
	'pre_get_avatar_data',
	'qmcfa_replace_avatar_data',
	20,
	2
);

function qmcfa_replace_avatar_data(
	$args,
	$id_or_email
) {
	$user = qmcfa_resolve_user(
		$id_or_email
	);


	/*
	 * 只处理能够对应到注册账号的用户。
	 *
	 * 未登录访客评论仍保留 WordPress 原有头像逻辑。
	 */
	if ( ! qmcfa_is_member( $user ) ) {
		return $args;
	}


	$paths = qmcfa_ensure_avatar_file(
		$user
	);


	if ( is_wp_error( $paths ) ) {

		$fallback_paths =
			qmcfa_get_user_paths(
				$user
			);

		if (
			! is_wp_error(
				$fallback_paths
			)
		) {
			$args['url'] =
				$fallback_paths[
					'template_url'
				];

			$args['found_avatar'] = true;
		}

		return $args;
	}


	$version = file_exists(
		$paths['path']
	)
		? (int) filemtime(
			$paths['path']
		)
		: time();


	/*
	 * 文件地址不变，但 v 参数会随修改时间变化，
	 * 避免浏览器或 CDN 一直显示旧头像。
	 */
	$args['url'] = add_query_arg(
		'v',
		$version,
		set_url_scheme(
			$paths['url'],
			'https'
		)
	);

	$args['found_avatar'] = true;

	return $args;
}


/* =========================================================
 * 九、注册与角色变化时生成头像
 * =========================================================
 */

/**
 * 新账号注册后生成默认头像。
 */
add_action(
	'user_register',
	'qmcfa_generate_avatar_on_registration',
	20,
	1
);

function qmcfa_generate_avatar_on_registration(
	$user_id
) {
	$user = get_userdata(
		absint( $user_id )
	);

	if ( qmcfa_is_member( $user ) ) {
		qmcfa_generate_default_avatar(
			$user->ID
		);
	}
}


/**
 * 用户角色发生变化时检查头像文件。
 *
 * 不限制新角色是什么。
 */
add_action(
	'set_user_role',
	'qmcfa_generate_avatar_after_role_change',
	20,
	3
);

function qmcfa_generate_avatar_after_role_change(
	$user_id,
	$role,
	$old_roles
) {
	$user = get_userdata(
		absint( $user_id )
	);

	if ( ! qmcfa_is_member( $user ) ) {
		return;
	}


	$paths = qmcfa_get_user_paths(
		$user
	);

	if (
		! is_wp_error( $paths )
		&& ! file_exists(
			$paths['path']
		)
	) {
		qmcfa_generate_default_avatar(
			$user->ID
		);
	}
}


/* =========================================================
 * 十、后台个人资料头像表单
 * =========================================================
 */

/**
 * 允许个人资料表单上传文件。
 */
add_action(
	'user_edit_form_tag',
	'qmcfa_add_profile_form_enctype'
);

function qmcfa_add_profile_form_enctype() {

	echo ' enctype="multipart/form-data"';
}


add_action(
	'show_user_profile',
	'qmcfa_show_profile_fields',
	20
);

add_action(
	'edit_user_profile',
	'qmcfa_show_profile_fields',
	20
);

function qmcfa_show_profile_fields( $user ) {

	if ( ! qmcfa_is_member( $user ) ) {
		return;
	}


	$mode = get_user_meta(
		$user->ID,
		QMCFA_MODE_META_KEY,
		true
	);

	?>
	<h2>账号头像</h2>

	<table
		class="form-table"
		role="presentation"
	>

		<tr>
			<th scope="row">
				当前头像
			</th>

			<td>
				<div style="
					display:flex;
					align-items:center;
					gap:16px;
				">
					<?php
					echo get_avatar(
						$user->ID,
						96,
						'',
						$user->display_name
					);
					?>

					<p class="description">
						<?php
						if ( 'custom' === $mode ) {
							echo '当前正在使用你上传的头像。';
						} else {
							echo '当前正在使用系统分配的 36 色默认头像。';
						}
						?>
					</p>
				</div>
			</td>
		</tr>


		<tr>
			<th scope="row">
				<label for="qmcfa_avatar_file">
					上传新头像
				</label>
			</th>

			<td>
				<input
					type="file"
					id="qmcfa_avatar_file"
					name="qmcfa_avatar_file"
					accept="image/jpeg,image/png,image/webp"
				>

				<p class="description">
					支持 JPG、PNG 和 WebP，
					最大 2 MB。
					图片会居中裁剪成正方形。
					保存后直接覆盖旧头像，
					不会进入媒体库。
				</p>
			</td>
		</tr>


		<?php if ( 'custom' === $mode ) : ?>
			<tr>
				<th scope="row">
					恢复默认头像
				</th>

				<td>
					<label>
						<input
							type="checkbox"
							name="qmcfa_restore_default"
							value="1"
						>

						恢复系统分配的彩色默认头像
					</label>
				</td>
			</tr>
		<?php endif; ?>

	</table>

	<?php
	wp_nonce_field(
		'qmcfa_save_profile_'
			. $user->ID,
		'qmcfa_profile_nonce'
	);
}


/**
 * 保存后台个人资料中的头像。
 */
add_action(
	'personal_options_update',
	'qmcfa_save_profile_avatar'
);

add_action(
	'edit_user_profile_update',
	'qmcfa_save_profile_avatar'
);

function qmcfa_save_profile_avatar(
	$user_id
) {
	$user_id = absint( $user_id );


	if (
		! $user_id
		|| ! current_user_can(
			'edit_user',
			$user_id
		)
	) {
		return;
	}


	$user = get_userdata(
		$user_id
	);

	if ( ! qmcfa_is_member( $user ) ) {
		return;
	}


	if (
		empty(
			$_POST['qmcfa_profile_nonce']
		)
		|| ! wp_verify_nonce(
			sanitize_text_field(
				wp_unslash(
					$_POST[
						'qmcfa_profile_nonce'
					]
				)
			),
			'qmcfa_save_profile_'
				. $user_id
		)
	) {
		return;
	}


	$restore_default = ! empty(
		$_POST['qmcfa_restore_default']
	);


	$result = qmcfa_process_avatar_change(
		$user_id,
		'qmcfa_avatar_file',
		$restore_default
	);


	if ( is_wp_error( $result ) ) {
		wp_die(
			esc_html(
				$result->get_error_message()
			),
			'头像保存失败',
			array(
				'response'  => 400,
				'back_link' => true,
			)
		);
	}
}


/* =========================================================
 * 十一、前台头像设置短代码
 * =========================================================
 */

/*
 * 使用方法：
 *
 * 在 WordPress 页面中加入：
 *
 * [qmc_avatar_form]
 */
add_shortcode(
	'qmc_avatar_form',
	'qmcfa_frontend_form_shortcode'
);

function qmcfa_frontend_form_shortcode() {

	if ( ! is_user_logged_in() ) {
		return '<p>请先登录后设置头像。</p>';
	}


	$user = wp_get_current_user();

	if ( ! qmcfa_is_member( $user ) ) {
		return '<p>当前账号不能使用此头像设置。</p>';
	}


	$mode = get_user_meta(
		$user->ID,
		QMCFA_MODE_META_KEY,
		true
	);


	$status = isset(
		$_GET['qmcfa_avatar_status']
	)
		? sanitize_key(
			wp_unslash(
				$_GET['qmcfa_avatar_status']
			)
		)
		: '';


	$messages = array(
		'updated' =>
			'头像已经更新。',

		'restored' =>
			'已恢复系统分配的彩色默认头像。',

		'unchanged' =>
			'头像没有发生变化。',

		'error' =>
			'头像处理失败，请重新尝试。',
	);


	$error_message = '';

	if ( 'error' === $status ) {

		$error_message = get_transient(
			'qmcfa_avatar_error_'
				. $user->ID
		);

		delete_transient(
			'qmcfa_avatar_error_'
				. $user->ID
		);
	}


	ob_start();


	if ( isset( $messages[ $status ] ) ) {
		?>
		<div
			class="qmcfa-avatar-message<?php
				echo 'error' === $status
					? ' is-error'
					: '';
			?>"
		>
			<?php
			echo esc_html(
				$error_message
					? $error_message
					: $messages[ $status ]
			);
			?>
		</div>
		<?php
	}

	?>
	<div class="qmcfa-avatar-form-wrap">

		<div class="qmcfa-avatar-current">

			<?php
			echo get_avatar(
				$user->ID,
				120,
				'',
				$user->display_name
			);
			?>

			<div>
				<strong>当前头像</strong>

				<p>
					<?php
					if ( 'custom' === $mode ) {
						echo '正在使用你上传的头像。';
					} else {
						echo '正在使用系统分配的 36 色默认头像。';
					}
					?>
				</p>
			</div>

		</div>


		<form
			method="post"
			enctype="multipart/form-data"
			action="<?php
				echo esc_url(
					admin_url(
						'admin-post.php'
					)
				);
			?>"
		>
			<input
				type="hidden"
				name="action"
				value="qmcfa_save_front_avatar"
			>

			<?php
			wp_nonce_field(
				'qmcfa_save_front_avatar_'
					. $user->ID,
				'qmcfa_front_nonce'
			);
			?>


			<p>
				<label for="qmcfa_front_file">
					<strong>上传新头像</strong>
				</label>
			</p>

			<p>
				<input
					type="file"
					id="qmcfa_front_file"
					name="qmcfa_front_file"
					accept="image/jpeg,image/png,image/webp"
				>
			</p>

			<p class="qmcfa-avatar-description">
				支持 JPG、PNG 和 WebP，
				最大 2 MB。
				图片会被居中裁剪成正方形，
				并直接覆盖当前头像文件。
				不会进入媒体库。
			</p>


			<?php if ( 'custom' === $mode ) : ?>
				<p>
					<label>
						<input
							type="checkbox"
							name="qmcfa_restore_default"
							value="1"
						>

						恢复系统分配的彩色默认头像
					</label>
				</p>
			<?php endif; ?>


			<p>
				<button type="submit">
					保存头像
				</button>
			</p>

		</form>

	</div>


	<style>
		.qmcfa-avatar-form-wrap {
			max-width: 620px;
		}

		.qmcfa-avatar-current {
			display: flex;
			align-items: center;
			gap: 18px;
			margin-bottom: 24px;
		}

		.qmcfa-avatar-current img {
			object-fit: cover;
		}

		.qmcfa-avatar-current p {
			margin: 6px 0 0;
		}

		.qmcfa-avatar-description {
			color: #666;
			font-size: 14px;
			line-height: 1.7;
		}

		.qmcfa-avatar-message {
			margin: 0 0 20px;
			padding: 11px 14px;

			color: #085d3a;
			background: #ecfdf3;

			border: 1px solid #abefc6;
			border-radius: 4px;
		}

		.qmcfa-avatar-message.is-error {
			color: #912018;
			background: #fee4e2;
			border-color: #fecdca;
		}
	</style>
	<?php

	return ob_get_clean();
}


/**
 * 处理前台头像保存。
 */
add_action(
	'admin_post_qmcfa_save_front_avatar',
	'qmcfa_handle_frontend_save'
);

function qmcfa_handle_frontend_save() {

	if ( ! is_user_logged_in() ) {
		wp_die(
			'请先登录。',
			'无法保存头像',
			array(
				'response' => 403,
			)
		);
	}


	$user = wp_get_current_user();

	if ( ! qmcfa_is_member( $user ) ) {
		wp_die(
			'当前账号不能执行此操作。',
			'无法保存头像',
			array(
				'response' => 403,
			)
		);
	}


	check_admin_referer(
		'qmcfa_save_front_avatar_'
			. $user->ID,
		'qmcfa_front_nonce'
	);


	$restore_default = ! empty(
		$_POST['qmcfa_restore_default']
	);


	$result = qmcfa_process_avatar_change(
		$user->ID,
		'qmcfa_front_file',
		$restore_default
	);


	if ( is_wp_error( $result ) ) {

		set_transient(
			'qmcfa_avatar_error_'
				. $user->ID,
			$result->get_error_message(),
			MINUTE_IN_SECONDS
		);

		$status = 'error';

	} else {
		$status = $result;
	}


	$redirect_url = wp_get_referer();

	if ( ! $redirect_url ) {
		$redirect_url = home_url( '/' );
	}


	$redirect_url = remove_query_arg(
		'qmcfa_avatar_status',
		$redirect_url
	);

	$redirect_url = add_query_arg(
		'qmcfa_avatar_status',
		$status,
		$redirect_url
	);


	wp_safe_redirect(
		$redirect_url
	);

	exit;
}


/* =========================================================
 * 十二、删除账号时清理头像文件
 * =========================================================
 */

/**
 * 根据登录用户名删除头像文件。
 */
function qmcfa_delete_avatar_for_login(
	$user_login
) {
	$paths = qmcfa_get_paths_for_login(
		$user_login
	);

	if ( is_wp_error( $paths ) ) {
		return;
	}


	if ( file_exists( $paths['path'] ) ) {
		wp_delete_file(
			$paths['path']
		);
	}


	/*
	 * 清理极少数意外遗留的备份文件。
	 */
	$backup_files = glob(
		$paths['path']
			. '.backup-*'
	);

	if ( is_array( $backup_files ) ) {

		foreach ( $backup_files as $backup_file ) {

			if ( is_file( $backup_file ) ) {
				wp_delete_file(
					$backup_file
				);
			}
		}
	}
}


/**
 * 普通 WordPress 删除用户。
 */
add_action(
	'delete_user',
	'qmcfa_cleanup_deleted_user',
	10,
	3
);

function qmcfa_cleanup_deleted_user(
	$user_id,
	$reassign,
	$user
) {
	if ( ! $user instanceof WP_User ) {
		$user = get_userdata(
			absint( $user_id )
		);
	}

	if ( ! $user ) {
		return;
	}


	qmcfa_delete_avatar_for_login(
		$user->user_login
	);

	qmcfa_cleanup_legacy_attachment(
		$user->ID
	);
}


/**
 * WordPress 多站点删除用户。
 */
add_action(
	'wpmu_delete_user',
	'qmcfa_cleanup_multisite_user',
	10,
	1
);

function qmcfa_cleanup_multisite_user(
	$user_id
) {
	$user = get_userdata(
		absint( $user_id )
	);

	if ( ! $user ) {
		return;
	}


	qmcfa_delete_avatar_for_login(
		$user->user_login
	);

	qmcfa_cleanup_legacy_attachment(
		$user->ID
	);
}