MDL-87671 core: New section routing parameter

.upgradenotes/MDL-87671-2026020509381268.yml

@@ -0,0 +1,5 @@
+issueNumber: MDL-87671
+notes:
+  core:
+    - message: A new path_section parameter type for routing has been created
+      type: improved

public/lib/classes/router/parameters/path_section.php

@@ -0,0 +1,98 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace core\router\parameters;
+
+use core\exception\not_found_exception;
+use core\param;
+use core\router\schema\example;
+use core\router\schema\parameters\mapped_property_parameter;
+use core\router\schema\referenced_object;
+use Psr\Http\Message\ServerRequestInterface;
+
+/**
+ * A parameter representing a section in the path.
+ *
+ * @package    core
+ * @copyright  2026 Amaia Anabitarte <[email protected]>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class path_section extends \core\router\schema\parameters\path_parameter implements
+    mapped_property_parameter,
+    referenced_object
+{
+    /**
+     * Create a new path_section parameter.
+     *
+     * @param string $name The name of the parameter to use for the section identifier
+     * @param mixed ...$extra Additional arguments
+     */
+    public function __construct(
+        string $name = 'section',
+        ...$extra,
+    ) {
+        $extra['name'] = $name;
+        $extra['type'] = param::RAW;
+        $extra['description'] = <<<EOF
+        The section identifier.
+
+        This can be the id of the section.
+        EOF;
+        $extra['examples'] = [
+            new example(
+                name: 'A section id',
+                value: 54,
+            ),
+        ];
+
+        parent::__construct(...$extra);
+    }
+
+    #[\Override]
+    public function add_attributes_for_parameter_value(
+        ServerRequestInterface $request,
+        string $value,
+    ): ServerRequestInterface {
+        $section = $this->get_section_for_value($value);
+        return $request
+            ->withAttribute($this->name, $section)
+            ->withAttribute("coursecontext", \context_course::instance($section->course));
+    }
+
+    /**
+     * Get the section object for the given identifier.
+     *
+     * @param string $value A section id
+     * @return object
+     * @throws not_found_exception If the section cannot be found
+     */
+    protected function get_section_for_value(string $value): mixed {
+        global $DB;
+
+        $data = false;
+
+        if (is_numeric($value)) {
+            $data = $DB->get_record('course_sections', [
+                'id' => $value,
+            ]);
+        }
+        if ($data) {
+            return $data;
+        }
+
+        throw new not_found_exception('course_sections', $value);
+    }
+}

public/lib/tests/router/parameters/path_section_test.php

@@ -0,0 +1,68 @@
+<?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+namespace core\router\parameters;
+
+use core\exception\not_found_exception;
+use core\tests\router\route_testcase;
+use GuzzleHttp\Psr7\ServerRequest;
+use stdClass;
+
+/**
+ * Tests for the Section Path parameter.
+ *
+ * @package    core
+ * @copyright  Amaia Anabitarte <[email protected]>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @covers     \core\router\parameters\path_section
+ */
+final class path_section_test extends route_testcase {
+    public function test_section_id(): void {
+        $this->resetAfterTest();
+
+        $course = $this->getDataGenerator()->create_course();
+        $modinfo = get_fast_modinfo($course);
+        $section = $modinfo->get_section_info(1);
+        $context = \context_course::instance($course->id);
+
+        $param = new path_section();
+        $request = new ServerRequest('GET', '/course/sections/' . $section->id . '/restricted');
+        $newrequest = $param->add_attributes_for_parameter_value($request, $section->id);
+
+        $this->assertInstanceOf(stdClass::class, $newrequest->getAttribute('section'));
+        $this->assertInstanceOf(\core\context\course::class, $newrequest->getAttribute('coursecontext'));
+
+        $this->assertEquals($section->id, $newrequest->getAttribute('section')->id);
+        $this->assertEquals($context->id, $newrequest->getAttribute('coursecontext')->id);
+    }
+
+    /**
+     * Tests for when a section was not found.
+     */
+    public function test_section_not_found(): void {
+        $this->resetAfterTest();
+
+        $param = new path_section();
+
+        $course = $this->getDataGenerator()->create_course();
+        $sectionid = 9999;
+
+        $request = new ServerRequest('GET', '/course/sections/' . $sectionid . '/restricted');
+
+        $this->expectException(not_found_exception::class);
+        $param->add_attributes_for_parameter_value($request, $sectionid);
+    }
+}