Preview snapshot for hydephp/develop#2064

src/Console/Commands/ChangeSourceDirectoryCommand.php

@@ -27,7 +27,7 @@
 class ChangeSourceDirectoryCommand extends Command
 {
     /** @var string */
-    protected $signature = 'change:sourceDirectory {name : The new source directory name }';
+    protected $signature = 'change:sourceDirectory {name : The new source directory name}';
 
     /** @var string */
     protected $description = 'Change the source directory for your project';

src/Console/Commands/ServeCommand.php

@@ -101,7 +101,7 @@ protected function configureOutput(): void
     protected function printStartMessage(): void
     {
         $this->useBasicOutput()
-            ? $this->output->writeln('<info>Starting the HydeRC server...</info> Press Ctrl+C to stop')
+            ? $this->output->writeln('<info>Starting the HydeRC server...</info> Use Ctrl+C to stop')
             : $this->console->printStartMessage($this->getHostSelection(), $this->getPortSelection(), $this->getEnvironmentVariables());
     }
 
@@ -146,12 +146,7 @@ protected function checkArgvForOption(string $name): ?string
 
     protected function openInBrowser(string $path = '/'): void
     {
-        $binary = match (PHP_OS_FAMILY) {
-            'Windows' => 'start',
-            'Darwin' => 'open',
-            'Linux' => 'xdg-open',
-            default => null
-        };
+        $binary = $this->getOpenCommand(PHP_OS_FAMILY);
 
         $command = sprintf('%s http://%s:%d', $binary, $this->getHostSelection(), $this->getPortSelection());
         $command = rtrim("$command/$path", '/');
@@ -164,4 +159,14 @@ protected function openInBrowser(string $path = '/'): void
             $this->newLine();
         }
     }
+
+    protected function getOpenCommand(string $osFamily): ?string
+    {
+        return match ($osFamily) {
+            'Windows' => 'start',
+            'Darwin' => 'open',
+            'Linux' => 'xdg-open',
+            default => null
+        };
+    }
 }

src/Facades/Author.php

@@ -18,7 +18,7 @@ class Author
      * Construct a new Post Author. For Hyde to discover this author,
      * you must call this method from your hyde.php config file.
      *
-     * @see https://hydephp.com/docs/1.x/customization.html#authors
+     * @see https://hydephp.com/docs/1.x/customization#authors
      *
      * @param  string  $username  The username of the author. This is the key used to find authors in the config.
      * @param  string|null  $name  The optional display name of the author, leave blank to use the username.

src/Facades/Filesystem.php

@@ -69,6 +69,21 @@ public static function smartGlob(string $pattern, int $flags = 0): Collection
         return self::kernel()->filesystem()->smartGlob($pattern, $flags);
     }
 
+    /**
+     * Find files in the project's directory, with optional filtering by extension and recursion.
+     *
+     * The returned collection will be a list of paths relative to the project root.
+     *
+     * @param  string  $directory
+     * @param  string|array<string>|false  $matchExtensions  The file extension(s) to match, or false to match all files.
+     * @param  bool  $recursive  Whether to search recursively or not.
+     * @return \Illuminate\Support\Collection<int, string>
+     */
+    public static function findFiles(string $directory, string|array|false $matchExtensions = false, bool $recursive = false): Collection
+    {
+        return self::kernel()->filesystem()->findFiles($directory, $matchExtensions, $recursive);
+    }
+
     /**
      * Touch one or more files in the project's directory.
      *
@@ -113,7 +128,7 @@ public static function unlinkIfExists(string $path): bool
      */
     public static function getContents(string $path, bool $lock = false): string
     {
-        return self::get($path, $lock);
+        return self::get(...func_get_args());
     }
 
     /**
@@ -126,7 +141,7 @@ public static function getContents(string $path, bool $lock = false): string
      */
     public static function putContents(string $path, string $contents, bool $lock = false): bool|int
     {
-        return self::put($path, $contents, $lock);
+        return self::put(...func_get_args());
     }
 
     protected static function filesystem(): \Illuminate\Filesystem\Filesystem

