<?php
/**
 * Licence fields on the attachment edit screen.
 *
 * @package AcidStudios\AEO
 */

declare(strict_types=1);

namespace AcidStudios\AEO\Admin;

use AcidStudios\AEO\Data\PageData;
use WP_Post;

defined( 'ABSPATH' ) || exit;

/**
 * Adds the licence, credit and creator an `ImageObject` node needs.
 *
 * Google's image licence features, and any assistant that reproduces a picture,
 * need to know who made it and under what terms. WordPress stores neither, so
 * the three fields are added to the media modal and to the attachment screen,
 * and `Data\PageData` reads them back onto the page's primary image.
 *
 * These fields ride along with core's own attachment save, so the request is
 * already authenticated and nonce checked by the time `attachment_fields_to_save`
 * fires — `wp_ajax_save_attachment_compat()` and `media_upload_form_handler()`
 * both verify before applying the filter. Adding a second nonce here would only
 * duplicate a check that has already passed; the capability is re-checked
 * because the meta belongs to a post this user may not be allowed to edit.
 */
final class MediaFields {

	/**
	 * Hooks the fields into the attachment screens.
	 *
	 * @return void
	 */
	public function register(): void {
		add_filter( 'attachment_fields_to_edit', [ $this, 'fields' ], 10, 2 );
		add_filter( 'attachment_fields_to_save', [ $this, 'save' ], 10, 2 );
	}

	/**
	 * Adds the three fields to an image attachment.
	 *
	 * @param mixed $form_fields Fields collected so far.
	 * @param mixed $post        The attachment being edited.
	 * @return array<string,mixed> Fields.
	 */
	public function fields( $form_fields, $post ): array {
		$form_fields = is_array( $form_fields ) ? $form_fields : [];

		if ( ! $post instanceof WP_Post || ! wp_attachment_is_image( $post ) ) {
			return $form_fields;
		}

		$attachment_id = (int) $post->ID;

		$form_fields[ PageData::LICENSE_META ] = [
			'label' => __( 'License URL', 'acid-aeo' ),
			'input' => 'text',
			'value' => $this->meta( $attachment_id, PageData::LICENSE_META ),
			'helps' => __( 'Page describing the licence this image is published under.', 'acid-aeo' ),
		];

		$form_fields[ PageData::CREDIT_META ] = [
			'label' => __( 'Credit text', 'acid-aeo' ),
			'input' => 'text',
			'value' => $this->meta( $attachment_id, PageData::CREDIT_META ),
			'helps' => __( 'Who should be credited when this image is reproduced.', 'acid-aeo' ),
		];

		$form_fields[ PageData::CREATOR_META ] = [
			'label' => __( 'Creator name', 'acid-aeo' ),
			'input' => 'text',
			'value' => $this->meta( $attachment_id, PageData::CREATOR_META ),
			'helps' => __( 'The photographer, illustrator or designer who made it.', 'acid-aeo' ),
		];

		return $form_fields;
	}

	/**
	 * Saves the three fields.
	 *
	 * WordPress hands the submitted values in `$attachment` and has already
	 * verified the request, so only the capability is checked here.
	 *
	 * @param mixed $post       The attachment post array.
	 * @param mixed $attachment Submitted attachment fields.
	 * @return array<string,mixed> The attachment post array, unchanged.
	 */
	public function save( $post, $attachment ): array {
		$post          = is_array( $post ) ? $post : [];
		$attachment    = is_array( $attachment ) ? $attachment : [];
		$attachment_id = (int) ( $post['ID'] ?? 0 );

		if ( $attachment_id <= 0 || ! current_user_can( 'edit_post', $attachment_id ) ) {
			return $post;
		}

		if ( array_key_exists( PageData::LICENSE_META, $attachment ) ) {
			update_post_meta( $attachment_id, PageData::LICENSE_META, esc_url_raw( $this->line( $attachment[ PageData::LICENSE_META ] ) ) );
		}

		foreach ( [ PageData::CREDIT_META, PageData::CREATOR_META ] as $field ) {
			if ( array_key_exists( $field, $attachment ) ) {
				update_post_meta( $attachment_id, $field, sanitize_text_field( $this->line( $attachment[ $field ] ) ) );
			}
		}

		return $post;
	}

	/**
	 * One attachment meta value as a string.
	 *
	 * @param int    $attachment_id Attachment ID.
	 * @param string $key           Meta key.
	 * @return string Meta value.
	 */
	private function meta( int $attachment_id, string $key ): string {
		$value = get_post_meta( $attachment_id, $key, true );

		return is_scalar( $value ) ? (string) $value : '';
	}

	/**
	 * A submitted value as a trimmed string.
	 *
	 * The media screens hand the filter what the request carried, slashes and
	 * all, so it is unslashed here rather than stored with the slashes in it.
	 *
	 * @param mixed $value Raw value.
	 * @return string Trimmed value.
	 */
	private function line( $value ): string {
		return is_scalar( $value ) ? trim( (string) wp_unslash( $value ) ) : '';
	}
}