Writing good WebEngine code

[g105b]

Over the last few weeks I've had the pleasure of working with some developers who were new to WebEngine, and it's always fulfilling to see their delight at the simplicity of some things. There are, however, many common pitfalls that are fell into over and over. I've written this guide to help guide human developers, and automated tooling, to writing good quality WebEngine code. It's a bit long, and definitely not designed for bedtime reading, but hopefully it helps someone increase their code quality over time.

I will add to this as and when, and once I'm happy with it it will go into https://github.com/phpgt/WebEngine/wiki/Coding-styleguide

---

Build practical WebEngine applications whose behaviour can be followed directly from HTML to page logic, owning classes and persistence. Good structure supports that traceability; architectural complexity is never a goal.

Scope and architectural judgement

• By default write direct, practical WebEngine code. Build the working page or flow first; do not optimise its architecture as you write it. Keep small pieces of markup and view orchestration inline, including simple headings and breadcrumbs.
• Extract a class or component only for a demonstrated need: substantial repeated behaviour, independently testable business rules, state management, or a chunk whose extraction clearly makes the calling code easier to understand. "Possible" future reuse, avoiding a few duplicated lines, or having a name for something is not enough justification for extracting into a component.
• Preserve strong typing, tests and clear ownership of business rules without adding layers around routine page work. A little obvious duplication is better than an abstraction that makes the reader jump between files to follow a simple operation. Refactor when the existing code presents a concrete problem.
• Before changing an area, read its implementation, representative tests and relevant framework APIs. Follow established project patterns and the maintainer's recent edits. Consult framework source/examples when lifecycle or API behaviour is unfamiliar; do not invent a replacement based on an assumption.
• Every new file, dependency, cache, fallback, compatibility path or configuration option must solve an identifiable current requirement. Do not prepare extension points or support hypothetical old data, clients or future features without evidence that the compatibility is needed.
• Complete one coherent feature or refactor, including its cleanup, before expanding scope. Surface material assumptions early and resolve routine implementation choices independently. Do not make the maintainer discover routine quality problems or require approval of every small implementation decision.

Readability and ownership

• Use double quotes for strings by default. Use single quotes when they avoid distracting escaping, such as embedded HTML or regular expressions.
• Separate logical steps and control-flow blocks with blank lines. Use explicit block bodies rather than compressed one-line conditionals.
• Code should be immediately skimmable: use clear names and straightforward control flow instead of dense ternaries, hidden logic or unnecessary layers.
• Comments explain a reason, constraint or trade-off that the code cannot make obvious on its own. Avoid narration, nested ternaries, boolean mode switches and hidden side effects. Split dense checks into readable control flow.
• Every class should have an obvious purpose, and each purpose should have an obvious home. Name classes for the responsibility they own; use injected instances for shared behaviour rather than disposable action wrappers or catch-all classes built for hypothetical future actions. A general class name does not justify collecting unrelated behaviour.
• Put behaviour in the existing class responsible for it. Do not introduce forwarding services or classes for individual actions; extract them only when a concrete problem warrants it. For example, there's no need for a AuthService if there's already a class that deals with authentication - just use it directly.
• Check the library's existing API before adding an application subclass or adapter. A private helper for repeated work in its owning repository is often enough; do not replace framework services just to add a convenience method. Test our application behaviour rather than re-testing framework internals or routine service wiring already exercised by the browser flows. Use existing connection transaction APIs rather than an application database subclass and replacement service wiring.

WebEngine page logic and components

• When exploring, a small procedural sketch in page logic is acceptable. Before
  delivering functionality, put business rules in their existing owning classes
  in class/ and unit-test new functionality, edge cases, invalid input and
  missing data before browser integration. Simple page orchestration stays inline;
  the sketch is not a reason to introduce a class for every operation.
• Then specify the browser flow in Behat and wire it into pages/components.
• Page logic in page/ only defines go* and do_* functions. Keep these light:
  read input, orchestrate typed services, bind results and choose an HTTP response.
  Keep HTTP guards and presentation decisions here; business rules belong in
  their owning classes.
• When extraction is warranted, reusable HTML belongs in page/_component, with
  its own PHP action handlers. Small markup fragments do not need a component
  merely because they appear on more than one page.
• Make the HTML-to-handler path obvious: name="do" value="example" maps to
  do_example(). Component controls normally use their component's own handlers;
  do not assume a same-named function elsewhere will run. Check WebEngine's
  component routing and lifecycle when a form posts to another page. A generated
  __component field must not prevent a deliberate page-level submission from
  reaching its actual handler.
• Components own their semantic HTML roots. Render the custom component directly
  in its caller; put elements such as aside, nav or section inside it rather
  than adding a caller-side wrapper solely around that one component. Keep outer
  containers when they genuinely group or lay out multiple elements.
  Test page/component behaviour with Behat, not direct page-function unit tests.
