Download the PHP package openapi-tools/generator-utils without Composer

generator-utils

Shared nikic/php-parser utilities for OpenAPI Tools code generators.

Installation

To install via Composer, use the command below, it will automatically detect the latest version and bind it with ^.

This package is typically pulled in as a dependency of generator packages such as generator-schema and generator-hydrator. You can also require it directly when building custom FileGenerator implementations.

Requirements

• PHP ^8.4
• openapi-tools/representation for type resolution helpers
• openapi-tools/utils for File, ClassString, and related value objects
• nikic/php-parser for AST construction and pretty-printing

Components

Usage

All builder classes expose static factory methods that return PhpParser\Node instances. Pass them to a PhpParser\PrettyPrinter\Standard (or another pretty printer) to inspect or embed generated code, then wrap the result in an openapi-tools/utils File for writing.

The examples below use $printer = new PhpParser\PrettyPrinter\Standard() to show the PHP that each method produces.

FileStringyfier

toString(File $file): string

Converts a File to its on-disk representation. String contents are returned unchanged (with a trailing newline). AST contents are pretty-printed and prefixed with declare(strict_types=1);.

Builder\DocBlockBuilder

fromLines(array $lines): string

Builds a PHPDoc block from plain text lines. Each line is prefixed with * automatically.

fromDocLines(array $lines): string

Like fromLines(), but strips existing /** and */ markers from each line first. Useful when collecting lines that may already be partial docblocks.

Builder\ExpressionBuilder

Method arguments accept variable names as strings, Expr nodes, or Arg instances.

var(string $name): Expr\Variable

Creates a $variable reference.

thisProperty(string $name): Expr\PropertyFetch

Creates a $this->property fetch.

thisMethod(string $method, array $arguments = []): Expr\MethodCall

Creates a $this->method(...) call. String arguments are treated as variable names.

methodCall(Expr $receiver, string $method, array $arguments = []): Expr\MethodCall

Creates a method call on an arbitrary receiver expression.

classConstant(string $className, string $constant = 'class'): Expr\ClassConstFetch

Creates a class constant fetch, defaulting to ::class.

objectClassConstant(string $variable, string $constant = 'class'): Expr\ClassConstFetch

Creates a $variable::class fetch for runtime class name resolution.

arrayFetch(string|Expr $array, string $key): Expr\ArrayDimFetch

Creates an array offset fetch with a string literal key. Pass a variable name as a string or an Expr as the array.

arrayFetchKey(string|Expr $array, Expr $key): Expr\ArrayDimFetch

Creates an array offset fetch with a dynamic key expression.

identical(Expr $left, Expr $right): Expr\BinaryOp\Identical

Creates a strict equality comparison (===).

andAll(array $conditions): Expr

Combines two or more expressions with &&.

orAll(array $conditions): Expr

Combines two or more expressions with ||.

nullSafe(Expr $value, Expr $nonNull): Expr\Ternary

Creates a null-coalescing-style ternary: $value === null ? null : $nonNull.

null(): Expr\ConstFetch

Creates a null literal.

true(): Expr\ConstFetch

Creates a true literal.

false(): Expr\ConstFetch

Creates a false literal.

literalString(string $value): Scalar\String_

Creates a string literal.

literalInt(int $value): Scalar\LNumber

Creates an integer literal.

invoke(Expr $callable, array $arguments = []): Expr\FuncCall

Invokes a callable stored in a variable.

funcCall(string $function, array $arguments = []): Expr\FuncCall

Creates a global function call.

newInstance(string $className, array $arguments = []): Expr\New_

Creates a new ClassName(...) expression.

newRuntimeException(string $message): Expr\New_

Creates a new \RuntimeException('message') expression.

throwRuntimeException(string $message): Stmt\Expression

Creates a throw new \RuntimeException('message'); statement.

throwNew(string $className, array $arguments = []): Stmt\Expression

Creates a throw new ClassName(...); statement.

