Configuring Apache 2

Hazaar Framework works with Apache 2.x for traditional web hosting environments. However, for modern production deployments, we recommend using FrankenPHP, which provides better performance, built-in HTTP/2 and HTTP/3 support, and advanced features like worker mode.

This guide covers Apache 2 configuration for scenarios where traditional hosting is required, such as shared hosting environments or existing Apache infrastructure.

Prerequisites

Before deploying to Apache, ensure you have created a Hazaar application. See the Getting Started guide for installation instructions.

Hazaar also works with Nginx and other web servers, though FrankenPHP, Apache, and Nginx are the primary tested configurations.

Document Root

If your Hazaar application is the only site running on your web server, configuration is straightforward. The DocumentRoot typically defaults to /var/www, and you can replace this directory with a symlink pointing to your application's public directory.

Directory Structure

Hazaar applications follow a standard MVC structure with a public directory that serves as the web-accessible entry point. See Project Layout for more details.

Ensure your default Apache configuration allows overrides by setting:

AllowOverride All

in your directory configuration. For example:

DocumentRoot /var/www
<Directory /var/www/>
    Options Indexes FollowSymLinks MultiViews
    AllowOverride All
    Order allow,deny
    allow from all
</Directory>

Example: If your DocumentRoot is /var/www and your application is located at /home/user/myapp (created via composer create-project hazaar/hazaar myapp), you can run:

sudo rm -rf /var/www
sudo ln -s /home/user/myapp/public /var/www

Sub-Directory

If your website hosts multiple sites in sub-directories, create a symlink in your DocumentRoot pointing to your application's public directory.

Example: To make your application accessible at http://yourdomain.com/myapp:

sudo ln -s /home/user/myapp/public /var/www/myapp

Virtual Host

You can deploy your Hazaar application as a virtual host for better isolation and configuration control.

Example configuration:

<VirtualHost *:80>
    ServerAdmin [email protected]
    ServerName myapp.example.com
    DocumentRoot /home/user/myapp/public
    
    <Directory /home/user/myapp/public>
        Options Indexes FollowSymLinks MultiViews
        AllowOverride All
        Order allow,deny
        allow from all
    </Directory>
</VirtualHost>

Update the ServerName, DocumentRoot, and Directory directives to match your domain and application path.

Directory Alias

Running a Hazaar application via a server alias is possible but not recommended. This approach requires modifying the .htaccess file to hard-code the application path, making it less portable. If you move the application later, you must remember to update the .htaccess file accordingly.

Warning

Prefer using Sub-Directory or Virtual Host configurations for better maintainability.

Setting up a server alias requires two steps:

Step 1 – Add the Server Alias

Edit your Apache site configuration file (typically /etc/apache2/sites-enabled/000-default.conf or similar). Add the following inside the <VirtualHost> container:

Alias /myapp /home/user/myapp/public

<Directory /home/user/myapp/public>
    Options Indexes FollowSymLinks MultiViews
    AllowOverride All
    Order allow,deny
    allow from all
</Directory>

Step 2 – Update the .htaccess File

Edit the .htaccess file in your application's public directory (e.g., /home/user/myapp/public/.htaccess) and add a RewriteBase directive:

<IfModule mod_rewrite.c>
    RewriteEngine on
    RewriteBase /myapp
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^(.*)$ index.php [QSA,L]
</IfModule>

Replace /myapp with the directory alias where you want your application to be accessible.