<?php

namespace WpOrg\Requests\Exception;

use WpOrg\Requests\Exception;

/**

 * Exception for when an incorrect number of arguments are passed to a method.

 *

 * Typically, this exception is used when all arguments for a method are optional,

 * but certain arguments need to be passed together, i.e. a method which can be called

 * with no arguments or with two arguments, but not with one argument.

 *

 * Along the same lines, this exception is also used if a method expects an array

 * with a certain number of elements and the provided number of elements does not comply.

 *

 * @package Requests\Exceptions

 * @since   2.0.0

 */

final class ArgumentCount extends Exception {

	/**

	 * Create a new argument count exception with a standardized text.

	 *

	 * @param string $expected The argument count expected as a phrase.

	 *                         For example: `at least 2 arguments` or `exactly 1 argument`.

	 * @param int    $received The actual argument count received.

	 * @param string $type     Exception type.

	 *

	 * @return \WpOrg\Requests\Exception\ArgumentCount

	 */

	public static function create($expected, $received, $type) {

		// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_debug_backtrace

		$stack = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2);

		return new self(

			sprintf(

				'%s::%s() expects %s, %d given',

				$stack[1]['class'],

				$stack[1]['function'],

				$expected,

				$received

			),

			$type

		);

	}

}