Merge pull request #1904 from hydephp/normalize-the-asset-api

[2.x] Rewrite the Asset API

Author: emmadesilva

RELEASE_NOTES.md

@@ -23,6 +23,12 @@ This serves two purposes:
 - You can now add custom posts to the blog post feed component when including it directly in https://github.com/hydephp/develop/pull/1893
 - Added a `Feature::fromName()` enum helper in https://github.com/hydephp/develop/pull/1895
 - Added support for specifying features in the YAML configuration in https://github.com/hydephp/develop/pull/1896
+- **Added a new consolidated Asset API to better handle media files.**
+  - Added several new fluent methods to the `MediaFile` class, like `getLink()`, `getLength()`, `getMimeType()`, etc.
+  - Added new `HydeFront` facade to handle CDN links and Tailwind config injection.
+  - Added method `Asset::exists()` has to check if a media file exists.
+  - Added a `Hyde::assets()` method to get all media file instancess in the site.
+
 
 ### Changed
 - **Breaking:** The internals of the navigation system has been rewritten into a new Navigation API. This change is breaking for custom navigation implementations. For more information, see below.
@@ -33,6 +39,7 @@ This serves two purposes:
 - **Breaking:** The `Author::get()` method now returns `null` if an author is not found, rather than creating a new instance. For more information, see below.
 - **Breaking:** The custom navigation item configuration now uses array inputs instead of the previous format. For more information, see the upgrade guide below.
 - **Breaking:** Renamed the `hyde.navigation.subdirectories` configuration option to `hyde.navigation.subdirectory_display`.
+- **Breaking:** Renamed the `hyde.enable_cache_busting` configuration option to `hyde.cache_busting` in https://github.com/hydephp/develop/pull/1980
 - Medium: The `route` function will now throw a `RouteNotFoundException` if the route does not exist in https://github.com/hydephp/develop/pull/1741
 - Minor: Navigation menu items are now no longer filtered by duplicates (meaning two items with the same label can now exist in the same menu) in https://github.com/hydephp/develop/pull/1573
 - Minor: Due to changes in the navigation system, it is possible that existing configuration files will need to be adjusted in order for menus to look the same (in terms of ordering etc.)
@@ -60,6 +67,21 @@ This serves two purposes:
 - The build command now groups together all `InMemoryPage` instances under one progress bar group in https://github.com/hydephp/develop/pull/1897
 - The `Markdown::render()` method will now always render Markdown using the custom HydePHP Markdown service (thus getting smart features like our Markdown processors) in https://github.com/hydephp/develop/pull/1900
 - Improved how the `MarkdownService` class is accessed, by binding it into the service container, in https://github.com/hydephp/develop/pull/1922
+- Improved the media asset transfer build task to have better output in https://github.com/hydephp/develop/pull/1904
+- **Many MediaFile related helpers has been changed or completely rewritten** to provide a simplified API for interacting with media files.
+  - **Note:** For most end users, the changes will have minimal direct impact, but if you have custom code that interacts with media files, you may need to update it.
+  - The `Asset` facade has been e restructured to be more scoped and easier to use, splitting out a separate `HydeFront` facade and inlining the `AssetService` class.
+  - All asset retrieval methods now return a `MediaFile` instance, which can be fluently interacted with, or cast to a string to get the link (which was the previous behavior).
+  - The `Hyde::asset()` method and `asset()` function now return `MediaFile` instances instead of strings, and will throw an exception if the asset does not exist.
+  - Renamed method `Asset::hasMediaFile` to `Asset::exists` in https://github.com/hydephp/develop/pull/1957
+  - Renamed method `MediaFile::getContentLength` to `MediaFile::getLength` in https://github.com/hydephp/develop/pull/1904
+  - Replaced method `Hyde::mediaPath` with `MediaFile::sourcePath` in https://github.com/hydephp/develop/pull/1911
+  - Replaced method `Hyde::siteMediaPath` with `MediaFile::outputPath` in https://github.com/hydephp/develop/pull/1911
+  - We will now throw an exception if you try to get a media file that does not exist in order to prevent missing assets from going unnoticed in https://github.com/hydephp/develop/pull/1932
+- **MediaFile performance improvements:**
+  - Media assets are now cached in the HydeKernel, giving a massive performance boost and making it easier to access the instances in https://github.com/hydephp/develop/pull/1917
+  - Media file metadata is now lazy loaded and then cached in memory, providing performance improvements for files that may not be used in a build in https://github.com/hydephp/develop/pull/1933
+  - We now use the much faster `CRC32` hashing algoritm instead of `MD5` for cache busting keys in https://github.com/hydephp/develop/pull/1918
 
 ### Deprecated
 - for soon-to-be removed features.
