What is this

JSON REST API which is build on top of Symfony framework.

Note that this project is build with Symfony 4 and Symfony Flex.

Table of Contents

• What is this?
  • Table of Contents
  • Requirements
  • Installation
    • 1. Clone repository
    • 2. Configuration
    • 3. Dependencies installation
    • 4. Create JWT auth keys
    • 5. File permissions
    • 6. Environment checks
      • CLI environment
      • Web-server environment
        • Apache
    • 7. Other (optionally)
      • Allow other IP's to access dev environment
  • Commands
    • Makefile
    • Symfony console
    • Custom commands
      • user:management
      • api-key:management
  • Structure
  • Development
    • IDE
    • PHP Code Sniffer
    • Database changes
    • Docker
  • Testing
  • Metrics
  • Links / resources
  • Notes
    • User password hashing
      • Installing libsodium
  • Authors
  • License

Requirements

• PHP 7.2 or higher
• Composer
• Database that is supported by Doctrine
• Sodium crypto library (libsodium)
  • for PHP < 7.2 use this pecl package
  • If you don't want to use Argon2 see Notes

Installation

1. Clone repository

Use your favorite IDE and get checkout from GitHub or just use following command

git clone https://github.com/tarlepp/symfony-flex-backend.git

2. Configuration

Next you need to create .env file, which contains all the necessary environment variables that application needs. You can create it by following command (in folder where you cloned this project):

cp .env.dist .env

Then open that file and make necessary changes to it. Note that this .env file is ignored on VCS.

note that this optional way to do this, installing dependencies will prompt you on every needed configuration

3. Dependencies installation

Next phase is to install all needed dependencies. This you can do with following command, in your project folder:

composer install

Or if you haven't installed composer globally

curl -sS https://getcomposer.org/installer | php
php composer.phar install

4. Create JWT auth keys

Application uses JWT to authenticate users, so we need to create public and private keys to sign those. You can create new keys with following command.

make generate-jwt-keys

5. File permissions

Next thing is to make sure that application var directory has correct permissions. Instructions for that you can find here.

I really recommend that you use ACL option in your development environment.

6. Environment checks

To check that your environment is ready for this application. You need to make two checks; one for CLI environment and another for your web-server environment.

CLI environment

You need to run following command to make all necessary checks.

./vendor/bin/requirements-checker

Web-server environment

Open terminal and go to project root directory and run following command to start standalone server.

./bin/console server:start

Open your favorite browser with http://127.0.0.1:8000/check.php url and check it for any errors.

Apache

To get JWT authorization headers to work correctly you need to make sure that your Apache config has mod_rewrite enabled. This you can do with following command:

sudo a2enmod rewrite

7. Other (optionally)

Allow other IP's to access dev environment

If you want to allow another IP addresses or all to your dev environment see /allowed_addresses.php file for detailed information how you can allow certain IP addresses to have access to your dev environment.

Commands

Makefile

Symfony Flex comes with Makefile configuration so that you can easily run some generic commands via make command. Below is a list of currently supported (main commands) make commands, note that you can get this same list with just running make command:

cache-clear                # Clears the cache
cache-warmup               # Warms up an empty cache
check-vendor-dependencies  # Checks if any vendor dependency can be updated
clear-vendor-bin           # Runs PHPStan static analysis tool
ecs                        # Runs The Easiest Way to Use Any Coding Standard
generate-jwt-keys          # Generates JWT auth keys
merge-clover               # Creates clover from fastest run
merge-junit                # Creates JUnit xml from fastest run
phpcs                      # Runs PHP CodeSniffer
phpmetrics                 # Generates PhpMetrics static analysis
phpstan                    # Runs PHPStan static analysis tool
psalm                      # Runs Psalm static analysis tool
run-tests-fastest-phpdbg   # Runs all test via fastest (phpdbg)
run-tests-fastest-php      # Runs all test via fastest (pure PHP)
run-tests-fastest          # Runs all test via fastest (Uses phpdbg if that is installed)
run-tests-phpdbg           # Runs all tests via phpunit (phpdbg)
run-tests-php              # Runs all tests via phpunit (pure PHP)
run-tests                  # Runs all tests via phpunit (Uses phpdbg if that is installed)
serve                      # Runs a local web server

Symfony console

You can list all Symfony console commands via following command:

./bin/console

Custom commands

Project contains following custom console commands to help eg. user management:

