From f1cdc9421ce3740dae69aeaefd4671843638a3fd Mon Sep 17 00:00:00 2001 From: Oscar Merida Date: Wed, 14 Jan 2026 23:15:24 -0500 Subject: [PATCH] * Document some architectural decisions for the project. --- docs/decisions/01-follow-psr-11.md | 24 +++++++++++++ docs/decisions/02-dependency-injection.md | 32 +++++++++++++++++ docs/decisions/03-follow-psr4-autoloading.md | 36 ++++++++++++++++++++ docs/decisions/04-adopt-coding-standard.md | 32 +++++++++++++++++ docs/decisions/05-use-php-codesniffer.md | 30 ++++++++++++++++ docs/decisions/_adr-template.md | 25 ++++++++++++++ 6 files changed, 179 insertions(+) create mode 100644 docs/decisions/01-follow-psr-11.md create mode 100644 docs/decisions/02-dependency-injection.md create mode 100644 docs/decisions/03-follow-psr4-autoloading.md create mode 100644 docs/decisions/04-adopt-coding-standard.md create mode 100644 docs/decisions/05-use-php-codesniffer.md create mode 100644 docs/decisions/_adr-template.md diff --git a/docs/decisions/01-follow-psr-11.md b/docs/decisions/01-follow-psr-11.md new file mode 100644 index 0000000..9585304 --- /dev/null +++ b/docs/decisions/01-follow-psr-11.md @@ -0,0 +1,24 @@ +--- +status: accepted +date: 14-JAN-2026 +--- + +# Follow PSR-11 for Dependency Injection Containers + +## Context and Problem Statement + +The spacetraders application should use a dependency injection container (DIC) to promote object composition and discourage direct instantiation of service classes. + +## Considered Options + +* [Adopting PSR-11](https://www.php-fig.org/psr/psr-11/) +* Rolling a custom container + +## Decision Outcome + +Any DIC we use must follow PSR-11 to allow us to change to a new or better implementation in the future. + +### Consequences + +* May limit the packages we can use as a DIC +* We are not locked into using any single solution. diff --git a/docs/decisions/02-dependency-injection.md b/docs/decisions/02-dependency-injection.md new file mode 100644 index 0000000..06d4a49 --- /dev/null +++ b/docs/decisions/02-dependency-injection.md @@ -0,0 +1,32 @@ +--- +status: accepted +date: 14-JAN-2026 +--- + +# Use PHP-DI for service container + +## Context and Problem Statement + +PHP classes should support dependency injection for composing objects instead of direct instantiation. We need to provide an easy-to-use Dependency Injection container for developers that follows PSR-11 container interface. + +## Considered Options + +* php-di/php-di + * PRO: autowiring based on typehints, can register with callbacks. Have previous experience using it. + * CON: many open issues +* league/container + * PRO: actively maintained + * CON: service registration is verbose +* symfony/dependency-injection + * PRO: backed by symfony development + * CON: service registration is verbose + +## Decision Outcome + +Use PHP-DI due to familiarity with it and its syntax. + +### Consequences + +* Will implement a service container that uses PHP-DI +* May need to look into container compilation as application grows. + diff --git a/docs/decisions/03-follow-psr4-autoloading.md b/docs/decisions/03-follow-psr4-autoloading.md new file mode 100644 index 0000000..6f701a5 --- /dev/null +++ b/docs/decisions/03-follow-psr4-autoloading.md @@ -0,0 +1,36 @@ +--- +status: accepted +date: 01-Jan-2026 +--- + + +# Use PSR-4 for Autoloading custom classes + +## Context and Problem Statement + +Project needs to follow some autoloading mechanism for PHP classes. + +## Considered Options + +* Adopt [PSR-4](https://www.php-fig.org/psr/psr-4/) + * PRO: supported by Composer and known wider PHP community +* Write a custom autoloader + * CON: another thing to maintain + +## Decision Outcome + +Custom classes must follow PSR-4 conventions for naming files and namespaces. + +### Consequences + +We will need to register namespaces in `composer.json`. For example: + +```json + "autoload": { + "psr-4": { + "Phparch\\SpaceTradersCLI\\": "cli/", + "Phparch\\SpaceTraders\\": "src/" + } + }, +``` + diff --git a/docs/decisions/04-adopt-coding-standard.md b/docs/decisions/04-adopt-coding-standard.md new file mode 100644 index 0000000..db2c38a --- /dev/null +++ b/docs/decisions/04-adopt-coding-standard.md @@ -0,0 +1,32 @@ +--- +status: accepted +date: 01-JAN-2026 +--- + +# Adopts PER-3 as project coding style + +## Context and Problem Statement + +Spacetraders application code needs to follow a consistent coding style guide that can be enforced with an automatic linter and supported by most IDEs. + +## Considered Options + +Both of these candidates report violations and can try to fix them. + +* [PSR-12](https://www.php-fig.org/psr/psr-12/) +* * PRO: existing coding standard we can adopt + * CON: superceded by PER-3 +* [PER-3](https://www.php-fig.org/per/coding-style/) + * PRO: evolving standard, adopted in wider PHP community +* Symfony, Drupal, WordPress or other coding standard + * PRO: existing coding standard we can adopt + * CON: We are not any of those projects and they each have their own quirks. + +## Decision Outcome + +Use PER-3 as the project's coding style and enforce it automatically. + +### Consequences + +Need to identify tooling for linting and automated checks. + diff --git a/docs/decisions/05-use-php-codesniffer.md b/docs/decisions/05-use-php-codesniffer.md new file mode 100644 index 0000000..c660eab --- /dev/null +++ b/docs/decisions/05-use-php-codesniffer.md @@ -0,0 +1,30 @@ +--- +status: accepted +date: 01-JAN-2026 +--- + +# Use PHPCodeSniffer to enforce PER-3 + +## Context and Problem Statement + +We have adopted [PER-3](https://www.php-fig.org/per/coding-style/) as our coding style and need automated tools to check, fix, and enforce adherence. + +## Considered Options + +* [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) + * PRO: Familiar with configuring it + * CON: XML for rules configuration +* [PHP CS Fixer](https://github.com/PHP-CS-Fixer/PHP-CS-Fixer) + * PRO: Part of symfony + + +## Decision Outcome + +Use PHP_Codesniffer since we are familiar with configuring it. + +### Consequences + +* Add to dev packages in `composer.json` +* Document how to run its linter and fixer at the command line +* Report violations when someone tries to push code. +* Check for violations in CI. diff --git a/docs/decisions/_adr-template.md b/docs/decisions/_adr-template.md new file mode 100644 index 0000000..a759888 --- /dev/null +++ b/docs/decisions/_adr-template.md @@ -0,0 +1,25 @@ +--- +status: proposed | rejected | accepted | deprecated | … | superseded by ADR-0123 +date: DD-MMM-YYYY +decision-makers: +consulted: +informed: +--- + + +# + +## Context and Problem Statement + + + +## Considered Options + + + +## Decision Outcome + + + +### Consequences +