PHP-Bereich

PHP-spezifische Specs, Templates und Skripte unter /var/www/code/php/.

Inhalt

README

# PHP Templates — YAML Criteria Reference

## YAML Schema Variants

The `criteria.yaml` files across templates use **two different schema variants**:

### Variant 1: Structured (meta + paradigms/checks/anti_patterns)

Used by templates like `entity/`, `value-object/`, `repository/`, `domain-event/`, etc.

```yaml
<template>_criteria:
  <criterion_key>:
    description: >
      Multi-line description of what is expected.
    check: "How to verify this criterion."
    severity: critical | high | medium | low | recommended
```

Top-level key is named after the template (e.g., `entity_criteria`, `value_object_criteria`).
Each criterion is a named mapping with `description`, `check`, and `severity` fields.

### Variant 2: Flat criteria list

Used by templates like `request-dto/`, `response-dto/`, `controller/`, etc.

```yaml
template: <name>
version: "1.0"
language: php
minimum_version: "8.2"

criteria:
  - id: <criterion-id>
    weight: <int>
    description: >
      Multi-line description.
    check: "How to verify."

scoring:
  max_points: <int>
  pass_threshold_percent: 90
```

Top-level includes `template`, `version`, `language`, `minimum_version` metadata.
Criteria is a list of mappings with `id`, `weight`, `description`, and `check` fields.
Scoring section defines `max_points` and `pass_threshold_percent`.

## Accepted Severity Values

The following severity values are accepted (from most to least severe):

- `critical`
- `high`
- `medium`
- `low`
- `recommended`

**Note:** The value `major` was historically used in some files as an alias for `high`.
It has been normalized to `high`. Any tooling that encounters `major` should treat it
as equivalent to `high`.

## KC PHP_PROFILE_PHASE1 Integration

KC reflects PHP code tasks against a finer PHP_PROFILE_PHASE1 artifact model.
The goal is to preserve the frameworkless PHP, DDD, Hexagonal, SRP, SoC and
Clean-Architecture character of the projects while making security-sensitive
boundaries visible in task planning, supervision and verification.

Phase-1 artifact types:

- `auth_handler_php`
- `session_cookie_php`
- `csrf_boundary_php`
- `repository_pdo_php`
- `transaction_boundary_php`
- `history_audit_php`
- `template_html_escape_php`
- `upload_handler_php`
- `mail_sender_php`
- `config_env_php`
- `router_php`
- `middleware_php`
- `exception_handler_php`
- `command_handler_php`
- `query_handler_php`
- `request_dto_php`
- `response_dto_php`
- `request_validator_php`
- `response_factory_php`

Supervision starts as warnings. It requires the task text to make the relevant
concern visible: Auth/Session state, cookie attributes, CSRF acceptance,
template escaping, PDO parameter binding, transactions, history/audit recovery,
upload validation, mail privacy, config/secrets, routing, middleware security,
DTO contracts and validator behavior.

Verification remains shell-free. Active PHP verification includes `/usr/bin/php
-l` and internal `forbid_regex` checks for public email/token URLs, dangerous
PHP execution functions, raw `$_REQUEST` access and unescaped template output.

## KC PHPUNIT_PHPSTAN_STANDARDPROFILE Integration

PHPUnit and PHPStan are standard verification tools without requiring Composer,
`vendor/bin`, or an external framework. KC uses global safelisted executables:

- `/usr/local/bin/phpunit`
- `/usr/local/bin/phpstan`

The required boundary is project-root execution. KC must discover the root from
the changed PHP file by walking upward to `phpunit.xml`, `phpunit.xml.dist`,
`phpstan.neon`, or `phpstan.neon.dist`, then run the tool with
`current_dir(project_root)`.

Project placeholders:

- `{project_root}`
- `{relative_file_path}`
- `{phpunit_config}`
- `{phpstan_config}`
- `{test_path}`

PHPUnit:

- Directly affected test files run with `required=true`.
- KC does not guess source-to-test mappings unless the test path is
  deterministic and exists.

PHPStan:

- Source files run with `project_argv` and project config.
- PHPStan uses `--debug` and project-local `TMPDIR` to avoid parallel TCP-worker
  and `/tmp/phpstan` permission problems.
- PHPStan starts with `required=false` until several real task runs prove that
  the project baselines and bootstrap assumptions are stable enough to block.

Zurück zur Übersicht aller Bereiche