What's Changed

• [2.x] Improve documentation page detection in MarkdownService by @emmadesilva in #701
• HydePHP v2.0.1 - 2025-10-04 by @emmadesilva in #702

Full Changelog: v2.0.0...v2.0.1

HydePHP v2.0 Release Notes

Overview

HydePHP v2.0 represents a major evolution of the framework, introducing significant improvements to the asset system, navigation API, and overall developer experience. This release modernizes the frontend tooling by replacing Laravel Mix with Vite, completely rewrites the navigation system for better flexibility, and introduces numerous performance optimizations throughout the framework.

This document will give you an overview of the changes. When you're ready to upgrade your site, take a look at the Upgrade Guide.

Major Features

🚀 Modern Frontend Tooling with Vite

We've replaced Laravel Mix with Vite for a faster, more modern development experience:

• Instant Hot Module Replacement (HMR) for real-time updates during development
• Direct asset compilation into the _media folder for cleaner builds
• Updated build command: Use npm run build instead of npm run prod (or --vite during the site build)
• Vite facade for seamless Blade template integration
• Optimized asset serving through the realtime compiler
• Hyde Vite plugin for enhanced integration

🎨 Enhanced Asset Management System

The new consolidated Asset API provides a more intuitive interface for handling media files:

• MediaFile instances with fluent methods like getLink(), getLength(), and getMimeType()
• HydeFront facade for CDN links and Tailwind configuration injection
• Intelligent caching with CRC32 hashing for improved performance
• Automatic validation to prevent missing assets from going unnoticed
• Lazy-loaded metadata for optimal resource usage

🧭 Redesigned Navigation API

The navigation system has been completely rewritten for maximum flexibility:

• YAML configuration support for defining navigation items
• Extra attributes for custom styling and behavior
• Improved Routes facade with Laravel-consistent naming conventions
• Natural priority ordering using numeric prefixes in filenames
• Enhanced sidebar management with better organization options

📝 Improved Documentation Features

Documentation pages now benefit from several enhancements:

• Alpine.js-powered search with customizable implementation
• Blade-based table of contents that's 40x faster than before
• Custom heading renderer with improved permalink handling
• Colored blockquotes now using Tailwind CSS classes
• Smart natural language processing for search headings
• Dynamic source file links in Markdown documents

🎯 Better Developer Experience

Numerous quality-of-life improvements for developers:

• PHP 8.4 support and Laravel 11 compatibility
• ESM module support for modern JavaScript development
• Tailwind CSS v4 with automated upgrade tools
• Enhanced data collections with syntax validation
• Improved error messages with clearer exception handling
• Interactive publish:views command on Unix systems
• Extension callbacks with booting() and booted() methods

Upgrading to v2.0

📖 For complete step-by-step upgrade instructions, see the Upgrade Guide.

Important: PHP 8.2+ is now required. Laravel Mix has been replaced with Vite, and Tailwind CSS has been upgraded to v4.

Breaking Changes

High Impact Changes

1. Tailwind CSS v4 Upgrade

We've upgraded from Tailwind CSS v3 to v4. Run the automated upgrade tool to migrate your custom classes:

npx @tailwindcss/upgrade

Review the Tailwind v4 Upgrade Guide for detailed breaking changes.

2. ESM Module Migration

Frontend tooling now uses ESM modules instead of CommonJS. If you have custom JavaScript, update to ESM syntax:

Before:

const module = require('module-name');
module.exports = { /* ... */ };

After:

import module from 'module-name';
export default { /* ... */ };

3. Navigation Configuration Format

Update your navigation configuration to use the new array-based format:

Before:

'navigation' => [
    'custom_items' => [
        'Custom Item' => '/custom-page',
    ],
],

After:

'navigation' => [
    'custom_items' => [
        ['label' => 'Custom Item', 'destination' => '/custom-page'],
    ],
],

4. Features Configuration

Replace static method calls with enum values in your config/hyde.php:

Before:

'features' => [
    Features::htmlPages(),
    Features::markdownPosts(),
],

After:

'features' => [
    Feature::HtmlPages,
    Feature::MarkdownPosts,
],

