<?php

namespace WPUltimateSecurity\UltimateSecurity\Infrastructure\Container;

/**
 * Container Interface
 *
 * PSR-11 compatible container interface for dependency injection.
 *
 * @package WPUltimateSecurity\UltimateSecurity\Infrastructure\Container
 * @since 2.0.0
 */
interface ContainerInterface
{
    /**
     * Finds an entry of the container by its identifier and returns it.
     *
     * @param string $id Identifier of the entry to look for.
     *
     * @throws ServiceNotFoundException No entry was found for **this** identifier.
     * @throws ContainerException       Error while retrieving the entry.
     *
     * @return mixed Entry.
     */
    public function get(string $id): mixed;

    /**
     * Returns true if the container can return an entry for the given identifier.
     * Returns false otherwise.
     *
     * @param string $id Identifier of the entry to look for.
     *
     * @return bool
     */
    public function has(string $id): bool;

    /**
     * Register a binding in the container.
     *
     * @param string   $id       The unique identifier for the binding.
     * @param callable $resolver A callable that returns the service instance.
     * @param bool     $shared   Whether to share the instance (singleton).
     *
     * @return void
     */
    public function bind(string $id, callable $resolver, bool $shared = false): void;

    /**
     * Register a shared (singleton) binding in the container.
     *
     * @param string   $id       The unique identifier for the binding.
     * @param callable $resolver A callable that returns the service instance.
     *
     * @return void
     */
    public function singleton(string $id, callable $resolver): void;

    /**
     * Register an existing instance in the container.
     *
     * @param string $id       The unique identifier for the instance.
     * @param mixed  $instance The instance to register.
     *
     * @return void
     */
    public function instance(string $id, mixed $instance): void;

    /**
     * Create an alias for an existing binding.
     *
     * @param string $alias    The alias name.
     * @param string $abstract The existing binding identifier.
     *
     * @return void
     */
    public function alias(string $alias, string $abstract): void;
}
