Nette Documentation Preview

syntax 
Nette PhpGenerator
******************

<div class=perex>
Are you looking for a tool to generate PHP code for classes, functions, or complete files?

- Supports all the latest PHP features (like property hooks, enums, attributes, etc.)
- Allows you to easily modify existing classes
- Output compliant with PSR-12 / PER coding style
- Mature, stable, and widely used library
</div>


Installation
------------

Download and install the library using the [Composer|best-practices:composer] tool:

```shell
composer require nette/php-generator
```

For PHP compatibility, see the [#compatibility table].


Classes
-------

Let's start with an example of creating a class using [ClassType |api:Nette\PhpGenerator\ClassType]:

```php
$class = new Nette\PhpGenerator\ClassType('Demo');

$class
	->setFinal()
	->setExtends(ParentClass::class)
	->addImplement(Countable::class)
	->addComment("Class description.\nSecond line\n")
	->addComment('@property-read Nette\Forms\Form $form');

// generate code simply by typecasting to string or using echo:
echo $class;
```

This returns the following result:

```php
/**
 * Class description.
 * Second line
 *
 * @property-read Nette\Forms\Form $form
 */
final class Demo extends ParentClass implements Countable
{
}
```

To generate the code, you can also use a printer, which, unlike `echo $class`, can be [further configured |#Printer and PSR Compliance]:

```php
$printer = new Nette\PhpGenerator\Printer;
echo $printer->printClass($class);
```

You can add constants (class [Constant |api:Nette\PhpGenerator\Constant]) and properties (class [Property |api:Nette\PhpGenerator\Property]):

```php
$class->addConstant('ID', 123)
	->setProtected() // constant visibility
	->setType('int')
	->setFinal();

$class->addProperty('items', [1, 2, 3])
	->setPrivate() // or setVisibility('private')
	->setStatic()
	->addComment('@var int[]');

$class->addProperty('list')
	->setType('?array')
	->setInitialized(); // outputs '= null'
```

This generates:

```php
final protected const int ID = 123;

/** @var int[] */
private static $items = [1, 2, 3];
public ?array $list = null;
```

And you can add [methods |#Method and Function Signatures]:

```php
$method = $class->addMethod('count')
	->addComment('Count it.')
	->setFinal()
	->setProtected()
	->setReturnType('?int') // return types for methods
	->setBody('return count($items ?: $this->items);');

$method->addParameter('items', []) // $items = []
	->setReference()           // &$items = []
	->setType('array');        // array &$items = []
```

The result is:

```php
/**
 * Count it.
 */
final protected function count(array &$items = []): ?int
{
	return count($items ?: $this->items);
}
```

Promoted parameters introduced in PHP 8.0 can be passed to the constructor:

```php
$method = $class->addMethod('__construct');
$method->addPromotedParameter('name');
$method->addPromotedParameter('args', [])
	->setPrivate();
```

The result is:

```php
public function __construct(
	public $name,
	private $args = [],
) {
}
```

Readonly properties and classes can be marked using the `setReadOnly()` function.

------

If an added property, constant, method, or trait already exists, an exception is thrown. Parameters, in contrast, are overwritten.

Class members can be removed using `removeProperty()`, `removeConstant()`, `removeMethod()`, or `removeParameter()`.

You can also add existing `Method`, `Property`, or `Constant` objects to the class:

```php
$method = new Nette\PhpGenerator\Method('getHandle');
$property = new Nette\PhpGenerator\Property('handle');
$const = new Nette\PhpGenerator\Constant('ROLE');

$class = (new Nette\PhpGenerator\ClassType('Demo'))
	->addMember($method)
	->addMember($property)
	->addMember($const);
```

You can also clone existing methods, properties, and constants under a different name using `cloneWithName()`:

```php
$methodCount = $class->getMethod('count');
$methodRecount = $methodCount->cloneWithName('recount');
$class->addMember($methodRecount);
```


Interfaces or Traits
--------------------

You can create interfaces and traits (classes [InterfaceType |api:Nette\PhpGenerator\InterfaceType] and [TraitType |api:Nette\PhpGenerator\TraitType]):

```php
$interface = new Nette\PhpGenerator\InterfaceType('MyInterface');
$trait = new Nette\PhpGenerator\TraitType('MyTrait');
```

Using a trait:

```php
$class = new Nette\PhpGenerator\ClassType('Demo');
$class->addTrait('SmartObject');
$class->addTrait('MyTrait')
	->addResolution('sayHello as protected')
	->addComment('@use MyTrait<Foo>');
echo $class;
```

The result is:

```php
class Demo
{
	use SmartObject;
	/** @use MyTrait<Foo> */
	use MyTrait {
		sayHello as protected;
	}
}
```


Enums
-----

You can easily create enums introduced in PHP 8.1 like this (class [EnumType |api:Nette\PhpGenerator\EnumType]):

```php
$enum = new Nette\PhpGenerator\EnumType('Suit');
$enum->addCase('Clubs');
$enum->addCase('Diamonds');
$enum->addCase('Hearts');
$enum->addCase('Spades');

echo $enum;
```

The result is:

```php
enum Suit
{
	case Clubs;
	case Diamonds;
	case Hearts;
	case Spades;
}
```

You can also define scalar equivalents and create a backed enum:

```php
$enum = new Nette\PhpGenerator\EnumType('Suit');
$enum->addCase('Clubs', '♣');
$enum->addCase('Diamonds', '♦');
```

For each case, you can add a comment or [#attributes] using `addComment()` or `addAttribute()`.


Anonymous Classes
-----------------

Pass `null` as the name, and you have an anonymous class:

```php
$class = new Nette\PhpGenerator\ClassType(null);
$class->addMethod('__construct')
	->addParameter('foo');

echo '$obj = new class ($val) ' . $class . ';';
```

The result is:

```php
$obj = new class ($val) {
	public function __construct($foo)
	{
	}
};
```


Global Functions
----------------

The code for global functions is generated by the class [GlobalFunction |api:Nette\PhpGenerator\GlobalFunction]:

```php
$function = new Nette\PhpGenerator\GlobalFunction('foo');
$function->setBody('return $a + $b;');
$function->addParameter('a');
$function->addParameter('b');
echo $function;

// or use PsrPrinter for output compliant with PSR-2 / PSR-12 / PER
// echo (new Nette\PhpGenerator\PsrPrinter)->printFunction($function);
```

The result is:

```php
function foo($a, $b)
{
	return $a + $b;
}
```


Anonymous Functions
-------------------

The code for anonymous functions (closures) is generated by the class [Closure |api:Nette\PhpGenerator\Closure]:

```php
$closure = new Nette\PhpGenerator\Closure;
$closure->setBody('return $a + $b;');
$closure->addParameter('a');
$closure->addParameter('b');
$closure->addUse('c')
	->setReference();
echo $closure;

// or use PsrPrinter for output compliant with PSR-2 / PSR-12 / PER
// echo (new Nette\PhpGenerator\PsrPrinter)->printClosure($closure);
```

The result is:

```php
function ($a, $b) use (&$c) {
	return $a + $b;
}
```


Short Arrow Functions
---------------------

You can also output a short arrow function using the printer:

```php
$closure = new Nette\PhpGenerator\Closure;
$closure->setBody('$a + $b');
$closure->addParameter('a');
$closure->addParameter('b');

echo (new Nette\PhpGenerator\Printer)->printArrowFunction($closure);
```

The result is:

```php
fn($a, $b) => $a + $b;
```


Method and Function Signatures
------------------------------

Methods are represented by the class [Method |api:Nette\PhpGenerator\Method]. You can set visibility, return type, add comments, [#attributes], etc.:

```php
$method = $class->addMethod('count')
	->addComment('Count it.')
	->setFinal()
	->setProtected()
	->setReturnType('?int');
```

Individual parameters are represented by the class [Parameter |api:Nette\PhpGenerator\Parameter]. Again, you can set all conceivable properties:

```php
$method->addParameter('items', []) // $items = []
	->setReference()           // &$items = []
	->setType('array');        // array &$items = []

// final protected function count(array &$items = []): ?int
```

To define variadic parameters (also known as the splat operator), use `setVariadic()`:

```php
$method = $class->addMethod('sum');
$method->setVariadic(true);
$method->addParameter('items');
```

This generates:

```php
public function sum(...$items)
{
}
```


Method and Function Bodies
--------------------------

The body can be passed all at once to the `setBody()` method or gradually (line by line) by repeatedly calling `addBody()`:

```php
$function = new Nette\PhpGenerator\GlobalFunction('foo');
$function->addBody('$a = rand(10, 20);');
$function->addBody('return $a;');
echo $function;
```

The result is:

```php
function foo()
{
	$a = rand(10, 20);
	return $a;
}
```

You can use special placeholders for easy variable insertion.

Simple placeholders `?`:

```php
$str = 'any string';
$num = 3;
$function = new Nette\PhpGenerator\GlobalFunction('foo');
$function->addBody('return substr(?, ?);', [$str, $num]);
echo $function;
```

The result is:

```php
function foo()
{
	return substr('any string', 3);
}
```

Placeholder for variadic `...?`:

```php
$items = [1, 2, 3];
$function = new Nette\PhpGenerator\GlobalFunction('foo');
$function->setBody('myfunc(...?);', [$items]);
echo $function;
```

The result is:

```php
function foo()
{
	myfunc(1, 2, 3);
}
```

You can also use named parameters for PHP 8 with `...?:`:

```php
$items = ['foo' => 1, 'bar' => true];
$function->setBody('myfunc(...?:);', [$items]);

// myfunc(foo: 1, bar: true);
```

The placeholder is escaped with a backslash `\?`:

```php
$num = 3;
$function = new Nette\PhpGenerator\GlobalFunction('foo');
$function->addParameter('a');
$function->addBody('return $a \? 10 : ?;', [$num]);
echo $function;
```

The result is:

```php
function foo($a)
{
	return $a ? 10 : 3;
}
```


Printer and PSR Compliance
--------------------------

The [Printer |api:Nette\PhpGenerator\Printer] class is used for generating PHP code:

```php
$class = new Nette\PhpGenerator\ClassType('Demo');
// ...

$printer = new Nette\PhpGenerator\Printer;
echo $printer->printClass($class); // same as: echo $class
```

It can generate code for all other elements, offering methods like `printFunction()`, `printNamespace()`, etc.

There's also the [PsrPrinter |api:Nette\PhpGenerator\PsrPrinter] class, whose output conforms to the PSR-2 / PSR-12 / PER coding style:

```php
$printer = new Nette\PhpGenerator\PsrPrinter;
echo $printer->printClass($class);
```

Need to customize the behavior? Create your own version by inheriting the `Printer` class. You can reconfigure these variables:

```php
class MyPrinter extends Nette\PhpGenerator\Printer
{
	// line length after which line wrapping occurs
	public int $wrapLength = 120;
	// indentation character, can be replaced with a sequence of spaces
	public string $indentation = "\t";
	// number of blank lines between properties
	public int $linesBetweenProperties = 0;
	// number of blank lines between methods
	public int $linesBetweenMethods = 2;
	// number of blank lines between 'use statement' groups for classes, functions, and constants
	public int $linesBetweenUseTypes = 0;
	// position of the opening curly brace for functions and methods
	public bool $bracesOnNextLine = true;
	// place a single parameter on one line, even if it has an attribute or is promoted
	public bool $singleParameterOnOneLine = false;
	// omits namespaces that do not contain any class or function
	public bool $omitEmptyNamespaces = true;
	// places declare(strict_types) on the same line as <?php
	public bool $declareOnOpenTag = false;
	// separator between the right parenthesis and the return type of functions and methods
	public string $returnTypeColon = ': ';
}
```

How and why do the standard `Printer` and `PsrPrinter` actually differ? Why isn't there just one printer, `PsrPrinter`, in the package?

The standard `Printer` formats code as we do throughout Nette. Because Nette was created much earlier than PSR, and also because PSR standards were often delivered late (sometimes years after a new PHP feature was introduced), the [Nette coding standard |contributing:coding-standard] differs in a few minor details. The main difference is the use of tabs instead of spaces. We know that using tabs in our projects allows for width customization, which is essential for [people with visual impairments |contributing:coding-standard#Tabs Instead of Spaces]. An example of a minor difference is placing the opening curly brace on a separate line for functions and methods, always. The PSR recommendation seems illogical to us and leads to [reduced code clarity |contributing:coding-standard#Wrapping and Braces].


Types
-----

Every type or union/intersection type can be passed as a string; you can also use predefined constants for native types:

```php
use Nette\PhpGenerator\Type;

$member->setType('array'); // or Type::Array
$member->setType('?array'); // or Type::nullable(Type::Array)
$member->setType('array|string'); // or Type::union(Type::Array, Type::String)
$member->setType('Foo&Bar'); // or Type::intersection(Foo::class, Bar::class)
$member->setType(null); // removes the type
```

The same applies to the `setReturnType()` method.


Literals
--------

Using `Literal`, you can pass any PHP code, for example, for default values of properties or parameters:

```php
use Nette\PhpGenerator\Literal;

$class = new Nette\PhpGenerator\ClassType('Demo');

$class->addProperty('foo', new Literal('Iterator::SELF_FIRST'));

$class->addMethod('bar')
	->addParameter('id', new Literal('1 + 2'));

echo $class;
```

Result:

```php
class Demo
{
	public $foo = Iterator::SELF_FIRST;

	public function bar($id = 1 + 2)
	{
	}
}
```

You can also pass parameters to `Literal` and have them formatted into valid PHP code using [placeholders |#Method and Function Bodies]:

```php
new Literal('substr(?, ?)', [$a, $b]);
// generates for example: substr('hello', 5)
```

A literal representing the creation of a new object can easily be generated using the `new` method:

```php
Literal::new(Demo::class, [$a, 'foo' => $b]);
// generates for example: new Demo(10, foo: 20)
```


Attributes
----------

PHP 8 attributes can be added to all classes, methods, properties, constants, enums, functions, closures, and parameters. [#Literals] can also be used as parameter values.

```php
$class = new Nette\PhpGenerator\ClassType('Demo');
$class->addAttribute('Table', [
	'name' => 'user',
	'constraints' => [
		Literal::new('UniqueConstraint', ['name' => 'ean', 'columns' => ['ean']]),
	],
]);

$class->addProperty('list')
	->addAttribute('Deprecated');

$method = $class->addMethod('count')
	->addAttribute('Foo\Cached', ['mode' => true]);

$method->addParameter('items')
	->addAttribute('Bar');

echo $class;
```

Result:

```php
#[Table(name: 'user', constraints: [new UniqueConstraint(name: 'ean', columns: ['ean'])])]
class Demo
{
	#[Deprecated]
	public $list;


	#[Foo\Cached(mode: true)]
	public function count(
		#[Bar]
		$items,
	) {
	}
}
```


Property Hooks
--------------

Using property hooks (represented by the [PropertyHook|api:Nette\PhpGenerator\PropertyHook] class), you can define get and set operations for properties, a feature introduced in PHP 8.4:

```php
$class = new Nette\PhpGenerator\ClassType('Demo');
$prop = $class->addProperty('firstName')
	->setType('string');

$prop->addHook('set', 'strtolower($value)')
	->addParameter('value')
		->setType('string');

$prop->addHook('get')
	->setBody('return ucfirst($this->firstName);');

echo $class;
```

This generates:

```php
class Demo
{
	public string $firstName {
		set(string $value) => strtolower($value);
		get {
			return ucfirst($this->firstName);
		}
	}
}
```

Properties and property hooks can be abstract or final:

```php
$class = new Nette\PhpGenerator\ClassType('Demo');
$class->setAbstract();
$class->addProperty('id')
	->setType('int')
	->setAbstract()
	->addHook('get')
		->setAbstract();

$class->addProperty('role')
	->setType('string')
	->addHook('set', 'strtolower($value)')
		->setFinal();
```

This generates:

```php
abstract class Demo
{
	abstract public int $id { get; }

	public string $role {
		final set => strtolower($value);
	}
}
```


Asymmetric Visibility
---------------------

PHP 8.4 introduces asymmetric visibility for properties. You can set different access levels for reading and writing.

Visibility can be set either using the `setVisibility()` method with two parameters, or using `setPublic()`, `setProtected()`, or `setPrivate()` with the `mode` parameter specifying whether the visibility applies to reading or writing the property. The default mode is `'get'`.

```php
$class = new Nette\PhpGenerator\ClassType('Demo');

$class->addProperty('name')
	->setType('string')
	->setVisibility('public', 'private'); // public for read, private for write

$class->addProperty('id')
	->setType('int')
	->setProtected('set'); // protected for write

echo $class;
```

This generates:

```php
class Demo
{
	public private(set) string $name;
	protected(set) int $id;
}
```


Namespace
---------

Classes, traits, interfaces, and enums (hereafter referred to as classes) can be grouped into namespaces represented by the [PhpNamespace |api:Nette\PhpGenerator\PhpNamespace] class:

```php
$namespace = new Nette\PhpGenerator\PhpNamespace('Foo');

// create new classes in the namespace
$class = $namespace->addClass('Task');
$interface = $namespace->addInterface('Countable');
$trait = $namespace->addTrait('NameAware');

// or insert an existing class or function into the namespace
$class = new Nette\PhpGenerator\ClassType('Task');
$namespace->add($class);
```

If a class with the same name already exists in the namespace, an exception is thrown.

You can define use clauses:

```php
// use Http\Request;
$namespace->addUse(Http\Request::class);
// use Http\Request as HttpReq;
$namespace->addUse(Http\Request::class, 'HttpReq');
// use function iter\range;
$namespace->addUseFunction('iter\range');
```

To simplify a fully qualified class, function, or constant name based on defined aliases or the current namespace, use the `simplifyName` method:

```php
echo $namespace->simplifyName('Foo\Bar'); // 'Bar', because 'Foo' is the current namespace
echo $namespace->simplifyName('iter\range', $namespace::NameFunction); // 'range', due to the defined use-statement
```

Conversely, you can convert a simplified class, function, or constant name back to a fully qualified name using the `resolveName` method:

```php
echo $namespace->resolveName('Bar'); // 'Foo\Bar'
echo $namespace->resolveName('range', $namespace::NameFunction); // 'iter\range'
```


Class Name Resolution
---------------------

**When a class is part of a namespace, it's rendered slightly differently:** all types (e.g., type hints, return types, parent class name, implemented interfaces, used traits, and attributes) are automatically *resolved* (unless you disable it, see below). This means you must **use fully qualified class names** in definitions, and they will be replaced with aliases (based on use clauses) or simplified names (if in the same namespace) in the resulting code:

```php
$namespace = new Nette\PhpGenerator\PhpNamespace('Foo');
$namespace->addUse('Bar\AliasedClass');

$class = $namespace->addClass('Demo');
$class->addImplement('Foo\A') // will be simplified to A
	->addTrait('Bar\AliasedClass'); // will be simplified to AliasedClass

$method = $class->addMethod('method');
$method->addComment('@return ' . $namespace->simplifyType('Foo\D')); // we manually simplify in comments
$method->addParameter('arg')
	->setType('Bar\OtherClass'); // will be translated to \Bar\OtherClass

echo $namespace;

// or use PsrPrinter for output compliant with PSR-2 / PSR-12 / PER
// echo (new Nette\PhpGenerator\PsrPrinter)->printNamespace($namespace);
```

Result:

```php
namespace Foo;

use Bar\AliasedClass;

class Demo implements A
{
	use AliasedClass;

	/**
	 * @return D
	 */
	public function method(\Bar\OtherClass $arg)
	{
	}
}
```

Auto-resolving can be disabled like this:

```php
$printer = new Nette\PhpGenerator\Printer; // or PsrPrinter
$printer->setTypeResolving(false);
echo $printer->printNamespace($namespace);
```


PHP Files
---------

Classes, functions, and namespaces can be grouped into PHP files represented by the [PhpFile|api:Nette\PhpGenerator\PhpFile] class:

```php
$file = new Nette\PhpGenerator\PhpFile;
$file->addComment('This file is auto-generated.');
$file->setStrictTypes(); // adds declare(strict_types=1)

$class = $file->addClass('Foo\A');
$function = $file->addFunction('Foo\foo');

// or
// $namespace = $file->addNamespace('Foo');
// $class = $namespace->addClass('A');
// $function = $namespace->addFunction('foo');

echo $file;

// or use PsrPrinter for output compliant with PSR-2 / PSR-12 / PER
// echo (new Nette\PhpGenerator\PsrPrinter)->printFile($file);
```

Result:

```php
<?php

/**
 * This file is auto-generated.
 */

declare(strict_types=1);

namespace Foo;

class A
{
}

function foo()
{
}
```

You can also insert existing class, function, and namespace objects into the file using the `add()` method:

```php
$file = new Nette\PhpGenerator\PhpFile;
$class = new Nette\PhpGenerator\ClassType('Demo');
$file->add($class);
```

**Please note:** No additional code (like `echo 'hello'`) can be added to the files outside of functions, classes, or namespaces.


Generating from Existing Elements
---------------------------------

Besides modeling classes and functions using the API described above, you can also have them automatically generated based on existing ones using reflection:

```php
// creates a class identical to the PDO class
$class = Nette\PhpGenerator\ClassType::from(PDO::class);

// creates a function identical to the trim() function
$function = Nette\PhpGenerator\GlobalFunction::from('trim');

// creates a closure based on the provided one
$closure = Nette\PhpGenerator\Closure::from(
	function (stdClass $a, $b = null) {},
);
```

By default, function and method bodies are empty. If you also want to load them, use this method (requires the `nikic/php-parser` package, version 5 or newer):

```php
$class = Nette\PhpGenerator\ClassType::from(Foo::class, withBodies: true);

$function = Nette\PhpGenerator\GlobalFunction::from('foo', withBody: true);
```


Loading from PHP Files
----------------------

You can also load functions, classes, interfaces, and enums directly from a string containing PHP code. For example, to create a `ClassType` object:

```php
$class = Nette\PhpGenerator\ClassType::fromCode(<<<XX
	<?php

	class Demo
	{
		public $foo;
	}
	XX);
```

When loading classes from PHP code, single-line comments outside method bodies (e.g., for properties) are ignored, as this library doesn't have an API to work with them.

You can also directly load an entire PHP file, which can contain any number of classes, functions, or even namespaces:

```php
$file = Nette\PhpGenerator\PhpFile::fromCode(file_get_contents('classes.php'));
```

The file's initial comment and `strict_types` declaration are also loaded. However, all other global code is ignored.

Requires `nikic/php-parser` version 5 or newer.

.[note]
If you need to manipulate global code in files or individual statements within method bodies, it's better to use the `nikic/php-parser` library directly.


Class Manipulator
-----------------

The [ClassManipulator|api:Nette\PhpGenerator\ClassManipulator] class provides tools for manipulating classes.

```php
$class = new Nette\PhpGenerator\ClassType('Demo');
$manipulator = new Nette\PhpGenerator\ClassManipulator($class);
```

The `inheritMethod()` method copies a method from a parent class or implemented interface into your class. This allows you to override the method or extend its signature:

```php
$method = $manipulator->inheritMethod('bar');
$method->setBody('...');
```

The `inheritProperty()` method copies a property from a parent class into your class. This is useful when you want to have the same property in your class, but possibly with a different default value:

```php
$property = $manipulator->inheritProperty('foo');
$property->setValue('new value');
```

The `implement()` method automatically implements all abstract methods and properties from the given interface or abstract class in your class:

```php
$manipulator->implement(SomeInterface::class);
// Now your class implements SomeInterface and contains stubs for all its methods
```


Variable Dumping
----------------

The [Dumper |api:Nette\PhpGenerator\Dumper] class converts a variable into parseable PHP code. It provides a better and clearer output than the standard `var_export()` function.

```php
$dumper = new Nette\PhpGenerator\Dumper;

$var = ['a', 'b', 123];

echo $dumper->dump($var); // outputs ['a', 'b', 123]
```


Compatibility Table
-------------------

PhpGenerator 4.2 is compatible with PHP 8.1 to 8.5.


If you are upgrading to a newer version, see the [upgrading] page.

{{maintitle: Nette PhpGenerator: Generate PHP Classes and Code}}
{{description: Generate PHP code for classes, functions or whole files with the latest PHP features such as property hooks, enums and attributes, or modify existing classes.}}

Nette PhpGenerator

Are you looking for a tool to generate PHP code for classes, functions, or complete files?
  • Supports all the latest PHP features (like property hooks, enums, attributes, etc.)
  • Allows you to easily modify existing classes
  • Output compliant with PSR-12 / PER coding style
  • Mature, stable, and widely used library

Installation

Download and install the library using the Composer tool:

composer require nette/php-generator

For PHP compatibility, see the compatibility table.

Classes

Let's start with an example of creating a class using ClassType:

$class = new Nette\PhpGenerator\ClassType('Demo');

$class
	->setFinal()
	->setExtends(ParentClass::class)
	->addImplement(Countable::class)
	->addComment("Class description.\nSecond line\n")
	->addComment('@property-read Nette\Forms\Form $form');

// generate code simply by typecasting to string or using echo:
echo $class;

This returns the following result:

/**
 * Class description.
 * Second line
 *
 * @property-read Nette\Forms\Form $form
 */
final class Demo extends ParentClass implements Countable
{
}

To generate the code, you can also use a printer, which, unlike echo $class, can be further configured:

$printer = new Nette\PhpGenerator\Printer;
echo $printer->printClass($class);

You can add constants (class Constant) and properties (class Property):

$class->addConstant('ID', 123)
	->setProtected() // constant visibility
	->setType('int')
	->setFinal();

$class->addProperty('items', [1, 2, 3])
	->setPrivate() // or setVisibility('private')
	->setStatic()
	->addComment('@var int[]');

$class->addProperty('list')
	->setType('?array')
	->setInitialized(); // outputs '= null'

This generates:

final protected const int ID = 123;

/** @var int[] */
private static $items = [1, 2, 3];
public ?array $list = null;

And you can add methods:

$method = $class->addMethod('count')
	->addComment('Count it.')
	->setFinal()
	->setProtected()
	->setReturnType('?int') // return types for methods
	->setBody('return count($items ?: $this->items);');

$method->addParameter('items', []) // $items = []
	->setReference()           // &$items = []
	->setType('array');        // array &$items = []

The result is:

/**
 * Count it.
 */
final protected function count(array &$items = []): ?int
{
	return count($items ?: $this->items);
}

Promoted parameters introduced in PHP 8.0 can be passed to the constructor:

$method = $class->addMethod('__construct');
$method->addPromotedParameter('name');
$method->addPromotedParameter('args', [])
	->setPrivate();

The result is:

public function __construct(
	public $name,
	private $args = [],
) {
}

Readonly properties and classes can be marked using the setReadOnly() function.

If an added property, constant, method, or trait already exists, an exception is thrown. Parameters, in contrast, are overwritten.

Class members can be removed using removeProperty(), removeConstant(), removeMethod(), or removeParameter().

You can also add existing Method, Property, or Constant objects to the class:

$method = new Nette\PhpGenerator\Method('getHandle');
$property = new Nette\PhpGenerator\Property('handle');
$const = new Nette\PhpGenerator\Constant('ROLE');

$class = (new Nette\PhpGenerator\ClassType('Demo'))
	->addMember($method)
	->addMember($property)
	->addMember($const);

You can also clone existing methods, properties, and constants under a different name using cloneWithName():

$methodCount = $class->getMethod('count');
$methodRecount = $methodCount->cloneWithName('recount');
$class->addMember($methodRecount);

Interfaces or Traits

You can create interfaces and traits (classes InterfaceType and TraitType):

$interface = new Nette\PhpGenerator\InterfaceType('MyInterface');
$trait = new Nette\PhpGenerator\TraitType('MyTrait');

Using a trait:

$class = new Nette\PhpGenerator\ClassType('Demo');
$class->addTrait('SmartObject');
$class->addTrait('MyTrait')
	->addResolution('sayHello as protected')
	->addComment('@use MyTrait<Foo>');
echo $class;

The result is:

class Demo
{
	use SmartObject;
	/** @use MyTrait<Foo> */
	use MyTrait {
		sayHello as protected;
	}
}

Enums

You can easily create enums introduced in PHP 8.1 like this (class EnumType):

$enum = new Nette\PhpGenerator\EnumType('Suit');
$enum->addCase('Clubs');
$enum->addCase('Diamonds');
$enum->addCase('Hearts');
$enum->addCase('Spades');

echo $enum;

The result is:

enum Suit
{
	case Clubs;
	case Diamonds;
	case Hearts;
	case Spades;
}

You can also define scalar equivalents and create a backed enum:

$enum = new Nette\PhpGenerator\EnumType('Suit');
$enum->addCase('Clubs', '♣');
$enum->addCase('Diamonds', '♦');

For each case, you can add a comment or attributes using addComment() or addAttribute().

Anonymous Classes

Pass null as the name, and you have an anonymous class:

$class = new Nette\PhpGenerator\ClassType(null);
$class->addMethod('__construct')
	->addParameter('foo');

echo '$obj = new class ($val) ' . $class . ';';

The result is:

$obj = new class ($val) {
	public function __construct($foo)
	{
	}
};

Global Functions

The code for global functions is generated by the class GlobalFunction:

$function = new Nette\PhpGenerator\GlobalFunction('foo');
$function->setBody('return $a + $b;');
$function->addParameter('a');
$function->addParameter('b');
echo $function;

// or use PsrPrinter for output compliant with PSR-2 / PSR-12 / PER
// echo (new Nette\PhpGenerator\PsrPrinter)->printFunction($function);

The result is:

function foo($a, $b)
{
	return $a + $b;
}

Anonymous Functions

The code for anonymous functions (closures) is generated by the class Closure:

$closure = new Nette\PhpGenerator\Closure;
$closure->setBody('return $a + $b;');
$closure->addParameter('a');
$closure->addParameter('b');
$closure->addUse('c')
	->setReference();
echo $closure;

// or use PsrPrinter for output compliant with PSR-2 / PSR-12 / PER
// echo (new Nette\PhpGenerator\PsrPrinter)->printClosure($closure);

The result is:

function ($a, $b) use (&$c) {
	return $a + $b;
}

Short Arrow Functions

You can also output a short arrow function using the printer:

$closure = new Nette\PhpGenerator\Closure;
$closure->setBody('$a + $b');
$closure->addParameter('a');
$closure->addParameter('b');

echo (new Nette\PhpGenerator\Printer)->printArrowFunction($closure);

The result is:

fn($a, $b) => $a + $b;

Method and Function Signatures

Methods are represented by the class Method. You can set visibility, return type, add comments, attributes, etc.:

$method = $class->addMethod('count')
	->addComment('Count it.')
	->setFinal()
	->setProtected()
	->setReturnType('?int');

Individual parameters are represented by the class Parameter. Again, you can set all conceivable properties:

$method->addParameter('items', []) // $items = []
	->setReference()           // &$items = []
	->setType('array');        // array &$items = []

// final protected function count(array &$items = []): ?int

To define variadic parameters (also known as the splat operator), use setVariadic():

$method = $class->addMethod('sum');
$method->setVariadic(true);
$method->addParameter('items');

This generates:

public function sum(...$items)
{
}

Method and Function Bodies

The body can be passed all at once to the setBody() method or gradually (line by line) by repeatedly calling addBody():

$function = new Nette\PhpGenerator\GlobalFunction('foo');
$function->addBody('$a = rand(10, 20);');
$function->addBody('return $a;');
echo $function;

The result is:

function foo()
{
	$a = rand(10, 20);
	return $a;
}

You can use special placeholders for easy variable insertion.

Simple placeholders ?:

$str = 'any string';
$num = 3;
$function = new Nette\PhpGenerator\GlobalFunction('foo');
$function->addBody('return substr(?, ?);', [$str, $num]);
echo $function;

The result is:

function foo()
{
	return substr('any string', 3);
}

Placeholder for variadic ...?:

$items = [1, 2, 3];
$function = new Nette\PhpGenerator\GlobalFunction('foo');
$function->setBody('myfunc(...?);', [$items]);
echo $function;

The result is:

function foo()
{
	myfunc(1, 2, 3);
}

You can also use named parameters for PHP 8 with ...?::

$items = ['foo' => 1, 'bar' => true];
$function->setBody('myfunc(...?:);', [$items]);

// myfunc(foo: 1, bar: true);

The placeholder is escaped with a backslash \?:

$num = 3;
$function = new Nette\PhpGenerator\GlobalFunction('foo');
$function->addParameter('a');
$function->addBody('return $a \? 10 : ?;', [$num]);
echo $function;

The result is:

function foo($a)
{
	return $a ? 10 : 3;
}

Printer and PSR Compliance

The Printer class is used for generating PHP code:

$class = new Nette\PhpGenerator\ClassType('Demo');
// ...

$printer = new Nette\PhpGenerator\Printer;
echo $printer->printClass($class); // same as: echo $class

It can generate code for all other elements, offering methods like printFunction(), printNamespace(), etc.

There's also the PsrPrinter class, whose output conforms to the PSR-2 / PSR-12 / PER coding style:

$printer = new Nette\PhpGenerator\PsrPrinter;
echo $printer->printClass($class);

Need to customize the behavior? Create your own version by inheriting the Printer class. You can reconfigure these variables:

class MyPrinter extends Nette\PhpGenerator\Printer
{
	// line length after which line wrapping occurs
	public int $wrapLength = 120;
	// indentation character, can be replaced with a sequence of spaces
	public string $indentation = "\t";
	// number of blank lines between properties
	public int $linesBetweenProperties = 0;
	// number of blank lines between methods
	public int $linesBetweenMethods = 2;
	// number of blank lines between 'use statement' groups for classes, functions, and constants
	public int $linesBetweenUseTypes = 0;
	// position of the opening curly brace for functions and methods
	public bool $bracesOnNextLine = true;
	// place a single parameter on one line, even if it has an attribute or is promoted
	public bool $singleParameterOnOneLine = false;
	// omits namespaces that do not contain any class or function
	public bool $omitEmptyNamespaces = true;
	// places declare(strict_types) on the same line as <?php
	public bool $declareOnOpenTag = false;
	// separator between the right parenthesis and the return type of functions and methods
	public string $returnTypeColon = ': ';
}

How and why do the standard Printer and PsrPrinter actually differ? Why isn't there just one printer, PsrPrinter, in the package?

The standard Printer formats code as we do throughout Nette. Because Nette was created much earlier than PSR, and also because PSR standards were often delivered late (sometimes years after a new PHP feature was introduced), the Nette coding standard differs in a few minor details. The main difference is the use of tabs instead of spaces. We know that using tabs in our projects allows for width customization, which is essential for people with visual impairments. An example of a minor difference is placing the opening curly brace on a separate line for functions and methods, always. The PSR recommendation seems illogical to us and leads to reduced code clarity.

Types

Every type or union/intersection type can be passed as a string; you can also use predefined constants for native types:

use Nette\PhpGenerator\Type;

$member->setType('array'); // or Type::Array
$member->setType('?array'); // or Type::nullable(Type::Array)
$member->setType('array|string'); // or Type::union(Type::Array, Type::String)
$member->setType('Foo&Bar'); // or Type::intersection(Foo::class, Bar::class)
$member->setType(null); // removes the type

The same applies to the setReturnType() method.

Literals

Using Literal, you can pass any PHP code, for example, for default values of properties or parameters:

use Nette\PhpGenerator\Literal;

$class = new Nette\PhpGenerator\ClassType('Demo');

$class->addProperty('foo', new Literal('Iterator::SELF_FIRST'));

$class->addMethod('bar')
	->addParameter('id', new Literal('1 + 2'));

echo $class;

Result:

class Demo
{
	public $foo = Iterator::SELF_FIRST;

	public function bar($id = 1 + 2)
	{
	}
}

You can also pass parameters to Literal and have them formatted into valid PHP code using placeholders:

new Literal('substr(?, ?)', [$a, $b]);
// generates for example: substr('hello', 5)

A literal representing the creation of a new object can easily be generated using the new method:

Literal::new(Demo::class, [$a, 'foo' => $b]);
// generates for example: new Demo(10, foo: 20)

Attributes

PHP 8 attributes can be added to all classes, methods, properties, constants, enums, functions, closures, and parameters. Literals can also be used as parameter values.

$class = new Nette\PhpGenerator\ClassType('Demo');
$class->addAttribute('Table', [
	'name' => 'user',
	'constraints' => [
		Literal::new('UniqueConstraint', ['name' => 'ean', 'columns' => ['ean']]),
	],
]);

$class->addProperty('list')
	->addAttribute('Deprecated');

$method = $class->addMethod('count')
	->addAttribute('Foo\Cached', ['mode' => true]);

$method->addParameter('items')
	->addAttribute('Bar');

echo $class;

Result:

#[Table(name: 'user', constraints: [new UniqueConstraint(name: 'ean', columns: ['ean'])])]
class Demo
{
	#[Deprecated]
	public $list;


	#[Foo\Cached(mode: true)]
	public function count(
		#[Bar]
		$items,
	) {
	}
}

Property Hooks

Using property hooks (represented by the PropertyHook class), you can define get and set operations for properties, a feature introduced in PHP 8.4:

$class = new Nette\PhpGenerator\ClassType('Demo');
$prop = $class->addProperty('firstName')
	->setType('string');

$prop->addHook('set', 'strtolower($value)')
	->addParameter('value')
		->setType('string');

$prop->addHook('get')
	->setBody('return ucfirst($this->firstName);');

echo $class;

This generates:

class Demo
{
	public string $firstName {
		set(string $value) => strtolower($value);
		get {
			return ucfirst($this->firstName);
		}
	}
}

Properties and property hooks can be abstract or final:

$class = new Nette\PhpGenerator\ClassType('Demo');
$class->setAbstract();
$class->addProperty('id')
	->setType('int')
	->setAbstract()
	->addHook('get')
		->setAbstract();

$class->addProperty('role')
	->setType('string')
	->addHook('set', 'strtolower($value)')
		->setFinal();

This generates:

abstract class Demo
{
	abstract public int $id { get; }

	public string $role {
		final set => strtolower($value);
	}
}

Asymmetric Visibility

PHP 8.4 introduces asymmetric visibility for properties. You can set different access levels for reading and writing.

Visibility can be set either using the setVisibility() method with two parameters, or using setPublic(), setProtected(), or setPrivate() with the mode parameter specifying whether the visibility applies to reading or writing the property. The default mode is 'get'.

$class = new Nette\PhpGenerator\ClassType('Demo');

$class->addProperty('name')
	->setType('string')
	->setVisibility('public', 'private'); // public for read, private for write

$class->addProperty('id')
	->setType('int')
	->setProtected('set'); // protected for write

echo $class;

This generates:

class Demo
{
	public private(set) string $name;
	protected(set) int $id;
}

Namespace

Classes, traits, interfaces, and enums (hereafter referred to as classes) can be grouped into namespaces represented by the PhpNamespace class:

$namespace = new Nette\PhpGenerator\PhpNamespace('Foo');

// create new classes in the namespace
$class = $namespace->addClass('Task');
$interface = $namespace->addInterface('Countable');
$trait = $namespace->addTrait('NameAware');

// or insert an existing class or function into the namespace
$class = new Nette\PhpGenerator\ClassType('Task');
$namespace->add($class);

If a class with the same name already exists in the namespace, an exception is thrown.

You can define use clauses:

// use Http\Request;
$namespace->addUse(Http\Request::class);
// use Http\Request as HttpReq;
$namespace->addUse(Http\Request::class, 'HttpReq');
// use function iter\range;
$namespace->addUseFunction('iter\range');

To simplify a fully qualified class, function, or constant name based on defined aliases or the current namespace, use the simplifyName method:

echo $namespace->simplifyName('Foo\Bar'); // 'Bar', because 'Foo' is the current namespace
echo $namespace->simplifyName('iter\range', $namespace::NameFunction); // 'range', due to the defined use-statement

Conversely, you can convert a simplified class, function, or constant name back to a fully qualified name using the resolveName method:

echo $namespace->resolveName('Bar'); // 'Foo\Bar'
echo $namespace->resolveName('range', $namespace::NameFunction); // 'iter\range'

Class Name Resolution

When a class is part of a namespace, it's rendered slightly differently: all types (e.g., type hints, return types, parent class name, implemented interfaces, used traits, and attributes) are automatically resolved (unless you disable it, see below). This means you must use fully qualified class names in definitions, and they will be replaced with aliases (based on use clauses) or simplified names (if in the same namespace) in the resulting code:

$namespace = new Nette\PhpGenerator\PhpNamespace('Foo');
$namespace->addUse('Bar\AliasedClass');

$class = $namespace->addClass('Demo');
$class->addImplement('Foo\A') // will be simplified to A
	->addTrait('Bar\AliasedClass'); // will be simplified to AliasedClass

$method = $class->addMethod('method');
$method->addComment('@return ' . $namespace->simplifyType('Foo\D')); // we manually simplify in comments
$method->addParameter('arg')
	->setType('Bar\OtherClass'); // will be translated to \Bar\OtherClass

echo $namespace;

// or use PsrPrinter for output compliant with PSR-2 / PSR-12 / PER
// echo (new Nette\PhpGenerator\PsrPrinter)->printNamespace($namespace);

Result:

namespace Foo;

use Bar\AliasedClass;

class Demo implements A
{
	use AliasedClass;

	/**
	 * @return D
	 */
	public function method(\Bar\OtherClass $arg)
	{
	}
}

Auto-resolving can be disabled like this:

$printer = new Nette\PhpGenerator\Printer; // or PsrPrinter
$printer->setTypeResolving(false);
echo $printer->printNamespace($namespace);

PHP Files

Classes, functions, and namespaces can be grouped into PHP files represented by the PhpFile class:

$file = new Nette\PhpGenerator\PhpFile;
$file->addComment('This file is auto-generated.');
$file->setStrictTypes(); // adds declare(strict_types=1)

$class = $file->addClass('Foo\A');
$function = $file->addFunction('Foo\foo');

// or
// $namespace = $file->addNamespace('Foo');
// $class = $namespace->addClass('A');
// $function = $namespace->addFunction('foo');

echo $file;

// or use PsrPrinter for output compliant with PSR-2 / PSR-12 / PER
// echo (new Nette\PhpGenerator\PsrPrinter)->printFile($file);

Result:

<?php

/**
 * This file is auto-generated.
 */

declare(strict_types=1);

namespace Foo;

class A
{
}

function foo()
{
}

You can also insert existing class, function, and namespace objects into the file using the add() method:

$file = new Nette\PhpGenerator\PhpFile;
$class = new Nette\PhpGenerator\ClassType('Demo');
$file->add($class);

Please note: No additional code (like echo 'hello') can be added to the files outside of functions, classes, or namespaces.

Generating from Existing Elements

Besides modeling classes and functions using the API described above, you can also have them automatically generated based on existing ones using reflection:

// creates a class identical to the PDO class
$class = Nette\PhpGenerator\ClassType::from(PDO::class);

// creates a function identical to the trim() function
$function = Nette\PhpGenerator\GlobalFunction::from('trim');

// creates a closure based on the provided one
$closure = Nette\PhpGenerator\Closure::from(
	function (stdClass $a, $b = null) {},
);

By default, function and method bodies are empty. If you also want to load them, use this method (requires the nikic/php-parser package, version 5 or newer):

$class = Nette\PhpGenerator\ClassType::from(Foo::class, withBodies: true);

$function = Nette\PhpGenerator\GlobalFunction::from('foo', withBody: true);

Loading from PHP Files

You can also load functions, classes, interfaces, and enums directly from a string containing PHP code. For example, to create a ClassType object:

$class = Nette\PhpGenerator\ClassType::fromCode(<<<XX
	<?php

	class Demo
	{
		public $foo;
	}
	XX);

When loading classes from PHP code, single-line comments outside method bodies (e.g., for properties) are ignored, as this library doesn't have an API to work with them.

You can also directly load an entire PHP file, which can contain any number of classes, functions, or even namespaces:

$file = Nette\PhpGenerator\PhpFile::fromCode(file_get_contents('classes.php'));

The file's initial comment and strict_types declaration are also loaded. However, all other global code is ignored.

Requires nikic/php-parser version 5 or newer.

If you need to manipulate global code in files or individual statements within method bodies, it's better to use the nikic/php-parser library directly.

Class Manipulator

The ClassManipulator class provides tools for manipulating classes.

$class = new Nette\PhpGenerator\ClassType('Demo');
$manipulator = new Nette\PhpGenerator\ClassManipulator($class);

The inheritMethod() method copies a method from a parent class or implemented interface into your class. This allows you to override the method or extend its signature:

$method = $manipulator->inheritMethod('bar');
$method->setBody('...');

The inheritProperty() method copies a property from a parent class into your class. This is useful when you want to have the same property in your class, but possibly with a different default value:

$property = $manipulator->inheritProperty('foo');
$property->setValue('new value');

The implement() method automatically implements all abstract methods and properties from the given interface or abstract class in your class:

$manipulator->implement(SomeInterface::class);
// Now your class implements SomeInterface and contains stubs for all its methods

Variable Dumping

The Dumper class converts a variable into parseable PHP code. It provides a better and clearer output than the standard var_export() function.

$dumper = new Nette\PhpGenerator\Dumper;

$var = ['a', 'b', 123];

echo $dumper->dump($var); // outputs ['a', 'b', 123]

Compatibility Table

PhpGenerator 4.2 is compatible with PHP 8.1 to 8.5.

If you are upgrading to a newer version, see the upgrading page.