Skip to content

Adding a New Resource

Below is a minimal mod that adds a widgets resource.

1. Mod entry point

Integration.php
<?php declare(strict_types=1);

namespace Vendor\Widgets;

if (! defined('SMF'))
    die('No direct access...');

class Integration
{
    public function hooks(): void
    {
        // Your own autoloader, so SMF can find the mod's classes.
        add_integration_function('integrate_autoload', self::class . '::autoload#', false);
        add_integration_function('integrate_api_routes', self::class . '::routes#', false);
    }

    public function autoload(array &$classMap): void
    {
        $classMap['Vendor\\Widgets\\'] = 'Widgets/';
    }

    // routes() is shown in the next section
}

2. Registering routes

The integrate_api_routes handler receives a Router object with the fluent methods get(), post(), put(), patch(), delete(). The {id} segment (or any {name}) is placed into the action's parameter array.

routes
<?php declare(strict_types=1);

use SMF\API\Router;

// ...

public function routes(Router $router): void
{
    $router->get('widgets', WidgetController::class, 'index');
    $router->get('widgets/{id}', WidgetController::class, 'show');
    $router->post('widgets', WidgetController::class, 'store');
}

The path parameters arrive as strings; validate them with $this->id($params) before using them in a query. Besides the verb helpers, Router::add($method, $pattern, $class, $action) registers a route for any other verb.

Version prefix

Routes are registered without a version prefix. The leading version segment (v1) is stripped and validated by the Router itself, so the patterns stay version-agnostic. The client addresses the resource as index.php?action=api&path=v1/widgets.

Nested collections and reserved parameters

Register "child" lists under the parent — parent/{parent_id}/children, not through a query filter. Examples from the core API: GET boards/{board_id}/topics, GET categories/{cat_id}/boards, GET topics/{topic_id}/posts. The reason is not just style: the names board, topic, msg, start, action are SMF's reserved query parameters. If you pass ?board=5, the core will treat the request as a board view during loadBoard() and return an HTML page — it will never reach action=api. The parent identifier in the path ({parent_id}) avoids this collision; read it with $this->id($params, 'parent_id').

3. Controller

The controller extends SMF\API\Controllers\AbstractController and gets a ready-made "harness": access to the request, a response factory, the Query builder, pagination, and id validation.

WidgetController.php
<?php declare(strict_types=1);

namespace Vendor\Widgets;

use SMF\API\ApiException;
use SMF\API\Query;
use SMF\API\Response;
use SMF\API\Controllers\AbstractController;

if (! defined('SMF'))
    die('No direct access...');

class WidgetController extends AbstractController
{
    public function index(array $params): Response
    {
        $query = (new Query())
            ->from('{db_prefix}widgets AS w')
            ->where('w.hidden = {int:hidden}')
            ->columns('w.id_widget, w.name')
            ->orderBy('w.name')
            ->params(['hidden' => 0]);

        // Every row passes through transform();
        // a collection with pagination meta is returned.
        return $this->paginate($query);
    }

    public function show(array $params): Response
    {
        // id($params) validates {id}
        $row = $this->first(
            (new Query())
                ->from('{db_prefix}widgets')
                ->where('id_widget = {int:id}')
                ->columns('id_widget, name')
                ->params(['id' => $this->id($params)])
        );

        if ($row === null) {
            throw ApiException::notFound('Widget not found');
        }

        return $this->response()->data($this->transform($row));
    }

    protected function transform(array $row): array
    {
        return [
            'id'   => (int) $row['id_widget'],
            'name' => $row['name'],
        ];
    }
}

See Query & Controller for the full reference of Query and AbstractController helpers.

What a controller action returns

An action should return a Response — $this->response()->data(...) for a single resource, $this->paginate($query) for a collection, $this->noContent() for an empty 204. A plain array works too: the router wraps it into data. Anything you throw as an ApiException becomes a JSON error with the matching status code.