Finalise HydePHP v2 release notes #2296
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
There was a problem hiding this comment.
Pull Request Overview
This PR finalizes the release notes for HydePHP v2.0 by transforming the detailed changelog into a comprehensive, user-friendly release document. The update restructures the content from a traditional changelog format to a modern release notes format that emphasizes key features, migration guidance, and user benefits.
Key changes:
- Complete rewrite from changelog format to structured release notes with clear sections
- Reorganized content to highlight major features like Vite integration, asset management, and navigation API improvements
- Enhanced upgrade guide with step-by-step migration instructions and code examples
- Added comprehensive migration checklist and support resources
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
emmadesilva
force-pushed
the
feat/release-notes
branch
from
baf78b3 to
1640f17
Compare
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #2296 +/- ##
===========================================
Coverage 100.00% 100.00%
Complexity 2000 2000
===========================================
Files 197 197
Lines 5178 5178
===========================================
Hits 5178 5178 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Updated release notes to reflect new features, improvements, and breaking changes.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Old Release Notes
[v2-dev] - YYYY-MM-DD
About
Keep an Unreleased section at the top to track upcoming changes.
This serves two purposes:
Added
MediaFileclass, likegetLink(),getLength(),getMimeType(), etcHydeFrontfacade to handle CDN links and Tailwind config injectionAsset::exists()to check if a media file existsHyde::assets()method to get all media file instances in the siteRoutes::get()toRoutes::find()to better indicate it may return nullRoutes::getOrFail()toRoutes::get()to make the exception-throwing behavior the default and match Laravel conventionsAssetfacade has been restructured to be more scoped and easier to use, splitting out a separateHydeFrontfacade and inlining theAssetServiceclassMediaFileinstance, which can be fluently interacted with, or cast to a string to get the link (which was the previous behavior)Hyde::asset()method andasset()function now returnMediaFileinstances instead of strings, and will throw an exception if the asset does not existAsset::hasMediaFiletoAsset::existsin #1957MediaFile::getContentLengthtoMediaFile::getLengthin #1904Hyde::mediaPathwithMediaFile::sourcePathin #1911Hyde::siteMediaPathwithMediaFile::outputPathin #1911CRC32hashing algorithm instead ofMD5for cache busting keys in #1918hyde::components.docs.search-widgettohyde::components.docs.search-modalin #2029resources/js/HydeSearch.jsfile in #2031npm run buildto compile your assets, instead ofnpm run prod_mediafolder, and will not be copied to the_site/mediafolder by the NPM command in #2011Feature::fromName()enum helper in #1895\Hyde\Framework\Actions\PreBuildTasks\TransferMediaAssetsbuild task to handle media assets transfers for site builds in #1536\Hyde\Framework\Exceptions\InvalidConfigurationExceptionexception class to handle invalid configuration exceptions in #1799\Hyde\Framework\Exceptions\ParseExceptionexception class to handle parsing exceptions in data collection files in #1732npm run buildcommand for compiling frontend assets with Vite in #2010booting()andbooted()callbacks inHydeExtensionclasses, allowing extension developers to hook into the kernel boot process more easily in #1847idattributes for heading permalinks have been moved from the anchor to the heading element in #2052\Hyde\Facades\Featuresclass is no longer marked as internal, and is now thus part of the public API in #1647publish:viewscommand is now interactive on Unix-like systems in #2062DateTimeinstance inDateStringinstances in #2235Filesystem::ensureParentDirectoryExists()method to reduce repetitive code when ensuring parent directories exist in #2293Changed
DataCollectionstoDataCollectionin #1732 For more information, see below.hyde.enable_cache_bustingconfiguration option tohyde.cache_bustingin #1980hyde.navigation.subdirectoriesconfiguration option tohyde.navigation.subdirectory_displayin #1818--run-devand--run-prodbuild command flags with a single--viteflag that uses Vite to build assets in #2013--run-prettierbuild command flag and Prettier dependency in #2312docs.sidebar_group_labelstodocs.sidebar.labelsin #2315Author::create()method now returns an array instead of aPostAuthorinstance in #1798 For more information, see below.Author::get()method now returnsnullif an author is not found, rather than creating a new instance in #1798 For more information, see below.hyde.authorsconfig setting should now be keyed by the usernames in #1782 For more information, see below.hyde.featuresconfiguration format has changed to use Enums instead of static method calls in #1649 For more information, see below.npx @tailwindcss/upgradein your project if you have custom Tailwind classes in your project. See the information below for details.routefunction will now throw aRouteNotFoundExceptionif the route does not exist in #1741Includesfacade now returnHtmlStringobjects instead ofstringin #1738 For more information, see below.processing_time_msattribute in thesitemap.xmlfile has now been removed in #1744Hyde::url()helper throw aBadMethodCallExceptioninsteadBaseUrlNotSetExceptionwhen no site URL is set and no path was provided to the method in #1890BlogPostingSchema.org type instead ofArticlein #1887Includes::path()andIncludes::get()methods now normalize paths to be basenames to match the behavior of the other include methods in #1738 This means that nested directories are no longer supported, as you should use a data collection for theseDataCollectionmethods will no longer create the data collections directory in #1732Include::path()method will no longer create the includes directory in #1707InMemoryPageinstead of a post-build task in #1498MarkdownServiceclass is accessed by binding it into the service container in #1922BuildService::transferMediaAssets()method in #2024hyde::pages.documentation-searchtohyde::pages.docs.searchin #2033categorytogroupin thepublish:viewscommand in #2166Markdown::render()method will now always render Markdown using the custom HydePHP Markdown service (thus getting smart features like our Markdown processors) in #1900hasFeaturemethod on the Hyde facade and HydeKernel now only accepts a Feature enum value instead of a string for its parameter in #1650InMemoryPageinstances under one progress bar group in #1897_media), and no longer checks the site output directory (_site/media) in #2012Fixed
app.cssfile will no longer be copied to the media output directory when app styles are configured to be loaded from a CDN in #2180app.jsfile will now only be compiled if it has scripts in #2028Removed
app.cssfile will no longer be copied to the media output directory when app styles are configured to be loaded from a CDN in #2180app.jsfile will now only be compiled if it has scripts in #2028Package updates
Realtime Compiler
HydeFront
hyde.cssfile in [2.x] Remove thehyde.cssfile from HydeFront #2037 as all its styles were refactored to Tailwind in [2.x] Refactor HydeFront styles to TailwindCSS #2024Upgrade Guide
Please see the "Breaking changes & upgrade guide" section below for more information.
Breaking changes & upgrade guide
Please read through this section to ensure your site upgrades smoothly.
Before you start
Before you start, please upgrade your application to at least HydePHP v1.6 as that version contains helpers to make the upgrade process easier.
TailwindCSS v4
We upgraded the TailwindCSS version from v3 to v4. If you have written custom markup with Tailwind classes you should read the Tailwind v4 Upgrade Guide so you know which breaking changes were introduced. Thankfully, the team behind Tailwind provide an automated Upgrade Tool. Run it with the following command:
High impact
Switch frontend tooling to full ESM support
The frontend tooling has been switched from CommonJS to ESM. This means that all JavaScript files are now ESM modules, and you will need to update your custom scripts to use ESM syntax.
If you only used the default HydePHP frontend (without custom JavaScript), no action is needed. Otherwise, please read the upgrade guide here: #2159
Navigation system rewrite
The navigation system has been rewritten into a new Navigation API. This change is breaking for custom navigation implementations, see more down below.
For most users, the only impact will be that configuration files need to be updated to use the new configuration format. Due to the internal changes,
it's also possible that menu items will be in a slightly different order than before, depending on your setup. Please verify that your site's menus
look as expected after upgrading, and adjust the configuration files if necessary, before deploying to production.
Navigation and sidebar configuration changes
The navigation and sidebar configuration files have been updated to use the new Navigation API.
This means that you will need to update your configuration files to use the new format.
The easiest way to upgrade is to publish updated configuration files (
hyde.phpanddocs.php) and copy over your customizations.The following configuration entries have been updated:
Changed configuration option
docs.sidebar_ordertodocs.sidebar.orderin [2.x] Breaking: Change configuration optiondocs.sidebar_ordertodocs.sidebar.order#1583Upgrade path: Move the
sidebar_orderoption's array in theconfig/docs.phpfile into thesidebararray in the same file.Changed configuration option
docs.table_of_contentstodocs.sidebar.table_of_contentsin [2.x] Breaking: Change configuration optiondocs.table_of_contentstodocs.sidebar.table_of_contents#1584Upgrade path: Move the
table_of_contentsoption's array in theconfig/docs.phpfile into thesidebararray in the same file.Changed configuration option
docs.sidebar_group_labelstodocs.sidebar.labelsin [2.x] Rename docs.sidebar_group_labels to docs.sidebar.labels #2315Upgrade path: Move the
sidebar_group_labelsoption into the nestedsidebar.labelsstructure inconfig/docs.phpBefore:
After:
Features configuration changes
The
hyde.featuresconfiguration format has changed to use Enums instead of static method calls. This change is breaking as it will require you to update yourconfig/hyde.phpfile.Instead of
Use instead
Of course, if you have disabled any of the features, do not include them in the new array.
General impact
Post Author changes
This release makes major improvements to the usability and design of the blog post author feature.
Here is the full list of changes:
hyde.authorsconfig setting must now be keyed by the usernames, instead of providing the username in the author facade constructor.Author::create()method now returns an array instead of aPostAuthorinstance. This only affects custom code that uses theAuthorfacade.Author::get()method now returnsnullif an author is not found, rather than creating a new instance. This only affects custom code that uses theAuthorfacade.PostAuthor::getName()method has been removed (use$author->nameinstead).$author->getPosts()method to get all of an author's posts.Hyde::authors().PostAuthorclass is now Arrayable and JsonSerializable.Upgrade guide:
Update your
config/hyde.phpfile to use the new author configuration format:Review and update any code that uses the
Authorfacade:create()method now returns an array instead of aPostAuthorinstance.get()method may returnnull, so handle this case in your code.Check your blog post front matter and ensure that
authorfields match the new username keys in your configuration.If you have custom templates that use author data, update them to:
bio,avatar, andsocials.Author::get()to create new authors on the fly, update your code to handlenullreturns or create authors explicitly.For more information, see #1782 and #1798
Documentation search page changes
The documentation search page and search index have been changed to be generated as
InMemoryPagesinstead of a post-build task.The main impact noticeable to most users by this is the implicit changes, like the pages showing up in the dashboard and route list command.
In case you have customized the
GenerateSearchpost-build task you may, depending on what you were trying to do,want to adapt your code to interact with the new
InMemoryPage, which is generated in theHydeCoreExtensionclass.For more information, see #1498.
Medium impact
Features class method renames
The following methods in the
Featuresclass have been renamed to follow a more consistent naming convention:Features::enabled()has been renamed toFeatures::has()Features::sitemap()has been renamed toFeatures::hasSitemap()Features::rss()has been renamed toFeatures::hasRss()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
MediaFileinstance, 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:
MD5toCRC32.{{ }}tags, as they can be cast to strings.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
MediaFileinstance instead of a string path; or you should cast theMediaFileinstance to a string when needed.Most changes were made in #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:
Update calls to renamed methods:
Rename the option
hyde.enable_cache_bustingtohyde.cache_bustingin your configuration file.Remove any references to
hyde.hydefront_versionandhyde.hydefront_cdn_urlin your config files as these options have been removed.If you were using
AssetServicedirectly, refactor your code to use the newAssetfacade,MediaFileclass, orHydeFrontfacade as appropriate.These changes simplify the Asset API and provide more robust handling of media files. The new
MediaFileclass offers additional functionality for working with assets.Low impact
Navigation internal changes
The navigation system has been rewritten into a new Navigation API. This change is breaking for custom navigation implementations.
If you have previously in your custom code done any of the following, or similar, you will need to adapt your code to use the new Navigation API:
Upgrade guide
Due to the scope of the rewrite, the easiest and fastest way to upgrade your code is to recreate it using the new Navigation API.
HTML ID changes
Some HTML IDs have been renamed to follow a more consistent naming convention.
If you have used any of the following selectors in custom code you wrote yourself, you will need to update to use the new changed IDs.
#1622
#searchMenuto#search-menu#searchMenuButtonto#search-menu-button#searchMenuButtonMobileto#search-menu-button-mobileEdge case changes to slug generation
Slug generation now normalizes two symbols before slugging (@ → at, & → and). This may change permalinks for titles containing these symbols. (#2314)
New documentation search implementation
As the new documentation search implementation brings changes to their code API you may need to adapt your code
according to the information below in case you wrote custom code that interacted with these parts of the codebase.
The
GenerateSearchpost-build task has been removed. If you have previously extended or customized this class,you will need to adapt your code, as the search index files are now handled implicitly during the standard build process,
as the search pages are now added to the kernel page and route collection. ([2.x] Rewrite documentation search page internals to be based on dynamic pages instead of a build task #1498)
If your site has a custom documentation search page, for example
_docs/search.mdor_pages/docs/search.blade.php,that page will no longer be built when using the specific
build:searchcommand. It will, of course,be built using the standard
buildcommand. 82dc71fIn the highly unlikely event your site customizes any of the search pages by replacing them in the kernel route collection,
you would now need to do that in the kernel page collection due to the search pages being generated earlier in the lifecycle.
82dc71f
Media asset transfer implementation changes
The internals of how media asset files are copied during the build process have been changed. For most users, this change
has no impact. However, if you have previously extended this method, or called it directly from your custom code,
you will need to adapt your code to use the new
TransferMediaAssetsbuild task.For example, if you triggered the media transfer with a build service method call, use the new build task instead:
Includes facade changes
The following methods in the
Includesfacade now returnHtmlStringobjects instead ofstring:Includes::html()Includes::blade()Includes::markdown()This means that you no longer need to use
{!! !!}to render the output of these methods in Blade templates, instead just use{{ }}.If you have used the return value of these methods in custom code, you may need to adjust your code to work with the new return type.
For more information, see the RFC that proposed this change: #1734
The RFC was implemented in #1738
Remember to escape output if necessary
Note: Remember that this means that includes are no longer escaped by default, so make sure to escape the output if necessary, for example if the content is user-generated.
{{ e(Includes::html('foo')) }}instead of{{ Includes::html('foo') }}to escape the output, matching the previous behavior.)DataCollection API changes
The DataCollection feature has been reworked to improve the developer experience and make it more consistent with the rest of the API.
Unfortunately, this means that existing setups may need to be adjusted to work with the new API.
Upgrade guide
DataCollectionsclass has been renamed toDataCollection. If you have used theDataCollectionsclass in your code, you will need to update your code to use the new class name.Changes
DataCollectionmethods will no longer create the data collections directory automatically.DataCollectionclass now validates the syntax of all data collection files during discovery, and throws aParseExceptionif the syntax is invalid.Issues that may arise
If you start getting a
ParseExceptionwhen using theDataCollectionclass, it may be due to malformed data collection files.Starting from this version, we validate the syntax of JSON and YAML in data files during discovery, including any front matter in Markdown data files.
We do this to help you catch errors early. See #1736 for more information.
For example, an empty or malformed JSON file will now throw an exception like this:
In order to normalize the thrown exceptions, we now rethrow the
ParseExceptionfromSymfony/Yamlas our customParseExceptionto match the JSON and Markdown validation.Additionally, an exception will be thrown if a data file is empty, as this is unlikely to be intentional. Markdown files can have an empty body if front matter is present.
Removal of
FeaturedImage::isRemote()methodThe
FeaturedImage::isRemote()method has been removed in v2.0. This method was deprecated in v1.8.0 and has now been completely removed.Upgrade guide
If you were using
FeaturedImage::isRemote()in your code, you should replace it withHyperlinks::isRemote(). Here's how to update your code:This change was implemented in #1883. Make sure to update any instances of
FeaturedImage::isRemote()in your codebase to ensure compatibility with HydePHP v2.0.Routes facade API changes
The Routes facade API has been improved to better follow Laravel naming conventions and make the API more intuitive. This change affects code that directly uses the Routes facade methods.
Changes
Routes::get()method has been renamed toRoutes::find()to better indicate that it may return null if a route is not foundRoutes::getOrFail()method has been renamed toRoutes::get()to make the exception-throwing behavior the default, matching Laravel conventionsUpgrade guide
If you have used the Routes facade in your custom code, update it as follows:
This change provides more intuitive method names and better type safety, with
find()returning?Routeandget()returningRoute.This change was implemented in #2179.
New Asset System
Abstract
The new asset system is a complete rewrite of the HydeFront asset handling system, replacing Laravel Mix with Vite, and favouring Blade-based components with Tailwind classes over CSS partials and custom stylesheets.
Enhancements
Replaced Laravel Mix with Vite for frontend asset compilation. ([[2.x] Replace Laravel Mix with Vite #2010], [[2.x] No longer copy files to site output from the asset bundler command #2011], [[2.x] Update the realtime compiler to only serve source media files #2012], [[2.x] Replace
--run-devand--run-prodbuild command flags with--run-viteflag #2013], [[2.x] Add Vite Realtime Compiler integration for HMR #2016], [[2.x] Massive Windows performance improvement of the Vite integration #2021])_mediafolder._media).npm run buildcommand for compiling frontend assets with Vite.--viteflag is passed.Improved HydeFront integration. ([[2.x] Refactor HydeFront styles to TailwindCSS #2024], [[2.x] Recreate the HydeSearch plugin with Alpine.js #2029], [[2.x] Extract vendor file for the HydeSearch script #2031], [[2.x] Normalize codeblock styles and remove Torchlight enabled class #2036], [[2.x] Remove the
hyde.cssfile from HydeFront #2037], [[2.x] Extract HydeFront partials for Tailwind component templates #2038], [[2.x] Bundle styles to support more torchlight features #2039])app.css.hyde.cssfrom HydeFront, as all styles are now included inapp.css.Implemented a custom Blade-based heading renderer for Markdown. ([[2.x] Custom Markdown heading renderer #2047], [[2.x] Semantic Tailwind Markdown heading permalinks #2052])
idattributes for heading permalinks have been moved from the anchor to the heading element.Colored Markdown blockquotes are now rendered using Blade and Tailwind CSS. ([[2.x] Blade-based colored Markdown blockquotes #2056])
The
app.jsfile will now only be compiled if it has scripts. ([[2.x] Only compile app scripts if it has contents #2028])Breaking Changes
npm run buildto compile your assets, instead ofnpm run prod.--run-devand--run-prodbuild command flags, replaced by--vite. ([[2.x] Replace--run-devand--run-prodbuild command flags with--run-viteflag #2013])--run-prettierbuild command flag.DocumentationPage::getTableOfContents()method. Table of contents are now generated using a Blade component. ([[2.x] Blade-based table of contents generator #2045])hyde.cssfrom HydeFront, requiring recompilation of assets if you were extending it. ([[2.x] Remove thehyde.cssfile from HydeFront #2037])hyde.cssandapp.css, all styles are now inapp.css. ([[2.x] Refactor HydeFront styles to TailwindCSS #2024])Removals
npm run prodcommand. ([[2.x] Replace Laravel Mix with Vite #2010])<x-hyde::docs.search-input />and<x-hyde::docs.search-scripts />Blade components, replaced by<x-hyde::docs.hyde-search />. ([[2.x] Recreate the HydeSearch plugin with Alpine.js #2029]).torchlight-enabledCSS class. ([[2.x] Normalize codeblock styles and remove Torchlight enabled class #2036])MarkdownService::withPermalinksandMarkdownService::canEnablePermalinksmethods. ([[2.x] Custom Markdown heading renderer #2047])Blade-based table of contents generator
The way we generate table of contents for documentation pages have been changed from a helper method to a Blade component.
This new system is much easier to customize and style, and is up to 40 times faster than the old system.
See #2045 for more information.
Scope
The likelihood of impact is low, but if any of the following are true, you may need to update your code:
Hyde\Framework\Actions\GeneratesTableOfContentsclass in custom code, you will likely need to update that code for the rewritten class.resources/views/components/docs/sidebar-item.blade.phpcomponent, you will need to update it to call the new component instead of the old generator rendering.getTableOfContentsmethod of theDocumentationPageclass in custom code, you will need to update that usage as to possibly call the new Blade component directly, depending on your use case.hasTableOfContentsmethod of theDocumentationPageclass in custom code you will need to replace the method call withConfig::getBool('docs.sidebar.table_of_contents.enabled', true)Changes
resources/views/components/docs/table-of-contents.blade.phpcomponent containing the structure and styles for the table of contentsGeneratesTableOfContentsclass to use a custom implementation instead of using CommonMarkexecutemethod of theGeneratesTableOfContentsclass now returns an array of data, instead of a string of HTML. This data should be fed into the new componenttable-of-contents.cssfile as styles are now made using Tailwindheading-permalinks.cssfile as styles are now made using Tailwindblockquotes.cssfile as styles are now made using TailwindNew features
Navigation configuration changes
The custom navigation item configuration format has been updated to use array inputs. This change allows for more flexibility and consistency in defining navigation items.
Old format:
New format:
Additionally, the
hyde.navigation.subdirectoriesconfiguration option has been renamed tohyde.navigation.subdirectory_display. Update your configuration files accordingly.YAML configuration for navigation items
You can now set custom navigation items directly in your YAML configuration files. This provides an alternative to defining them in the PHP configuration files.
Example:
Extra attributes for navigation items
Navigation items now support extra attributes, allowing you to add custom data or styling to your navigation elements. You can set these attributes in both PHP and YAML configurations.
Example in PHP:
Example in YAML:
These changes provide more flexibility and control over your site's navigation structure. Make sure to update your configuration files and any custom code that interacts with navigation items to align with these new formats and features.