Skip to content

AGENTS.md

Latest commit

 

History

History
69 lines (53 loc) · 2.98 KB

AGENTS.md

File metadata and controls

69 lines (53 loc) · 2.98 KB
Raw

To My Agents!

It is my fervent wish that this file guide every AI coding agent working with code in this repository.

Documentation

Any distilled, agent-facing documentation for this package - how it works internally and the rationale behind key design decisions - lives in docs/. Consult it before non-trivial changes; it is the source of truth from which the public manual is distilled.

Five small files, but a genuinely tricky core (tree + monitoring + lookup + cloning). Almost all the value is in the monitor walks (Component::attachMonitors / detachMonitors) and the cloning handshake - read docs/internals.md before touching them.

docs/upgrading.md records, per released version, every change visible to users of the package (renames, removals, deprecations, signatures, behavior, configuration), each with its commit hash; internal changes are not in it. It is the place to look up the history of a public symbol. Do not write to it; it is extended at release time from the git history.

Project Overview

nette/component-model is the foundational component architecture for the Nette Framework: a hierarchical system where components nest inside containers, are monitored for attach/detach events, and are addressed through a path-based lookup. Consumed by Forms and Application, not usually used directly.

  • PHP Version: 8.3 - 8.6
  • Package: nette/component-model

Essential Commands

# Run all tests
composer tester        # or: vendor/bin/tester tests -s

# Run a single test file
php tests/ComponentModel/Container.getComponentTree.phpt

# Static analysis (PHPStan level 8)
composer phpstan

Conventions

  • Every file starts with declare(strict_types=1);; the coding style is checked by DressCode (dresscode.neon).
  • Tests are Nette Tester .phpt files; they usually define minimal component classes inline.

Working in this repo

  • Monitoring is a single-pass, live-mutation-safe walk with a precise order: attached fires top-down (ancestor→descendant), detached fires bottom-up, and detach is depth-gated. The handler registry ($monitors), the depth each type was notified about ($attachedDepths, updated before the handlers run) and the lookup cache ($lookups, dropped for the whole subtree on every parent change) are kept apart. A throwing listener vetoes the change. This is the sharp edge - see docs/internals.md and the ADR it references before changing it.
  • Cloning re-homes children via a cross-instance handshake (the private Component::$cloning, written by Container::__clone), not a parameter. Standalone-cloning a child detaches it.
  • A component name cannot contain - (#^[a-zA-Z0-9_]+$#) because - is the path separator; getComponent('a-b-c') descends into sub-containers.
  • Components cannot be serialized (__serialize throws by design).
  • getComponent() return-type inference lives in nette/phpstan-rules (GetComponentReturnTypeExtension), not in phpDoc here - look there for types.