shrink/laravel-strict

:briefcase: Laravel install for building containerised applications with strict standards

Laravel Strict

Laravel 8 + Docker shrink/docker-php-api:8

Laravel Strict is a Laravel ^⇗ install designed for building high quality containerised Laravel applications.

• All HTTP requests served by Laravel — ideal for an API
• Code quality enforced by vimeo/psalm^⇗ and squizlabs/php_codesniffer^⇗
• Laravel configured with sane defaults and without boilerplate
• Continuous Delivery using GitHub Actions and the GitHub Container Registry
• Development Environment using Docker Compose
• Taskfile^⇗ with helpful development lifecycle commands

💭 Laravel Strict is intended for projects with strict code quality requirements, it was created for use in regulated environments where confidence is more valuable than development speed.

1. Getting Started with Laravel Strict
2. Features included in Laravel Strict
3. Differences between Laravel Strict and Laravel
4. Development Environment

Getting Started

Laravel Strict is designed to be up and running immediately, producing a deployable application image from the first commit. Generate^⇗ a new repository from this template and complete these steps from your new repository.

• Generate and add a Personal Access Token^⇗ to the repository secrets with name GHCR_PAT
• Fill out composer.json with project name and description
• Create your README.md with a project name and description

Your application is now ready to go: a production-ready Docker image has been built and pushed to the GitHub Container Registry by the build workflow. Start developing!

dev:~$ git clone https://github.com/example/my-strict-application.git
dev:~$ task start
»» Launched application at http://localhost:8094

Features

Healthcheck

Docker's HEALTHCHECK functionality declares a command that Docker can use at runtime to check the health of a container. Laravel Strict ships with a healthcheck endpoint (using Conductor) that is checked at a 10s interval.

Differences

There are differences between this install of Laravel and the standard that a developer will need to keep in mind. Many defaults have been removed, consolidated or changed to encourage best practices.

During development any required boilerplate can be obtained from the laravel/laravel repository. When introducing boilerplate into the project the code must be updated to meet the quality standards of the application.

Configuration

Configuration has been moved from config/*.php into the application bootstrap in bootstrap/app.php where all additional configuration of the application should take place. All of Laravel's optional configuration options have been removed, only required configuration is included by default.

Aliases have been removed as they encourage bypassing dependency injection.

Routing

The routes directory has been removed in favour of explicit route registration through a ServiceProvider for each component, as this encourages developers to think about HTTP as one interface into the application — rather than the application.

Environment

Laravel ships with vlucas/phpdotenv for easy environment variable management, however for a containerised application this library is unnecessary and may even compromise portability. All environment variables should be provided via the container orchestration engine, e.g: Docker Compose.

Application Build

.dockerignore excludes all files by default before explicitly including paths required by the application. Learn more about this approach in Getting Control Of Your .dockerignore Files by @markbirbeck.

Development Environment

task

Task is a cross-platform task runner, which is used to provide a full suite of commands for use during the development lifecycle.

dev:~$ task
task: Available tasks for this project:
* check: 	Run application checks (code quality, tests)
* start: 	Start the local application environment
* .....: 	+ more

Environment Variables

Environment Variables should be explicitly set for each service in docker-compose.yml to emulate how environment variables will be provided in production environments. A developer can use docker-compose.override.yml to provide values unique to their local environment.

Volumes vendor + storage

The vendor and storage directories are volume mounts to maximise performance, however this means by default the host machine cannot access the volume contents.

Developers can bind mount these volumes instead to gain access to the volume contents by overriding the volume configuration in their docker-compose.override.yml.

+services:
+  app:
+    volumes:
+      - .:/srv
+      - ./storage:/srv/storage
+      - ./vendor:/srv/vendor

⚠️ bind mounting volumes in this way may reduce application performance in development by up to 10x