apii-php/src/FlashiiUrls.php

<?php declare(strict_types=1);
// FlashiiUrls.php
// Created: 2024-11-16
// Updated: 2024-11-16

namespace Flashii;

/**
 * Defines the base URLs the client has to be aware of to use the API.
 */
final class FlashiiUrls {
    /**
     * Production API base URL.
     *
     * @var string
     */
    public const PROD_API_URL = 'https://api.flashii.net';

    /**
     * Production ID service base URL.
     *
     * @var string
     */
    public const PROD_ID_URL = 'https://id.flashii.net';

    /**
     * @param string $apiUrl API base URL, without trailing /.
     * @param string $idUrl ID service base URL, without trailing /.
     */
    public function __construct(
        private string $apiUrl,
        private string $idUrl
    ) {}

    /**
     * @param string $url
     * @param string $path
     * @param array<string, mixed> $args
     * @return string
     */
    private static function buildUrl(string $url, string $path, array $args): string {
        $url .= $path;

        if(!empty($args)) {
            $url .= str_contains($url, '?') ? '&' : '?';
            $url .= http_build_query($args, encoding_type: PHP_QUERY_RFC3986);
        }

        return $url;
    }

    /**
     * Retrieves the API base URL.
     *
     * @param string $path Path to append to the URL.
     * @param array<string, mixed> $args Query arguments to append to the URL.
     * @return string
     */
    public function getApiUrl(string $path = '', array $args = []): string {
        return self::buildUrl($this->apiUrl, $path, $args);
    }

    /**
     * Retrieves the ID service base URL.
     *
     * @param string $path Path to append to the URL.
     * @param array<string, mixed> $args Query arguments to append to the URL.
     * @return string
     */
    public function getIdUrl(string $path = '', array $args = []): string {
        return self::buildUrl($this->idUrl, $path, $args);
    }

    /**
     * Creates an instance with the production URLs preset.
     *
     * @return FlashiiUrls
     */
    public static function production(): self {
        return new static(
            self::PROD_API_URL,
            self::PROD_ID_URL
        );
    }
}