<?php
/**
 * Submission context passed to an integration.
 *
 * @package FormPilot
 * @since   1.0.0
 */

declare( strict_types = 1 );

namespace FormPilot\Integrations;

use FormPilot\Models\Field;
use FormPilot\Models\Form;
use FormPilot\Submissions\ValueFormatter;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Everything an integration is allowed to know about one submission.
 *
 * Values arrive as they were stored, which for a checkbox group or an upload is
 * an encoded string rather than text. Reading them through this object rather
 * than the raw array means every integration gets the same answer for the same
 * field, and none of them has to know how a value was encoded.
 *
 * @since 1.0.0
 */
final class IntegrationContext {

	/**
	 * Constructor.
	 *
	 * @param Form                 $form          Form that was submitted.
	 * @param int                  $submission_id Stored submission ID.
	 * @param array<string, mixed> $values        Stored values keyed by field key.
	 * @param array<int, Field>    $fields        Fields of the form, in display order.
	 * @param ValueFormatter       $formatter     Decoder for stored values.
	 */
	public function __construct(
		private Form $form,
		private int $submission_id,
		private array $values,
		private array $fields,
		private ValueFormatter $formatter
	) {}

	/**
	 * Returns the form.
	 */
	public function form(): Form {
		return $this->form;
	}

	/**
	 * Returns the submission ID.
	 *
	 * @return int The ID, 0 for a test delivery.
	 */
	public function submission_id(): int {
		return $this->submission_id;
	}

	/**
	 * Returns the fields of the form.
	 *
	 * @return array<int, Field> The fields.
	 */
	public function fields(): array {
		return $this->fields;
	}

	/**
	 * Returns one answer as readable text.
	 *
	 * @param string $key Field key.
	 *
	 * @return string The answer, or an empty string when the field was not answered.
	 */
	public function value( string $key ): string {
		if ( '' === $key || ! array_key_exists( $key, $this->values ) ) {
			return '';
		}

		$raw = $this->values[ $key ];

		return $this->formatter->raw_to_text( is_scalar( $raw ) ? (string) $raw : (string) wp_json_encode( $raw ) );
	}

	/**
	 * Returns an answer only when it is a usable email address.
	 *
	 * @param string $key Field key.
	 *
	 * @return string The address, or an empty string.
	 */
	public function email( string $key ): string {
		$value = trim( $this->value( $key ) );

		return is_email( $value ) ? $value : '';
	}

	/**
	 * Returns every answer as text, keyed by field key.
	 *
	 * @return array<string, string> Answers keyed by field key.
	 */
	public function all(): array {
		$values = array();

		foreach ( array_keys( $this->values ) as $key ) {
			$values[ (string) $key ] = $this->value( (string) $key );
		}

		return $values;
	}

	/**
	 * Returns every answer as text, keyed by the label the visitor saw.
	 *
	 * @return array<string, string> Answers keyed by label.
	 */
	public function labelled(): array {
		$values = array();

		foreach ( $this->fields as $field ) {
			if ( ! $field instanceof Field ) {
				continue;
			}

			$key = $field->field_key();

			if ( ! array_key_exists( $key, $this->values ) ) {
				continue;
			}

			$label = '' !== $field->label() ? $field->label() : $key;

			$values[ $label ] = $this->value( $key );
		}

		return $values;
	}

	/**
	 * Returns the link to the stored entry.
	 *
	 * @return string The admin URL, or an empty string for a test delivery.
	 */
	public function entry_url(): string {
		if ( $this->submission_id <= 0 ) {
			return '';
		}

		return add_query_arg(
			array(
				'page'  => 'formpilot-entries',
				'entry' => $this->submission_id,
			),
			admin_url( 'admin.php' )
		);
	}
}