Upgrade Guide

Website Rareloop Timber Documentation Twig Documentation
Search…
Upgrade Guide
Upgrading to v5.0 from v4.4
We migrated away from the deprecated Zend Diactoros package to the replacement Laminas Diactoros and also took the opportunity to upgrade to v2.
This migration introduces new default namespaces but also includes a bridge package that creates aliases meaning there should be no need to upgrade namespaces in any of your app code. We plan to migrate all the namespaces used internally by Lumberjack in a future major release.
The upgrade to v2 of Diactoros also adds some additional typehints to some of their classes. We expect that for most apps these will not cause any issues. If however you have extended any of the core Diactoros classes, you may need to add additional typehints and return types to some methods. More information on what has changed in Diactoros can be found here.
Upgrading to v4.4 from v4.3
There is nothing that requires upgrading between these versions.
Upgrading to v4.3 from v4.2
There is nothing that requires upgrading between these versions.
Upgrading to v4.2 from v4.1
We aim to document all the changes that could impact your theme, and there may only be a portion that are applicable to your theme.
Extending controllers
Create app/Http/Controllers/Controller.php  with the following contents:
1
<?php
2
​
3
namespace App\Http\Controllers;
4
​
5
use Rareloop\Lumberjack\Http\Controller as BaseController;
6
​
7
class Controller extends BaseController
8
{
9
​
10
}
Copied!
In all of your controllers, extend from this new base controller. For example:
1
/**
2
 * The Template for displaying all single posts
3
 */
