Jingga/Developer-Guide
1
0
Fork 0
mirror of https://github.com/Karaka-Management/Developer-Guide.git synced 2026-01-11 20:38:42 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merging develop

Browse Source
This commit is contained in:
Dennis Eichhorn 2016-07-12 18:26:46 +02:00
commit 57b62c7f28
18 changed files with 740 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
README.md
View File

@ -1,17 +1,5 @@
# Introduction
This developer guides intention is to provide useful information
for developers to help you to understand the structure of the
application, important classes, workflows and standards for
code quality as well as code style. The intention is to provide
enough information to get a basic understanding of these
key elements for module developers, frontend developers or
developers working on the core application.
This developer guides intention is to provide useful information for developers to help you to understand the structure of the application, important classes, workflows and standards for code quality as well as code style. The intention is to provide enough information to get a basic understanding of these key elements for module developers, frontend developers or developers working on the core application.
The guide is **not** explaining in detail how to use classes,
for this you can find the automatically generated code
documentation. All the provided information are very important
to ensure the quality of the published code and often are mandatory.
Not following these guides can cause security issues, worsen the
user experience or even cause malfunction as well as make it
difficult for other developers to understand the code.
The guide is **not** explaining in detail how to use classes, for this you can find the automatically generated code documentation. All the provided information are very important to ensure the quality of the published code and often are mandatory. Not following these guides can cause security issues, worsen the user experience or even cause malfunction as well as make it difficult for other developers to understand the code.

26
SUMMARY.md
View File

@ -1,6 +1,28 @@
# Summary
* [Introduction](README.md)
* [Security Guidelines](security_guidelines.md)
* [Inspections, Tests & Code Guidelines](inspections,_tests_&_code_guidelines.md)
## Setup
* [Installation](setup/installation.md)
* [Dev Environment](setup/dev_environment.md)
## Standards
* [General](standards/general.md)
* [Documentation](standards/documentation.md)
* [Html](standards/html.md)
* [Php](standards/php.md)
## Security
* [Security Guidelines](security/security_guidelines.md)
## Code Quality
* [Code Quality](quality/code_quality.md)
* [Inspections](quality/inspections.md)
* [Tests](quality/tests.md)
## Frontend
* [Styles and Layout](frontend/styles_and_layout.md)
## Components
* [Caching, Sessions, Local Storage & Cookies](components/caching,_sessions,_local_storage_&_cookies.md)
* [Modules](components/modules.md)

46
components/caching,_sessions,_local_storage_&_cookies.md Normal file
View File

@ -0,0 +1,46 @@
# Caching, Sessions, Local Storage & Cookies
## Caching
For caching the `CacheManager` provides access to the caching systems in place. Out of the box the CacheManager supports and automatically initializes either Redis or Memcached depending on the client configuration. The caching is not mandatory and therfor shouldn't be missuesed as in-memory database. It is not necessary to check if Redis or Memcached are available the CacheManager automatically handles the caching based on their existence.
### HTTP Cache
By default only stylesheets, javascript and layout images as well as module images are cached. Everything else is considered volatile and not cached. If a response specific response should be cached feel free to use the response header:
Example usage for 30 days caching:
```
$resposne->setHeader('Cache-Control', 'Cache-Control: max-age=2592000');
```
In order to trigger a re-cache of stylesheets or javascript files make sure to update the version in the `Controller.php` file. This way version updates will result in a new virtual file uri and result in a re-cache.
Example usage:
```
$head->addAsset(AssetType::JS, $request->getUri()->getBase() . 'Modules/Media/Controller.js?v=' . self::MODULE_VERSION);
```
## Sessions
Sessions are handled via the `SessionManager`. Sessions can be set and manipulated from the web application as well as the socket or console application.
### HTTP
The Http session will be saved automatically, there is no need to access the super global `$_SESSION`. Make sure to only modify session data using the SessionManager
### Socket & Console
The session will be stored and assoziated with the logged in user in memory. A disconnect or quit is considered as a logout and therefor results in the destruction of the session object of this user and will be empty for the next login.
## Local Storage
## Cookies
### PHP
Only use cookies when absolutely necessary. Most of the time session data or local storage is the prefered choice. The `CookieJar` class provides you with all the necessary functionality similar to the `SessionManager`. The super global `$_COOKIE` is also overwritten and shouldn't be used anywhere.
### JavaScript

