A PHP-based API to handle custom requests sent to api.elias-haeussler.de. The API serves different endpoints which can be accessed from various clients.
- Start or end your lunch break in Slack using slash command
- Display Redmine issue information in Slack using slash command
- Notify your team members in Slack that you're ready for stand-up using slash command
- Apache web server
- MySQL database
Clone the repository first:
git clone email@example.com:eliashaeussler/api.git
Install dependencies (
composer needs to be installed for this):
Now point your web server/virtual host to the
public directory of your cloned project
and you should be able to access the API.
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
1to 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
LogServiceclass for available log levels.
ROUTE_BLACKLIST: favicon.ico: Comma-separated list of routes to be blocked on request
If you want to deploy the API to a remote server, you need to create a custom
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
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
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
The API awaits requests in the form
?param1=a¶m2=b will be extracted and stored in the concrete controller class.
<controller> an appropriate class
is expected and instantiated, if available.
For example, requests with
<API_HOST>/slack/<parameters> will result in an instantiation of the
Each controller must extend the
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
They must extend the class
BaseRoute and then registered
in the appropriate controller within the class constant
SlackController 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
lunch: Process a request for the Slack slash command
redmine: Process a request for the Slack slash commands
standup: Process a request for the Slack slash command
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). Additionally, both your local machine and your deployment target server must support these packages:
rsyncto transfer files to the remote target server
sshto process the further deployment on the remote target server
phpwith at least version 7.1 on the remote target server to run API console commands
First, configure the deployment settings in the
remote.env file of your local installation
On the target server, make sure that the following files exist in the deployment target path:
<TARGET_PATH>/local/.envcontaining the database credentials and API configurations. Make sure that the value of
DEBUG_EXCEPTIONSis set to
<TARGET_PATH>/local/slack.envis only necessary if you want to support requests for
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
1, otherwise all debug messages will be logged.
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
Note that on each deployment, the log files on the server will be removed.
The API ships with a console which provides useful commands to keep the API up-to-date.
The console is based on Symfony console, so all known commands such as
help are available.
This command allows you to export the currently used database. It prints the database dump to
which allows you to save it to a SQL file.
This command allows you to migrate legacy SQLite databases to the new MySQL database. It's useful to
database:schema command after calling this one.
./console.php database:migrate <file>
This command allows you to maintain the database schema. It can be used to update the database schema or drop unused components such as fields or tables.
./console.php database:schema update [-s|--schema <schema>] ./console.php database:schema drop [--fields] [--tables] [--dry-run] [--force] [-s|--schema <schema>]
This command allows you to clear old log files. It is useful to run this command in a specific interval
to remove old logs and clear disk space as the log files might exceed in its size in case a low
MINIMUM_LOG_LEVEL is set.
./console.php logfile:clear [--keep-current]
This command allows you to run scheduled tasks. If all parameters are omitted, the command executes all
tasks which were scheduled for execution in the past. In case either one of the
specified, only the tasks matching the appropriate patterns are executed. If both parameters are set,
the appropriated constraints are AND-combined.
./console.php scheduler:run [-u|--uid <uid>] [-t|--task <task>]