Routing

HTTP routing

Turn URLs into application behavior with a tiny, readable router.

Leaf routes define the URL, HTTP method, and handler for each request. The API stays small enough to read quickly, while still supporting named routes, redirects, 404 handling, dynamic routes, middleware, groups, and MVC controllers.

routes/index.php

app()->get('/home', function () {

return response()->json(['ok' => true]);

});

Routing covers

Methods

GET, POST, PUT, PATCH, DELETE, and multi-method routes.

Flow

Names, redirects, current route data, custom 404s, and middleware.

AI context

Routes are one of the first maps assistants use to understand an app.

Create a route

Route → Controller → Response

Building with Leaf MVC? Keep routes thin and move application logic into controllers.

MVC routing →

Every route has a URL (the web address the user visits) and an HTTP method (like GET, POST, etc.), which tells the server what action to take. For example, if you create a route for a GET request to /home, the user can access that page by visiting http://example.com/home. This way, different URLs and methods control how users interact with your app.

So to define a route, you need to specify the URL and the HTTP method. Leaf router allows you to do this using get(), post(), put(), patch(), delete(), ... methods. Let's take a look at them.

Create a GET route

You can add a route that handles only GET HTTP requests with the Leaf router's get() method. It accepts two arguments:

• The route pattern
• The route handler

app()->get('/home', function () {
  // your code
});

Create a POST route

You can add a route that handles only POST HTTP requests with the Leaf router's post() method. It accepts two arguments:

• The route pattern
• The route handler

app()->post('/users/add', function () {
  $user = request()->get('user');
  // create a new user
});

Create a PUT route

The put() method allows you to add a route that handles only PUT HTTP requests. It accepts two arguments:

• The route pattern
• The route handler

app()->put('/book/edit/{id}', function ($id) {
  // your code
});

Create a DELETE route

You can add a route that handles only DELETE HTTP requests with the Leaf router's delete() method. It accepts two arguments:

• The route pattern
• The route handler

app()->delete('/quotes/{id}', function ($id) {
  // delete quote
});

Create a PATCH route

You can add a route that handles only PATCH HTTP requests with the Leaf router's patch() method. It accepts two arguments:

• The route pattern
• The route handler

app()->patch('/quotes/{id}', function ($id) {
  // update quote
});

Create a multiple method route

There are some cases where you want a route to handle multiple HTTP methods. You can do this using the match() method. This method accepts three arguments:

• A list of HTTP methods separated by | (pipe)
• The route pattern
• The route handler

app()->match('GET|POST', '/users', function () {
  // your code
});

Create a view route

If your route needs to return a template without any logic, you can use the view() method. This method accepts two arguments:

• The route pattern
• The view file to render

app()->view('/home', 'home');

The view() method will look for the view file using whatever view engine you have set up in your app. For instance, if you have blade setup, it will look for a file called home.blade.php. The template location also depends on your view engine setup.

Running your routes

After defining all the routes you application needs, you need to start the router to listen for incoming requests. You can do this by calling the run() method.

app()->run();

Handling 404

Leaf displays a default 404 screen when it can't find a page that a user wants to access in your app, however this page may not match your app's design or you may want to return JSON instead of HTML.

You can customize the 404 page using Leaf's set404() method.

app()->set404(fn () => response()->json([
  "error" => "Page not found"
]));

Once this is set, Leaf will automatically use your custom 404 page when a user tries to access a page that doesn't exist in your app.

Named routes

In big applications, you might have to reference a route over and over again. When you change the route URL, you'll have to change it everywhere you referenced it.

To avoid this, you can name your routes and reference them by their name. This will save you a lot of time and prevent errors.

Leaf router allows you name routes by using route params. They allow you add extra options to your routes like a route name, middleware, etc. You can set route options by passing an array with configuration options as the second argument to the whatever route you are working on.

app()->get('/home', ['name' => 'home', function () {
  // your code
}]);

You can then redirect to this route using the route name by passing an array with the route name to the redirect() method.

response()->redirect(['home']);

Route groups can carry a name too, which prefixes every named route inside (admin + dashboard → admin.dashboard), and resource routes name themselves automatically. See named groups.

To build a URL from a route name (for links, redirects, or anywhere you'd otherwise hardcode a path), use the route() method. Parameters fill in the route's placeholders:

$url = app()->route('home');                     // /home
$url = app()->route('users.show', ['id' => 5]);  // /users/5

(If you need the full details of the current route, like its pattern, name, method, and handler, that's getRoute(), shown below.)

Getting the current route

There are times when you need to get the current route which the user is visiting from inside your route handler. You can do this by calling the getRoute() method on the router instance.

app()->get('/home', ['name' => 'home', function () {
  $route = app()->getRoute();
  echo $route['name'];
}]);

This method returns an array containing the following information:

• pattern: The route pattern
• path: The route path
• name: The route name
• method: The route method
• handler: The route handler
• params: Dynamic route parameters

Navigating to another route

There are times when you need to redirect users to another route. For example, after a user logs in, you might want to redirect them to their dashboard. You can do this by calling the redirect() method on the response instance.

response()->redirect('/login');

If your route has a name, you can navigate to it by passing the route name in an array to the redirect() method.

response()->redirect(['home']);