[2.x] Improve the media file instance API

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

@@ -1,7 +1,7 @@
 <section id="hyde-kernel-hyperlink-methods">
 
 <!-- Start generated docs for Hyde\Foundation\Concerns\ForwardsHyperlinks -->
-<!-- Generated by HydePHP DocGen script at 2024-07-26 18:20:22 in 0.13ms -->
+<!-- Generated by HydePHP DocGen script at 2024-09-04 19:44:45 in 0.10ms -->
 
 #### `formatLink()`
 
@@ -19,20 +19,12 @@ No description provided.
 Hyde::relativeLink(string $destination): string
 ```
 
-#### `mediaLink()`
-
-No description provided.
-
-```php
-Hyde::mediaLink(string $destination, bool $validate): string
-```
-
 #### `asset()`
 
 No description provided.
 
 ```php
-Hyde::asset(string $name): string
+Hyde::asset(string $name): Hyde\Support\Filesystem\MediaFile
 ```
 
 #### `url()`

docs/architecture-concepts/the-hydekernel.md

@@ -205,14 +205,6 @@ No description provided.
 Hyde::relativeLink(string $destination): string
 ```
 
-#### `mediaLink()`
-
-No description provided.
-
-```php
-Hyde::mediaLink(string $destination, bool $validate): string
-```
-
 #### `asset()`
 
 No description provided.

ide.json

@@ -15,6 +15,35 @@
                 }
             ]
         },
