MagratheaPHP2
Up to date Narrative last written —; no source changes since. Method signatures below are reflected live.

MagratheaPHP — Main Entry Point

File: src/MagratheaPHP.php Namespace: Magrathea2 Extends: Singleton

The central bootstrap class for any MagratheaPHP2 application. Manages the app root path, autoloading, environment mode, configuration loading, and database connection. Uses the Singleton pattern — always access via MagratheaPHP::Instance().


Properties

PropertyTypeDescription
$appRootstringRoot directory of the application
$magRootstringProject root: AppPath()'s parent folder (holds configs/); not the framework's folder (that's GetMagratheaRoot())
$codeFolderarray<string>Folders the autoloader searches for <ClassName>.php (see Global Functions & Autoloader)
$versionRequired?stringMinimum required Magrathea version

Static Methods

LoadVendor(): void

Deprecated since 2.4.0, removed in 3.0. Require vendor/autoload.php yourself instead.

Requires Composer's vendor/autoload.php (require_once): the framework's own in a standalone checkout, the project's when the framework is installed as a dependency; throws MagratheaException if neither exists. Before 2.4.0 it only looked for the second one, so it failed with a fatal error in a standalone checkout. Since MagratheaPHP itself is only loadable after vendor/autoload.php has been required, calling it never does anything useful; it's not what registers Magrathea's autoloader (Composer's files autoload of src/_Functions.php does that).

Version(): string

Returns the current framework version string.

echo MagratheaPHP::Version(); // "2.1.24"

Returns a link to the official online documentation.

Test(): void

Runs internal self-test of the framework.


Instance Methods (Fluent Interface)

All instance methods return $this for chaining unless otherwise stated.

AppPath(string $path): MagratheaPHP

Sets the application root directory. Must be called first.

MagratheaPHP::Instance()->AppPath(__DIR__);

GetAppRoot(): string

Returns the currently set application root path.

GetMagratheaRoot(): string

Returns the framework's own root path.

MinVersion(string $version, bool $throwEx = false): MagratheaPHP

Asserts the running framework version is at least $version. If $throwEx is true, throws an exception on failure.

MagratheaPHP::Instance()->MinVersion("2.1.0");

AddCodeFolder(...$folder): MagratheaPHP

Registers folders for the autoloader, as given: absolute paths, or paths relative to the current working directory (under a web server, the entry script's folder), not to $appRoot. For folders inside the app, use AddRootCodeFolder().

$app->AddCodeFolder(__DIR__."/models", "/var/www/shared/lib");

AddRootCodeFolder(...$folder): MagratheaPHP

Same as AddCodeFolder(), with each path prefixed by $appRoot/. Call it after AppPath().

$app->AddRootCodeFolder("models", "controls", "services"); // <appRoot>/models, ...

AddFeature(...$features): MagratheaPHP

For each feature name, registers <appRoot>/features/<Name> and <appRoot>/features/<Name>/Base for the autoloader. Call it after AppPath().

AppNamespace(string $namespace): MagratheaPHP

Sets the project's root namespace (e.g. "App"). In DEV, a class in that namespace that the autoloader can't find adds a "Could not find class [...]. Are the code folders correct?" debug item. Since 2.4.0 it no longer throws: class_exists() returns false and new fails with PHP's Error: Class "…" not found.

Dev(): MagratheaPHP

Enables development mode: error_reporting(E_ALL), display_errors and log_errors on, and Debugger::DEV. Like Prod() and Debug(), it doesn't choose the config environment: that's general/use_environment or Config::Instance()->SetEnvironment().

Debug(): MagratheaPHP

Enables debug mode: Debugger::DEBUG (debug items are stored and printed at the end of the request; API responses carry them in _debug) + database query logging. It doesn't change PHP's error display, unlike Dev().

Prod(): MagratheaPHP

Enables production mode: Debugger::LOG (debug items and exceptions go to the log file). It doesn't touch PHP's display_errors: turn that off in php.ini (or with ini_set()) on servers.

Load(): MagratheaPHP

Loads the configuration file. Must be called after AppPath() and the desired mode. If the active environment has a timezone key, it's set as PHP's timezone (date_default_timezone_set()); an invalid name is ignored and PHP stays on php.ini's default. The key is timezone, not time_zone (see the Config page).

GetConfigRoot(): string

Returns the path to the configuration directory: configs/ in AppPath()'s parent folder (<magRoot>/configs).

StartDB(): MagratheaPHP / Connect(): MagratheaPHP

Sets the database connection from the active environment's config keys db_host, db_name, db_user, db_pass and db_port (optional; without it, mysqli's default port is used. Before 2.4.0, db_port was ignored). StartDB is an alias for Connect. Nothing is opened yet: the connection opens on the first query and stays open for the rest of the request (see the Database page).

