8fold Architecture for PHP

Consumer dependencies

The 8fold Quality Suite is intended to be a development dependency in consuming projects. Composer ignores a dependency's require-dev entries, so the suite lists PHPStan, PHPCS, and its required PHPStan extension in its own require. When a consumer lists the suite in require-dev, those transitive dependencies are also development-only unless another production dependency requires them.

The same package currently provides runtime contracts such as Eightfold\Interfaces\ToString. An application class that implements one needs the contract when PHP loads that class, including in a private deployment. A consumer using such contracts at runtime cannot omit the suite with composer install --no-dev. Independent distribution of runtime contracts is tracked in #61.

With Composer's default vendor/ directory, include the suite in the consumer's existing phpstan.neon:

includes:
    - vendor/8fold/php-architecture/extension.neon

Set a PHPStan analysis level in the consumer's configuration. To run the suite's PHPCS sniffs against a consumer's src/ directory:

./vendor/bin/phpcs --standard=vendor/8fold/php-architecture/src/PHPCS/Efqs src

The Efqs standard contains the suite's sniffs; include any additional coding standards in the consumer's own PHPCS configuration. This repository's root phpcs.xml is its local ruleset, not the consumer standard.

Install the shared agent rules, context, and Graphify guides

Add 8fold/php-architecture to the consuming project's Composer dependencies and install them. From the consuming project's root, copy the shared rules and the project context and Graphify guides:

./vendor/bin/efqs docs:agents
./vendor/bin/efqs docs:context
./vendor/bin/efqs docs:graphify-setup
./vendor/bin/efqs docs:graphify-workflow

The commands copy AGENTS.md, docs/agent-context.md, docs/graphify-setup.md, and docs/graphify-workflow.md, respectively, creating destination directories if needed. Each command leaves an identical destination unchanged and refuses to overwrite a different file. Copying the guides does not install Graphify, configure hooks, or create a graph.

Composer makes efqs available in its configured bin-dir, which defaults to vendor/bin. To expose the commands as Composer scripts, add these entries to the consuming project's existing composer.json scripts:

{
  "scripts": {
    "efqs:docs:agents": "efqs docs:agents",
    "efqs:docs:context": "efqs docs:context",
    "efqs:docs:graphify-setup": "efqs docs:graphify-setup",
    "efqs:docs:graphify-workflow": "efqs docs:graphify-workflow"
  }
}

The copied context and guides are starting points, not consuming-project facts. Adapt project-specific setup and commands before relying on them.

Install contribution policy and templates

The contribution guide defines the cumulative triage rubric and change classification. This repository retains existing labels while adding the apps categories. Labels are live GitHub metadata, not files; use the guide's label-cloning procedure to add them to a consuming repository.

The reusable-file inventory below records each command's package source and consumer destination. They are the same relative path, rooted respectively at the installed package and the consuming project's current directory.

efqs command	Source and destination
docs:contributing	.github/contributing.md
docs:convention-workflow	docs/convention-workflow.md
templates:bug	.github/ISSUE_TEMPLATE/Bug_report.md
templates:feature	.github/ISSUE_TEMPLATE/Feature_request.md
templates:deprecation	.github/ISSUE_TEMPLATE/Deprecation_notice_or_request.md
templates:convention	.github/ISSUE_TEMPLATE/Convention_request.md
templates:pull-request	.github/pull_request_template.md

Run individual commands from the consuming project root:

./vendor/bin/efqs docs:contributing
./vendor/bin/efqs templates:bug
./vendor/bin/efqs templates:pull-request

For a human-friendly Composer entry point, add the commands needed by the project to its existing scripts:

{
  "scripts": {
    "efqs:docs:contributing": "efqs docs:contributing",
    "efqs:templates:bug": "efqs templates:bug",
    "efqs:templates:pull-request": "efqs templates:pull-request"
  }
}

All copy commands retain the same no-overwrite behavior as docs:agents. They create directories when needed but do not install labels or copy linked files automatically. Keep the shared agent rules, project context, security policy, code of conduct, and relevant instructions available; adapt links and commands to the consuming project. Convention templates also refer to the convention workflow. Review existing GitHub template locations before copying: the default PR template is .github/pull_request_template.md, not an additional conflicting default.

Contributing and choosing work

Use the issue-triage procedure when evaluating the backlog. Labels contribute qualitative impact, while current evidence and dependencies establish readiness. A recommendation does not authorize implementation or issue changes. The template instruction governs template maintenance.

Refresh code in this repository's knowledge graph

From the repository root:

composer graph:code

This refreshes code only; documentation still needs the Graphify skill's semantic refresh. The agent context describes the command's requirements and its code-only alias.

PHP conventions (strict)

• Class stringability: classes with direct or inherited stringability implement Eightfold\Interfaces\ToString directly or indirectly. The interface also requires toString(): string; the PHPStan rule is enabled in extension.neon. See the enforcement boundaries.
• Explicit boolean expressions: prefer positive conditions or strict comparisons to negating a boolean expression with !. The type-aware BooleanNegationMustBeExplicit PHPStan rule is implemented but disabled. See the enforcement boundaries for its scope and current activation state.
• Method scope: Guidance distinguishes self::, parent::, and $this->. The registered PHPCS sniff checks instance method calls via $this->; it does not enforce every scope convention.
• Data object and record purity: No PHPStan purity rules are currently shipped.

PHP conventions (default with options)

• Class finality and inheritance: ClassesShouldBeFinal and ClassesShouldNotBeSubclass recognize Eightfold\Attributes\Classes\BaseClass and Eightfold\Attributes\Classes\Subclass as their respective advisory opt-outs. The corresponding Must rules do not accept those opt-outs. The corresponding PHPStan rules are currently disabled in extension.neon.
• Data Objects are PHP classes

Attribute inference

CallableSubtype supports name lookups, but the unfinished fromFlags() sketch is not part of the production API. The inference prototype is non-autoloaded and unsupported.