Skip to content

Directory Structure

Overview

The NexusPHP directory structure is designed to be highly intuitive, heavily inspired by modern enterprise PHP frameworks. It enforces a clean separation of concerns while keeping the architecture minimal and lightning-fast. Because NexusPHP relies entirely on a zero-dependency philosophy, you will find its root directory remarkably lean compared to traditional frameworks.

While NexusPHP is highly flexible, it follows a convention-over-configuration paradigm. Sticking to the default structure ensures that features like automatic service resolution and routing work seamlessly out of the box.

Root Directory Breakdown

When you install a fresh NexusPHP application, you will find the following top-level directories and files:

app/

The app/ directory contains the core business logic of your application. Almost all the classes in your application will reside here. By default, it is minimal, containing only what you need. - app/Http/Controllers/: Contains your HTTP Controllers, which handle incoming requests, orchestrate business logic, and return responses (e.g., JSON, HTML).

(Note: Additional directories like Models or Middleware may be created here manually or via the nexus CLI as your application grows.)

bootstrap/

The bootstrap/ directory houses the files responsible for booting the framework. - app.php: The crucial bootstrap script that initializes the PSR-4 autoloader, loads environment variables, reads the config/ directory, creates the Application container, and sets up the HTTP Kernel and Router. - helpers.php: Contains global helper functions initialized during the boot process.

config/

The config/ directory holds all your application's configuration files. NexusPHP loads these files dynamically at boot time. Notable files include: - app.php: Application-wide settings, environment, and debug toggles. - database.php: Database connection settings (SQLite, MySQL, PostgreSQL). - security.php: Configuration for CORS, Content Security Policies (CSP), and hashing. - services.php: Dependency Injection bindings for the Service Container.

framework/

Unlike frameworks that pull their core via a vendor directory from Packagist, NexusPHP ships its source code directly in the framework/ directory. This ensures zero third-party dependencies. It contains the underlying routing, ORM, security, and container logic.

public/

The public/ directory is the document root for your web server. - index.php: The front controller that intercepts all incoming HTTP requests and funnels them into the NexusPHP application kernel. This directory should be the only one exposed to the web.

routes/

The routes/ directory houses your application's routing definitions. - web.php: The default file where you define your HTTP routes. These routes are automatically loaded and parsed by the Router during application bootstrap.

storage/

The storage/ directory contains files generated by the framework at runtime. - storage/logs/: Holds application logs, such as nexus.log (for HTTP and runtime errors) and events.log.

tests/

The tests/ directory contains your automated tests. - tests/TestRunner.php: NexusPHP includes a built-in native PHP assertion test runner that operates without PHPUnit. - tests/Feature/: A directory for your feature and integration tests.

Important Root Files

  • composer.json: Defines the project metadata and configures the PSR-4 autoloader (though it declares no third-party required packages other than PHP itself).
  • .env: Your environment variables configuration file (database credentials, app key, etc.).
  • nexus: The CLI executable script used for generating code and running administrative commands (like serve and migrate).

[!NOTE] Directories such as database/ (for migrations/seeders) or resources/ (for views) do not exist by default in a fresh framework installation but will be created dynamically by the nexus CLI scaffolding tools.

Namespace Mapping

NexusPHP relies heavily on the PSR-4 autoloading standard, which maps namespaces directly to directory paths.

  • App\ Namespace: Mapped to the app/ directory. Any class you create in app/Http/Controllers/ must be placed in the App\Http\Controllers namespace.
  • Nexus\ Namespace: Mapped to the framework/ directory. This namespace is reserved for core framework components.

These mappings are explicitly defined in the composer.json file's "autoload" section and are also natively handled by bootstrap/app.php as a fallback.

Best Practices

  • Keep Controllers Lean: Your app/Http/Controllers should primarily handle HTTP request parsing and response formatting. Push complex business logic into service classes.
  • Creating Models: When you create ActiveRecord models (e.g., via php nexus make:model), they should typically reside in an app/Models directory, mapped to the App\Models namespace.
  • Use the Container: Take advantage of the config/services.php file to register custom classes and logic into the Service Container, rather than hardcoding instantiations throughout the app/ directory.

Customization

The directory structure is not locked in stone. Because NexusPHP's autoloader relies on PSR-4, you can extend or modify the structure easily:

  1. Adding Custom Directories: You can create new directories inside app/ (like app/Services/ or app/Repositories/). As long as you adhere to the App\ namespace (e.g., namespace App\Services;), they will be automatically loaded.
  2. Modifying Namespaces: If you wish to change the default App\ namespace to something else (e.g., MyCompany\), you can update the mapping in the composer.json file and regenerate the autoloader by running: bash composer dump-autoload

Next Steps: Now that you understand the directory layout, dive into how the framework handles an incoming HTTP request in the Request Lifecycle guide.