General Impact Changes

Post Author System

The blog post author feature has been significantly improved:

Configuration changes:

// Before
'authors' => [
    Author::create('username', 'Display Name', 'https://example.com'),
],

// After
'authors' => [
    'username' => Author::create(
        name: 'Display Name',
        website: 'https://example.com',
        bio: 'Author bio',
        avatar: 'avatar.png',
        socials: ['twitter' => '@username']
    ),
],

Key changes:

• Authors are now keyed by username
• Author::create() returns an array instead of a PostAuthor instance
• Author::get() returns null if not found (previously created new instance)
• Usernames are automatically normalized (lowercase, underscores for spaces)
• Authors support biographies, avatars, and social media links
• A new Hyde::authors() method provides access to all site authors
• Authors can be configured via YAML

The way this system now works is that you first define authors in the config, Hyde then loads this during the booting process, and you can then access them using the get method.

Medium Impact Changes

Asset API Updates

All asset methods now return MediaFile instances instead of strings. This instance can be cast to a string which will automatically resolve to a relative link at that time. You can also call helper methods on it. When using Blade templates, thanks to the Stringable implementation no change will happen.

// Methods renamed for clarity
Hyde::asset('image.png');        // Previously: Hyde::mediaLink()
Asset::get('image.png');         // Previously: Asset::mediaLink()
Asset::exists('image.png');      // Previously: Asset::hasMediaFile()
HydeFront::cdnLink('app.css');   // Previously: Asset::cdnLink()

Configuration changes:

• Rename hyde.enable_cache_busting to hyde.cache_busting
• Remove references to hyde.hydefront_version and hyde.hydefront_cdn_url

Routes Facade API

Methods renamed to follow Laravel conventions:

// Before
$route = Routes::get('route-name');        // Returns null if not found
$route = Routes::getOrFail('route-name');  // Throws exception

// After
$route = Routes::find('route-name');       // Returns null if not found
$route = Routes::get('route-name');        // Throws exception

DataCollection API

• Class renamed from DataCollections to DataCollection
• Syntax validation now throws ParseException for malformed files
• Empty data files are no longer allowed
• Directory creation is no longer automatic
• The route function now throws RouteNotFoundException if route not found

Low Impact Changes

Includes Facade Return Types

Methods now return HtmlString objects:

{{-- Before: Required unescaped output --}}
{!! Includes::html('partial') !!}

{{-- After: Automatic rendering --}}
{{ Includes::html('partial') }}

⚠️ Security Note: Output is no longer escaped by default. Use {{ e(Includes::html('foo')) }} for user-generated content.

Documentation Search Generation

The documentation search page is now generated as an InMemoryPage instead of a post-build task, meaning it appears in the dashboard and route list.

Sidebar Configuration

Documentation sidebar configuration has been reorganized:

• docs.sidebar_order → docs.sidebar.order
• docs.table_of_contents → docs.sidebar.table_of_contents
• docs.sidebar_group_labels → docs.sidebar.labels

New Features

Enhanced Blog Posts

• Simplified image front matter with new "caption" field
• Date prefixes in filenames for automatic publishing dates
• Rich markup data with BlogPosting Schema.org type
• Author collections accessible via Hyde::authors()
• Custom posts support in blog feed component

Improved Build System

• Vite integration with HMR support in realtime compiler
• Smart asset compilation - app.js only compiles when needed
• Environment variable support for saving previews
• Grouped progress bars for InMemoryPage instances
• Media asset transfers via dedicated build task

Developer Tools

• Interactive publish:views command on Unix systems
• Custom HydeSearch.js support for search customization
• Extension callbacks with booting() and booted() methods
• Dynamic source file links in Markdown documents (for example [Home](/_pages/index.blade.php))
• Filesystem::ensureParentDirectoryExists() helper method

Package Updates

Realtime Compiler

• Simplified asset file locator for media source directory
• Added Vite HMR support
• Experimental Laravel Herd support

HydeFront

• Complete migration from Sass to Tailwind CSS
• Extracted CSS component partials
• Removed legacy hyde.css file

Performance Improvements

