Boilerplate project template for create RESTFul services with docker and database integrated
This project enables you to create a full functional project for RESTFul server Api.
This project install the follow components:
- PSR11 Container dependency
- A JWT Authentication
- Pre-configured for different environments (DEV, HOMOLOG, LIVE, etc)
- Docker for build your project
This project requires in order to run:
Follow the instructions for your environment at dockers web site.
Debian systems just do:
sudo apt install composer php php-sqlite php-mysql
On Windows system the easiest way is installing from Chocolatey. Once chocolatey is installed you can just do:
choco install -y php composer
composer create-project byjg/resttemplate YOURPATH 4.0.*
composer -sdev create-project byjg/resttemplate YOURPATH master
After the command create-project is executed some questions will be asked for setup your new project.
You can create the project by your own hand:
composer install npm i node_modules/.bin/usdocker --refresh -v
This project uses a PSR11 implementation for container. The implementation is from byjg/config.
Start editing from "config/config-dev"
The build process will enable you create an artifact of your project. The "Builder" can easily turn your project inside a docker container.
The ready to use command is:
# If you do not have a test database you can do: node_modules/.bin/usdocker mysql up # Update the database APPLICATION_ENV=dev composer migrate -- update # or reset if you want to recreate # Build APPLICATION_ENV=dev composer build
The build process uses the configuration environment defined in the PSR11 Container
The process for build is:
- Read the PSR11 Container with the specific environment;
- If exists PSR11 "BUILDER_DOCKERFILE" variable it will copy the Dockerfile template from 'docker/Dockerfile' to the workdir and apply the customizations;
- Run the commands inside the PSR11 "BUILDER_BEFORE_BUILD" variable
- Run the commands inside the PSR11 "BUILDER_BUILD" variable
- Run the commands inside the PSR11 "BUILDER_DEPLOY_COMMAND" variable
Your PSR11 Container must have the follow variables:
- BUILDER_VARIABLES => an array with custom variables. By default there are:
- %env% - Your current environment
- %workdir% - The root workdir
- BUILDER_DOCKERFILE: an array with specific commands for the current environment. Basically
the build process will copy the docker template file from 'docker/Dockerfile' and replace the
##---ENV-SPECIFICS-HEREwith the commands defined here; IMPORTANT NOTE: if the array is empty or null, the Builder will ignore the custom Dockerfile
- BUILDER_BEFORE_BUILD' => The commands before start the build image. For example the grunt command or a minifier;
- BUILDER_BUILD =>The commands used to build your artifact.
- BUILDER_DEPLOY_COMMAND: The commands used to deploy your artifact. Maybe a docker run command or a docker push or everything else.;
The sample database requires you have a MySQL running.
You can install the MySQL or running a Docker file. We use the "USDocker" project that make easy create and up Database/Services instances.
The default user/password is "root/password".
If you're using the USDocker just do the line below before run :
node_modules/.bin/usdocker mysql up
Update to the most recent database version
APPLICATION_ENV=dev composer migrate -- update
Reset the database
APPLICATION_ENV=dev composer migrate -- reset
Note: be careful with this command, because all of your database will erased and recreated with the migrations scripts.
The migration process uses the byjg/migration
Basically there are migration scripts located at "%workdir%/db".
The initial file is "base.sql" and the migration are "%workdir%/db/up/1.sql", "%workdir%/db/up/2.sql" and so on.
The basic migrations command are:
- reset: Will reset the database starting from "base.sql" and apply an migrations starting from 1.sql.
- update: Will update the database until the most recent version existing in the migration;
- update --up-to=n: Will update the database until the version 'n' existing in the migration;
The connection is in the Psr11 container variable 'DBDRIVER_CONNECTION';
The ORM uses the byjg/micro-orm
There are a basic example in "%workdir%/src/project/Repository/DummyRepository". The defintion in the Psr11 container variable 'DUMMY_TABLE'
To run the tests you need to start the database and build the project.
After all, you have to setup the environment and the username for test
export APPLICATION_ENV=dev export TEST_ADMIN_USER=admin export TEST_ADMIN_PASSWORD=pwd export TEST_REGULAR_USER=user export TEST_REGULAR_PASSWORD=pwd vendor/bin/phpunit
node_modules\.bin\usdocker --refresh --home ..\db
If you are running under Windows or Mac or even a Virtual Machine outside your local host try to setup the docker to:
node_modules\.bin\usdocker --global docker-host=http://localhost:2375 --home ..\db
Try to add to your hosts file the follow line:
export APPLICATION_ENV=dev composer migrate -- reset