From 6292164f9a892eb60eb124f3b3d4f6badf7838a0 Mon Sep 17 00:00:00 2001 From: Adam Date: Wed, 5 Apr 2023 16:10:56 +0000 Subject: [PATCH 1/4] GITBOOK-1: Add v6 docs --- the-basics/collections.md | 15 +++----- the-basics/view-models.md | 21 +++++----- upgrade-guide.md | 73 +++++++++++++++++++++++++++++------ whats-new.md | 81 ++++++++++++++++++++++++++++++--------- 4 files changed, 139 insertions(+), 51 deletions(-) diff --git a/the-basics/collections.md b/the-basics/collections.md index 345013d..f696bbb 100644 --- a/the-basics/collections.md +++ b/the-basics/collections.md @@ -9,7 +9,7 @@ description: >- You can create a collection in a couple of ways: ```php -use Tightenco\Collect\Support\Collection; +use Illuminate\Support\Collection; $data = new Collection(['Jayne', 'Milo']); @@ -35,19 +35,14 @@ $data = collect(['Jayne', 'Milo']); $firstName = $data->first(); ``` -The collection class that Lumberjack uses comes from Laravel, [via a split package by Tighten Co.](https://github.com/tightenco/collect) - -For a list of the available methods, please refer to their documentation: [https://laravel.com/docs/5.8/collections\#available-methods](https://laravel.com/docs/5.8/collections#available-methods) +For a list of the available methods, please refer to their documentation: [https://laravel.com/docs/9.x/collections#available-methods](https://laravel.com/docs/9.x/collections#available-methods) {% hint style="info" %} -Note: Laravel's collections may change over time as the add/remove features etc. Make sure you are always referring to the correct version of their documentation. - -Lumberjack will use the latest collections version for Laravel `v5.x` _\(with the minimum version being `v5.6`\)_ +Note: Laravel's collections may change over time as they add/remove features etc. Make sure you are always referring to the correct version of their documentation. {% endhint %} ### Extending collections -Similar to post types and the query builder, you can add your own methods to the collection class using macros. For more information about this, please refer to Laravel's documentation: - -[https://laravel.com/docs/5.8/collections\#extending-collections](https://laravel.com/docs/5.8/collections#extending-collections) +Similar to post types and the query builder, you can add your own methods to the collection class using macros. For more information about this, please refer to Laravel's documentation: +[https://laravel.com/docs/9.x/collections#extending-collections](https://laravel.com/docs/9.x/collections#extending-collections) diff --git a/the-basics/view-models.md b/the-basics/view-models.md index edbc6c7..14964f1 100644 --- a/the-basics/view-models.md +++ b/the-basics/view-models.md @@ -1,6 +1,6 @@ # View Models -View Models are useful for preparing data for your Twig views. It’s common \(and typically desirable\) for the shape of the data needed by your views to be different from how it is stored in the database or Post objects. How this data is transformed can be encapsulated in a View Model, cutting down repetitive code you have in your Controllers. +View Models are useful for preparing data for your Twig views. It’s common (and typically desirable) for the shape of the data needed by your views to be different from how it is stored in the database or Post objects. How this data is transformed can be encapsulated in a View Model, cutting down repetitive code you have in your Controllers. ## Example Controller @@ -62,7 +62,7 @@ class MediaCardViewModel extends ViewModel } ``` -Now lets pass in the post object into the view model and keep a \(protected\) reference to it. +Now lets pass in the post object into the view model and keep a (protected) reference to it. ```php get(App\AppInterface::class); $object1 === $object2; // false ``` -{% page-ref page="container/using-the-container.md" %} +{% content-ref url="container/using-the-container.md" %} +[using-the-container.md](container/using-the-container.md) +{% endcontent-ref %} -### `ServerRequest` class \(optional\) +### `ServerRequest` class (optional) {% hint style="warning" %} **Likelihood Of Impact: Optional, but recommended** @@ -170,13 +218,13 @@ $object1 === $object2; // false If you're injecting an instance of the Diactoros `ServerRequest` class into a Controller, you can now switch this out for the following class if you want to benefit from some of the [new helper functions](the-basics/http-requests.md#usage): -```text +``` Rareloop\Lumberjack\Http\ServerRequest ``` For example: -```text +``` use Rareloop\Lumberjack\Http\ServerRequest; class MyController @@ -233,7 +281,9 @@ $request->input('name', 'Jane'); $request->has('name'); ``` -{% page-ref page="the-basics/http-requests.md" %} +{% content-ref url="the-basics/http-requests.md" %} +[http-requests.md](the-basics/http-requests.md) +{% endcontent-ref %} ### View Models @@ -243,7 +293,7 @@ $request->has('name'); This is a previously undocumented feature. If you are using ViewModels, this is a major change to how they work. However, if you are not using ViewModels you do not need to do anything. {% endhint %} -View Models are simple classes that allow you to transform data that would otherwise be defined in your controller. This allows for better encapsulation of code and allows your code to be re-used across your controllers \(and even across themes\). +View Models are simple classes that allow you to transform data that would otherwise be defined in your controller. This allows for better encapsulation of code and allows your code to be re-used across your controllers (and even across themes). #### Upgrading existing ViewModels @@ -313,7 +363,7 @@ $app->singleton(HandlerInterface::class, Handler::class); **Likelihood Of Impact: Very low** {% endhint %} -`Helpers::app()` \(and the `app()` global counterpart\) no longer use the `make()` method of the Application instance and now rely on `get()`. This provides much more consistent behaviour with other uses of the Container. If you still want to use the helpers to get `make()` behaviour you can change your code. +`Helpers::app()` (and the `app()` global counterpart) no longer use the `make()` method of the Application instance and now rely on `get()`. This provides much more consistent behaviour with other uses of the Container. If you still want to use the helpers to get `make()` behaviour you can change your code. From: @@ -339,13 +389,13 @@ If you resolve an instance of the `Router` class from the container, you'll need From: -```text +``` use Rareloop\Router\Router ``` To: -```text +``` Rareloop\Lumberjack\Http\Router ``` @@ -358,4 +408,3 @@ Rareloop\Lumberjack\Http\Router The `http-interop/http-server-middleware` package has been deprecated in favour of the now official PSR-15 interfaces found in `psr/http-server-middleware`. Make sure any middleware used now complies with the `Psr\Http\Server\MiddlewareInterface` interface. - diff --git a/whats-new.md b/whats-new.md index 07bfae6..1866d9b 100644 --- a/whats-new.md +++ b/whats-new.md @@ -1,9 +1,33 @@ # What's New -This release of Lumberjack is jam packed full of goodies. We have also added a whole lot more documentation, so grab a cuppa and make yourself comfy while we take you through all the changes. +## What's new in v6.0 + +Lumberjack v6.0 comes with PHP 8.1 support. It also replaced the (deprecated) [tightenco/collect](https://packagist.org/packages/tightenco/collect) package with [illuminate/collections](https://packagist.org/packages/illuminate/collections) package. + +### Features + +Lumberjack will no longer give a 500 error for deprecation warnings, and instead will only "report" these to your error log. + +Specifically, lumberjack will only report (and not render) the following error codes: + +* `E_DEPRECATED` - [_Run-time notices. Enable this to receive warnings about code that will not work in future versions._](#user-content-fn-1)[^1] +* `E_USER_DEPRECATED` - _User-generated warning message. This is like an E\_DEPRECATED, except it is generated in PHP code by using the PHP function trigger\_error()._ +* `E_USER_NOTICE` - _User-generated notice message. This is like an E\_NOTICE, except it is generated in PHP code by using the PHP function trigger\_error()._ + +If you need to change this behaviour, you can add a new config file `config/errors.php` in your theme, like so: + +```php + [E_USER_ERROR], +]; +``` ## What's new in v4.3 +This release of Lumberjack is jam packed full of goodies. We have also added a whole lot more documentation, so grab a cuppa and make yourself comfy while we take you through all the changes. + ### Features #### Middleware Aliases on routes and controllers @@ -27,7 +51,9 @@ Router::get( )->middleware('auth'); ``` -{% page-ref page="the-basics/middleware.md" %} +{% content-ref url="the-basics/middleware.md" %} +[middleware.md](the-basics/middleware.md) +{% endcontent-ref %} #### `logger()` helper @@ -53,7 +79,9 @@ logger()->warning('Example warning'); Also, the `Logger` instance is now also bound to the PSR-3 interface `Psr\Log\LoggerInterface` in the Container. {% endhint %} -{% page-ref page="the-basics/helpers.md" %} +{% content-ref url="the-basics/helpers.md" %} +[helpers.md](the-basics/helpers.md) +{% endcontent-ref %} ### Patches @@ -86,7 +114,9 @@ $query->search('Elephant'); $posts = $query->first(); ``` -{% page-ref page="the-basics/query-builder.md" %} +{% content-ref url="the-basics/query-builder.md" %} +[query-builder.md](the-basics/query-builder.md) +{% endcontent-ref %} #### Define middleware in controllers @@ -114,9 +144,11 @@ class MyController extends Controller } ``` -{% page-ref page="the-basics/middleware.md" %} +{% content-ref url="the-basics/middleware.md" %} +[middleware.md](the-basics/middleware.md) +{% endcontent-ref %} -#### Config has\(\) +#### Config has() Lumberjack's configuration class now lets you check whether a config file contains a given item: @@ -126,17 +158,19 @@ if (Config::has('app.mySetting') { } ``` -Note that the `has` method only checks whether the config item exists, regardless of its value. +Note that the `has` method only checks whether the config item exists, regardless of its value. If you set `app.mySetting` to an empty value such as `false` or `null`, `has('app.mySetting')` will return `true`. -{% page-ref page="getting-started/configuration.md" %} +{% content-ref url="getting-started/configuration.md" %} +[configuration.md](getting-started/configuration.md) +{% endcontent-ref %} ### Documentation We have also added/revisited some of the documentation. We recommend checking these out: -* [View Models](the-basics/view-models.md) - New documentation +* [View Models](the-basics/view-models.md) - New documentation * [Middleware](the-basics/middleware.md) - New documentation * [Collections](the-basics/collections.md) - New documentation @@ -146,9 +180,9 @@ We have also added/revisited some of the documentation. We recommend checking th #### Extending Lumberjack with Macros -You can now extend core Lumberjack classes and add your own functionality without needing to rely on inheritance. Instead, you can add macros \(custom functions\) to the core classes themselves. +You can now extend core Lumberjack classes and add your own functionality without needing to rely on inheritance. Instead, you can add macros (custom functions) to the core classes themselves. -Here's an example macro, that adds a custom `acf()` method on `Rareloop\Lumberjack\Post`. +Here's an example macro, that adds a custom `acf()` method on `Rareloop\Lumberjack\Post`. ```php use Rareloop\Lumberjack\Post; @@ -172,7 +206,7 @@ The following classes are 'macroable': ## What's new in v4.0 -### General +### General #### PHP Version @@ -284,7 +318,9 @@ $value2->name; // 'Adam' Head over to the "Using the Container" docs to learn more: -{% page-ref page="container/using-the-container.md" %} +{% content-ref url="container/using-the-container.md" %} +[using-the-container.md](container/using-the-container.md) +{% endcontent-ref %} ### Features @@ -300,13 +336,17 @@ To make your development lives easier, there are now some additional helper func Check out the Helpers documentation for more details: -{% page-ref page="the-basics/helpers.md" %} +{% content-ref url="the-basics/helpers.md" %} +[helpers.md](the-basics/helpers.md) +{% endcontent-ref %} #### Query Builder -We've baked-in the [rareloop/lumberjack-querybuilder](https://github.com/Rareloop/lumberjack-querybuilder) package into the core. You now get an expressive, fluent and explicit way of querying data in WordPress out-of-the-box with Lumberjack. It can be used instead of [WP\_Query](https://codex.wordpress.org/Class_Reference/WP_Query) to query posts \(of any type\) and means you do not have to worry about "the loop". +We've baked-in the [rareloop/lumberjack-querybuilder](https://github.com/Rareloop/lumberjack-querybuilder) package into the core. You now get an expressive, fluent and explicit way of querying data in WordPress out-of-the-box with Lumberjack. It can be used instead of [WP\_Query](https://codex.wordpress.org/Class\_Reference/WP\_Query) to query posts (of any type) and means you do not have to worry about "the loop". -{% page-ref page="the-basics/query-builder.md" %} +{% content-ref url="the-basics/query-builder.md" %} +[query-builder.md](the-basics/query-builder.md) +{% endcontent-ref %} #### Sessions @@ -336,7 +376,9 @@ session()->forget('key'); Be sure to read the Sessions documentation for a more in-depth look: -{% page-ref page="the-basics/session.md" %} +{% content-ref url="the-basics/session.md" %} +[session.md](the-basics/session.md) +{% endcontent-ref %} #### Interacting with the request @@ -405,7 +447,9 @@ $request->has('name'); You can read the HTTP Requests documentation for more information: -{% page-ref page="the-basics/http-requests.md" %} +{% content-ref url="the-basics/http-requests.md" %} +[http-requests.md](the-basics/http-requests.md) +{% endcontent-ref %} ### Documentation @@ -417,3 +461,4 @@ We have also added/revisited some of the documentation. We recommend checking th * [Using the Container](container/using-the-container.md) - Revisited docs after the changes to the container's behaviour * [Helpers](the-basics/helpers.md) - Added more helpers +[^1]: From 95edf894dfe443640269f125e440fd3a18e29451 Mon Sep 17 00:00:00 2001 From: Adam Date: Thu, 27 Apr 2023 18:19:16 +0000 Subject: [PATCH 2/4] GITBOOK-2: Add docs on creating custom middleware --- the-basics/middleware.md | 58 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 53 insertions(+), 5 deletions(-) diff --git a/the-basics/middleware.md b/the-basics/middleware.md index ad8f897..e2f07db 100644 --- a/the-basics/middleware.md +++ b/the-basics/middleware.md @@ -121,15 +121,15 @@ To register an alias you can use the `MiddlewareAliases` facade. It is recommend There are 3 ways to define your middleware alias: -* A closure factory _\(recommended - always creates a new instance when used\)_ -* A class name _\(always resolves a new instance from the Container when used\)_ -* A previously instantiated object _\(you don't get the benefits of lazy loading\)_ +* A closure factory _(recommended - always creates a new instance when used)_ +* A class name _(always resolves a new instance from the Container when used)_ +* A previously instantiated object _(you don't get the benefits of lazy loading)_ {% hint style="info" %} -_See "_[_Setting entries in the container_](https://app.gitbook.com/@rareloop/s/lumberjack/~/edit/drafts/-Lk9PktE5_xnzl2Zs2j1/container/using-the-container#setting-entries-in-the-container)_" for more information about the differences between these. While only the class name uses the container, principally they behave in the same way with regards to lazy-loading and object instantiation_. +_See "_[_Setting entries in the container_](https://app.gitbook.com/@rareloop/s/lumberjack/\~/edit/drafts/-Lk9PktE5\_xnzl2Zs2j1/container/using-the-container#setting-entries-in-the-container)_" for more information about the differences between these. While only the class name uses the container, principally they behave in the same way with regards to lazy-loading and object instantiation_. {% endhint %} -#### Using a closure factory \(recommended\) +#### Using a closure factory (recommended) It is recommended that the alias is registered using a closure that acts as a factory, like so: @@ -209,3 +209,51 @@ Router::get( In this example, `$key` will have the value `X-Key` and `$value` will have the value of `HeaderValue`. +## Creating custom Middleware + +While you can use any PSR 15/7 Middleware, sometimes you need to write your own. In this example, we will create custom middleware that adds the response header `X-Foo`.\ +\ +First, create the class in `app/Http/Middleware/ExampleMiddleware.php` (create the folder if it doesn't exist) with the following content: + +```php +handle($request); + + return $response; + } +} +``` + +In our example, we want to modify the **response**. Below we add the `X-Foo` header to the response: + +```php +return $response->withHeader('X-Foo', 'Bar'); +``` + +If you need to modify the request before it gets passed to your application, you can do so before `$handler->handle($request)` gets called: + +```php +public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface +{ + // Chance to modify the request here before passing it into your application + + // Pass the request on (to the next middleware or your application) + $response = $handler->handle($request); + + // Chance to modify the response here before sending it back + + return $response; +} +``` From 3af6ead4a8643696812464ef571fe2756828404a Mon Sep 17 00:00:00 2001 From: Adam Date: Fri, 28 Apr 2023 11:15:14 +0000 Subject: [PATCH 3/4] GITBOOK-1: Fix bad php in response example --- the-basics/http-responses.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/the-basics/http-responses.md b/the-basics/http-responses.md index 41468eb..493f197 100644 --- a/the-basics/http-responses.md +++ b/the-basics/http-responses.md @@ -36,9 +36,13 @@ return new TimberResponse('home.twig', $context); When passing context data to TimberResponse, any objects that implement the `Rareloop\Lumberjack\Contracts\Arrayable` contract will automatically be flattened to a standard PHP array. This means that it is safe to use objects such as `Collection` and `ViewModel` in your data without it causing issues with Twig. -{% page-ref page="view-models.md" %} +{% content-ref url="view-models.md" %} +[view-models.md](view-models.md) +{% endcontent-ref %} -{% page-ref page="collections.md" %} +{% content-ref url="collections.md" %} +[collections.md](collections.md) +{% endcontent-ref %} ### Redirect Response @@ -57,7 +61,7 @@ return new RedirectResponse('/another/page'); If you want to redirect to a URL and also flash some data to the session, you can use the `with()` method. ```php -return new RedirectResponse('/another/page') +return (new RedirectResponse('/another/page')) ->with('error', 'Something went wrong'); ``` @@ -141,4 +145,3 @@ class TestException extends \Exception implements Responsable } } ``` - From 6b12d74135b1843ab03c90fdf615893eddfc01e1 Mon Sep 17 00:00:00 2001 From: Adam Date: Wed, 27 Mar 2024 10:51:51 +0000 Subject: [PATCH 4/4] GITBOOK-3: Add documentation about password protected pages --- the-basics/wordpress-controllers.md | 39 +++++++++++++++++++++++++++-- 1 file changed, 37 insertions(+), 2 deletions(-) diff --git a/the-basics/wordpress-controllers.md b/the-basics/wordpress-controllers.md index 570dae0..ef03862 100644 --- a/the-basics/wordpress-controllers.md +++ b/the-basics/wordpress-controllers.md @@ -2,7 +2,7 @@ ## Introduction -In the files \(i.e. controllers\) that WordPress uses when it matches a route \(e.g. `page.php`, `single.php`\), you can now use a class rather than writing procedural code. +In the files (i.e. controllers) that WordPress uses when it matches a route (e.g. `page.php`, `single.php`), you can now use a class rather than writing procedural code. ```php // page-home.php @@ -33,7 +33,7 @@ class PageHomeController **The name of the controller is important:** * It should be under the namespace `App`. -* The class name must be an UpperCamelCase version of the filename with the word `Controller` on the end \(without spaces, dashes and underscores\). If the controller name is not correctly Lumberjack will not throw any errors - instead you will just get a blank page. +* The class name must be an UpperCamelCase version of the filename with the word `Controller` on the end (without spaces, dashes and underscores). If the controller name is not correctly Lumberjack will not throw any errors - instead you will just get a blank page. The `handle` method will automatically be called on your controller. @@ -63,3 +63,38 @@ In WordPress, you have a `404.php` file. `PHP` Classes cannot start with a numbe Instead Lumberjack will look for a controller called `Error404Controller` +## Password protected pages + +{% hint style="info" %} +Since: v6.1.0 +{% endhint %} + +WordPress supports password protection for pages across your site. This is also [supported by Timber](https://timber.github.io/docs/v1/guides/wp-integration/#password-protected-posts) but requires you to implement it in each of your site's templates to take effect universally. + +To make this simpler to implement, Lumberjack adds a middleware to handle this across all page templates. When a request is made for a page that requires a password it will intercept the call and attempt to render the `single-password.twig` file instead. + +It is recommended that you implement the Twig file in line with what Timber suggests: + +```twig +{% raw %} +{% extends "base.twig" %} + +{% block content %} + {{ function('get_the_password_form') }} +{% endblock %} +{% endraw %} +``` + +{% hint style="info" %} +**Note:** If a `single-password.twig` file is **not found,** the middleware will fall back gracefully to the default behaviour, which is to **ignore the password functionality and render the page as normal**. +{% endhint %} + +### Changing the Twig file used for password protected pages + +If you would like to change the name of the Twig file that is used for password protection you can do so using the `lumberjack/password_protect_template` filter: + +```php +add_filter('lumberjack/password_protect_template', function() { + return 'my-password-template.twig'; +}); +```