mirror of
https://github.com/itflow-org/itflow
synced 2026-09-17 12:15:14 +00:00
70 lines
4.2 KiB
Markdown
70 lines
4.2 KiB
Markdown
# Agent Guidelines
|
|
|
|
## Code and tooling
|
|
|
|
- All code must remain compatible with PHP 7.4. Run PHPStan and PHP-CS-Fixer
|
|
only under a PHP 7.4.x runtime; never run either tool under any other PHP
|
|
major.minor version.
|
|
- Use fully qualified `#[\SensitiveParameter]` on concrete executable
|
|
parameters when their established role normally carries a secret,
|
|
credential-bearing aggregate, or confidential Guzzle-owned container, and
|
|
the active frame can throw or invoke throwing code.
|
|
- Repeat the attribute on every qualifying owned caller, callee, concrete trait
|
|
method, and closure parameter. Do not add it to interfaces, abstract-only
|
|
declarations, pure/no-realistic-throw helpers, assignment-only sites,
|
|
arbitrary generic payloads, or completed non-recoverable derivatives.
|
|
- For PHP 7.4 compatibility, put `#[\SensitiveParameter]` on its own line and
|
|
the parameter on the following line, expand the complete parameter list, and
|
|
never add a comma after the final parameter. Native trace redaction starts on
|
|
PHP 8.2 and does not redact logs, messages, properties, wire traffic, captured
|
|
variables, return values, or the separate backtrace `$this`/`object`.
|
|
- Always pass an explicit character list to `trim()`, `ltrim()`, and `rtrim()`;
|
|
never rely on the default characters.
|
|
- Handle `preg_*` engine failures: when the result is used as data, test for
|
|
`false` or `null` and throw a `\RuntimeException` including
|
|
`preg_last_error_msg()`; boolean validation guards must compare strictly, such
|
|
as `=== 1`, so an engine failure can only ever fail closed. Diagnostic
|
|
escaping is the narrow exception: use a deterministic bytewise fallback rather
|
|
than throwing, so it cannot obscure the original exception.
|
|
- Anchor validation patterns to the true end of input with the `D` modifier or
|
|
`\z`; a bare `$` accepts a trailing newline.
|
|
- Never embed raw control bytes in exception messages and other diagnostics;
|
|
escape or redact the offending value first.
|
|
- Helper classes that expose only public static methods are `final` and have a
|
|
private constructor.
|
|
- Resist native PHP serialization when a class holds live state (streams,
|
|
resources, handles, callbacks, credentials) or when magic methods such as
|
|
`__destruct()` have side effects that untrusted unserialized data could
|
|
redirect, as with the file and session write fixes in Guzzle's persisting
|
|
cookie jars. Plain data holders, such as Guzzle's in-memory cookie jar, remain
|
|
serializable.
|
|
- To resist, `__serialize()` and `__unserialize()` both throw
|
|
`\LogicException(static::class.' should never be serialized')` and its
|
|
unserialized counterpart, usually via the `@internal`
|
|
`NonSerializableStreamTrait`. Where a `__destruct()` has such a side effect,
|
|
it is enabled only by the constructor and disabled in `__wakeup()` and
|
|
`__unserialize()` before throwing, so the protection holds even if the
|
|
exception is swallowed.
|
|
- In general, numeric inputs should not accept non-finite floats. In situations
|
|
where they are accepted and we need to cast to a string, we should branch on
|
|
`\is_finite($value)`, using `(string) $value` for the finite case and
|
|
`\is_nan($value) ? 'NAN' : ($value > 0 ? 'INF' : '-INF')` otherwise.
|
|
- Never call `strtolower()`, `strtoupper()`, `strcasecmp()`, `stripos()`, or
|
|
other locale-sensitive case functions; use the locale-independent
|
|
`Utils::asciiToLower()`, `Utils::asciiToUpper()`, `Utils::caselessEquals()`,
|
|
and `Utils::caselessContains()` helpers instead.
|
|
- Changes in behavior need a `CHANGELOG.md` entry in the unreleased section of
|
|
the target branch and an `UPGRADING.md` note when the behavior differs between
|
|
major versions.
|
|
|
|
## Documentation
|
|
|
|
- Wrap markdown prose and PHPDoc text to 80 columns using greedy wrapping. Never
|
|
split a markdown link or an inline code span across a line break; a line that
|
|
cannot be broken may exceed the limit. Avoid em dashes.
|
|
- Keep PHPDoc and the corresponding `docs/` pages in sync: shared prose is
|
|
deliberately word-for-word identical, including boilerplate copied verbatim
|
|
between related functions, so apply the same edit to every copy. Only
|
|
formatting and linking may differ, such as a docs link becoming a PHPDoc
|
|
`@see` tag; the wording must never drift.
|