Migration Guide #

This guide is primarily for users with prior Leaf 2 experience who want to learn about the new features and changes in Leaf 3. This is not something you have to read from top to bottom before trying out Leaf 3. While it looks like a lot has changed, a lot of what you know and love about Leaf is still the same; but we wanted to be as thorough as possible and provide detailed explanations and examples for every documented change.

• Quickstart
• Breaking Changes
• Notable New Features

Quickstart #

If you want to quickly try out Leaf 3 in a new project, create a folder and run:

composer require leafs/leaf

This will quickly setup a leaf 3 with the default modules. From there, create your index.php file and add this quickstart.

<?php

require __DIR__ . "/vendor/autoload.php";

app()->get("/", function () {
  response()->json(["name" => "Leaf"]);
});

app()->run();

<?php

require __DIR__ . "/vendor/autoload.php";

$app = new \Leaf\App();

$app->get("/", function () use($app) {
  $app->response()->json(["name" => "Leaf"]);
});

$app->run();

You can run this with the built in php server

php -S localhost:5500

Alternatively, you can use the Leaf CLI:

leaf create <app-name>

And run the sample app with:

leaf serve

Migrating from leaf 2 #

As mentioned before, we've made leaf 3 as backwards compatible with Leaf 2.5+ as possible. This means that moving from v2 to v3 will be a breeze or close.

• Install leaf 3

composer require leafs/leaf

Or with leaf CLI

leaf install leaf

• After this, it's just a matter of installing the modules required in your project. For example, if you use Leaf\Auth, you will need to install the auth module. This can be done with:

leaf install auth

Or with composer:

composer require leafs/auth

Just do this for all other modules in your project. And your app should be back online, working even faster than before.

Breaking Changes #

The following consists a list of breaking changes from 2.x:

Modules #

Leaf 3 only retains the core of the framework with a few utilities, all other features were packaged as modules. This means that you will have errors if you try to use some packages like Leaf\Auth or Leaf\Flash without installing them first.

This is not really a problem since installing the module will automatically fix any problems that came along with it's abscence.

CORS #

In v2, some basic cors configuration was available on the Leaf object, however, this has been discontinued and replaced with the Cors module. This module contains both basic and advanced CORS configurations and is inspired by the ExpressJS cors package. So if you have any experience with that library, you will have no problems using the leaf cors module.

To fix any problems with cors in your Leaf 2 app, follow these steps:

• Install the cors module

composer require leafs/cors

• Replace the original cors configuration with the cors module. (This is done under the hood for you, all you need to do now call the cors method on your leaf app)

$app = new Leaf\App;

$app->evadeCors(true);

// ...

$app = new Leaf\App;

$app->cors();

// ...

app()->evadeCors(true);

// ...

app()->cors();

// ...

The cors method is automatically linked to the cors module by Leaf and so, no extra configuration is needed to make it work. Cors takes in some optional configuration, checkout the cors module docs. Also cors is no longer available on the response object.

Router #

Leaf\Router::getRequestMethod has been been moved to Leaf\Http\Request::getMethod. This is used in Leaf's core and should not be an issue, but if you do have references to this function, changing it to Leaf\Http\Request::getMethod will fix any errors.

Notable New Features #

Some of the new features to keep an eye on in Leaf 3 include:

• Global functions
• CORS module