Finalize foundation collections

packages/framework/src/Foundation/Concerns/BaseFoundationCollection.php

@@ -7,34 +7,57 @@
 use Hyde\Foundation\HydeKernel;
 use Illuminate\Contracts\Support\Arrayable;
 use Illuminate\Support\Collection;
+use RuntimeException;
+use Throwable;
 
 /**
  * Base class for the kernel auto-discovery collections.
  *
- * @see \Hyde\Foundation\Kernel\FileCollection
- * @see \Hyde\Foundation\Kernel\PageCollection
- * @see \Hyde\Foundation\Kernel\RouteCollection
- * @see \Hyde\Framework\Testing\Unit\BaseFoundationCollectionTest
+ * These collections are the heart of the discovery process.
+ *
+ * They are responsible for discovering the files, pages, and routes,
+ * for the project, and also act as containers for the discovered data.
+ *
+ * The collections are stored as singletons in the kernel, and can be
+ * accessed via the kernel's `getFiles()`, `getPages()`, and `getRoutes()`
+ * methods respectively, or through the corresponding facade helper classes.
+ *
+ * Each collection depends on the earlier one, thus they are booted in sequence.
+ *
+ * @see \Hyde\Foundation\Kernel\FileCollection Discovers the source files in the project.
+ * @see \Hyde\Foundation\Kernel\PageCollection Parses the source files into page objects.
+ * @see \Hyde\Foundation\Kernel\RouteCollection Creates route objects from the page objects.
+ *
+ * The collections are constructed and booted in the kernel through the `BootsHydeKernel` trait.
+ * Between the construction and booting is a time-frame where the extensions can hook into
+ * the discovery process and add their data through the `runExtensionCallbacks` API.
  */
 abstract class BaseFoundationCollection extends Collection
 {
     protected HydeKernel $kernel;
 
-    abstract protected function runDiscovery(): self;
+    abstract protected function runDiscovery(): void;
 
-    abstract protected function runExtensionCallbacks(): self;
+    abstract protected function runExtensionCallbacks(): void;
 
     public static function init(HydeKernel $kernel): static
     {
         return (new static())->setKernel($kernel);
     }
 
-    public function boot(): static
+    final public function boot(): static
     {
-        return $this->runDiscovery();
+        try {
+            $this->runDiscovery();
+            $this->runExtensionCallbacks();
+        } catch (Throwable $exception) {
+            throw new RuntimeException('An error occurred during the discovery process.', previous: $exception);
+        }
+
+        return $this;
     }
 
-    protected function __construct(array|Arrayable|null $items = [])
+    final protected function __construct(array|Arrayable|null $items = [])
     {
         parent::__construct($items);
     }
@@ -46,10 +69,4 @@ protected function setKernel(HydeKernel $kernel): static
 
         return $this;
     }
-
-    /** @return $this */
-    public function getInstance(): static
-    {
-        return $this;
-    }
 }

packages/framework/src/Foundation/Concerns/HandlesFoundationCollections.php

