v8.3 docs

docs/the-basics/error-handling.md

@@ -0,0 +1,86 @@
+---
+title: Error Handling
+description: Lumberjack provides a robust error handling system that displays detailed error pages in development and a generic error page in production.
+sidebar_position: 13
+---
+
+# Error Handling
+
+Lumberjack comes with a powerful error handling system powered by [Ignition](https://spatie.be/docs/ignition/v1/introduction), which provides beautiful, detailed error pages when you're in development. When in production, Lumberjack will display a simple, styled error page to avoid exposing sensitive information.
+
+## The Default Error Page
+
+When `APP_DEBUG` is set to `false` in your `.env` file, Lumberjack will catch any exceptions and display a generic error page. This prevents your site from showing a blank white page or a detailed error stack trace that could be a security risk.
+
+![Default Error Page](/img/error-page-screenshot.png)
+
+As you can see, it's a simple, clean error page that informs the user that something has gone wrong.
+
+## Customizing the Error Page
+
+While the default error page is a great starting point, you may want to create a custom error page that matches your site's branding. You can do this by extending the `Rareloop\Lumberjack\Exceptions\Handler` class and overriding the `renderDefaultErrorView` method.
+
+It's important to note that the expectation is that you will extend the exception handler to create your own custom error pages.
+
+Here's an example of how you might create a custom error handler:
+
+```php
+// app/Exceptions/Handler.php
+namespace App\Exceptions;
+
+use Exception;
+use Psr\Http\Message\ResponseInterface;
+use Rareloop\Lumberjack\Http\Responses\TimberResponse;
+use Rareloop\Lumberjack\Exceptions\Handler as ExceptionHandler;
+
+class Handler extends ExceptionHandler
+{
+    protected function renderDefaultErrorView(Exception $e): ResponseInterface
+    {
+        $status = method_exists($e, 'getStatusCode') ? $e->getStatusCode() : 500;
+
+        return new TimberResponse('views/errors/error.twig', [
+            'statusCode' => $status,
+        ], $status);
+    }
+}
+```
+
+In this example, we're telling Lumberjack to render the `views/errors/error.twig` template instead of the default one. You can now create a custom Twig file with your own branding.
+
+Once you have created your custom `Handler` class, you will need to update your `bootstrap/app.php` file to tell Lumberjack to use your custom handler instead of the default one.
+
+```php
+// bootstrap/app.php
+...
+$app->singleton(
+    Rareloop\Lumberjack\Contracts\ExceptionHanlder::class,
+    App\Exceptions\Handler::class
+);
+...
+```
+
+## Configuring Ignition
+
+Lumberjack v8.3 introduces a new `Ignition` facade and `IgnitionServiceProvider` to make it easier to configure Ignition. You can now add solution providers, set themes, and more from any service provider.
+
+Here's an example of how you might add a custom solution provider to Ignition in your `AppServiceProvider`:
+
+```php
+// app/Providers/AppServiceProvider.php
+namespace App\Providers;
+
+use App\Solutions\MyCustomSolutionProvider;
+use Rareloop\Lumberjack\Facades\Ignition;
+use Rareloop\Lumberjack\Providers\ServiceProvider;
+
+class AppServiceProvider extends ServiceProvider
+{
+    public function boot()
+    {
+        Ignition::addSolutionProviders([
+            MyCustomSolutionProvider::class,
+        ]);
+    }
+}
+```

docs/the-basics/wordpress-controllers.md

@@ -101,3 +101,49 @@ add_filter('lumberjack/password_protect_template', function() {
     return 'my-password-template.twig';
 });
 ```
+
+## Dependency Injection in WordPress Controllers
+
+:::info
+Available from v8.3.0, with full adoption in v9
+:::
+
+In newer versions of Lumberjack, we've introduced dependency injection typehints for your WordPress controllers - for example:
+
+```diff
+class PageHomeController
+{
+-   public function handle()
++   public function handle(TimberContext $context, Post $post)
+    {
+-       $context = Timber::context();
+-       $context['post'] = Timber::get_post();
++       $context->set('post', $post);
+
+        return new TimberResponse('home', $context);
+    }
+}
+```
+
+This makes controllers much leaner, but critically, much more testable by de-coupling them from Timber.
+
+### Available Typehints
+
+Any object bound in the [Container](../container/using-the-container.md) can be typehinted, for example, `Application $app` or `\Rareloop\Lumberjack\LoggerInterface`.
+
+For each Lumberjack type, there's full support for child classes. For example, injecting a custom post type will respect your Timber classmap.
+
+| Typehint                             | Description                     | Timber Equivalent     |
+| ------------------------------------ | ------------------------------- | --------------------- |
+| `\Rareloop\Lumberjack\TimberContext` | Get a Timber context singleton  | `Timber::context()`   |
+| `\Rareloop\Lumberjack\PostQuery`     | Get all the posts for the query | `Timber::get_posts()` |
+| `\Rareloop\Lumberjack\Post`          | Get the current Post object     | `Timber::get_post()`  |
+| `\Your\Custom\PostType`              | Get the current PostType        | `Timber::get_post()`  |
+| `\Rareloop\Lumberjack\Term`          | Get the current Term            | `Timber::get_term()`  |
+| `\Your\Custom\CategoryTerm`          | Get the current CategoryTerm    | `Timber::get_term()`  |
+| `\Rareloop\Lumberjack\User`          | Get the current User            | `Timber::get_user()`  |
+| `\Your\Custom\AdminUser`             | Get the current AdminUser       | `Timber::get_user()`  |
+
+:::note
+For each of Lumberjack's Proxy objects, the upstream Timber classes/interfaces are also supported. For example, typehinting `\Timber\PostQuery` will return an instance of that class.
+:::

docs/upgrade-guide.md

@@ -6,6 +6,16 @@ sidebar_position: 3
 
 # Upgrade Guide
 
+## Upgrading from v8.2 to v8.3
+
+Estimated time for upgrade: 1 minute
+
+Lumberjack v8.3 is a minor release with no breaking changes.
+
+This release introduces a new default error page for production environments, provides an easier way to configure Ignition, and expands dependency injection support for WordPress controllers.
+
+See [Error Handling](./the-basics/error-handling) and [WordPress Controllers](./the-basics/wordpress-controllers.md#dependency-injection-in-wordpress-controllers).
+
 ## Upgrading from v8 to v8.1
 
 Estimated time for upgrade: 5 minutes

docs/whats-new.md

@@ -6,6 +6,14 @@ sidebar_position: 1
 
 # What's New
 
+## What's new in v8.3
+
+Lumberjack v8.3 is a minor release that introduces a styled default error page for production and refactors Ignition registration to improve extensibility.
+
+- **Production Error Page**: A clean, styled 'Lumberjack | status' fallback page is now displayed when debug mode is `false`, preventing blank white pages on errors.
+- **Easier Ignition Configuration**: A new `Ignition` facade and `IgnitionServiceProvider` have been introduced to allow for easier configuration of Ignition. You can now easily add solution providers or set themes from any service provider.
+- **Expanded dependency injection support for WordPress controllers**: New, streamlined, options to make controllers smaller, and more testable.
+
 ## What's new in v8.2
 
 Lumberjack v8.2 is a minor release with the following changes: