Acorn v5 installation and upgrading docs

acorn/installation.md

@@ -26,13 +26,12 @@ This means you get access to Laravel's artisan commands through the use of [`wp
 
 ## Installing Acorn with Composer
 
-We recommend that you install Acorn on your WordPress install managed by Composer, such as with [Bedrock](https://roots.io/bedrock/):
+Install Acorn with Composer:
 
 ```shell
 $ composer require roots/acorn
 ```
 
-If you don't use Composer to manage your WordPress install and you are using a Sage-based theme, you can install Acorn with Composer from your theme directory. Navigate to your theme folder and then run the command above.
 
 ## Booting Acorn
 
@@ -46,7 +45,9 @@ Add the following in your theme's `functions.php` file, or in your main plugin f
 ```php
 <?php
 
-if (! function_exists('\Roots\bootloader')) {
+use Roots\Acorn\Application;
+
+if (! class_exists(\Roots\Acorn\Application::class)) {
     wp_die(
         __('You need to install Acorn to use this site.', 'domain'),
         '',
@@ -57,11 +58,57 @@ if (! function_exists('\Roots\bootloader')) {
     );
 }
 
-add_action('after_setup_theme', fn () => \Roots\bootloader()->boot(), 0);
-```
+add_action('after_setup_theme', function () {
+    Application::configure()
+        ->withProviders([
+            App\Providers\ThemeServiceProvider::class,
+        ])
+        ->boot();
+}, 0);
 
 </details>
 
+### Advanced booting
+
+Acorn provides several additional configuration methods that can be chained before booting. Here's a comprehensive example with explanations:
+
+```php
+add_action('after_setup_theme', function () {
+    Application::configure()
+        ->withProviders([
+            // Register your service providers
+            App\Providers\ThemeServiceProvider::class,
+        ])
+        ->withMiddleware(function (Middleware $middleware) {
+            // Configure HTTP middleware for WordPress requests
+            $middleware->wordpress([
+                Illuminate\Cookie\Middleware\EncryptCookies::class,
+                Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
+                Illuminate\Session\Middleware\StartSession::class,
+                Illuminate\View\Middleware\ShareErrorsFromSession::class,
+                Illuminate\Foundation\Http\Middleware\ValidateCsrfToken::class,
+                Illuminate\Routing\Middleware\SubstituteBindings::class,
+            ]);
+
+            // You can also configure middleware for web and API routes
+            // $middleware->web([...]);
+            // $middleware->api([...]);
+        })
+        ->withExceptions(function (Exceptions $exceptions) {
+            // Configure exception handling
+            // $exceptions->reportable(function (\Throwable $e) {
+            //     Log::error($e->getMessage());
+            // });
+        })
+        ->withRouting(
+            // Configure routing with named parameters
+            web: base_path('routes/web.php'),    // Laravel-style web routes
+            api: base_path('routes/api.php'),    // API routes
+            wordpress: true,                     // Enable WordPress request handling
+        )
+        ->boot();
+}, 0);
+
 ## Add the autoload dump script
 
 Acorn has a function that should be added to the `scripts` section of your `composer.json` file for the `post-autoload-dump` event. To automatically configure this script, run the following command:
@@ -73,7 +120,7 @@ $ wp acorn acorn:install
 Select **Yes** when prompted to install the Acorn autoload dump script.
 
 ::: warning
-`wp acorn` commands won't work if your theme/plugin that boots Acorn hasn't been activated and will result in the following message: 
+`wp acorn` commands won't work if your theme/plugin that boots Acorn hasn't been activated and will result in the following message:
 
 **Error: 'acorn' is not a registered wp command.**
 :::
@@ -98,6 +145,6 @@ Open `composer.json` and add Acorn's `postAutoloadDump` function to Composer's `
 
 Acorn's server requirements are minimal, and mostly come from WordPress and [Laravel 10's requirements](https://laravel.com/docs/10.x/deployment#server-requirements).
 
-- PHP >=8.1 with extensions: BCMath, Ctype, Fileinfo, JSON, Mbstring, Tokenizer, XML
+- PHP >=8.2 with extensions: BCMath, Ctype, Fileinfo, JSON, Mbstring, Tokenizer, XML
 - WordPress >= 5.4
 - [WP-CLI](https://wp-cli.org/)

acorn/upgrading-acorn.md

@@ -11,6 +11,64 @@ authors:
 
 # Upgrading Acorn
 
+## Upgrading to v5.x from v4.x
+
+Acorn v5 includes Laravel v11 components, whereas Acorn v4 includes Laravel v10 components.
+
+### Upgrading dependencies
+
+Acorn v5 requires PHP >= 8.2.
+
+Update the `roots/acorn` dependency in your `composer.json` file to `^5.0`:
+
+```shell
+$ composer require roots/acorn ^5.0 -W
+```
+
+The `-W` flag is required to upgrade the included Laravel dependencies.
+
+::: warning
+If any packages/dependencies have conflicts while updating, try removing and then re-requiring them after Acorn is bumped to 5.x.
+:::
+
+### Breaking changes
+
+The most significant change in v5 is how Acorn is booted. The `bootloader()` helper has been deprecated in favor of using `Application::configure()`. This change aligns Acorn with Laravel 11's new application configuration system, providing a more fluent and powerful way to configure your application.
+
+You'll need to import the Application class at the top of your file:
+
+```php
+use Roots\Acorn\Application;
+```
+
+Then update your bootstrapping code:
+
+```diff
+- add_action('after_setup_theme', fn () => \Roots\bootloader()->boot(), 0);
++ add_action('after_setup_theme', function () {
++     Application::configure()
++         ->withProviders([
++             App\Providers\ThemeServiceProvider::class,
++         ])
++         ->boot();
++ }, 0);
+```
+
+If you have previously registered service providers through either `composer.json` (`extra.acorn.providers`) or `config/app.php`, you'll need to migrate these to the new configuration method. All providers should now be registered using `withProviders()` when configuring the application. Remove any provider configurations from your composer.json and config files, and instead register them directly in your bootstrapping code:
+
+```php
+Application::configure()
+    ->withProviders([
+        App\Providers\ThemeServiceProvider::class,
+        App\Providers\ExampleServiceProvider::class,
+    ])
+    ->boot();
+```
+
+### Config changes
+
+If you have published Acorn's configs, you should review and update them based on the latest versions in the [Acorn repo](https://github.com/roots/acorn/tree/main/config).
+
 ## Upgrading to v4.x from v3.x
 
 Acorn v4 includes Laravel v10 components, whereas Acorn v3 includes Laravel v9 components.
@@ -208,7 +266,7 @@ namespace App\Providers;
 }
 ```
 
-After doing so, you may need to delete [Acorn's application cache directory](https://roots.io/acorn/docs/directory-structure/). By default, this is located in `[wp-content|app]/cache/acorn/`. 
+After doing so, you may need to delete [Acorn's application cache directory](https://roots.io/acorn/docs/directory-structure/). By default, this is located in `[wp-content|app]/cache/acorn/`.
 
 Reference the [Acorn v3 upgrade pull request on the Sage repo](https://github.com/roots/sage/pull/3097) to see a full diff.