All the parameters specified during the engine installation are stored in the config.php file. Let’s consider the example of the config.php file and all possible parameters.

This file is located in the same folder as other S2 files. It stores parameters specified during the engine installation. For fine-tuning the engine as described below, the config.php file needs to be edited manually.

Example of config.php contents right after installation:

<?php

return [
    'database' => [
        'type'      => 'mysql',
        'host'      => 'localhost',
        'name'      => 's2',
        'user'      => 'root',
        'password'  => '',
        'prefix'    => 's2_',
        'p_connect' => false,
    ],
    'http' => [
        'base_url'   => 'https://example.com',
        'base_path'  => '',
        'url_prefix' => '',
    ],
    'options'  => [
        'force_admin_https' => true,
        'canonical_url'     => null,
        'debug'             => 0,
        'debug_view'        => 0,
        'show_queries'      => 0,
    ],
    'cookies' => [
        'name' => 's2_cookie_209796818',
    ],
];

Configured in the database section:

'database' => [
    'type'      => 'mysql',      // Database type (mysql, pgsql, or sqlite)
    'host'      => 'localhost',  // Host running the database server
    'name'      => 's2',         // Database name (or SQLite file path)
    'user'      => 'root',       // Database username
    'password'  => '',           // Database user password
    'prefix'    => 'foo_',       // S2 tables prefix
    'p_connect' => false,        // Persistent connections (rarely needed)
],

type defines which database to connect to. Possible values:

• mysql (MySQL and MariaDB);
• pgsql (PostgreSQL);
• sqlite (SQLite).

Configured in the http section:

'http' => [
    'base_url'   => 'https://example.com', // Full site address without trailing slash
    'base_path'  => '',     // Same path without protocol and domain
    'url_prefix' => '',     // URL prefix for routing (see below)
],

If S2 is installed in the website root, parameter values should be:

'http' => [
    'base_url'   => 'https://example.com',
    'base_path'  => '',
],

If S2 is installed in a folder, for example subdir, the values would be:

'http' => [
    'base_url'   => 'https://example.com/subdir',
    'base_path'  => '/subdir',
],

To use clean URLs, you need to configure the web server to redirect requests to the index.php file.

The nginx web server can be configured like this:

server {
    listen       80;
    listen       [::]:80;
    server_name  www.example.com;
    access_log   /var/www/example.com/logs/access.log;
    error_log    /var/www/example.com/logs/error.log error;
    return       301    http://example.com$request_uri;
}

server {
    listen       80;
    listen       [::]:80;
    server_name  example.com;

    root         /var/www/example.com/public_html;
    access_log   /var/www/example.com/logs/access.log;
    error_log    /var/www/example.com/logs/error.log error;

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

    location ^~ /_pictures {
        index           index.html;
#        expires         1d;
    }

    location ~ \.php$ {
        try_files       $uri /index.php?$args;
        include         /etc/nginx/fastcgi.conf;
        fastcgi_pass    unix:/run/php/php8.4-fpm.sock;
    }
}

If the web server is Apache with mod_rewrite enabled, redirection will work automatically thanks to the .htaccess file included in the distribution:

# BEGIN S2

<IfModule mod_rewrite.c>
# MultiViews interfers with proper rewriting
Options +FollowSymlinks -MultiViews

RewriteEngine On

# Uncomment and properly set the RewriteBase if the rewrite rules are not working properly
#RewriteBase /

RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . index.php [L]
</IfModule>

# END S2

For the S2 to generate links matching the URL scheme configured in the web server, the url_prefix parameter is used.

If redirection to index.php is configured (for example, using one of the methods above), then url_prefix should be empty, and links will have the shortest form:

'http' => [
    'url_prefix' => '',             // https://example.com/section1/page1
],

Other possible values for url_prefix and examples of resulting URLs:

'http' => [
    // Works if index.php is configured as an index file for the root folder
    'url_prefix' => '/?',           // https://example.com/?/section1/page1

    // Works in some Apache and Nginx configurations  
    'url_prefix' => '/index.php',   // https://example.com/index.php/section1/page1

    // Should work everywhere
    'url_prefix' => '/index.php?',  // https://example.com/index.php?/section1/page1
],

During installation, the above url_prefix values are checked and the first working one is selected. If you configure request redirection in the web server after installing the S2, you'll likely need to change url_prefix in the config.php file as well.

Additional configuration sections can be added to the config.php file.

'files' => [
    'cache_dir'          => null,  // Absolute path to cache directory
    'image_dir'          => '_pictures',  // Overrides the folder for uploading images
    'allowed_extensions' => 'gif bmp jpg jpeg png ico svg mp3 wav ogg flac mp4 avi flv mpg mpeg mkv zip 7z rar doc docx ppt pptx odt odp ods xlsx xls pdf txt rtf csv',
    'log_dir'            => null,  // Directory for log files
],

• cache_dir – specifies an absolute path to the cache directory. If not set, defaults to _cache/ in the project root.
• image_dir – overrides the folder for uploading images and other files.
• allowed_extensions – space-separated whitelist of file extensions permitted for uploads to the server.
• log_dir – defines a custom directory for log files. If not specified, logs will be written to the cache directory.

'options' => [
    'force_admin_https' => true, // Enables forced switching to https in control panel
    'canonical_url'     => 'https://example.com', // Enables canonical URL generation
    'disable_cache'     => false, // Disables cache (not recommended)
    'debug'             => false, // Enables debug information and generation time
    'debug_view'        => false, // Enables template debugging mode
    'show_queries'      => false, // Shows executed SQL queries
],

Detailed description:

• force_admin_https – enables forced switching to https protocol in the control panel. This setting is automatically added during installation if the engine detects https support. Before manually adding this, make sure your hosting supports https protocol.

• canonical_url – sets a prefix for canonical URLs and enables its generation on the content pages. This helps search engines distinguish the primary website from its mirrors. Use this setting if you haven't implemented HTTP to HTTPS redirects or WWW to non-WWW redirects (or vice versa).

• disable_cache – disables cache (writing configuration parameters and installed extensions to the cache folder). This parameter was introduced to allow engine operation on unusual hosting where PHP can't get write permissions. Highly discouraged for use on normal hosting due to performance considerations and lack of testing.

• debug – enables debug information output for errors and enables PHP notice output, as well as shows page generation time and database query count.

• debug_view – enables a special template debugging mode with two key features:

  1. Each template placeholder is outlined with a red border showing the placeholder's name

  2. Every used view is highlighted with a gray border containing a special button that displays the variables passed to that view

• show_queries – enables output the list of executed SQL queries in the <!-- s2_debug --> placeholder.

Use the redirects section to define permanent redirects (status code 301).

'redirects' => [
    '#^/old-path$#' => '/new-path',
    '#^/blog/(\d+)$#' => '/news/$1',
],

The format is the following: regular expression → target mappings. Redirects are checked when a non-existing page is requested before answering with a 404 error page. They are useful when the site structure is changed.

The format uses regular expression patterns (keys) mapped to their target URLs (values). These redirects are processed when a request is made for a non-existing page, before the engine returns a 404 error. This mechanism is particularly useful for preserving link equity and user experience after restructuring your site's URLs.