• 40x faster table of contents generation using Blade components
• CRC32 hashing replaces MD5 for cache busting (much faster)
• Lazy-loaded media metadata with in-memory c...

What's Changed

• Update name and email by @emmadesilva in #698
• HydePHP v2 Release Candidate Four by @emmadesilva in #699

Full Changelog: v2.0.0-RC.3...v2.0.0-RC.4

What's Changed

• HydePHP v2 Release Candidate Three by @caendesilva in #697
• Forward DateString method calls to DateTime instances by @Cyberking99 in hydephp/develop#2235
• [2.x] Fix rebuild command showing the wrong console output by @nats-afs in hydephp/develop#2240

New Contributors

• @Cyberking99 made their first contribution in hydephp/develop#2235

Full Changelog: v2.0.0-RC.2...v2.0.0-RC.3

What's Changed

• HydePHP v2 Release Candidate Two by @caendesilva in #696

Full Changelog: v2.0.0-RC.1...v2.0.0-RC.2

At long last, this is the first release candidate for HydePHP v2.0. Please stay tuned for the official release which will contain the finalized changeset and release notes with upgrade guide. However, for those who are curious - feel free to start testing this right now!

What's Changed

• HydePHP v2 Release Candidate One by @caendesilva in #695

Full Changelog: v1.8.0...v2.0.0-RC.1

Please see the full release notes in the development monorepo https://github.com/hydephp/develop/releases/tag/v1.8.0

What's Changed

• Clean up and refactor code and tests by @caendesilva in #667
• Update the Hyde facade to use a mixin annotation instead of method annotations by @caendesilva in #668
• Refactor and clean up test code and improve testing performance by @caendesilva in #669
• Deprecate Hyde::mediaLink being replaced by Hyde::asset() in v2 by @caendesilva in #670
• Improved printed documentation views by @caendesilva in #671
• Shorten the realtime compiler server start message by @caendesilva in #672
• Improve the Serializable trait to support automatic serialization by @caendesilva in #674
• Update the post author class to prepare for the v2 overhaul by @caendesilva in #675
• Internal: Improve test static analysis and improve tests by @caendesilva in #676
• Internal: Improve testing helpers by @caendesilva in #677
• Refactor the serve command and add more unit tests for it by @caendesilva in #678
• Refactor code to increase code quality and type coverage by @caendesilva in #679
• Hide the Torchlight install command by @caendesilva in #680
• Update 404 page home link fallback to lead to the domain root by @caendesilva in #681
• Register the cache clear command by @caendesilva in #682
• Normalize protocol relative URL handling by @caendesilva in #683
• Cleanup the canonical URL helper method by @caendesilva in #684
• Support setting page descriptions in front matter for all page types by @caendesilva in #685
• Clean up and refactor code by @caendesilva in #686
• Fix URL metadata for blog posts not using customized post output directories by @caendesilva in #687
• Update the HydeKernel array representation to include the Hyde version by @caendesilva in #688
• Internal: Test code refactors and cleanup by @caendesilva in #689
• Automatically transliterate logographic inputs for slug generation by @caendesilva in #691
• Fix serve command not handling project path with spaces by @caendesilva in #693
• HydePHP v1.7.6 by @caendesilva in #694
• HydePHP v1.8.0 - 2025-05-17 by @caendesilva in #690

Full Changelog: v1.7.6...v1.8.0

What's Changed

• Merge pull request #2135 from hydephp/fix-serve-command-not-handling-project-path-with-spaces in abe5943
• Framework version v1.7.6 hydephp/develop@8a7f148 in 94a5879

Full Changelog: v1.7.5...v1.7.6

What's Changed

• Automatically transliterate logographic inputs for slug generation in #691
• Framework version v1.7.5 in 9edb227

Full Changelog: v1.7.4...v1.7.5

What's Changed

• Add webp to the list of default media extensions by @caendesilva in #663
• Internal: Fix framework tests not running in workflow by @caendesilva in #665
• Replace GLOB_BRACE with a more robust solution by @caendesilva in #664
• HydePHP v1.7.4 - 2024-12-21 by @caendesilva in #666

Full Changelog: v1.7.3...v1.7.4