README.md.dist

# {{ project }}
developed by drunomics GmbH, office@drunomics.com

This project is maintained using composer. Please refer to the documentation provided at https://github.com/drupal-composer/drupal-project and https://www.drupal.org/node/2471553.

## Prerequesites

 * Install docker and [docker compose](https://docs.docker.com/compose/install/) - use version 1.22.0 or later.

 * Install phapp (see tools) - or use the project-local version if preferred:

        composer install-phar-tools
        export PATH=./vendor/bin/:$PATH

 * If your user ID is not 1000, run the following commands to
   automatically set a suitable environment variable on every startup:

        # Check ID:
        id -u $USER
        # If not 1000, run:
        echo "# Allow docker compose setup to switch to the correct user." >> ~/.bashrc
        echo "export COMPOSE_DEFAULT_USER=$(id -u $USER)" >> ~/.bashrc
        bash

## Project devsetup

To setup the project, ensure you have all prerequesites fullfilled and follow next steps:

 * Optional: Drop container and data from previous runs:

        docker compose down -v

 * Initialize setup and run docker compose

        phapp setup localdev
        docker compose up -d --build

* Build the app:

        phapp build

 * Run `phapp init` to quickly initialize the application.
 
         docker compose exec cli phapp init --no-build

## Localdev project URLs

| Url | Webroot | Description |
| --- | ------- | ----------- |
| http://example.{{ project }}.localdev.space/ | web | the Example site |

## Docker-compose - IMPORTANT NOTES.

For now most phapp and drush must be from inside the docker container.
Do so via

    docker compose exec cli phapp init --no-build
    docker compose exec cli drush cr

However, the exception is `phapp build`. Run it on the host so that your SSH key(s)
are picked up and you can access private repositories:

    phapp build

During development it's convenient to permanently switch to the docker cli container:

    docker compose exec cli bash
    drush cr

## Command line tools

### Phapp
Version 0.7.0 or later is required. Either install it globally and run `phapp`
or execute the embedded phapp version from the root repository directory:

```./vendor/bin/phapp ```

Refer to [the project page](http://github.com/drunomics/phapp-cli) for
instructions on how to install phapp globally.

### Drush
 To run drush, execute from the root repository directory:
 ```./vendor/bin/drush ```

 The more convenient alternative is to install a global launcher or a global
 drush with version 8, which includes a global launcher. Then, drush picks up
 the project-local drush automatically.
 For docs on drush see http://docs.drush.org/en/master/.

## Useful commands

- Commands for setting up or updating the project:

```
# Get in the docker web container (where you can use the phapp commands)
docker compose exec cli bash

# Quick-install the application for development:
docker compose exec cli phapp init --no-build

# Update the build and run updates after switching branches:
phapp build
docker compose exec cli phapp update --no-build

# Install the app from scratch:
docker compose exec cli phapp install
```
The commands executed can be found in `phapp.yml`.

- During development, some useful commands are:

```
# Config export (export your config changes):
docker compose exec cli drush cex -y

# Config import (manual import of config files):
docker compose exec cli drush cim -y

# Cache clear/rebuild:
docker compose exec cli drush cr
```

## Running tests

Tests are implemented using behat and use a headless chrome browser for javascript enabled tests:

To run the tests:

    ./tests/behat/run.sh

Any further arguments are forwarded to behat:

    ./tests/behat/run.sh --tags=javascript


## Coding style

To check the coding style for the project's custom code, run PHP code sniffer:

    composer cs

To automatically fix the coding style errors (as far as possible), run the PHP
code beautifier:

    composer cbf

### Pre-commit checks

Coding style can be checked automatically via Git's pre-commit hooks. To do so, just make sure to run the script `devsetup/setup-git-config.sh` at least once.

Once configured, running pre-commit hooks can be bypassed via the Git commmit
`--no-verify` option.

### PHPstorm coding style configuration

Configure the following settings:
* Under Languages / PHP / Code Sniffer
  - Select "local" configuration and make it point to `vendor/bin/phpcs`).
* Under Editor / Inspections / PHP Code Sniffer validation:
  - Select "warning" as severity.
  - Show warnings as "warning"
  - Show sniff name "true"
  - Coding standard: "custom", make it point to the phpcs.xml.dist file in the
    vcs root.