adding framework 101 to provide a basic explanation of the core setup

Pep 2014-04-10 15:42:48 -07:00
parent f1569007e1
commit 558a058172
1 changed files with 57 additions and 0 deletions

57
Getting-started.md Normal file

@ -0,0 +1,57 @@
The goal of this article is to provide the reader with a quick introduction to the setup of the phpservermon project.
## Namespace
All code related to phpservermon lives in the psm namespace, which can be found under "src/psm".
## Bootstrap
The [bootstrap file](https://github.com/phpservermon/phpservermon/blob/develop/src/bootstrap.php) located in the "src/" directory is the starting point of the application. It makes sure that:
* The database config is loaded.
* Autoload function is registered.
* All functions, constants etc are loaded.
* Database connection is set up and working properly.
* Database version corresponds with code version.
* Config from database table is loaded.
## Router
The [Router](https://github.com/phpservermon/phpservermon/blob/develop/src/psm/Router.class.php) is used to load the modules. All modules are registered inside the Router class with a unique ID (see getModules()), and can either be loaded manually ($router->run('mod')), or if no module is given it will attempt to discover the module from the $_GET['mod'] var.
If no valid module or controller is found, it will fall back to the default module.
If the module and controller ID are valid and the user level check validates (see below), the module controller will be loaded.
### Loading a module
The $mod (manually) or $_GET\['mod'\] (automatic detection) var is used by the Router to determine what to load. The var may exist of 2 parts, separated by an underscore. The first part is the ID of the module, and the second part is the ID of the controller registered in the module. If no controller ID is found, it will attempt to load the controller with the same ID as the module.
Examples:
* $router->run('config'): module ID "config" and controller ID also "config" (same as $router->run('config_config'))
* $router->run('server_status'): module ID "server" and controller ID "status"
### User level check
Each controller can provide a minimum user level required to open it (see setMinUserLevelRequired()). The Router will validate the level of the user, and if it does not match the minimum user level required, it will provide an "Insufficient privileges" error and not load the controller.
If the user is not logged in, it will automatically load the user login controller without throwing an error.
## Modules
Each module has its own directory under "src/psm/Module". A module consists of:
* One class implementing the [ModuleInterface](/phpservermon/phpservermon/blob/develop/src/psm/Module/ModuleInterface.class.php) with a list of available controllers.
* One directory named "Controllers" with the available controllers (all implementing the [ControllerInterface](/phpservermon/phpservermon/blob/develop/src/psm/Module/ControllerInterface.class.php) ).
Before a module can be loaded, it must be registered inside the Router. Currently it needs to be added manually to the getModules() method in the Router class.
## Controllers
One module can be divided up into several controllers to keep functionality separated. For example, the user module can separated in the LoginController and ProfileController.
All controllers must be registered in the module class before it can be loaded from the router.
While all controllers only need to implement the [ControllerInterface](/phpservermon/phpservermon/blob/develop/src/psm/Module/ControllerInterface.class.php), it is recommended to have a look at the [AbstractController](/phpservermon/phpservermon/blob/develop/src/psm/Module/AbstractController.class.php) as it provides a lot of basic functionality for your controller.
### Actions
@todo