Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Deprecating all ::fromArray() methods in in the package #153

Merged
merged 4 commits into from
Nov 18, 2022
Merged

Deprecating all ::fromArray() methods in in the package #153

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
075a3ca
Deprecating all `::fromArray()` methods in in the package
Ocramius Nov 18, 2022
f150da7
Rewrote documentation to get rid of any `::fromArray()` references
Ocramius Nov 18, 2022
b70cbc5
Adjusted `->setBody()` call to use less escaping noise
Ocramius Nov 18, 2022
e93f83b
Adjusted docblock annotation sorting as per PHPCS rules
Ocramius Nov 18, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
211 changes: 90 additions & 121 deletions docs/book/generator/examples.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,25 +7,20 @@ The following example generates an empty class with a class-level DocBlock.
```php
use Laminas\Code\Generator\ClassGenerator;
use Laminas\Code\Generator\DocBlockGenerator;

$foo = new ClassGenerator();
$docblock = DocBlockGenerator::fromArray([
'shortDescription' => 'Sample generated class',
'longDescription' => 'This is a class generated with Laminas\Code\Generator.',
'tags' => [
[
'name' => 'version',
'description' => '$Rev:$',
],
[
'name' => 'license',
'description' => 'New BSD',
],
],
]);
$foo->setName('Foo')
->setDocblock($docblock);
echo $foo->generate();
use Laminas\Code\Generator\DocBlock\Tag\GenericTag;

echo (new ClassGenerator())
->setName('Foo')
->setDocblock(
(new DocBlockGenerator())
->setShortDescription('Sample generated class')
->setLongDescription('This is a class generated with Laminas\Code\Generator.')
->setTags([
new GenericTag('version', '$Rev:$'),
new GenericTag('license', 'New BSD'),
])
)
->generate();
```

The above code will result in the following:
Expand Down Expand Up @@ -55,31 +50,25 @@ use Laminas\Code\Generator\ClassGenerator;
use Laminas\Code\Generator\DocBlockGenerator;
use Laminas\Code\Generator\PropertyGenerator;

$foo = new ClassGenerator();
$docblock = DocBlockGenerator::fromArray([
'shortDescription' => 'Sample generated class',
'longDescription' => 'This is a class generated with Laminas\Code\Generator.',
'tags' => [
[
'name' => 'version',
'description' => '$Rev:$',
],
[
'name' => 'license',
'description' => 'New BSD',
],
],
]);
$foo->setName('Foo')
->setDocblock($docblock)
echo (new ClassGenerator())
->setName('Foo')
->setDocblock(
(new DocBlockGenerator())
->setShortDescription('Sample generated class')
->setLongDescription('This is a class generated with Laminas\Code\Generator.')
->setTags([
new GenericTag('version', '$Rev:$'),
new GenericTag('license', 'New BSD'),
])
)
->addProperties([
['bar', 'baz', PropertyGenerator::FLAG_PROTECTED],
['baz', 'bat', PropertyGenerator::FLAG_PUBLIC]
new PropertyGenerator('bar', 'baz', PropertyGenerator::FLAG_PROTECTED),
new PropertyGenerator('baz', 'bat', PropertyGenerator::FLAG_PUBLIC),
])
->addConstants([
['bat', 'foobarbazbat']
new PropertyGenerator('bat', 'foobarbazbat', PropertyGenerator::FLAG_CONSTANT)
]);
echo $foo->generate();
->generate();
```

The above results in the following class definition:
Expand Down Expand Up @@ -117,75 +106,65 @@ use Laminas\Code\Generator\ClassGenerator;
use Laminas\Code\Generator\DocBlockGenerator;
use Laminas\Code\Generator\DocBlock\Tag;
use Laminas\Code\Generator\MethodGenerator;
use Laminas\Code\Generator\ParameterGenerator;
use Laminas\Code\Generator\PropertyGenerator;

$foo = new ClassGenerator();
$docblock = DocBlockGenerator::fromArray([
'shortDescription' => 'Sample generated class',
'longDescription' => 'This is a class generated with Laminas\Code\Generator.',
'tags' => [
[
'name' => 'version',
'description' => '$Rev:$',
],
[
'name' => 'license',
'description' => 'New BSD',
],
],
]);
$foo->setName('Foo')
->setDocblock($docblock)
echo (new ClassGenerator())
->setName('Foo')
->setDocblock(
(new DocBlockGenerator())
->setShortDescription('Sample generated class')
->setLongDescription('This is a class generated with Laminas\Code\Generator.')
->setTags([
new GenericTag('version', '$Rev:$'),
new GenericTag('license', 'New BSD'),
])
)
->addProperties([
['bar', 'baz', PropertyGenerator::FLAG_PROTECTED],
['baz', 'bat', PropertyGenerator::FLAG_PUBLIC]
new PropertyGenerator('bar', 'baz', PropertyGenerator::FLAG_PROTECTED),
new PropertyGenerator('baz', 'bat', PropertyGenerator::FLAG_PUBLIC),
])
->addConstants([
['bat', 'foobarbazbat', PropertyGenerator::FLAG_CONSTANT]
])
new PropertyGenerator('bat', 'foobarbazbat', PropertyGenerator::FLAG_CONSTANT)
]);
->addMethods([
// Method passed as array
MethodGenerator::fromArray([
'name' => 'setBar',
'parameters' => ['bar'],
'body' => '$this->bar = $bar;' . "\n" . 'return $this;',
'docblock' => DocBlockGenerator::fromArray([
'shortDescription' => 'Set the bar property',
'longDescription' => null,
'tags' => [
new Tag\ParamTag(
'bar',
[
'string',
'array'
],
'parameter description'
),
new Tag\ReturnTag([
'datatype' => 'string',
]),
],
]),
// Method built programmatically
(new MethodGenerator())
->setName('setBar')
->setParameters([
new ParameterGenerator('bar')
])
->setBody('$this->bar = $bar;' . "\n" . 'return $this;')
->setDocBlock(
(new DocBlockGenerator())
->setShortDescription('Set the bar property')
->setTags([
new Tag\ParamTag(
'bar',
['string', 'array'],
'parameter description'
),
new Tag\ReturnTag([
'datatype' => 'string',
]),
])
)
]),
// Method passed as concrete instance
new MethodGenerator(
'getBar',
[],
MethodGenerator::FLAG_PUBLIC,
'return $this->bar;',
DocBlockGenerator::fromArray([
'shortDescription' => 'Retrieve the bar property',
'longDescription' => null,
'tags' => [
new Tag\ReturnTag([
'datatype' => 'string|null',
]),
],
(new DocBlockGenerator())
->setShortDescription('Retrieve the bar property'),
->setTags([
new Tag\ReturnTag(['string|null']),
])
])
),
]);

echo $foo->generate();
->generate();
```