With a timezone in the config, it also turns on the MySQL timezone sync (Database::SetTimezoneSync()): each new connection sets MySQL's session time_zone to PHP's. db_sync_timezone = false turns it off.

$app->Connect();
// or
$app->StartDB();

GetDB(): Database

Returns the active Database singleton instance.

$db = MagratheaPHP::Instance()->GetDB();

StartSession(): MagratheaPHP

Calls session_start() if no session is active.

AppVersion(): string

Reads the app version from <magRoot>/version and removes trailing line breaks (\n / \r\n).


Full Bootstrap Chain

<?php
require_once __DIR__ . '/vendor/autoload.php';

use Magrathea2\MagratheaPHP;

$app = MagratheaPHP::Instance()
    ->AppPath(__DIR__)
    ->MinVersion("2.1.0")
    ->AddRootCodeFolder("models", "controls", "api")
    ->Dev()                 // swap for ->Prod() in production
    ->Load()
    ->StartSession()
    ->Connect();

Debug Modes Comparison

These set the Debugger mode only; the config environment ([dev], [production], …) is chosen by general/use_environment or Config::SetEnvironment(), never by these methods.

MethodPHP error displayQuery LoggingDebug items / exceptions
Dev()Turned on (display_errors, E_ALL)OffPrinted where they're added (DEV)
Debug()UnchangedOnStored, printed at the end of the request (DEBUG)
Prod()Unchanged (set it in php.ini)OffWritten to the log (LOG)

Notes

Class Reference — MagratheaPHP

Magrathea2\MagratheaPHP extends Singleton /home/platypusweb/platypusweb.com.br/site/magratheaphp2/src/MagratheaPHP.php

Base class for a Magrathea project. It handles paths, configurations, database connections, and environments.

AddCodeFolder(...$folder): Magrathea2\MagratheaPHP

Adds one or more code folders for the autoloader.

ParamTypeDefault
$folder mixed —
AddFeature(...$features): Magrathea2\MagratheaPHP

Adds feature folders based on the application root. For each feature, it adds `features/[name]` and `features/[name]/Base`.

ParamTypeDefault
$features mixed —
AddRootCodeFolder(...$folder): Magrathea2\MagratheaPHP
ParamTypeDefault
$folder mixed —
AppNamespace(string $namespace): Magrathea2\MagratheaPHP

Sets the project's root namespace, used to scope autoloader errors. Only classes within this namespace will trigger a MagratheaException when not found.

ParamTypeDefault
$namespace string required
AppPath(string $path): Magrathea2\MagratheaPHP

Sets the application's root path. Also defines the `magRoot` as the parent directory.

ParamTypeDefault
$path string required
AppVersion(): string

Gets the version of the application from the `version` file in the project root.

Connect()

Connects to the database using credentials from the configuration.

Debug(): Magrathea2\MagratheaPHP

Enables the debugger. This will also log database queries.

Dev(): Magrathea2\MagratheaPHP

Sets the environment to development mode. Enables error reporting and display.

GetAppRoot(): string

Returns the root path of the application.

GetConfigRoot()

Gets the path to the configuration directory.

GetDB(): Magrathea2\DB\Database

Gets the singleton instance of the Database object.

GetMagratheaRoot(): string

Gets the root directory of the MagratheaPHP library.

Load()

Starts Magrathea

MinVersion(string $version, bool $throwEx = false)

Checks if the current Magrathea version meets a minimum requirement. Otherwise, it displays an error message.

ParamTypeDefault
$version string required
$throwEx bool false
Prod(): Magrathea2\MagratheaPHP

Sets the environment to production mode. Errors will be sent to the logger instead of being displayed.

StartDB()

Connects to the database. Alias for `Connect()`.

StartSession(): Magrathea2\MagratheaPHP

Starts a PHP session if one is not already active.

static LoadVendor(): void

Includes the Composer autoloader.

static Test(): void

A simple test function to check if MagratheaPHP is working.

static Version(): string

Gets Magrathea Version

Examples