@@ -72,6 +94,13 @@ This serves two purposes:
 - Removed: The deprecated `PostAuthor::getName()` method is now removed (use `$author->name`) in https://github.com/hydephp/develop/pull/1782
 - Internal: Removed the internal `DocumentationSearchPage::generate()` method as it was unused in https://github.com/hydephp/develop/pull/1569
 - Removed the deprecated `FeaturedImage::isRemote()` method in https://github.com/hydephp/develop/pull/1883. Use `Hyperlinks::isRemote()` instead.
+- **With the new Asset API, a few features had to be moved/removed:**
+  - `AssetService` class has been removed (was merged into the `Asset` facade) in https://github.com/hydephp/develop/pull/1908
+  - Removed HydeFront methods from the `Asset` facade (moved to the new HydeFront facade) in https://github.com/hydephp/develop/pull/1907
+  - The config options `hyde.hydefront_version` and `hyde.hydefront_cdn_url` have been removed in https://github.com/hydephp/develop/pull/1909 (as changing these could lead to incompatible asset versions, defeating the feature's purpose)
+  - Removed `Hyde::mediaLink()` method replaced by `Hyde::asset()` in https://github.com/hydephp/develop/pull/1932
+  - Removed `Hyde::mediaPath()` method replaced by `MediaFile::sourcePath()` in https://github.com/hydephp/develop/pull/1911
+  - Removed `Hyde::siteMediaPath()` method replaced by `MediaFile::outputPath()` in https://github.com/hydephp/develop/pull/1911
 
 ### Fixed
 - Added missing collection key types in Hyde facade method annotations in https://github.com/hydephp/develop/pull/1784
@@ -240,6 +269,53 @@ The following methods in the `Features` class have been renamed to follow a more
 
 Note that this class was previously marked as internal in v1, but the change is logged here in case it was used in configuration files or custom code.
 
+### Asset API Changes
+
+#### Overview
+For most end users, the changes to the Asset API in HydePHP 2.x will have minimal direct impact. However, if you have custom code that interacts with media files, you may need to update it.
+
+The most important thing to note is that all asset retrieval methods now return a `MediaFile` instance, which can be fluently interacted with, or cast to a string to get the link (which was the previous behavior).
+
+#### Side effects to consider
+
+Regardless of if you need to make changes to your code, there are a few side effects to consider:
+
+- All cache busting keys will have changed since we changed the hashing algorithm from `MD5` to `CRC32`.
+- Media file getters now return MediaFile instances instead of strings. But these can still be used the same way in Blade `{{ }}` tags, as they can be cast to strings.
+- Due to the internal normalizations, we will consistently use cache busting keys and use qualified paths when site URLs are set.
+- An exception will be thrown if you try to get a media file that does not exist in order to prevent missing assets from going unnoticed.
+
+These side effects should not have any negative impact on your site, but may cause the generated HTML to look slightly different.
+
+#### Impact on Your Code
+
+If you are using strict type declarations, you may need to update your code to expect a `MediaFile` instance instead of a string path; or you should cast the `MediaFile` instance to a string when needed.
+
+Most changes were made in https://github.com/hydephp/develop/pull/1904 which contains extra information and the reasoning behind the changes.
+
+#### Updating Your Code
+
+Once you have determined that you need to update your code, here are the steps you should take:
+
+1. Update calls to renamed methods:
+   ```php
+   // Replace this:                      With this:
+   Hyde::mediaLink('image.png')      =>  Hyde::asset('image.png');
+   Asset::mediaLink('image.png')     =>  Asset::get('image.png');
+   Asset::hasMediaFile('image.png')  =>  Asset::exists('image.png');
+   Asset::cdnLink('app.css')         =>  HydeFront::cdnLink('app.css');
+   Asset::injectTailwindConfig()     =>  HydeFront::injectTailwindConfig();
+   FeaturedImage::isRemote($source)  =>  Hyperlinks::isRemote($source);
+   ```
+
+2. Rename the option `hyde.enable_cache_busting` to `hyde.cache_busting` in your configuration file.
+
+3. Remove any references to `hyde.hydefront_version` and `hyde.hydefront_cdn_url` in your config files as these options have been removed.
+
+4. If you were using `AssetService` directly, refactor your code to use the new `Asset` facade, `MediaFile` class, or `HydeFront` facade as appropriate.
+
+These changes simplify the Asset API and provide more robust handling of media files. The new `MediaFile` class offers additional functionality for working with assets.
+
 ## Low impact
 
 ### Navigation internal changes

