<?php

namespace xlvask\interfaces;

use Exception;
use helpers\xlvask_customer;
use helpers\xlvask_vehicle;

interface xlvask_cache_i
{
    /**
     * Check if a customer is cached by their customer number.
     * @param int $customer_number The customer number to check.
     * @return bool True if the customer is cached, false otherwise.
     */
    public function isCustomerCached(int $customer_number): bool;

    /**
     * Get the cached customer object by customer number.
     * @param int $customer_number The customer number to retrieve.
     * @return object The cached customer object.
     * @throws Exception If the customer is not cached.
     */
    public function getCustomerCache(int $customer_number): xlvask_customer;

    /**
     * Set the cache for a specific customer.
     * @param int $customer_number The customer number to cache.
     * @param xlvask_customer $customer The customer object to cache.
     */
    public function setCustomerCache(int $customer_number, xlvask_customer $customer): void;

    /**
     * Clear the cache for a specific customer.
     * @param int $customer_number The customer number to clear the cache for.
     */
    public function clearCustomerCache(int $customer_number): void;

    /**
     * Clear all cached customers.
     * This will remove all customer caches, so use with caution.
     */
    public function clearAllCustomerCache(): void;

    /**
     * Get all cached customers.
     * @return array[xlvask_customer] An array of all cached customer objects.
     * @example [xlvask_customer, xlvask_customer, ...]
     * @see xlvask_customer
     */
    public function getAllCachedCustomers(): array;

    /**
     * Get the count of cached customers.
     * @return int
     */
    public function getCachedCustomerCount(): int;

    /**
     * Get cached customers by their customer numbers.
     * @param array $customer_numbers [int] An array of customer numbers to retrieve.
     * @param bool $allow_missing If true, will return null for missing customers, otherwise will throw an exception.
     * @return array[xlvask_customer]
     * @example [xlvask_customer, xlvask_customer, ...]
     */
    public function getCachedCustomersByCustomerNumbers(array $customer_numbers, bool $allow_missing = false): array;

    /**
     * Check if a vehicle is cached by its registration number.
     * @param string $registration The vehicle registration number to check.
     * @return bool True if the vehicle is cached, false otherwise.
     */
    public function isVehicleCached(string $registration): bool;

    /**
     * Get the cached vehicle object by its registration number.
     * @param string $registration The vehicle registration number to retrieve.
     * @return xlvask_vehicle The cached vehicle object.
     * @throws Exception If the vehicle is not cached.
     */
    public function getVehicleCache(string $registration): xlvask_vehicle;

    /**
     * Set the cache for a specific vehicle.
     * @param string $registration The vehicle registration number to cache.
     * @param xlvask_vehicle $vehicle The vehicle object to cache.
     */
    public function setVehicleCache(string $registration, xlvask_vehicle $vehicle): void;

    /**
     * Clear the cache for a specific vehicle.
     * @param string $registration The vehicle registration number to clear the cache for.
     */
    public function clearVehicleCache(string $registration): void;

    /**
     * Clear all cached vehicles.
     * This will remove all vehicle caches, so use with caution.
     */
    public function clearAllVehicleCache(): void;

    /**
     * Get all cached vehicles.
     * @return array<xlvask_vehicle> An array of all cached vehicle objects.
     * @example [xlvask_vehicle, xlvask_vehicle, ...]
     * @see xlvask_vehicle
     */
    public function getAllCachedVehicles(): array;
}