<?php declare(strict_types = 1);

namespace PHPStan\Reflection;

use PHPStan\TrinaryLogic;
use PHPStan\Type\Type;

/**
 * Reflection for a class method.
 *
 * This is the interface extension developers should implement when creating custom
 * MethodsClassReflectionExtension implementations for magic methods (__call, etc.).
 *
 * Methods can have multiple "variants" (overloaded signatures) — for example,
 * built-in functions like `array_map` have different signatures depending on
 * the number of arguments. Each variant is a ParametersAcceptor.
 *
 * For additional method metadata (assertions, purity, named arguments, attributes),
 * see ExtendedMethodReflection which extends this interface.
 *
 * @api
 */
interface MethodReflection extends ClassMemberReflection
{

	public function getName(): string;

	/**
	 * For methods that override a parent method, this returns the parent's
	 * method reflection. For methods with no parent, returns itself.
	 */
	public function getPrototype(): ClassMemberReflection;

	/**
	 * Most methods have a single variant. Built-in PHP functions with overloaded
	 * signatures (e.g. different return types based on argument count) have multiple.
	 *
	 * @return list<ParametersAcceptor>
	 */
	public function getVariants(): array;

	public function isDeprecated(): TrinaryLogic;

	public function getDeprecatedDescription(): ?string;

	public function isFinal(): TrinaryLogic;

	public function isInternal(): TrinaryLogic;

	public function getThrowType(): ?Type;

	/**
	 * Void methods are always considered impure since they must do something
	 * to be useful.
	 */
	public function hasSideEffects(): TrinaryLogic;

}