Template

Overview

This is a PHP project template that provides a structured development environment using Docker Compose and Make. It includes tools for code quality, testing, dependency management, and gRPC support.

Dev Environment

This project uses Docker Compose and Make to manage the development environment. The makefile provides convenient commands for common development tasks.

Prerequisites

• Docker and Docker Compose
• Make
• protoc (Protocol Buffers compiler) - for gRPC code generation

Quick Start

# Install PHP dependencies
make composer-install

# Start the development container
make start

# Run the application server
make run

Available Commands

Container Management

• make start - Start the development runtime container
• make stop - Stop and remove all containers
• make restart - Restart the development container
• make rebuild - Rebuild containers (use after Dockerfile changes)
• make sh - Open a shell in the development container
• make ps - Show running containers

Application

• make run - Run the application server (RoadRunner)
• make migrate - Run database migrations

Composer & Dependencies

• make composer-install - Install PHP dependencies
• make composer-update - Update PHP dependencies
• make composer-require package=vendor/package - Add a new dependency
• make composer-require-dev package=vendor/package - Add a new dev dependency

Code Quality

• make lint - Run linters (phpcs and phpstan)
• make fmt - Format code with php-cs-fixer
• make test - Run the test suite (phpunit)
• make license-check - Check license headers in source files

Debugging & Coverage

• make enable-debug - Enable Xdebug for debugging
• make enable-coverage - Enable PCOV for code coverage

gRPC

• make protoc - Generate PHP gRPC code from .proto files

CI Workflow

• make ci - Run the full CI pipeline locally (install, license check, lint, test)

Help

• make help - Show all available commands with descriptions

Common Workflows

Starting Development

make composer-install
make start
make run

Adding a New Package

make composer-require package=vendor/package-name

Running Tests

make test

Code Quality Check

make lint
make fmt

Debugging

make enable-debug
make run

Notes

• All commands run inside Docker containers, ensuring a consistent environment
• The development runtime uses RoadRunner as the application server
• Composer commands run in a separate composer-runtime container
• Database migrations run in a dedicated migration-container

Additional Information

Accessing Services

• You can access the api at https://localhost
• Traefik dashboard is at https://127.0.0.1/dashboard/
• the grpc server is at tcp://localhost:9001

License

Copyright (c)2025 Siteworx Professionals, LLC

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
documentation
files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom
the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.