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 public directory.
• /public: 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 git@github.com:bassix/basic.git bassix-basic
cd bassix-basic

(Optional) GitLab alternative and fallback repository copy:

git clone git@gitlab.com: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

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.

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:8000 -t public

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

nohup php -S 127.0.0.1:8000 -t public > 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:8000
• The Adminer: http://localhost:8000/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

Docker and Docker Compose

Build and start the small and simple environment:

docker-compose up -d

Access the application:

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

Build and start the development environment with all containers incl. Adminer and PHPMyAdmin:

docker-compose -p basic -f docker-compose.yml -f docker-compose.dev.yml up -d --build --force-recreate

Check if all containers are running correctly:

docker-compose -p basic ps

Access the application:

• The basic web page: http://localhost:8080
• The Adminer:
  • Internal: http://localhost:8080/adminer.php
  • Dedicated app: http://localhost:8081
• The PHPMyAdmin: http://localhost:8082

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/