The above generates the following output:
Expand Down Expand Up @@ -244,21 +223,18 @@ previous example.
```php
use Laminas\Code\Generator\DocBlockGenerator;
use Laminas\Code\Generator\FileGenerator;

$file = FileGenerator::fromArray([
'classes' => [$foo],
'docblock' => DocBlockGenerator::fromArray([
'shortDescription' => 'Foo class file',
'longDescription' => null,
'tags' => [
[
'name' => 'license',
'description' => 'New BSD',
],
],
]),
'body' => 'define(\'APPLICATION_ENV\', \'testing\');',
]);
use Laminas\Code\Generator\DocBlock\Tag\GenericTag;

$file = (new FileGenerator)
->setClasses([$foo])
->setDocBlock(
(new DocBlockGenerator())
->setShortDescription('Foo class file')
->setTag([
new GenericTag('license', 'New BSD')
])
)
->setBody("define('APPLICATION_ENV', 'testing');");
```

Calling `generate()` will generate the code -- but not write it to a file. You will need to capture
Expand Down Expand Up @@ -346,19 +322,12 @@ $generator->addMethod(
['baz'],
MethodGenerator::FLAG_PUBLIC,
'$this->baz = $baz;' . "\n" . 'return $this;',
DocBlockGenerator::fromArray([
'shortDescription' => 'Set the baz property',
'longDescription' => null,
'tags' => [
new Tag\ParamTag([
'paramName' => 'baz',
'datatype' => 'string'
]),
new Tag\ReturnTag([
'datatype' => 'string',
]),
],
])
(new DocBlockGenerator())
->setShortDescription('Set the baz property')
->setTags([
new Tag\ParamTag('baz', ['string']),
new Tag\ReturnTag('string'),
])
);
$code = $generator->generate();
```
1 change: 0 additions & 1 deletion docs/book/generator/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -264,7 +264,6 @@ The *API* of the class is as follows:
```php
class Laminas\Code\Generator\FileGenerator extends Laminas\Code\Generator\AbstractGenerator
{
public static function fromArray(array $values)
public function setDocblock(Laminas\Code\Generator\DocBlockGenerator $docblock)
public function getDocblock()
public function setRequiredFiles($requiredFiles)
Expand Down
Loading