4
​
5
namespace App;
6
​
7
use App\Http\Controllers\Controller;
8
// ...
9
​
10
class SingleController extends Controller
11
{
Copied!
Here are the list of controllers that come out of the box:
404.php
archive.php
author.php
index.php
page.php
search.php
single.php
Upgrading to v4.1 from v4.0
There is nothing that requires upgrading between these versions.
Upgrading to v4 from v3
We aim to document all the changes that could impact your theme, and there may only be a portion that are applicable to your theme.
Composer
Update lumberjack-core to version 4.
1
"rareloop/lumberjack-core": "^4.0"
Copied!
PHP Version
Likelihood Of Impact: High
Support for PHP 7.0 has been dropped, ensure you're running at least PHP 7.1.
Service Providers
Likelihood Of Impact: Critical
Add the following providers to config/app.php:
1
'providers' => [
2
    ...
3
    Rareloop\Lumberjack\Providers\QueryBuilderServiceProvider::class,
4
    Rareloop\Lumberjack\Providers\SessionServiceProvider::class,
5
    Rareloop\Lumberjack\Providers\EncryptionServiceProvider::class,
6
],
Copied!
The query builder is now part of the core, rather than an external package. If you were using the package, you will need to remove its service provider from your list of providers above.
Exception Handler
Likelihood Of Impact: Critical
The type hint on the render() function has changed to the PSR interface from the concrete Zend implementation.
Make the following change in app/Exceptions/Handler.php:
From:
1
use Zend\Diactoros\ServerRequest;
2
​
3
public function render(ServerRequest $request, Exception $e) : ResponseInterface
4
{
5
​
6
}
Copied!
To:
1
use Psr\Http\Message\ServerRequestInterface;
2
​
3
public function render(ServerRequestInterface $request, Exception $e) : ResponseInterface
4
{
5
​
6
}
Copied!
No changes should be required to your application logic as Zend subclasses will already comply with the new interface.
Container
Likelihood Of Impact: Medium
The bind() method on the Application container is no longer a singleton by default when the value (2nd param) is not a primitive or object instance.
When binding a concrete implementation to an interface, using singletons by default can create unexpected side affects as state is maintained across instances.
A new singleton() method has been provided to enable the previous behaviour. This enables the app developer to be more intentional about the behaviour they desire.
For example:
1
// Singleton
2
$app->singleton(App\AppInterface::class, App\AppImplementation::class);
3
$object1 = $app->get(App\AppInterface::class);
4
$object2 = $app->get(App\AppInterface::class);
5
​
6
// The same object is resolved from the container
7
$object1 === $object2; // true
8
​
9
// Bind
10
$app->bind(App\AppInterface::class, App\AppImplementation::class);
11
$object1 = $app->get(App\AppInterface::class);
12
$object2 = $app->get(App\AppInterface::class);
13
​
14
// The container resolves new instances, so the objects are not the same
15
$object1 === $object2; // false
Copied!
Using the Container
ServerRequest class (optional)
Likelihood Of Impact: Optional, but recommended
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:
1
Rareloop\Lumberjack\Http\ServerRequest
Copied!
For example:
1
use Rareloop\Lumberjack\Http\ServerRequest;
2
​
3
class MyController
4
{
5
    public function show(ServerRequest $request)
6
    {
7
        $name = $request->input('name');
8
    }
9
}
Copied!
If you have enabled global helpers, you can use access the current ServerRequest instance using the request()helper instead of using dependency injection. For example:
1
class MyController
2
{
3
    public function show()
4
    {
5
        $name = $request->input('name');
6
    }
7
}
Copied!
Here's a quick overview of what the new ServerRequest object can do. If you are using global helpers, you can replace $request with request() instead in the examples below:
Query Parameters
1
// Get all query parameters
2
$request->query();
3
​
4
// Get a specific query parameter
5
$request->query('name');
6
​
7
// Get a specific query parameter with a default
8
$request->query('name', 'Jane');
Copied!
Input
1
// Get all input params (from $_GET and $_POST)
2
$request->input();
3
​
4
// Get a specific input parameter
5
$request->input('name');
6
​
7
// Get a specific input parameter, with a default
8
$request->input('name', 'Jane');
9
​
10
// Check if the request has a key
11
$request->has('name');
Copied!
HTTP Requests
View Models
Likelihood Of Impact: Medium
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.
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
The ViewModel base class no longer extends from stdClass and so can no longer have arbitrary properties set on it.
We'd suggest upgrading your existing ViewModels to either use public methods or public properties. If your project has a large number of ViewModel's, the simplest change is to specifically name all properties in the class.
For example:
1
// Lumberjack v3
2
use Rareloop\Lumberjack\ViewModel;
3
​
4
class MyViewModel extends ViewModel
5
{
6
    public function __construct($post)
7
    {
8
        $this->title = $post->title;
9
        $this->link = $post->link;
10
    }
11
}
Copied!
To:
1
// Lumberjack v4
2
use Rareloop\Lumberjack\ViewModel;
3
​
4
class MyViewModel extends ViewModel
5
{
6
    // Declare the class properties
7
    public $title;
8
    public $link;
9
​
10
    public function __construct($post)
11
    {
12
        $this->title = $post->title;
13
        $this->link = $post->link;
14
    }
15
}
Copied!
Binding of the Exception Handler
Likelihood Of Impact: Very low
In bootstrap/app.php you should change how the exception handler is bound to Rareloop\Lumberjack\Exceptions\HandlerInterface.
From:
1
$app->bind(HandlerInterface::class, $app->make(Handler::class));
Copied!
To:
1
$app->singleton(HandlerInterface::class, Handler::class);
Copied!
Helpers::app() helper
Likelihood Of Impact: Very low
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:
1
Helpers::app(MyClassName::class);
Copied!
To:
1
Helpers::app()->make(MyClassName::class);
Copied!
Router class namespace
Likelihood Of Impact: Very low
If you resolve an instance of the Router class from the container, you'll need to change the class reference.
If you're just using the Router Facade, you do not need to change anything.
From:
1
use Rareloop\Router\Router
Copied!
To:
1
Rareloop\Lumberjack\Http\Router
Copied!
PSR-15 Middleware
Likelihood Of Impact: Very low
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.