diff --git a/ICAL.txt b/ICLA.txt old mode 100755 new mode 100644 similarity index 100% rename from ICAL.txt rename to ICLA.txt diff --git a/SUMMARY.md b/SUMMARY.md index e7c58b4..3b0b609 100755 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -21,11 +21,3 @@ * [Application Sample]({%}?page=phpOMS/application) * [Modules]({%}?page=application/module) * [Packages]({%}?page=application/packages) - -## phpOMS - -## jsOMS - -## cssOMS - -## cOMS \ No newline at end of file diff --git a/application/concepts/tables.md b/application/concepts/tables.md index da95f99..7625a89 100644 --- a/application/concepts/tables.md +++ b/application/concepts/tables.md @@ -20,8 +20,8 @@ Url parameters: * `n` means that elements to the **right/below** of `id` should be shown * `sort_by` defines the column which is used to sort the data * `sort_order` defines what **left/above** and **right/below** mean - * `ASC` means ascending and therfore defines **left/above** as smaller elements and **right/below** as larger elements - * `DESC` means descending and therfore defines **left/above** as larger elements and **right/below** as smaller elements + * `ASC` means ascending and therefore defines **left/above** as smaller elements and **right/below** as larger elements + * `DESC` means descending and therefore defines **left/above** as larger elements and **right/below** as smaller elements * `subid` defines the id of the `sort_by` column IFF `sort_by` is not the primary field. > The maximum amount of elements returned depend on the defined limit. diff --git a/general/first_steps.md b/general/first_steps.md index ecf7582..e0b469c 100755 --- a/general/first_steps.md +++ b/general/first_steps.md @@ -51,7 +51,7 @@ All tests need to have the following docblocks: #### Module documentation -Modules have a `Help` and a `Dev` documentation both are insifficient for most modules. Feel free to add some documentation. Consider to use images wherever helpful. Consider to add the used images to https://github.com/Karaka-Management/Build/blob/master/Js/createImages.js which will automatically create new images even if the style changes or minor layout changes are made. +Modules have a `Help` and a `Dev` documentation both are insufficient for most modules. Feel free to add some documentation. Consider to use images wherever helpful. Consider to add the used images to https://github.com/Karaka-Management/Build/blob/master/Js/createImages.js which will automatically create new images even if the style changes or minor layout changes are made. ```js ... diff --git a/general/setup.md b/general/setup.md index 3612129..4c7004c 100755 --- a/general/setup.md +++ b/general/setup.md @@ -16,7 +16,7 @@ The following dev tools are highly recommended and the documentation assumes you ```sh # For php/html/javascript developers -sudo apt-get install git poppler-utils mariadb-server mariadb-client postgresql postgresql-contrib vsftpd tesseract-ocr wget curl grep sed composer nodejs npm software-properties-common php8.1 php8.1-dev php8.1-cli php8.1-common php8.1-mysql php8.1-pgsql php8.1-xdebug php8.1-opcache php8.1-pdo php8.1-sqlite php8.1-mbstring php8.1-curl php8.1-imap php8.1-bcmath php8.1-zip php8.1-dom php8.1-xml php8.1-phar php8.1-gd php-pear apache2 redis redis-server memcached sqlite3 wkhtmltopdf imagemagick +sudo apt-get install git poppler-utils mariadb-server mariadb-client postgresql postgresql-contrib vsftpd tesseract-ocr wget curl grep sed composer nodejs npm software-properties-common php8.2 php8.2-dev php8.2-cli php8.2-common php8.2-intl php8.2-mysql php8.2-pgsql php8.2-xdebug php8.2-opcache php8.2-pdo php8.2-sqlite php8.2-mbstring php8.2-curl php8.2-imap php8.2-bcmath php8.2-zip php8.2-dom php8.2-xml php8.2-phar php8.2-gd php-pear apache2 redis redis-server memcached sqlite3 wkhtmltopdf imagemagick sudo systemctl enable apache2 sudo mysql_secure_installation @@ -72,7 +72,7 @@ Additional tools and settings coming with the VM: 1. Download the latest trace from `http://vm_ip:82/Logs` 2. Drag and drop that downloaded `*.xt` file in the trace visualizer 5. `sitespeed.io ./Build/Helper/Scripts/sitespeedDemoUrls.txt -b chrome --outputFolder /var/www/html/sitespeed` -6. Slow sql query threashold is defined as 0.5s. +6. Slow sql query threshold is defined as 0.5s.

