mirror of
https://github.com/Karaka-Management/Developer-Guide.git
synced 2026-01-11 20:38:42 +00:00
spellchecking
This commit is contained in:
parent
7b3b0ef7ae
commit
adc1a5299e
|
|
@ -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 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.
|
||||
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 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.
|
||||
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.
|
||||
|
|
@ -4,7 +4,7 @@ Responses can be either outgoing responses such as http or socket responses on t
|
|||
|
||||
## Http Response
|
||||
|
||||
A response can be defined with the `set()` function and the body of the response can be generated/rendered witth the `getBody()` function.
|
||||
A response can be defined with the `set()` function and the body of the response can be generated/rendered with the `getBody()` function.
|
||||
|
||||
```php
|
||||
$response->set('response_id', {stringifiable_element});
|
||||
|
|
@ -54,11 +54,11 @@ In order to change the response type the header `content-type` must be changed.
|
|||
$response->header->set('content-type', '....', true);
|
||||
```
|
||||
|
||||
The boolean flag at the end forces an overwrite of the previous response type. If this flag is not set the response type will not be overwritten. The reason for this flag is to protect header elements from accidentially getting overwritten.
|
||||
The boolean flag at the end forces an overwrite of the previous response type. If this flag is not set the response type will not be overwritten. The reason for this flag is to protect header elements from accidentally getting overwritten.
|
||||
|
||||
### Sending Headers
|
||||
|
||||
> After the headers are sent it is not possible to change the headers or re-send them, the header is locked!. Usually you don't have to worry about this since the headers are automatically sent just bevore the content gets rendered.
|
||||
> After the headers are sent it is not possible to change the headers or re-send them, the header is locked!. Usually you don't have to worry about this since the headers are automatically sent just before the content gets rendered.
|
||||
|
||||
### Text/Html Response
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Routing
|
||||
|
||||
Routing allows to bind a string representation to a function. This is required in order to execute request specific code segments. One very common scenario for routing is to take the url of a http(s) request and assign it to a function located in a controller.
|
||||
Routing allows to bind a string representation to a function. This is required in order to execute request specific code segments. One very common scenario for routing is to take the URL of a http(s) request and assign it to a function located in a controller.
|
||||
|
||||
## Routes
|
||||
|
||||
|
|
@ -82,7 +82,7 @@ In this schematic the first route has different destinations depending on the ve
|
|||
|
||||
With request verbs it's possible to use the same request path and assign different endpoints to them. This is helpful when you want to have the same path for retrieving data and changing data. This is a normal situation in web development e.g.
|
||||
|
||||
Let's assume we have the url `https://yoururl.com/user/1/name` if we make a `GET` request we could return the name for the user `1` and if we make a `POST` request we could update the name for the user `1` and use the same url.
|
||||
Let's assume we have the URL `https://yoururl.com/user/1/name` if we make a `GET` request we could return the name for the user `1` and if we make a `POST` request we could update the name for the user `1` and use the same url.
|
||||
|
||||
Allowed request verbs are:
|
||||
|
||||
|
|
|
|||
|
|
@ -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 savely 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. `<?= $this->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. `<?= $this->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 `<?= $this->getHtml('Word', '0', '0'); ?>`. Common translations are for example `ID`, `Submit`, `Send`, `Cancel` etc.
|
||||
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ $head->addAsset(AssetType::JS, $request->uri->getBase() . 'Modules/Media/Control
|
|||
|
||||
## System Cache
|
||||
|
||||
All cache systems implement very similar functionality. It is only due to different features of the underlying technologie that some minor details are different between the different cache solutions.
|
||||
All cache systems implement very similar functionality. It is only due to different features of the underlying technology that some minor details are different between the different cache solutions.
|
||||
|
||||
The available cache solutions are:
|
||||
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ The following application is a minimal sample in order to show how it's possible
|
|||
|
||||
```txt
|
||||
# .htaccess
|
||||
# enable url rewriting
|
||||
# enable URL rewriting
|
||||
<ifmodule mod_rewrite.c>
|
||||
RewriteEngine On
|
||||
RewriteBase /
|
||||
|
|
@ -77,7 +77,7 @@ class Application extends ApplicationAbstract
|
|||
// bind the page view to the response object. This is rendered later on.
|
||||
$response->set('Content', $pageView);
|
||||
|
||||
/* get data from url endpoints defined by the routes */
|
||||
/* get data from URL endpoints defined by the routes */
|
||||
$dispatch = $this->dispatcher->dispatch(
|
||||
$this->router->route(
|
||||
$request->uri->getRoute(),
|
||||
|
|
@ -105,7 +105,7 @@ class Application extends ApplicationAbstract
|
|||
// initialize request from the superglobals which are automatically populated
|
||||
$request = Request::createFromSuperglobals();
|
||||
|
||||
// optional: will transform the url path and sub-paths to hashs
|
||||
// optional: will transform the URL path and sub-paths to hashs
|
||||
$request->createRequestHashs(0);
|
||||
|
||||
// if your application is located in a web-subfolder for easier handling
|
||||
|
|
|
|||
|
|
@ -47,7 +47,7 @@ During this process the database automatically gets dropped (if existing) and re
|
|||
|
||||
## 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.
|
||||
This will only setup the application including some dummy data and also perform the code tests but no quality checks.
|
||||
|
||||
### Steps
|
||||
|
||||
|
|
|
|||
|
|
@ -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 esential 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 are 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 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 are accepted. Updates and bug fixes also must follow the standards.
|
||||
|
||||
## How and what to test?
|
||||
|
||||
|
|
@ -20,7 +20,7 @@ When testing it makes sense to test for the happy path/branch of how a method sh
|
|||
|
||||
### Unit tests
|
||||
|
||||
The smallest/lowest level of testing are the unit tests. Unit tests should be implemented for models and framework methods. Every public function should be covered by at least one unit test. If a method has multiple branches every branch should be covered by a separate unit test. In some cases it might make sense to cover multiple branches in one unit test/test function, such a decision should however be made conciously.
|
||||
The smallest/lowest level of testing are the unit tests. Unit tests should be implemented for models and framework methods. Every public function should be covered by at least one unit test. If a method has multiple branches every branch should be covered by a separate unit test. In some cases it might make sense to cover multiple branches in one unit test/test function, such a decision should however be made consciously.
|
||||
|
||||
### Integration tests
|
||||
|
||||
|
|
@ -97,7 +97,7 @@ The javascript testing is done with jasmine. The javascript testing directory is
|
|||
|
||||
### PHP CS
|
||||
|
||||
Besides the code tests and static code analysis the code style is another very imporant inspection to ensure the code quality.
|
||||
Besides the code tests and static code analysis the code style is another very important inspection to ensure the code quality.
|
||||
|
||||
```sh
|
||||
php vendor/bin/phpcs ./ --standard="Build/Config/phpcs.xml" -s --report-junit=Build/test/junit_phpcs.xml
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ The eventId can also be a regex in order to let it trigger on multiple occasions
|
|||
|
||||
### Repeating events
|
||||
|
||||
If a event should only be able to be triggered once another boolean parameter has to be edded to the `attach()` function call.
|
||||
If a event should only be able to be triggered once another boolean parameter has to be added to the `attach()` function call.
|
||||
|
||||
```php
|
||||
$eventManager->attach('eventId', function() { echo 'Hello World'; }, true);
|
||||
|
|
@ -42,7 +42,7 @@ $eventManager->trigger('eventId');
|
|||
|
||||
### Triggering Similar Events
|
||||
|
||||
In some situations you might want to trigger multiple events. In this case you can provide a regex as eventId and/or conditionName (e.g. `$eventManager->grigger('/[a-z]+/')`)
|
||||
In some situations you might want to trigger multiple events. In this case you can provide a regex as eventId and/or conditionName (e.g. `$eventManager->trigger('/[a-z]+/')`)
|
||||
|
||||
## Multi Condition Events
|
||||
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ The initialization can be done by providing an integer, float or string represen
|
|||
* (float) 1.23 = 1.23
|
||||
* (string) 1.23 = 1.23
|
||||
|
||||
The max and min money values that can be represented on a 32bit system are `214,748.3647` and `-214,748.3647` which is most of the time not sufficient. On 64bit systems however the max and min values that can be represented ar `922,337,203,685,477.5807` and `-922,337,203,685,477.5807`.
|
||||
The max and min money values that can be represented on a 32bit system are `214,748.3647` and `-214,748.3647` which is most of the time not sufficient. On 64bit systems however the max and min values that can be represented are `922,337,203,685,477.5807` and `-922,337,203,685,477.5807`.
|
||||
|
||||
## Operations
|
||||
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ function functionName(mixed $var, $mySetting1, $mySetting2) : bool
|
|||
Validator::isValid($testVariable, ['functionName' => $settings]);
|
||||
```
|
||||
|
||||
The second parameter (settings paramenter) contains an associative array where the key is the function name which should get invoked and the value are the settings/options/parameters passed to the function name. The function must be implemented by the user.
|
||||
The second parameter (settings parameter) contains an associative array where the key is the function name which should get invoked and the value are the settings/options/parameters passed to the function name. The function must be implemented by the user.
|
||||
|
||||
If multiple constraints are provided the validation only returns true if all validations are successful.
|
||||
|
||||
|
|
@ -115,7 +115,7 @@ Example for our `info.json` valdiation
|
|||
|
||||
```
|
||||
|
||||
The example above shows how to specifiy optional elements (e.g. "dependencies") which can have as many children in any form possible or optional values with a specific key (e.g. website) which can be omitted.
|
||||
The example above shows how to specify optional elements (e.g. "dependencies") which can have as many children in any form possible or optional values with a specific key (e.g. website) which can be omitted.
|
||||
|
||||
## Finance
|
||||
|
||||
|
|
@ -167,7 +167,7 @@ Hostname::isValid('http://test.com'); // false
|
|||
|
||||
### Ip
|
||||
|
||||
A simple ip validator which only validates the structure not if it actually exists.
|
||||
A simple Ip validator which only validates the structure not if it actually exists.
|
||||
|
||||
```php
|
||||
IP::isValid('192.168.178.1');
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
## Module
|
||||
|
||||
Every module must have two types of documentation. One for the end-user, which also includes information for the administrator and module configuration and another documentation for developers. Documentation must be available in at least english language.
|
||||
Every module must have two types of documentation. One for the end-user, which also includes information for the administrator and module configuration and another documentation for developers. Documentation must be available in at least English language.
|
||||
|
||||
### User
|
||||
|
||||
|
|
@ -26,7 +26,7 @@ The developer documentation should cover the following aspects:
|
|||
|
||||
## Database
|
||||
|
||||
### Diagramms
|
||||
### Diagrams
|
||||
|
||||
Every module that has a database table must implement a UML diagram illustrating the internal table relations as well as the relations with external tables from other modules.
|
||||
|
||||
|
|
|
|||
|
|
@ -128,7 +128,7 @@ $result = condition
|
|||
: very long expr2 which should be written like this;
|
||||
```
|
||||
|
||||
Multiline `if` conditions should begin with a logical opperator `or`/`and`.
|
||||
Multiline `if` conditions should begin with a logical operator `or`/`and`.
|
||||
|
||||
```php
|
||||
if (isTrue == true
|
||||
|
|
|
|||
|
|
@ -31,8 +31,8 @@ The following tags MUST not specify a end tag (\\):
|
|||
|
||||
## Accessible Rich Internet Applications
|
||||
|
||||
All modules and themes SHOULD be WAI-ARIA 2.0 compliant. For further reading please refere to https://www.w3.org/TR/WCAG20-TECHS/aria.
|
||||
All modules and themes SHOULD be WAI-ARIA 2.0 compliant. For further reading please refer to https://www.w3.org/TR/WCAG20-TECHS/aria.
|
||||
|
||||
## Structured Data (Microdata)
|
||||
|
||||
For structured data https://schema.org/ SHOULD be used.
|
||||
For structured data https://schema.org/ SHOULD be used.
|
||||
Loading…
Reference in New Issue
Block a user