From a5d554ca261f429e0dd2ab45c570c9522df029d5 Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Tue, 29 Dec 2015 17:55:22 +0100 Subject: [PATCH 01/27] Init new chapters --- caching,_sessions,_local_storage_&_cookies.md | 57 +++++++++++++++++++ datamapper_&_query_builder.md | 4 ++ modules.md | 21 +++++++ 3 files changed, 82 insertions(+) create mode 100644 caching,_sessions,_local_storage_&_cookies.md create mode 100644 datamapper_&_query_builder.md create mode 100644 modules.md diff --git a/caching,_sessions,_local_storage_&_cookies.md b/caching,_sessions,_local_storage_&_cookies.md new file mode 100644 index 0000000..5876ca8 --- /dev/null +++ b/caching,_sessions,_local_storage_&_cookies.md @@ -0,0 +1,57 @@ +# 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 +include their version hash as file name. This way version updates will result +in a new file name and will be re-cached by the client browser. + +Example usage: + +``` +$head->addAsset(AssetType::JS, $request->getUri()->getBase() . 'Modules/Media/ModuleMedia_' . self::$version . '.js'); +``` + +## 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 \ No newline at end of file diff --git a/datamapper_&_query_builder.md b/datamapper_&_query_builder.md new file mode 100644 index 0000000..77d8789 --- /dev/null +++ b/datamapper_&_query_builder.md @@ -0,0 +1,4 @@ +# DataMapper & Query Builder + + + diff --git a/modules.md b/modules.md new file mode 100644 index 0000000..4a2021d --- /dev/null +++ b/modules.md @@ -0,0 +1,21 @@ +# Modules + +## Info + +## Install + +## Update + +## Uninstall + +## Routing + +## Model, View, Controller, Template + +## Resources + +## Providing + +## Requesting + +## Receiving \ No newline at end of file From 260f04e2e55d35460920be907c3b735b2aa5f6ce Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Tue, 29 Dec 2015 18:25:53 +0100 Subject: [PATCH 02/27] Fixing line break --- caching,_sessions,_local_storage_&_cookies.md | 37 +++++---------- security_guidelines.md | 47 +++++-------------- 2 files changed, 24 insertions(+), 60 deletions(-) diff --git a/caching,_sessions,_local_storage_&_cookies.md b/caching,_sessions,_local_storage_&_cookies.md index 5876ca8..f4fe085 100644 --- a/caching,_sessions,_local_storage_&_cookies.md +++ b/caching,_sessions,_local_storage_&_cookies.md @@ -2,19 +2,11 @@ ## 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. +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: +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: @@ -22,9 +14,7 @@ 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 -include their version hash as file name. This way version updates will result -in a new file name and will be re-cached by the client browser. +In order to trigger a re-cache of stylesheets or javascript files make sure to include their version hash as file name. This way version updates will result in a new file name and will be re-cached by the client browser. Example usage: @@ -34,24 +24,23 @@ $head->addAsset(AssetType::JS, $request->getUri()->getBase() . 'Modules/Media/Mo ## 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. +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 +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. +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 \ No newline at end of file +## 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 diff --git a/security_guidelines.md b/security_guidelines.md index 3d13b5d..28898ac 100644 --- a/security_guidelines.md +++ b/security_guidelines.md @@ -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,16 +12,9 @@ Example usage: ``` -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: @@ -41,37 +31,30 @@ if($request->getData('CSRF') === null) { ### 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 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. Client can be logged out and still need a CSRF token and obviously vice versa. ## 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,10 +74,7 @@ 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: @@ -104,9 +84,7 @@ if(($pathNew = realpath($path)) === false || strpos($pathNew, ROOT_PATH . '/Modu } ``` -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 `ROOT_PATH . '/Modules/' . self::$module`. Another validation could be: ``` if(($pathNew = realpath($path)) === false || !Validator::startsWith($pathNew, ROOT_PATH)) { @@ -114,7 +92,4 @@ if(($pathNew = realpath($path)) === false || !Validator::startsWith($pathNew, RO } ``` -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. \ No newline at end of file +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. \ No newline at end of file From 06fd3ca85ef8dd461bdede81a6aa00153025953f Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Tue, 29 Dec 2015 21:51:56 +0100 Subject: [PATCH 03/27] Line ending fixes and module installation --- modules.md | 101 +++++++++++++++++++++++++++++++++++++---- security_guidelines.md | 4 +- 2 files changed, 93 insertions(+), 12 deletions(-) diff --git a/modules.md b/modules.md index 4a2021d..e2d4153 100644 --- a/modules.md +++ b/modules.md @@ -1,21 +1,102 @@ # Modules -## Info +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. -## Install +* UniqueModuleName + * Admin + * Install + * Navigation.install.json + * Navigation.php + * Install.php + * Models + * YourPhPModels.php + * YourJavaScriptModels.js + * Theme + * Css + * yourCss_1.0.0.css + * yourScss_1.0.0.scss + * Img + * yourTemplateImages.jpg + * backend + * your_template_files.tpl.php + * lang + * backend.en.lang.php + * nav.backend.en.lang.php + * Views + * YourPhpViews.php + * YourJavaScriptViews.js + * Controller.php + * Controller.js + * ModuleUniqueModuleName_1.0.0.js + * info.json -## Update +All modules are located inside the `/Modules` directory and their directory name has to be the module name itself without whitespaces. -## Uninstall +## Admin -## Routing +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. -## Model, View, Controller, Template +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. -## Resources +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. -## Providing +### Install.php -## Requesting +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: -## Receiving \ No newline at end of file +``` +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 + +### Delete.php + +### Activate.php + +### Deactivate.php \ No newline at end of file diff --git a/security_guidelines.md b/security_guidelines.md index 28898ac..97f6159 100644 --- a/security_guidelines.md +++ b/security_guidelines.md @@ -79,12 +79,12 @@ These are just a few examples but it is very important to make sure, that these Example usage: ``` -if(($pathNew = realpath($path)) === false || strpos($pathNew, ROOT_PATH . '/Modules/' . self::$module) === false) { +if(($pathNew = realpath($path)) === false || strpos($pathNew, self::MODULE_PATH) === false) { throw new FilePathException($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)) { From e3651ffe1ce557cf1872a07ec59a95b25e2b0264 Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Fri, 1 Jan 2016 10:29:29 +0100 Subject: [PATCH 04/27] Continuing documentation --- modules.md | 83 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 69 insertions(+), 14 deletions(-) diff --git a/modules.md b/modules.md index e2d4153..0c82335 100644 --- a/modules.md +++ b/modules.md @@ -7,21 +7,29 @@ The following directory structure should roughly visualize how modules are struc * Install * Navigation.install.json * Navigation.php - * Install.php + * Update + * yourUpdateFiles.??? + * Activate.php + * Deactivate.php + * Installer.php + * Uninstall.php + * Update.php + * Img + * modulePreviewImage.jpg * Models * YourPhPModels.php * YourJavaScriptModels.js * Theme - * Css - * yourCss_1.0.0.css - * yourScss_1.0.0.scss - * Img - * yourTemplateImages.jpg - * backend + * 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 - * lang - * backend.en.lang.php - * nav.backend.en.lang.php * Views * YourPhpViews.php * YourJavaScriptViews.js @@ -41,7 +49,7 @@ The content of the navigation install file highly depends on the module and shou 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. -### Install.php +### 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: @@ -89,14 +97,61 @@ public static function install(Pool $dbPool) } ``` -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. +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 -### Delete.php +### Uninstall.php ### Activate.php -### Deactivate.php \ No newline at end of file +### 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 include the version number in the CSS file name for overwriting the cache on updates. 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 + +The content of the language file is straight forward: + +``` + '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 \ No newline at end of file From a2e35a5d97d754b650bf516adff24788039a904b Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Sat, 9 Jan 2016 20:09:43 +0100 Subject: [PATCH 05/27] Fixing concept changes (resource versioning) --- caching,_sessions,_local_storage_&_cookies.md | 4 ++-- modules.md | 11 ++++++----- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/caching,_sessions,_local_storage_&_cookies.md b/caching,_sessions,_local_storage_&_cookies.md index f4fe085..6b56cf6 100644 --- a/caching,_sessions,_local_storage_&_cookies.md +++ b/caching,_sessions,_local_storage_&_cookies.md @@ -14,12 +14,12 @@ 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 include their version hash as file name. This way version updates will result in a new file name and will be re-cached by the client browser. +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/ModuleMedia_' . self::$version . '.js'); +$head->addAsset(AssetType::JS, $request->getUri()->getBase() . 'Modules/Media/ModuleMedia.js?v=' . self::MODULE_VERSION); ``` ## Sessions diff --git a/modules.md b/modules.md index 0c82335..00d5856 100644 --- a/modules.md +++ b/modules.md @@ -2,7 +2,7 @@ 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 +* {UniqueModuleName} * Admin * Install * Navigation.install.json @@ -35,7 +35,7 @@ The following directory structure should roughly visualize how modules are struc * YourJavaScriptViews.js * Controller.php * Controller.js - * ModuleUniqueModuleName_1.0.0.js + * Module{UniqueModuleName}.js * info.json All modules are located inside the `/Modules` directory and their directory name has to be the module name itself without whitespaces. @@ -123,7 +123,7 @@ The Theme directory contains the current theme for every page this module suppor ### 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 include the version number in the CSS file name for overwriting the cache on updates. CSS files need to be minimized and if it makes sense concatenated. +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 @@ -135,13 +135,14 @@ The Lang directory contains all language files for this application. Usually the A language file should have the following naming convention: - {ISO 639-1}.lang.php + {ISO 639-1}.lang.php + {UniqueModuleName}.{ISO 639-1}.lang.php The content of the language file is straight forward: ``` 'Your localized string', ]; ``` From 45f9746285da60916e115152ebb5e612d40dd639 Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Sun, 17 Jan 2016 18:32:27 +0100 Subject: [PATCH 06/27] Init tests --- tests.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 tests.md diff --git a/tests.md b/tests.md new file mode 100644 index 0000000..8520b17 --- /dev/null +++ b/tests.md @@ -0,0 +1,11 @@ +# 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. \ No newline at end of file From 3db1a1a8a8092e4cef73158214728fba3f2db93d Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Wed, 17 Feb 2016 21:46:53 +0100 Subject: [PATCH 07/27] New files and removing duplication --- documentation.md | 104 ++++++++++++++++++++++++ inspections,_tests_&_code_guidelines.md | 14 ---- styles_and_layout.md | 19 +++++ 3 files changed, 123 insertions(+), 14 deletions(-) create mode 100644 documentation.md delete mode 100644 inspections,_tests_&_code_guidelines.md create mode 100644 styles_and_layout.md diff --git a/documentation.md b/documentation.md new file mode 100644 index 0000000..031c42b --- /dev/null +++ b/documentation.md @@ -0,0 +1,104 @@ +# 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 is mandatory and needs to have the following layout: + +``` +/** + * File description + * + * PHP Version 7.0 + * + * @category Category name + * @package Package name + * @author Your Author 1 + * @author Your Author 2 + * @copyright Orange Management + * @license OMS License 1.0 + * @version 1.0.0 + * @link http://your.url.com + */ +``` + +### Class + +A class documentation is mandatory and needs to have the following layout: + +``` +/** + * Class description. + * + * @category Category name + * @package Package name + * @author Your Author 1 + * @author Your Author 2 + * @license OMS License 1.0 + * @link http://your.url.com + * @since 1.0.0 + */ +``` + +#### Member + +A member variable documentation is mandatory and needs to have the following layout: + +``` +/** + * Member variable description. + * + * @var variable_type + * @since 1.0.0 + */ +``` + +#### Function/Method + +A function/method documentation is mandatory and needs to have the following layout: + +``` +/** + * 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 + */ +``` + +### 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 + +## Scss + +The scss documentation is based on SassDoc, therefore only valid SassDoc comments are valid for all scss files. + +``` +//// +// Documentation +// +// Optional example or more detailed description. +// +// @since 1.0.0 +// @author Your Author 2 +//// +``` \ No newline at end of file diff --git a/inspections,_tests_&_code_guidelines.md b/inspections,_tests_&_code_guidelines.md deleted file mode 100644 index ae15030..0000000 --- a/inspections,_tests_&_code_guidelines.md +++ /dev/null @@ -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 - diff --git a/styles_and_layout.md b/styles_and_layout.md new file mode 100644 index 0000000..b53c238 --- /dev/null +++ b/styles_and_layout.md @@ -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: + +``` + + 333 + +``` + +## Examples + +An example of all styles can be found in the tests called `StandardElements.htm`. \ No newline at end of file From 4827fbc5851567a11959598f967005ed8ec08f2d Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Sun, 21 Feb 2016 10:08:22 +0100 Subject: [PATCH 08/27] JS documentation --- documentation.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/documentation.md b/documentation.md index 031c42b..9751591 100644 --- a/documentation.md +++ b/documentation.md @@ -88,6 +88,8 @@ Example: ## JavaScript +The javascript documentation is based on JsDoc, therefore only valid JsDoc comments are valid for all js files. + ## Scss The scss documentation is based on SassDoc, therefore only valid SassDoc comments are valid for all scss files. From 989575f217fc42f8c43002a898e3d5c16796c65f Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Sat, 26 Mar 2016 11:03:27 +0100 Subject: [PATCH 09/27] Name fix --- security_guidelines.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/security_guidelines.md b/security_guidelines.md index 97f6159..225f637 100644 --- a/security_guidelines.md +++ b/security_guidelines.md @@ -80,7 +80,7 @@ Example usage: ``` if(($pathNew = realpath($path)) === false || strpos($pathNew, self::MODULE_PATH) === false) { - throw new FilePathException($path); + throw new PathException($path); } ``` @@ -88,7 +88,7 @@ The example throws an exception if the path either doesn't exist or is trying to ``` if(($pathNew = realpath($path)) === false || !Validator::startsWith($pathNew, ROOT_PATH)) { - throw new FilePathException($path); + throw new PathException($path); } ``` From 63e3bf0e272b6cfd9a04bc1fb0e0622117fe2aec Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Sat, 26 Mar 2016 23:55:42 +0100 Subject: [PATCH 10/27] Adding installation and summary cleanup --- SUMMARY.md | 9 +++++++-- inspections.md | 0 installation.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 55 insertions(+), 2 deletions(-) create mode 100644 inspections.md create mode 100644 installation.md diff --git a/SUMMARY.md b/SUMMARY.md index 9784e4a..68bf9de 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,6 +1,11 @@ # Summary * [Introduction](README.md) +* [Installation](installation.md) +* [Documentation](documentation.md) * [Security Guidelines](security_guidelines.md) -* [Inspections, Tests & Code Guidelines](inspections,_tests_&_code_guidelines.md) - +* [Styles and Layout](styles_and_layout.md) +* [Caching, Sessions, Local Storage & Cookies](caching,_sessions,_local_storage_&_cookies.md) +* [Modules](modules.md) +* [Inspections](inspections.md) +* [Tests](tests.md) diff --git a/inspections.md b/inspections.md new file mode 100644 index 0000000..e69de29 diff --git a/installation.md b/installation.md new file mode 100644 index 0000000..28eeb8b --- /dev/null +++ b/installation.md @@ -0,0 +1,48 @@ +# Installation + +Installing the application as a developer can be achived by following one of the following instructions + +## 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. \ No newline at end of file From e532c07513872275c4630810e51fd5573a12e09d Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Sun, 27 Mar 2016 15:11:18 +0200 Subject: [PATCH 11/27] Permission instruction for logging --- installation.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/installation.md b/installation.md index 28eeb8b..59d8ad1 100644 --- a/installation.md +++ b/installation.md @@ -2,6 +2,12 @@ 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. @@ -45,4 +51,4 @@ This only installs an application without any dev tools that may be required by ### Annotation -Re-installing the application this way requires you to drop and re-create the database. \ No newline at end of file +Re-installing the application this way requires you to drop and re-create the database. From 5cd30bfd62c87307c7134c07427d73e74d182f06 Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Sun, 27 Mar 2016 17:32:30 +0200 Subject: [PATCH 12/27] Commit for update --- inspections.md | 1 + 1 file changed, 1 insertion(+) diff --git a/inspections.md b/inspections.md index e69de29..a22117d 100644 --- a/inspections.md +++ b/inspections.md @@ -0,0 +1 @@ +# Inspections \ No newline at end of file From 8cbb812c549bafdd36e8d053406a6736fb2046e5 Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Fri, 22 Apr 2016 15:21:36 +0200 Subject: [PATCH 13/27] Update --- modules.md | 7 ++++--- security_guidelines.md | 2 +- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/modules.md b/modules.md index 00d5856..0ff83a5 100644 --- a/modules.md +++ b/modules.md @@ -59,11 +59,12 @@ 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, array $info) + public static function install(Pool $dbPool, InfoManager $info) { parent::install($dbPool, $info); @@ -142,9 +143,9 @@ The content of the language file is straight forward: ``` [ '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. diff --git a/security_guidelines.md b/security_guidelines.md index 225f637..d4ec79d 100644 --- a/security_guidelines.md +++ b/security_guidelines.md @@ -20,7 +20,7 @@ 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)); From 2084dcf99ce5a3ca03c136e81074c17c56a51c32 Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Sat, 4 Jun 2016 18:52:41 +0200 Subject: [PATCH 14/27] Mention javascript testing --- tests.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/tests.md b/tests.md index 8520b17..1ea7d49 100644 --- a/tests.md +++ b/tests.md @@ -8,4 +8,8 @@ This application uses PHPUnit as unit testing framework. The PHPUnit directory i ### 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. \ No newline at end of file +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. \ No newline at end of file From aabef68bdb5d7afbf78777cfdd2bfdb79328a9fc Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Tue, 5 Jul 2016 16:36:21 +0200 Subject: [PATCH 15/27] Minor corrections --- README.md | 16 ++-------------- caching,_sessions,_local_storage_&_cookies.md | 2 +- modules.md | 3 +-- 3 files changed, 4 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 50513c4..b2f5c9e 100644 --- a/README.md +++ b/README.md @@ -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. \ No newline at end of file +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. \ No newline at end of file diff --git a/caching,_sessions,_local_storage_&_cookies.md b/caching,_sessions,_local_storage_&_cookies.md index 6b56cf6..577bc76 100644 --- a/caching,_sessions,_local_storage_&_cookies.md +++ b/caching,_sessions,_local_storage_&_cookies.md @@ -19,7 +19,7 @@ In order to trigger a re-cache of stylesheets or javascript files make sure to u Example usage: ``` -$head->addAsset(AssetType::JS, $request->getUri()->getBase() . 'Modules/Media/ModuleMedia.js?v=' . self::MODULE_VERSION); +$head->addAsset(AssetType::JS, $request->getUri()->getBase() . 'Modules/Media/Controller.js?v=' . self::MODULE_VERSION); ``` ## Sessions diff --git a/modules.md b/modules.md index 0ff83a5..4364a48 100644 --- a/modules.md +++ b/modules.md @@ -28,14 +28,13 @@ The following directory structure should roughly visualize how modules are struc * yourTemplateImages.jpg * Lang * en.lang.php - * navigation.en.lang.php + * Navigation.en.lang.php * your_template_files.tpl.php * Views * YourPhpViews.php * YourJavaScriptViews.js * Controller.php * Controller.js - * Module{UniqueModuleName}.js * info.json All modules are located inside the `/Modules` directory and their directory name has to be the module name itself without whitespaces. From 5bbc32ab1e54995ae8df1249602df6ecd37c16bc Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Tue, 5 Jul 2016 16:36:30 +0200 Subject: [PATCH 16/27] First draft --- inspections.md | 120 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 119 insertions(+), 1 deletion(-) diff --git a/inspections.md b/inspections.md index a22117d..d63e562 100644 --- a/inspections.md +++ b/inspections.md @@ -1 +1,119 @@ -# Inspections \ No newline at end of file +# 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. + +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. + +## Class Constants, Properties, and Methods + +The term "class" refers to all classes, interfaces, and traits. + +## Code Quality + +### General + +### Modules + +#### Langauge Files + +Every provided language element in the language files SHOULD be used at least once by the module itself. + +## Code Standards + +### Html + +#### Indention + +The default indention MUST be 4 spaces. + +#### Omitted closing tags + +The following closing tags SHOULD be omitted: + +* `` +* `` +* `` +* `` +* `` +* `` +* `` +* `` +* `` +* `` +* `` + +The following tags MUST not specify a end tag (\): + +* `
` +* `` +* `` +* `
` +* `` +* `` +* `` +* `` + +### 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 `` 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 + +#### Indention + +The default indention MUST be 4 spaces. + +#### 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) : ?> +

This is html

+ +``` + +### JavaScript + +#### Indention + +The default indention MUST be 4 spaces. + +### Scss + +#### Indention + +The default indention MUST be 4 spaces. + +## Code Security + From 8af01bdc656f20008be87a27c3a5bc7247b27e0a Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Tue, 5 Jul 2016 20:39:30 +0200 Subject: [PATCH 17/27] re-structuring --- SUMMARY.md | 28 +++-- ...hing,_sessions,_local_storage_&_cookies.md | 0 .../datamapper_&_query_builder.md | 0 modules.md => components/modules.md | 0 .../styles_and_layout.md | 0 inspections.md | 119 ------------------ quality/code_quality.md | 9 ++ quality/inspections.md | 23 ++++ tests.md => quality/tests.md | 0 .../security_guidelines.md | 0 installation.md => setup/installation.md | 0 .../documentation.md | 0 standards/general.md | 48 +++++++ standards/php.md | 45 +++++++ 14 files changed, 145 insertions(+), 127 deletions(-) rename caching,_sessions,_local_storage_&_cookies.md => components/caching,_sessions,_local_storage_&_cookies.md (100%) rename datamapper_&_query_builder.md => components/datamapper_&_query_builder.md (100%) rename modules.md => components/modules.md (100%) rename styles_and_layout.md => frontend/styles_and_layout.md (100%) delete mode 100644 inspections.md create mode 100644 quality/code_quality.md create mode 100644 quality/inspections.md rename tests.md => quality/tests.md (100%) rename security_guidelines.md => security/security_guidelines.md (100%) rename installation.md => setup/installation.md (100%) rename documentation.md => standards/documentation.md (100%) create mode 100644 standards/general.md create mode 100644 standards/php.md diff --git a/SUMMARY.md b/SUMMARY.md index 68bf9de..a369e49 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,11 +1,23 @@ # Summary * [Introduction](README.md) -* [Installation](installation.md) -* [Documentation](documentation.md) -* [Security Guidelines](security_guidelines.md) -* [Styles and Layout](styles_and_layout.md) -* [Caching, Sessions, Local Storage & Cookies](caching,_sessions,_local_storage_&_cookies.md) -* [Modules](modules.md) -* [Inspections](inspections.md) -* [Tests](tests.md) + +## Setup +* [Installation](setup/installation.md) + +## Standards +* [Documentation](standards/documentation.md) + +## Security +* [Security Guidelines](security/security_guidelines.md) + +## Code Quality +* [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) diff --git a/caching,_sessions,_local_storage_&_cookies.md b/components/caching,_sessions,_local_storage_&_cookies.md similarity index 100% rename from caching,_sessions,_local_storage_&_cookies.md rename to components/caching,_sessions,_local_storage_&_cookies.md diff --git a/datamapper_&_query_builder.md b/components/datamapper_&_query_builder.md similarity index 100% rename from datamapper_&_query_builder.md rename to components/datamapper_&_query_builder.md diff --git a/modules.md b/components/modules.md similarity index 100% rename from modules.md rename to components/modules.md diff --git a/styles_and_layout.md b/frontend/styles_and_layout.md similarity index 100% rename from styles_and_layout.md rename to frontend/styles_and_layout.md diff --git a/inspections.md b/inspections.md deleted file mode 100644 index d63e562..0000000 --- a/inspections.md +++ /dev/null @@ -1,119 +0,0 @@ -# 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. - -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. - -## Class Constants, Properties, and Methods - -The term "class" refers to all classes, interfaces, and traits. - -## Code Quality - -### General - -### Modules - -#### Langauge Files - -Every provided language element in the language files SHOULD be used at least once by the module itself. - -## Code Standards - -### Html - -#### Indention - -The default indention MUST be 4 spaces. - -#### Omitted closing tags - -The following closing tags SHOULD be omitted: - -* `` -* `` -* `` -* `` -* `` -* `` -* `` -* `` -* `` -* `` -* `` - -The following tags MUST not specify a end tag (\): - -* `
` -* `` -* `` -* `
` -* `` -* `` -* `` -* `` - -### 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 `` 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 - -#### Indention - -The default indention MUST be 4 spaces. - -#### 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) : ?> -

This is html

- -``` - -### JavaScript - -#### Indention - -The default indention MUST be 4 spaces. - -### Scss - -#### Indention - -The default indention MUST be 4 spaces. - -## Code Security - diff --git a/quality/code_quality.md b/quality/code_quality.md new file mode 100644 index 0000000..5069590 --- /dev/null +++ b/quality/code_quality.md @@ -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. diff --git a/quality/inspections.md b/quality/inspections.md new file mode 100644 index 0000000..5f690fd --- /dev/null +++ b/quality/inspections.md @@ -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 + diff --git a/tests.md b/quality/tests.md similarity index 100% rename from tests.md rename to quality/tests.md diff --git a/security_guidelines.md b/security/security_guidelines.md similarity index 100% rename from security_guidelines.md rename to security/security_guidelines.md diff --git a/installation.md b/setup/installation.md similarity index 100% rename from installation.md rename to setup/installation.md diff --git a/documentation.md b/standards/documentation.md similarity index 100% rename from documentation.md rename to standards/documentation.md diff --git a/standards/general.md b/standards/general.md new file mode 100644 index 0000000..32f0520 --- /dev/null +++ b/standards/general.md @@ -0,0 +1,48 @@ +# Code Standards + +The following code standard is enforced in order to make it easier to update and maintain implementations. + +## General + +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. + +## Html + +### Omitted closing tags + +The following closing tags SHOULD be omitted: + +* `` +* `` +* `` +* `` +* `` +* `` +* `` +* `` +* `` +* `` +* `` + +The following tags MUST not specify a end tag (\\): + +* `
` +* `` +* `` +* `
` +* `` +* `` +* `` +* `` + +# + +## JavaScript + +## Scss \ No newline at end of file diff --git a/standards/php.md b/standards/php.md new file mode 100644 index 0000000..763f853 --- /dev/null +++ b/standards/php.md @@ -0,0 +1,45 @@ +# 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 `` 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) : ?> +

This is html

+ +``` \ No newline at end of file From a78af833b708bf19f20168c0f8c3eb6a42bf200c Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Fri, 8 Jul 2016 14:39:47 +0200 Subject: [PATCH 18/27] Added section elements for filling --- standards/documentation.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/standards/documentation.md b/standards/documentation.md index 9751591..403ae5a 100644 --- a/standards/documentation.md +++ b/standards/documentation.md @@ -90,10 +90,22 @@ Example: 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 @@ -103,4 +115,12 @@ The scss documentation is based on SassDoc, therefore only valid SassDoc comment // @since 1.0.0 // @author Your Author 2 //// -``` \ No newline at end of file +``` + +### Class + +#### Member + +#### Function/Method + +### Variable \ No newline at end of file From f91959e3ebb5d4073e7f2c0ae3d0df7ddafa8aea Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Fri, 8 Jul 2016 14:40:01 +0200 Subject: [PATCH 19/27] Added deprecated functions and vars --- standards/php.md | 103 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 102 insertions(+), 1 deletion(-) diff --git a/standards/php.md b/standards/php.md index 763f853..6f0fb2d 100644 --- a/standards/php.md +++ b/standards/php.md @@ -42,4 +42,105 @@ Php code embedded into template files SHOULD use the alternative syntax for cont if($a === 5) : ?>

