Генератор на PHP код
********************

<div class=perex>
Търсите ли инструмент за генериране на PHP код за класове, функции или цели файлове?

- Поддържа всички най-нови функции на PHP (като enums и др.)
- Позволява ви лесно да променяте съществуващи класове
- Изход, съвместим със стила на кодиране PSR-12 / PER
- Зряла, стабилна и широко използвана библиотека
</div>


Инсталация .[#toc-installation]
-------------------------------

Изтеглете и инсталирайте пакета с помощта на [Composer |best-practices:composer]:

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

За съвместимост с PHP вижте [таблицата |#Compatibility Table].


Класове .[#toc-classes]
-----------------------

Нека да започнем с прост пример за генериране на клас с помощта на [ClassType |api:Nette\PhpGenerator\ClassType]:

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

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

// за генериране на PHP код просто го превърнете в низ или използвайте echo:
echo $class;
```

Той ще даде този резултат:

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

Можем също така да използваме принтер за генериране на кода, който, за разлика от `echo $class`, ще можем да [конфигурираме допълнително |#Printers and PSR compliance]:

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

Можем да добавяме константи (клас [Constant |api:Nette\PhpGenerator\Constant]) и свойства (клас [Property |api:Nette\PhpGenerator\Property]):

```php
$class->addConstant('ID', 123)
	->setProtected() // постоянна видимост
	->setType('int')
	->setFinal();

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

$class->addProperty('list')
	->setType('?array')
	->setInitialized(); // отпечатва '= null'
```

Той генерира:

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

/** @var int[] */
private static $items = [1, 2, 3];

public ?array $list = null;
```

Можем да добавяме и [методи |#Method and Function Signature]:

```php
$method = $class->addMethod('count')
	->addComment('Count it.')
	->setFinal()
	->setProtected()
	->setReturnType('?int') // тип връщане на метода
	->setBody('return count($items ?: $this->items);');

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

Това води до:

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

Промотираните параметри, въведени от PHP 8.0, могат да се предават на конструктора:

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

Това води до:

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

Свойствата и класовете само за четене могат да бъдат маркирани чрез `setReadOnly()`.

------

Ако добавеното свойство, константа, метод или параметър вече съществуват, се изхвърля изключение.

Членовете могат да бъдат премахнати с помощта на `removeProperty()`, `removeConstant()`, `removeMethod()` или `removeParameter()`.

Можете също така да добавяте съществуващи обекти `Method`, `Property` или `Constant` към класа:

```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);
```

Можете да клонирате съществуващи методи, свойства и константи с различно име, като използвате `cloneWithName()`:

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


Интерфейс или черта .[#toc-interface-or-trait]
----------------------------------------------

Можете да създавате интерфейси и черти (класове [InterfaceType |api:Nette\PhpGenerator\InterfaceType] и [TraitType |api:Nette\PhpGenerator\TraitType]):

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

Използване на черти:

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

Резултат:

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


Енуми .[#toc-enums]
-------------------

Можете лесно да създадете енумите, които PHP 8.1 въвежда (клас [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;
```

Резултат:

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

Можете също така да дефинирате скаларни еквиваленти за случаите, за да създадете подкрепен енум:

```php
$enum->addCase('Clubs', '♣');
$enum->addCase('Diamonds', '♦');
```

Възможно е да добавите коментар или [атрибути |#attributes] към всеки случай, като използвате `addComment()` или `addAttribute()`.


Анонимен клас .[#toc-anonymous-class]
-------------------------------------

Дайте името `null` и ще имате анонимен клас:

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

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

Резултат:

```php
$obj = new class ($val) {

	public function __construct($foo)
	{
	}
};
```


Глобална функция .[#toc-global-function]
----------------------------------------

Кодът на функциите ще генерира клас [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;

// или използвайте PsrPrinter за изход, съответстващ на PSR-2 / PSR-12 / PER
// echo (new Nette\PhpGenerator\PsrPrinter)->printFunction($function);
```

Резултат:

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


Затваряне .[#toc-closure]
-------------------------

Кодът на затворите ще генерира клас [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;

// или използвайте PsrPrinter за изход, съответстващ на PSR-2 / PSR-12 / PER
// echo (new Nette\PhpGenerator\PsrPrinter)->printClosure($closure);
```

Резултат:

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


Функция стрелка .[#toc-arrow-function]
--------------------------------------

Можете също така да отпечатате затварянето като функция стрелка, като използвате принтер:

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

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

Резултат:

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


Подпис на метод и функция .[#toc-method-and-function-signature]
---------------------------------------------------------------

Методите се представят чрез класа [Method |api:Nette\PhpGenerator\Method]. Можете да задавате видимост, връщана стойност, да добавяте коментари, [атрибути |#Attributes] и т.н:

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

Всеки параметър се представя от клас [Parameter |api:Nette\PhpGenerator\Parameter]. Отново можете да задавате всички възможни свойства:

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

// function count(&$items = [])
```

За да дефинирате т.нар. вариационни параметри (а също и оператора splat, spread, ellipsis, unpacking или three dots), използвайте `setVariadic()`:

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

Генерира:

```php
function count(...$items)
{
}
```


Метод и тяло на функцията .[#toc-method-and-function-bodies]
------------------------------------------------------------

Тялото може да се предаде на метода `setBody()` наведнъж или последователно (ред по ред) чрез многократно извикване на `addBody()`:

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

Резултат

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

Можете да използвате специални заместители за удобен начин за инжектиране на променливи.

Обикновени заместители `?`

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

Резултат:

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

Variadic placeholder `...?`

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

Резултат:

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

Можете също така да използвате именувани параметри в PHP 8, като използвате заместител `...?:`

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

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

Избягване на заместителя чрез наклонена черта `\?`

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

Резултат:

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


Принтери и съответствие с PSR .[#toc-printers-and-psr-compliance]
-----------------------------------------------------------------

Класът [Printer |api:Nette\PhpGenerator\Printer] се използва за генериране на PHP код:

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

$printer = нов Nette\PhpGenerator\Printer;
echo $printer->printClass($class); // същото като: echo $class
```

Той може да генерира код за всички останали елементи, като предлага методи като `printFunction()`, `printNamespace()` и др.

Освен това е наличен класът `PsrPrinter`, чийто изход е в съответствие със стила на кодиране PSR-2 / PSR-12 / PER:

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

Трябва да настроите поведението според нуждите си? Създайте свой собствен принтер, като го наследите от класа `Printer`. Можете да преконфигурирате тези променливи:

```php
class MyPrinter extends Nette\PhpGenerator\Printer
{
	// дължина на реда, след която редът ще се прекъсне
	public int $wrapLength = 120;
	// символ за отстъпление, може да бъде заменен с поредица от интервали
	public string $indentation = "\t";
	// брой празни редове между свойствата
	public int $linesBetweenProperties = 0;
	// Брой празни редове между методите
	public int $linesBetweenMethods = 2;
	// брой празни редове между групите декларации за употреба на класове, функции и константи
	public int $linesBetweenUseTypes = 0;
	// позиция на отварящата се скоба за функции и методи
	public bool $bracesOnNextLine = true;
	// поставяне на един параметър на един ред, дори ако той има атрибут или е повишен
	public bool $singleParameterOnOneLine = false;
	// omits namespaces that do not contain any class or function
	public bool $omitEmptyNamespaces = true;
	// разделител между дясната скоба и типа за връщане на функции и методи
	public string $returnTypeColon = ': ';
}
```

Как и защо точно се различават стандартните `Printer` и `PsrPrinter`? Защо в пакета няма само един принтер, `PsrPrinter`, който да се различава?

Стандартният `Printer` форматира кода така, както го правим в цялата мрежа Nette. Тъй като Nette беше създадена много по-рано от PSR, а също и защото PSR в продължение на много години не предоставяше стандартите навреме, а понякога дори с няколко години закъснение от въвеждането на нова функция в PHP, това доведе до няколко малки разлики в [стандарта за кодиране |contributing:coding-standard].
По-голямата разлика е само в използването на табулатори вместо интервали. Знаем, че чрез използването на табулатори в нашите проекти даваме възможност за регулиране на ширината, което е [от съществено значение за хората със зрителни увреждания |contributing:coding-standard#Tabs Instead of Spaces].
Пример за малка разлика е поставянето на къдравата скоба на отделен ред за функциите и методите и винаги. Считаме, че препоръката на PSR е нелогична и [води до намаляване на яснотата на кода |contributing:coding-standard#Wrapping and Braces].


Типове .[#toc-types]
--------------------

Всеки тип или тип съюз/междинна секция може да бъде предаден като низ, можете също така да използвате предварително дефинирани константи за местни типове:

```php
use Nette\PhpGenerator\Type;

$member->setType('array'); // или 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'); // или Type::intersection(Foo::class, Bar::class)
$member->setType(null); // премахва тип
```

Същото се отнася и за метода `setReturnType()`.


Литерали .[#toc-literals]
-------------------------

С помощта на `Literal` можете да предавате произволен PHP код, например стойности на свойства или параметри по подразбиране и т.н:

```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;
```

Резултат:

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

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

Можете също така да подавате параметри на `Literal` и да ги форматирате във валиден PHP код, като използвате [специални заместители |#method-and-function-bodies]:

```php
new Literal('substr(?, ?)', [$a, $b]);
// генерира, например: substr('hello', 5);
```

Литералът, представящ създаването на нов обект, се генерира лесно чрез метода `new`:

```php
Literal::new(Demo::class, [$a, 'foo' => $b]);
// генерира, например: new Demo(10, foo: 20)
```


Атрибути .[#toc-attributes]
---------------------------

Можете да добавяте атрибути на PHP 8 към всички класове, методи, свойства, константи, списъци, функции, затваряния и параметри. [Литералите |#Literals] също могат да се използват като стойности на параметрите.

```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;
```

Резултат:

```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,
	) {
	}
}
```


Пространство от имена .[#toc-namespace]
---------------------------------------

Класовете, чертите, интерфейсите и енумите (наричани по-долу класове) могат да бъдат групирани в пространства от имена[(PhpNamespace) |api:Nette\PhpGenerator\PhpNamespace]:

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

// създаване на нови класове в пространството от имена
$class = $namespace->addClass('Task');
$interface = $namespace->addInterface('Countable');
$trait = $namespace->addTrait('NameAware');

// или да вмъкнете съществуващ клас в пространството от имена
$class = new Nette\PhpGenerator\ClassType('Task');
$namespace->add($class);
```

Ако класът вече съществува, се изхвърля изключение.

Можете да дефинирате декларации за употреба:

```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');
```

За да опростите напълно квалифицирано име на клас, функция или константа в съответствие с дефинираните псевдоними, използвайте метода `simplifyName`:

```php
echo $namespace->simplifyName('Foo\Bar'); // 'Bar', защото 'Foo' е текущото пространство от имена
echo $namespace->simplifyName('iter\range', $namespace::NameFunction); // 'range', защото е дефинирано твърдение за употреба
```

И обратно, можете да преобразувате опростено име на клас, функция или константа в пълно квалифицирано име, като използвате метода `resolveName`:

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


Преобразуване на имена на класове .[#toc-class-names-resolving]
---------------------------------------------------------------

**Когато един клас е част от пространство от имена, той се визуализира по малко по-различен начин:** всички типове (напр. подсказки за тип, типове връщане, име на родителския клас, имплементирани интерфейси, използвани черти и атрибути) се решават автоматично (освен ако не го изключите, вижте по-долу).
Това означава, че трябва да използвате **пълно квалифицирани имена на класове** в дефинициите и те ще бъдат заменени с псевдоними (въз основа на клаузи за използване) или напълно квалифицирани имена в получения код:

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

$class = $namespace->addClass('Demo');
$class->addImplement('Foo\A') // ще се опрости до A
	->addTrait('Bar\AliasedClass'); // ще се опрости до AliasedClass

$method = $class->addMethod('method');
$method->addComment('@return ' . $namespace->simplifyType('Foo\D')); // в коментарите опростете ръчно
$method->addParameter('arg')
	->setType('Bar\OtherClass'); // ще се разреши до \Bar\OtherClass

echo $namespace;

// или използвайте PsrPrinter за изход, съответстващ на PSR-2 / PSR-12 / PER
// echo (new Nette\PhpGenerator\PsrPrinter)->printNamespace($namespace);
```

Резултат:

```php
namespace Foo;

use Bar\AliasedClass;

class Demo implements A
{
	use AliasedClass;

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

По този начин автоматичното разрешаване може да бъде изключено:

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


PHP файлове .[#toc-php-files]
-----------------------------

Класовете, функциите и пространствата от имена могат да бъдат групирани в PHP файлове, представени от класа [PhpFile |api:Nette\PhpGenerator\PhpFile]:

```php
$file = new Nette\PhpGenerator\PhpFile;
$file->addComment('This file is auto-generated.');
$file->setStrictTypes(); // добавя declare(strict_types=1)

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

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

echo $file;

// или използвайте PsrPrinter за изход, съответстващ на PSR-2 / PSR-12 / PER
// echo (new Nette\PhpGenerator\PsrPrinter)->printFile($file);
```

Резултат:

```php
<?php

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

declare(strict_types=1);

namespace Foo;

class A
{
}

function foo()
{
}
```

**Забележете:** Във файловете не може да се добавя допълнителен код извън функциите и класовете.


Генериране според съществуващите .[#toc-generating-according-to-existing-ones]
------------------------------------------------------------------------------

Освен че можете да моделирате класове и функции, използвайки API, описан по-горе, можете също така да ги генерирате автоматично по съществуващи такива:

```php
// създава клас, идентичен на класа PDO
$class = Nette\PhpGenerator\ClassType::from(PDO::class);

// създава функция, идентична на trim()
$function = Nette\PhpGenerator\GlobalFunction::from('trim');

// създава затваряне, както е посочено
$closure = Nette\PhpGenerator\Closure::from(
	function (stdClass $a, $b = null) {},
);
```

По подразбиране телата на функциите и методите са празни. Ако искате да ги заредите също, използвайте този начин
(той изисква да е инсталиран `nikic/php-parser`):

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

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


Зареждане от PHP файл .[#toc-loading-from-php-file]
---------------------------------------------------

Можете също така да зареждате функции, класове, интерфейси и енуми директно от низ от PHP код. Например, създаваме обект `ClassType` по този начин:

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

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

Когато зареждате класове от PHP код, коментарите на един ред извън тялото на метода се игнорират (например за свойства и т.н.), тъй като тази библиотека не разполага с API за работа с тях.

Можете също така да заредите директно целия PHP файл, който може да съдържа произволен брой класове, функции или дори няколко пространства от имена:

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

Първоначалният коментар на файла и декларацията `strict_types` също се зареждат. От друга страна, всички останали глобални кодове се игнорират.

Това изисква да е инсталиран `nikic/php-parser`.

.[note]
Ако трябва да манипулирате глобален код във файлове или отделни оператори в тялото на метод, по-добре е да използвате директно библиотеката `nikic/php-parser`.


Манипулатор на класове .[#toc-class-manipulator]
------------------------------------------------

Класът [ClassManipulator |api:Nette\PhpGenerator\ClassManipulator] предоставя инструменти за манипулиране на класове.

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

Методът `inheritMethod()` копира метод от родителски клас или имплементиран интерфейс във вашия клас. Това ви позволява да замените метода или да разширите неговата сигнатура:

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

Методът `inheritProperty()` копира свойство от родителски клас във вашия клас. Това е полезно, когато искате да имате същото свойство във вашия клас, но евентуално с различна стойност по подразбиране:

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

Методът `implementInterface()` автоматично имплементира всички методи от дадения интерфейс във вашия клас:

```php
$manipulator->implementInterface(SomeInterface::class);
// Сега вашият клас имплементира SomeInterface и включва всички негови методи
```


Дъмпер за променливи .[#toc-variables-dumper]
---------------------------------------------

Dumper връща символно представяне на променлива в PHP низ. Осигурява по-добър и по-ясен изход от нативната функция `var_export()`.

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

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

echo $dumper->dump($var); // отпечатва ['a', 'b', 123]
```


Таблица за съвместимост .[#toc-compatibility-table]
---------------------------------------------------

PhpGenerator 4.0 и 4.1 са съвместими с PHP 8.0 до 8.3

{{leftbar: nette:@menu-topics}}