catchThrowable(string $throwableVariable, string $errorVariable): Stmt\Catch_

Creates a catch block that assigns the caught throwable to a second variable.

lazyInitIfNotInstance(string $propertyName, string $className, array $constructorArguments = []): Stmt\If_

Creates an if block that lazily initializes a $this->property when it is not yet an instance of the given class.

returnProperty(string $propertyName): Stmt\Return_

Creates a return $this->property; statement.

args(array $arguments): array

Normalizes a mixed argument list to Arg objects. Strings become variable references; Expr nodes are wrapped; existing Arg instances pass through unchanged.

Builder\StatementBuilder

assign(string|Expr $variable, Expr $value): Stmt\Expression

Creates an assignment statement. The variable may be a name or an expression (for example $this->mapper).

yieldMapOverIterable(string $iterableVariable, string $itemVariable, string $indexVariable, string $methodName, array $methodArguments = []): Stmt\Foreach_

Creates a foreach that yields $index => $this->method(...) for each item. Used by hydrator generators for batch operations.

tryReturnIgnoringThrowable(Stmt\Return_ $return): Stmt\TryCatch

Wraps a return statement in a try/catch that swallows any \Throwable.

throwVariable(string $variable): Stmt\Expression

Creates a throw $variable; statement.

returnMethodCall(string $variable, string $method, array $arguments = []): Stmt\Return_

Creates a return $variable->method(...); statement.

Builder\MatchBuilder

onVariable(string $variableName, array $arms, Expr ...$default): Expr\Match_

Creates a match on a variable. Each arm has a conditions list and a body expression. Pass a default body as a variadic argument after the arms.

onClassNameStrings(string $variableName, array $arms, Expr ...$default): Expr\Match_

Creates a match on a class name string. Each arm maps one or more class name strings to a body expression. This is the pattern used by hydrator dispatch.

Builder\HydrationBuilder

hydrateCall(string $className, Expr $data, Expr $receiver, string $method = 'hydrate'): Expr\MethodCall

Creates a hydrator method call that passes a class constant and data payload to a receiver.

Builder\NamespaceBuilder

namespaceNode(string $namespace, Node ...$statements): Node\Stmt\Namespace_

Wraps one or more AST statements in a namespace node.

classFile(string $pathPrefix, ClassString $className, Node $classNode, bool $loadOnWrite = File::DO_LOAD_ON_WRITE): File

Builds a File with the correct path prefix, FQCN, namespace-wrapped class node, and load-on-write flag.

Type\UnionTypeUtils

Type helpers operate on openapi-tools/representation Namespaced\Property\Type objects.

buildUnionType(Namespaced\Property\Type $type): string

Flattens union type nodes into a deduplicated PHP type string.

getUnionTypeSchemas(Namespaced\Property\Type $type): iterable

Yields every Namespaced\Schema referenced in a union, including nested unions. Generators use this to emit cast helpers for schema-backed union properties.

Type\PropertyTypeResolver

resolve(Namespaced\Property $property, DocBlockTag $docBlockTag = DocBlockTag::Property): ResolvedPropertyType

Resolves a representation property to type hints, a nullable prefix, and an optional docblock line.

Use DocBlockTag::Property for promoted properties and class docblocks. Use DocBlockTag::Param for constructor parameters. Array properties receive generic docblock annotations when the element type can be resolved, for example array<\\Vendor\\Schema\\Item> or array<string|int>.

Type\ResolvedPropertyType

typeHint(): string

Returns the combined nullable prefix and type hints as a single PHP type string suitable for Param::setType().

Type\DocBlockTag

Selects which PHPDoc tag PropertyTypeResolver::resolve() emits:

• DocBlockTag::Property — @property lines for class and promoted property documentation
• DocBlockTag::Param — @param lines for constructor parameter documentation

Contributing

Please see CONTRIBUTING for details.

License

The MIT License (MIT)

Copyright (c) 2026 Cees-Jan Kiewiet

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.