Creating Controllers

A controller is a class that derives from mach::ControllerBase and groups related actions under a common route.

Define a Controller

Create a controller class for the part of your application you want to handle:

class UsersController final : public mach::ControllerBase {
public:
    inline static constexpr std::string_view route = "/users";

    mach::Reply<> index() {
        return noContent();
    }

    static void configure(mach::ControllerBuilder<UsersController>& builder) {
        builder.mapGet("/", &UsersController::index);
    }
};

Every controller defines a base route. Routes mapped by the controller are relative to that base route.

In this example, the controller route is:

/users

and the index action is mapped to:

/

Together, they handle:

GET /users/

Keeping configure() at the end of the class leaves the controller’s actions together and makes the route configuration easy to find.

ControllerBuilder

The configure() function receives a mach::ControllerBuilder specialized for the controller:

static void configure(mach::ControllerBuilder<UsersController>& builder) {
    builder.mapGet("/", &UsersController::index);
}

ControllerBuilder connects controller actions to HTTP methods and routes.

The controller type is supplied as the template argument:

mach::ControllerBuilder<UsersController>

This allows the builder to map routes directly to member functions of UsersController, such as:

builder.mapGet("/", &UsersController::index);

The route passed to the builder is relative to the controller’s base route.

You will take a closer look at action mapping in the next guide.

Generate a Controller

The Mach CLI can create the controller file for you.

Run:

mach generate controller users

Mach generates a UsersController in your project’s controllers directory.

Controller names are normalized automatically, so you can provide either a resource name or a controller name:

Input	Generated controller
users	UsersController
usersController	UsersController
USERS	UsersController

Tip

You can use mach g c users as a shorter alias for mach generate controller users.

Register the Controller

A controller must be registered with the application builder:

mach::AppBuilder builder;

builder.addController<UsersController>();

auto app = builder.build();

Registered controllers are configured when the application is built. Controllers that are not registered are not included in the application.

Tip

Keep controllers focused on a single area of your application. A UsersController, for example, should contain user-related actions rather than unrelated application logic.

Organizing Controller Files

A typical project keeps controllers in a dedicated directory:

src/
└── controllers/
    └── UsersController.hpp

This keeps controller definitions separate from application startup and makes larger applications easier to navigate.

---

Next, you’ll learn how to define and map controller actions.