Verified Commit aa41b5dc authored by Elias Häußler's avatar Elias Häußler 🐛

[DOCS] Add documentation

parent d30de551
......@@ -23,6 +23,7 @@ Version numbers are based on [Semantic Versioning](
- Git Pre-Commit hook file
- Set correct HTTP response code on failures
- Possibility to define remote server port in [`remote.env`](remote.env.dist)
- Documentation
- **Breaking:** SlackController: Request user's locale when sending API request
- SlackController: Allow users to set default expiration time when using `/lunch` command in Slack
- SlackController: Introduce `SlackMessage` class for styling of Slack messages
A PHP-based API to handle custom requests sent to [](
The API serves different endpoints which can be accessed from various clients.
## Contents
- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
+ [User-specific environment](#user-specific-environment)
- [`.env`](#env)
- [`remote.env`](#remoteenv)
+ [PHP-CS-Fixer](#php-cs-fixer)
+ [Initialize database](#initialize-database)
- [Usage](#usage)
+ [Controller](#controller)
+ [Route mapping](#route-mapping)
+ [Example: `SlackController`](#example-slackcontroller)
- [Deployment](#deployment)
+ [Prerequisites](#prerequisites)
+ [Process deployment](#process-deployment)
## Features
- Start or end your lunch break in Slack using slash command `/lunch`
- Display Redmine issue information in Slack using slash command `/issue` or `/redmine issue`
## Requirements
- Apache web server
- MySQL database
- Composer
## Installation
Clone the repository first:
git clone
Install dependencies (`composer` needs to be installed for this):
composer install
Now point your web server/virtual host to the `public` directory of your cloned project
and you should be able to access the API.
### User-specific environment
#### [`.env`](.env.dist)
In order to access the database and set some configuration settings, it's necessary to create
a user-specific environment file:
cp .env.dist .env
Adapt the following environment variables by your needs:
- `DB_HOST`: **localhost**: Host where your MySQL database is served
- `DB_USER`: Database user to be used for database connections
- `DB_PASSWORD`: Password of the database user
- `DB_NAME`: Name of the database
- `DB_PORT`: **3306**: Port which listens for incoming database connections
- `DEBUG_EXCEPTIONS`: **0**: Set to `1` to debug exceptions.
**Do not use this in production mode as it may print sensitive data.**
- `MINIMUM_LOG_LEVEL`: **1**: The minimum level for logs printed to the log file.
See [`LogService`](src/classes/Service/LogService.php) class for available log levels.
- `ROUTE_BLACKLIST`: **favicon.ico**: Comma-separated list of routes to be blocked on request
#### [`remote.env`](remote.env.dist)
If you want to deploy the API to a remote server, you need to create a custom `remote.env` file:
cp remove.env.dist remote.env
Adapt the following environment variables by your needs:
- `TARGET_HOST`: Remote host in SSH notation (`user@host`) serving the production API
- `TARGET_PATH`: Path on the remote host to the deployed API
- `TARGET_PORT`: **22**: Port of the remote host listening for incoming SSH connections
### PHP-CS-Fixer
Set up the PHP-CS-Fixer by defining a custom `.php_cs` file. You can also use the distributed file:
cp .php_cs.dist .php_cs
### Initialize database
Before using the API, the database schema needs to be updated. This can be done by using the
included console:
./console.php database:schema update
## Usage
The API awaits requests in the form
`GET`-Parameters like `?param1=a&param2=b` will be extracted and stored in the concrete controller class.
### Controller
For each `<controller>` an appropriate class `EliasHaeussler\Api\Controller\<Controller>Controller`
is expected and instantiated, if available.
For example, requests with `<API_HOST>/slack/<parameters>` will result in an instantiation of the
[`SlackController`](src/classes/Controller/SlackController.php) class.
Each controller must extend the [`BaseController`](src/classes/Controller/BaseController.php) class.
### Route mapping
The controller parameters, displayed as `<parameters>` in the above example, will be redirected to
the controller. Each controller is then responsible for defining route mappings for each available
Route mappings are defined as separate class `EliasHaeussler\Api\Routing\<controller>\<route>Route`.
They must extend the class [`BaseRoute`](src/classes/Routing/BaseRoute.php) and then registered
in the appropriate controller within the class constant `ROUTE_MAPPINGS`.
### Example: `SlackController`
![Slack slash command `/lunch`](docs/assets/slack-lunch.gif)
The [`SlackController`](src/classes/Controller/SlackController.php) will be used when sending
requests in the form `<API_HOST>/slack/<parameters>`. It currently allows three route mappings:
- `authenticate`: Process user authentication at Slack using
[`AuthenticateRoute`](src/classes/Routing/Slack/AuthenticateRoute.php) class
- `lunch`: Process a request for the Slack slash command `/lunch` using
[`LunchCommandRoute`](src/classes/Routing/Slack/LunchCommandRoute.php) class
- `redmine`: Process a request for the Slack slash commands `/redmine` or `/issue` using
[`RedmineCommandRoute`](src/classes/Routing/Slack/RedmineCommandRoute.php) class
## Deployment
The API includes a basic deployment of the project to a remote host. Before processing the deployment,
make sure your server supports the required environment (see [Requirements](#requirements)).
Additionally, both your local machine and your deployment target server must support these packages:
- `rsync` to transfer files to the remote target server
- `ssh` to process the further deployment on the remote target server
- `php` with at least version 7.1 on the remote target server to run API console commands
### Prerequisites
First, configure the deployment settings in the `remote.env` file of your local installation
(see [`remote.env`](#remoteenv)).
On the target server, make sure that the following files exist in the deployment target path:
- `<TARGET_PATH>/local/.env` containing the database credentials and API configurations.
**Make sure that the value of `DEBUG_EXCEPTIONS` is set to `0`!**
- `<TARGET_PATH>/local/slack.env` is only necessary if you want to support requests for `SlackController`
Your web server/virtual host should point to `<TARGET_PATH>/release/public`. Additionally, it is
recommended to set the value of `MINIMUM_LOG_LEVEL` in your remote `.env` file to a value not
lower than `1`, otherwise all debug messages will be logged.
### Process deployment
Before starting the deployment, make sure your Git working directory is clean. Otherwise, the
deployment won't start due to security reasons.
The deployment process can be started as follows:
On each deployment, the script will rsync the build files to a `cache` folder inside your
remote target path. If all files are ready on the server, the `release` directory will be
overridden by the `cache` directory which is overlain by the `local` directory.
Note that on each deployment, the log files on the server will be removed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment