A utility class for determining and overriding the current [TargetPlatform].

platform_utils.dart

// MIT License
//
// Copyright (c) 2025 Nidal Bakir
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
// SOFTWARE.
//


import 'package:flutter/foundation.dart';

/// A utility class for determining and overriding the current [TargetPlatform].
///
/// This class provides convenient platform checks (e.g. [isAndroid], [isIOS])
/// and allows overriding the platform for debugging or testing purposes.
///
/// To override the global platform used by the Flutter framework,
/// use [setDebugDefaultTargetPlatformOverride].
///
/// To override the platform only within this utility (without affecting the
/// Flutter framework), use [setCurrentTargetPlatform].
///
/// The [dart:io.Platform] object should only be used directly when it's critical to
/// actually know the current platform, without any overrides possible (for
/// example, when a system API is about to be called
class PlatformUtils {
  static TargetPlatform _current = defaultTargetPlatform;

  /// Overrides the global [defaultTargetPlatform] used by the Flutter framework.
  ///
  /// This change affects the entire Flutter runtime, influencing widgets and
  /// platform-specific behaviors throughout the app.
  ///
  /// Only takes effect in debug mode.
  static void setDebugDefaultTargetPlatformOverride(TargetPlatform targetPlatform) {
    if (kDebugMode) {
      debugDefaultTargetPlatformOverride = targetPlatform;
      _current = targetPlatform;
    }
  }

  /// Overrides the platform value **only** within this utility class.
  ///
  /// Unlike [setDebugDefaultTargetPlatformOverride], this does **not**
  /// modify Flutter's internal platform settings. It only affects code that
  /// checks the platform using [PlatformUtils].
  ///
  /// Useful for testing logic that depends on the platform without altering
  /// the behavior of the entire app.
  ///
  /// Only takes effect in debug mode.
  static void setCurrentTargetPlatform(TargetPlatform targetPlatform) {
    if (kDebugMode) {
      _current = targetPlatform;
    }
  }

  /// The currently active platform for [PlatformUtils].
  static TargetPlatform get current => _current;

  /// Platform-specific convenience getters.
  static bool get isIOS => current == TargetPlatform.iOS;
  static bool get isAndroid => current == TargetPlatform.android;
  static bool get isMacOS => current == TargetPlatform.macOS;
  static bool get isWindows => current == TargetPlatform.windows;
  static bool get isLinux => current == TargetPlatform.linux;
  static bool get isFuchsia => current == TargetPlatform.fuchsia;

  /// Returns `true` when running on the web.
  static bool get isWeb => kIsWeb;
}