Configuration

Configuration file
Package
Object data
Database
Session cookie
Secured protocol port
Forms

Configuration files

Configuration is split across two files in the etc directory:

config.php — shared settings committed to the repository (defaults, charset, mail sender, etc.)
local.php — environment-specific or sensitive settings, not committed (database credentials, HTTPS, etc.)

Files are loaded in the following order, each overriding the previous:
packages/{package}/etc/{config}.php → etc/config.php → etc/local.php

Copy etc/local.php.sample to etc/local.php (or etc/local.{MW_ENVIRONMENT}.php if MW_ENVIRONMENT is defined) and fill in your environment values.

MW_ENVIRONMENT is an environment variable. See Installation.

Package

Access to a package is done in the configuration file. The package host must match the server host for MageWork to load the corresponding package.

You can specify multiple hosts to access the same package, or develop multiple packages with their own host.

<?php
// etc/local.php

$config = [
    'packages' => [
        'localhost.magework' => [ // HTTP Host
            'Magework' => '', // Package name (directory) and URL prefix (empty = no prefix)
        ],
    ],
    /* ... */
];

See Add a new package page for more information about packages.

If you are using a port other than 80 or 443, the port must be included in the host, e.g. : "127.0.0.1:8080".

Object data

In the configuration file, you can define all the environment information that needs to be passed to your own objects.

For example, to pass a variable to page-type objects in a package:

<?php
// etc/config.php

$config = [
    /* ... */
    'Acme' => [ // Package name
        Core_Page::TYPE => [ // Object type
            'default' => [ // All pages (default value)
                'email' => 'default@example.com',
            ],
            '/contact.html' => [ // Specific page
                'email' => 'contact@example.com', // Override the default value
            ],
        ],
    ],
    /* ... */
];

Database

To interact with a database, you need to configure your database connection. Shared settings go in config.php, and environment-specific credentials go in local.php:

<?php
// etc/config.php

$config = [
    /* ... */
    'default' => [ // "default" is the configuration for all packages. Use the package name for a specific configuration.
        Core_Model::TYPE => [
            'database' => [
                'db_charset' => 'utf8mb4',
                'lc_time_names' => 'en_US', // Language used to display day and month names and abbreviations
                'time_zone' => '+00:00', // Affects display and storage of time values that are zone-sensitive
            ],
        ],
    ],
    /* ... */
];

<?php
// etc/local.php

$config = [
    /* ... */
    'default' => [
        Core_Model::TYPE => [
            'database' => [
                'db_host' => '',
                'db_username' => '',
                'db_password' => '',
                'db_database' => '',
            ],
        ],
    ],
    /* ... */
];

This provides the connection information to the Core_Model_Database class, for all packages.

You are able to configure specific settings per package. See data assignment.

If you need to use a session, the following configurations are available:

<?php
// etc/config.php

$config = [
    /* ... */
    'app' => [
        'session_lifetime' => 3600, // Cookie lifetime in seconds
        'cookie_same_site' => 'Lax', // None, Lax, Strict
        'cookie_http_only' => true,
    ],
    /* ... */
];

These configurations are shared by all packages.

Secured protocol port

App::isSsl() determines whether the current context is secure. By default, it compares the server port against 443. If you're using a certificate on a different port, you can override the expected port:

<?php
// etc/local.php

$config = [
    /* ... */
    'app' => [
        'secured_port' => 8443,
    ],
    /* ... */
];

You can also force the protocol explicitly with https, bypassing the port check entirely. This is useful when the application runs behind a reverse proxy that terminates SSL — the app sees port 80, but the connection is served over HTTPS:

<?php
// etc/local.php

$config = [
    /* ... */
    'app' => [
        'https' => true, // Force HTTPS regardless of server port
    ],
    /* ... */
];

When https is set, it takes priority over secured_port: no port comparison is performed.

Forms

To manage forms and send emails, you can configure the contact settings. Default sender values go in config.php, while activation is controlled per environment in local.php:

<?php
// etc/config.php

$config = [
    /* ... */
    'default' => [ // "default" is the configuration for all packages. Use the package name for a specific configuration.
        Core_Model::TYPE => [
            'form' => [
                '_mail_from_name' => 'MageWork',
                '_mail_from_email' => 'hello@example.com',
            ],
        ],
    ],
    /* ... */
];

<?php
// etc/local.php

$config = [
    /* ... */
    'default' => [
        Core_Model::TYPE => [
            'form' => [
                '_mail_enabled' => true,
            ],
        ],
    ],
    /* ... */
];

This provides the contact information to the Core_Model_Form class.

See Forms page for more information.