<?php
/**
 * Outcome of a link-insertion attempt.
 *
 * @package Postlinkly
 * @since   1.0.0
 */

declare(strict_types=1);

namespace Postlinkly\Link;

/**
 * Outcome of a link-insertion, removal, or update attempt.
 *
 * Returns a typed result so callers can branch on success or failure
 * cleanly. When `is_success()` is true, `get_content()` returns the
 * modified content; when it's false, `get_reason()` explains why.
 *
 * Reason codes are documented as class constants so callers can branch
 * on them without string-comparing free-form messages.
 *
 * @since 1.0.0
 */
final class LinkInsertionResult {

	/** Reason: input was empty (content, sentence, or changed sentence). */
	public const REASON_EMPTY_INPUT = 'empty_input';

	/** Reason: changed sentence was identical to original — nothing to do. */
	public const REASON_NO_CHANGE = 'no_change';

	/** Reason: every match position was unsafe (inside tag, attribute, JSON, or link). */
	public const REASON_NO_SAFE_POSITION = 'no_safe_position';

	/** Reason: content already contains the link (idempotent insertion guard). */
	public const REASON_ALREADY_PRESENT = 'already_present';

	/** Reason: target link not present in content (for remove/update operations). */
	public const REASON_LINK_NOT_FOUND = 'link_not_found';

	private bool $success;

	private string $content;

	private string $reason;

	/**
	 * Private constructor; use {@see success()} or {@see failure()}.
	 *
	 * @since 1.0.0
	 *
	 * @param bool   $success Whether the operation modified content.
	 * @param string $content Resulting content. Equal to original on failure.
	 * @param string $reason  Reason code for failures; empty string on success.
	 */
	private function __construct( bool $success, string $content, string $reason ) {
		$this->success = $success;
		$this->content = $content;
		$this->reason  = $reason;
	}

	/**
	 * Builds a success result.
	 *
	 * @since 1.0.0
	 *
	 * @param string $content Modified content.
	 *
	 * @return self
	 */
	public static function success( string $content ): self {
		return new self( true, $content, '' );
	}

	/**
	 * Builds a failure result.
	 *
	 * @since 1.0.0
	 *
	 * @param string $reason           One of the REASON_* class constants.
	 * @param string $original_content Optional. Original content to echo back.
	 *
	 * @return self
	 */
	public static function failure( string $reason, string $original_content = '' ): self {
		return new self( false, $original_content, $reason );
	}

	/**
	 * Returns whether the operation modified content.
	 *
	 * @since 1.0.0
	 *
	 * @return bool
	 */
	public function is_success(): bool {
		return $this->success;
	}

	/**
	 * Returns the resulting content (modified on success, original on failure).
	 *
	 * @since 1.0.0
	 *
	 * @return string
	 */
	public function get_content(): string {
		return $this->content;
	}

	/**
	 * Returns the reason code on failure, or empty string on success.
	 *
	 * @since 1.0.0
	 *
	 * @return string
	 */
	public function get_reason(): string {
		return $this->reason;
	}
}