Installation

Requirements
- PHP
- Server
Environment variables
Root directory
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

You just need to set 2 environment variables:

MW_ENVIRONMENT: The environment name (local, prod, staging...). This variable is used to read the configuration file in the etc directory: etc/config.{MW_ENVIRONMENT}.php. Default value if missing is default.
MW_DEVELOPER_MODE: Display PHP error. Always set 0 in production. Default value if missing is 0.

If you can't add environment variables, you need to use etc/config.default.php as configuration file.

Root directory

Configure the web server to serve the pub directory.

Examples

Built-in PHP server

Unix

From the MageWork root folder:

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
set MW_ENVIRONMENT=local
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

    SetEnv MW_DEVELOPER_MODE 1
    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;

        fastcgi_param MW_DEVELOPER_MODE 1;
        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 {environment} {host} {path} {developer_mode}

Example:

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