diff --git a/.github/workflows/greetings.yml b/.github/workflows/greetings.yml new file mode 100644 index 0000000..adb8716 --- /dev/null +++ b/.github/workflows/greetings.yml @@ -0,0 +1,13 @@ +name: Greetings + +on: [pull_request, issues] + +jobs: + greeting: + runs-on: ubuntu-latest + steps: + - uses: actions/first-interaction@v1 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + issue-message: 'Thank you for createing this issue. We will check it as soon as possible.' + pr-message: 'Thank you for your pull request. We will check it as soon as possible.' diff --git a/README.md b/README.md index b2f5c9e..57c3b40 100644 --- a/README.md +++ b/README.md @@ -1,5 +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 api functions, 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 all of the api, for this you can find the automatically generated code documentation or even better use the test cases. 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/SUMMARY.md b/SUMMARY.md index 34cef5f..ca1105b 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,72 +1,47 @@ -# Summary +# General * [Introduction]({%}?page=README) -* [Application Structure]({%}?page=application/structure) -* [Application Sample]({%}?page=application/sample) +* [Setup]({%}?page=general/setup) +* [Application Structure]({%}?page=general/structure) -## Setup -* [Installation]({%}?page=setup/installation) -* [Developer Environment]({%}?page=setup/developer_environment) +## Quality & Standards +* [Code Inspection]({%}?page=quality/inspections) +* [Documentation Standards]({%}?page=standards/documentation) +* [General Code Standards]({%}?page=standards/general) +* [Security Standards]({%}?page=security/security_guidelines) +* [Html Coding Standards]({%}?page=standards/html) +* [Php Coding Standards]({%}?page=standards/php) -## Standards -* [General]({%}?page=standards/general) -* [Documentation]({%}?page=standards/documentation) -* [Html]({%}?page=standards/html) -* [Php]({%}?page=standards/php) +## Examples +* [Application Sample]({%}?page=example_app/app) +* [Modules]({%}?page=example_module/module) +* [Packages]({%}?page=example_module/packages) -## Basics +## API * [Routing]({%}?page=basics/routing) * [Dispatching]({%}?page=basics/dispatching) * [Views]({%}?page=basics/views) * [Requests]({%}?page=basics/requests) * [Responses]({%}?page=basics/responses) - -## Security -* [Security Guidelines]({%}?page=security/security_guidelines) - -## DataStorage * [Cache]({%}?page=datastorage/cache) * [Session]({%}?page=datastorage/session) * [Cookie]({%}?page=datastorage/cookie) * [LocalStorage]({%}?page=datastorage/localstorage) - -### Database -* [Connection]({%}?page=datastorage/database/connection) +* [Database Connection]({%}?page=datastorage/database/connection) * [DataMapper]({%}?page=datastorage/database/datamapper) * [Queries]({%}?page=datastorage/database/queries) - -## Code Quality -* [Code Quality]({%}?page=quality/code_quality) -* [Inspections]({%}?page=quality/inspections) -* [Tests]({%}?page=quality/tests) - -## Frontend * [Styles and Layout]({%}?page=frontend/styles_and_layout) * [Charting]({%}?page=services/charting) * [Codes]({%}?page=services/codes) - -## Components -* [Modules]({%}?page=components/modules) -* [Packages]({%}?page=components/packages) - -## System * [Events]({%}?page=services/events) * [Filesystem]({%}?page=services/filesystem) * [Logging]({%}?page=services/logging) * [Tasks]({%}?page=services/tasks) - -## Message * [Mail]({%}?page=services/mail) * [Encoding]({%}?page=services/encoding) * [Encryption]({%}?page=services/encryption) - -## Localization * [Localization]({%}?page=services/localization) * [Money]({%}?page=services/money) - -## Stdl * [Queues]({%}?page=services/queues) * [Collection]({%}?page=services/collection) - -## Helper * [Validation]({%}?page=services/validation) * [Uri]({%}?page=services/uri) \ No newline at end of file diff --git a/basics/dispatching.md b/basics/dispatching.md index 6375eb4..c199186 100644 --- a/basics/dispatching.md +++ b/basics/dispatching.md @@ -41,11 +41,11 @@ $dispatcher->dispatch(function($para1, $para2) { ... }, $staticToCallPara1, $sta The dispatcher accepts the resoults from the `route()` method of the router which is an array of routes. ```php -$dispatcher->dispatch($router->route($request)) +$dispatcher->dispatch($router->route($request->getUri()->getRoute())); ``` Based on the function definition returned by the router it's possible to pass more parameters to the function such e.g. request and response objects. ```php -$dispatcher->dispatch($router->route($request), $request, $response) +$dispatcher->dispatch($router->route($request->getUri()->getRoute()), $request, $response); ``` diff --git a/basics/views.md b/basics/views.md index 95f0621..52375a3 100644 --- a/basics/views.md +++ b/basics/views.md @@ -10,7 +10,7 @@ In case the response header is set to JSON the view will automatically get parse ## Localization -The base view class contains the request as well as the response objects hence it also contains the request/response localization. One of the most important methods is the `getText()` method. This private method allows for module and theme specific translations of defined language elements. +The base view class contains the request as well as the response objects hence it also contains the request/response localization. One of the most important methods is the `getText()` method. This private method allows for module and theme specific translations of defined language elements. In the template you can simply use `$this->getText({TEXT_ID})` for localized text. All other localization elements can be accessed in a similar way e.g. `$this->l11n->getTemperature()`. @@ -28,4 +28,4 @@ Note that the path definition doesn't include the file ending. ## Data Binding -In the generic view it's possible to bind data by using the `setData()` method and this data can be accessed by using the `getData()` method. \ No newline at end of file +In the generic view it's possible to bind data by using the `setData()` method and this data can be accessed by using the `getData()` method. \ No newline at end of file diff --git a/datastorage/database/queries.md b/datastorage/database/queries.md index 842c5d9..be37841 100644 --- a/datastorage/database/queries.md +++ b/datastorage/database/queries.md @@ -113,4 +113,38 @@ $query->prefix(...)->select(...)->from(...)->where(...)->groupBy('columnA', 'col ### Schema Builder -The schema builder is used for schema related operations such as `DROP`, `CREATE` etc. \ No newline at end of file +The schema builder is used for schema related operations such as `DROP`, `CREATE` etc. + +#### Drop Database + +A database can be dropped with `dropDatabase`. + +```php +$query->dropDatabase('test'); +``` + +#### Create Table + +A table can be created with `createTable`. + +```php +$query->createTable('user_roles') + ->field('user_id', 'INT', null, false, true, true, 'users', 'ext1_id') + ->field('role_id', 'VARCHAR(10)', '1', true, false, false, 'roles', 'ext2_id'); +``` + +#### Show Tables + +All tables of a database can be returned with `selectTables`. + +```php +$query->selectTables(); +``` + +#### Show Table Fields + +All table fields of a table can be returned with `selectFields`. + +```php +$query->selectFields('test'); +``` diff --git a/application/sample.md b/example_app/app.md similarity index 99% rename from application/sample.md rename to example_app/app.md index 25d28c8..ae29b40 100644 --- a/application/sample.md +++ b/example_app/app.md @@ -212,7 +212,7 @@ use app\view\TestView; class TestController { - private $app = null; + private ApplicationAbstract $app; /* the dispatcher passes the ApplicationAbstract reference to the controller */ public function __construct(ApplicationAbstract $app) diff --git a/components/modules.md b/example_module/module.md similarity index 86% rename from components/modules.md rename to example_module/module.md index ce6a546..555f38a 100644 --- a/components/modules.md +++ b/example_module/module.md @@ -5,6 +5,7 @@ The following directory structure should roughly visualize how modules are struc * {UniqueModuleName} * Admin * Install + * db.json * Navigation.install.json * Navigation.php * Routes @@ -51,6 +52,83 @@ 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. +### Database schema + +The database schema of a module is defined in the `db.json` file and is automatically installed during the installation process. + +In the following you can find a sample `db.json` file. + +```json +{ + "task": { + "name": "task", + "fields": { + "task_id": { + "name": "task_id", + "type": "INT", + "null": false, + "primary": true, + "autoincrement": true + }, + "task_title": { + "name": "task_title", + "type": "VARCHAR(255)", + "null": false + }, + "task_desc": { + "name": "task_desc", + "type": "TEXT", + "null": false + }, + "task_type": { + "name": "task_type", + "type": "TINYINT", + "null": false + }, + "task_created_at": { + "name": "task_created_at", + "type": "DATETIME", + "default": null, + "null": true + }, + "task_created_by": { + "name": "task_created_by", + "type": "INT", + "null": false, + "foreignTable": "account", + "foreignKey": "account_id" + } + } + }, + "task_media": { + "name": "task_media", + "fields": { + "task_media_id": { + "name": "task_media_id", + "type": "INT", + "null": false, + "primary": true, + "autoincrement": true + }, + "task_media_src": { + "name": "task_media_src", + "type": "INT", + "null": false, + "foreignTable": "task", + "foreignKey": "task_id" + }, + "task_media_dst": { + "name": "task_media_dst", + "type": "INT", + "null": false, + "foreignTable": "media", + "foreignKey": "media_id" + } + } + } +} +``` + ### Installer.php In contrast to the install file for other modules this file has to follow more strict standards. The following example shows you the bare minimum requirements of a installation file: diff --git a/components/packages.md b/example_module/packages.md similarity index 67% rename from components/packages.md rename to example_module/packages.md index 1a6a076..724ec76 100644 --- a/components/packages.md +++ b/example_module/packages.md @@ -34,7 +34,32 @@ In the files directory all files are stored. The `package.json` file contains information of the package. ```json - +{ + "name": "{MODULE_NAME|RESOURCE_NAME|phpOMS|jsOMS|cssOMS}", + "type": "Modules", + "version": "1.0.1", + "update": [ + { + "download": { + "{download_uri}": "{save_to_path/file_name}" + }, + "move": { + "{file_or_directory_to_move}": "{new_destination}" + }, + "copy": { + "{file_or_directory_to_copy}": [ + "{new_destination}" + ] + }, + "delete": [ + "{file_or_directory_to_delete}" + ], + "cmd": [ + "{php|sh|batch_script_to_execute}", + ] + } + ] +} ``` ### Other diff --git a/example_module/update.md b/example_module/update.md new file mode 100644 index 0000000..e69de29 diff --git a/application/app_flow.svg b/general/app_flow.svg similarity index 100% rename from application/app_flow.svg rename to general/app_flow.svg diff --git a/general/base_uml.svg b/general/base_uml.svg new file mode 100644 index 0000000..9b08c03 --- /dev/null +++ b/general/base_uml.svg @@ -0,0 +1,3 @@ + + +accountaccount_idPK...groupgroup_idPK...profile_accountprofile_account_idPKprofile_account_accountFK1...languagelanguage_idPKCustomerIdFK1...modulemodule_idPK...l11nl11n_idPKl11n_accountFK1...account_permissionaccount_permission_idPKaccount_permission_accountFK1...module_loadmodule_load_idPKmodule_load_fromFK1...countrycountry_idPK...addressaddress_idPKaddress_countryFK1...account_groupaccount_idPKaccount_group_accountFK1account_group_groupFK2settingssettings_idPKsettings_moduleFK1settings_accountFK2settings_groupFK3....group_permissiongroup_permission_idPKgroup_permission_accountFK1...
Profile Module
Profile Module
Core / Installation
Core / Installation
Admin Module
Admin Module
Address Module
Address Module \ No newline at end of file diff --git a/general/overview.md b/general/overview.md new file mode 100644 index 0000000..e69de29 diff --git a/general/setup.md b/general/setup.md new file mode 100644 index 0000000..4b21a31 --- /dev/null +++ b/general/setup.md @@ -0,0 +1,91 @@ +# Setup + +In order to setup the application for development for the first time please see the following instructions and recommendations. + +## Dev-Environment Requirements + +Make sure your dev-environment or server fulfills the following requirements: + +* PHP >= 7.4 +* PHP extensions: mbstring, gd, zip, dom, mysql/pgsql/sqlsrv, sqlite, bcmath, imap*, redis*, memcached*, ftp*, socket*, curl*, xml* +* databases: mysql, postgresql, sqlsrv +* webserver: apache2 + * mod_headers + +The application and frameworks can use different databases. For the normal development process you only need one (whichever you prefer). However, in order to test against all supported databases and all code paths you would have to install all above mentioned databases. + +Extensions marked with `*` are optional. They are only required in special situations. + +Steps which are not explained in this documentation are how to install and setup the above mentioned software and extensions. You also should configure the webserver paths accordingly in order to access the application in the browser. + +## Option 1: Linux Shell Script + +This also installs all required dev tools and sets up the directory 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. + +### Steps + +The following steps will setup the application, download all necessary tools and perform extensive code quality checks and documentation tasks: + +1. Go to the directory where you want to install the build script +2. Run `git clone -b develop https://github.com/Orange-Management/Build.git` +3. Modify `config.sh` (most likely the db credentials and paths) +4. Run `chmod +x buildProject.sh` +5. Run `./buildProject.sh` + +After the installation you'll have access to the following content: + +* Application: `http://127.0.0.1` +* Code Coverager: `http://127.0.0.1/Build/coverage/` +* Test Report: `${INSPECTION_PATH}/test/ReportExternal` +* Unit Test Report: `${INSPECTION_PATH}/test/testdox.txt` +* PHPStan Report: `${INSPECTION_PATH}/test/phpstan.json` +* ... and more + +### Annotation + +During this process the database automatically gets dropped (if existing) and re-created. If you don't have `xdebug` installed but `phpdbg` you can replace `php phpunit.phar ...` with `phpdbg -qrr phpunit.phar ...` or use `pcov` for much faster code coverage generation. + +## Option 2: PHPUnit Test Suits + +This wil only setup the application including some dummy data and also perform the code tests but no quality checks. + +### Steps + +1. Go to the directory where you want to install the application +2. Run `git clone -b develop https://github.com/Orange-Management/Orange-Management.git` +3. Run `git submodule update --init --recursive >/dev/null` +4. Run `git submodule foreach git checkout develop >/dev/null` +5. Install Composer +6. Run `composer install` inside `Orange-Management` +7. Run `php vendor/bin/phpunit --configuration tests/phpunit_no_coverage.xml` inside `Orange-Management` or open `http://127.0.0.1/Install` + +After the installation you'll have access to the following content: + +* Application: `http://127.0.0.1` +* Code Coverager: `http://127.0.0.1/Build/coverage/` + +### Annotation + +During this process the database automatically gets dropped (if existing) and re-created. If you don't have `xdebug` installed but `phpdbg` you can replace `php phpunit.phar ...` with `phpdbg -qrr phpunit.phar ...` or use `pcov` for much faster code coverage generation. + +## Git Hooks (Linux only) + +The git hooks perform various checks and validations during the `commit` and warn the developer about invalid code or code style/guideline violations. + +For developers it is recommended to copy the contents of the `default.sh` file in the `Build` repository under `Hooks` to your `pre-commit` file in the `.git/hooks` directory. If the `pre-commit` file doesn't exist just create it. + +The same should be done with every module. Simply go to `.git/modules/**/hooks` and also add the content of the `default.sh` file to all `pre-commit` files. + +By doing this every commit will be inspected and either pass without warnings, pass with warnings or stop with errors. This will allow you to fix code before committing it. Be aware only changed files will be inspected. Also make sure all `pre-commit` have `+x` permissions. + +## Tools + +The following tools are important to test the application and to ensure the code quality. The configurations and sample shell executions can be found in the `Build` directory. These tools are also downloaded during the setup process of the `buildProject.sh` script. + +* composer +* phploc +* phpunit +* phpcs +* phpmetrics +* documentor +* phpstan \ No newline at end of file diff --git a/application/structure.md b/general/structure.md similarity index 79% rename from application/structure.md rename to general/structure.md index c8e44df..692d27b 100644 --- a/application/structure.md +++ b/general/structure.md @@ -1,10 +1,10 @@ # Application Structure & Flow -The user request gets passed through the entire application to all modules. The same goes for the response which gets created at the beginning and passed through the application to be filled. The `WebApplication` automatically forwards the user request to the correct application e.g. `Backend`, `Api`. Inside the application the user request gets routed and the routes are forwarded to the dispatcher which resolves the routes. +The user request gets passed through the entire application to all modules. The same goes for the response which gets created at the beginning and passed through the application to be filled. The `WebApplication` automatically forwards the user request to the correct application e.g. `Backend`, `Api`. Inside the application the user request gets routed and the routes are forwarded to the dispatcher which resolves the routes. The routes usually reference endpoints in the module `controllers` which collects the model data through the model `mapper` and creates a partial response `view` with an assigned `template` and the collected model data. -![Application Flow](Developer-Guide/application/app_flow.svg) +![Application Flow](Developer-Guide/general/app_flow.svg) In the following only the WebApplication and Application are mentioned as the other components are explained in detail in their respective documentation. @@ -27,4 +27,10 @@ The `Application` workload depends heavily on the type of the application but in * App Settings * Page View -Furthermore the Application also performs a `CSRF` check, defines the `CSP`, authenticates the user and handles global errors such as invalid application permission, database connection error etc. \ No newline at end of file +Furthermore the Application also performs a `CSRF` check, defines the `CSP`, authenticates the user and handles global errors such as invalid application permission, database connection error etc. + +## Database + +A short extract of the database structure can be seen below. Please note that this only contains the very basic tables from a fresh install without very limited modules and even then we only included the key tables for simplicity reasons. + +![Application Flow](Developer-Guide/general/base_uml.svg) \ No newline at end of file diff --git a/quality/inspections.md b/quality/inspections.md index a4722d5..c07b05d 100644 --- a/quality/inspections.md +++ b/quality/inspections.md @@ -6,17 +6,53 @@ Code inspections are very important in order to maintain the same code quality t Tools used for the code inspection are: -* PhpLoc -* PhpMetrics -* PhpUnit (see tests) -* Jasmine (see tests) +* PHPUnit +* PHPStan +* Jasmine +* PHPCS * Custom scripts/tools These tools are all installed by running the `setup.sh` script from the Build repository. -## External Tools +## PHPUnit -As external tool scrutinizer is used to automate code inspection and provide insight on issues, bugs, best practices etc. +This application uses PHPUnit as unit testing framework. Unit tests for specific classes need to be named in the same manner as the testing class. + +In order to run all tests and also creating the dummy data for UI tests, execute the following command: + +```sh +php vendor/bin/phpunit -c tests/PHPUnit/phpunit_no_coverage.xml +``` + +In order to also create a code coverage report run: + +```sh +php vendor/bin/phpunit -c tests/PHPUnit/phpunit_default.xml +``` + +### 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 at least 80% is mandatory for every module for integration. + +## PHPStan + +With phpstan the code base is statically analyzed based on its configuration. This will help you to follow some of the "best" practices we enforce. + +```sh +php vendor/bin/phpstan analyse --autoload-file=phpOMS/Autoloader.php -l 7 -c Build/Config/phpstan.neon --error-format=prettyJson ./ > Build/test/phpstan.json +``` + +## 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. + +## PHP CS + +Besides the code tests and static code analysis the code style is another very imporant inspection to ensure the code quality. + +```sh +php vendor/bin/phpcs ./ --standard="Build/Config/phpcs.xml" -s --report-junit=Build/test/junit_phpcs.xml +``` ## Git Hooks (Linux only) diff --git a/quality/tests.md b/quality/tests.md deleted file mode 100644 index 072fec0..0000000 --- a/quality/tests.md +++ /dev/null @@ -1,27 +0,0 @@ -# Tests - -The applications goal is to achive 90% code coverage, which applies for the framework, applications as well as all modules. All unit tests are located in the corresponding `tests` directories. - -## PHPUnit - -This application uses PHPUnit as unit testing framework. Unit tests for specific classes need to be named in the same manner as the testing class. - -In order to run all tests and also creating the dummy data for UI tests, execute the following command: - -```sh -php phpunit.phar -c tests/PHPUnit/phpunit_no_coverage.xml -``` - -In order to also create a code coverage report run: - -```sh -php phpunit.phar -c tests/PHPUnit/phpunit_default.xml -``` - -### 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 at least 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. diff --git a/security/security_guidelines.md b/security/security_guidelines.md index f05324c..e2bd528 100644 --- a/security/security_guidelines.md +++ b/security/security_guidelines.md @@ -107,23 +107,23 @@ Input validation be implemented on multiple levels. 1. Regex validation in html/javascript by using the `pattern=""` attribute 2. Type hints for method parameters wherever possible. 3. Making use of the `Validation` classes as much as possible -4. **Don't** sanitize at all! Accept or dismiss. +4. **Don't** sanitize! Accept or dismiss. ## Inclusion and file paths Be vigilant of where and how the path for the following scenarios comes from: 1. `include $path;` -2. `fopen($path);` -3. `file_get_contents('../relative/path/to/' . $path);` -4. `mkdir($path);` +2. `\fopen($path);` +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: ```php -if(($pathNew = realpath($path)) === false) { +if(($pathNew = \realpath($path)) === false) { throw new PathException($path); } ``` diff --git a/services/codes.md b/services/codes.md index 978165e..9ed6ad2 100644 --- a/services/codes.md +++ b/services/codes.md @@ -10,7 +10,7 @@ Supported codes are: * Aztec * QR -All codes expect the string to encode as parameter, the basic dimensions (width, height) and optionally the orientation for barcodes. The hoirzontal barcode image size will be adjusted automatically based on its length. +All codes expect the string to encode as parameter, the basic dimensions (width, height) and optionally the orientation for barcodes. The horizontal barcode image size will be adjusted automatically based on its length. ```php $c128b = new C128b('ABcdeFG0123+-!@?', 200, 50); diff --git a/setup/developer_environment.md b/setup/developer_environment.md deleted file mode 100644 index d98056a..0000000 --- a/setup/developer_environment.md +++ /dev/null @@ -1,39 +0,0 @@ -# Developer Environment - -The following points are only recommendations to help with the development process. Support for other settings or tools cannot be guaranteed. - -## IDE/Editor - -The following IDEs and editors are recommended - -1. PHPStorm -2. Visual Studio Code - 1. Markdown All in One - 2. PHP Debug - 3. PHP IntelliSense - 4. PHP Server - 5. PHPUnit - 6. SVG Viewer - -## Tools - -The following tools are important to test the application and to ensure the code quality. The configurations and sample shell executions can be found in the `Build` directory. These tools are also downloaded during the setup process of the `buildProject.sh` script (see installation documentation). - -* composer -* phploc -* phpunit -* phpcs -* phpmetrics -* documentor -* phpstan -* phan - -## Git Hooks (Linux only) - -The git hooks perform various checks and validations during the `commit` and warn the developer about invalid code or code style/guideline violations. - -For developers it is recommended to copy the contents of the `default.sh` file in the `Build` repository under `Hooks` to your `pre-commit` file in the `.git/hooks` directory. If the `pre-commit` file doesn't exist just create it. - -The same should be done with every module. Simply go to `.git/modules/**/hooks` and also add the content of the `default.sh` file to all `pre-commit` files. - -By doing this every commit will be inspected and either pass without warnings, pass with warnings or stop with errors. This will allow you to fix code before committing it. Be aware only changed files will be inspected. Also make sure all `pre-commit` have `+x` permissions. \ No newline at end of file diff --git a/setup/installation.md b/setup/installation.md deleted file mode 100644 index 3044bdb..0000000 --- a/setup/installation.md +++ /dev/null @@ -1,67 +0,0 @@ -# Installation - -Installing the application as a developer can be achived by following one of the following instructions. - -## Server Requirements - -* PHP >= 7.2 -* PDO PHP Extension -* mbstring -* database such as mysql -* apache2 - * mod_headers - -### Recommended Extensions - -The following extensions are recommended for tests and in some cases required by the build tools - -* ast -* phear -* memcache -* Sqlite -* socket -* curl -* imap -* bcmath -* zip -* php*-dev -* dom -* xml -* phar -* opcache -* gd / gd2 - -## Linux Shell Script - -This is the preferred way to install the application since this also installs all required dev tools and sets up the directory 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. - -### Steps - -The following steps will setup the application, download all necessary tools and perform extensive code quality checks and documentation tasks: - -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 `config.sh` -4. Run `chmod +x buildProject.sh` -5. Run `./buildProject.sh` - -Alternatively after cloning the git repository: - -1. Run `php composor.phar install` inside `Orange-Management` -2. Run `php phpunit.phar --configuration tests/phpunit_no_coverage.xml` inside `Orange-Management` or open `http://your_url.com/Install` - -This wil only setup the application instead of also performing additional code quality checks. - -### Annotation - -During this process the database automatically gets dropped (if existing) and re-created. 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 ...`. - -## Git Hooks (Linux only) - -The git hooks perform various checks and validations during the `commit` and warn the developer about invalid code or code style/guideline violations. - -For developers it is recommended to copy the contents of the `default.sh` file in the `Build` repository under `Hooks` to your `pre-commit` file in the `.git/hooks` directory. If the `pre-commit` file doesn't exist just create it. - -The same should be done with every module. Simply go to `.git/modules/**/hooks` and also add the content of the `default.sh` file to all `pre-commit` files. - -By doing this every commit will be inspected and either pass without warnings, pass with warnings or stop with errors. This will allow you to fix code before committing it. Be aware only changed files will be inspected. Also make sure all `pre-commit` have `+x` permissions. \ No newline at end of file diff --git a/standards/documentation.md b/standards/documentation.md index 1714d41..5c28f53 100644 --- a/standards/documentation.md +++ b/standards/documentation.md @@ -87,7 +87,7 @@ The javascript documentation is based on JsDoc, therefore only valid JsDoc comme ```js /** - * File description + * File description. * * @package Package name * @copyright Orange Management diff --git a/standards/general.md b/standards/general.md index e2e4754..6906cda 100644 --- a/standards/general.md +++ b/standards/general.md @@ -36,7 +36,7 @@ Always use a whitespace **after**: Always use a whitespace **before** and **after**: * assignment (e.g. `=`, `=>`, `+=`, `/=`, `*=`, `-=`, `.=`) -* math operations (e.g. `+`, `-`, `*`, `/`, `%`, `&`, `|`, `**`, `>>`, `<<`) +* math operations (e.g. `+`, `-`, `*`, `/`, `%`, `&`, `|`, `**`, `>>`, `<<`) * logic operators (e.g. `&&`, `||`) * comparison (e.g. `==`, `===`, `>`, `>=`, `<`, `<=`) @@ -50,11 +50,11 @@ Don't use whitespace inside ANY parentheses (e.g. functions, loops, conditions, ```js for (let i = 1; i < 100; ++i) { ... } -``` +``` ```js function(para1, para2) { ... } -``` +``` ### Brackets @@ -92,7 +92,6 @@ function() ```php class Test { - } ``` @@ -104,7 +103,7 @@ Always use a whitespace before the parentheses. while (true) { ... } -``` +``` ## If, while, for, foreach, switch @@ -159,4 +158,18 @@ All string representations should use single quotes `''` unless `""` provides si ```js 'This is a string' +``` + +## Todos + +Most issues should be documented in the code as todos and vice versa. + +```php +/** + * @todo Orange-Management/Repository#IssueNumber + * Below comes the issue/todo description. + * This way developers can see todos directly in the code without going to an external source. + * Todos must not have empty lines in their descriptions. + * If the external ressources have empty lines they must be removed in the todo comment. + */ ``` \ No newline at end of file diff --git a/standards/php.md b/standards/php.md index 5257cee..840b569 100644 --- a/standards/php.md +++ b/standards/php.md @@ -155,23 +155,3 @@ The following functions and (super-) global variables MAY only be used in the ph * `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()`