evolvephp / dev-tools
Development-time generators and tooling for EvolvePHP 2 applications.
Requires
- php: ^8.4
- ext-tokenizer: *
- evolvephp/contracts: ^2.0
- evolvephp/core: ^2.0
- evolvephp/module: ^2.0
- evolvephp/plugin: ^2.0
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-16 14:47:55 UTC
README
Development-time generators and tooling for EvolvePHP 2 applications.
This package remains development-only.
Package
evolvephp/dev-tools
Requirements
PHP ^8.4 with ext-tokenizer.
Dependencies
evolvephp/contracts, evolvephp/core, evolvephp/module, evolvephp/plugin
Adoption Planning
The package provides public experimental adoption-planning models under
Evolve\DevTools\Adoption.
An AdoptionPlan records explicit maintainer migration decisions for one
bounded capability at a time. Its MigrationManifest records the selected
capability, whether the capability is intended for embedded or remote
integration, route ownership transitions, data ownership transitions,
migration/source-of-truth states, compatibility requirements and
identity/security requirements. Sidecar deployment is represented as a
deployment form of remote mode rather than a separate integration mode.
Route declarations record current and target route owners. Data declarations record current and target stores, current and target authoritative writers, current and target migration states and any declared temporary synchronization. The ownership vocabulary prevents modelling two uncontrolled authoritative writers for the same data declaration.
The plan records migration evidence, rollback evidence and measurable acceptance criteria in caller-declared order. These are declarations for planning and review; construction does not certify that the evidence is valid, rollback is possible, acceptance criteria have been met or cutover is safe.
Current limitations: adoption planning has no automatic plan generation from Audit, route discovery, ownership inference, migration scoring, compatibility certification, migration-readiness certification, Bridge implementation, Bridge protocol, adapter, database synchronization, cutover execution or rollback execution.
Database Capability Advisor
The package provides public experimental database-family guidance models under
Evolve\DevTools\Database.
DatabaseCatalog::builtIn() exposes a deterministic catalogue of exactly
thirteen database families, their family-level capabilities, example engines
and trade-offs. Custom catalogs are supported by constructing DatabaseCatalog
with explicit DatabaseFamilyDefinition values.
DatabaseAdvisor evaluates explicitly supplied DatabaseWorkloadProfile
instances against an explicit catalogue and returns structured DatabaseAdvice
with recommendations, alternatives and disqualified families. Advice is
explainable through per-family DatabaseFamilyAssessment values that record
matched required capabilities, missing required capabilities, matched preferred
capabilities, missing preferred capabilities and conflicting excluded
capabilities. Required capabilities are hard gates, excluded capabilities are
hard conflicts, and preferred score is only the count of matched preferred
capabilities. Equal recommendation scores remain explicit ties ordered
deterministically.
A capability means representative systems in that family are commonly suited to that workload characteristic. It does not mean every product belonging to the family guarantees that capability. Example engines are documentation and guidance data only; they are not Composer dependencies.
The advisor is deterministic and static-input driven. It does not inspect the
running application, inspect infrastructure, detect installed database drivers,
inspect SQL, query vendors, use runtime telemetry, perform network lookup, apply
hidden weights, rank products by popularity, price or cloud provider, install
databases, configure databases, migrate databases, switch databases, mutate
infrastructure, provide a universal CRUD/query/database API, certify product or
version compatibility or combine multiple workload profiles into a composite
score. This slice has no database:recommend command or other CLI adapter.
adviseMany() evaluates multiple explicit workload profiles independently for
polyglot-persistence planning.
Audit Foundation
The package provides a public experimental Audit foundation under
Evolve\DevTools\Audit.
AuditRunner accepts explicitly supplied inspectors and an explicit target
project root. It performs no automatic discovery. ComposerProjectInspector
inspects only the target root composer.json; it does not scan parent
directories, nested manifests, lock files or transitive dependency graphs.
ComposerLockInspector inspects only the target root composer.lock for
resolved lockfile evidence. PhpSourceCouplingInspector discovers PHP source
files below the explicit project root and tokenizes source text with PHP's
native tokenizer. PhpSourceStructureInspector reports lexical namespace and
named-declaration structure from those discovered PHP source files.
Audit treats the target project as data. It does not include target PHP files,
include the target vendor/autoload.php, bootstrap Laravel, Symfony, CakePHP,
Yii, EvolvePHP or custom application code, run Composer, run scripts, invoke
shell commands, load .env, write caches or modify target files.
The Composer inspector reports structured findings for root Composer evidence:
direct runtime and development dependencies, direct framework package evidence
for Laravel, Symfony, CakePHP, Yii and EvolvePHP, the raw root require.php
constraint when present, missing PHP constraint evidence, malformed Composer
evidence and config.platform.php review evidence.
It also reports root autoload and autoload-dev metadata for PSR-4, PSR-0,
classmap and files sections as raw Composer evidence. Runtime PSR-4 namespaces
and runtime autoload files may produce modernization review signals, while
development autoload metadata remains evidence only.
The Composer lockfile inspector reports deterministic read-only evidence for locked runtime and development package inventory, raw locked versions, locked package requirement edges, PHP, extension, library and Composer platform requirements, Composer-plugin package metadata and lockfile-declared abandoned package metadata. Runtime and development lockfile sections remain separate, and malformed entries produce incomplete evidence without erasing valid sibling package evidence.
The PHP source inspector reports structured findings for source inventory,
direct superglobal access, direct $_SESSION coupling, $GLOBALS, global
statements, static-state declarations, static-property access and a bounded
catalogue of runtime-call hazard review evidence. The runtime-call catalogue is
limited to direct lexical evidence for session_start(), selected
process-global mutation calls, response/output side-effect calls and constructs,
process-lifetime callback registration, process termination, eval and
include/require constructs. Source paths are reported relative to the target
root with / separators. Findings aggregate deterministically sorted lexical
evidence and report incomplete inspection when a source file cannot be read
safely.
The PHP source structure inspector reports namespace declarations and named classes, interfaces, traits, enums and functions using PHP's native tokenizer. Non-empty namespaces with named declarations may produce namespace-group review signals, and global named declarations or files with multiple namespace declarations are reported for human review.
Raw Composer constraints and raw locked versions are preserved exactly as
declared. Audit does not solve Composer SemVer constraints, execute Composer,
query live vulnerability or package registries, verify lock freshness or
content hashes, certify composer.json to composer.lock consistency, or claim
PHP, package, framework, lockfile or Bridge compatibility from raw evidence. A
Composer platform override is reported as compatibility-review evidence only;
it is not proof of the actual runtime PHP version.
Audit can be used through the standalone evolve-audit binary against an
explicit existing PHP project root without migrating that project to EvolvePHP
first:
evolve-audit <target-root> evolve-audit <target-root> --format=text evolve-audit <target-root> --format=json
Text output is the default. JSON output uses schema version 1 and contains
the stable top-level shape:
{
"schema_version": 1,
"findings": []
}
Warning and Risk findings are review evidence and do not themselves make the
command fail; invalid command usage and invalid target roots return usage
errors. The tool requires its own PHP ^8.4 runtime, while the target project
may use an older PHP version because target code is read as source text and
metadata only.
Current limitations: Audit has no remediation, vulnerability lookup, AST analysis, control-flow analysis, data-flow analysis, framework bootstrap analysis, route discovery, data ownership discovery, migration scoring, automatic migration plan, compatibility certification or Bridge integration. Autoload mappings and namespaces are structural review hints, not proven module or capability boundaries. Lockfile evidence is recorded dependency metadata only; it does not prove dependency compatibility, freshness or security status. Lexical PHP source evidence does not prove runtime incompatibility, persistent-worker unsafety, Bridge compatibility status, unsafe mutability, modernization feasibility, migration readiness or whether a detected occurrence actually executes. Include and require evidence records the construct and source line only; Audit does not resolve, classify, inspect or follow included paths.
Generator Commands
The package provides two public experimental command adapters:
Evolve\DevTools\Console\ModuleNewCommandEvolve\DevTools\Console\PluginNewCommand
The commands are caller-registerable and receive an explicit project root. They
generate application-owned module and plugin starter files from one ASCII
StudlyCase name token. Billing becomes the component identifier app/billing;
AuditLog becomes app/audit-log.
The commands do not discover components, edit Composer manifests, execute
generated PHP, run Composer, run Git, auto-enable generated components or inspect
application state beyond the derived output paths. Invalid usage writes only to
stderr and returns exit code 2. Existing output files are refused before any
new target is written.
Publication Status
EvolvePHP 2 is pre-release. This package is not yet independently published, and the current canonical source is the EvolvePHP monorepo:
https://github.com/josiahking/evolvephp
Installation
Independent Composer installation guidance will be added when package publication begins.
Licence
BSD-3-Clause. See LICENSE.md.