refactor(support): improve path utilities (#1080)

Author: innocenzi

composer.json

@@ -128,6 +128,7 @@
             "src/Tempest/Support/src/Html/functions.php",
             "src/Tempest/Support/src/Language/functions.php",
             "src/Tempest/Support/src/Namespace/functions.php",
+            "src/Tempest/Support/src/Path/functions.php",
             "src/Tempest/Support/src/Random/functions.php",
             "src/Tempest/Support/src/Regex/functions.php",
             "src/Tempest/Support/src/Str/functions.php",

src/Tempest/Console/src/Highlight/TempestConsoleLanguage/Injections/FileInjection.php

@@ -23,7 +23,7 @@ public function parse(string $content, Highlighter $highlighter): ParsedInjectio
                 $href = $matches['file'];
                 $exists = realpath($href) !== false;
                 $file = $exists
-                    ? str(realpath($href))->replace('\\', '/')->replaceStart(root_path('/'), '')
+                    ? str(realpath($href))->replace('\\', '/')->stripStart(root_path())->stripStart('/')
                     : $href;
 
                 return TerminalStyle::UNDERLINE((string) $file);

src/Tempest/Core/src/Composer.php

@@ -4,15 +4,20 @@
 
 namespace Tempest\Core;
 
+use Tempest\Support\Namespace\Psr4Namespace;
+
 use function Tempest\Support\arr;
-use function Tempest\Support\path;
+use function Tempest\Support\Arr\wrap;
+use function Tempest\Support\Path\normalize;
+use function Tempest\Support\Str\ensure_ends_with;
+use function Tempest\Support\Str\starts_with;
 
 final class Composer
 {
-    /** @var array<ComposerNamespace> */
+    /** @var array<Psr4Namespace> */
     public array $namespaces;
 
-    public ?ComposerNamespace $mainNamespace = null;
+    public ?Psr4Namespace $mainNamespace = null;
 
     private string $composerPath;
 
@@ -25,16 +30,17 @@ public function __construct(
 
     public function load(): self
     {
-        $this->composerPath = path($this->root, 'composer.json')->toString();
+        $this->composerPath = normalize($this->root, 'composer.json');
         $this->composer = $this->loadComposerFile($this->composerPath);
         $this->namespaces = arr($this->composer)
             ->get('autoload.psr-4', default: arr())
-            ->map(fn (string $path, string $namespace) => new ComposerNamespace($namespace, $path))
+            ->map(fn (string $path, string $namespace) => new Psr4Namespace($namespace, $path))
+            ->sortByCallback(fn (Psr4Namespace $ns1, Psr4Namespace $ns2) => strlen($ns1->path) <=> strlen($ns2->path))
             ->values()
             ->toArray();
 
         foreach ($this->namespaces as $namespace) {
-            if (str_starts_with($namespace->path, 'app/') || str_starts_with($namespace->path, 'src/')) {
+            if (starts_with(ensure_ends_with($namespace->path, '/'), ['app/', 'src/', 'source/', 'lib/'])) {
                 $this->mainNamespace = $namespace;
 
                 break;
@@ -45,16 +51,31 @@ public function load(): self
             $this->mainNamespace = $this->namespaces[0];
         }
 
+        $this->namespaces = arr([
+            $this->mainNamespace,
+            ...$this->namespaces,
+        ])
+            ->filter()
+            ->unique(fn (Psr4Namespace $ns) => $ns->namespace)
+            ->toArray();
+
         return $this;
     }
 
-    public function setMainNamespace(ComposerNamespace $namespace): self
+    public function setMainNamespace(Psr4Namespace $namespace): self
     {
         $this->mainNamespace = $namespace;
 
         return $this;
     }
 
+    public function setNamespaces(Psr4Namespace|array $namespaces): self
+    {
+        $this->namespaces = wrap($namespaces);
+
+        return $this;
+    }
+
     public function setShellExecutor(ShellExecutor $executor): self
     {
         $this->executor = $executor;

src/Tempest/Core/src/ComposerNamespace.php

@@ -50,6 +50,7 @@ public static function boot(
             discoveryLocations: $discoveryLocations,
             container: $container,
         )
+            ->validateRoot()
             ->loadEnv()
             ->registerEmergencyErrorHandler()
             ->registerShutdownFunction()
@@ -63,6 +64,19 @@ public static function boot(
             ->event(KernelEvent::BOOTED);
     }
 
+    public function validateRoot(): self
+    {
+        $root = realpath($this->root);
+
+        if (! is_dir($root)) {
+            throw new \RuntimeException('The specified root directory is not valid.');
+        }
+
+        $this->root = $root;
+
+        return $this;
+    }
+
     public function shutdown(int|string $status = ''): never
     {
         $this->finishDeferredTasks()

src/Tempest/Core/src/FrameworkKernel.php

@@ -9,7 +9,7 @@
 use Tempest\Discovery\DiscoveryException;
 use Tempest\Discovery\DiscoveryLocation;
 
-use function Tempest\Support\path;
+use function Tempest\Support\Path\normalize;
 
 /** @internal */
 final readonly class LoadDiscoveryLocations
@@ -34,8 +34,8 @@ public function __invoke(): void
      */
     private function discoverCorePackages(): array
     {
-        $composerPath = path($this->kernel->root, 'vendor/composer');
-        $installed = $this->loadJsonFile(path($composerPath, 'installed.json')->toString());
+        $composerPath = normalize($this->kernel->root, 'vendor/composer');
+        $installed = $this->loadJsonFile(normalize($composerPath, 'installed.json'));
         $packages = $installed['packages'] ?? [];
 
         $discoveredLocations = [];
@@ -48,12 +48,12 @@ private function discoverCorePackages(): array
                 continue;
             }
 
-            $packagePath = path($composerPath, $package['install-path'] ?? '');
+            $packagePath = normalize($composerPath, $package['install-path'] ?? '');
 
             foreach ($package['autoload']['psr-4'] as $namespace => $namespacePath) {
-                $namespacePath = path($packagePath, $namespacePath);
+                $namespacePath = normalize($packagePath, $namespacePath);
 
-                $discoveredLocations[] = new DiscoveryLocation($namespace, $namespacePath->toString());
+                $discoveredLocations[] = new DiscoveryLocation($namespace, $namespacePath);
             }
         }
 
@@ -68,9 +68,9 @@ private function discoverAppNamespaces(): array
         $discoveredLocations = [];
 
         foreach ($this->composer->namespaces as $namespace) {
-            $path = path($this->kernel->root, $namespace->path);
+            $path = normalize($this->kernel->root, $namespace->path);
 
-            $discoveredLocations[] = new DiscoveryLocation($namespace->namespace, $path->toString());
+            $discoveredLocations[] = new DiscoveryLocation($namespace->namespace, $path);
         }
 
         return $discoveredLocations;
@@ -81,8 +81,8 @@ private function discoverAppNamespaces(): array
      */
     private function discoverVendorPackages(): array
     {
-        $composerPath = path($this->kernel->root, 'vendor/composer');
-        $installed = $this->loadJsonFile(path($composerPath, 'installed.json')->toString());
+        $composerPath = normalize($this->kernel->root, 'vendor/composer');
+        $installed = $this->loadJsonFile(normalize($composerPath, 'installed.json'));
         $packages = $installed['packages'] ?? [];
 
         $discoveredLocations = [];
@@ -95,7 +95,7 @@ private function discoverVendorPackages(): array
                 continue;
             }
 
-            $packagePath = path($composerPath, $package['install-path'] ?? '');
+            $packagePath = normalize($composerPath, $package['install-path'] ?? '');
             $requiresTempest = isset($package['require']['tempest/framework']) || isset($package['require']['tempest/core']);
             $hasPsr4Namespaces = isset($package['autoload']['psr-4']);
 
@@ -104,9 +104,9 @@ private function discoverVendorPackages(): array
             }
 
             foreach ($package['autoload']['psr-4'] as $namespace => $namespacePath) {
-                $path = path($packagePath, $namespacePath);
+                $path = normalize($packagePath, $namespacePath);
 
-                $discoveredLocations[] = new DiscoveryLocation($namespace, $path->toString());
+                $discoveredLocations[] = new DiscoveryLocation($namespace, $path);
             }
         }
 

src/Tempest/Core/src/Kernel/LoadDiscoveryLocations.php

@@ -26,6 +26,8 @@
 use function Tempest\root_path;
 use function Tempest\Support\Namespace\to_base_class_name;
 use function Tempest\Support\path;
+use function Tempest\Support\Path\to_absolute_path;
+use function Tempest\Support\Path\to_relative_path;
 use function Tempest\Support\str;
 
 use const JSON_PRETTY_PRINT;
@@ -147,18 +149,14 @@ public function getSuggestedPath(string $className, ?string $pathPrefix = null,
     {
         // Separate input path and classname
         $inputClassName = to_base_class_name($className);
-        $inputPath = str(path($className))->replaceLast($inputClassName, '')->toString();
+        $inputPath = path($className)->stripEnd($inputClassName);
         $className = str($inputClassName)
             ->pascal()
             ->finish($classSuffix ?? '')
             ->toString();
 
         // Prepare the suggested path from the project namespace
-        return str(path(
-            $this->composer->mainNamespace->path,
-            $pathPrefix ?? '',
-            $inputPath,
-        ))
+        return str(to_absolute_path($this->composer->mainNamespace->path, $pathPrefix ?? '', $inputPath))
             ->finish('/')
             ->append($className . '.php')
             ->toString();
@@ -266,7 +264,7 @@ function (string $content) use ($callback) {
 
     private function friendlyFileName(string $path): string
     {
-        return str_replace(str(root_path())->finish('/')->toString(), '', $path);
+        return to_relative_path(root_path(), $path);
     }
 
     private function detectIndent(string $raw): string

src/Tempest/Core/src/PublishesFiles.php

@@ -4,51 +4,63 @@
 
 namespace Tempest {
     use Closure;
+    use ReflectionException;
+    use RuntimeException;
+    use Stringable;
+    use Tempest\Container\Exceptions\CannotInstantiateDependencyException;
+    use Tempest\Container\Exceptions\CannotResolveTaggedDependency;
+    use Tempest\Container\Exceptions\CircularDependencyException;
     use Tempest\Core\Composer;
     use Tempest\Core\DeferredTasks;
     use Tempest\Core\Kernel;
+    use Tempest\Support\Namespace\PathCouldNotBeMappedToNamespaceException;
+    use Tempest\Support\Regex\InvalidPatternException;
 
-    use function Tempest\Support\path;
-    use function Tempest\Support\str;
+    use function Tempest\Support\Namespace\to_psr4_namespace;
+    use function Tempest\Support\Path\to_absolute_path;
 
     /**
-     * Creates a path scoped within the root of the project
+     * Creates an absolute path scoped to the root of the project.
      */
-    function root_path(string ...$parts): string
+    function root_path(Stringable|string ...$parts): string
     {
-        return path(realpath(get(Kernel::class)->root), ...$parts)->toString();
+        return to_absolute_path(get(Kernel::class)->root, ...$parts);
     }
 
     /**
-     * Creates an absolute path scoped within the framework's internal storage directory.
+     * Creates an absolute path scoped to the main directory of the project.
      */
-    function internal_storage_path(string ...$parts): string
+    function src_path(Stringable|string ...$parts): string
     {
-        return path(get(Kernel::class)->internalStorage, ...$parts)->toString();
+        return root_path(get(Composer::class)->mainNamespace->path, ...$parts);
     }
 
     /**
-     * Creates a relative path scoped within the main directory of the project.
+     * Creates an absolute path scoped to the framework's internal storage directory.
      */
-    function src_path(string ...$parts): string
+    function internal_storage_path(Stringable|string ...$parts): string
     {
-        $composer = get(Composer::class);
-
-        return path($composer->mainNamespace->path, ...$parts)->toString();
+        return root_path(get(Kernel::class)->internalStorage, ...$parts);
     }
 
     /**
-     * Creates a namespace scoped within the main namespace of the project.
+     * Converts the given path to a registered namespace. The path is expected to be absolute, or relative to the root of the project.
+     *
+     * @throws PathCouldNotBeMappedToNamespaceException If the path cannot be mapped to registered namespace
      */
-    function src_namespace(?string $append = null): string
+    function registered_namespace(Stringable|string ...$parts): string
     {
-        $composer = get(Composer::class);
+        return to_psr4_namespace(get(Composer::class)->namespaces, root_path(...$parts), root: root_path());
+    }
 
-        return str($composer->mainNamespace->namespace)
-            ->append($append ?? '')
-            ->replace('\\\\', '\\')
-            ->trim('\\')
-            ->toString();
+    /**
+     * Converts the given path to the main namespace. The path is expected to be absolute, or relative to the root of the project.
+     *
+     * @throws PathCouldNotBeMappedToNamespaceException If the path cannot be mapped to the main namespace
+     */
+    function src_namespace(Stringable|string ...$parts): string
+    {
+        return to_psr4_namespace(get(Composer::class)->mainNamespace, root_path(...$parts), root: root_path());
     }
 
     /**