feat/grpc (#25)

Reviewed-on: #25
Co-authored-by: Ron Rise <ron@siteworxpro.com>
Co-committed-by: Ron Rise <ron@siteworxpro.com>

README.md

@@ -2,55 +2,132 @@
 
 ![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
 
-### Prerequisites
-- Docker
-- Docker Compose
+This project uses Docker Compose and Make to manage the development environment. The `makefile` provides convenient
+commands for common development tasks.
 
-### migrations
+## Prerequisites
 
-create a new migration
-```shell
-docker run --rm  -v $(PWD):/app siteworxpro/migrate:v4.18.3 create -ext sql -dir /app/db/migrations -seq create_users_table
+- 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
 ```
 
-```text
-postgres://siteworxpro:password@localhost:5432/siteworxpro?sslmode=disable
+## 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
 ```
 
-```shell
-docker run --rm  -v $(PWD):/app siteworxpro/migrate:v4.18.3 -database "postgres://siteworxpro:password@localhost:5432/siteworxpro?sslmode=disable" -path /app/db/migrations up
+### Adding a New Package
+
+```bash
+make composer-require package=vendor/package-name
 ```
 
-### Starting the Runtime
-```shell
-docker-compose up -d
-```
-### Start the server
-```shell
-docker exec -it template-dev-runtime-1 rr serve
+### Running Tests
+
+```bash
+make test
 ```
 
-You can access the api at `http://localhost:9501/`
+### Code Quality Check
 
-### Xdebug
-
-xdebug needs to be built into the container before it will work
-```shell
- docker exec -it php-template-composer-runtime-1 bin/xdebug.sh
+```bash
+make lint
+make fmt
 ```
 
-### Install the dependencies
-```shell
-docker run --rm  -v $(PWD):/app siteworxpro/composer install --ignore-platform-reqs
+### Debugging
+
+```bash
+make enable-debug
+make run
 ```
 
-### Running all tests
-```shell
-docker run --rm  -v $(PWD):/app siteworxpro/composer run tests:all
-```
+## 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