src/Foundation/Concerns/BaseFoundationCollection.php

@@ -13,6 +13,11 @@
 /**
  * Base class for the kernel auto-discovery collections.
  *
+ * @template TKey of array-key
+ * @template TValue
+ *
+ * @extends \Illuminate\Support\Collection<TKey, TValue>
+ *
  * These collections are the heart of the discovery process.
  *
  * They are responsible for discovering the files, pages, and routes,

src/Foundation/Concerns/ForwardsHyperlinks.php

@@ -5,6 +5,7 @@
 namespace Hyde\Foundation\Concerns;
 
 use Hyde\Support\Models\Route;
+use JetBrains\PhpStorm\Deprecated;
 
 /**
  * @internal Single-use trait for the HydeKernel class.
@@ -23,8 +24,14 @@ public function relativeLink(string $destination): string
         return $this->hyperlinks->relativeLink($destination);
     }
 
+    /**
+     * @deprecated This method will be removed in v2.0. Please use `asset()` instead.
+     */
+    #[Deprecated(reason: 'Use `asset` method instead.', replacement: '%class%::asset(%parameter0%)')]
     public function mediaLink(string $destination, bool $validate = false): string
     {
+        trigger_deprecation('hyde/framework', '1.8.0', 'The %s() method is deprecated, use %s() instead.', __METHOD__, 'asset');
+
         return $this->hyperlinks->mediaLink($destination, $validate);
     }
 

src/Foundation/Concerns/HandlesFoundationCollections.php

@@ -15,23 +15,20 @@
  */
 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();

src/Foundation/Facades/Files.php

