Table of Contents
Boilerplate Project Template for RESTFul API #
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, PROD, etc)
- Database
- Docker for build your project
Install #
Requirements #
This project requires in order to run:
- PHP
- composer
- Docker and docker-compose
Create a Project from the Stable Release #
composer create-project byjg/resttemplate YOURPATH 4.1.*
Create a Project from Development Release #
composer -sdev create-project byjg/resttemplate YOURPATH master
Use instead of master
branch the feature branch version like 4.0.1.x-dev
How to use #
Start #
After the command create-project is executed some questions will be asked for setup your new project.
You need also a MySQL installation. You can use docker if you want:
docker run -d --rm \
--name mysql-container \
-e MYSQL_ROOT_PASSWORD=mysqlp455w0rd \
-v mysql:/var/lib/mysql \
-p 3306:3306 \
mysql:5.7
PSR-11 #
This project uses a PSR11 implementation for container. The implementation is from byjg/config.
Start editing from “config/config-dev”
Build #
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:
# Set the correct environment
export APPLICATION_ENV=dev
# Create the database
composer migrate -- reset --yes
# Update the database
composer migrate -- update # or reset if you want to recreate
# Build
composer docker-build
# Run
composer docker-run
Build TL;DR #
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_DOCKER_BUILD” variable
- Run the commands inside the PSR11 “BUILDER_DOCKER_RUN” 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
string comment
##---ENV-SPECIFICS-HERE
with the commands defined here; IMPORTANT NOTE: if the array is empty or null, the Builder will ignore the custom Dockerfile - BUILDER_DOCKER_BUILD =>The commands used to build your artifact.
- BUILDER_DOCKER_RUN: The commands used to deploy your artifact. Maybe a docker run command or a docker push or everything else.;
Migrate database #
The sample database requires you have a MySQL running.
Update to the most recent database version
APPLICATION_ENV=dev composer migrate -- update
Reset the database
APPLICATION_ENV=dev composer migrate -- reset --yes
Note: be careful with this command, because all of your database will erased and recreated with the migrations scripts.
Database TL;DR #
Migration #
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’;
ORM #
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’
Test #
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
Fix problems #
SQLSTATE[HY000] [1049] Unknown database ‘database’ #
export APPLICATION_ENV=dev
composer migrate -- reset --yes
How to setup the environment APPLICATION at Windows command prompt? #
Use the set
command.
set APPLICATION_ENV=dev