<?php

declare(strict_types=1);

namespace CloudXM\SDK\Contracts;

/**
 * Service container interface for CloudXM plugins
 *
 * Defines the contract for dependency injection containers used across
 * all CloudXM plugins. Provides service registration, resolution, and
 * lifecycle management.
 */
interface ContainerInterface
{
    /**
     * Register a singleton service
     */
    public function singleton(string $abstract, callable|string|null $concrete = null): void;

    /**
     * Register a transient service (new instance each time)
     */
    public function bind(string $abstract, callable|string|null $concrete = null, bool $shared = false): void;

    /**
     * Register an alias for a service
     */
    public function alias(string $abstract, string $alias): void;

    /**
     * Get a service from the container (PSR-11 compatible)
     */
    public function get(string $id): mixed;

    /**
     * Check if service exists (PSR-11 compatible)
     */
    public function has(string $id): bool;

    /**
     * Boot the container
     */
    public function boot(): void;

    /**
     * Check if container is booted
     */
    public function isBooted(): bool;

    /**
     * Get all registered service IDs
     */
    public function getServiceIds(): array;

    /**
     * Clear container state (for testing)
     */
    public function reset(): void;
}