4
components/datamapper_&_query_builder.md Normal file
View File

@ -0,0 +1,4 @@
# DataMapper & Query Builder

158
components/modules.md Normal file
View File

@ -0,0 +1,158 @@
# Modules
The following directory structure should roughly visualize how modules are strucured. The purpose of the different sub-directories and their files will be covered in the following sections.
* {UniqueModuleName}
* Admin
* Install
* Navigation.install.json
* Navigation.php
* Update
* yourUpdateFiles.???
* Activate.php
* Deactivate.php
* Installer.php
* Uninstall.php
* Update.php
* Img
* modulePreviewImage.jpg
* Models
* YourPhPModels.php
* YourJavaScriptModels.js
* Theme
* Backend
* Css
* yourCss_1.0.0.css
* yourScss_1.0.0.scss
* Img
* yourTemplateImages.jpg
* Lang
* en.lang.php
* Navigation.en.lang.php
* your_template_files.tpl.php
* Views
* YourPhpViews.php
* YourJavaScriptViews.js
* Controller.php
* Controller.js
* info.json
All modules are located inside the `/Modules` directory and their directory name has to be the module name itself without whitespaces.
## Admin
The admin directory contains the install directory as well as the install, delete, update, activate and deactivate script assoziated with this module. The install directory contains installation files required for other modules. The above example contains the two required files for providing navigation information to the navigation module so that the navigation module can display this module in the navigation bar. The navigation installation file as well as all other module installation files must have the same name as the navigation module and will be automatically called on installation if defined in the info.json file.
The content of the navigation install file highly depends on the module and should be documented in the according module. The additional json file is also required by the navigation module for the installation process. How many additional files and how they have to be structured/named should all be documented in the module documentation. If your module doesn't provide any navigation links or in general doesn't use any other modules, your install directory will be empty.
Some modules can be used without requiring any additional installations it all depends on how the other modules got implemented. Thats also why many modules don't offer any integration at all and
are almost stand-alone without the possibility to get extended.
### Installer.php
In contrast to the install file for other moduels this file has to follow more strict standards. The following example shows you the bare minimum requirements of a installation file:
```
<?php
namespace Modules\Navigation\Admin;
use phpOMS\DataStorage\Database\DatabaseType;
use phpOMS\DataStorage\Database\Pool;
use phpOMS\Module\InfoManager;
use phpOMS\Module\InstallerAbstract;
class Installer extends InstallerAbstract
{
public static function install(Pool $dbPool, InfoManager $info)
{
parent::install($dbPool, $info);
switch ($dbPool->get('core')->getType()) {
case DatabaseType::MYSQL:
/* Your database setup goes here */
break;
}
}
}
```
If your application doesn't need to implement any database tables for itself the switch statement can be omitted. From the directory structur at the beginning we can however see that some modules accept information form other modules. The following example shows how the navigation module is accepting information during the installation of other modules:
```
public static function installExternal(Pool $dbPool, array $data)
{
/* What do you want to do with the data provided by $data? */
}
```
Other modules have to create a Navigation.php file inside the install directory with the following method:
```
public static function install(Pool $dbPool)
{
$navData = json_decode(file_get_contents(__DIR__ . '/Navigation.install.json'), true);
$class = '\\Modules\\Navigation\\Admin\\Installer';
$class::installExternal($dbPool, $navData);
}
```
How the receiving module (e.g. Navigation) is accepting information depends on the module itself. The module documentation will also state how the content of the `install(...)` method has to look like. At the same time if you write a module and are accepting information from other modules during their installation you have to document very well how they have to provide these information. Very often however it will not be necessary to let other modules pass these information during installation and only do this during runtime.
The navigation module is a good example of passing navigation links during installation. The navigation module could request the link information during runtime this would mean that all modules would have to be initialized for every request since the navigation module doesn't know if these modules are providing links or not. By providing these information during the installation, the navigation module can store these information in a database table and query these information for every page request without initializing all modules or performing some file readings.
### Update.php
### Uninstall.php
### Activate.php
### Deactivate.php
## Img
All module specific images (not theme specific images). E.g. Module preview images showing when searching for modules.
## Models
All models and data mapper classes should be stored in here (PHP & JS). How to create a data mapper for a model is described in the data mapper chapter. All JavaScript files need to be provided unoptimized (not minified or concatenated).
## Theme
The Theme directory contains the current theme for every page this module supports. If a module only supports the backend application there will only be a Backend directory containing the theme for the backend.
### Css
Every page has its own CSS directory. This application only allows the use of SASS/SCSS as preprocessor. All sass/scss files need to be provided as well as the processed CSS files. Make sure to update the version number in the `Controller.php` file. CSS files need to be minimized and if it makes sense concatenated.
### Img
This directory contains all images for this page.
### Lang
The Lang directory contains all language files for this application. Usually there is one language file for the page which will be loaded automatically wherever the module gets loaded (this language file has to exist).
A language file should have the following naming convention:
{ISO 639-1}.lang.php
{UniqueModuleName}.{ISO 639-1}.lang.php
The content of the language file is straight forward:
```
<?php
$return [ '{UniqueModuleName}' => [
'StringID' => 'Your localized string',
]];
```
All other language files are optional and usually are only required by other modules. The navigation module for example requires an extra language file for the navigation elements. This however should be specified in the modules you want to make use of.
## Views
## Controller.php
## Controller.js
## info.json