@@ -89,14 +89,14 @@ This will only setup the application including some dummy data and also perform 5. Run `composer install` inside `Karaka` 6. Run `npm install` inside `Karaka` 7. Create the database `omd` in your database management software -8. Adjust the `demoSetup/config.php` file according to your settings (e.g. database user name + password) +8. Adjust the `demoSetup/config.php` file according to your settings (e.g. database user + password) 9. Run `php demoSetup/setup.php` inside `Karaka` (takes a long time: > 2h) After the installation you'll have access to the following content: * Application: `http://127.0.0.1` -Instead of calling `php demoSetup/setup.php` which only uses a single thread you may also run `php demoSetup/setup.php -a 0` which will execute the install script in multiple threads leading to most likely 100% CPU and storage usage but therfore significantly reduce the execution time. +Instead of calling `php demoSetup/setup.php` which only uses a single thread you may also run `php demoSetup/setup.php -a 0` which will execute the install script in multiple threads leading to most likely 100% CPU and storage usage but therefore significantly reduce the execution time. > You may want to call the setup script as a different user to ensure the same permissions `sudo -u wwww-data php demoSetup/setup.php` @@ -130,14 +130,15 @@ This will only setup the application including some dummy data and also perform 3. Run `git submodule foreach git checkout develop` 4. Run `composer install` inside `Karaka` 5. Run `npm install` inside `Karaka` -6. Create the database `oms` in your database management software -7. Adjust the `tests/Bootstrap.php` file according to your settings (e.g. database user name + password) -8. Run `php -dxdebug.mode=develop,debug,profile,coverage -dxdebug.start_with_request=yes vendor/bin/phpunit --configuration tests/phpunit_default.xml` inside `Karaka` or open `http://127.0.0.1/Install` for a web install without dummy data. +6. Create the database `omt` in your database management software +7. Create the database user `test` with the password `orange` +8. Adjust the `tests/Bootstrap.php` file according to your settings (e.g. database user name + password) +9. Run `php -dxdebug.mode=develop,debug,profile,coverage -dxdebug.start_with_request=yes vendor/bin/phpunit --configuration tests/phpunit_default.xml` inside `Karaka` or open `http://127.0.0.1/Install` for a web install without dummy data. After the installation you'll have access to the following content: * Application: `http://127.0.0.1` -* Code Coverager: `http://127.0.0.1/tests/coverage/` +* Code Coverage: `http://127.0.0.1/tests/coverage/` > During this process the database automatically gets dropped (if it exists) and re-created. If you don't have `xdebug` installed but `phpdbg` you can replace `php phpunit ...` with `phpdbg -qrr phpunit.phar ...` or use `pcov` for much faster code coverage generation. diff --git a/phpOMS/basics/language_files.md b/phpOMS/basics/language_files.md index aa61d84..ab86ffe 100644 --- a/phpOMS/basics/language_files.md +++ b/phpOMS/basics/language_files.md @@ -15,7 +15,7 @@ The content of the language files is very simple. All you need is the module nam /** * Jingga * - * PHP Version 8.1 + * PHP Version 8.2 * * @copyright Dennis Eichhorn * @license OMS License 1.0 diff --git a/phpOMS/basics/views.md b/phpOMS/basics/views.md index 3094662..fd6c93f 100644 --- a/phpOMS/basics/views.md +++ b/phpOMS/basics/views.md @@ -14,7 +14,7 @@ The base view class contains the request as well as the response objects hence i 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()`. -In html templates it's recommended to use `$this->getHtml({TEXT_ID})` as this will safely escape static/defined strings (see language files) for html output. By default the language file of the current module is used for the translation, if you would like to use a translation from another module you have to specify the module name and the template name e.g. `getHtml('Word', 'ModuleName', 'TemplateName'); ?>`. This only works if the specified module is available and therefore it is only recommended to use this if the current module has a dependency defined on the specified module which ensures its availability. +In html templates it's recommended to use `$this->getHtml({TEXT_ID})` as this will safely escape static/defined strings (see language files) for html output. By default the language file of the current module is used for the translation, if you would like to use a translation from another module you have to specify the module name and the template name e.g. `getHtml('Word', 'ModuleName', 'TemplateName'); ?>`. This only works if the specified module is available and therefore it is only recommended to use this if the current module has a dependency defined on the specified module which ensures its availability. Furthermore there is also a global translation file for common translations, this can be accessed as follows `getHtml('Word', '0', '0'); ?>`. Common translations are for example `ID`, `Submit`, `Send`, `Cancel` etc. diff --git a/phpOMS/datastorage/cache.md b/phpOMS/datastorage/cache.md index aaa4d81..9174b01 100644 --- a/phpOMS/datastorage/cache.md +++ b/phpOMS/datastorage/cache.md @@ -1,6 +1,6 @@ # Cache -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 therefor shouldn't be misused 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 therefore shouldn't be misused 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 diff --git a/phpOMS/datastorage/session.md b/phpOMS/datastorage/session.md index abe24b6..2ccb503 100644 --- a/phpOMS/datastorage/session.md +++ b/phpOMS/datastorage/session.md @@ -8,4 +8,4 @@ The Http session will be saved automatically, there is no need to access the sup ## Socket & Console -The session will be stored and associated 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 associated with the logged in user in memory. A disconnect or quit is considered as a logout and therefore results in the destruction of the session object of this user and will be empty for the next login. diff --git a/phpOMS/services/localization.md b/phpOMS/services/localization.md index d0c41b6..7097a27 100644 --- a/phpOMS/services/localization.md +++ b/phpOMS/services/localization.md @@ -16,7 +16,7 @@ or indirectly by calling the `getText()` in the view context. $this->getText({TEXT}) ``` -The language that should be used for a response should always be depending on the requested language and therefore never be hard coded. +The language that should be used for a response should always be depending on the requested language and therefore never be hard coded. The language code of the localization object is the 2 character ISO639 code. The corresponding enums are located in the localization directory and labeled with `ISO639`. @@ -58,7 +58,7 @@ $money->getCurrency(2, ',', '.', '$', 0); ### DateTime -The date/time is versatile and can have multiple formats. By default the localization object stores 5 different date/time formats depending on the degree of accuracy required. +The date/time is versatile and can have multiple formats. By default the localization object stores 5 different date/time formats depending on the degree of accuracy required. * very_short * short diff --git a/quality/inspections.md b/quality/inspections.md index fae0563..e861c75 100755 --- a/quality/inspections.md +++ b/quality/inspections.md @@ -1,6 +1,6 @@ # Code Inspections & Tests -Code inspections are very important in order to maintain the same code quality throughout the application. The `Build` repository and package managers such as `composer` and `npm` contain all essential configuration files for the respective php and javascript inspection tools. The framework and every module will be evaluated based on the defined code and quality standards. Only code that passes all code, quality and test standards is accepted. Updates and bug fixes also must follow these standards. +Code inspections are very important in order to maintain the same code quality throughout the application. The [Build](https://github.com/Karaka-Management/Build) repository and package managers such as `composer` and `npm` contain all essential configuration files for the respective php and javascript inspection tools. The framework and every module will be evaluated based on the defined code and quality standards. Only code that passes all code, quality and test standards is accepted. Updates and bug fixes also must follow these standards. ## Summary @@ -13,9 +13,8 @@ The following automated tests must pass without errors, failures and warnings fo * `php ./vendor/bin/phpunit -c tests/phpunit_no_coverage.xml` * `php ./vendor/bin/rector process --config Build/Config/rector.php --dry-run ./` * `npx eslint ./ -c Build/Config/.eslintrc.json` -* `npx jasmine-node ./` +* `./Build/Config/jasmine_build.sh && npx jasmine --config=Build/Config/jasmine.json` * `./cOMS/tests/test.sh` -* see [other checks](#other-checks) below