• Use template binding and data-list for repeated data. Prefer one readable
  template for existing and new records to near-identical copies for each state.
  Fields may remain present but hidden in the relevant state. Read-only fields
  still need meaningful name attributes.
• Respect binding and rendering order. An enhancement that reads table rows must
  run after their data has been bound. Consult the framework lifecycle rather
  than adding caches, duplicated data attributes or guessed execution hooks.
• Put directory-wide repeating markup in nested _header.html or _footer.html
  files. These extend the outer magic header/footer; do not repeat the same
  component in every page within a directory.
• Do not add static application classes or static application methods. Construct
  small stateless helpers in page functions when useful; register reused or
  stateful services in ServiceLoader for typed parameter injection.

Types, binding and persistence

• Prefer typed data objects to associative-array structures. Lists are fine;
  adapters at library/database boundaries may translate data when necessary.
• Keep form field names identical to entity/database column names when they
  represent the same value. Prefer data-bind:value="@" (the shorthand for
  @name) instead of repeating a matching bind key. Human-readable labels can
  differ without renaming the data: a deployment's title can be shown as
  "Deployment name" without translating the field through several layers.
• Bind repository entities directly where it makes sense to. Do not create
  context, managed, panel or settings classes merely to copy fields, rename them
  and unwrap them again.
  Keep small presentation calculations, select options, disclosure state and
  rejected form values in the component's binding callback. Use existing binder
  callbacks before creating a view-model class. A distinct projection must solve
  a real transformation or business requirement, not keep duplicate shapes in sync.
• Give each application table and its model entity the identical PascalCase
  name, including in migrations, queries and fixtures. Entity properties reflect
  the table's columns, types and nullability. Preserve persisted values during
  hydration; apply display fallbacks in presentation code. Keep UI projections
  distinct from entities. Do not add ORM dependencies,
  mapping attributes or persistence abstractions before ORM integration is needed.
• Declare repositories readonly, and use readonly class for other classes
  whose properties remain fixed after initialisation. This expresses the intent
  of services as doers with fixed dependencies; they can still update the
  database, session or other objects they hold. Readonly value objects are useful
  too. Remove redundant property-level readonly inside a readonly class.
  Keep classes mutable when their own properties change, and respect inherited
  framework constraints. Do not introduce state wrappers just to obtain readonly.
• Depend on the library's declared interfaces when they provide the operations
  needed. Use the canonical namespace casing declared by the installed package
  (GT for migrated PHP.GT libraries); do not depend on compatibility aliases.
  Do not add subclasses, casts or state wrappers to conceal a misunderstood API.
• Repository getBy* lookups return nullable objects; handle absence explicitly
  at the caller. Alternate-key lookups use
  a single-row getIdBy*.sql query with fetchString/fetchInt, then delegate to
  the canonical ID lookup rather than duplicating object hydration.
• Keep creation, reading, updating and deletion in the repository responsible
  for those entities rather than adding separate action wrappers. Return useful
  values from application services (for example, a redirect Uri) and perform
  the HTTP redirect in page logic.
• Use explicit method names instead of boolean arguments that select unrelated
  actions. A single-method class is not inherently wrong, but its responsibility
  must justify the class beyond giving a function a name.
• Persist application functionality in the database. When tables or columns are
  missing, add a numbered SQL migration in query/_migration/ and run gt migrate.
  Do not substitute session-only demo behaviour for persistence.

Auditing and security

• Audit user actions through the class responsible for auditing, with an
  authenticated or anonymous actor and concise changed values for state changes.
  Do not add separate forwarding services or payload classes without a concrete
  need. Never record credentials, including passwords, API secrets, ciphers or session IVs.
  Commit application mutations and their audit records together. Cover audit rows,
  rejected input and audit-write failures in unit tests and the browser flow.
• Record requests and business events at their proper level. Request auditing
  should be concise; do not create a generic diff factory or copy entire request
  payloads into every event. Mutation records identify the entity, actor and
  meaningful from/to changes without repeating unchanged snapshots or nesting
  redundant envelopes. Keep auditing in its owning class instead of adding
  forwarding services, action wrappers or payload classes.
• Resolve the authenticated audit actor before clearing authentication state.
  Across client/provider boundaries, identity must come from authenticated data
  and be checked against its deployment; a plain user ID in a query string is not
  proof of identity. Do not assume the provider retains a session after sign-in.

HTTP flows, forms and progressive enhancement

• Build HTTP-first HTML/forms. JavaScript must be minimal. Flux is progressive
  enhancement after the plain HTTP behaviour works.