19
frontend/styles_and_layout.md Normal file
View File

@ -0,0 +1,19 @@
# Styles and Layout
## Css
This project only supports scss and css. All css files need to be provided with a scss file which will be processed for every build. The css file has to be minimized, optimized and compressed as `.gz`. This means there is at least one scss file (multiple if you are combining/importing multiple scss files and creating one output css file), one css file and one compressed `.gz` file. The file name has to be lower case and the same for every file and only the extension is different.
## Icons
This project uses font-awesome for its icons, the following example allows for stacked icons e.g. creating new/undread email notifications:
```
<i class="fa fa-lg infoIcon fa-envelope">
<span class="badge">333</span>
</i>
```
## Examples
An example of all styles can be found in the tests called `StandardElements.htm`.

14
inspections,_tests_&_code_guidelines.md
View File

@ -1,14 +0,0 @@
# Inspections, Tests & Code Guidelines
Running inspections and tests ensures the quality of the provided code. It
also helps to ensure multiple programmers follow the same standard which
helps to work on other programmers code.
## Unit tests
### PHPUnit
## Code style
## External tools

9
quality/code_quality.md Normal file
View File

@ -0,0 +1,9 @@
# Code Quality
## General
## Modules
### Langauge Files
Every provided language element in the language files SHOULD be used at least once by the module itself. Don't provide language elments that are only used by *optional* 3rd party modules.

23
quality/inspections.md Normal file
View File

@ -0,0 +1,23 @@
# Inspections
Code inspections are very important in order to maintain the same code quality throughout the application. The Build repository contains all esential configuration files for the respective inspection tools. Every provided module will be evaluated based on the predefined code and quality standards. Only modules that pass all code, quality and unit tests are accepted. This also applies to updates and bug fixes. Any change will have to be re-evaluated.
## Tools
Tools used for the code inspection are:
* PhpMessDetector
* PhpMetrics
* PhpDepend
* PhpCS
* PhpCPD
* PhpUnit (see tests)
* Jasmine (see tests)
* Custom scripts/tools
These tools are all installed by running the `setup.sh` script from the Build repository.
## Configurations
### PhpMessDetector

15
quality/tests.md Normal file
View File

