Deltik
commented
12 months ago RFC: e107_config.php v3 Format
This request for comments proposes a new format for the e107_config.php file, which is used to store the configuration of an e107 installation.
Motivation
Status Quo
The e107 v2 configuration file is made of unstructured and inflexible variables and some additional code that defines constants to modify global behavior.
This is the template of the e107 v2 configuration file:
<?php
/**
* e107 website system
*
* Copyright (C) 2008-{$copyrightYear} e107 Inc (e107.org)
* Released under the terms and conditions of the
* GNU General Public License (http://www.gnu.org/licenses/gpl.txt)
*
* e107 configuration file
*
* This file has been generated by the installation script on {$rfc2822Date}.
*/
$mySQLserver = '{{ mySQLserver }}';
$mySQLuser = '{{ mySQLuser }}';
$mySQLpassword = '{{ mySQLpassword }}';
$mySQLdefaultdb = '{{ mySQLdefaultdb }}';
$mySQLport = '{{ mySQLport }}';
$mySQLprefix = '{{ mySQLprefix }}';
$mySQLcharset = 'utf8mb4';
$ADMIN_DIRECTORY = 'e107_admin/';
$FILES_DIRECTORY = 'e107_files/';
$IMAGES_DIRECTORY = 'e107_images/';
$THEMES_DIRECTORY = 'e107_themes/';
$PLUGINS_DIRECTORY = 'e107_plugins/';
$HANDLERS_DIRECTORY = 'e107_handlers/';
$LANGUAGES_DIRECTORY = 'e107_languages/';
$HELP_DIRECTORY = 'e107_docs/help/';
$MEDIA_DIRECTORY = 'e107_media/';
$SYSTEM_DIRECTORY = 'e107_system/';
// -- Optional --
// define('e_DEBUG', true); // Enable debug mode to allow displaying of errors
// define('e_HTTP_STATIC', 'https://static.mydomain.com/'); // Use a static subdomain for js/css/images etc.
// define('e_MOD_REWRITE_STATIC', true); // Rewrite static image urls.
// define('e_LOG_CRITICAL', true); // log critical errors but do not display them to user.
// define('e_GIT', 'path-to-git'); // Path to GIT for developers
// define('X-FRAME-SAMEORIGIN', false); // Option to override X-Frame-Options
// define('e_PDO, true); // Enable PDO mode (used in PHP > 7 and when mysql_* methods are not available)This template has the following limitations:
- The database configuration is defined by a set of variables that are not grouped together.
- Only one kind of database configuration is supported.
- The directories are also defined by a set of variables that are not grouped together.
- Arbitrary code is loaded in an uncontrolled manner.
- There is no schema to validate the configuration file.
- The variables that are set have to be retrieved and are not passed to the caller, making the handoff unstructured, too.
Goals
- Plug-in architecture for the database configuration to support multiple database types or connection methods
- Validatable schema for the configuration file
- Logical grouping of configuration options
- Structured handoff of the configuration to the caller that imports the configuration file
- Deferred loading of configuration options for tighter control over the loading process
- Adapter for the old configuration file format to allow for a smooth transition
Proposal
New Configuration File Template
The equivalent configuration file in the new format would look like this:
<?php
/**
* e107 website system
*
* Copyright (C) 2008-{$copyrightYear} e107 Inc (e107.org)
* Released under the terms and conditions of the
* GNU General Public License (https://www.gnu.org/licenses/gpl.txt)
*
* Site configuration file
*/
class E107Config extends BaseSiteConfig
{
function getDatabase(): DatabaseConnector
{
return new MysqlTcpConnector(
user: '{{ mySQLuser }}',
password: '{{ mySQLpassword }}',
host: '{{ mySQLserver }}',
port: '{{ mySQLport }}',
dbname: '{{ mySQLdefaultdb }}',
charset: 'utf8mb4',
prefix: '{{ mySQLprefix }}',
);
}
#[ArrayShape(SiteConfig::PATHS_ARRAY_SHAPE)]
function getPaths(): array
{
return [
'admin' => 'e107_admin/',
'core' => 'e107_system/',
'handlers' => 'e107_handlers/',
'images' => 'e107_images/',
'languages' => 'e107_languages/',
'media' => 'e107_media/',
'plugins' => 'e107_plugins/',
'system' => 'e107_system/',
'themes' => 'e107_themes/',
'web' => 'e107_web/',
'docs' => 'e107_docs/',
'files' => 'e107_files/',
];
}
function defineGlobals(): void
{
// define('e_DEBUG', true); // Enable debug mode to allow displaying of errors
// define('e_HTTP_STATIC', 'https://static.mydomain.com/'); // Use a static subdomain for js/css/images etc.
// define('e_MOD_REWRITE_STATIC', true); // Rewrite static image urls.
// define('e_LOG_CRITICAL', true); // log critical errors but do not display them to user.
// define('e_GIT', 'path-to-git'); // Path to GIT for developers
// define('X-FRAME-SAMEORIGIN', false); // Option to override X-Frame-Options
// define('e_PDO, true); // Enable PDO mode (used in PHP > 7 and when mysql_* methods are not available)
}
}
return new E107Config();This template has the following advantages:
- The database configuration can be defined flexibly by implementing the
DatabaseConnectorinterface. Plugins or other core components can provide their own implementations of the interface to support different database types or connection methods. - The system paths are grouped together in a single method.
- The provider pattern allows us to defer the loading of the configuration until each scope (paths, database, or globals) is needed.
- Arbitrary (legacy) code moved into the
defineGlobals()method allows us to defer and disable the execution of this code in the future. Administrators can then test their installation with the legacy code disabled and report any issues. - The configuration follows a clearly defined schema that can be validated with static code analysis.
- The configuration is passed to the caller as an object, which allows for a structured handoff.
- With that ending return, the caller can also detect whether the old or the new configuration format is used and select the appropriate adapter.
To use this structured approach, the following interface is defined prior to loading e107_config.php:
/**
* Interface for the return value of including e107_config.php
*/
interface SiteConfig
{
const PATHS_ARRAY_SHAPE = [
// Current paths
'admin' => 'string', // Admin area files
'core' => 'string', // System assets
'handlers' => 'string', // System backend framework
'images' => 'string', // System images
'languages' => 'string', // Locale files
'media' => 'string', // Uploaded files
'plugins' => 'string', // System plugins
'system' => 'string', // Runtime-generated site files
'themes' => 'string', // System themes
'web' => 'string', // Frontend web libraries
// Legacy paths
'docs' => 'string', // Admin documentation
'files' => 'string', // e107 v1/v2 supplementary files
];
/**
* Base Paths
*
* Relative paths to the directories of each kind of e107 resource
*
* e107 will append site-specific paths to these base paths.
*
* @return array Associative array of relative paths
*/
#[ArrayShape(SiteConfig::PATHS_ARRAY_SHAPE)]
function getPaths(): array;
/**
* Database Connection Settings
*
* How to connect to the database
*
* @return DatabaseConnector The database connection settings
*/
function getDatabase(): DatabaseConnector;
/**
* Set legacy global constants
*
* @deprecated v2.4.0 Global constants are being phased out in favor of configurable settings elsewhere.
*
* @example
* define('e_DEBUG', true); // Enable debug mode to allow displaying of errors
* define('e_HTTP_STATIC', 'https://static.mydomain.com/'); // Use a static subdomain for js/css/images etc.
* define('e_MOD_REWRITE_STATIC', true); // Rewrite static image urls.
* define('e_LOG_CRITICAL', true); // log critical errors but do not display them to user.
* define('e_GIT', 'path-to-git'); // Path to GIT for developers
* define('X-FRAME-SAMEORIGIN', false); // Option to override X-Frame-Options
* define('e_PDO, true); // Enable PDO mode (used in PHP > 7 and when mysql_* methods are not available)
*/
function defineGlobals(): void;
}To shield the concrete implementation from new methods that might be added to the interface in the future, the interface is extended by an abstract class:
/**
* Dummy class implementing the {@see SiteConfig} interface
*/
abstract class BaseSiteConfig implements SiteConfig
{
/**
* @inheritDoc
*/
abstract function getDatabase(): DatabaseConnector;
/**
* @inheritDoc
*/
abstract function getPaths(): array;
/**
* @inheritDoc
*/
abstract function defineGlobals(): void;
}Optional Sensible Defaults
We could go a step further and inherit sensible defaults, but this would obfuscate what configurable options are available in the concrete implementation in e107_config.php.
Such a default implementation could look like this:
/**
* Partial {@see SiteConfig} implementation with default paths and no global constants
*
* {@see SiteConfig::getDatabase()} must be implemented by the concrete class.
*/
abstract class DefaultSiteConfig implements SiteConfig
{
const DEFAULT_PATH_ADMIN = 'admin/';
const DEFAULT_PATH_CORE = 'core/';
const DEFAULT_PATH_HANDLERS = 'handlers/';
const DEFAULT_PATH_IMAGES = 'images/';
const DEFAULT_PATH_LANGUAGES = 'languages/';
const DEFAULT_PATH_MEDIA = 'media/';
const DEFAULT_PATH_PLUGINS = 'plugins/';
const DEFAULT_PATH_SYSTEM = 'system/';
const DEFAULT_PATH_THEMES = 'themes/';
const DEFAULT_PATH_WEB = 'web/';
const DEFAULT_PATH_DOCS = 'docs/';
const DEFAULT_PATH_FILES = 'files/';
protected function pathPrefix(): string
{
return "e107_";
}
/**
* @inheritDoc
*/
#[ArrayShape(SiteConfig::PATHS_ARRAY_SHAPE)]
function getPaths(): array
{
$pathPrefix = $this->pathPrefix();
return [
'admin' => $pathPrefix . self::DEFAULT_PATH_ADMIN,
'core' => $pathPrefix . self::DEFAULT_PATH_CORE,
'handlers' => $pathPrefix . self::DEFAULT_PATH_HANDLERS,
'images' => $pathPrefix . self::DEFAULT_PATH_IMAGES,
'languages' => $pathPrefix . self::DEFAULT_PATH_LANGUAGES,
'media' => $pathPrefix . self::DEFAULT_PATH_MEDIA,
'plugins' => $pathPrefix . self::DEFAULT_PATH_PLUGINS,
'system' => $pathPrefix . self::DEFAULT_PATH_SYSTEM,
'themes' => $pathPrefix . self::DEFAULT_PATH_THEMES,
'web' => $pathPrefix . self::DEFAULT_PATH_WEB,
'docs' => $pathPrefix . self::DEFAULT_PATH_DOCS,
'files' => $pathPrefix . self::DEFAULT_PATH_FILES,
];
}
/**
* @inheritDoc
*/
function defineGlobals(): void
{
}
}DatabaseConnector
The DatabaseConnector is a simple interface that returns the database abstraction layer (DBAL):
interface DatabaseConnector
{
/**
* Get a new database connection
*
* @return e_db The database abstraction layer
*/
function connect(): e_db;
}Implementations will be autoloaded from the core in e107_handlers/Database/Connection or from plugins.
The core will provide the following implementations:
MysqlConnector < DatabaseConnectorfor MySQL or MariaDB connectionsMysqlTcpConnector < MysqlConnectorfor MySQL connections via TCPMysqlTlsConnector < MysqlTcpConnectorfor encrypted MySQL connections via TCPMysqlSocketConnector < MysqlConnectorfor MySQL connections via a UNIX socket
DsnConnector < DatabaseConnectorfor connections from a DSN string as an alternative and compact way to define the database connection. (A DSN string might look like:mysql://user:password@localhost:3306/database?charset=utf8mb4)
Although not in the scope of this RFC, this plug-in architecture could be extended to support more database types. Hypothetical examples could be:
PgsqlConnector < DatabaseConnectorfor PostgreSQL connectionsSqliteConnector < DatabaseConnectorfor SQLite file connectionsSqlsrvConnector < DatabaseConnectorfor Microsoft SQL Server connectionsOracleConnector < DatabaseConnectorfor Oracle connectionsDb2Connector < DatabaseConnectorfor IBM DB2 connections
Backwards-Compatibility Adapter
Using just the new configuration file format in the core would be simple:
$config = include(e_ROOT . 'e107_config.php');
// Connect to the database
$db = $config->getDatabase()->connect();
// Get the handler path
$handlerPath = $config->getPaths()['handlers'];To transition from the old configuration file format to the new one, we will need to detect which format is used and wrap the old configuration file values in an adapter:
$config = include(e_ROOT . 'e107_config.php');
if (!($config instanceof SiteConfig)) {
$config = new V2ConfigAdapter();
}V2ConfigAdapter will implement the SiteConfig interface and wrap the old configuration file values:
/**
* Adapter for the old e107 v2 configuration file format
*/
class V2ConfigAdapter implements SiteConfig
{
protected const DATABASE_CREDENTIAL_DEFAULTS = [
'prefix' => '',
'port' => '3306',
'charset' => 'utf8mb4',
];
protected const LEGACY_DATABASE_VARIABLES = [
'prefix' => 'mySQLprefix',
'host' => 'mySQLserver',
'port' => 'mySQLport',
'name' => 'mySQLdefaultdb',
'username' => 'mySQLuser',
'password' => 'mySQLpassword',
'charset' => 'mySQLcharset',
];
protected const LEGACY_PATH_VARIABLES = [
'admin' => 'ADMIN_DIRECTORY',
'core' => 'CORE_DIRECTORY',
'docs' => 'DOCS_DIRECTORY',
'help' => 'HELP_DIRECTORY',
'files' => 'FILES_DIRECTORY',
'handlers' => 'HANDLERS_DIRECTORY',
'images' => 'IMAGES_DIRECTORY',
'languages' => 'LANGUAGES_DIRECTORY',
'media' => 'MEDIA_DIRECTORY',
'plugins' => 'PLUGINS_DIRECTORY',
'system' => 'SYSTEM_DIRECTORY',
'themes' => 'THEMES_DIRECTORY',
'web' => 'WEB_DIRECTORY',
];
/**
* @inheritDoc
*/
function getDatabase(): DatabaseConnector
{
$credentials = self::DATABASE_CREDENTIAL_DEFAULTS;
foreach (self::LEGACY_DATABASE_VARIABLES as $key => $legacyVariable) {
$credentials[$key] = $$legacyVariable;
}
return new DsnConnector(
dsn: sprintf(
'mysql://%s:%s@%s:%s/%s?charset=%s',
$credentials['username'],
$credentials['password'],
$credentials['host'],
$credentials['port'],
$credentials['name'],
$credentials['charset'],
),
prefix: $credentials['prefix'],
);
}
/**
* @inheritDoc
*/
#[ArrayShape(SiteConfig::PATHS_ARRAY_SHAPE)]
function getPaths(): array
{
$paths = [];
foreach (self::LEGACY_PATH_VARIABLES as $key => $legacyVariable) {
$paths[$key] = constant($legacyVariable);
}
return $paths;
}
/**
* @inheritDoc
*/
function defineGlobals(): void
{
include_once(e_ROOT . 'e107_config.php');
}
}Migration
The old configuration file format can likely be migrated to the new one automatically by a script that reads the old configuration file and replaces it with the new one.
A PHP parser is not required because the configuration loaded by the adapter (V2ConfigAdapter) can be rewritten into the new format template, and all the other code can be wrapped within the SiteConfig::defineGlobals() method.
CaMer0n
Jimmi08
Motivation
Currently it's a mess of different formats.
Proposed Solution
Return a multi-dimensional array. As an example:
or an Object:
Alternatives
-
Additional Context
No response