# Basic boilerplate
Used for setting up basic websites! Built on top of our core composer package: komma/kms.

## General setup
* Make sure you've installed the following pre-requisites on you computer
    * PHP >= 7.1.3
    * OpenSSL PHP Extension
    * PDO PHP Extension
    * Mbstring PHP Extension
    * Tokenizer PHP Extension
    * XML PHP Extension
    * Ctype PHP Extension
    * JSON PHP Extension
    * BCMath PHP Extension
    * MySQL 5.5 or higher
    * [node package manager](https://nodejs.org/en/download/) 
    * [Composer](https://getcomposer.org/download/)
* Make sure you have a MySQL database, and if you are developing locally a second one.    
    * Make sure that the database encoding is set to: ```UTF-8 Unicode (utf8mb4)```
    * Make sure that the database collation is set to: ```Default (utf8mb4_general_ci)```
* Run the following commands in the root of the project:
  * ```composer install``` To install the laravel framework and related packages (see composer.json). After installation composer will automatically generate a .env file if one isn't present, will make artisan generate new app key and make artisan run the migrate script.
  * ```npm install``` To install the development / and some frontend packages
  * ```npm run dev``` To transpile sass, javascripts, copy assets
  * ```php artisan vendor:publish --tag=kms-core-config``` To copy required assets public assets from the kms (core) package.
  * ```php artisan vendor:publish --tag=kms-core-public --force``` To copy required assets public assets from the kms (core) package.
* Setup a cron job to make sure housekeeping, mail processing, catalog indexing etc is done:
  ```* * * * * php /path-to-your-project/artisan schedule:run >> /dev/null 2>&1```
* Rename env.example and env.testing.example respectively to  .env and .env.testing. And configure them as needed.
* Run the migrations and seeds. Look further in the manual to the Migrations and seeds chapter to discover how.

### Migrations and seeds
Run the migrations and seeds to setup your database.
```
php artisan migrate:fresh
php artisan kms:seed
php artisan db:seed
```
Run the migrations and seeds to setup your test database.
```
php artisan migrate:fresh --env=testing
php artisan kms:seed --env=testing
php artisan db:seed --env=testing
```

The kms seed is the seed from the core package.

## Development notes
### Environments
the APP_ENV variable in .env must contain a specific value. One of these all in lower case: local, testing, development, production.

#### local
The environment that one should use when developing on its own computer.

#### testing
The environment that test software automatically uses. See for example phpunit.xml and

#### development
The environment that one must used on komma.pro staging servers.

#### production
The environment that should be used when the system is live and being used for customers.

### Running tests
#### Unit Testing
Before testing you must make sure that your webserver is using the test database, defined in env.testing. To do so using the
built in webserver you must run: ```php artisan serve --env=testing```

Use the following command to run the unit tests. These will run the unit tests in the tests/Unit folder and tests/Feature folder.
```
vendor/bin/phpunit
```
You can append ```--group=<groupname>``` to specify a group to test. And ```--filter=<testname>``` to run a specific test.
When testing, make sure your database is "fresh". That is, freshly migrated and seeded for best results. If tests fail, refresh your database first.

#### End to end (browser testing)
Run ```cypress open``` in the project root to start the cypres e2e tool. Click on ```run all specs``` to run al tests (also called specs). Or click
individual tests to test those parts only. These test files are located in the folder tests/Cypress/integration. 

When testing, make sure your database is "fresh". That is, freshly migrated and seeded for best results. If tests fail, refresh your database first.

### Kommandline.js
The boilderplates ships with a helper tool called kommandline.js. Start it in the root with ```node kommandline.js```. It can quickly setup a (test) database,
and kill abandoned artisan processes.

### Generating documentation
#### Install doxygen
Doxygen is the tool that generates the documentation for us. Install it like so:

* Press ```Command+Space``` and type *Terminal* and press ```enter/return``` key.
* Run in terminal: ```ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" < /dev/null 2> /dev/null``` and press ```enter/return``` key.
If the screen prompts you to enter a password, please enter your Mac's user password to continue. When you type the password, it won't be displayed on screen, but the system would accept it. Then wait for the command to finish.
* Run in terminal: ```brew install doxygen```

#### Generate the documentation via the terminal
* Use your terminal with the ```doxygen doxygen_config``` command in the root of the project to generate the documentation.
* You can also generate the documentation and automatically open it in chrome with ```sh doxygenit.sh```

#### Opening the documentation
The documentation will be available in the *kms_documentation* folder. Just open the index.html file in there and your good to go.