Nextcloud Syntax Controllers

nextcloud-syntax-controllers

Quick Reference

Controller Types

Route Definition Arrays (appinfo/routes.php)

Route Name Resolution

Parameter Extraction

Type Casting (via type hints or @param)

Security Attributes (NC 27+)

Default security posture (no attributes): admin-only, authenticated, 2FA required, CSRF validated.

Response Types

Critical Warnings

NEVER create controller methods without security attributes and assume they are public -- the default is admin-only. Explicitly add #[NoAdminRequired] for regular user access or #[PublicPage] for anonymous access.

NEVER use #[NoCSRFRequired] on state-changing endpoints without alternative protection -- either require the OCS-APIRequest: true header or use token-based authentication.

NEVER use #[PublicPage] + #[NoCSRFRequired] on state-changing endpoints without additional authentication -- this leaves the endpoint completely unprotected.

NEVER return a response without the correct HTTP status code -- use the Http::STATUS_* constants for clarity.

ALWAYS extend OCSController for OCS API endpoints -- using Controller with OCS routes will break the response envelope.

ALWAYS define routes in appinfo/routes.php -- controllers without routes are unreachable.

ALWAYS use constructor injection for dependencies -- Nextcloud auto-wires by type hint.

ALWAYS call $response->throttle() only on failure conditions when using #[BruteForceProtection] -- never on success.

Essential Patterns

Pattern 1: Page Controller with Template

namespace OCA\MyApp\Controller;

use OCP\AppFramework\Controller;
use OCP\AppFramework\Http\TemplateResponse;
use OCP\IRequest;

class PageController extends Controller {
    public function __construct(
        string $appName,
        IRequest $request,
        private MyService $service,
    ) {
        parent::__construct($appName, $request);
    }

    #[NoAdminRequired]
    #[NoCSRFRequired]
    public function index(): TemplateResponse {
        return new TemplateResponse($this->appName, 'main');
    }
}

// appinfo/routes.php
return [
    'routes' => [
        ['name' => 'page#index', 'url' => '/', 'verb' => 'GET'],
    ],
];

Pattern 2: OCS API Controller

namespace OCA\MyApp\Controller;

use OCP\AppFramework\Http\DataResponse;
use OCP\AppFramework\OCSController;
use OCP\IRequest;

class ItemApiController extends OCSController {
    public function __construct(
        string $appName,
        IRequest $request,
        private ItemService $service,
        private ?string $userId,
    ) {
        parent::__construct($appName, $request);
    }

    #[NoAdminRequired]
    public function index(): DataResponse {
        return new DataResponse($this->service->findAll($this->userId));
    }

    #[NoAdminRequired]
    public function show(int $id): DataResponse {
        return new DataResponse($this->service->find($id, $this->userId));
    }

    #[NoAdminRequired]
    public function create(string $title, string $content = ''): DataResponse {
        return new DataResponse(
            $this->service->create($title, $content, $this->userId)
        );
    }
}

// appinfo/routes.php
return [
    'ocs' => [
        ['name' => 'item_api#index', 'url' => '/api/v1/items', 'verb' => 'GET'],
        ['name' => 'item_api#show', 'url' => '/api/v1/items/{id}', 'verb' => 'GET'],
        ['name' => 'item_api#create', 'url' => '/api/v1/items', 'verb' => 'POST'],
    ],
];

Pattern 3: Resource Routes (Auto-CRUD)

// appinfo/routes.php
return [
    'resources' => [
        'author' => ['url' => '/authors'],
    ],
];

This auto-generates five routes mapping to AuthorController:

Pattern 4: Attribute-Based Routing (NC 29+)

use OCP\AppFramework\Http\Attribute\FrontpageRoute;
use OCP\AppFramework\Http\Attribute\ApiRoute;

class PageController extends Controller {

    #[NoAdminRequired]
    #[FrontpageRoute(verb: 'GET', url: '/')]
    public function index(): TemplateResponse {
        return new TemplateResponse($this->appName, 'main');
    }
}

class ItemApiController extends OCSController {

    #[NoAdminRequired]
    #[ApiRoute(verb: 'GET', url: '/api/v1/items')]
    public function index(): DataResponse {
        return new DataResponse($this->service->findAll());
    }
}

Pattern 5: Error Handling with Status Codes

use OCP\AppFramework\Http;
use OCP\AppFramework\Http\JSONResponse;

#[NoAdminRequired]
public function show(int $id): JSONResponse {
    try {
        return new JSONResponse($this->service->find($id, $this->userId));
    } catch (NotFoundException $e) {
        return new JSONResponse([], Http::STATUS_NOT_FOUND);
    } catch (ForbiddenException $e) {
        return new JSONResponse(['message' => $e->getMessage()], Http::STATUS_FORBIDDEN);
    }
}

Pattern 6: Complete routes.php with All Three Arrays

<?php
return [
    'routes' => [
        ['name' => 'page#index', 'url' => '/', 'verb' => 'GET'],
        ['name' => 'page#settings', 'url' => '/settings', 'verb' => 'GET'],
        [
            'name' => 'file#download',
            'url' => '/files/{path}',
            'verb' => 'GET',
            'requirements' => ['path' => '.+'],  // match slashes in path
        ],
        [
            'name' => 'page#list',
            'url' => '/list',
            'verb' => 'GET',
            'defaults' => ['page' => 1, 'limit' => 20],
        ],
    ],
    'ocs' => [
        ['name' => 'api#getData', 'url' => '/api/v1/data', 'verb' => 'GET'],
        ['name' => 'api#updateData', 'url' => '/api/v1/data/{id}', 'verb' => 'PUT'],
    ],
    'resources' => [
        'author' => ['url' => '/authors'],
    ],
];

Responder System (Format Negotiation)

Priority order for response format:

1. ?format=xml or ?format=json query parameter (highest)
2. Accept HTTP header
3. Default: json

OCSController handles this automatically -- DataResponse is rendered as JSON or XML based on negotiation.

For custom formats, register a responder:

class MyController extends Controller {
    public function __construct(string $appName, IRequest $request) {
        parent::__construct($appName, $request);
        $this->registerResponder('xml', function ($data) {
            return new XMLResponse($data);
        });
    }
}

URL Generation

use OCP\IURLGenerator;

// Route URL: /index.php/apps/myapp/authors/3
$url = $urlGenerator->linkToRoute('myapp.author.show', ['id' => 3]);

// OCS route URL: /ocs/v2.php/apps/myapp/api/v1/data
$url = $urlGenerator->linkToOCSRoute('myapp.api.getData');

Route name format: {appid}.{controller}.{method} where hashes become dots and underscores are preserved.

Reference Links

• references/methods.md -- Controller types, route syntax, response types, parameter extraction
• references/examples.md -- Controller patterns, routing patterns
• references/anti-patterns.md -- Controller mistakes

Official Sources

• https://docs.nextcloud.com/server/latest/developer_manual/digging_deeper/controllers.html
• https://docs.nextcloud.com/server/latest/developer_manual/basics/routing.html
• https://docs.nextcloud.com/server/latest/developer_manual/digging_deeper/middleware.html