# Template

![pipeline status](https://gitea.siteworxpro.com/siteworxpro/Php-Template/actions/workflows/tests.yml/badge.svg?branch=master&style=flat-square)

## 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

```bash
# 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

```bash
make composer-install
make start
make run
```

### Adding a New Package

```bash
make composer-require package=vendor/package-name
```

### Running Tests

```bash
make test
```

### Code Quality Check

```bash
make lint
make fmt
```

### Debugging

```bash
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](https://localhost)
- Traefik dashboard is at [https://127.0.0.1/dashboard/](https://127.0.0.1/dashboard/)
- the grpc server is at [tcp://localhost:9001](tcp://localhost:9001)

## License

```text
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.
```