@ -0,0 +1,15 @@
# Tests
The applications goal is to achive 90% code coverage, which applies for the core application as well as all modules. All unit tests are located in a separate repository `Tests`.
## PHPUnit
This application uses PHPUnit as unit testing framework. The PHPUnit directory is structured the same way as the `Framework`, `Modules`, `Install` and `Models` directories. Unit tests for specific classes need to be named in the same manner as the testing class.
### Modules
Every module needs to have a `Admin` directory containing a class called `AdminTest.php` which is used for testing the installation, activation, deactivation, uninstall and remove of the module. Tests that install, update, remove etc. a module need to have a group called `admin`. After running the `AdminTest.php` test the final state of the module should be installed and active, only this way it's possible to further test the controller and models. A code coverage of 80% is mandatory for every module for integration.
## Jasmine
The javascript testing is done with jasmine. The javascript testing directory is structured the same way as the `Framework`. Unit tests for specific classes need to be named in the same manner as the testing class.

0
security/README.md
View File

105
security/security_guidelines.md
View File

@ -2,10 +2,7 @@
## CSRF
The tool to protect clients from CSRF is a randomly generated CSRF token,
that can be used inside the URI generator. It's highly recomended to make
use of this token whenever possible to reduce the risk of CSRF
attacks.
The tool to protect clients from CSRF is a randomly generated CSRF token, that can be used inside the URI generator. It's highly recomended to make use of this token whenever possible to reduce the risk of CSRF attacks.
Example usage:
@ -15,63 +12,93 @@ Example usage:
</form>
```
Now the application will receive the automatically generated CSRF token as
query parameter for further use. If the CSRF token is not the same as the one
assoziated with the client on the server side the client will receive a 403
HTTP response. The CSRF however doesn't have be specified, if that's the case
**every module itself must make sure wheter a valid CSRF token is required**
or not. The reason for this is that third party requests are a possibility as
well, and sharing the private CSRF token would render it useless.
Now the application will receive the automatically generated CSRF token as query parameter for further use. If the CSRF token is not the same as the one assoziated with the client on the server side the client will receive a 403 HTTP response. The CSRF however doesn't have be specified, if that's the case **every module itself must make sure wheter a valid CSRF token is required** or not. The reason for this is that third party requests are a possibility as well, and sharing the private CSRF token would render it useless.
Since the validation of the CSRF token is performed automatically it is only
necessary to check the existence, since if it exists it has to be valid.
Since the validation of the CSRF token is performed automatically it is only necessary to check the existence, since if it exists it has to be valid.
Example usage in a module handling a API request:
```
if($request->getData('CSRF') === null) {
$response->setStatusCode(403);
$response->setStatusCode(RequestStatus::R_403);
/* optional */
$response->set($request->__toString(), new Notify('Unknown referrer!', NotifyType::INFO));
return;
}
```
### When do I check for the CSRF token validity/existence?
Always! Except the request has the potential to come from third party
referrers. Here a few examples of requests that must always have a valid CSRF
token:
Always! Except the request has the potential to come from third party referrers. Here a few examples of requests that must always have a valid CSRF token:
1. Login/logout
2. Creating/updating/deleting a news post
2. Creating/updating/deleting something
3. Uploading media files
4. Changes in user settings
Here some examples of requests that **MAY** not need a validation (mostly API
GET requests):
Here some examples of requests that **MAY** not need a validation (mostly API GET requests):
1. Get news posts
2. Get last log message
It's important to understand that the CSRF token is not equivalent with
authentication or API token. Client can be logged out and still need a
CSRF token and obviously vice versa.
It's important to understand that the CSRF token is not equivalent with authentication or API token. Clients can be logged out and still need a CSRF token and obviously vice versa.
## Headers
The following headers must be set for every web application. By default they are already set in the `WebApplication` which gets expanded by all other web applications.
### Content-Security-Policy
Scripts and frames must be provided by the own server or google. This is important in order to prevent the injection of other scripts and clickjacking. Inline javascript is prohibited and may only be defined in the application and not in any modules.
The default CSP looks like the following:
```
$response->getHeader()->set('content-security-policy', 'script-src \'self\'; frame-src \'self\'', true);
```
In order to whitelist inline javascript you can use the following logic. This however requires you to know the inline script beforehand `$script`. After setting the CSP header they automatically get locked so that further changes are not possible. This is a security measure in order to prevent any malicious adjustments.
```
$response->getHeader()->set('content-security-policy', 'script-src \'self\' \'sha256-' . base64_encode(hash('sha256', $script, true)) . '\'; frame-src \'self\'', true);
```
### X-XSS-Protection
This header tells the client browser to use local xss protection if available.
```
$response->getHeader()->set('x-xss-protection', '1; mode=block');
```
### X-Content-Type-Options
By using this header browsers which support this feature will ignore the content/mime and recognize the file by the provided header only.
```
$response->getHeader()->set('x-content-type-options', 'nosniff');
```
### X-Frame-Options
The x-frame-options is providing the same protection for frames as the content-security-policy header. Please only use this header in addition to the content-security-policy if you have to but make sure the rules don't contradict with the content-security-policy.
```
$response->getHeader()->set('x-frame-options', 'SAMEORIGIN');
```
## Super globals
Super globals are not available througout the application and the values can
only be accesed through middleware classes like:
Super globals are not available througout the application and the values can only be accesed through middleware classes like:
* SessionManager
* CookieJar
* Request
* Response
In some cases super globals will even be overwritten by values from these
classes before generating a response. Do not directly access super globals!
In some cases super globals will even be overwritten by values from these classes before generating a response. Do not directly access super globals!
## Input validation
@ -91,30 +118,22 @@ Be vigilant of where and how the path for the following scenarios comes from:
3. `file_get_contents('../relative/path/to/' . $path);`
4. `mkdir($path);`
These are just a few examples but it is very important to make sure, that
these paths only have access to wherever the programmer intended them for.
At first it is always a good idea to get the `$path = realpath($path)` of a
path in order to make sure the path exists and for further validation.
These are just a few examples but it is very important to make sure, that these paths only have access to wherever the programmer intended them for. At first it is always a good idea to get the `$path = realpath($path)` of a path in order to make sure the path exists and for further validation.
Example usage:
```
if(($pathNew = realpath($path)) === false || strpos($pathNew, ROOT_PATH . '/Modules/' . self::$module) === false) {
throw new FilePathException($path);
if(($pathNew = realpath($path)) === false || strpos($pathNew, self::MODULE_PATH) === false) {
throw new PathException($path);
}
```
The example throws an exception if the path either doesn't exist or is trying
to access a path that doesn't contain the path defined in
`ROOT_PATH . '/Modules/' . self::$module`. Another validation could be:
The example throws an exception if the path either doesn't exist or is trying to access a path that doesn't contain the path defined in `self::MODULE_PATH`. Another validation could be:
```
if(($pathNew = realpath($path)) === false || !Validator::startsWith($pathNew, ROOT_PATH)) {
throw new FilePathException($path);
throw new PathException($path);
}
```
This example now is not only checking if the path exists and if it contains a
path element, it also makes sure that the path is inside the application root
path. You could as easily replace `ROOT_PATH` with `self::MODULE_PATH` and this
validation would make sure `$path` only directs within a module.
This example now is not only checking if the path exists and if it contains a path element, it also makes sure that the path is inside the application root path. You could as easily replace `ROOT_PATH` with `self::MODULE_PATH` and this validation would make sure `$path` only directs within a module.

1
setup/dev_environment.md Normal file
View File

@ -0,0 +1 @@
# Dev Environment

54
setup/installation.md Normal file
View File

@ -0,0 +1,54 @@
# Installation
Installing the application as a developer can be achived by following one of the following instructions
## General
After installation following one of the instructions make sure you set the appropriate permissions for files and directories:
* 0700 Log
## Linux Shell Script
This is the prefered way to install the application since this also installs all required dev tools and sets up the direcetory structure by itself. Using this method also tears down previous installs for a fresh install perfect for re-installing from the current development version. Furthermore the use of phpUnit also makes sure that the application is working as intended. The phpUnit install also provides lots of dummy data for better integration and functionality testing of your own code/modules.
### Requirements
1. PHP 7.0
2. npm
3. xdebug or phpdbg
### Steps
1. Go somewhere where you want to install the build script
2. Enter `git clone -b develop https://github.com/Orange-Management/Build.git`
3. Modify `var.sh`
4. Run `chmod 777 setup.sh`
5. Run `./setup.sh`
6. Modify `config.php`
7. Run `php phpunit.phar --configuration Tests/PHPUnit/phpunit_default.xml` inside `Orange-Management` or open `http://your_url.com/Install`
### Annotation
The database user and password can't be changed right now since the install config relies on the same data. Future releases will make use of a new user that will get set up by the install script as well. If you don't have `xdebug` installed but `phpdbg` you can replace `php phpunit.phar ...` with `phpdbg -qrr phpunit.phar ...`.
## FTP Web Install
This only installs an application without any dev tools that may be required by other scripts in order to test your implementations.
### Requirements
1. PHP 7.0
2. xdebug or phpdbg
3. phpunit
### Steps
1. Download all Orange-Management repositories
2. Put all repositories inside the Orange-Management repository
3. Modify `config.php`
4. Run `php phpunit.phar --configuration Tests/PHPUnit/phpunit_default.xml` inside `Orange-Management` or open `http://your_url.com/Install`
### Annotation
Re-installing the application this way requires you to drop and re-create the database.

126
standards/documentation.md Normal file
View File

@ -0,0 +1,126 @@
# Documentation
## Php
The php documentation is based on PhpDocumentor, therefore only valid PhpDocumentor comments are valid for files, classes, functions/methods and (member) variables.
### File
A file documentation MUST be implemented in the following form:
```
/**
* File description
*
* PHP Version 7.0
*
* @category Category name
* @package Package name
* @author Your Author 1 <your@email.com>
* @author Your Author 2 <your.second@email.com>
* @copyright Orange Management
* @license OMS License 1.0
* @version 1.0.0
* @link http://your.url.com
*/
```
### Class
A class documentation MUST be implemented in the following form:
```
/**
* Class description.
*
* @category Category name
* @package Package name
* @author Your Author 1 <your@email.com>
* @author Your Author 2 <your.second@email.com>
* @license OMS License 1.0
* @link http://your.url.com
* @since 1.0.0
*/
```
#### Member
A member variable documentation MUST be implemented in the following form:
```
/**
* Member variable description.
*
* @var variable_type
* @since 1.0.0
*/
```
#### Function/Method
A function/method documentation MUST be implemented in the following form:
```
/**
* Function/method description.
*
* Optional example or more detailed description.
*
* @param variable_type $param1Name Parameter description
* @param variable_type $param2Name Parameter description
*
* @return return_type
*
* @since 1.0.0
* @author Your Author 2 <your.second@email.com>
*/
```
### Variable
Variable documentation is not mandatory and can be omitted. However it's recommended to use a variable documentation for objects and arrays of objects in templates for ide code completion.
Example:
```
/** @var TestObject[] $myArray */
```
## JavaScript
The javascript documentation is based on JsDoc, therefore only valid JsDoc comments are valid for all js files.
### File
### Class
#### Member
#### Function/Method
### Variable
## Scss
The scss documentation is based on SassDoc, therefore only valid SassDoc comments are valid for all scss files.
### File
```
////
// Documentation
//
// Optional example or more detailed description.
//
// @since 1.0.0
// @author Your Author 2 <your.second@email.com>
////
```
### Class
#### Member
#### Function/Method
### Variable

11
standards/general.md Normal file
View File

@ -0,0 +1,11 @@
# Code Standards
The following code standard is enforced in order to make it easier to update and maintain implementations.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
The term "class" refers to all classes, interfaces, and traits.
## Indention
The default indention MUST be 4 spaces.

38
standards/html.md Normal file
View File

@ -0,0 +1,38 @@
# Html
All html has to be html 5 compliant.
## Omitted closing tags
The following closing tags SHOULD be omitted:
* `</li>`
* `</option>`
* `</tr>`
* `</td>`
* `</th>`
* `</thead>`
* `</tbody>`
* `</tfoot>`
* `</head>`
* `</body>`
* `</html>`
The following tags MUST not specify a end tag (\\):
* `<br \>`
* `<meta \>`
* `<input \>`
* `<hr \>`
* `<img \>`
* `<link \>`
* `<source \>`
* `<embed \>`
## Accessible Rich Internet Applications
All modules and themes SHOULD be WAI-ARIA 2.0 compliant. For further reading please refere to https://www.w3.org/TR/WCAG20-TECHS/aria.
## Structured Data (Microdata)
For structured data https://schema.org/ SHOULD be used.

148
standards/php.md Normal file
View File

@ -0,0 +1,148 @@
# Php
The php code needs to be php 7 compliant. No php 7 deprecated or removed elements, functions or practices are allowed (e.g. short open tag).
## Php Tags
PHP code MUST use the long `<?php ?>` tags or the short-echo `<?= ?>` tags; it MUST NOT use the other tag variations.
## Character Encoding
PHP code MUST use only UTF-8 without BOM
## Side Effects
A file SHOULD declare new symbols (classes, functions, constants, etc.) and cause no other side effects, or it SHOULD execute logic with side effects, but SHOULD NOT do both.
The phrase "side effects" means execution of logic not directly related to declaring classes, functions, constants, etc., merely from including the file.
"Side effects" include but are not limited to: generating output, explicit use of require or include, connecting to external services, modifying ini settings, emitting errors or exceptions, modifying global or static variables, reading from or writing to a file, and so on.
## Namespace and Class Names
Namespaces and classes MUST follow an "autoloading" PSR: [PSR-0, PSR-4].
This means each class is in a file by itself, and is in a namespace of at least one level: a top-level vendor name.
Class names MUST be declared in StudlyCaps.
## Constants
Class constants MUST be declared in all upper case with underscore separators.
## Methods
Method names MUST be declared in camelCase().
## Php in html
Php code embedded into template files SHOULD use the alternative syntax for control structures in order to improve the readability:
```
if($a === 5) : ?>
<p>This is html</p>
<?php endif; ?>
```
## Deprecated functions and variables
The following functions and (super-) global variables MUST NOT be used.
* `extract()`
* `parse_str()`
* `int_set()`
* `putenv()`
* `eval()`
* `assert()`
* `system()`
* `shell_exec()`
* `create_function()`
* `call_user_func_array()`
* `call_user_func()`
* `url_exec()`
* `passthru()`
* `Java()`
* `COM()`
* `event_new()`
* `dotnet_load()`
* `runkit_function_rename()`
* `pcntl_signal()`
* `pcntl_alarm()`
* `register_tick_function()`
* `dl()`
* `pfsockopen()`
* `fsockopen()`
* `posix_mkfifo()`
* `posix_getlogin()`
* `posix_ttyname()`
* `posix_kill()`
* `posix_mkfifo()`
* `posix_setpgid()`
* `posix_setsid()`
* `posix_setuid()`
The following functions and (super-) global variables MAY only be used in the phpOMS Framework in special cases.
* `$_GET`
* `$_POST`
* `$_PUT`
* `$_DELETE`
* `$_SERVER`
* `header()`
* `mail()`
* `phpinfo()`
* `getenv()`
* `get_current_user()`
* `proc_get_status()`
* `get_cfg_var()`
* `disk_free_space()`
* `disk_total_space()`
* `diskfreespace()`
* `getcwd()`
* `getlastmo()`
* `getmygid()`
* `getmyinode()`
* `getmypid()`
* `getmyuid()`
* `proc_nice()`
* `proc_terminate()`
* `proc_close()`
* `pfsockopen()`
* `fsockopen()`
* `apache_child_terminate()`
* `posix_kill()`
* `posix_mkfifo()`
* `posix_setpgid()`
* `posix_setsid()`
* `posix_setuid()`
* `ftp_get()`
* `ftp_nb_get()`
* `register_shutdown_function()`
* `chown()`
* `chdir()`
* `chmod()`
* `chgrp()`
* `symlink()`
* `flock()`
* `socket_create()`
* `socket_connect()`
The usage of the following functions SHOULD be avoided and inspected for any kind of possible injection.
* `include()`
* `include_once()`
* `require()`
* `require_once()`
* `fopen()`
* `delete()`
* `copy()`
* `file()`
* `file_get_contents()`
* `file_put_contents()`
* `readfile()`
* `rename()`
* `symlink()`
* `rmdir()`
* `mkdir()`
* `touch()`
* `unlink()`