Controllers and Routing

// 1. the file is included by path, never autoloaded
include CONTROLLER_DIR . $surface . DS . $controller . '.php';

// 2. the class name is tried in this order (separators removed, case-insensitive)
//    \WISECP\controllers\{surface}\{name}   ->   {Name}Controller   ->   Controller

// 3. the name and the route key are published before construction
Controllers::$cname = $controller;      // "widgets"
Controllers::$rkey  = $route_key;       // the route entry that matched

// 4. params are assigned AFTER the constructor, unless the constructor declares one
$this->controller = new $className();
$this->controller->params = $params;

// 5. entry point: index() wins, main() is the fallback
$content = method_exists($this->controller, 'index')
    ? $this->controller->index()
    : $this->controller->main();

// page_{segment}[_{subsegment}[_{subsegment}]] - dashes and dots become underscores
public function page_list(&$links, &$meta, &$breadcrumbs): string;

// one operation method per registered operation name
public function save_widget(Operation $operation): bool;

public Models $model;                    // constructed for you, by name
public View $view;
public array $params = [];               // URL segments after the controller
public array $data = [];                 // what the template receives
public array $operations = [];           // the registration table
public bool $loggedIn = false;
public bool $loginControl = false;
public static string|int $cname = '';    // controller name
public static string|int $rkey  = '';    // matched route key
public static array $rparams = [];       // the matched route's params, slug INCLUDED

public function addData($k = '', $v = ''): void;
public function getData($key);
public function takeDatas($which = []): void;
public function set_predefined_data(string $type = 'client', array $meta = [], array $breadcrumbs = [], array $links = []): void;
public function operation(string $name = '', array $operations = []): bool;
public function checkLogin(bool $redirect = true): bool;
public function client_gate(bool $requireComplete = true): ?string;
public function page_404($type = 'admin'): string;
public function page_denied(string $scope = ''): string;
public function CRLink($r_key = '', $params = [], $slang = ''): string|bool;
public function AdminCRLink($r_key = '', $params = [], $slang = ''): string|bool;
public function RouteURI($params = [], $key = null, $slang = '', $admin = false): string;
public function ControllerURI(): string;
protected function localize_lang_links(string $routeKey, array $slugByLang): void;

public function __construct()
{
    parent::__construct();

    $this->operations = array_merge($this->operations, [
        // 'privileges' => string[]  privilege keys, ALL of which the session must hold
        // 'method'     => string    the method to call, when it is not the operation name
        'save_widget' => ['privileges' => ['WIDGETS_OPERATION']],
        'delete'      => ['privileges' => ['WIDGETS_OPERATION'], 'method' => 'delete_widget'],
        'view_detail' => ['privileges' => ['WIDGETS_LOOK', 'WIDGETS_OPERATION']],
    ]);
}

// coremio/classes/Controllers.php reads exactly those two keys:
private function run_operation(string $name = '', array $properties = []): bool;
//   $method     = $properties["method"]     ?? $name;
//   $privileges = $properties["privileges"] ?? [];
//   if ($privileges && !Admin::isPrivilege($privileges)) throw new Exception(...);

// Router: instance methods, reached through Router::getInstance()
public static function getInstance(array $routes = []): self;
public function get(string $url): ?array;          // ['key' => string, 'controller' => string|callable, 'params' => array] or null
public function add(string $name, string $pattern, string|array|callable $handler): void;
public function generate(string $name, array $params = []): ?string;
public function matchController(array $params): string;   // controller name, or '' when the slug resolves to nothing
public function findRoute($controller, $params): bool;    // memoized slug lookup in the *_lang tables
public function setRoutes(array $routes): self;
public function setLang($lang): self;
public function getRoutes(): array;

// LinkGenerator: static
public static function admin($route = '', $params = [], $lang = '', $wqs = []): string|bool;
public static function client($route = '', $params = [], $lang = '');
public static function wQS(string|bool|null $url, array|string $params = []): string;
public static function convert_to_link(string $arg): string;

namespace WISECP\controllers\admin;

use Controllers;
use Filter;
use Language;
use LinkGenerator;
use WISECP\Operations\AdminWidgets;

class widgets extends Controllers
{
    use AdminWidgets;                    // the operation methods live in this trait

    public function __construct()
    {
        parent::__construct();
        $this->checkLogin();

        $this->operations = array_merge($this->operations, [
            'save_widget' => ['privileges' => ['WIDGETS_OPERATION']],
        ]);
    }

    public function main()
    {
        if ($operation = Filter::init("REQUEST/operation", "route")) return $this->operation($operation);

        $page        = $this->params[0] ?? 'list';
        $links       = ['controller' => LinkGenerator::admin("widgets")];
        $meta        = ['title' => Language::gc("admin/widgets/page-list")];
        $breadcrumbs = [
            ['link' => LinkGenerator::admin("dashboard"), 'title' => Language::gc("admin/index/breadcrumb-name")],
            ['link' => null, 'title' => Language::gc("admin/widgets/breadcrumb-list")],
        ];

        $method = "page_" . str_replace(["-", "."], "_", $page);
        if (method_exists($this, $method) && ($out = $this->$method($links, $meta, $breadcrumbs))) return $out;

        // Mind the order: links is the LAST argument here, the FIRST one above.
        $this->set_predefined_data("admin", $meta, $breadcrumbs, $links);

        return $this->view->chose("admin")->render("widgets/" . $page, $this->data, true);
    }

    public function page_list(&$links, &$meta, &$breadcrumbs): string
    {
        $this->addData("rows", $this->model->list(false, [], ['id' => 'DESC'], 0, 25));
        $this->addData("clink", $links["controller"]);

        return '';                       // main() renders templates/admin/widgets/list.php
    }
}

<?php /* $rows and $clink arrive from addData(); $meta and $breadcrumb from set_predefined_data() */ ?>
<ul>
<?php foreach ($rows as $row): ?>
    <li><a href="<?= $clink ?>/detail/<?= (int) $row['id'] ?>"><?= htmlspecialchars($row['title'] ?? '') ?></a></li>
<?php endforeach; ?>
</ul>