diff --git a/SUMMARY.md b/SUMMARY.md index 4c87ad6..f9e27fe 100755 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -18,72 +18,7 @@ * [Css Coding Standards]({%}?page=standards/css) ## Application Examples -* [Application Sample]({%}?page=example_app/web_app) -* [Modules]({%}?page=example_module/module) -* [Packages]({%}?page=example_module/packages) +* [Application Sample]({%}?page=phpOMS/application) +* [Modules]({%}?page=application/module) +* [Packages]({%}?page=application/packages) * [Language Files]({%}?page=basics/language_files) - -## API - -### Backend -* [Codes]({%}?page=services/codes) -* [Routing]({%}?page=basics/routing) -* [Dispatching]({%}?page=basics/dispatching) -* [Views]({%}?page=basics/views) -* [Validation]({%}?page=services/validation) - -### Frontend -* [Notifications]({%}?page=frontend/notifications) - -### Message -* [Uri]({%}?page=services/uri) -* [Requests]({%}?page=basics/requests) -* [Responses]({%}?page=basics/responses) -* [Mail]({%}?page=services/mail) - -### DataStorage -* [LocalStorage]({%}?page=datastorage/localstorage) -* [Database Connection]({%}?page=datastorage/database/connection) -* [DataMapper]({%}?page=datastorage/database/datamapper) -* [Queries]({%}?page=datastorage/database/queries) -* [Cache]({%}?page=datastorage/cache) -* [Session]({%}?page=datastorage/session) -* [Cookie]({%}?page=datastorage/cookie) - -### System -* [Filesystem]({%}?page=services/filesystem) -* [Events]({%}?page=services/events) -* [Logging]({%}?page=services/logging) -* [Tasks]({%}?page=services/tasks) - -### StdLib -* [Localization]({%}?page=services/localization) -* [Money]({%}?page=services/money) -* [Queues]({%}?page=services/queues) -* [Collection]({%}?page=services/collection) - -### Security -* [Encoding]({%}?page=services/encoding) -* [Encryption]({%}?page=services/encryption) - -## UI - -### Layout - -* [Tables]({%}?page=frontend/elements/tables/tables) -* [Data selection]({%}?page=frontend/elements/dataselection/dataselection) -* [Alerts]({%}?page=frontend/elements/alerts/alerts) -* [Buttons]({%}?page=frontend/elements/buttons/buttons) -* [Tags]({%}?page=frontend/elements/tags/tags) -* [Panels]({%}?page=frontend/elements/panels/panels) -* [Tabs]({%}?page=frontend/elements/tabs/tabs) -* [Breadcrumbs]({%}?page=frontend/elements/breadcrumbs/breadcrumbs) -* [Progress]({%}?page=frontend/elements/progress/progress) -* [Layout]({%}?page=frontend/grid/grid) -* [Drag & Drop]({%}?page=frontend/elements/dragndrop/dragndrop) -* [Charting]({%}?page=services/charting) - -### Forms -* [Forms]({%}?page=frontend/forms/forms) -* [Inputs]({%}?page=frontend/elements/inputs/inputs) -* [Tables]({%}?page=frontend/elements/tables/tables) diff --git a/concepts/tables.md b/application/concepts/tables.md old mode 100755 new mode 100644 similarity index 100% rename from concepts/tables.md rename to application/concepts/tables.md diff --git a/example_module/module.md b/application/module.md old mode 100755 new mode 100644 similarity index 93% rename from example_module/module.md rename to application/module.md index f5291f0..9589d02 --- a/example_module/module.md +++ b/application/module.md @@ -9,9 +9,15 @@ The following directory structure should roughly visualize how modules are struc * db.json * Navigation.install.json * Navigation.php + * ... more providing scripts similar to Navigation.* + * Hooks + * Web + * Api.php * Routes + * Cli.php * Web * Backend.php + * Api.php * Update * yourUpdateFiles.??? * Activate.php @@ -19,10 +25,27 @@ The following directory structure should roughly visualize how modules are struc * Installer.php * Uninstall.php * Update.php + * Controller + * BackendController.php + * ApiController.php + * Controller.php + * Controller.js + * Docs + * Dev + * en + * SUMMARY.md + * ... + * Help + * en + * SUMMARY.md + * ... * Img * modulePreviewImage.jpg * Models - * YourPhPModels.php + * YourPHPModel.php + * NullYourPHPModel.php + * YourPHPModelMapper.php + * ... more models/mappers/enums * YourJavaScriptModels.js * Theme * Backend @@ -38,9 +61,8 @@ The following directory structure should roughly visualize how modules are struc * Views * YourPhpViews.php * YourJavaScriptViews.js - * Controller.php - * Controller.js * info.json + * README.md ``` All modules are located inside the `/Modules` directory and their directory name has to be the module name itself without whitespace. @@ -150,11 +172,7 @@ final class Installer extends InstallerAbstract { parent::install($path, $dbPool, $info); - switch ($dbPool->get('core')->getType()) { - case DatabaseType::MYSQL: - /* Your database setup goes here */ - break; - } + /* Your module specific setup goes here */ } } ``` @@ -164,16 +182,16 @@ If your application doesn't need to implement any database tables for itself the ```php public static function installExternal(Pool $dbPool, array $data) : array { - /* What do you want to do with the data provided by $data? */ + /* What do you want to do with the data provided by $data (coming from other modules)? */ } ``` -Other modules have to create a Navigation.php file inside the install directory with the following method: +Install navigation elements: Modules have to create a Navigation.php file inside the install directory with the following method: ```php public static function install(string $path, Pool $dbPool) { - $navData = json_decode(file_get_contents(__DIR__ . '/Navigation.install.json'), true); + $navData = \json_decode(file_get_contents(__DIR__ . '/Navigation.install.json'), true); $class = '\\Modules\\Navigation\\Admin\\Installer'; $class::installExternal($dbPool, $navData); diff --git a/example_module/packages.md b/application/packages.md old mode 100755 new mode 100644 similarity index 100% rename from example_module/packages.md rename to application/packages.md diff --git a/example_module/update.md b/application/update.md old mode 100755 new mode 100644 similarity index 100% rename from example_module/update.md rename to application/update.md diff --git a/example_app/c_app.md b/cOMS/Application.md old mode 100755 new mode 100644 similarity index 96% rename from example_app/c_app.md rename to cOMS/Application.md index 12a0639..2455b25 --- a/example_app/c_app.md +++ b/cOMS/Application.md @@ -1,3 +1,4 @@ +```c++ /** * Karaka * @@ -7,7 +8,6 @@ * @version 1.0.0 * @link https://jingga.app */ - #include #include #include @@ -34,42 +34,42 @@ int main(int argc, char **argv) /* --------------- Basic setup --------------- */ const char *arg = Utils::ApplicationUtils::compile_arg_line(argc, argv); - + // Set program path as cwd char *cwd = Utils::ApplicationUtils::cwd(); if (cwd == NULL) { printf("Couldn't get the CWD\n"); - + return -1; } - + char *cwdT = Utils::StringUtils::search_replace(cwd, "\\", "/"); free(cwd); cwd = cwdT; - + Utils::ApplicationUtils::chdir_application(cwd, argv[0]); - + // Check config if (!Utils::FileUtils::file_exists("config.json")) { Controller::ApiController::notInstalled(argc, argv); - + return -1; } - + /* --------------- App setup --------------- */ - + // Load config FILE *in = fopen("config.json", "r"); if (in == NULL) { printf("Couldn't open config.json\n"); - + return -1; } - + app.config = nlohmann::json::parse(in); - + fclose(in); - + // Setup db connection DataStorage::Database::DbConnectionConfig dbdata = { DataStorage::Database::database_type_from_str(app.config["db"]["core"]["masters"]["admin"]["db"].get_ref().c_str()), @@ -79,47 +79,48 @@ int main(int argc, char **argv) app.config["db"]["core"]["masters"]["admin"]["login"].get_ref().c_str(), app.config["db"]["core"]["masters"]["admin"]["password"].get_ref().c_str(), }; - + app.pool = Threads::pool_create(app.config["app"]["threads"]["count"].get()); - + app.db = DataStorage::Database::create_connection(dbdata); app.db->connect(); - + /* --------------- Handle request --------------- */ - + // Handle routes Router::Router router = generate_routes(&app); Router::RouterFunc ptr = Router::match_route(&router, arg); - + // No endpoint found if (ptr == NULL) { ptr = &Controller::ApiController::printHelp; } - + // Dispatch found endpoint (*ptr)(argc, argv); - + /* --------------- Cleanup --------------- */ - + Threads::pool_destroy(app.pool); - + DataStorage::Database::free_MapperData((DataStorage::Database::MapperData *) &Models::ResourceMapper); - + app.db->close(); app.db = NULL; - + Router::free_router(&router); - + free((char *) arg); arg = NULL; - + // Reset CWD (don't know if this is necessary) chdir(cwd); - + free(cwd); } +``` - +```c++ /** * Karaka * @@ -145,12 +146,12 @@ Router::Router generate_routes(Application::ApplicationAbstract *app) Controller::ApiController::app = app; Router::Router router = Router::create_router(4); - + Router::set(&router, "^.*?\\-h *.*$", (void *) &Controller::ApiController::printHelp); Router::set(&router, "^.*?\\-v *.*$", (void *) &Controller::ApiController::printVersion); Router::set(&router, "^.*?\\-r *.*$", (void *) &Controller::ApiController::checkResources); Router::set(&router, "^.*?\\-\\-install *.*$", (void *) &Controller::InstallController::installApplication); - + return router; } @@ -174,4 +175,5 @@ namespace Controller { } } -#endif \ No newline at end of file +#endif +``` \ No newline at end of file diff --git a/frontend/elements/alerts/alerts.md b/cssOMS/alerts/alerts.md old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/alerts/alerts.md rename to cssOMS/alerts/alerts.md diff --git a/frontend/elements/alerts/error.png b/cssOMS/alerts/error.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/alerts/error.png rename to cssOMS/alerts/error.png diff --git a/frontend/elements/alerts/info.png b/cssOMS/alerts/info.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/alerts/info.png rename to cssOMS/alerts/info.png diff --git a/frontend/elements/alerts/ok.png b/cssOMS/alerts/ok.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/alerts/ok.png rename to cssOMS/alerts/ok.png diff --git a/frontend/elements/alerts/ok_advanced.png b/cssOMS/alerts/ok_advanced.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/alerts/ok_advanced.png rename to cssOMS/alerts/ok_advanced.png diff --git a/frontend/elements/alerts/warning.png b/cssOMS/alerts/warning.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/alerts/warning.png rename to cssOMS/alerts/warning.png diff --git a/frontend/elements/breadcrumbs/breadcrumbs.md b/cssOMS/breadcrumbs/breadcrumbs.md old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/breadcrumbs/breadcrumbs.md rename to cssOMS/breadcrumbs/breadcrumbs.md diff --git a/frontend/elements/breadcrumbs/normal.png b/cssOMS/breadcrumbs/normal.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/breadcrumbs/normal.png rename to cssOMS/breadcrumbs/normal.png diff --git a/frontend/elements/buttons/buttons.md b/cssOMS/buttons/buttons.md old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/buttons/buttons.md rename to cssOMS/buttons/buttons.md diff --git a/frontend/elements/buttons/cancel.png b/cssOMS/buttons/cancel.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/buttons/cancel.png rename to cssOMS/buttons/cancel.png diff --git a/frontend/elements/buttons/cancel_icon.png b/cssOMS/buttons/cancel_icon.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/buttons/cancel_icon.png rename to cssOMS/buttons/cancel_icon.png diff --git a/frontend/elements/buttons/close.png b/cssOMS/buttons/close.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/buttons/close.png rename to cssOMS/buttons/close.png diff --git a/frontend/elements/buttons/close_icon.png b/cssOMS/buttons/close_icon.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/buttons/close_icon.png rename to cssOMS/buttons/close_icon.png diff --git a/frontend/elements/buttons/disabled.png b/cssOMS/buttons/disabled.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/buttons/disabled.png rename to cssOMS/buttons/disabled.png diff --git a/frontend/elements/buttons/disabled_icon.png b/cssOMS/buttons/disabled_icon.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/buttons/disabled_icon.png rename to cssOMS/buttons/disabled_icon.png diff --git a/frontend/elements/buttons/normal.png b/cssOMS/buttons/normal.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/buttons/normal.png rename to cssOMS/buttons/normal.png diff --git a/frontend/elements/buttons/normal_icon.png b/cssOMS/buttons/normal_icon.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/buttons/normal_icon.png rename to cssOMS/buttons/normal_icon.png diff --git a/frontend/elements/buttons/save.png b/cssOMS/buttons/save.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/buttons/save.png rename to cssOMS/buttons/save.png diff --git a/frontend/elements/buttons/save_icon.png b/cssOMS/buttons/save_icon.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/buttons/save_icon.png rename to cssOMS/buttons/save_icon.png diff --git a/frontend/elements/dragndrop/dragndrop.md b/cssOMS/dragndrop/dragndrop.md old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/dragndrop/dragndrop.md rename to cssOMS/dragndrop/dragndrop.md diff --git a/frontend/elements/dragndrop/dragndrop.png b/cssOMS/dragndrop/dragndrop.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/dragndrop/dragndrop.png rename to cssOMS/dragndrop/dragndrop.png diff --git a/frontend/grid/grid.md b/cssOMS/grid/grid.md old mode 100755 new mode 100644 similarity index 100% rename from frontend/grid/grid.md rename to cssOMS/grid/grid.md diff --git a/frontend/grid/grid.png b/cssOMS/grid/grid.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/grid/grid.png rename to cssOMS/grid/grid.png diff --git a/frontend/elements/panels/header_footer.png b/cssOMS/panels/header_footer.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/panels/header_footer.png rename to cssOMS/panels/header_footer.png diff --git a/frontend/elements/panels/panels.md b/cssOMS/panels/panels.md old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/panels/panels.md rename to cssOMS/panels/panels.md diff --git a/frontend/elements/panels/plain.png b/cssOMS/panels/plain.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/panels/plain.png rename to cssOMS/panels/plain.png diff --git a/frontend/elements/progress/meter.png b/cssOMS/progress/meter.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/progress/meter.png rename to cssOMS/progress/meter.png diff --git a/frontend/elements/progress/meter_striped.png b/cssOMS/progress/meter_striped.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/progress/meter_striped.png rename to cssOMS/progress/meter_striped.png diff --git a/frontend/elements/progress/progress.md b/cssOMS/progress/progress.md old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/progress/progress.md rename to cssOMS/progress/progress.md diff --git a/frontend/elements/progress/progress.png b/cssOMS/progress/progress.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/progress/progress.png rename to cssOMS/progress/progress.png diff --git a/frontend/elements/tabs/accordion.png b/cssOMS/tabs/accordion.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/tabs/accordion.png rename to cssOMS/tabs/accordion.png diff --git a/frontend/elements/tabs/highlighted_horizontal.png b/cssOMS/tabs/highlighted_horizontal.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/tabs/highlighted_horizontal.png rename to cssOMS/tabs/highlighted_horizontal.png diff --git a/frontend/elements/tabs/highlighted_vertical.png b/cssOMS/tabs/highlighted_vertical.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/tabs/highlighted_vertical.png rename to cssOMS/tabs/highlighted_vertical.png diff --git a/frontend/elements/tabs/more.png b/cssOMS/tabs/more.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/tabs/more.png rename to cssOMS/tabs/more.png diff --git a/frontend/elements/tabs/more_open.png b/cssOMS/tabs/more_open.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/tabs/more_open.png rename to cssOMS/tabs/more_open.png diff --git a/frontend/elements/tabs/tabs.md b/cssOMS/tabs/tabs.md old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/tabs/tabs.md rename to cssOMS/tabs/tabs.md diff --git a/frontend/elements/tags/dynamic_style.png b/cssOMS/tags/dynamic_style.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/tags/dynamic_style.png rename to cssOMS/tags/dynamic_style.png diff --git a/frontend/elements/tags/icon.png b/cssOMS/tags/icon.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/tags/icon.png rename to cssOMS/tags/icon.png diff --git a/frontend/elements/tags/normal.png b/cssOMS/tags/normal.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/tags/normal.png rename to cssOMS/tags/normal.png diff --git a/frontend/elements/tags/remove_icon.png b/cssOMS/tags/remove_icon.png old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/tags/remove_icon.png rename to cssOMS/tags/remove_icon.png diff --git a/frontend/elements/tags/tags.md b/cssOMS/tags/tags.md old mode 100755 new mode 100644 similarity index 100% rename from frontend/elements/tags/tags.md rename to cssOMS/tags/tags.md diff --git a/general/setup.md b/general/setup.md index f140e0f..9d94773 100755 --- a/general/setup.md +++ b/general/setup.md @@ -12,17 +12,24 @@ Follow the general install/setup documentation until the application setup: [Ins The following dev tools are highly recommended and the documentation assumes you installed them and added them to your environment paths on Windows. On linux they should be accessible immediately after installation. -* [git](https://git-scm.com/) -* [composer](https://getcomposer.org/) -* [npm](https://docs.npmjs.com/) +### Quick software overview -### Quick Setup +```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 -```ssh -sudo apt-get install git poppler-utils tesseract-ocr mysql-server postgresql postgresql-contrib vsftpd tesseract-ocr wget curl grep sed composer 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 +sudo systemctl enable apache2 +sudo mysql_secure_installation +sudo systemctl start mariadb +sudo systemctl enable mariadb sudo a2enmod rewrite +sudo a2enmod expires +sudo a2enmod headers sudo systemctl restart apache2 + +# For c/c++ developers (additional may be required, see below) +sudo apt-get install gcc curl libcurl4-openssl-dev libxml2 libxml2-dev cmake ``` ### IDE / Editor @@ -37,20 +44,32 @@ Which IDE or editor a developer uses is up to the individual developer. From exp Option 1 and 2 require you to install the dev tools in advance! -1. Option: Use the virtual machine we provide for devs which has everything setup and configered to start almost instantly after download **Most Recommended** -2. Option: Installs the application (with a lot of dummy data, this may take a long time). **Recommended (slow but a lot of usefull data)** -3. Option: Installs the application (with or without performing tests). **Recommended (slow and less usefull data)** -4. Option: Full installation, code checks/tests, generating documentation. **Not recomended (slow and less usefull data)** +1. Option: Use the virtual machine we provide for devs which has everything setup and configured to start almost instantly after download **Most Recommended** +2. Option: Installs the application (with a lot of dummy data, this may take a long time). **Recommended (slow but a lot of useful data)** +3. Option: Installs the application (with or without performing tests). **Recommended (slow and much less useful data)** ### Option 1: VM Please contact us if you would like to use our VM, we will send you a download link. 1. Install VirtualBox -2. Download the VM image -3. Setup your IDE (i.e. to use ssh, or mount the git repository, ...) -> The VM has apache2 and a database already running with dummy data for immediate testing. The VM size is less than 10 GB. +2. Download the VM image + +3. Setup your IDE (i.e. to use ssh, or mount the git repository, ...) + 1. Username: jingga + 2. Password: orange + + +> The VM has apache2 and a database already running with dummy data for immediate development. The VM size is 60 GB. + +Additional tools and settings coming with the VM: + +1. Automatic trace and benchmark generation with every web request in `/var/www/html/webgrind/Logs` +2. Webgrind view `http://vm_ip:82` +3. Trace visualization `http://vm_ip:81` + 1. Download the latest trace from `http://vm_ip:82/Logs` + 2. Drag and drop that downloaded `*.xt` file in the trace visualizer ### Option 2: Demo Application @@ -62,7 +81,7 @@ This will only setup the application including some dummy data and also perform 4. Run `git clone -b master https://github.com/Karaka-Management/demoSetup.git` 5. Run `composer install` inside `Karaka` 6. Run `npm install` inside `Karaka` -7. Create the database `oms` in your database management software +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) 9. Run `php demoSetup/setup.php` inside `Karaka` (takes a long time: > 1h) @@ -85,7 +104,7 @@ Instead of calling `php demoSetup/setup.php` which only uses a single thread you #### Profiling -You maybe want to use the following command to run the install script instead in order to also generate a cachegrind output for memory and performance profiling: +You may want to use the following command to run the install script instead in order to also generate a cachegrind output for memory and performance profiling: ```sh php -dxdebug.mode=develop,debug,profile -dxdebug.start_with_request=yes -dxdebug.output_dir=/your/path demoSetup/setup.php @@ -106,44 +125,17 @@ This will only setup the application including some dummy data and also perform 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` +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. 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/` +* Code Coverager: `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. -### Option 4: 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 (this is not the place where you want to install the application) -2. Run `git clone -b develop https://github.com/karaka-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 Coverage: `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 - -> 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 in `Build/Inspection/Php/tests.sh` - ## cOMS If you are interest on working on the c++ code base you will in addition need the following tools and libraries: -* [gcc](https://gcc.gnu.org/) version 7.5.0 or newer -* [cmake](https://cmake.org/) * [OpenCV](https://docs.opencv.org/3.4/d7/d9f/tutorial_linux_install.html) diff --git a/frontend/forms/forms.md b/jsOMS/forms/forms.md old mode 100755 new mode 100644 similarity index 100% rename from frontend/forms/forms.md rename to jsOMS/forms/forms.md diff --git a/frontend/notifications.md b/jsOMS/notifications.md old mode 100755 new mode 100644 similarity index 97% rename from frontend/notifications.md rename to jsOMS/notifications.md index 8d0b76b..72e29dd --- a/frontend/notifications.md +++ b/jsOMS/notifications.md @@ -1,40 +1,40 @@ -# Notifications - -The application supports two types of notifications: - -1. Desktop notifications -2. App notifications - -Both notifications can be used through the `NotificationManager`. - -## Desktop Notifications - -Desktop notifications make use of the `Notification` Api. These notifications allow to inform the user in the browser and desktop. With push notifications it's possible to send notifications directly to the user without waiting for the user to request outstanding notifications. This can be achieved by making use of `Service Workers`. The push notifications are especially helpful for mobile users to inform them about changes in the app (e.g. new message, new task etc.). - -... service worker implementation coming soon ... - -```js -notifyManager.send( - new NotificationMessage( - NotificationStatus.SUCCESS, - 'Title', - 'My Message' - ), - NotificationType.BROWSER_NOTIFICATION -); -``` - -## App notifications - -App notifications are a custom notification implementation which can be themed and manipulated within the app. These notifications are most helpful for direct user interactions/feedback (e.g. giving the user feedback if the input was successful or not). - -```js -notifyManager.send( - new NotificationMessage( - NotificationStatus.SUCCESS, - 'Title', - 'My Message' - ), - NotificationType.APP_NOTIFICATION -); +# Notifications + +The application supports two types of notifications: + +1. Desktop notifications +2. App notifications + +Both notifications can be used through the `NotificationManager`. + +## Desktop Notifications + +Desktop notifications make use of the `Notification` Api. These notifications allow to inform the user in the browser and desktop. With push notifications it's possible to send notifications directly to the user without waiting for the user to request outstanding notifications. This can be achieved by making use of `Service Workers`. The push notifications are especially helpful for mobile users to inform them about changes in the app (e.g. new message, new task etc.). + +... service worker implementation coming soon ... + +```js +notifyManager.send( + new NotificationMessage( + NotificationStatus.SUCCESS, + 'Title', + 'My Message' + ), + NotificationType.BROWSER_NOTIFICATION +); +``` + +## App notifications + +App notifications are a custom notification implementation which can be themed and manipulated within the app. These notifications are most helpful for direct user interactions/feedback (e.g. giving the user feedback if the input was successful or not). + +```js +notifyManager.send( + new NotificationMessage( + NotificationStatus.SUCCESS, + 'Title', + 'My Message' + ), + NotificationType.APP_NOTIFICATION +); ``` \ No newline at end of file diff --git a/example_app/web_app.md b/phpOMS/application.md old mode 100755 new mode 100644 similarity index 93% rename from example_app/web_app.md rename to phpOMS/application.md index 6316ac2..104c310 --- a/example_app/web_app.md +++ b/phpOMS/application.md @@ -1,6 +1,6 @@ # Application Sample -The following application is a minimal sample in order to show how it's possible to set it up. Please note that for simplicity purposes many framework features and architectural aspects are omitted. +The following application is a minimal sample in order to show how it's possible to set up a standalone application with the `phpOMS` framework. Please note that for simplicity purposes many framework features, docblocks and architectural aspects are omitted. ## .htaccess @@ -24,7 +24,8 @@ The .htaccess file can be used to enable URL rewriting, file compression for css In the index file the application gets initialized and executed. ```php -dispatcher->dispatch( $this->router->route( $request->uri->getRoute(), - $request->getData('CSRF'), // optional: only required if csrf tokens are used otherwise use null + $request->getDataString('CSRF'), // optional: only required if csrf tokens are used otherwise use null $request->getRouteVerb() // e.g. get, post, put ... ), $request, // this is passed to the endpoint @@ -158,7 +160,8 @@ class Application extends ApplicationAbstract The routes file contains the routing information. which is responsible for matching URLs to application end-points. ```php - - <?= $this->getData('title'); ?> + <?= $this->getDataString('title') ?? ''; ?>
This is the main template....
What follows next comes from the dispatcher results:
getData('dispatch'); // get data bound to the view with the key "dispatch" + $dispatch = $this->getDataArray('dispatch') ?? []; // get data bound to the view with the key "dispatch" foreach($dispatch as $view) echo $view->render(); // in this case it has a 'render()' method which is called ?>
@@ -225,7 +228,8 @@ The `$dispatch` date is populated in the `Application.php` an can be used in thi A controller file defines the end-point functionality. In this file the response content is generated incl. the date collection for the response. Usually there are two types of controllers, one is a UI controller which is responsible for generating UI content and the other is a API controller which is used to handle API logic (e.g. handling form data such as creating/updating new models). ```php - +
``` diff --git a/basics/dispatching.md b/phpOMS/basics/dispatching.md old mode 100755 new mode 100644 similarity index 100% rename from basics/dispatching.md rename to phpOMS/basics/dispatching.md diff --git a/basics/language_files.md b/phpOMS/basics/language_files.md old mode 100755 new mode 100644 similarity index 100% rename from basics/language_files.md rename to phpOMS/basics/language_files.md diff --git a/basics/requests.md b/phpOMS/basics/requests.md old mode 100755 new mode 100644 similarity index 100% rename from basics/requests.md rename to phpOMS/basics/requests.md diff --git a/basics/responses.md b/phpOMS/basics/responses.md old mode 100755 new mode 100644 similarity index 100% rename from basics/responses.md rename to phpOMS/basics/responses.md diff --git a/basics/routing.md b/phpOMS/basics/routing.md old mode 100755 new mode 100644 similarity index 100% rename from basics/routing.md rename to phpOMS/basics/routing.md diff --git a/basics/views.md b/phpOMS/basics/views.md old mode 100755 new mode 100644 similarity index 100% rename from basics/views.md rename to phpOMS/basics/views.md diff --git a/datastorage/cache.md b/phpOMS/datastorage/cache.md old mode 100755 new mode 100644 similarity index 100% rename from datastorage/cache.md rename to phpOMS/datastorage/cache.md diff --git a/datastorage/cookie.md b/phpOMS/datastorage/cookie.md old mode 100755 new mode 100644 similarity index 100% rename from datastorage/cookie.md rename to phpOMS/datastorage/cookie.md diff --git a/datastorage/database/connection.md b/phpOMS/datastorage/database/connection.md old mode 100755 new mode 100644 similarity index 100% rename from datastorage/database/connection.md rename to phpOMS/datastorage/database/connection.md diff --git a/datastorage/database/datamapper.md b/phpOMS/datastorage/database/datamapper.md old mode 100755 new mode 100644 similarity index 100% rename from datastorage/database/datamapper.md rename to phpOMS/datastorage/database/datamapper.md diff --git a/datastorage/database/queries.md b/phpOMS/datastorage/database/queries.md old mode 100755 new mode 100644 similarity index 100% rename from datastorage/database/queries.md rename to phpOMS/datastorage/database/queries.md diff --git a/datastorage/localstorage.md b/phpOMS/datastorage/localstorage.md old mode 100755 new mode 100644 similarity index 100% rename from datastorage/localstorage.md rename to phpOMS/datastorage/localstorage.md diff --git a/datastorage/session.md b/phpOMS/datastorage/session.md old mode 100755 new mode 100644 similarity index 100% rename from datastorage/session.md rename to phpOMS/datastorage/session.md diff --git a/math/matrix.md b/phpOMS/math/matrix.md old mode 100755 new mode 100644 similarity index 98% rename from math/matrix.md rename to phpOMS/math/matrix.md index b69e1cf..7d113d1 --- a/math/matrix.md +++ b/phpOMS/math/matrix.md @@ -8,7 +8,7 @@ $matrix->setMatrix([ [1, 2, 3], [4, 5, 6], [7, 8, 9], -); +]); ``` The implementation implements `ArrayAccess` for direct access and an `Iterator` for iteration. diff --git a/math/statistics.md b/phpOMS/math/statistics.md old mode 100755 new mode 100644 similarity index 100% rename from math/statistics.md rename to phpOMS/math/statistics.md diff --git a/services/authentication.md b/phpOMS/services/authentication.md old mode 100755 new mode 100644 similarity index 100% rename from services/authentication.md rename to phpOMS/services/authentication.md diff --git a/services/charting.md b/phpOMS/services/charting.md old mode 100755 new mode 100644 similarity index 100% rename from services/charting.md rename to phpOMS/services/charting.md diff --git a/services/codes.md b/phpOMS/services/codes.md old mode 100755 new mode 100644 similarity index 100% rename from services/codes.md rename to phpOMS/services/codes.md diff --git a/services/codes1.png b/phpOMS/services/codes1.png old mode 100755 new mode 100644 similarity index 100% rename from services/codes1.png rename to phpOMS/services/codes1.png diff --git a/services/events.md b/phpOMS/services/events.md old mode 100755 new mode 100644 similarity index 100% rename from services/events.md rename to phpOMS/services/events.md diff --git a/services/filesystem.md b/phpOMS/services/filesystem.md old mode 100755 new mode 100644 similarity index 100% rename from services/filesystem.md rename to phpOMS/services/filesystem.md diff --git a/services/localization.md b/phpOMS/services/localization.md old mode 100755 new mode 100644 similarity index 100% rename from services/localization.md rename to phpOMS/services/localization.md diff --git a/services/logging.md b/phpOMS/services/logging.md old mode 100755 new mode 100644 similarity index 100% rename from services/logging.md rename to phpOMS/services/logging.md diff --git a/services/mail.md b/phpOMS/services/mail.md old mode 100755 new mode 100644 similarity index 100% rename from services/mail.md rename to phpOMS/services/mail.md diff --git a/services/money.md b/phpOMS/services/money.md old mode 100755 new mode 100644 similarity index 100% rename from services/money.md rename to phpOMS/services/money.md diff --git a/services/parsers.md b/phpOMS/services/parsers.md old mode 100755 new mode 100644 similarity index 100% rename from services/parsers.md rename to phpOMS/services/parsers.md diff --git a/services/queues.md b/phpOMS/services/queues.md old mode 100755 new mode 100644 similarity index 100% rename from services/queues.md rename to phpOMS/services/queues.md diff --git a/services/rng.md b/phpOMS/services/rng.md old mode 100755 new mode 100644 similarity index 100% rename from services/rng.md rename to phpOMS/services/rng.md diff --git a/services/tasks.md b/phpOMS/services/tasks.md old mode 100755 new mode 100644 similarity index 100% rename from services/tasks.md rename to phpOMS/services/tasks.md diff --git a/services/uri.md b/phpOMS/services/uri.md old mode 100755 new mode 100644 similarity index 100% rename from services/uri.md rename to phpOMS/services/uri.md diff --git a/services/validation.md b/phpOMS/services/validation.md old mode 100755 new mode 100644 similarity index 100% rename from services/validation.md rename to phpOMS/services/validation.md diff --git a/quality/inspections.md b/quality/inspections.md index 37268ba..feff184 100755 --- a/quality/inspections.md +++ b/quality/inspections.md @@ -1,12 +1,12 @@ # 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 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 the standards. +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. ## Summary The following automated tests must pass without errors, failures and warnings for successful code changes: -* `php ./vendor/bin/phpstan analyse --autoload-file=phpOMS/Autoloader.php -l 9 -c Build/Config/phpstan.neon ./` +* `php ./vendor/bin/phpstan analyse -l 9 -c Build/Config/phpstan.neon ./` * `php ./vendor/bin/phpcs --severity=1 ./ --standard="Build/Config/phpcs.xml"` * `php ./vendor/bin/phpunit -c tests/phpunit_no_coverage.xml` * `php ./vendor/bin/rector process --config Build/Config/rector.php --dry-run ./` @@ -15,7 +15,7 @@ The following automated tests must pass without errors, failures and warnings fo * `./cOMS/tests/test.sh` * see [other checks](#other-checks) below -Alternatively you can simply run the helper script in the Build repository, which executes all the above mentioned checks: +Alternatively you can simply run the helper script in the Build repository, which executes a few of the above mentioned checks: ```sh ./Build/Helper/inspectproject.sh @@ -48,7 +48,7 @@ When testing it makes sense to test for the happy path/branch of how a method sh * C++ framework + tools: cOMS/tests * Css framework: cssOMS/tests * Configurations for tools: Build/Config -* Inspection script: Build/Inspection/inspection.sh +* Inspection script: Build/php.sh or Builde/Helper/Scripts/inspectproject.sh ### Unit tests @@ -69,7 +69,7 @@ The system tests are the highest level of tests and test the overall functionali Every module must implement the following tests if applicable: * general module tests (e.g. install, update, delete, status change) -* admin tests (`use \Modules\tests\ModuleTestTrait;`) +* admin tests (`use \tests\Modules\ModuleTestTrait;`) * model tests (unit tests) * controller tests (e.g. ApiController tests) * view tests @@ -119,6 +119,7 @@ Tools used for the code inspection are: * PHPStan * Jasmine * PHPCS +* Rector * Custom scripts/tools These tools are all installed by running the `setup.sh` script from the Build repository. @@ -136,19 +137,31 @@ php vendor/bin/phpunit -c tests/PHPUnit/phpunit_no_coverage.xml In order to also create a code coverage report run: ```sh -php -dxdebug.remote_enable=1 -dxdebug.mode=coverage,develop vendor/bin/phpunit -c tests/phpunit_default.xml +php -dxdebug.remote_enable=1 -dxdebug.mode=coverage,develop vendor/bin/phpunit -c tests/phpunit_default.xml --log-junit Build/test/junit_php.xml --coverage-html Build/coverage ``` +A visualization of the coverage can be found at http://127.0.0.1/Build/coverage + #### 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 90% is mandatory for every module for integration. +### PHPmetrics + +While phpmetrics doesn't provide additional tests it is useful to visualize dependencies and potentially critical code. Including the junit report `junit_php.xml` in the command below requires you to run the PHPUnit tests first. + +```sh +php vendor/bin/phpmetrics --config=Build/Config/phpmetrics.json --junit=Build/test/junit_php.xml --report-html=Build/test/metrics +``` + +A visualization of the metrics can be found at http://127.0.0.1/Build/test/metrics + ### 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 9 -c Build/Config/phpstan.neon --error-format=prettyJson ./ > Build/test/phpstan.json +php vendor/bin/phpstan analyse -l 9 -c Build/Config/phpstan.neon --error-format=prettyJson ./ > Build/test/phpstan.json ``` ### PHP CS @@ -161,6 +174,12 @@ php vendor/bin/phpcs --severity=1 ./ --standard="Build/Config/phpcs.xml" -s --re > Many IDEs allow to integrate phpcs rules/configuration files for automatic checks in the editor +### Rector + +```sh +php vendor/bin/rector process --dry-run --config Build/Config/rector.php ./ +``` + ### 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 5294ec0..397bdcb 100755 --- a/security/security_guidelines.md +++ b/security/security_guidelines.md @@ -51,18 +51,29 @@ The following headers must be set for every web application. By default they are ### 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. +Scripts and frames must be provided by the own server. 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: ```php -$response->header->set('content-security-policy', 'script-src \'self\'; frame-src \'self\'', true); +$scriptSrc = \bin2hex(\random_bytes(32)); +$this->app->appSettings->setOption('script-nonce', $scriptSrc); +$response->header->set('content-security-policy', + 'base-uri \'self\';' + . 'object-src \'none\';' + . 'script-src \'nonce-' . $scriptSrc . '\' \'strict-dynamic\';' + . 'worker-src \'self\';' +); ``` -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. +Javascript can now be included like this: ```php -$response->header->set('content-security-policy', 'script-src \'self\' \'sha256-' . base64_encode(hash('sha256', $script, true)) . '\'; frame-src \'self\'', true); +$head = $response->data['Content']->head; +$nonce = $this->app->appSettings->getOption('script-nonce'); + +$head->addAsset(AssetType::JSLATE, 'Resources/chartjs/Chartjs/chart.js', ['nonce' => $nonce]); +$head->addAsset(AssetType::JSLATE, 'Modules/ItemManagement/Controller.js', ['nonce' => $nonce, 'type' => 'module']); ``` ### X-XSS-Protection @@ -107,7 +118,7 @@ Input validation can 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! Accept or dismiss! +4. **Do not** sanitize! Accept or dismiss! ## Inclusion and file paths @@ -118,12 +129,12 @@ 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. - -Example usage: +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. If a file path is provided or influenced by a user you can make sure that it is within a trusted subdirectory: ```php -if(($pathNew = \realpath($path)) === false) { - throw new PathException($path); +if (!Guard::isSafePath($outputDir, __DIR__ . '/../../../')) { + return; } ``` + +Using this guard ensures that a file path is within the provided path. diff --git a/standards/documentation.md b/standards/documentation.md index 4078203..e31d8c0 100755 --- a/standards/documentation.md +++ b/standards/documentation.md @@ -175,7 +175,7 @@ In some cases it may be required to type hint a variable in this case the follow ## Todos -Todos should be documented in the [PROJECT.md](https://github.com/Karaka-Management/Organization-Guide/blob/master/Project/PROJECT.md). +Todos should be documented in the [todo list](https://github.com/orgs/Karaka-Management/projects/10). In code todos can be created like this diff --git a/standards/php.md b/standards/php.md index 1e19d3d..c81985e 100755 --- a/standards/php.md +++ b/standards/php.md @@ -108,7 +108,21 @@ $arr = [1, 2, 3]; ### file_exists -Instead of using `\file_exists()` the functions `\is_dir()` or `\is_file()` should be used. +Instead of using `\file_exists()` the functions `\is_dir()` or `\is_file()` should be used. `\file_exists()` should be only used if the programmer doesn't know if the provided path is a file or directory. + +### String starts with / ends with + +Instead of using `\stripos() === 0` to check if a string starts with a certain string use `\str_starts_with()`. Similarly use `\str_ends_with()` + +### str_replace + +Whenever possible instead of using `\str_replace()` use the function `\strtr()`. + +> Careful, \strtr() **DOES NOT** support deleting a character = replace it with an empty string! + +### json_encode + +For simple static arrays `\json_encode()` should be avoided and a manual json string generation should be used. ## Enum