@@ -13,7 +13,6 @@
  */
 class Files extends Facade
 {
-    /**  @return \Hyde\Foundation\Kernel\FileCollection<string, \Hyde\Support\Filesystem\SourceFile> */
     public static function getFacadeRoot(): FileCollection
     {
         return HydeKernel::getInstance()->files();

src/Foundation/Facades/Pages.php

@@ -13,7 +13,6 @@
  */
 class Pages extends Facade
 {
-    /** @return \Hyde\Foundation\Kernel\PageCollection<string, \Hyde\Pages\Concerns\HydePage> */
     public static function getFacadeRoot(): PageCollection
     {
         return HydeKernel::getInstance()->pages();

src/Foundation/Facades/Routes.php

@@ -19,7 +19,6 @@
  */
 class Routes extends Facade
 {
-    /** @return \Hyde\Foundation\Kernel\RouteCollection<string, \Hyde\Support\Models\Route> */
     public static function getFacadeRoot(): RouteCollection
     {
         return HydeKernel::getInstance()->routes();
@@ -41,7 +40,6 @@ public static function getOrFail(string $routeKey): Route
         return static::getFacadeRoot()->getRoute($routeKey);
     }
 
-    /** @return \Hyde\Foundation\Kernel\RouteCollection<\Hyde\Support\Models\Route> */
     public static function all(): RouteCollection
     {
         return static::getFacadeRoot()->getRoutes();

src/Foundation/HydeKernel.php

@@ -136,6 +136,7 @@ public function hasFeature(Feature|string $feature): bool
     public function toArray(): array
     {
         return [
+            'version' => self::VERSION,
             'basePath' => $this->basePath,
             'sourceRoot' => $this->sourceRoot,
             'outputDirectory' => $this->outputDirectory,

src/Foundation/Internal/LoadYamlConfiguration.php

@@ -26,14 +26,19 @@
 class LoadYamlConfiguration
 {
     protected YamlConfigurationRepository $yaml;
+
+    /** @var array<string, array<string, null|scalar|array>> */
     protected array $config;
 
     public function bootstrap(Application $app): void
     {
         $this->yaml = $app->make(YamlConfigurationRepository::class);
 
         if ($this->yaml->hasYamlConfigFile()) {
-            tap($app->make('config'), function (Repository $config): void {
+            /** @var Repository $config */
+            $config = $app->make('config');
+
+            tap($config, function (Repository $config): void {
                 $this->config = $config->all();
                 $this->mergeParsedConfiguration();
             })->set($this->config);

src/Foundation/Kernel/FileCollection.php

@@ -4,21 +4,21 @@
 
 namespace Hyde\Foundation\Kernel;
 
+use Hyde\Facades\Filesystem;
 use Hyde\Foundation\Concerns\BaseFoundationCollection;
 use Hyde\Framework\Exceptions\FileNotFoundException;
 use Hyde\Pages\Concerns\HydePage;
 use Hyde\Support\Filesystem\SourceFile;
 
 use function basename;
-use function glob;
 use function str_starts_with;
 
 /**
  * The FileCollection contains all the discovered source files.
  *
  * @template T of \Hyde\Support\Filesystem\SourceFile
  *
- * @template-extends \Hyde\Foundation\Concerns\BaseFoundationCollection<string, T>
+ * @extends \Hyde\Foundation\Concerns\BaseFoundationCollection<string, T>
  *
  * @property array<string, SourceFile> $items The files in the collection.
  *
@@ -59,7 +59,7 @@ protected function runExtensionHandlers(): void
     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 $path) {
+        foreach (Filesystem::findFiles($pageClass::sourceDirectory(), $pageClass::fileExtension(), true) as $path) {
             if (! str_starts_with(basename((string) $path), '_')) {
                 $this->addFile(SourceFile::make($path, $pageClass));
             }
@@ -71,10 +71,7 @@ public function getFile(string $path): SourceFile
         return $this->get($path) ?? throw new FileNotFoundException($path);
     }
 
-    /**
-     * @param  class-string<\Hyde\Pages\Concerns\HydePage>|null  $pageClass
-     * @return \Hyde\Foundation\Kernel\FileCollection<string, \Hyde\Support\Filesystem\SourceFile>
-     */
+    /** @param  class-string<\Hyde\Pages\Concerns\HydePage>|null  $pageClass */
     public function getFiles(?string $pageClass = null): FileCollection
     {
         return $pageClass ? $this->filter(function (SourceFile $file) use ($pageClass): bool {

src/Foundation/Kernel/Filesystem.php

@@ -8,6 +8,7 @@
 use Hyde\Foundation\HydeKernel;
 use Hyde\Foundation\PharSupport;
 use Illuminate\Support\Collection;
+use Hyde\Framework\Actions\Internal\FileFinder;
 
 use function collect;
 use function Hyde\normalize_slashes;
@@ -183,4 +184,16 @@ public function smartGlob(string $pattern, int $flags = 0): Collection
 
         return $files->map(fn (string $path): string => $this->pathToRelative($path));
     }
+
+    /**
+     * @param  string|array<string>|false  $matchExtensions
+     * @return \Illuminate\Support\Collection<int, string>
+     */
+    public function findFiles(string $directory, string|array|false $matchExtensions = false, bool $recursive = false): Collection
+    {
+        /** @var \Hyde\Framework\Actions\Internal\FileFinder $finder */
+        $finder = app(FileFinder::class);
+
+        return $finder->handle($directory, $matchExtensions, $recursive);
+    }
 }

src/Foundation/Kernel/Hyperlinks.php

@@ -7,6 +7,7 @@
 use Hyde\Facades\Config;
 use Hyde\Support\Models\Route;
 use Hyde\Foundation\HydeKernel;
+use JetBrains\PhpStorm\Deprecated;
 use Hyde\Framework\Exceptions\BaseUrlNotSetException;
 use Hyde\Framework\Exceptions\FileNotFoundException;
 use Illuminate\Support\Str;
@@ -92,7 +93,10 @@ public function relativeLink(string $destination): string
      *
      * An exception will be thrown if the file does not exist in the _media directory,
      * and the second argument is set to true.
+     *
+     * @deprecated This method will be removed in v2.0. Please use `asset()` instead.
      */
+    #[Deprecated(reason: 'Use `asset` method instead.', replacement: '%class%->asset(%parameter0%)')]
     public function mediaLink(string $destination, bool $validate = false): string
     {
         if ($validate && ! file_exists($sourcePath = "{$this->kernel->getMediaDirectory()}/$destination")) {
@@ -111,7 +115,7 @@ public function mediaLink(string $destination, bool $validate = false): string
      */
     public function asset(string $name, bool $preferQualifiedUrl = false): string
     {
-        if (str_starts_with($name, 'http')) {
+        if (static::isRemote($name)) {
             return $name;
         }
 
@@ -147,7 +151,7 @@ public function url(string $path = ''): string
     {
         $path = $this->formatLink(trim($path, '/'));
 
-        if (str_starts_with($path, 'http')) {
+        if (static::isRemote($path)) {
             return $path;
         }
 
@@ -173,4 +177,12 @@ public function route(string $key): ?Route
     {
         return $this->kernel->routes()->get($key);
     }
+
+    /**
+     * Determine if the given URL is a remote link.
+     */
+    public static function isRemote(string $url): bool
+    {
+        return str_starts_with($url, 'http') || str_starts_with($url, '//');
+    }
 }

src/Foundation/Kernel/PageCollection.php

@@ -14,7 +14,7 @@
  *
  * @template T of \Hyde\Pages\Concerns\HydePage
  *
- * @template-extends \Hyde\Foundation\Concerns\BaseFoundationCollection<string, T>
+ * @extends \Hyde\Foundation\Concerns\BaseFoundationCollection<string, T>
  *
  * @property array<string, HydePage> $items The pages in the collection.
  *
@@ -59,10 +59,7 @@ public function getPage(string $sourcePath): HydePage
         return $this->get($sourcePath) ?? throw new FileNotFoundException($sourcePath);
     }
 
-    /**
-     * @param  class-string<\Hyde\Pages\Concerns\HydePage>|null  $pageClass
-     * @return \Hyde\Foundation\Kernel\PageCollection<string, \Hyde\Pages\Concerns\HydePage>
-     */
+    /** @param  class-string<\Hyde\Pages\Concerns\HydePage>|null  $pageClass */
     public function getPages(?string $pageClass = null): PageCollection
     {
         return $pageClass ? $this->filter(function (HydePage $page) use ($pageClass): bool {

src/Foundation/Kernel/RouteCollection.php

@@ -15,7 +15,7 @@
  *
  * @template T of \Hyde\Support\Models\Route
  *
- * @template-extends \Hyde\Foundation\Concerns\BaseFoundationCollection<string, T>
+ * @extends \Hyde\Foundation\Concerns\BaseFoundationCollection<string, T>
  *
  * @property array<string, Route> $items The routes in the collection.
  *
@@ -53,10 +53,7 @@ public function getRoute(string $routeKey): Route
         return $this->get($routeKey) ?? throw new RouteNotFoundException($routeKey);
     }
 
-    /**
-     * @param  class-string<\Hyde\Pages\Concerns\HydePage>|null  $pageClass
-     * @return \Hyde\Foundation\Kernel\RouteCollection<string, \Hyde\Support\Models\Route>
-     */
+    /** @param  class-string<\Hyde\Pages\Concerns\HydePage>|null  $pageClass */
     public function getRoutes(?string $pageClass = null): RouteCollection
     {
         return $pageClass ? $this->filter(function (Route $route) use ($pageClass): bool {

src/Framework/Actions/BladeMatterParser.php

@@ -4,10 +4,9 @@
 
 namespace Hyde\Framework\Actions;
 
-use Hyde\Hyde;
 use RuntimeException;
+use Hyde\Facades\Filesystem;
 
-use function file_get_contents;
 use function str_ends_with;
 use function str_starts_with;
 use function substr_count;
@@ -53,7 +52,7 @@ class BladeMatterParser
 
     public static function parseFile(string $path): array
     {
-        return static::parseString(file_get_contents(Hyde::path($path)));
+        return static::parseString(Filesystem::getContents($path));
     }
 
     public static function parseString(string $contents): array