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
│  ├─ Controllers
│  │  ├─ Main.php
│  │  ├─ Error.php
│  │  └─ ...
│  ├─ Events
│  │  └─ ...
│  ├─ Exceptions
│  │  └─ ...
│  ├─ Middleware
│  │  └─ ...
│  ├─ Models
│  │  ├─ Model1.php
│  │  ├─ Model2.php
│  │  └─ ...
│  ├─ Views
│  |  ├─ application.tpl
│  |  ├─ index.tpl
│  |  ├─ error.tpl
|  |  └─ ...
|  ├─ bootstrap.php
|  └─ route.php
├─ configs
│  ├─ app.php
│  ├─ database.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.

Naming Conventions

Directory and File Case

The app directory itself is lowercase. Subdirectories within it follow PascalCase (e.g., Controllers, Models, Events) and are PSR-4 compliant — meaning the directory names map directly to PHP namespaces. Class files inside these directories must also be PascalCase and match their class name exactly (e.g., App\Controller\Main lives in app/Controllers/Main.php).

The one exception is the Views directory. Because it contains template files rather than PHP classes, it is not subject to PSR-4 rules. View files are resolved using exactly the case provided at the call site, so the filename on disk must match the case used when referencing the view in your code.

Case Sensitivity on Windows vs. Linux

Windows uses a case-insensitive file system, so views/Index.tpl and views/index.tpl will resolve to the same file. Linux, however, is case-sensitive and will treat these as two distinct files. Code that works on a Windows development machine may fail in a Linux production environment due to case mismatches. Always use the exact, consistent casing in both your code and your file names to avoid hard-to-diagnose deployment issues.

configs directory

The configs directory is located at the root of your project, alongside the app and public directories. Because it contains configuration files rather than PHP classes, it is not part of the PSR-4 namespace structure. It 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.