@@ -15,20 +15,23 @@
  */
 trait HandlesFoundationCollections
 {
+    /**  @return \Hyde\Foundation\Kernel\FileCollection<string, \Hyde\Support\Filesystem\ProjectFile> */
     public function files(): FileCollection
     {
         $this->needsToBeBooted();
 
         return $this->files;
     }
 
+    /** @return \Hyde\Foundation\Kernel\PageCollection<string, \Hyde\Pages\Concerns\HydePage> */
     public function pages(): PageCollection
     {
         $this->needsToBeBooted();
 
         return $this->pages;
     }
 
+    /** @return \Hyde\Foundation\Kernel\RouteCollection<string, \Hyde\Support\Models\Route> */
     public function routes(): RouteCollection
     {
         $this->needsToBeBooted();

packages/framework/src/Foundation/Facades/Files.php

@@ -6,13 +6,53 @@
 
 use Hyde\Foundation\HydeKernel;
 use Hyde\Foundation\Kernel\FileCollection;
+use Hyde\Framework\Exceptions\FileNotFoundException;
+use Hyde\Support\Filesystem\MediaFile;
+use Hyde\Support\Filesystem\ProjectFile;
+use Hyde\Support\Filesystem\SourceFile;
 use Illuminate\Support\Facades\Facade;
 
 /**
  * @mixin \Hyde\Foundation\Kernel\FileCollection
  */
 class Files extends Facade
 {
+    public static function getFile(string $filePath): ProjectFile
+    {
+        return static::getFacadeRoot()->get($filePath) ?? throw new FileNotFoundException(message: "File [$filePath] not found in file collection");
+    }
+
+    /**
+     * @param  class-string<\Hyde\Pages\Concerns\HydePage>|null  $pageClass
+     * @return \Hyde\Foundation\Kernel\FileCollection<\Hyde\Support\Filesystem\SourceFile>
+     */
+    public static function getSourceFiles(?string $pageClass = null): FileCollection
+    {
+        return $pageClass ? static::getSourceFilesFor($pageClass) : static::getAllSourceFiles();
+    }
+
+    /**
+     * @param  class-string<\Hyde\Pages\Concerns\HydePage>  $pageClass
+     * @return \Hyde\Foundation\Kernel\FileCollection<\Hyde\Support\Filesystem\SourceFile>
+     */
+    public static function getSourceFilesFor(string $pageClass): FileCollection
+    {
+        return static::getAllSourceFiles()->where(fn (SourceFile $file): bool => $file->model === $pageClass);
+    }
+
+    /** @return \Hyde\Foundation\Kernel\FileCollection<\Hyde\Support\Filesystem\SourceFile> */
+    public static function getAllSourceFiles(): FileCollection
+    {
+        return static::getFacadeRoot()->where(fn (ProjectFile $file): bool => $file instanceof SourceFile);
+    }
+
+    /** @return \Hyde\Foundation\Kernel\FileCollection<\Hyde\Support\Filesystem\MediaFile> */
+    public static function getMediaFiles(): FileCollection
+    {
+        return static::getFacadeRoot()->where(fn (ProjectFile $file): bool => $file instanceof MediaFile);
+    }
+
+    /**  @return \Hyde\Foundation\Kernel\FileCollection<string, \Hyde\Support\Filesystem\ProjectFile> */
     public static function getFacadeRoot(): FileCollection
     {
         return HydeKernel::getInstance()->files();

packages/framework/src/Foundation/Facades/Pages.php

@@ -6,13 +6,28 @@
 
 use Hyde\Foundation\HydeKernel;
 use Hyde\Foundation\Kernel\PageCollection;
+use Hyde\Framework\Exceptions\FileNotFoundException;
+use Hyde\Pages\Concerns\HydePage;
 use Illuminate\Support\Facades\Facade;
 
 /**
  * @mixin \Hyde\Foundation\Kernel\PageCollection
  */
 class Pages extends Facade
 {
+    public static function getPage(string $sourcePath): HydePage
+    {
+        return static::getFacadeRoot()->get($sourcePath) ?? throw new FileNotFoundException(message: "Page [$sourcePath] not found in page collection");
+    }
+
+    public static function getPages(?string $pageClass = null): PageCollection
+    {
+        return $pageClass ? static::getFacadeRoot()->filter(function (HydePage $page) use ($pageClass): bool {
+            return $page instanceof $pageClass;
+        }) : static::getFacadeRoot();
+    }
+
+    /** @return \Hyde\Foundation\Kernel\PageCollection<string, \Hyde\Pages\Concerns\HydePage> */
     public static function getFacadeRoot(): PageCollection
     {
         return HydeKernel::getInstance()->pages();

packages/framework/src/Foundation/Facades/Routes.php

@@ -6,13 +6,28 @@
 
 use Hyde\Foundation\HydeKernel;
 use Hyde\Foundation\Kernel\RouteCollection;
+use Hyde\Framework\Exceptions\RouteNotFoundException;
+use Hyde\Support\Models\Route;
 use Illuminate\Support\Facades\Facade;
 
 /**
  * @mixin \Hyde\Foundation\Kernel\RouteCollection
  */
 class Routes extends Facade
 {
+    public static function getRoute(string $routeKey): Route
+    {
+        return static::getFacadeRoot()->get($routeKey) ?? throw new RouteNotFoundException(message: "Route [$routeKey] not found in route collection");
+    }
+
+    public static function getRoutes(?string $pageClass = null): RouteCollection
+    {
+        return $pageClass ? static::getFacadeRoot()->filter(function (Route $route) use ($pageClass): bool {
+            return $route->getPage() instanceof $pageClass;
+        }) : static::getFacadeRoot();
+    }
+
+    /** @return \Hyde\Foundation\Kernel\RouteCollection<string, \Hyde\Support\Models\Route> */
     public static function getFacadeRoot(): RouteCollection
     {
         return HydeKernel::getInstance()->routes();

packages/framework/src/Foundation/Kernel/FileCollection.php

@@ -15,6 +15,9 @@
  * The FileCollection contains all the discovered source and media files,
  * and thus has an integral role in the Hyde Auto Discovery process.
  *
+ * @template T of \Hyde\Support\Filesystem\ProjectFile
+ * @template-extends \Hyde\Foundation\Concerns\BaseFoundationCollection<string, T>
+ *
  * @property array<string, ProjectFile> $items The files in the collection.
  *
  * This class is stored as a singleton in the HydeKernel.
@@ -26,36 +29,18 @@
 final class FileCollection extends BaseFoundationCollection
 {
     /**
-     * @param  class-string<\Hyde\Pages\Concerns\HydePage>|null  $pageClass
-     * @return \Hyde\Foundation\Kernel\FileCollection<\Hyde\Support\Filesystem\SourceFile>
-     */
-    public function getSourceFiles(?string $pageClass = null): self
-    {
-        return ! $pageClass ? $this->getAllSourceFiles() : $this->getSourceFilesFor($pageClass);
-    }
-
-    /**
-     * @param  class-string<\Hyde\Pages\Concerns\HydePage>  $pageClass
-     * @return \Hyde\Foundation\Kernel\FileCollection<\Hyde\Support\Filesystem\SourceFile>
+     * This method adds the specified file to the file collection.
+     * It can be used by package developers to add a file that can be discovered.
+     *
+     * In order for your file to be further processed you must call this method during the boot process,
+     * either using a Kernel bootingCallback, or by using a HydeExtension's discovery handler callback.
      */
-    public function getSourceFilesFor(string $pageClass): self
+    public function addFile(ProjectFile $file): void
     {
-        return $this->getAllSourceFiles()->where(fn (SourceFile $file): bool => $file->model === $pageClass);
+        $this->put($file->getPath(), $file);
     }
 
-    /** @return \Hyde\Foundation\Kernel\FileCollection<\Hyde\Support\Filesystem\SourceFile> */
-    public function getAllSourceFiles(): self
-    {
-        return $this->where(fn (ProjectFile $file): bool => $file instanceof SourceFile);
-    }
-
-    /** @return \Hyde\Foundation\Kernel\FileCollection<\Hyde\Support\Filesystem\MediaFile> */
-    public function getMediaFiles(): self
-    {
-        return $this->where(fn (ProjectFile $file): bool => $file instanceof MediaFile);
-    }
-
-    protected function runDiscovery(): self
+    protected function runDiscovery(): void
     {
         /** @var class-string<\Hyde\Pages\Concerns\HydePage> $pageClass */
         foreach ($this->kernel->getRegisteredPageClasses() as $pageClass) {
@@ -64,21 +49,15 @@ protected function runDiscovery(): self
             }
         }
 
-        $this->runExtensionCallbacks();
-
         $this->discoverMediaAssetFiles();
-
-        return $this;
     }
 
-    protected function runExtensionCallbacks(): self
+    protected function runExtensionCallbacks(): void
     {
         /** @var class-string<\Hyde\Foundation\Concerns\HydeExtension> $extension */
         foreach ($this->kernel->getExtensions() as $extension) {
             $extension->discoverFiles($this);
         }
-
-        return $this;
     }
 
     /** @param class-string<HydePage> $pageClass */
@@ -87,15 +66,15 @@ protected function discoverFilesFor(string $pageClass): void
         // Scan the source directory, and directories therein, for files that match the model's file extension.
         foreach (glob($this->kernel->path($pageClass::sourcePath('{*,**/*}')), GLOB_BRACE) as $filepath) {
             if (! str_starts_with(basename((string) $filepath), '_')) {
-                $this->put($this->kernel->pathToRelative($filepath), SourceFile::make($filepath, $pageClass));
+                $this->addFile(SourceFile::make($filepath, $pageClass));
             }
         }
     }
 
     protected function discoverMediaAssetFiles(): void
     {
         foreach (DiscoveryService::getMediaAssetFiles() as $filepath) {
-            $this->put($this->kernel->pathToRelative($filepath), MediaFile::make($filepath));
+            $this->addFile(MediaFile::make($filepath));
         }
     }
 }