_ide_helper.php

@@ -33,7 +33,6 @@
 class Hyde extends \Hyde\Hyde {}
 class Site extends \Hyde\Facades\Site {}
 class Meta extends \Hyde\Facades\Meta {}
-/** @mixin \Hyde\Framework\Services\AssetService */
 class Asset extends \Hyde\Facades\Asset {}
 class Author extends \Hyde\Facades\Author {}
 class Features extends \Hyde\Facades\Features {}

app/config.php

@@ -94,6 +94,7 @@
         'Meta' => \Hyde\Facades\Meta::class,
         'Asset' => \Hyde\Facades\Asset::class,
         'Author' => \Hyde\Facades\Author::class,
+        'HydeFront' => \Hyde\Facades\HydeFront::class,
         'Features' => \Hyde\Facades\Features::class,
         'Config' => \Hyde\Facades\Config::class,
         'Filesystem' => \Hyde\Facades\Filesystem::class,
@@ -104,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,

config/hyde.php

@@ -355,18 +355,16 @@
     | Cache Busting
     |--------------------------------------------------------------------------
     |
-    | Any assets loaded using the Asset::mediaLink() helper will automatically
-    | have a cache busting query string appended to the URL. This is useful
+    | Any assets loaded using the Hyde Asset helpers will automatically have
+    | a "cache busting" query string appended to the URL. This is useful
     | when you want to force browsers to load a new version of an asset.
+    | All included Blade templates use this feature to load assets.
     |
-    | The mediaLink helper is used in the built-in views to load the
-    | default stylesheets and scripts, and thus use this feature.
-    |
-    | To disable cache busting, set this setting to false.
+    | To disable the cache busting, set this setting to false.
     |
     */
 
