Merge pull request #1911 from hydephp/normalize-media-path-helpers

[2.x] Normalize media path helpers to unify naming with HydePages

app/config.php

@@ -105,6 +105,7 @@
         'MarkdownPage' => \Hyde\Pages\MarkdownPage::class,
         'MarkdownPost' => \Hyde\Pages\MarkdownPost::class,
         'DocumentationPage' => \Hyde\Pages\DocumentationPage::class,
+        'MediaFile' => \Hyde\Support\Filesystem\MediaFile::class,
         'DataCollection' => \Hyde\Support\DataCollection::class,
         'Includes' => \Hyde\Support\Includes::class,
         'Feature' => \Hyde\Enums\Feature::class,

docs/_data/partials/hyde-pages-api/hyde-kernel-filesystem-methods.md

@@ -1,7 +1,7 @@
 <section id="hyde-kernel-filesystem-methods">
 
 <!-- Start generated docs for Hyde\Foundation\Concerns\ForwardsFilesystem -->
-<!-- Generated by HydePHP DocGen script at 2023-03-11 11:17:34 in 0.10ms -->
+<!-- Generated by HydePHP DocGen script at 2024-07-26 15:15:12 in 0.09ms -->
 
 #### `filesystem()`
 
@@ -27,14 +27,6 @@ No description provided.
 Hyde::vendorPath(string $path, string $package): string
 ```
 
-#### `mediaPath()`
-
-No description provided.
-
-```php
-Hyde::mediaPath(string $path): string
-```
-
 #### `sitePath()`
 
 No description provided.
@@ -43,14 +35,6 @@ No description provided.
 Hyde::sitePath(string $path): string
 ```
 
-#### `siteMediaPath()`
-
-No description provided.
-
-```php
-Hyde::siteMediaPath(string $path): string
-```
-
 #### `pathToAbsolute()`
 
 No description provided.

packages/framework/resources/views/layouts/head.blade.php

@@ -2,7 +2,7 @@
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>{{ $page->title() }}</title>
 
-@if (file_exists(Hyde::mediaPath('favicon.ico')))
+@if (file_exists(MediaFile::sourcePath('favicon.ico')))
     <link rel="shortcut icon" href="{{ Hyde::relativeLink('media/favicon.ico') }}" type="image/x-icon">
 @endif
 

packages/framework/src/Facades/Asset.php

@@ -5,6 +5,7 @@
 namespace Hyde\Facades;
 
 use Hyde\Hyde;
+use Hyde\Support\Filesystem\MediaFile;
 
 use function md5_file;
 use function file_exists;
@@ -24,13 +25,13 @@ public static function mediaLink(string $file): string
 
     public static function hasMediaFile(string $file): bool
     {
-        return file_exists(Hyde::mediaPath($file));
+        return file_exists(MediaFile::sourcePath($file));
     }
 
     protected static function getCacheBustKey(string $file): string
     {
         return Config::getBool('hyde.enable_cache_busting', true)
-            ? '?v='.md5_file(Hyde::mediaPath("$file"))
+            ? '?v='.md5_file(MediaFile::sourcePath("$file"))
             : '';
     }
 }

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

@@ -28,21 +28,11 @@ public function vendorPath(string $path = '', string $package = 'framework'): st
         return $this->filesystem->vendorPath($path, $package);
     }
 
-    public function mediaPath(string $path = ''): string
-    {
-        return $this->filesystem->mediaPath($path);
-    }
-
     public function sitePath(string $path = ''): string
     {
         return $this->filesystem->sitePath($path);
     }
 
-    public function siteMediaPath(string $path = ''): string
-    {
-        return $this->filesystem->siteMediaPath($path);
-    }
-
     public function pathToAbsolute(string|array $path): string|array
     {
         return $this->filesystem->pathToAbsolute($path);

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

@@ -91,18 +91,6 @@ public function pathToRelative(string $path): string
             : $path);
     }
 
-    /**
-     * Get the absolute path to the media source directory, or a file within it.
-     */
-    public function mediaPath(string $path = ''): string
-    {
-        if (empty($path)) {
-            return $this->path(Hyde::getMediaDirectory());
-        }
-
-        return $this->path(path_join(Hyde::getMediaDirectory(), unslash($path)));
-    }
-
     /**
      * Get the absolute path to the compiled site directory, or a file within it.
      */
@@ -115,20 +103,6 @@ public function sitePath(string $path = ''): string
         return $this->path(path_join(Hyde::getOutputDirectory(), unslash($path)));
     }
 