+        {
+            "complete": "directoryFiles",
+            "options": {
+                "directory": "/_media"
+            },
+            "condition": [
+                {
+                    "methodNames": ["get", "hasMediaFile"],
+                    "place": "parameter",
+                    "classFqn": ["\\Hyde\\Facades\\Asset"],
+                    "parameters": [1]
+                },
+                {
+                    "methodNames": ["__construct", "get", "make", "sourcePath", "outputPath"],
+                    "place": "parameter",
+                    "classFqn": ["Hyde\\Support\\Filesystem\\MediaFile"],
+                    "parameters": [1]
+                }, {
+                    "methodNames": ["asset"],
+                    "place": "parameter",
+                    "classFqn": ["Hyde\\Foundation\\HydeKernel", "\\Hyde\\Hyde", "Hyde"],
+                    "parameters": [1]
+                }, {
+                    "functionNames": ["asset"],
+                    "place": "parameter",
+                    "parameters": [1]
+                }
+            ]
+        },
         {
             "complete": "configKey",
             "condition": [

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

@@ -1,6 +1,6 @@
 {{-- The compiled Laravel Mix scripts --}}
 @if(Asset::hasMediaFile('app.js'))
-    <script defer src="{{ Asset::mediaLink('app.js') }}"></script>
+    <script defer src="{{ Asset::get('app.js') }}"></script>
 @endif
 
 {{-- Alpine.js --}}

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

@@ -5,7 +5,7 @@
 @if(config('hyde.load_app_styles_from_cdn', false))
     <link rel="stylesheet" href="{{ HydeFront::cdnLink('app.css') }}">
 @elseif(Asset::hasMediaFile('app.css'))
-    <link rel="stylesheet" href="{{ Asset::mediaLink('app.css') }}">
+    <link rel="stylesheet" href="{{ Asset::get('app.css') }}">
 @endif
 
 {{-- Dynamic TailwindCSS Play CDN --}}

packages/framework/src/Facades/Asset.php

@@ -17,16 +17,11 @@
  */
 class Asset
 {
-    public static function get(string $file): string
+    public static function get(string $file): MediaFile
     {
         return hyde()->asset($file);
     }
 
-    public static function mediaLink(string $file): string
-    {
-        return hyde()->mediaLink($file);
-    }
-
     public static function hasMediaFile(string $file): bool
     {
         return file_exists(MediaFile::sourcePath($file));

packages/framework/src/Facades/Filesystem.php

@@ -129,6 +129,42 @@ public static function putContents(string $path, string $contents, bool $lock =
         return self::put($path, $contents, $lock);
     }
 
+    /**
+     * Improved mime type detection for the given path that can be relative to the project root,
+     * or a remote URL where this will try to guess the mime type based on the file extension.
+     *
+     * @param  string  $path  The path to the file, relative to the project root or a remote URL.
+     */
+    public static function findMimeType(string $path): string
+    {
+        $extension = self::extension($path);
+
+        $lookup = [
+            'txt' => 'text/plain',
+            'md' => 'text/markdown',
+            'html' => 'text/html',
+            'css' => 'text/css',
+            'svg' => 'image/svg+xml',
+            'png' => 'image/png',
+            'jpg' => 'image/jpeg',
+            'jpeg' => 'image/jpeg',
+            'gif' => 'image/gif',
+            'json' => 'application/json',
+            'js' => 'application/javascript',
+            'xml' => 'application/xml',
+        ];
+
+        if (isset($lookup[$extension])) {
+            return $lookup[$extension];
+        }
+
+        if (extension_loaded('fileinfo') && self::exists($path)) {
+            return self::mimeType($path);
+        }
+
+        return 'text/plain';
+    }
+
     protected static function filesystem(): \Illuminate\Filesystem\Filesystem
     {
         return app(\Illuminate\Filesystem\Filesystem::class);

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

@@ -5,6 +5,7 @@
 namespace Hyde\Foundation\Concerns;
 
 use Hyde\Support\Models\Route;
+use Hyde\Support\Filesystem\MediaFile;
 
 /**
  * @internal Single-use trait for the HydeKernel class.
@@ -23,12 +24,7 @@ public function relativeLink(string $destination): string
         return $this->hyperlinks->relativeLink($destination);
     }
 
-    public function mediaLink(string $destination, bool $validate = false): string
-    {
-        return $this->hyperlinks->mediaLink($destination, $validate);
-    }
-
-    public function asset(string $name): string
+    public function asset(string $name): MediaFile
     {
         return $this->hyperlinks->asset($name);
     }

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

@@ -10,12 +10,10 @@
 use Hyde\Foundation\HydeKernel;
 use Hyde\Support\Filesystem\MediaFile;
 use Hyde\Framework\Exceptions\FileNotFoundException;
-use Illuminate\Support\Str;
 
 use function str_ends_with;
 use function str_starts_with;
 use function substr_count;
-use function file_exists;
 use function str_replace;
 use function str_repeat;
 use function substr;
@@ -89,39 +87,17 @@ public function relativeLink(string $destination): string
     }
 
     /**
-     * Gets a relative web link to the given file stored in the _site/media folder.
-     *
-     * An exception will be thrown if the file does not exist in the _media directory,
-     * and the second argument is set to true.
-     */
-    public function mediaLink(string $destination, bool $validate = false): string
-    {
-        if ($validate && ! file_exists($sourcePath = "{$this->kernel->getMediaDirectory()}/$destination")) {
-            throw new FileNotFoundException($sourcePath);
-        }
-
-        return $this->withCacheBusting($this->relativeLink("{$this->kernel->getMediaOutputDirectory()}/$destination"), $destination);
-    }
-
-    /**
-     * Gets a relative web link to the given file stored in the `_site/media` folder.
-     * If the image is already qualified (starts with `http`) it will be returned as is.
+     * Gets a MediaAsset instance for the given file stored in the `_site/media` folder.
+     * The returned value can be cast into a string in Blade views to resole the URL.
      *
      * If a base URL is configured, the image will be returned with a qualified absolute URL.
+     * Otherwise, a relative path will be returned based on the rendered page's location.
+     *
+     * @throws FileNotFoundException If the file does not exist in the `_media` directory in order to make the issue clear.
      */
-    public function asset(string $name): string
+    public function asset(string $name): MediaFile
     {
-        if (static::isRemote($name)) {
-            return $name;
-        }
-
-        $name = Str::start($name, "{$this->kernel->getMediaOutputDirectory()}/");
-
-        if ($this->hasSiteUrl()) {
-            return $this->withCacheBusting($this->url($name), $name);
-        }
-
-        return $this->withCacheBusting($this->relativeLink($name), $name);
+        return MediaFile::get($name);
     }
 
     /**
@@ -181,12 +157,4 @@ public static function isRemote(string $url): bool
     {
         return str_starts_with($url, 'http') || str_starts_with($url, '//');
     }
-
-    /**
-     * Apply cache to the URL if enabled in the configuration.
-     */
-    protected function withCacheBusting(string $url, string $file): string
-    {
-        return $url.MediaFile::getCacheBustKey($file);
-    }
 }

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

@@ -83,7 +83,7 @@ public function getSource(): string
     {
         if ($this->type === self::TYPE_LOCAL) {
             // Return value is always resolvable from a compiled page in the _site directory.
-            return Hyde::mediaLink($this->source);
+            return (string) Hyde::asset($this->source);
         }
 
         return $this->source;

packages/framework/src/Framework/Features/XmlGenerators/RssFeedGenerator.php

@@ -12,7 +12,7 @@
 use Hyde\Facades\Site;
 use Hyde\Facades\Config;
 use Hyde\Pages\MarkdownPost;
-use Hyde\Support\Filesystem\MediaFile;
+use Hyde\Facades\Filesystem;
 use Hyde\Framework\Features\Blogging\Models\FeaturedImage;
 
 use function date;
@@ -108,7 +108,7 @@ protected function addAtomLinkItem(): void
 
     protected function getImageType(FeaturedImage $image): string
     {
-        return (new MediaFile($image->getSource()))->getMimeType();
+        return Filesystem::findMimeType($image->getSource());
     }
 
     /** @return numeric-string */

packages/framework/src/Markdown/Processing/DynamicMarkdownLinkProcessor.php

@@ -66,7 +66,7 @@ protected static function assetMap(): array
 
     protected static function assetPath(MediaFile $mediaFile): string
     {
-        return Hyde::asset(Str::after($mediaFile->getPath(), '_media/'));
+        return Hyde::asset(Str::after($mediaFile->getPath(), '_media/'))->getLink();
     }
 
     /** @internal Testing helper to reset the asset map cache. */