This is html

-``` \ No newline at end of file +``` + +## 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()` +* `unlink()` \ No newline at end of file From 3a65029694e74e95821d5865c1f5441062c8fb1b Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Fri, 8 Jul 2016 14:52:47 +0200 Subject: [PATCH 20/27] Extracting html standards --- standards/general.md | 31 ------------------------------- standards/html.md | 38 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 38 insertions(+), 31 deletions(-) create mode 100644 standards/html.md diff --git a/standards/general.md b/standards/general.md index 32f0520..c82943c 100644 --- a/standards/general.md +++ b/standards/general.md @@ -12,37 +12,6 @@ The term "class" refers to all classes, interfaces, and traits. The default indention MUST be 4 spaces. -## Html - -### Omitted closing tags - -The following closing tags SHOULD be omitted: - -* `` -* `` -* `` -* `` -* `` -* `` -* `` -* `` -* `` -* `` -* `` - -The following tags MUST not specify a end tag (\\): - -* `
` -* `` -* `` -* `
` -* `` -* `` -* `` -* `` - -# - ## JavaScript ## Scss \ No newline at end of file diff --git a/standards/html.md b/standards/html.md new file mode 100644 index 0000000..c25fec5 --- /dev/null +++ b/standards/html.md @@ -0,0 +1,38 @@ +# Html + +All html has to be html 5 compliant. + +## Omitted closing tags + +The following closing tags SHOULD be omitted: + +* `` +* `` +* `` +* `` +* `` +* `` +* `` +* `` +* `` +* `` +* `` + +The following tags MUST not specify a end tag (\\): + +* `
` +* `` +* `` +* `
` +* `` +* `` +* `` +* `` + +## 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. \ No newline at end of file From 3e53cc398f63964bbc90144bed12fb56576d6817 Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Fri, 8 Jul 2016 14:53:26 +0200 Subject: [PATCH 21/27] Cleanup general --- standards/general.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/standards/general.md b/standards/general.md index c82943c..1b55d52 100644 --- a/standards/general.md +++ b/standards/general.md @@ -2,16 +2,10 @@ The following code standard is enforced in order to make it easier to update and maintain implementations. -## General - 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 +## Indention The default indention MUST be 4 spaces. - -## JavaScript - -## Scss \ No newline at end of file From 443f61ef313411dfb74de03384b193cb49fd2853 Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Fri, 8 Jul 2016 14:54:02 +0200 Subject: [PATCH 22/27] Hint for dev environment --- setup/dev_environment.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 setup/dev_environment.md diff --git a/setup/dev_environment.md b/setup/dev_environment.md new file mode 100644 index 0000000..7f4ac05 --- /dev/null +++ b/setup/dev_environment.md @@ -0,0 +1 @@ +# Dev Environment \ No newline at end of file From 29610c4a96d68e26a488321bcfc813e150ea31b6 Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Fri, 8 Jul 2016 14:57:59 +0200 Subject: [PATCH 23/27] Adding language description --- quality/code_quality.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/quality/code_quality.md b/quality/code_quality.md index 5069590..efdee5c 100644 --- a/quality/code_quality.md +++ b/quality/code_quality.md @@ -6,4 +6,4 @@ ### Langauge Files -Every provided language element in the language files SHOULD be used at least once by the module itself. +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. From 3b83d5b283bd6421511af02b206470f7a9f73dd7 Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Fri, 8 Jul 2016 14:58:21 +0200 Subject: [PATCH 24/27] Extending summary with more elements --- SUMMARY.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/SUMMARY.md b/SUMMARY.md index a369e49..b1b4ed2 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -4,14 +4,19 @@ ## 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) From 046f7bcd741f256da0bcfc457f8ba15021314ec6 Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Fri, 8 Jul 2016 15:06:22 +0200 Subject: [PATCH 25/27] Fixing to rfc lingo --- standards/documentation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/standards/documentation.md b/standards/documentation.md index 403ae5a..4b651ef 100644 --- a/standards/documentation.md +++ b/standards/documentation.md @@ -6,7 +6,7 @@ The php documentation is based on PhpDocumentor, therefore only valid PhpDocumen ### File -A file documentation is mandatory and needs to have the following layout: +A file documentation MUST be implemented in the following form: ``` /** @@ -27,7 +27,7 @@ A file documentation is mandatory and needs to have the following layout: ### Class -A class documentation is mandatory and needs to have the following layout: +A class documentation MUST be implemented in the following form: ``` /** @@ -45,7 +45,7 @@ A class documentation is mandatory and needs to have the following layout: #### Member -A member variable documentation is mandatory and needs to have the following layout: +A member variable documentation MUST be implemented in the following form: ``` /** @@ -58,7 +58,7 @@ A member variable documentation is mandatory and needs to have the following lay #### Function/Method -A function/method documentation is mandatory and needs to have the following layout: +A function/method documentation MUST be implemented in the following form: ``` /** From 950cf58cfb581779f112ebb837b1de8cade4af30 Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Tue, 12 Jul 2016 14:22:12 +0200 Subject: [PATCH 26/27] Adding critical functions --- standards/php.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/standards/php.md b/standards/php.md index 6f0fb2d..abecc44 100644 --- a/standards/php.md +++ b/standards/php.md @@ -143,4 +143,6 @@ The usage of the following functions SHOULD be avoided and inspected for any kin * `rename()` * `symlink()` * `rmdir()` +* `mkdir()` +* `touch()` * `unlink()` \ No newline at end of file From 9b1cb1fca28e4dc7a4e88389f1a76619ebb5ed30 Mon Sep 17 00:00:00 2001 From: Dennis Eichhorn Date: Tue, 12 Jul 2016 14:22:23 +0200 Subject: [PATCH 27/27] Adding header security --- security/security_guidelines.md | 48 +++++++++++++++++++++++++++++++-- 1 file changed, 46 insertions(+), 2 deletions(-) diff --git a/security/security_guidelines.md b/security/security_guidelines.md index d4ec79d..59a375e 100644 --- a/security/security_guidelines.md +++ b/security/security_guidelines.md @@ -34,7 +34,7 @@ if($request->getData('CSRF') === null) { 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 @@ -43,7 +43,51 @@ Here some examples of requests that **MAY** not need a validation (mostly API GE 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