-    /**
-     * Get the absolute path to the compiled site's media directory, or a file within it.
-     */
-    public function siteMediaPath(string $path = ''): string
-    {
-        if (empty($path)) {
-            return $this->sitePath(Hyde::getMediaOutputDirectory());
-        }
-
-        $path = unslash($path);
-
-        return $this->sitePath(Hyde::getMediaOutputDirectory()."/$path");
-    }
-
     /**
      * Works similarly to the path() function, but returns a file in the Framework package.
      *

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

@@ -7,6 +7,7 @@
 use Hyde\Hyde;
 use Hyde\Facades\Config;
 use Hyde\Facades\Filesystem;
+use Hyde\Support\Filesystem\MediaFile;
 use Hyde\Framework\Features\BuildTasks\PreBuildTask;
 
 use function basename;
@@ -22,7 +23,7 @@ public function handle(): void
     {
         if ($this->isItSafeToCleanOutputDirectory()) {
             Filesystem::unlink(glob(Hyde::sitePath('*.{html,json}'), GLOB_BRACE));
-            Filesystem::cleanDirectory(Hyde::siteMediaPath());
+            Filesystem::cleanDirectory(MediaFile::outputPath());
         }
     }
 

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

@@ -4,7 +4,6 @@
 
 namespace Hyde\Framework\Actions\PreBuildTasks;
 
-use Hyde\Hyde;
 use Hyde\Support\Filesystem\MediaFile;
 use Hyde\Framework\Features\BuildTasks\PreBuildTask;
 use Hyde\Framework\Concerns\InteractsWithDirectories;
@@ -17,14 +16,14 @@ class TransferMediaAssets extends PreBuildTask
 
     public function handle(): void
     {
-        $this->needsDirectory(Hyde::siteMediaPath());
+        $this->needsDirectory(MediaFile::outputPath());
 
         $this->newLine();
 
         $this->withProgressBar(MediaFile::files(), function (string $identifier): void {
-            $sitePath = Hyde::siteMediaPath($identifier);
+            $sitePath = MediaFile::outputPath($identifier);
             $this->needsParentDirectory($sitePath);
-            copy(Hyde::mediaPath($identifier), $sitePath);
+            copy(MediaFile::sourcePath($identifier), $sitePath);
         });
 
         $this->newLine();

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

@@ -11,6 +11,7 @@
 use Hyde\Support\BuildWarnings;
 use Illuminate\Support\Facades\Http;
 use Hyde\Foundation\Kernel\Hyperlinks;
+use Hyde\Support\Filesystem\MediaFile;
 use Hyde\Framework\Exceptions\FileNotFoundException;
 use Hyde\Markdown\Contracts\FrontMatter\SubSchemas\FeaturedImageSchema;
 
@@ -213,7 +214,7 @@ protected function has(string $property): bool
 
     protected function getContentLengthForLocalImage(): int
     {
-        $storagePath = Hyde::mediaPath($this->source);
+        $storagePath = MediaFile::sourcePath($this->source);
 
         if (! file_exists($storagePath)) {
             throw new FileNotFoundException(customMessage: sprintf('Featured image [%s] not found.', Hyde::pathToRelative($storagePath)));

packages/framework/src/Framework/Services/ValidationService.php

@@ -11,6 +11,7 @@
 use Hyde\Pages\MarkdownPage;
 use Hyde\Pages\DocumentationPage;
 use Hyde\Enums\Feature;
+use Hyde\Support\Filesystem\MediaFile;
 use Hyde\Support\Models\ValidationResult as Result;
 
 use function count;
@@ -102,12 +103,12 @@ public function check_documentation_site_has_an_index_page(Result $result): Resu
 
     public function check_site_has_an_app_css_stylesheet(Result $result): Result
     {
-        if (file_exists(Hyde::siteMediaPath('/app.css')) || file_exists(Hyde::mediaPath('app.css'))) {
+        if (file_exists(MediaFile::outputPath('/app.css')) || file_exists(MediaFile::sourcePath('app.css'))) {
             return $result->pass('Your site has an app.css stylesheet');
         }
 
         return $result->fail(sprintf('Could not find an app.css file in the %s or %s directory!',
-            Hyde::pathToRelative(Hyde::siteMediaPath()), Hyde::getMediaDirectory()
+            Hyde::pathToRelative(MediaFile::outputPath()), Hyde::getMediaDirectory()
         ))->withTip('You may need to run `npm run dev`.`');
     }
 

packages/framework/src/Hyde.php

@@ -7,6 +7,7 @@
 use Hyde\Enums\Feature;
 use Hyde\Facades\Features;
 use Hyde\Foundation\HydeKernel;
+use Hyde\Support\V1Compatibility;
 use Illuminate\Support\Collection;
 use Hyde\Foundation\Kernel\FileCollection;
 use Hyde\Foundation\Kernel\Filesystem;
@@ -33,8 +34,6 @@
  * @method static string pathToAbsolute(string $path)
  * @method static string pathToRelative(string $path)
  * @method static string sitePath(string $path = '')
- * @method static string mediaPath(string $path = '')
- * @method static string siteMediaPath(string $path = '')
  * @method static string formatLink(string $destination)
  * @method static string relativeLink(string $destination)
  * @method static string mediaLink(string $destination, bool $validate = false)
@@ -79,6 +78,8 @@
  */
 class Hyde extends Facade
 {
+    use V1Compatibility;
+
     public static function version(): string
     {
         return HydeKernel::version();

packages/framework/src/Support/Filesystem/MediaFile.php

@@ -9,6 +9,8 @@
 use Hyde\Framework\Exceptions\FileNotFoundException;
 use Illuminate\Support\Str;
 
+use function Hyde\unslash;
+use function Hyde\path_join;
 use function extension_loaded;
 use function file_exists;
 use function array_merge;
@@ -32,7 +34,7 @@ class MediaFile extends ProjectFile
     /** @return array<string, \Hyde\Support\Filesystem\MediaFile> The array keys are the filenames relative to the _media/ directory */
     public static function all(): array
     {
-        return static::discoverMediaAssetFiles();
+        return static::discoverMediaFiles();
     }
 
     /** @return array<string> Array of filenames relative to the _media/ directory */
@@ -41,6 +43,32 @@ public static function files(): array
         return array_keys(static::all());
     }
 
+    /**
+     * Get the absolute path to the media source directory, or a file within it.
+     */
+    public static function sourcePath(string $path = ''): string
+    {
+        if (empty($path)) {
+            return Hyde::path(Hyde::getMediaDirectory());
+        }
+
+        return Hyde::path(path_join(Hyde::getMediaDirectory(), unslash($path)));
+    }
+
+    /**
+     * Get the absolute path to the compiled site's media directory, or a file within it.
+     */
+    public static function outputPath(string $path = ''): string
+    {
+        if (empty($path)) {
+            return Hyde::sitePath(Hyde::getMediaOutputDirectory());
+        }
+
+        $path = unslash($path);
+
+        return Hyde::sitePath(Hyde::getMediaOutputDirectory()."/$path");
+    }
+
     public function getIdentifier(): string
     {
         return Str::after($this->getPath(), Hyde::getMediaDirectory().'/');
@@ -95,16 +123,16 @@ public function getMimeType(): string
         return 'text/plain';
     }
 
-    protected static function discoverMediaAssetFiles(): array
+    protected static function discoverMediaFiles(): array
     {
-        return collect(static::getMediaAssetFiles())->mapWithKeys(function (string $path): array {
+        return collect(static::getMediaFiles())->mapWithKeys(function (string $path): array {
             $file = static::make($path);
 
             return [$file->getIdentifier() => $file];
         })->all();
     }
 
-    protected static function getMediaAssetFiles(): array
+    protected static function getMediaFiles(): array
     {
         return glob(Hyde::path(static::getMediaGlobPattern()), GLOB_BRACE) ?: [];
     }

packages/framework/src/Support/V1Compatibility.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hyde\Support;
+
+use JetBrains\PhpStorm\Deprecated;
+use Hyde\Support\Filesystem\MediaFile;
+
+/**
+ * @internal Hyde Facade support to aid in the v1 to v2 transition.
+ *
+ * @deprecated All code here is deprecated, and exists to help you transition.
+ *
+ * @codeCoverageIgnore This class is ignored from code coverage.
+ */
+trait V1Compatibility
+{
+    /**
+     * @deprecated Use MediaFile::sourcePath() instead.
+     * @see \Hyde\Support\Filesystem\MediaFile::sourcePath()
+     */
+    #[Deprecated(reason: 'Use MediaFile::sourcePath() instead', replacement: '\Hyde\Support\Filesystem\MediaFile::sourcePath(%parametersList%)')]
+    public static function mediaPath(string $path = ''): string
+    {
+        return MediaFile::sourcePath($path);
+    }
+
+    /**
+     * @deprecated Use MediaFile::outputPath() instead.
+     * @see \Hyde\Support\Filesystem\MediaFile::outputPath()
+     */
+    #[Deprecated(reason: 'Use MediaFile::outputPath() instead', replacement: '\Hyde\Support\Filesystem\MediaFile::outputPath(%parametersList%)')]
+    public static function siteMediaPath(string $path = ''): string
+    {
+        return MediaFile::outputPath($path);
+    }
+}