-    'enable_cache_busting' => true,
+    'cache_busting' => true,
 
     /*
     |--------------------------------------------------------------------------
@@ -470,11 +468,6 @@
     // Where should the build manifest be saved? (Relative to project root, for example _site/build-manifest.json)
     'build_manifest_path' => 'app/storage/framework/cache/build-manifest.json',
 
-    // Here you can specify HydeFront version and URL for when loading app.css from the CDN.
-    // Only change these if you know what you're doing as some versions may be incompatible with your Hyde version.
-    'hydefront_version' => \Hyde\Framework\Services\AssetService::HYDEFRONT_VERSION,
-    'hydefront_cdn_url' => \Hyde\Framework\Services\AssetService::HYDEFRONT_CDN_URL,
-
     // Should the theme toggle buttons be displayed in the layouts?
     'theme_toggle_buttons' => true,
 

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-08-01 10:01:06 in 0.13ms -->
 
 #### `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,28 +35,28 @@ No description provided.
 Hyde::sitePath(string $path): string
 ```
 
-#### `siteMediaPath()`
+#### `pathToAbsolute()`
 
 No description provided.
 
 ```php
-Hyde::siteMediaPath(string $path): string
+Hyde::pathToAbsolute(array|string $path): array|string
 ```
 
-#### `pathToAbsolute()`
+#### `pathToRelative()`
 
 No description provided.
 
 ```php
-Hyde::pathToAbsolute(array|string $path): array|string
+Hyde::pathToRelative(string $path): string
 ```
 
-#### `pathToRelative()`
+#### `assets()`
 
 No description provided.
 
 ```php
-Hyde::pathToRelative(string $path): string
+Hyde::assets(): \Illuminate\Support\Collection<string, \Hyde\Support\Filesystem\MediaFile>
 ```
 
 <!-- End generated docs for Hyde\Foundation\Concerns\ForwardsFilesystem -->

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-02-25 19:02:29 in 0.09ms -->
+<!-- Generated by HydePHP DocGen script at 2024-09-08 10:25:34 in 0.11ms -->
 
 #### `formatLink()`
 
@@ -19,22 +19,16 @@ 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, bool $preferQualifiedUrl): string
+Hyde::asset(string $name): Hyde\Support\Filesystem\MediaFile
 ```
 
+- **Throws:** \Hyde\Framework\Exceptions\FileNotFoundException If the file does not exist in the `_media` source directory.
+
 #### `url()`
 
 No description provided.

docs/architecture-concepts/the-hydekernel.md

@@ -189,7 +189,7 @@ Hyde::markdown(string $text, bool $normalizeIndentation): Illuminate\Support\Htm
 <section id="hyde-kernel-hyperlink-methods">
 
 <!-- Start generated docs for Hyde\Foundation\Concerns\ForwardsHyperlinks -->
-<!-- Generated by HydePHP DocGen script at 2024-02-25 19:02:29 in 0.09ms -->
+<!-- Generated by HydePHP DocGen script at 2024-09-08 10:25:34 in 0.11ms -->
 
 #### `formatLink()`
 
@@ -207,22 +207,16 @@ 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, bool $preferQualifiedUrl): string
+Hyde::asset(string $name): Hyde\Support\Filesystem\MediaFile
 ```
 
+- **Throws:** \Hyde\Framework\Exceptions\FileNotFoundException If the file does not exist in the `_media` source directory.
+
 #### `url()`
 
 No description provided.
@@ -254,7 +248,7 @@ Hyde::hasSiteUrl(): bool
 <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-08-01 10:01:06 in 0.13ms -->
 
 #### `filesystem()`
 
@@ -280,14 +274,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.
@@ -296,28 +282,28 @@ No description provided.
 Hyde::sitePath(string $path): string
 ```
 
-#### `siteMediaPath()`
+#### `pathToAbsolute()`
 
 No description provided.
 
 ```php
-Hyde::siteMediaPath(string $path): string
+Hyde::pathToAbsolute(array|string $path): array|string
 ```
 
-#### `pathToAbsolute()`
+#### `pathToRelative()`
 
 No description provided.
 
 ```php
-Hyde::pathToAbsolute(array|string $path): array|string
+Hyde::pathToRelative(string $path): string
 ```
 
-#### `pathToRelative()`
+#### `assets()`
 
 No description provided.
 
 ```php
-Hyde::pathToRelative(string $path): string
+Hyde::assets(): \Illuminate\Support\Collection<string, \Hyde\Support\Filesystem\MediaFile>
 ```
 
 <!-- End generated docs for Hyde\Foundation\Concerns\ForwardsFilesystem -->

docs/digging-deeper/customization.md

@@ -342,20 +342,6 @@ Specifies the path where the build manifest should be saved, relative to the pro
 'build_manifest_path' => 'app/storage/framework/cache/build-manifest.json',
 ```
 
-### `hydefront_version` and `hydefront_cdn_url`
-
-These options allow you to specify the HydeFront version and CDN URL when loading `app.css` from the CDN.
-
-Only change these if you know what you're doing as some versions may be incompatible with your Hyde version.
-
-```php
-// filepath config/hyde.php
-use \Hyde\Framework\Services\AssetService;
-
-'hydefront_version' => AssetService::HYDEFRONT_VERSION,
-'hydefront_cdn_url' => AssetService::HYDEFRONT_CDN_URL,
-```
-
 ### `theme_toggle_buttons`
 
 >info This feature was added in HydePHP v1.7.0