From bea8eca255a477bc22b4fd9a5f70a6bf6df8acae Mon Sep 17 00:00:00 2001 From: Josh Date: Mon, 1 Jun 2026 09:25:19 -0400 Subject: [PATCH 1/3] docs(App): drop/update outdated OCP\AppFramework\App docblocks Signed-off-by: Josh --- lib/public/AppFramework/App.php | 63 +++++++++++++-------------------- 1 file changed, 25 insertions(+), 38 deletions(-) diff --git a/lib/public/AppFramework/App.php b/lib/public/AppFramework/App.php index b012e93bce894..7aac5f0456e2e 100644 --- a/lib/public/AppFramework/App.php +++ b/lib/public/AppFramework/App.php @@ -18,10 +18,16 @@ use Psr\Log\LoggerInterface; /** - * Class App + * Public base class for AppFramework applications. + * + * Provides access to the app container and a convenience dispatch() method + * for routing requests to controllers. + * + * Apps using the AppFramework typically extend this class to register + * services and dispatch controller actions. + * + * @see https://docs.nextcloud.com/server/latest/developer_manual/app_development/bootstrap.html * - * Any application must inherit this call - all controller instances to be used are - * to be registered using IContainer::registerService * @since 6.0.0 */ class App { @@ -29,13 +35,11 @@ class App { private $container; /** - * Turns an app id into a namespace by convention. The id is split at the - * underscores, all parts are CamelCased and reassembled. e.g.: - * some_app_id -> OCA\SomeAppId - * @param string $appId the app id - * @param string $topNamespace the namespace which should be prepended to - * the transformed app id, defaults to OCA\ - * @return string the starting namespace for the app + * Returns the app namespace for the given app ID. + * + * @param string $appId the app ID + * @param string $topNamespace the namespace prefix to substitute for OCA\ + * @return string the app namespace * @since 8.0.0 * @deprecated 34.0.0 use IAppManager::getAppNamespace */ @@ -44,8 +48,10 @@ public static function buildAppNamespace(string $appId, string $topNamespace = ' } /** - * @param string $appName - * @param array $urlParams an array with variables extracted from the routes + * Creates or retrieves the app container for the given app. + * + * @param string $appName the app ID + * @param array $urlParams route parameters to make available in the request container * @since 6.0.0 */ public function __construct(string $appName, array $urlParams = []) { @@ -97,6 +103,8 @@ public function __construct(string $appName, array $urlParams = []) { } /** + * Returns the app container. + * * @return IAppContainer * @since 6.0.0 */ @@ -105,34 +113,13 @@ public function getContainer(): IAppContainer { } /** - * This function is called by the routing component to fire up the frameworks dispatch mechanism. - * - * Example code in routes.php of the task app: - * $this->create('tasks_index', '/')->get()->action( - * function($params){ - * $app = new TaskApp($params); - * $app->dispatch('PageController', 'index'); - * } - * ); - * - * - * Example for for TaskApp implementation: - * class TaskApp extends \OCP\AppFramework\App { - * - * public function __construct($params){ - * parent::__construct('tasks', $params); + * Dispatches a controller action through the AppFramework runtime. * - * $this->getContainer()->registerService('PageController', function(IAppContainer $c){ - * $a = $c->query('API'); - * $r = $c->query('Request'); - * return new PageController($a, $r); - * }); - * } - * } + * This is a convenience wrapper around the internal AppFramework request + * execution for the current app container. * - * @param string $controllerName the name of the controller under which it is - * stored in the DI container - * @param string $methodName the method that you want to call + * @param string $controllerName controller service name or controller class basename + * @param string $methodName controller method to invoke * @since 6.0.0 */ public function dispatch(string $controllerName, string $methodName) { From 4438eac04119e57c8d7bd4cdd03e7c8b80391673 Mon Sep 17 00:00:00 2001 From: Josh Date: Mon, 1 Jun 2026 09:47:15 -0400 Subject: [PATCH 2/3] docs(App): drop/update outdated OC\AppFramework\App docblocks Signed-off-by: Josh --- lib/private/AppFramework/App.php | 47 +++++++++++++++++++++----------- 1 file changed, 31 insertions(+), 16 deletions(-) diff --git a/lib/private/AppFramework/App.php b/lib/private/AppFramework/App.php index 1d9c2157f9316..8e5d83e507041 100644 --- a/lib/private/AppFramework/App.php +++ b/lib/private/AppFramework/App.php @@ -25,19 +25,23 @@ use OCP\Server; /** - * Entry point for every request in your app. You can consider this as your - * public static void main() method + * Internal entry point for AppFramework request execution. * - * Handles all the dependency injection, controllers and output flow + * Resolves controllers from the app container, runs the dispatcher and + * middleware stack, and writes headers, cookies, and the response body to + * the output layer. + * + * This class is internal to the server and not part of the public app API. + * App code should use OCP\AppFramework\App instead. */ class App { /** - * Turns an app id into a namespace by either reading the appinfo.xml's - * namespace tag or uppercasing the appid's first letter - * @param string $appId the app id - * @param string $topNamespace the namespace which should be prepended to - * the transformed app id, defaults to OCA\ - * @return string the starting namespace for the app + * Returns the app namespace for the given app ID, optionally rewritten to a + * different top-level namespace. + * + * @param string $appId the app ID + * @param string $topNamespace the namespace prefix to substitute for OCA\ + * @return string the app namespace * @deprecated 34.0.0 use IAppManager::getAppNamespace */ public static function buildAppNamespace(string $appId, string $topNamespace = 'OCA\\'): string { @@ -50,6 +54,11 @@ public static function buildAppNamespace(string $appId, string $topNamespace = ' } /** + * Returns the app ID for the given class namespace. + * + * @param string $className the fully qualified class name + * @param string $topNamespace unused legacy namespace prefix parameter + * @return string|null the app ID, or null if the class does not belong to an app namespace * @deprecated 34.0.0 use IAppManager::getAppFromNamespace */ public static function getAppIdForClass(string $className, string $topNamespace = 'OCA\\'): ?string { @@ -57,14 +66,20 @@ public static function getAppIdForClass(string $className, string $topNamespace } /** - * Shortcut for calling a controller method and printing the result + * Executes an AppFramework controller action and emits the HTTP response. + * + * Resolves the controller from the app container, dispatches the requested + * method, and forwards headers, cookies, and body output to the output layer. + * + * The controller is first resolved as provided and then, if necessary, as + * \Controller\. * - * @param string $controllerName the name of the controller under which it is - * stored in the DI container - * @param string $methodName the method that you want to call - * @param DIContainer $container an instance of a pimple container. - * @param array $urlParams list of URL parameters (optional) - * @throws HintException + * @param string $controllerName Controller service name or controller class name + * @param string $methodName Controller method to invoke + * @param DIContainer $container App dependency injection container + * @param array|null $urlParams Route parameters to inject into the request + * @throws HintException If a controller from a globally registered route + * belongs to an app that is not enabled */ public static function main( string $controllerName, From 4fa88bce92620419eaea2eac0ca1187bfb9ce8dd Mon Sep 17 00:00:00 2001 From: Josh Date: Mon, 1 Jun 2026 09:55:19 -0400 Subject: [PATCH 3/3] chore(App): add minor missing typing Signed-off-by: Josh --- lib/public/AppFramework/App.php | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/lib/public/AppFramework/App.php b/lib/public/AppFramework/App.php index 7aac5f0456e2e..ff9a921d5dffd 100644 --- a/lib/public/AppFramework/App.php +++ b/lib/public/AppFramework/App.php @@ -31,8 +31,7 @@ * @since 6.0.0 */ class App { - /** @var IAppContainer */ - private $container; + private IAppContainer $container; /** * Returns the app namespace for the given app ID. @@ -122,7 +121,7 @@ public function getContainer(): IAppContainer { * @param string $methodName controller method to invoke * @since 6.0.0 */ - public function dispatch(string $controllerName, string $methodName) { + public function dispatch(string $controllerName, string $methodName): void { \OC\AppFramework\App::main($controllerName, $methodName, $this->container); } }