tomkyle/webapp-boilerplate

This is how I would start a new PHP web application on PHP 8.1+, based on Slim 4 , Docker, Gulp, Webpack, PhpUnit, and pretty much everything I find useful.

---

Features

• Slim Framework
• Docker setup with SSL support
• PhpUnit with basic unit and integration tests
• Composer scripts with PHP-CS and phpstan
• Gulp + Webpack for frontend workflow
• Serviceworker and Webmanifest
• Modern favicons setup
• Content-Security-Policy configuration file
• Customizable .htaccess configuration and build tool
• Custom error pages
• Dark mode support with JS theme switcher
• Postman collection

---

Installation

$ gh repo clone tomkyle/webapp-boilerplate
$ cd webapp-boilerplate

On production environment, install dependencies like this:

$ composer install --no-dev

On development environment, install dependencies as follows.

$ composer install
$ npm install

After successful installation

1. Composer will automatically run the bin/post-install.php script which, if necessary, creates a .env file and a public/.htaccess, based on their respective dist template files.
2. Open .env and public/.htaccess in your editor and adapt to your needs.
3. Edit public/robots.txt and change sitemap URL.
4. On development environment:
   • Setup the SSL certificates for the Docker container. See section below.
   • Also edit the source file header in .php-cs-fixer.dist.php

---

Docker container

Prepare SSL certificates

The Apache webserver inside the docker container requires *.pem development certificates for its SSL engine. Create those and store them in resources/docker/ssl/ directory.

A good tool for creating locally trusted development certificates is Filippo Valsorda's mkcert. It is available for MacOS, Linux, and Windows; follow the docs over on GitHub on how to install mkcert.

$ cd resources/docker/ssl
$ mkcert \
-key-file localhost-key.pem \
-cert-file localhost.pem \
localhost 127.0.0.1 ::1

Running Docker

You can use docker-compose.yml to serve on https://localhost/. Make sure you installed some locally trusted SSL certificates / PEM keys as described above. To turn on Docker machine:

$ docker compose up
# and somewhere else:
$ docker compose down

---

Server configuration

Building .htaccess

The public/htaccess.dist distributed with the repo combines modules from the H5BP Apache Server Configs and Jeff Starr's Perishable Press 7G Firewall.

This repo uses a .htaccess configuration file located in the server-configs directory. This kind of file is described on the H5BP Apache Server Configs project site. Have a look at their docs on how to tweak your .htaccess file.

To build a new public/htaccess.dist file:

$ composer htaccess
$ cp public/htaccess.dist public/.htaccess

Custom error pages / ErrorDocument

Do not forget to edit or add your contact data to the HTML files inside the public/errordocs/ directory. To disable custom error documents, look inside the .htaccess configuration file – you'll find this line:

enable  "resources/server-configs/custom-errorpages.conf"

Simply change to disable … and rebuild the .htaccess.

Content-Security-Policy

The web app uses \Middlewares\CSP middleware for certain routes. The value of the CSP header can be defined in configs/csp.dist.yaml (or configs/csp.yaml, respectively).

The distributed csp.dist.yaml creates the same CSP headers than those used in the H5BP Apache Server Configs project. Head over to their original content-security snippet: content-security-policy.conf

---

Command Line Interface

General information

$ bin/console list
$ bin/console help

Update website from repo

Pull the latest stuff from repo; install dependencies without the development stuff.

$ git pull
$ bin/console install --no-dev
$ bin/console install --no-dev -v

---

Frontend development

Gulp and Webpack

The npx command will use local or global Gulp CLI. Watch file changes and build assets like so:

$ npx gulp watch
$ NODE_ENV=production npx gulp watch

Development builds

$ npm run dev
# Alias for
$ npx gulp && npx workbox-cli injectManifest

Production builds

$ npm run build
# Alias for
$ NODE_ENV=production npx gulp && NODE_ENV=production npx workbox-cli injectManifest

Building Favicons

This feature uses svgexport and imagemagick's convert to create various PNG favicons and a traditional ICO file.

1. Put a new SVG favicon favicon.svg into the public/favicons directory
2. Run build script to create several PNG favicons as well as a favicon.ico file:

$ bin/favicons

---

Running tests

This packages has predefined test setups for code quality, code readability and style, unit/integration tests, and frontend performance. Check them out at the scripts sections of composer.json and package.json.

PhpStan

Default configuration is phpstan.neon.dist. Create a custom phpstan.neon to apply your own settings. Also visit phpstan.org · GitHub · Packagist

$ composer phpstan

# which includes
$ phpstan analyse

PHP-CS

Default configuration is .php-cs-fixer.dist.php. Create a custom .php-cs-fixer.php to apply your own settings. Also visit cs.symfony.com · GitHub · Packagist

$ composer phpcs
$ composer phpcs:apply

PHPUnit and integration tests

Default configuration is phpunit.xml.dist. Create a custom phpunit.xml to apply your own settings. Also visit phpunit.readthedocs.io · Packagist

$ composer test

# which includes these two:
$ composer test:unit
$ composer test:integration

Frontend performance

Default configuration is lighthouserc.js. Before running Lighthouse CI on the Docker machine, a production build is triggered. Test results will go locally in ./tests/lhci directory. Visit lhci docs · Google's Lighthouse

$ npm run lighthouse
# Alias for
$ npx lhci autorun lighthouserc.js

Postman API testing

Postman users import the requests collection.json from the resources/postman directory. All requests are prefixed with a {{LOCALHOST}} variable; either set its value in Postman or replace the whole string with a text editor.

---

License

The MIT License (MIT). Please see License File for more information.