./bin/console user:management                       # To manage your users and user groups
./bin/console api-key:management                    # To manage your API keys
./bin/console make:rest-api                         # To create skeleton classes for new REST resource
./bin/console utils:create-date-dimension-entities  # Console command to create 'DateDimension' entities.

user:management

This command is just a wrapper for following commands:

./bin/console user:create         # To create user
./bin/console user:create-group   # To create user group
./bin/console user:create-roles   # To initialize user group roles
./bin/console user:edit           # To edit user
./bin/console user:edit-group     # To edit user group
./bin/console user:remove         # To remove user
./bin/console user:remove-group   # To remove user group
./bin/console user:list           # To list current users
./bin/console user:list-groups    # To list current user groups

api-key:management

This command is just a wrapper for following commands:

./bin/console api-key:create          # To create API key
./bin/console api-key:edit            # To edit API key
./bin/console api-key:change-token    # To change API key token
./bin/console api-key:remove          # To remove API key
./bin/console api-key:list            # To list API keys

utils:create-date-dimension-entities

Command to create DateDimension entities that can be used with date/time related report queries.

Structure

todo

Development

• Coding Standards

IDE

I highly recommend that you use "proper" IDE to development your application. Below is short list of some popular IDEs that you could use.

• PhpStorm
• NetBeans
• Sublime Text
• Visual Studio Code

Personally I recommend PhpStorm, but just choose one which is the best for you. Also note that project contains .idea folder that holds default settings for PHPStorm.

PHP Code Sniffer

It's highly recommended that you use this tool while doing actual development to application. PHP Code Sniffer is added to project dev dependencies, so all you need to do is just configure it to your favorite IDE. So the phpcs command is available via following example command.

./vendor/bin/phpcs -i

If you're using PhpStorm following links will help you to get things rolling.

• Using PHP Code Sniffer Tool
• PHP Code Sniffer in PhpStorm

Database changes

When you start a new project where you use this project as a "seed" first thing to do is to run following command:

./bin/console doctrine:migrations:diff

This will create a migration file which contains all necessary database changes to get application running with default database structure. You can migrate these changes to your database with following command:

./bin/console doctrine:migrations:migrate

After that you can start to modify or delete existing entities or create your own ones. Easiest way to make this all work is to follow below workflow:

1. Make your changes (create, delete, modify) to entities in /src/Entity/ folder
2. Run diff command to create new migration file
3. Run migrate command to make actual changes to your database
4. Run validate command to validate your mappings and actual database structure

Those commands you can run with ./bin/console doctrine:migrations:<command>.

With this workflow you get easy approach to generic database changes on your application. And you don't need to make any migrations files by hand (just let Doctrine handle those). Although remember to really take a closer look of those generated migration files to make sure that those doesn't contain anything that you really don't want.

Docker

Todo

Testing

Project contains bunch of tests (Functional, Integration, Unit) which you can run simply by following command:

make run-tests

And if you want to run tests with fastest library use following command:

make run-tests-fastest

Note that you need to create .env.test file to define your testing environment. This file has the same content as the main .env file, just change database and others to match your testing environment.

• PHPUnit

Or you could easily configure your IDE to run these for you.

Metrics

Project also contains PhpMetrics to make some analyze of your code. You can run this by following command:

make phpmetrics

And after that open build/phpmetrics/index.html with your favorite browser.

Links / resources

• Symfony Flex set to enable RAD (Rapid Application Development)
• Symfony 4: A quick Demo
• Symfony Development using PhpStorm
• Symfony Plugin plugin for PhpStorm
• PHP Annotations plugin for PhpStorm
• Php Inspections (EA Extended) plugin for PhpStorm
• EditorConfig
• composer-version
• Symfony Recipes Server

Notes

User password hashing

By default this application uses Argon2 to hash all user passwords, and that is why application requires that your PHP has support for Sodium crypto library (libsodium) library.

If you cannot or don't want to use this as password hashing method you need to change security.yaml before installation step.

Installing libsodium

To check if your current PHP has libsodium you can use following command

php -m

If [PHP Modules] does not contain libsodium you need to install it to get password hashing to work. You can install it with following commands on your *nix box.

git clone -b stable https://github.com/jedisct1/libsodium.git
cd libsodium && sudo ./configure && sudo make check && sudo make install
pecl install libsodium

Authors

Tarmo Leppänen

License

The MIT License (MIT)

Copyright (c) 2018 Tarmo Leppänen