Migrating to v3

Backwards compatibility has for the most part been maintained, but there are some changes that you should be aware of when migrating from v2 to v3.

Output Buffering Behavior (3.5.0)

Output buffering is the process where the output generated by a PHP script is stored in a buffer (internal to PHP) before being sent to the client. This allows you to modify the output before it is sent to the client.

In an MVC application, the Controller is the "manager" and it manages what the view does. Having output generated outside of the controller (or in Flights case sometimes an anonymous function) breaks the MVC pattern. This change is to be more in line with the MVC pattern and to make the framework more predictable and easier to use.

In v2, output buffering was handled in a way where it wasn't consistently closing it's own output buffer and which made unit testing and streaming more difficult. For the majority of users, this change may not actually affect you. However if you are echoing content outside of callables and controllers (for example in a hook), you likely are going to run into trouble. Echoing out content in hooks, and prior to the framework actually executing may have worked in the past, but it won't work moving forward.

Where you might have problems

// index.php
require 'vendor/autoload.php';

// just an example
define('START_TIME', microtime(true));

function hello() {
    echo 'Hello World';
}

Flight::map('hello', 'hello');
Flight::after('hello', function(){
    // this will actually be fine
    echo '<p>This Hello World phrase was brought to you by the letter "H"</p>';
});

Flight::before('start', function(){
    // things like this will cause an error
    echo '<html><head><title>My Page</title></head><body>';
});

Flight::route('/', function(){
    // this is actually just fine
    echo 'Hello World';

    // This should be just fine as well
    Flight::hello();
});

Flight::after('start', function(){
    // this will cause an error
    echo '<div>Your page loaded in '.(microtime(true) - START_TIME).' seconds</div></body></html>';
});

Turning on v2 Rendering Behavior

Can you still keep your old code the way it is without doing a rewrite to make it work with v3? Yes, you can! You can turn on v2 rendering behavior by setting the flight.v2.output_buffering configuration option to true. This will allow you to continue to use the old rendering behavior, but it is recommended to fix it moving forward. In v4 of the framework, this will be removed.

// index.php
require 'vendor/autoload.php';

Flight::set('flight.v2.output_buffering', true);

Flight::before('start', function(){
    // Now this will be just fine
    echo '<html><head><title>My Page</title></head><body>';
});

// more code

Dispatcher Changes (3.7.0)

If you have directly been calling static methods for Dispatcher such as Dispatcher::invokeMethod(), Dispatcher::execute(), etc. you will need to update your code to not directly call these methods. Dispatcher has been converted to be more object oriented so that Dependency Injection Containers can be used in an easier way. If you need to invoke a method similar to how Dispatcher did, you can manually use something like $result = $class->$method(...$params); or call_user_func_array() instead.

halt() stop() redirect() and error() Changes (3.10.0)

Default behavior before 3.10.0 was to clear both the headers and the response body. This was changed to only clear the response body. If you need to clear the headers as well, you can use Flight::response()->clear().