Merge branch 'master' into 2.x-dev

docs/architecture-concepts/the-hydekernel.md

@@ -41,7 +41,7 @@ app(HydeKernel::class)->version();
 hyde()->version();
 ```
 
-The Kernel instance is constructed in `bootstrap.php`, and is available globally as `$hyde`.
+The Kernel instance is constructed and bound in the `app/bootstrap.php` file.
 
 
 ## The Kernel Lifecycle

monorepo/CodeIntelligence/CodeIntelligence.php

@@ -14,6 +14,8 @@
 use Hyde\Foundation\HydeKernel;
 use Hyde\Markdown\Models\MarkdownDocument;
 
+use function Hyde\normalize_slashes;
+
 if (php_sapi_name() !== 'cli') {
     // Run the file and proxy the dashboard page for a live browser preview
     exec('php '.realpath(__FILE__).' 2>&1', $output, $returnCode);
@@ -70,7 +72,7 @@
     ));
 
     $this->line();
-    $this->line('Dashboard page generated at '.OUTPUT_PATH.'/dashboard.html');
+    $this->line(sprintf('Dashboard page generated at file:///%s', normalize_slashes(realpath(OUTPUT_PATH.'/dashboard.html'))));
 
     $this->line();
     $this->info(sprintf('Time taken: %s. Memory used: %s',

packages/framework/src/Console/Commands/BuildSiteCommand.php

@@ -10,11 +10,11 @@
 use Hyde\Console\Concerns\Command;
 use Hyde\Framework\Services\BuildService;
 use Hyde\Framework\Services\BuildTaskService;
+use Illuminate\Support\Facades\Process;
 
 use function memory_get_peak_usage;
 use function number_format;
 use function array_search;
-use function shell_exec;
 use function microtime;
 use function sprintf;
 use function app;
@@ -137,13 +137,9 @@ protected function runNodeCommand(string $command, string $message, ?string $act
     {
         $this->info($message.' This may take a second.');
 
-        $output = shell_exec(sprintf(
-            '%s%s',
-            (string) app()->environment() === 'testing' ? 'echo ' : '',
-            $command
-        ));
+        $output = Process::command($command)->run();
 
-        $this->line($output ?? sprintf(
+        $this->line($output->output() ?? sprintf(
             '<fg=red>Could not %s! Is NPM installed?</>',
             $actionMessage ?? 'run script'
         ));

packages/framework/src/Console/Commands/PublishHomepageCommand.php

@@ -64,8 +64,8 @@ public function handle(): int
 
         Artisan::call('vendor:publish', [
             '--tag' => $this->options[$selected]['group'] ?? $selected,
-            '--force' => true, // Todo add force state dynamically depending on existing file state
-        ], ! $tagExists ? $this->output : null);
+            '--force' => true,
+        ], $tagExists ? null : $this->output); // If the tag doesn't exist, we pass the output to use the called command's error output.
 
         if ($tagExists) {
             $this->infoComment("Published page [$selected]");

packages/framework/src/Foundation/HydeKernel.php

@@ -31,10 +31,9 @@
  * The HydeKernel It is stored as a singleton in this class, and is bound into the
  * Laravel Application Service Container, and can be accessed in a few ways.
  *
- * Commonly, you'll use the Hyde facade, but you can also use Dependency Injection
+ * Commonly, you'll use the Hyde facade to access it, but you can also use Dependency Injection
  * by type-hinting the HydeKernel::class, or use the hyde() function to get the Kernel.
- *
- * The Kernel instance is constructed in bootstrap.php, and is available globally as $hyde.
+ * The Kernel instance is constructed and bound in the app/bootstrap.php script.
  */
 class HydeKernel implements SerializableContract
 {

packages/framework/src/Foundation/Internal/LoadConfiguration.php

@@ -19,7 +19,7 @@ class LoadConfiguration extends BaseLoadConfiguration
     /** Get all the configuration files for the application. */
     protected function getConfigurationFiles(Application $app): array
     {
-        return (array) tap(parent::getConfigurationFiles($app), function (array &$files) use ($app): void {
+        return (array) tap(parent::getConfigurationFiles($app), /** @param array<string, string> $files */ function (array &$files) use ($app): void {
             // Inject our custom config file which is stored in `app/config.php`.
             $files['app'] ??= $app->basePath().DIRECTORY_SEPARATOR.'app'.DIRECTORY_SEPARATOR.'config.php';
         });

packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php

@@ -46,7 +46,7 @@ protected function hasYamlConfigFile(): bool
             || file_exists(Hyde::path('hyde.yaml'));
     }
 
-    /** @return array<string, mixed> */
+    /** @return array<string, scalar> */
     protected function getYaml(): array
     {
         return Arr::undot((array) Yaml::parse(file_get_contents($this->getFile())));

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

@@ -16,7 +16,6 @@
 use function array_map;
 use function is_string;
 use function is_array;
-use function collect;
 use function str_starts_with;
 use function unslash;
 use function unlink;
@@ -198,8 +197,9 @@ public function unlinkIfExists(string $path): bool
     /** @return \Illuminate\Support\Collection<int, string> */
     public function smartGlob(string $pattern, int $flags = 0): Collection
     {
-        return collect(\Hyde\Facades\Filesystem::glob($pattern, $flags))
-            ->map(fn (string $path): string => $this->pathToRelative($path))
-            ->values();
+        /** @var \Illuminate\Support\Collection<int, string> $files */
+        $files = collect(\Hyde\Facades\Filesystem::glob($pattern, $flags));
+
+        return $files->map(fn (string $path): string => $this->pathToRelative($path));
     }
 }

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

@@ -49,7 +49,7 @@ protected function runExtensionHandlers(): void
     }
 
     /** @param  class-string<\Hyde\Pages\Concerns\HydePage>  $pageClass */
-    protected static function parsePage(string $pageClass, string $path)
+    protected static function parsePage(string $pageClass, string $path): HydePage
     {
         return $pageClass::parse($pageClass::pathToIdentifier($path));
     }

packages/framework/src/Framework/Actions/BladeMatterParser.php

@@ -136,7 +136,11 @@ protected static function getValueWithType(string $value): mixed
 
         // This will cast integers, floats, and booleans to their respective types
         // Still working on a way to handle multidimensional arrays and objects
-        return json_decode($value) ?? $value;
+
+        /** @var scalar|null $decoded */
+        $decoded = json_decode($value);
+
+        return $decoded ?? $value;
     }
 
     /** @return array<string, scalar> */
@@ -153,7 +157,7 @@ protected static function parseArrayString(string $string): array
         }
 
         // Check if string is multidimensional (not yet supported)
-        if (substr_count($string, '[') > 1 || substr_count($string, ']') > 1) {
+        if ((substr_count($string, '[') > 1) || (substr_count($string, ']') > 1)) {
             throw new RuntimeException('Failed parsing BladeMatter array. Multidimensional arrays are not supported yet.');
         }
 
@@ -171,6 +175,7 @@ protected static function parseArrayString(string $string): array
             // Add key/value pair to array
             $key = (string) static::getValueWithType(trim(trim($pair[0]), "'"));
             $value = static::getValueWithType(trim(trim($pair[1]), "'"));
+
             $array[$key] = $value;
         }
 

packages/framework/src/Framework/Actions/ConvertsMarkdownToPlainText.php

@@ -4,7 +4,9 @@
 
 namespace Hyde\Framework\Actions;
 
+use function trim;
 use function rtrim;
+use function is_numeric;
 use function str_ends_with;
 use function str_starts_with;
 use function substr;

packages/framework/src/Framework/Actions/PostBuildTasks/GenerateBuildManifest.php

@@ -77,7 +77,7 @@ protected function jsonEncodeOutput(Collection $pages): string
         ], JSON_PRETTY_PRINT);
     }
 
-    public function setOutput(OutputStyle $output)
+    public function setOutput(OutputStyle $output): void
     {
         // Disable output
     }

packages/framework/src/Framework/Actions/PostBuildTasks/GenerateSitemap.php

@@ -9,6 +9,7 @@
 use Hyde\Framework\Concerns\InteractsWithDirectories;
 use Hyde\Framework\Features\XmlGenerators\SitemapGenerator;
 
+use function blank;
 use function file_put_contents;
 
 class GenerateSitemap extends PostBuildTask

packages/framework/src/Framework/Actions/PreBuildTasks/CleanSiteDirectory.php

@@ -6,10 +6,9 @@
 
 use Hyde\Hyde;
 use Hyde\Facades\Config;
+use Hyde\Facades\Filesystem;
 use Hyde\Framework\Features\BuildTasks\PreBuildTask;
-use Illuminate\Support\Facades\File;
 
-use function array_map;
 use function basename;
 use function glob;
 use function in_array;
@@ -22,8 +21,8 @@ class CleanSiteDirectory extends PreBuildTask
     public function handle(): void
     {
         if ($this->isItSafeToCleanOutputDirectory()) {
-            array_map('unlink', glob(Hyde::sitePath('*.{html,json}'), GLOB_BRACE));
-            File::cleanDirectory(Hyde::siteMediaPath());
+            Filesystem::unlink(glob(Hyde::sitePath('*.{html,json}'), GLOB_BRACE));
+            Filesystem::cleanDirectory(Hyde::siteMediaPath());
         }
     }
 

packages/framework/src/Framework/Concerns/Internal/ForwardsIlluminateFilesystem.php

@@ -59,7 +59,7 @@
  * @method static bool isWritable(string $path)
  * @method static bool hasSameHash(string $firstFile, string $secondFile)
  * @method static bool isFile(string $file)
- * @method static array glob(string $pattern, int $flags = 0)
+ * @method static array<string> glob(string $pattern, int $flags = 0)
  * @method static SplFileInfo[] files(string $directory, bool $hidden = false)
  * @method static SplFileInfo[] allFiles(string $directory, bool $hidden = false)
  * @method static array directories(string $directory)
@@ -89,10 +89,7 @@ protected static function getParameterNames(string $name): array
     protected static function qualifyArguments(array $parameterNames, array $arguments): Collection
     {
         return collect($arguments)->mapWithKeys(function (string|array|int|bool $argumentValue, int|string $key) use ($parameterNames): string|array|int|bool {
-            $argumentsToQualify = [
-                'path', 'paths', 'file', 'target', 'directory', 'destination', 'firstFile', 'secondFile',
-                'pattern', 'link', 'from', 'to',
-            ];
+            $argumentsToQualify = ['path', 'paths', 'file', 'target', 'directory', 'destination', 'firstFile', 'secondFile', 'pattern', 'link', 'from', 'to'];
 
             if (is_int($key)) {
                 // If the argument is not named, we'll retrieve it from the reflection data.

packages/framework/src/Framework/Factories/BlogPostDataFactory.php

@@ -4,6 +4,7 @@
 
 namespace Hyde\Framework\Factories;
 
+use Illuminate\Support\Str;
 use Hyde\Framework\Factories\Concerns\CoreDataObject;
 use Hyde\Framework\Actions\ConvertsMarkdownToPlainText;
 use Hyde\Framework\Features\Blogging\Models\FeaturedImage;
@@ -13,9 +14,6 @@
 use Hyde\Markdown\Models\Markdown;
 use Hyde\Support\Models\DateString;
 
-use function strlen;
-use function substr;
-
 /**
  * Streamlines the data construction specific to a blog post.
  *
@@ -110,25 +108,14 @@ protected function makeImage(): ?FeaturedImage
 
     private function makeDescriptionFromMarkdownBody(): string
     {
-        return $this->getTruncatedMarkdown($this->stripMarkdownFromBody($this->markdown->body()));
-    }
-
-    private function getTruncatedMarkdown(string $markdown): string
-    {
-        if (strlen($markdown) >= 128) {
-            return substr($markdown, 0, 125).'...';
-        }
-
-        return $markdown;
-    }
-
-    private function stripMarkdownFromBody(string $body): string
-    {
-        return (new ConvertsMarkdownToPlainText($body))->execute();
+        return Str::limit((new ConvertsMarkdownToPlainText($this->markdown->body()))->execute(), 125);
     }
 
     protected function getMatter(string $key): string|null|array
     {
-        return $this->matter->get($key);
+        /** @var string|null|array $value */
+        $value = $this->matter->get($key);
+
+        return $value;
     }
 }

packages/framework/src/Framework/Factories/FeaturedImageFactory.php

@@ -91,6 +91,9 @@ protected static function normalizeLocalImagePath(string $path): string
 
     protected function getStringMatter(string $key): ?string
     {
-        return is_string($this->matter->get($key)) ? $this->matter->get($key) : null;
+        /** @var string|null $value */
+        $value = $this->matter->get($key);
+
+        return is_string($value) ? $value : null;
     }
 }

packages/framework/src/Framework/Factories/HydePageDataFactory.php

@@ -28,21 +28,15 @@ class HydePageDataFactory extends Concerns\PageDataFactory implements PageSchema
 
     protected readonly string $title;
     protected readonly ?NavigationData $navigation;
-    private readonly string $routeKey;
-    private readonly string $outputPath;
     private readonly string $identifier;
-    private readonly string $pageClass;
     private readonly Markdown|false $markdown;
     private readonly FrontMatter $matter;
 
     public function __construct(private readonly CoreDataObject $pageData)
     {
         $this->matter = $this->pageData->matter;
         $this->markdown = $this->pageData->markdown;
-        $this->pageClass = $this->pageData->pageClass;
         $this->identifier = $this->pageData->identifier;
-        $this->outputPath = $this->pageData->outputPath;
-        $this->routeKey = $this->pageData->routeKey;
 
         $this->title = $this->makeTitle();
         $this->navigation = $this->makeNavigation();
@@ -101,6 +95,9 @@ private function findTitleFromParentIdentifier(): ?string
 
     protected function getMatter(string $key): string|null
     {
-        return $this->matter->get($key);
+        /** @var ?string $value */
+        $value = $this->matter->get($key);
+
+        return $value;
     }
 }

packages/framework/src/Framework/Factories/NavigationDataFactory.php

@@ -125,7 +125,7 @@ private function searchForHiddenInConfigs(): ?bool
             : $this->isPageHiddenInNavigationConfiguration();
     }
 
-    private function isPageHiddenInNavigationConfiguration(): ?bool
+    private function isPageHiddenInNavigationConfiguration(): bool
     {
         return in_array($this->routeKey, Config::getArray('hyde.navigation.exclude', ['404']));
     }
@@ -215,9 +215,13 @@ private function searchForPriorityInNavigationConfig(): ?int
         return $this->parseNavigationPriorityConfig($config, 'routeKey');
     }
 
-    /** @param array<string, int>|array<string> $config */
+    /**
+     * @param  array<string, int>|array<string>  $config
+     * @param  'routeKey'|'identifier'  $pageKeyName
+     */
     private function parseNavigationPriorityConfig(array $config, string $pageKeyName): ?int
     {
+        /** @var string $pageKey */
         $pageKey = $this->{$pageKeyName};
 
         // Check if the config entry is a flat array or a keyed array.
@@ -256,7 +260,7 @@ protected function getSubdirectoryConfiguration(): string
         return Config::getString('hyde.navigation.subdirectories', 'hidden');
     }
 
-    /** @param class-string $class */
+    /** @param class-string<\Hyde\Pages\Concerns\HydePage> $class */
     protected function isInstanceOf(string $class): bool
     {
         return is_a($this->pageClass, $class, true);
@@ -274,6 +278,9 @@ protected function offset(?int $value, int $offset): ?int
 
     protected function getMatter(string $key): string|null|int|bool
     {
-        return $this->matter->get($key);
+        /** @var string|null|int|bool $value */
+        $value = $this->matter->get($key);
+
+        return $value;
     }
 }

packages/framework/src/Framework/Features/Blogging/Models/FeaturedImage.php

@@ -63,7 +63,7 @@ public function __construct(
         protected readonly ?string $licenseUrl = null,
         protected readonly ?string $copyrightText = null
     ) {
-        $this->type = $this->isRemote($source) ? self::TYPE_REMOTE : self::TYPE_LOCAL;
+        $this->type = self::isRemote($source) ? self::TYPE_REMOTE : self::TYPE_LOCAL;
         $this->source = $this->setSource($source);
     }
 
@@ -224,7 +224,7 @@ protected function getContentLengthForLocalImage(): int
 
     protected function getContentLengthForRemoteImage(): int
     {
-        // Check if the --no-api flag is set when running the build command, and if so, skip the API call.
+        // API calls can be skipped in the config, or by setting the --no-api flag when running the build command.
         if (Config::getBool('hyde.api_calls', true)) {
             /** @var string[][] $headers */
             $headers = Http::withHeaders([