Directory Structure

Forge follows a clear and organized directory structure that promotes modularity and maintainability. This guide explains the default structure and how you can customize it to fit your needs.

Root Structure

At the root level, Forge organizes code into several key directories:

/
├── apps/              # Application code
├── cache/             # Cached files (compiled views, etc.)
├── docs/              # Documentation
├── engine/            # Core framework code
├── modules/           # Installed modules
├── modules-registry/  # Module registry
├── public/            # Publicly accessible files
│   ├── assets/        # CSS, JavaScript, images
│   ├── modules/       # Module public assets
│   └── index.php      # Front controller
└── storage/           # Application storage
    ├── app/           # Application files
    ├── compiled_views/# Compiled view templates
    ├── framework/     # Framework storage
    └── logs/          # Log files

Application Structure

The apps/MyApp directory contains your application code. By default, it includes the following structure:

/apps/MyApp/
├── Bootstrap/           # Application bootstrap files
├── Commands/            # Custom console commands
├── Contracts/           # Interfaces and contracts
├── Controllers/         # HTTP controllers
├── DataTransferObjects/ # DTOs for data transfer
├── Database/            # Database migrations and seeders
│   ├── Migrations/      # Database migration files
│   └── Seeders/         # Database seeder files
├── Events/              # Event classes
├── Helpers/             # Helper functions
├── Jobs/                # Queue jobs
├── Middleware/          # HTTP middleware
├── Models/              # Database models
├── MyApp.php            # Application entry point
├── Repositories/        # Repository pattern implementations
├── Services/            # Business logic services
├── Traits/              # Reusable traits
├── ValueObjects/        # Value objects
├── config/              # Application configuration files
├── resources/           # Views, assets, and other resources
│   ├── components/      # Reusable view components
│   ├── layouts/         # Layout templates
│   ├── spark/           # Spark templates
│   └── views/           # View templates
└── routes/              # Route definitions

Configuration

The directory paths are configurable in your apps/MyApp/config/app.php file. Here's the default configuration:

"paths" => [
    "resources" => [
        "views" => "apps/MyApp/resources/views",
        "components" => "apps/MyApp/resources/components",
        "layouts" => "apps/MyApp/resources/layouts",
        "spark" => "apps/MyApp/resources/spark",
    ],
    "public" => [
        "assets" => "public/assets",
        "modules" => "public/modules",
        "uploads" => "public/uploads"
    ],
    "database" => [
        "migrations" => "apps/MyApp/Database/Migrations",
        "seeders" => "apps/MyApp/Database/Seeders"
    ],
    "controllers" => "apps/MyApp/Controllers",
    "models" => "apps/MyApp/Models",
    "respositories" => "apps/MyApp/Repositories",
    "routes" => "app/MyApp/routes",
    "events" => "apps/MyApp/Events",
    "helpers" => "apps/MyApp/Helpers",
    "middlewares" => "apps/MyApp/Middleware",
    "commands" => "apps/MyApp/Commands",
    "config" => "apps/MyApp/config",
    "interfaces" => "apps/MyApp/Contracts",
    "services" => "apps/MyApp/Services",
    "traits" => "apps/MyApp/Traits",
    "dtos" => "apps/MyApp/DataTransferObjects",
]

Important: If you change the location of your migrations or seeders, make sure to update the paths in your configuration file.

Customization

You can customize the directory structure to match your preferred architecture. Common approaches include:

Domain-Driven Design (DDD)

Organize by domain instead of technical concerns:

/apps/MyApp/
├── Domain/
│   ├── User/
│   │   ├── Controllers/
│   │   ├── Models/
│   │   ├── Repositories/
│   │   ├── Services/
│   │   └── Events/
│   ├── Product/
│   │   ├── Controllers/
│   │   ├── Models/
│   │   └── ...
│   └── ...
├── Infrastructure/
│   ├── Database/
│   ├── Queue/
│   └── ...
└── Application/
    ├── Middleware/
    ├── Commands/
    └── ...

Clean Architecture

Separate core business logic from infrastructure concerns:

/apps/MyApp/
├── Core/
│   ├── Entities/
│   ├── UseCases/
│   └── Interfaces/
├── Infrastructure/
│   ├── Database/
│   ├── ExternalServices/
│   └── Repositories/
└── Presentation/
    ├── Controllers/
    ├── Middleware/
    └── Views/

Note: While Forge provides a default directory structure, you're free to organize your code in a way that best suits your project's needs. Just remember to update the paths in your configuration accordingly.

Updating Configuration

When you customize your directory structure, make sure to update your app.php configuration file to reflect the new paths:

// Example for DDD approach
"paths" => [
    "resources" => [
        "views" => "apps/MyApp/Presentation/Views",
        "components" => "apps/MyApp/Presentation/Components",
        "layouts" => "apps/MyApp/Presentation/Layouts",
    ],
    "database" => [
        "migrations" => "apps/MyApp/Infrastructure/Database/Migrations",
        "seeders" => "apps/MyApp/Infrastructure/Database/Seeders"
    ],
    "controllers" => "apps/MyApp/Presentation/Controllers",
    // ...
]

Engine Directory Structure

The engine/ directory contains the core framework code that powers Forge. Understanding this structure can help you extend or modify the framework:

/engine/
├── Console/            # Command-line functionality
│   ├── Commands/       # Built-in console commands
│   └── ConsoleKernel.php # Console application kernel
├── Core/               # Core framework components
│   ├── Bootstrap/      # Framework bootstrap process
│   ├── Configuration/  # Configuration management
│   ├── Contracts/      # Core interfaces
│   ├── DependencyInjection/ # Service container
│   ├── Events/         # Event system
│   ├── Helpers/        # Helper functions
│   ├── Models/         # Base model classes
│   ├── Module/         # Module management
│   ├── Pagination/     # Pagination utilities
│   ├── Resources/      # Resource management
│   ├── Routing/        # Routing system
│   ├── Schema/         # Schema definitions
│   ├── Services/       # Core services
│   ├── Templates/      # Template files
│   └── Traits/         # Reusable traits
├── Enums/              # Enumeration classes
└── Http/               # HTTP layer
    ├── Exceptions/     # HTTP exceptions
    ├── Middleware/     # HTTP middleware
    ├── HttpKernel.php  # HTTP application kernel
    ├── Request.php     # HTTP request handling
    ├── Response.php    # HTTP response handling
    ├── Session.php     # Session management
    └── Validator.php   # Input validation

Module Structure

Forge's modular architecture allows you to extend functionality through modules. Each module follows a consistent structure:

/modules/ModuleName/
├── Commands/           # Module-specific commands
├── Contracts/          # Interfaces and contracts
├── Database/           # Database migrations and seeders
├── ModuleNameModule.php # Module entry point
├── config/             # Module configuration
├── resources/          # Module resources
│   ├── assets/         # CSS, JavaScript, images
│   └── views/          # View templates
└── forge.json          # Module manifest

Best Practice: When developing your own modules, follow this structure to maintain compatibility with the Forge module system and make your modules easier to understand for other developers.

Storage Directory

The storage/ directory is used for storing application-generated files:

/storage/
├── app/                # Application storage
│   ├── images/         # Uploaded images
│   └── uploads/        # User uploads
├── compiled_views/     # Compiled view templates
├── framework/          # Framework storage
│   ├── modules/        # Module-specific storage
│   ├── tmp/            # Temporary files
│   └── views/          # Cached views
└── logs/               # Application logs

Make sure your web server has write permissions to the storage directory, as Forge needs to write to these locations during normal operation.