@@ -27,7 +26,7 @@ Alternatively you can simply run the helper script in the Build repository, whic ./Build/Helper/inspectproject.sh ``` -An overview of all tests and statistics can be found at https://dev.jingga.app. Navigate to the ./src directory and then open the ./src/**/build directory of the respective repository. +An overview of all tests and statistics can be found at https://dev.jingga.app. Navigate to the `./src` directory and then open the `./src/**/build` directory of the respective repository. > Manual tests and inspections may reveal further issues during the review process requiring additional code changes @@ -49,14 +48,15 @@ When testing it makes sense to test for the happy path/branch of how a method sh ### Test locations -* Application: tests -* Php framework: phpOMS/tests -* Modules: Modules/**/tests -* Js framework: jsOMS/tests -* C++ framework + tools: cOMS/tests -* Css framework: cssOMS/tests -* Configurations for tools: Build/Config -* Inspection script: Build/php.sh or Builde/Helper/Scripts/inspectproject.sh +* Application: `tests` +* Php framework: `phpOMS/tests` +* Modules: `Modules/**/tests` +* Js framework: `jsOMS/tests` +* C++ framework + tools: `cOMS/tests` +* Css framework: `cssOMS/tests` +* Configurations for tools: `Build/Config` +* Inspection script: `Build/php.sh` or `Build/Helper/Scripts/inspectproject.sh` +* End-to-End: `tests/Web` ### Unit tests @@ -68,15 +68,15 @@ Integration tests are the second level or middle level of tests. These types of For large controllers it can make sense to define a `*ControllerTest` which uses `Traits` in order to categorize different suits of tests. For example in the `Admin` ApiControllerTest we implemented different traits for group, account and module tests. -### System tests +### User/End-To-End -The system tests are the highest level of tests and test the overall functionality and if the implementation fulfills the specifications. +The User/End-To-End tests are the highest level of tests and test the overall functionality and if the implementation fulfills the specifications. ### Modules Every module must implement the following tests if applicable: -* general module tests (e.g. install, update, delete, status change) +* general module tests (e.g. `AdminTest.php`, install, update, delete, status change) * admin tests (`use \tests\Modules\ModuleTestTrait;`) * model tests (unit tests) * controller tests (e.g. ApiController tests) @@ -96,14 +96,22 @@ The following command will create a demo application: php demoSetup/setup.php ``` -> You might want to call the setup script as a different user to ensure the same permissions `sudo -u wwww-data php demoSetup/setup.php` +> You might want to call the setup script as a different user to ensure the same permissions `sudo -u wwww-demo php demoSetup/setup.php` or `sudo -u wwww-data php demoSetup/setup.php` -In some cases code changes may require changes to the demo setup script (e.g. changes in the api, new modules). Since the demo setup script tries to simulate user generated data it takes some time to run. You may speed up the runtime by parallelizing the execution. However, this may use up 100% of your CPU and storage performance. +In some cases code changes may require changes to the demo setup script (e.g. changes in the api, new modules). Since the demo setup script tries to simulate user generated data it takes some time to run. You may speed up the runtime by parallelizing the execution. However, this may use up 100% of your CPU and storage performance: ```sh php demoSetup/setup.php -a 0 ``` +### End-To-End tests + +End-To-End tests simulate the user interaction with the application in the browser. These tests can be found in `tests/Web` and can only be run on a machine with `Chrome` and a window manager installed (these tests don't run in a pure CLI environment). + +```sh +node test/Web/Backend/Install.js +``` + ### UI tests While UI tests can be part of unit, integration or system tests the `cssOMS` repository also includes a simple test suit at [http://127.0.0.1/cssOMS/tests/app](http://127.0.0.1/cssOMS/tests/app) which allows developers to test UI elements and check how they work. @@ -116,8 +124,8 @@ In the demo application it is possible to highlight html and css warnings (e.g. * every test must have a short test description * every test and description must be added to the test report -* every test needs a test category (e.g. framework, module etc.) -* every test should have a @covers annotation to specify which class it covers +* every test needs a test category (for PHPUnit tests) (e.g. framework, module etc.) +* every test should have a covers attribute (for PHPUnit tests) to specify which class it covers ## Tools @@ -216,9 +224,11 @@ php vendor/bin/rector process --dry-run --config Build/Config/rector.php ./ 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. ```sh -npx jasmine-node ./ +./Build/Config/jasmine_build.sh && npx jasmine --config=Build/Config/jasmine.json ``` +Alternatively you can open `http://127.0.0.1/jsOMS/tests/SpecRunner.html` to run the tests in your browser. + ### JS Eslint The js code base has a defined code style standard. The easiest way to check for most rules is to run eslint. @@ -247,7 +257,7 @@ sitespeed.io ./Build/Helper/Scripts/sitespeedDemoUrls.txt -b chrome --outputFold ### SQL performance -With query profiling enabled you can inspect slow running queries that may need optimization. The threashold for slow running queries is defined at 0.5s. +With query profiling enabled you can inspect slow running queries that may need optimization. The threshold for slow running queries is defined at 0.5s. ```sh mysqldumpslow -t 10 /var/log/mysql/mysql-slow.log @@ -305,6 +315,26 @@ The following checks should also be performed. If you use the git hooks from the * Has logs * Has whitespace at line end +## Classification + +```mermaid +quadrantChart; + x-axis Low Level --> High Level; + y-axis Low Importance --> High Importance; + PHPStan: [0.2, 0.5]; + *UI tests: [0.8, 0.05]; + PHPCS/CBF/Fixer/Rector/eslint: [0.1, 0.1]; + PHPUnit: [0.5, 0.75]; + cOMS/tests.sh: [0.2, 0.2]; + Jasmine: [0.3, 0.5]; + *Selenium: [0.9, 0.9]; + *Sitespeed: [0.75, 0.25]; + *Demo: [0.95, 0.95]; + *Other: [0.3, 0.05]; +``` + +\* Optional and/or manual + ## References [Development process](https://github.com/Karaka-Management/Organization-Guide/blob/master/Processes/01_Development.md) diff --git a/standards/cpp.md b/standards/cpp.md index 678b689..7271320 100755 --- a/standards/cpp.md +++ b/standards/cpp.md @@ -43,7 +43,7 @@ Don't use C++ standard functions or C++ functions provided by other C++ header f ### Parameters -Generally, functions that thake pointers to non-scalar types should modify the data instead of allocating new memory **IF** reasonable. This forces programmers to consciously create copies before passing data **IF** they need the original data. To indicate that a reference/pointer is not modified by a function define them as const! +Generally, functions that take pointers to non-scalar types should modify the data instead of allocating new memory **IF** reasonable. This forces programmers to consciously create copies before passing data **IF** they need the original data. To indicate that a reference/pointer is not modified by a function define them as const! We believe this approach provides a framework for better memory management and better performance in general. diff --git a/standards/documentation.md b/standards/documentation.md index bc20f8c..abbed6e 100755 --- a/standards/documentation.md +++ b/standards/documentation.md @@ -32,7 +32,7 @@ Every module that has a database table must implement a UML diagram illustrating ## Php -The php documentation is based on PhpDocumentor, therefore only valid PhpDocumentor comments are valid for files, classes, functions/methods and (member) variables. +The php documentation is based on PhpDocumentor, therefore only valid PhpDocumentor comments are valid for files, classes, functions/methods and (member) variables. ### File @@ -111,7 +111,7 @@ Example: ## JavaScript -The javascript documentation is based on JsDoc, therefore only valid JsDoc comments are valid for all js files. +The javascript documentation is based on JsDoc, therefore only valid JsDoc comments are valid for all js files. ### File diff --git a/standards/general.md b/standards/general.md index 391f679..fe4ac34 100755 --- a/standards/general.md +++ b/standards/general.md @@ -32,7 +32,7 @@ Getters and setters for member variables should be kept at a absolute minimum an ### Why are we using public so much? -* Private/protected adds a huge amount of unneccessary typing without gaining much/anything +* Private/protected adds a huge amount of unnecessary typing without gaining much/anything * Getters/setters may hide unsuspecting side effects * Adding additional functionality afterwards if it becomes necessary is easy by changing the member to private and letting the static code inspection tools find the callers * Performance overhead (function calls, data mappers)