Tag v8.1

Author: Tom Mitchelmore

docs/upgrade-guide.md

@@ -8,7 +8,7 @@ sidebar_position: 3
 
 ## Upgrading from v8 to v8.1
 
-Estimated time for upgrade: 30 minutes
+Estimated time for upgrade: 5 minutes
 
 ### Minimum PHP version increased to PHP 8.3
 

versioned_docs/version-v8.1/README.md

@@ -0,0 +1,72 @@
+---
+id: introduction
+title: Introduction
+description: Supercharge your WordPress Development
+sidebar_position: 1
+---
+
+# Introduction
+
+Lumberjack is a powerful MVC framework for the modern WordPress developer. Write better, more expressive and easier to maintain code.
+
+### Who is Lumberjack for?
+
+Coming from another PHP framework such as Laravel, have experience using Timber with WordPress but want more, or are just getting started with modern WordPress? Then Lumberjack is for you.
+
+Use as little or as much as you need, it's beginner friendly!
+
+### Beautiful code. Easy to maintain
+
+Object orientated and MVC patterns help keep your code structured and DRY.
+
+**index.php**
+
+```php
+class IndexController
+{
+    public function handle()
+    {
+        $context = Timber::context();
+        $context['posts'] = Post::builder()
+            ->whereStatus('publish')
+            ->limit(5)
+            ->get();
+
+        return new TimberResponse('index.twig', $context);
+    }
+}
+```
+
+**index.twig**
+
+```twig
+{% if posts is not empty %}
+    <h4>Recent Articles</h4>
+    <ul>
+        {% for post in posts %}
+            <li class="article">
+                <h3>{{ $post->title }}</h3>
+                {{ $post->preview }}
+                <a href="{{ $post->link }}">Read the full story</a>
+            </li>
+        {% endfor %}
+    </ul>
+{% endif %}
+```
+
+### You're in good company
+
+> Lumberjack is the deluxe version of what Modern WordPress should look like today. The team has done a great job of making it easy to build complicated custom applications while taking advantage of the best parts of WordPress.
+>
+> - _**Jared Novack - Timber creator**_
+
+Standing on the shoulders of giants, Lumberjack proudly builds on the great work of other open source WordPress projects:
+
+- [Timber](https://www.upstatement.com/timber/)
+- [Bedrock](https://roots.io/bedrock/)
+
+### Made by [Rareloop](https://rareloop.com)
+
+We're a Digital Product Studio based in Southampton (UK) with many years experience working on modern WordPress websites. We design and build digital products for a range of clients, take a look at what else we can do.
+
+[Find out more](https://www.rareloop.com/)

versioned_docs/version-v8.1/container/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Container",
+  "position": 6
+}

versioned_docs/version-v8.1/container/facades.md

@@ -0,0 +1,110 @@
+---
+sidebar_position: 3
+---
+
+# Facades
+
+Lumberjack provides a custom implementation of Facades, based on the now-deprecated [Blast Facades](https://github.com/phpthinktank/blast-facades) library.
+
+## Creating a Facade
+
+Facades provide a simple static API to an object that has been registered into the container. For example to setup a facade you would first use a Service Provider to register an instance of your class into the container:
+
+```php
+namespace Rareloop\Lumberjack\Providers;
+
+use Monolog\Logger;
+use Rareloop\Lumberjack\Application;
+
+class LogServiceProvider extends ServiceProvider
+{
+    public function register()
+    {
+        // Create object instance and bind into container
+        $this->app->bind('logger', new Logger('app'));
+    }
+}
+```
+
+Then create a Facade subclass and tell it which key to use to retrieve your class instance:
+
+```php
+namespace Rareloop\Lumberjack\Facades;
+
+use Rareloop\Lumberjack\Facades\AbstractFacade;
+
+class Log extends AbstractFacade
+{
+    protected static function accessor()
+    {
+        return 'logger';
+    }
+}
+```
+
+## Available Facades
+
+Lumberjack comes with a handful of useful Facades. Below you can see which class the Facade references and what it is bound to the container under.
+
+| Facade  | Class Reference                              | Container binding |
+| :------ | :------------------------------------------- | :---------------- |
+| Config  | `Rareloop\Lumberjack\Config`                 | `config`          |
+| Log     | `Monolog\Logger`                             | `logger`          |
+| Router  | `Rareloop\Lumberjack\Http\Route`             | `router`          |
+| Session | `Rareloop\Lumberjack\Session\SessionManager` | `session`         |
+
+### Example usage
+
+All of Lumberjack's Facades live under the `Rareloop\Lumberjack\Facades` namespace.
+
+#### Config
+
+The `Config` facade allows you to get and set values from your config.
+
+```php
+use Rareloop\Lumberjack\Facades\Config;
+
+Config::set('app.debug', false);
+
+$value = Config::get('app.debug');
+```
+
+Config is also available as a [Helper](/the-basics/helpers#config)
+
+#### Log
+
+The `Log` facade allows you to use the [PSR-3](https://www.php-fig.org/psr/psr-3/) Logger [Monolog](https://github.com/Seldaek/monolog).
+
+```php
+use Rareloop\Lumberjack\Facades\Log;
+
+$value = Log::warning('Oops! Something went wrong');
+```
+
+#### Router
+
+The `Router` facade allows you to create custom routes or get the URLs for your routes.
+
+```php
+use Rareloop\Lumberjack\Facades\Router;
+
+Router::get('posts/all', function () {})->name('posts.index');
+
+$url = Router::url('posts.index');
+```
+
+See [Creating Routes](/the-basics/routing#creating-routes) for more information.
+
+#### Session
+
+The `Session` facade allows you to retrieve and store data in the current session.
+
+```php
+use Rareloop\Lumberjack\Facades\Session;
+
+Session::put('name', 'Chris');
+
+$name = Session::get('name');
+```
+
+Session is also available as a [Helper](/the-basics/helpers#session)

versioned_docs/version-v8.1/container/service-providers.md

@@ -0,0 +1,90 @@
+---
+sidebar_position: 2
+---
+
+# Service Providers
+
+## Introduction
+
+When Lumberjack bootstraps it creates an Application Container, which is responsible for resolving concrete classes that have been **bound** to the container in one way or another. This binding happens via Service Providers.
+
+A Service Provider needs to be registered with Lumberjack. This can be done in `config/app.php` under the `providers` array.
+
+Let's look at how to create a new Service Provider and register it to the container.
+
+## Creating Service Providers
+
+Service Providers can live anywhere within the `app/` directory, or even as packages that you bring in via composer. Let's create a new file within `app/Providers` called `PaymentGatewayProvider.php`.
+
+This file must extend `Rareloop\Lumberjack\Providers\ServiceProvider`. This gives you access to the container via `$this->app`. There are 2 methods that Lumberjack looks for on a Service Providers: `register()` and `boot()`.
+
+### Register
+
+The `register` method should only be used to bind things to the container. You cannot rely on Lumberjack registering service providers in any order, so you should always assume no other provider had been registered.
+
+You should not attempt to do anything other than binding things to the container in `register`. Do not try and add WordPress filters/actions, register routes, configure WordPress etc here. This is to prevent you from accidentally using a service provider which has not been loaded yet.
+
+```php
+namespace App\Providers;
+
+use Rareloop\Lumberjack\Providers\ServiceProvider;
+
+class PaymentGatewayProvider extends ServiceProvider
+{
+    public function register()
+    {
+        $this->app->bind('\App\PaymentGateway', '\App\StripePaymentGateway');
+    }
+}
+```
+
+Now, whenever we need to use a payment gateway in our application we can resolve it from the container. This, in theory, makes it really easy to swap out Stripe with another payment gateway.
+
+#### Binding to the container
+
+There are a number of different ways to bind things to the container. Head over to ['Using the Container'](using-the-container.md) for more information.
+
+### Boot
+
+Once all service providers have been registered, Lumberjack then attempts to call the `boot` method on each one. This means that you have access to everything that has been bound to the container and can access it using [dependency injection](using-the-container.md#dependency-injection) on the `boot` method.
+
+```php
+namespace App\Providers;
+
+use Rareloop\Lumberjack\Providers\ServiceProvider;
+use Rareloop\Lumberjack\Config;
+
+/**
+ * Add Option Pages to WP using the config, using ACF
+ */
+class OptionPagesProvider extends ServiceProvider
+{
+    // Dependency inject Config from the container
+    public function boot(Config $config)
+    {
+        $optionPages = $config->get('option-pages');
+
+        if (!is_array($optionPages)) {
+            return;
+         }
+
+         foreach ($optionPages as $optionPage) {
+             acf_add_options_page($optionPage);
+         }
+    }
+}
+```
+
+### Register Service Providers with Lumberjack
+
+Once you have your service provider ready to go, you need to add the name of the class to the `providers` array in `config/app.php`.
+
+```php
+return [
+    'providers' => [
+        // ...
+
+        App\Providers\TwitterProvider::class,
+    ],
+];
+```