Skip to content

Commit 1962479

Browse files
emmadesilvaemmadesilva
committed
HydePHP v2.0
1 parent 2012ded commit 1962479

2 files changed

Lines changed: 355 additions & 4 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 354 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,17 +5,368 @@ All notable changes to this project will be documented in this file.
55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
66
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
77

8+
## [Unreleased] - YYYY-MM-DD
89

9-
## Upcoming changes
10+
### About
11+
12+
Keep an Unreleased section at the top to track upcoming changes.
1013

11-
Please see the [RELEASE_NOTES.md](RELEASE_NOTES.md) for the changelog for the upcoming release.
14+
This serves two purposes:
1215

16+
1. People can see what changes they might expect in upcoming releases
17+
2. At release time, you can move the Unreleased section changes into a new release version section.
18+
19+
### Added
20+
- for new features.
21+
22+
### Changed
23+
- for changes in existing functionality.
24+
25+
### Deprecated
26+
- for soon-to-be removed features.
27+
28+
### Removed
29+
- for now removed features.
30+
31+
### Fixed
32+
- for any bug fixes.
33+
34+
### Security
35+
- in case of vulnerabilities.
1336

1437
## About the release cycle
1538

1639
HydePHP consists of two primary components, Hyde/Hyde and Hyde/Framework. Development is made in the [Hyde/Develop Monorepo](https://github.com/hydephp/develop). Major and Minor release versions are made in the Develop project. These releases are synced to the Hyde and Framework projects, and are what this changelog file tracks. Patch release versions are made in the Framework and Hyde projects independently. See https://github.com/hydephp/develop#releases for more information.
1740

18-
<!-- CHANGELOG_START -->
41+
# HydePHP v2.0 Release Notes
42+
43+
## Overview
44+
45+
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.
46+
47+
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](https://hydephp.com/docs/2.x/upgrade-guide).
48+
49+
## Major Features
50+
51+
### 🚀 Modern Frontend Tooling with Vite
52+
53+
We've replaced Laravel Mix with Vite for a faster, more modern development experience:
54+
- **Instant Hot Module Replacement (HMR)** for real-time updates during development
55+
- **Direct asset compilation** into the `_media` folder for cleaner builds
56+
- **Updated build command**: Use `npm run build` instead of `npm run prod` (or `--vite` during the site build)
57+
- **Vite facade** for seamless Blade template integration
58+
- **Optimized asset serving** through the realtime compiler
59+
- **Hyde Vite plugin** for enhanced integration
60+
61+
### 🎨 Enhanced Asset Management System
62+
63+
The new consolidated Asset API provides a more intuitive interface for handling media files:
64+
- **MediaFile instances** with fluent methods like `getLink()`, `getLength()`, and `getMimeType()`
65+
- **HydeFront facade** for CDN links and Tailwind configuration injection
66+
- **Intelligent caching** with CRC32 hashing for improved performance
67+
- **Automatic validation** to prevent missing assets from going unnoticed
68+
- **Lazy-loaded metadata** for optimal resource usage
69+
70+
### 🧭 Redesigned Navigation API
71+
72+
The navigation system has been completely rewritten for maximum flexibility:
73+
- **YAML configuration support** for defining navigation items
74+
- **Extra attributes** for custom styling and behavior
75+
- **Improved Routes facade** with Laravel-consistent naming conventions
76+
- **Natural priority ordering** using numeric prefixes in filenames
77+
- **Enhanced sidebar management** with better organization options
78+
79+
### 📝 Improved Documentation Features
80+
81+
Documentation pages now benefit from several enhancements:
82+
- **Alpine.js-powered search** with customizable implementation
83+
- **Blade-based table of contents** that's 40x faster than before
84+
- **Custom heading renderer** with improved permalink handling
85+
- **Colored blockquotes** now using Tailwind CSS classes
86+
- **Smart natural language processing** for search headings
87+
- **Dynamic source file links** in Markdown documents
88+
89+
### 🎯 Better Developer Experience
90+
91+
Numerous quality-of-life improvements for developers:
92+
- **PHP 8.4 support** and Laravel 11 compatibility
93+
- **ESM module support** for modern JavaScript development
94+
- **Tailwind CSS v4** with automated upgrade tools
95+
- **Enhanced data collections** with syntax validation
96+
- **Improved error messages** with clearer exception handling
97+
- **Interactive publish:views command** on Unix systems
98+
- **Extension callbacks** with `booting()` and `booted()` methods
99+
## Upgrading to v2.0
100+
101+
**📖 For complete step-by-step upgrade instructions, see the [Upgrade Guide](https://hydephp.com/docs/2.x/upgrade-guide).**
102+
103+
**Important:** PHP 8.2+ is now required. Laravel Mix has been replaced with Vite, and Tailwind CSS has been upgraded to v4.
104+
105+
---
106+
107+
## Breaking Changes
108+
109+
### High Impact Changes
110+
111+
#### 1. Tailwind CSS v4 Upgrade
112+
113+
We've upgraded from Tailwind CSS v3 to v4. Run the automated upgrade tool to migrate your custom classes:
114+
115+
```bash
116+
npx @tailwindcss/upgrade
117+
```
118+
119+
Review the [Tailwind v4 Upgrade Guide](https://tailwindcss.com/docs/upgrade-guide) for detailed breaking changes.
120+
121+
#### 2. ESM Module Migration
122+
123+
Frontend tooling now uses ESM modules instead of CommonJS. If you have custom JavaScript, update to ESM syntax:
124+
125+
**Before:**
126+
```javascript
127+
const module = require('module-name');
128+
module.exports = { /* ... */ };
129+
```
130+
131+
**After:**
132+
```javascript
133+
import module from 'module-name';
134+
export default { /* ... */ };
135+
```
136+
137+
#### 3. Navigation Configuration Format
138+
139+
Update your navigation configuration to use the new array-based format:
140+
141+
**Before:**
142+
```php
143+
'navigation' => [
144+
'custom_items' => [
145+
'Custom Item' => '/custom-page',
146+
],
147+
],
148+
```
149+
150+
**After:**
151+
```php
152+
'navigation' => [
153+
'custom_items' => [
154+
['label' => 'Custom Item', 'destination' => '/custom-page'],
155+
],
156+
],
157+
```
158+
159+
#### 4. Features Configuration
160+
161+
Replace static method calls with enum values in your `config/hyde.php`:
162+
163+
**Before:**
164+
```php
165+
'features' => [
166+
Features::htmlPages(),
167+
Features::markdownPosts(),
168+
],
169+
```
170+
171+
**After:**
172+
```php
173+
'features' => [
174+
Feature::HtmlPages,
175+
Feature::MarkdownPosts,
176+
],
177+
```
178+
179+
### General Impact Changes
180+
181+
#### Post Author System
182+
183+
The blog post author feature has been significantly improved:
184+
185+
**Configuration changes:**
186+
```php
187+
// Before
188+
'authors' => [
189+
Author::create('username', 'Display Name', 'https://example.com'),
190+
],
191+
192+
// After
193+
'authors' => [
194+
'username' => Author::create(
195+
name: 'Display Name',
196+
website: 'https://example.com',
197+
bio: 'Author bio',
198+
avatar: 'avatar.png',
199+
socials: ['twitter' => '@username']
200+
),
201+
],
202+
```
203+
204+
Key changes:
205+
- Authors are now keyed by username
206+
- `Author::create()` returns an array instead of a `PostAuthor` instance
207+
- `Author::get()` returns `null` if not found (previously created new instance)
208+
- Usernames are automatically normalized (lowercase, underscores for spaces)
209+
- Authors support biographies, avatars, and social media links
210+
- A new `Hyde::authors()` method provides access to all site authors
211+
- Authors can be configured via YAML
212+
213+
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.
214+
215+
### Medium Impact Changes
216+
217+
#### Asset API Updates
218+
219+
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.
220+
221+
```php
222+
// Methods renamed for clarity
223+
Hyde::asset('image.png'); // Previously: Hyde::mediaLink()
224+
Asset::get('image.png'); // Previously: Asset::mediaLink()
225+
Asset::exists('image.png'); // Previously: Asset::hasMediaFile()
226+
HydeFront::cdnLink('app.css'); // Previously: Asset::cdnLink()
227+
```
228+
229+
Configuration changes:
230+
- Rename `hyde.enable_cache_busting` to `hyde.cache_busting`
231+
- Remove references to `hyde.hydefront_version` and `hyde.hydefront_cdn_url`
232+
233+
#### Routes Facade API
234+
235+
Methods renamed to follow Laravel conventions:
236+
237+
```php
238+
// Before
239+
$route = Routes::get('route-name'); // Returns null if not found
240+
$route = Routes::getOrFail('route-name'); // Throws exception
241+
242+
// After
243+
$route = Routes::find('route-name'); // Returns null if not found
244+
$route = Routes::get('route-name'); // Throws exception
245+
```
246+
247+
#### DataCollection API
248+
249+
- Class renamed from `DataCollections` to `DataCollection`
250+
- Syntax validation now throws `ParseException` for malformed files
251+
- Empty data files are no longer allowed
252+
- Directory creation is no longer automatic
253+
- The `route` function now throws `RouteNotFoundException` if route not found
254+
255+
### Low Impact Changes
256+
257+
#### Includes Facade Return Types
258+
259+
Methods now return `HtmlString` objects:
260+
261+
```blade
262+
{{-- Before: Required unescaped output --}}
263+
{!! Includes::html('partial') !!}
264+
265+
{{-- After: Automatic rendering --}}
266+
{{ Includes::html('partial') }}
267+
```
268+
269+
⚠️ **Security Note:** Output is no longer escaped by default. Use `{{ e(Includes::html('foo')) }}` for user-generated content.
270+
271+
#### Documentation Search Generation
272+
273+
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.
274+
275+
#### Sidebar Configuration
276+
277+
Documentation sidebar configuration has been reorganized:
278+
- `docs.sidebar_order` → `docs.sidebar.order`
279+
- `docs.table_of_contents` → `docs.sidebar.table_of_contents`
280+
- `docs.sidebar_group_labels` → `docs.sidebar.labels`
281+
282+
## New Features
283+
284+
### Enhanced Blog Posts
285+
286+
- **Simplified image front matter** with new "caption" field
287+
- **Date prefixes in filenames** for automatic publishing dates
288+
- **Rich markup data** with BlogPosting Schema.org type
289+
- **Author collections** accessible via `Hyde::authors()`
290+
- **Custom posts support** in blog feed component
291+
292+
### Improved Build System
293+
294+
- **Vite integration** with HMR support in realtime compiler
295+
- **Smart asset compilation** - app.js only compiles when needed
296+
- **Environment variable support** for saving previews
297+
- **Grouped progress bars** for InMemoryPage instances
298+
- **Media asset transfers** via dedicated build task
299+
300+
### Developer Tools
301+
302+
- **Interactive publish:views command** on Unix systems
303+
- **Custom HydeSearch.js** support for search customization
304+
- **Extension callbacks** with `booting()` and `booted()` methods
305+
- **Dynamic source file links** in Markdown documents (for example `[Home](/_pages/index.blade.php)`)
306+
- **Filesystem::ensureParentDirectoryExists()** helper method
307+
308+
## Package Updates
309+
310+
### Realtime Compiler
311+
- Simplified asset file locator for media source directory
312+
- Added Vite HMR support
313+
- Experimental Laravel Herd support
314+
315+
### HydeFront
316+
- Complete migration from Sass to Tailwind CSS
317+
- Extracted CSS component partials
318+
- Removed legacy hyde.css file
319+
320+
## Performance Improvements
321+
322+
- **40x faster table of contents generation** using Blade components
323+
- **CRC32 hashing** replaces MD5 for cache busting (much faster)
324+
- **Lazy-loaded media metadata** with in-memory caching
325+
- **Cached media assets** in HydeKernel for instant access
326+
327+
## Dependency Updates
328+
329+
- **PHP**: Now requires 8.2–8.4 (dropped 8.1 support)
330+
- **Laravel**: Upgraded to version 11
331+
- **Tailwind CSS**: Upgraded to version 4
332+
- **Symfony/Yaml**: Updated to version 7
333+
- **Torchlight**: Switched to forked version for compatibility
334+
335+
## Removed Features
336+
337+
### Deprecated Method Removals
338+
- `PostAuthor::getName()` - use `$author->name` property
339+
- `FeaturedImage::isRemote()` - use `Hyperlinks::isRemote()`
340+
- `DocumentationPage::getTableOfContents()` - use Blade component
341+
- `MarkdownService::withPermalinks()` and `canEnablePermalinks()`
342+
343+
### Build Commands
344+
- `npm run prod` - replaced by `npm run build`
345+
- `--run-dev` and `--run-prod` flags - replaced by `--vite`
346+
- `--run-prettier` flag and Prettier dependency removed
347+
348+
### Configuration Options
349+
- `hyde.hydefront_version` and `hyde.hydefront_cdn_url` - now handled automatically
350+
- `hyde.enable_cache_busting` - renamed to `hyde.cache_busting`
351+
- `hyde.navigation.subdirectories` - renamed to `hyde.navigation.subdirectory_display`
352+
353+
### Components and Files
354+
- `hyde.css` from HydeFront - all styles now in `app.css`
355+
- `table-of-contents.css`, `heading-permalinks.css`, `blockquotes.css` - styles now use Tailwind
356+
- `.torchlight-enabled` CSS class
357+
- `<x-hyde::docs.search-input />` and `<x-hyde::docs.search-scripts />` components - replaced by `<x-hyde::docs.hyde-search />`
358+
359+
## Support & Resources
360+
361+
- **Documentation**: [https://hydephp.com/docs/2.x](https://hydephp.com/docs/2.x)
362+
- **Upgrade Guide**: [https://hydephp.com/docs/2.x/upgrade-guide](https://hydephp.com/docs/2.x/upgrade-guide)
363+
- **GitHub Issues**: [https://github.com/hydephp/hyde/issues](https://github.com/hydephp/hyde/issues)
364+
- **Community Discord**: [https://discord.hydephp.com](https://discord.hydephp.com)
365+
366+
---
367+
368+
For the complete changelog with all pull request references, see the [full changelog](https://github.com/hydephp/hyde/releases/tag/v2.0.0).
369+
19370

20371
## [1.8.0](https://github.com/hydephp/develop/releases/tag/1.8.0) - 2025-05-17
21372
### Added

‎packages/framework/src/Foundation/HydeKernel.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ class HydeKernel implements SerializableContract
5050
use Serializable;
5151
use Macroable;
5252

53-
final public const VERSION = '2.0.0-RC.4';
53+
final public const VERSION = '2.0.0';
5454

5555
protected static self $instance;
5656

0 commit comments

Comments
 (0)