• A redirect is navigation, not a request to replay the originating action.
  After a logout or other completed POST action, return to an ordinary GET
  destination. Do not append action parameters such as do=logout that re-enter
  a client's handler and create a loop. Preserve intentional destination paths,
  queries and fragments without introducing new actions.
• Define form field constraints in HTML using required, input type, pattern,
  minlength/maxlength, ranges and steps as appropriate. Validate the same form
  server-side with phpgt/domvalidation before performing mutations. Do not
  maintain a second set of field-format or length rules in PHP classes.
  Use labels and title hints to explain constraints, and show server errors at
  the submitted form without discarding its values. PHP still enforces ownership,
  permissions and other business rules that HTML cannot express.
• Reject malformed input shapes, including arrays where a scalar is expected,
  before mutation. Classes may normalise validated values; ownership, permissions,
  uniqueness and other business rules remain in their owning PHP classes.
• Keep validation patterns readable and limited to supported inputs. Document
  reasonable assumptions instead of encoding an entire networking specification
  in a pattern. Add complex formats such as IPv6 only when required. Patterns
  must work in both HTML and DomValidation.
• Test both native browser rejection (no request sent) and server rejection when
  browser validation is deliberately bypassed. Check library/browser parity for
  relevant edge cases such as Unicode lengths and the string "0". Fix validation
  library defects in the library, rather than adding application workarounds.
  Repeating form templates are extracted before handlers run; retrieve the
  canonical form through ListElementCollection when validating a data-list.
• Keep rejected values, the submitted disclosure open and accessible feedback
  at the submitted form. Make the error visible and focusable where appropriate.
  A validation failure must not silently discard input or appear to do nothing.
• Preserve native links, forms and keyboard navigation when enhancing HTML.
  Derive enhancements from existing markup rather than duplicating link targets
  in extra attributes. Generated duplicate links must not add extra tab stops.
• Enhancements must not wrap existing links, buttons or other interactive
  controls inside new links. Generated duplicate table links use tabindex="-1";
  preserve the original link as the keyboard entry point.

Shared design and accessible controls

• Put shared control styling in the design library, with theme-specific values
  in the theme. Reuse its patterns before adding local CSS. Cover normal, hover, focus, active
  and disabled states with readable contrast, including primary controls.
  Fix cascade/specificity problems rather than adding !important. Prevent
  initial-render flashes and layout jumps with HTML/CSS before Flux runs, while
  preserving usable controls without scripting.
• Shared behaviour means one implementation. All instances of a spinner,
  including temporary previews, share geometry, animation and reduced-motion rules.
  Fix a CSS/rendering problem in that shared code instead of creating a separate
  variant or editing/generating replacement SVGs to compensate for it. Preserve
  supplied icon assets unless an asset change is explicitly requested.
• Group form-ending buttons in an .actions container using the design library's
  shared spacing: the top space should match an input caption's line height and gap.
  Keep single panels at a readable maximum width; use responsive layouts that
  preserve the meaningful HTML order. Use native exclusive
  disclosures when only one item should be open.
• Preserve meaningful DOM and keyboard order when changing visual layout. Keep
  the intended Save/Continue submit button first so Enter submits that action;
  position secondary or delete controls with CSS rather than moving them ahead
  of the default submit button in HTML. Icon-only controls retain an accessible
  name through screen-reader text and use the shared icon-button pattern.

Honest functionality and destructive actions

• Do not present scaffolding as working functionality. Remove obsolete demo
  handlers, fake records, unused dependencies and their tests when real behaviour
  replaces them; clearly mark unfinished controls as unavailable.
• A label, placeholder or renamed checklist item is not implemented behaviour.
  Define what observable event completes a milestone, including production and
  development exclusions, then persist and audit it. Do not infer completion
  from an unrelated setting or confuse a development exemption with a completed
  production milestone. Be explicit about whether earlier events can be recognised; do not invent or
  backfill historical success without reliable evidence.
• Use domain terms consistently without conflating distinct values. Application
  identity is user-facing; a deployment label identifies an environment. Keep
  those meanings distinct even when their current strings happen to match.
• Destructive controls use a shared confirmation dialog naming the saved entity.
  Keep an HTTP confirmation fallback and require confirmation for the same
  specific target on the server before deleting. Cancel and Escape must never
  perform a deletion.

Tests and database isolation

• Behat must not alter the development database's lasting state. Stateful tests
  snapshot their database, apply dev-only fixtures in
  test/behat/database/<state_name>, and restore after the run, including failures.
• Keep unit tests in test/phpunit and browser flows in test/behat. Reuse
  existing Behat steps and describe observable behaviour using meaningful UI
  elements, such as the application switcher, rather than incidental fixture
  words. Test real routes, persistence and audit records rather than a simulated
  backend. Check HTTP and Flux behaviour where enhancement affects the flow.
