[2.x] Rewrite the Asset API

[caendesilva]

Abstract

Background

The Problem: The current system is confusing and unintuitive with multiple and inconsistent ways to access assets.
The Cause: This is due to multiple code locations have had overlapping code independently implemented, without thinking about the bigger picture.
The Solution: This PR rewrites the web of related code into a unified Asset API, designed to provide a consistent interface to interact with the project's media asset.

Scope

We create the new solution by thinking about how users will actually use these features, which can be summarized into the following scope:

• End users will mainly interact with Media asset files from their pages. Commonly, this will be to do things like resolving links to images located in their media folder. Given our simplicity-first approach, this is our primary focus: to provide a convenient way to get links to assets.
• A secondary role of the API is for the internal HydePHP codebase, package developers, and serious power users, to be used in parts of the static site generation to interact with the site assets.

Podcast

Overwhelmed by this massive changelog? Listen to this AI-generated podcast episode by NotebookLM by Google which was fed the commit logs. Improved version available here

output.mp4

Roadmap

• See if we can cache the media assets during discovery. A good location may be in the kernel Filesystem instance. This would also provide a small performance optimization if we create cache busting keys at discovery time. It would also improve DX with almost no performance penalty as we could throw an exception when trying to get a non-existent file.
• Throw exceptions when trying to get an asset() that does not exist
• Handle side effect in [2.x] Normalize media path helpers to unify naming with HydePages #1911 (comment)
• Remove the mediaLink helper as it can be merged into the main asset() helper
• Rename getContentLength() to getLength()
• More or less implements Support modifying the copied media assets in the build process #1981

Development

• [2.x] Decouple HydeFront features from the Asset facade #1907
• [2.x] Merge the AssetService directly into the Asset facade #1908
• [2.x] Remove HydeFront version and CDN URL configuration options #1909
• [2.x] Simplify public asset service API #1910
• [2.x] Normalize media path helpers to unify naming with HydePages #1911
• [2.x] Remove the preferQualifiedUrl parameter from the asset helper #1913
• [2.x] Experiment with removing the mediaLink method #1914
• [2.x] Normalize asset cache busting #1915
• [2.x] Bring media assets into the Hyde kernel #1917
• [2.x] Major performance and data handling improvements to media assets #1918
• [2.x] Lazy loaded MediaFile metadata properties #1933
• [2.x] Improve the media file instance API #1932
• [2.x] Rename method Asset::hasMediaFile to Asset::exists #1957
• [2.x] Rename config option hyde.enable_cache_busting to hyde.cache_busting #1980

I don't think we'll be doing a v1 tie in here (normally we would backport the new feature and deprecate the old code to provide a migration path, but considering that v1 is in feature freeze #1877 I don't think this complexity would provide value, as there is too little of a time frame between when the next minor release comes out and the v2 release, so it's easier to just migrate to v2 directly)

• We should still deprecate Hyde::mediaLink in favour of Hyde::asset in v1. [1.x] Deprecate Hyde::mediaLink being replaced by Hyde::asset() in v2 #1993

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (0cacea4) to head (40cffc6).
Report is 359 commits behind head on 2.x-dev.

Additional details and impacted files

@@             Coverage Diff             @@
##             2.x-dev     #1904   +/-   ##
===========================================
  Coverage     100.00%   100.00%           
- Complexity      1876      1884    +8     
===========================================
  Files            192       193    +1     
  Lines           5011      5028   +17     
===========================================
+ Hits            5011      5028   +17     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[caendesilva]

Could also have a wrapper like HydeFront::enabled()

[caendesilva]

Let's break down the changes in this Pull Request (PR) and ensure the release notes and upgrade guide accurately reflect them.

Key Changes and Affected Files

• New Asset API: A consolidated API for media files, with changes spanning across multiple files.
  • MediaFile class enhancements (getLink, getLength, etc.).
  • New HydeFront facade for CDN and Tailwind.
  • New Asset::exists method.
  • New Hyde::assets method.
• Navigation API: A complete rewrite of the navigation system.
• Configuration Updates: Renaming and restructuring of config options.
• Media File Handling: Improvements to media file transfer and MediaFile helpers.
• Removals: Deprecated features and methods were removed.
• Fixes and Performance: Various fixes and media file performance improvements.

Release Notes and Upgrade Guide Analysis

• Completeness: The release notes seem to cover all the key changes, additions, and removals in the PR.
• Accuracy: The upgrade guide provides detailed information on breaking changes and steps for upgrading.
• Specific Sections: The sections on navigation changes, features configuration, and DataCollection API changes are particularly thorough.
• Examples: The inclusion of code examples and upgrade paths is helpful for users.

Overall Assessment

Based on the information provided, the release notes and upgrade guide appear to be fully implemented and accurate in relation to the PR's changes. They comprehensively cover the key aspects of the update and provide clear guidance for users to upgrade their sites.