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
  • Testing
  • Metrics
  • Links / resources
  • Notes
    • User password hashing
  • Authors
  • License

Requirements

• PHP 7.1.3 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.

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
generate-jwt-keys Generates JWT auth keys
phpmetrics        Generates PhpMetrics static analysis
run-tests-fastest Runs all test via fastest
run-tests         Runs all tests via phpunit
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

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

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.

Testing

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

make run-tests
# or alternative
./vendor/bin/phpunit

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

make run-tests-fastest
# or alternative
./vendor/bin/fastest -x phpunit.xml.dist
# or another alternative
find tests/ -name "*Test.php" | ./vendor/bin/fastest -v

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
# or alternative
./vendor/bin/phpmetrics --report-html=build/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
• 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.

Authors

Tarmo Leppänen

License

The MIT License (MIT)

Copyright (c) 2017 Tarmo Leppänen