PHPStan

At a glance

NextPDF Enterprise ships a custom PHPStan rule, EditionBoundaryRule, that flags use imports which cross the Core → Pro → Enterprise edition boundary. It is a developer-facing static check that reports violations; it analyzes import statements and does not guarantee correctness of your code.

Availability & licensing

This capability ships in NextPDF Enterprise (nextpdf/enterprise) and activates with an Enterprise-tier license envelope. It is a build-time PHPStan rule registered through your PHPStan configuration, so it runs during static analysis and has no runtime path; the license gate is the nextpdf/enterprise package boundary, with no separate per-feature capability code. Compare editions and get a license.

Install

composer require nextpdf/enterprise:^3

Register the rule in your PHPStan configuration:

rules:
    - NextPDF\Enterprise\PHPStan\EditionBoundaryRule

Conceptual overview

The rule inspects each use statement and compares the importing namespace against the imported symbol’s namespace prefix. It enforces a one-directional dependency order:

• Core code (NextPDF\, excluding the Pro and Enterprise sub-namespaces) must not import from NextPDF\Pro\* or NextPDF\Enterprise\*.
• Pro code (NextPDF\Pro\*) must not import from NextPDF\Enterprise\*.
• Enterprise code (NextPDF\Enterprise\*) is the top tier and may import from any of them.

When an import crosses the boundary, the rule reports an error with the identifier nextpdf.editionBoundaryViolation and a message naming the importing namespace, the forbidden prefix, and human-readable edition labels. The check is purely static: it reads the import graph at analysis time.

Why it works this way

The rule reasons about use statements at analysis time, not at runtime, because the edition boundary is an architectural invariant rather than a runtime decision. Core, Pro, and Enterprise ship as separate packages, so a lower tier must never depend on symbols absent from a smaller install. Catching a boundary-crossing import during static analysis fails the build before the mistake ships. The alternative is worse: the same import surfaces later as a fatal missing-class error in a Core-only deployment. The order is deliberately one-directional, Core → Pro → Enterprise, mirroring how the open-core packages layer on top of each other. Enterprise stays unconstrained because it is the top tier and may reference every edition below it.

Design background: Open core, no lock-in.

API surface

Class	Responsibility
EditionBoundaryRule	PHPStan rule over use statements; reports edition-boundary violations.

The rule implements the standard PHPStan Rule contract over the Use_ node type and emits errors under the nextpdf.editionBoundaryViolation identifier.

Code sample — Quick start

# phpstan.neon
includes:
    - vendor/nextpdf/enterprise/phpstan.neon.dist

Code sample — Production

# phpstan.neon
rules:
    - NextPDF\Enterprise\PHPStan\EditionBoundaryRule

parameters:
    level: 9
    paths:
        - src

A violation appears in PHPStan output as, for example: an Enterprise import inside Core code is reported as an edition-boundary violation on the offending use line, under nextpdf.editionBoundaryViolation.

Edge cases & gotchas

• The rule reasons about the analyzed file’s namespace and the imported symbol’s prefix. Code in a non-NextPDF\ namespace is not constrained by this rule.
• Enterprise namespaces are unrestricted by design; the rule never flags an Enterprise file for importing Pro or Core.
• The rule analyzes use statements. A fully-qualified class reference written inline without a use is outside this rule’s scope; prefer imports so the boundary is enforced.
• The check is static and advisory: it reports boundary violations. It does not prove your program is otherwise correct.

Performance

The rule runs per use statement during PHPStan analysis and performs string-prefix comparisons. Its overhead is proportional to the number of import statements and is negligible relative to overall analysis time.

Security notes

This is a static-analysis rule. It executes at build time within PHPStan, reads source structure only, and has no runtime effect on generated PDFs.

Data residency & PII mitigations

The rule processes source code at analysis time and handles no document or personal data.

Safe telemetry & log scrubbing

Rule output is PHPStan diagnostics. It contains namespaces and symbol names from your own code; treat analysis logs with the same care as your source.

Conformance

No standards conformance is claimed. This is a developer tooling rule that enforces an internal architectural constraint (edition layering) in downstream builds.

FIPS-mode behavior

Not applicable; the rule performs no cryptographic operations and has no runtime path.

Threat model

Not a runtime component. The rule’s purpose is to catch an architectural mistake — an edition-boundary import — before it ships, by failing the static-analysis stage.

Behavior contract

• The rule inspects each use statement and enforces a one-directional dependency order: Core must not import Pro or Enterprise; Pro must not import Enterprise; Enterprise may import any.
• A boundary-crossing import is reported under the nextpdf.editionBoundaryViolation identifier with the importing namespace and the forbidden prefix.
• Code in a non-NextPDF\ namespace is not constrained by this rule.
• A fully-qualified inline class reference without a use is outside this rule’s scope; prefer imports so the boundary is enforced.

Publication boundary

This page documents externally observable behavior and the supported public API surface only. Internal namespace paths, helper classes, mechanism tables, runbook filenames, and ticket prefixes are out of scope.

Core fallback

NextPDF Core does not ship an edition-boundary PHPStan rule. A Core-only consumer that wants edition layering enforced in its own build must write or source an equivalent rule itself.

Pro fallback

NextPDF Pro does not ship the edition-boundary PHPStan rule; it is part of the nextpdf/enterprise package only. A Pro-only deployment has no Enterprise component to register this rule from. See the Enterprise overview for the Enterprise surface.

Enterprise boundary note

Internal mechanism detail stays in the source repository’s internal documentation and is out of scope for this manual.

Deployment boundary

This is a build-time static-analysis rule. It executes inside PHPStan during analysis, reads source structure only, and has no runtime effect on generated PDFs or on any deployed service. Registering it and choosing the PHPStan level are the integrator’s responsibility.

Legal-compliance boundary

This page describes a developer-tooling static-analysis rule. It makes no compliance, certification, or correctness guarantee about your code; it reports edition-boundary import violations only and is advisory. It does not constitute legal advice. Judging whether your build meets your own architectural or contractual obligations is your responsibility.

See also

• PHPStan — Deep Reference
• Enterprise overview
• Core vs Pro vs Enterprise feature matrix