• Browser waits must establish the actual completed transition: expected route,
  relevant content or a completed request. A shared sidebar appearing does not
  establish that a redirect chain or background form submission has finished.
  Fix the observed timing condition instead of masking races with arbitrary
  sleeps or retries that can conceal a real failure.
• Give each tested class one unit test class named exactly XTest, where X
  is the class name. Mirror the source namespace/directory. Consolidate tests
  by class, not by purpose: test AdminArea in AdminAreaTest, never in a
  separate AdminAreaSecurityTest or LogoutTest.
• Name test methods test + the tested method in PascalCase, optionally followed
  by _ and a descriptive context: testLogout, testLogout_newSession, or
  testLogout_invalidSessionShouldThrow. Use testConstruct for constructors.
  Name data providers and fixture helpers for the data they provide; they do
  not use the test prefix.
• Each unit test invocation has one system under test, always named $sut.
  Keep its construction, exercise and assertions easy to follow. Use data
  providers for cases needing different subject instances rather than replacing
  $sut or constructing subjects in a loop. Assert the subject's behaviour,
  not several unrelated classes' behaviour in one test. Several assertions may
  establish one result; one system under test does not mean one assertion.
• Use stubs for collaborator responses and mocks for interactions that matter
  to the behaviour. Keep real value objects when their values are needed; avoid
  unnecessary databases, transports or application services in unit fixtures.
  Preserve checks that require actual SQL, files or several services in the
  separate test/integration PHPUnit suite, included in composer test.
  Class-based integration tests may mirror the corresponding unit-test class
  names under their own namespace. Existing page-function integration checks
  are retained there; write new page/component coverage in Behat.
• Keep composer test green with PHPUnit, Behat, PHPCS, PHPMD and PHPStan. When
  simplifying code, update tests to protect supported behaviour; do not restore
  unnecessary implementation just to satisfy an obsolete test.
• Use the newest supported PHPUnit version for the test bed. Keep checks
  proportionate to the change and choose tests for their ability to catch a
  concrete defect, not to increase a count or preserve discarded architecture.
• Before adding a test, identify the application defect it would catch. Avoid
  tests that repeat assignments, demonstrate framework behaviour or check routine
  service wiring already exercised by real flows. Test count is not a measure
  of useful coverage.

Verification, dependencies and review

• Verify environment-dependent assumptions directly: use MySQL for MySQL-specific
  schema behaviour, a browser for rendering and initial-paint behaviour, and the
  built/installed assets for package changes. State what the checks establish
  and any material limits; a substitute environment passing is not proof of
  behaviour it cannot reproduce.
• Reproduce a reported defect before choosing a fix. Compare a working example
  under the same runtime conditions, inspect the actual output and establish a
  cause. Do not successively guess at CSS sizes, origins or other settings and
  present each guess as a verified fix.
• Visual and animation changes require browser inspection of the real rendered
  page. Check relevant viewport sizes and themes; inspect initial paint for
  flashes and frame-by-frame output for blur or movement when necessary.
  Functional browser assertions and a passing asset build do not establish that
  an animation looks correct. State any visual checks still outstanding.
• Inspect the implementation actually executing: the consumer's Composer
  constraints, lockfile, installed vendor code and built/installed npm assets,
  not merely a sibling source checkout. Verify the complete integration contract:
  parameter names and meanings, encryption, redirects, session persistence and
  cookie flags in the actual HTTP/HTTPS environment. Do not add speculative
  backwards compatibility to paper over mismatched client/provider versions.
• Prefer the smallest dependency update that supplies the required fix, retaining
  unrelated locked versions. Update affected build commands and configuration,
  then check that the configuration is actually honoured at runtime. Fix library
  defects in the owning library instead of committing vendor edits or creating
  application adapters around them.
• Clarify material contract ambiguities using concrete inputs and outputs before
  changing behaviour. For DNS, distinguish the zone, record name, fully qualified
  lookup name and TXT value. For client protocols, distinguish application IDs,
  deployment IDs, destinations and action parameters. Do not guess which value
  the maintainer meant or silently swap their meanings.
• Keep bulk refactors targeted. Use syntax-aware edits where appropriate and
  inspect changes across SQL, PHP, templates, selectors, fixture values and prose.
  Matching text is not necessarily the same identifier or responsibility. A
  replacement count or green test run does not establish a correct refactor.
• Before declaring completion, review the complete diff of your work as a
  maintainer would, preserving unrelated existing edits. Check for unnecessary
  files and layers, duplicated responsibilities, misleading names, dense logic,
  stale references, obsolete code and convention violations. Remove problems
  found during this review, run the checks appropriate to the final changes,
  and report the result. Passing tests alone does not make the work complete.