Nextcloud Core Architecture

nextcloud-core-architecture

Quick Reference

Architecture Layers (NC 28+)

Key Dependencies

Critical Warnings

NEVER query services from other apps inside register() -- they may not be registered yet. ALWAYS use boot() for cross-app service dependencies.

NEVER omit the <namespace> element in appinfo/info.xml -- auto-wiring will silently fail because the DI container cannot map OCA\{Namespace}\* classes to the lib/ directory.

NEVER use \OCP\Server::get() for service resolution in new code -- it is a service locator anti-pattern that breaks testability. ALWAYS use constructor injection.

NEVER use OCP\ILogger -- deprecated since NC 24. ALWAYS inject Psr\Log\LoggerInterface instead.

NEVER put business logic in Application.php -- keep it in Service/ classes. Application.php MUST only contain registration and boot wiring.

NEVER perform I/O or side effects in constructors -- constructors MUST only assign dependencies.

Request Lifecycle

All HTTP requests follow this path:

index.php
  -> lib/base.php (init: auth backends, filesystem, logging)
    -> Load all enabled apps (appinfo/info.xml)
    -> Load navigation and pre-config files
    -> Load route definitions (appinfo/routes.php)
    -> Router matches URL to Controller method
      -> Middleware chain (beforeController -> controller -> afterController)
        -> Response rendered and returned

1. index.php loads lib/base.php, which abstracts web server differences and initializes core classes
2. Authentication backends, filesystem, and logging are bootstrapped
3. Each installed app is loaded based on its appinfo/info.xml
4. Route definitions from each app's appinfo/routes.php are loaded
5. The router matches the incoming URL to a controller method
6. The middleware chain processes the request and response

App Lifecycle: IBootstrap

The Application class in lib/AppInfo/Application.php implements IBootstrap for a two-phase lifecycle:

Phase 1: register() -- Lazy Registration

Called during app loading. ONLY use IRegistrationContext methods here:

public function register(IRegistrationContext $context): void {
    $context->registerMiddleware(MyMiddleware::class);
    $context->registerServiceAlias(IMyInterface::class, MyImplementation::class);
    $context->registerEventListener(ItemCreatedEvent::class, ItemCreatedListener::class);
    $context->registerParameter('TableName', 'my_app_table');
}

Phase 2: boot() -- Post-Registration Initialization

Called after ALL apps have completed register(). All services are now available:

public function boot(IBootContext $context): void {
    $context->injectFn(function (IFooManager $manager) {
        $manager->registerCustomFoo(MyFooImpl::class);
    });
}

Bootstrap Sequence

1. Nextcloud scans enabled apps for lib/AppInfo/Application.php
2. Apps with IBootstrap -> register() called (in app dependency order)
3. App load groups processed (filesystem, session, etc.)
4. All Application classes fully instantiated
5. All boot() methods called -- prior registrations guaranteed complete
6. Request routing begins

Dependency Injection

Nextcloud uses auto-wiring as the primary DI mechanism (PSR-11 compatible container).

How Auto-Wiring Resolves Parameters

1. Type hints: SomeType $param resolves via $container->get(SomeType::class)
2. Parameter names: $variable resolves via $container->get('variable')

Predefined Parameters

Auto-Wiring Requirements

1. <namespace> MUST be declared in appinfo/info.xml
2. Array-style routes in appinfo/routes.php
3. Constructor parameters MUST have type hints

IRegistrationContext Methods

Optional Dependencies (NC 28+)

Use nullable types for services that may not exist:

class MyService {
    public function __construct(private ?SomeOptionalService $service) { }
}

Key OCP Interfaces

Namespace Conventions

The <namespace> element in info.xml determines the OCA\{Namespace} prefix. Nextcloud's autoloader maps this to the lib/ directory:

Project Structure

myapp/
├── appinfo/
│   ├── info.xml              # App manifest (REQUIRED)
│   └── routes.php            # Route definitions
├── lib/
│   ├── AppInfo/
│   │   └── Application.php   # Bootstrap entry point (IBootstrap)
│   ├── Controller/            # HTTP controllers
│   ├── Service/               # Business logic layer
│   ├── Db/                    # Entity classes and mappers
│   ├── Listener/              # Event listeners
│   ├── Middleware/             # Request middleware
│   ├── Migration/             # Database migrations
│   └── Command/               # OCC CLI commands
├── src/                       # Vue.js frontend source
│   ├── main.js                # Vue app entry point
│   ├── App.vue                # Root Vue component
│   ├── components/            # Reusable Vue components
│   ├── views/                 # Page-level components
│   ├── store/                 # Vuex/Pinia store
│   └── services/              # API service layer
├── css/                       # Stylesheets (CSS/SCSS)
├── img/                       # Icons (app.svg = app icon)
├── js/                        # Compiled JS output (generated)
├── templates/                 # PHP templates
├── tests/                     # PHPUnit tests
├── l10n/                      # Translation files
├── webpack.config.js          # Build configuration
└── package.json               # NPM dependencies

Source Control Rules

• ALWAYS commit: composer.lock, package-lock.json (deterministic builds)
• ALWAYS ignore: vendor/, node_modules/, js/ (build artifacts)
• NEVER edit: generated files in js/ directory

Reference Links

• references/methods.md -- Key interfaces: App, IBootstrap, IRegistrationContext, IServerContainer, core services
• references/examples.md -- Application.php, DI patterns, service layer examples
• references/anti-patterns.md -- DI mistakes, bootstrap errors, common pitfalls

Official Sources

• https://docs.nextcloud.com/server/latest/developer_manual/app_development/intro.html
• https://docs.nextcloud.com/server/latest/developer_manual/app_development/bootstrap.html
• https://docs.nextcloud.com/server/latest/developer_manual/basics/dependency_injection.html
• https://docs.nextcloud.com/server/latest/developer_manual/app_development/info.html