Installation

Requirements
- PHP
- Server
Environment variables
Root directory
Writable directories
Examples
- Built-in PHP server
- Apache
- Nginx
- Caddy
- CLI

Requirements

PHP

A PHP version 8.4 or higher is required.

PHP Extensions:

ext-fileinfo (to read an asset static file)
ext-gd (to generate a Captcha)
ext-openssl (to encrypt and decrypt data)

sudo apt install php8.4-gd php8.4-common

Server

MageWork is compatible with any web server.

Environment variables

MW_DEVELOPER_MODE: Display PHP error. Always set 0 in production. Default value if missing is 0.
MW_ENVIRONMENT: The environment name (local, prod, staging...). This variable is used to read the local configuration file in the etc directory: etc/local.{MW_ENVIRONMENT}.php. If the variable is missing, the local configuration file will be etc/local.php.
MW_HOST: Force the HTTP host. Mainly useful on the command line, where there is no Host header (the CLI entry point sets it from its first argument).

Root directory

Configure the web server to serve the pub directory. A pub/.htaccess file is already provided for Apache (it needs AllowOverride All).

Writable directories

MageWork creates a var/ directory at the project root and must be able to write to it:

var/cache — cache files
var/session — session files
var/log — log files
var/encryption — encryption key (0400, created once)

The web server user (and the CLI user) must have write access to var/.

Examples

Built-in PHP server

Unix

From the MageWork root folder:

sudo php -S localhost.magework:80 -t pub

With optional environment variables:

sudo MW_ENVIRONMENT=local MW_DEVELOPER_MODE=1 php -S localhost.magework:80 -t pub

Windows

Add an executable bat file to the MageWork root directory:

:: server.bat

@echo off

:: Environment-specific configuration (optional)
:: set MW_ENVIRONMENT=local

:: Display PHP error (optional)
:: set MW_DEVELOPER_MODE=1

php -S localhost.magework:80 -t pub
pause

To serve MageWork quickly without adding a new host, serve on 127.0.0.1:80 (or another port if port 80 is busy).

Apache

<VirtualHost *:80>
    ServerName localhost.magework
    DocumentRoot /var/www/magework/pub

    # Display PHP error (optional)
    # SetEnv MW_DEVELOPER_MODE 1

    # Environment-specific configuration (optional)
    # SetEnv MW_ENVIRONMENT local

    <Directory /var/www/magework/pub>
        Options Indexes FollowSymLinks MultiViews
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/magework.log
</VirtualHost>

Nginx

server {
    listen 80;
    listen [::]:80;

    root /var/www/magework/pub;
    server_name localhost.magework;
    index index.php;

    charset utf-8;
    autoindex off;

    location ~ /\.ht {
        deny all;
    }

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.4-fpm.sock;

        # Display PHP error (optional)
        # fastcgi_param MW_DEVELOPER_MODE 1;

        # Environment-specific configuration (optional)
        # fastcgi_param MW_ENVIRONMENT local;
    }
}

Caddy

localhost.magework {
    root * /var/www/magework/pub
    try_files {path} {path}/ /index.php?{query}
    php_fastcgi unix//var/run/php/php8.4-fpm.sock {
        env MW_DEVELOPER_MODE 1
        env MW_ENVIRONMENT local
    }
    file_server
}

CLI

You can display a page directly in the console, for debugging or CI/CD testing.

php pub/index.php {host} {path} {developer_mode} {environment}

Example:

php pub/index.php localhost.magework /documentation/installation.html 1 local