Project Layout

Before you start developing your first application, it is helpful to understand the layout of a Hazaar application directory. When you create a new project using Composer or the Dev Container, a standard structure is generated for you. This structure organizes your code into logical sections—separating your application logic, public assets, and configuration.

Hazaar follows a typical MVC (Model-View-Controller) structure. A standard project looks like this:

.
├─ app
│  ├─ configs
│  │  ├─ app.php
│  │  ├─ database.php
│  │  └─ ...
│  ├─ controllers
│  │  ├─ Main.php
│  │  ├─ Error.php
│  │  └─ ...
│  ├─ events
│  │  └─ ...
│  ├─ exceptions
│  │  └─ ...
│  ├─ middleware
│  │  └─ ...
│  ├─ models
│  │  ├─ Model1.php
│  │  ├─ Model2.php
│  │  └─ ...
│  ├─ views
│  |  ├─ application.tpl
│  |  ├─ index.tpl
│  |  ├─ error.tpl
|  |  └─ ...
|  ├─ bootstrap.php
|  └─ route.php
├─ public
│  └─ index.php
└─ composer.json

app directory

The app directory is the heart of your application. It contains all the logic, configuration, and templates.

configs directory

This directory contains your application's configuration files. The most important file is app.php, which controls the core settings of your application. See the Configuration section for more details.

controllers directory

Namespace: App\Controller

Controllers act as the glue binding your models and views together. They handle incoming requests and determine the appropriate response. For example, App\Controller\Main corresponds to app/controllers/Main.php. See Controllers.

events directory

Namespace: App\Event

The events directory is used to store event listeners and handlers. Hazaar uses an event-driven architecture that allows you to hook into various points of the application lifecycle. See Events.

exceptions directory

Namespace: App\Exception

This directory holds your application's custom Exception classes. Grouping them here ensures a clean separation of error definitions from your business logic.

middleware directory

Namespace: App\Middleware

Middleware provides a convenient mechanism for inspecting and filtering HTTP requests entering your application. This directory is where you define your middleware classes. See Middleware.

models directory

Namespace: App\Model

Models represent the data structure of your application. They typically interact with the database and handle data logic. See Models.

views directory

Views serve as the presentation layer. They are the templates (typically Smarty or PHP files) that generate the final output sent to the user. See Views.

public directory

This directory serves as the document root for your web server. It contains the entry point index.php, as well as public assets like images, CSS, and JavaScript files.

Only files in this directory are directly accessible by the web server, ensuring your application code and configuration remain secure.

Customizing Directory Paths

While Hazaar provides a sensible default structure, all of these paths are fully configurable in your app.php configuration file. This allows you to organize your application however you see fit.

The paths configuration array maps the internal component names to their directory locations relative to the app folder.

Example Configuration

To change the location of your components, you can define the paths section in your configuration file:

PHP (Recommended)

<?php
return [
    'paths' => [
        'controller' => 'src/Controllers',
        'model' => 'src/Models',
        'view' => 'templates',
        'middleware' => 'src/Middleware',
        'event' => 'src/Events'
    ],
    // ... other settings
];

JSON

{
    "paths": {
        "controller": "src/Controllers",
        "model": "src/Models",
        "view": "templates",
        "middleware": "src/Middleware",
        "event": "src/Events"
    }
    // ... other settings
}

INI (Legacy)

[paths]
controller = "src/Controllers"
model = "src/Models"
view = "templates"
middleware = "src/Middleware"
event = "src/Events"
# ... other settings

If a path is not specified, it will fall back to the default location defined in the Application Defaults.