basic

This repository holds a basic web application for a default website with some default pages to be deployed on an empty webserver with php enabled.

Structure & Philosophy

This project is based on following structure:

• /: Inside the root folder there are many helper scripts to make the handling of relevant task much easier
  • ./env.sh: Creates a .env file with application and database relevant settings.
  • ./docker compose.sh: Starts a full environment with Docker and Docker Compose.
  • ./adminer.sh: Downloads the latest version of Adminer into the web directory.
• /web: The location of the main page application and the root of Composer
• /docs: A collection of documents with further information about work as a web developer and the environments
• /docker: All relevant configurations for the Docker and Docker Compose environment

The following main dependencies are used inside this project:

• The Git version control system is used for the source code management
• The main programing language is PHP minimum version 8.2
• The main database is MariaDB minimum version 10.5
• For database administration Adminer is used
• The Composer is used as the main dependency manager for PHP
• The Node.js JavaScript runtime is used for the frontend development
• The Docker and Docker Compose container virtualization is used for the development environment

Further information of the philosophy and fundamental arrangement:

• GitFlow or the more recent GitHub flow is the base process for the branching model and workflow.
• Branch naming conventions are used got Git branches to organize ongoing work to ensure that software delivery stays effective. The Git workflows depend extensively on using branches effectively — and naming a new branch is something most important.
• Semantic versioning (aka SemVer) keeps the software ecosystem healthy, reliable, and secure, every time you make fixes, minor changes or significant updates to a software this reflects this changes in the updated version number.

Get Started

To get this project you need to get a local copy of this repository first:

git clone [email protected]:bassix/basic.git bassix-basic
cd bassix-basic

(Optional) GitLab alternative and fallback repository copy:

git clone [email protected]:bassix/basic.git bassix-basic
cd bassix-basic

Note: read how to install Git.

Initialize GIT flow before development and contribution:

echo "main" | DEBUG=yes git flow init -f &>/dev/null

Note: read how to install Git-Flow.

Serve Application

This application is developed to be agnostic to the environment running on. For development there are three different ways to create a running environment:

1. PHP built in web server
2. Apache2 web server with PHP module
3. [Docker and Docker Compose environment](#docker-and-docker compose)

Configuration

Before the application can be served it should be configured:

1. .env: The environment configuration, is based on .env.dist.

   Note: use the ./env.sh helper script.

2. app/config/config.php: The environment configuration, is based on app/config/config.dist.php.

   Note: use the ./config.sh helper script.

Note: the environment has default parameters, and it can be started without any configuration.

Docker

The easiest way to start the application in its very basic form is to use Docker:

docker run -d -p 8090:80 --name basic -v "$PWD"/web:/var/www/html php:apache

Access the application:

• The basic web page: http://localhost:8090

Docker and Docker Compose

To start the application with services like MariaDB, Adminer and PHPMyAdmin the Docker Compose is used:

# Start only the basic web application
docker compose -p basic -f docker-compose.yml up -d --build --force-recreate
# Start the basic web application with MariaDB
docker compose -p basic -f docker-compose.yml -f docker-compose.mariadb.yml up -d --build --force-recreate
# Start the full environment with MariaDB, Adminer and PHPMyAdmin
docker compose -p basic -f docker-compose.yml -f docker-compose.mariadb.yml -f docker-compose.adminer.yml -f docker-compose.phpmyadmin.yml up -d --build --force-recreate

Access the application:

• The basic web page: http://localhost:8090
• The Adminer: http://localhost:8091
• The PHPMyAdmin: http://localhost:8092

Docker Compose Commands

Check if all containers are running correctly:

docker compose -p basic ps

To follow the logs of the Docker stack:

docker compose -p basic logs -f

To stop the Docker stack and remove all containers:

docker compose -p basic -f docker-compose.yml -f docker-compose.mariadb.yml down --rmi all --remove-orphans

PHP

For development purpose the easiest way to serve the website is to use the PHP integrated web server:

php -S 127.0.0.1:8090 -t web

Alternative, run the development server in the background and write the output to a log file:

nohup php -S 127.0.0.1:8090 -t web > phpd.log 2>&1 &

Show the last 100 rows and follow the log file:

tail -fn 100 phpd.log

Enter the application:

• The basic web page: http://localhost:8090
• The Adminer: http://localhost:8090/adminer.php

Apache2 with PHP

Drafts for the configuration:

• conf/apache2/000-default.conf: The Apache2 default configuration for HTTP
• conf/apache2/000-default-ssl.conf: The Apache2 default configuration for HTTPS

For further details howto install and configure the Apache2 web server correct is described inside doc/apache2.md.

Enter the application:

• The basic web page: http://localhost/
• The Adminer: http://localhost/adminer.php

Development

The development of this application is based on following tools:

• PHP is the main programing language
• Composer is used as the main dependency manager for PHP
• PHP Coding Standards Fixer (PHP CS Fixer) is a tool to automatically fix PHP coding standards issues
• PHPStan is a static code analysis tool for PHP
• PHPUnit is a programmer-oriented testing framework for PHP

PHP Coding Standards Fixer (PHP CS Fixer)

PHP Coding Standards Fixer (PHP CS Fixer) is a tool to automatically fix PHP coding standards issues. It is a standalone CLI tool that you can use on your projects regardless of the framework you use.

vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.dist.php -v --using-cache=no --allow-risky=yes src

PHPStan

PHPStan is a static code analysis tool for PHP.

vendor/bin/phpstan analyse src tests --level=max

PHPUnit

PHPUnit is a programmer-oriented testing framework for PHP.

vendor/bin/phpunit --configuration phpunit.xml.dist

Concepts and Inspiration

Not everything is invented here, so here are some links to other projects tah inspired this project and implementation:

• A very lightweight template engine with PHP: https://codeshack.io/lightweight-template-engine-php/