Skip to content

Commit 86ab3b7

Browse files
committed
Organise generator into namespaces
Trying to make this project as easy to contribute to as possible - smaller modules make it easier to focus on parts relevant to an issue
1 parent e0392eb commit 86ab3b7

23 files changed

+73
-60
lines changed

CONTRIBUTING.md

Lines changed: 9 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -17,20 +17,15 @@ Safe-PHP code is generated automatically from the PHP doc.
1717
### Generator
1818

1919
* `safe.php` is the CLI entry point, with a few utility commands, but the
20-
most important one is `generate`, which generates the Safe-PHP code.
21-
* `GenerateCommand` is the class that actually does the generation:
22-
* Call `Scanner` to get a list of all the PHP XML documentation files
23-
(returned in a `ScannerResponse`).
24-
* Use `DocPage` to parse each XML file and extract the relevant
25-
information.
26-
* The "relevant information" is a list of `Method`s, which have
27-
`Parameter`s, which have `Type`s.
28-
* (As well as taking some information from the PHP XML docs, we also
29-
take some type-hint information from PHPStan's type-hint database,
30-
and merge these sources together to get a more complete picture.)
31-
* Given a bunch of `Method` meta-data objects, `FileCreator` will create
32-
files in `generated/` and use `WritePhpFunction` to write safe wrappers
33-
for each function into those files.
20+
most important one is `\Safe\Commands\GenerateCommand`, which does the
21+
generation:
22+
* Use `\Safe\XmlDocParser` to parse the PHP XML documentation
23+
and pull out information about `Method`s, `Parameter`s, and
24+
`Type`s - try to figure out which methods are unsafe.
25+
* Use `\Safe\PhpStanFunctions` to get a bit of extra data from
26+
PHPStan's typehint database, and merge that with the XML info.
27+
* Given this list of unsafe functions, use `\Safe\Generator` to
28+
write a bunch of safe wrappers.
3429

3530
### End-Users
3631

generator/safe.php

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@
44

55
require __DIR__.'/vendor/autoload.php';
66

7-
use Safe\GenerateCommand;
8-
use Safe\ScanObjectsCommand;
9-
use Safe\FunctionInfoCommand;
7+
use Safe\Commands\FunctionInfoCommand;
8+
use Safe\Commands\GenerateCommand;
9+
use Safe\Commands\ScanObjectsCommand;
1010
use Symfony\Component\Console\Application;
1111

1212
$application = new Application();

generator/src/FunctionInfoCommand.php renamed to generator/src/Commands/FunctionInfoCommand.php

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,11 @@
22

33
declare(strict_types=1);
44

5-
namespace Safe;
5+
namespace Safe\Commands;
66

7+
use Safe\XmlDocParser\Scanner;
8+
use Safe\XmlDocParser\DocPage;
9+
use Safe\Generator\WritePhpFunction;
710
use Symfony\Component\Console\Command\Command;
811
use Symfony\Component\Console\Input\InputInterface;
912
use Symfony\Component\Console\Input\InputArgument;

generator/src/GenerateCommand.php renamed to generator/src/Commands/GenerateCommand.php

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,12 @@
22

33
declare(strict_types=1);
44

5-
namespace Safe;
5+
namespace Safe\Commands;
6+
7+
use Safe\XmlDocParser\Scanner;
8+
use Safe\XmlDocParser\DocPage;
9+
use Safe\Generator\FileCreator;
10+
use Safe\Generator\ComposerJsonEditor;
611

712
use Symfony\Component\Console\Command\Command;
813
use Symfony\Component\Console\Input\InputInterface;

generator/src/ScanObjectsCommand.php renamed to generator/src/Commands/ScanObjectsCommand.php

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,10 @@
22

33
declare(strict_types=1);
44

5-
namespace Safe;
5+
namespace Safe\Commands;
66

7+
use Safe\XmlDocParser\Scanner;
8+
use Safe\XmlDocParser\DocPage;
79
use Symfony\Component\Console\Command\Command;
810
use Symfony\Component\Console\Input\InputInterface;
911
use Symfony\Component\Console\Output\OutputInterface;

generator/src/ComposerJsonEditor.php renamed to generator/src/Generator/ComposerJsonEditor.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
declare(strict_types=1);
44

5-
namespace Safe;
5+
namespace Safe\Generator;
66

77
/**
88
* This class will edit the main composer.json file to add the list of files generated from modules.

generator/src/FileCreator.php renamed to generator/src/Generator/FileCreator.php

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,9 @@
22

33
declare(strict_types=1);
44

5-
namespace Safe;
5+
namespace Safe\Generator;
6+
7+
use Safe\XmlDocParser\Method;
68

79
use function array_merge;
810
use function file_exists;
@@ -151,7 +153,7 @@ public static function createFromPhpError(): self
151153

152154
public static function getSafeRootDir(): string
153155
{
154-
return __DIR__ . '/../..';
156+
return __DIR__ . '/../../..';
155157
}
156158

157159
/**

generator/src/WritePhpFunction.php renamed to generator/src/Generator/WritePhpFunction.php

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,10 @@
22

33
declare(strict_types=1);
44

5-
namespace Safe;
5+
namespace Safe\Generator;
6+
7+
use Safe\XmlDocParser\Method;
8+
use Safe\XmlDocParser\Parameter;
69

710
class WritePhpFunction
811
{

generator/src/PhpStanFunctions/PhpStanFunctionMapReader.php

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44

55
namespace Safe\PhpStanFunctions;
66

7+
use Safe\Generator\FileCreator;
8+
79
class PhpStanFunctionMapReader
810
{
911
/**
@@ -18,8 +20,8 @@ class PhpStanFunctionMapReader
1820

1921
public function __construct()
2022
{
21-
$this->functionMap = require 'phar://' . \Safe\FileCreator::getSafeRootDir() . '/generator/vendor/phpstan/phpstan/phpstan.phar/resources/functionMap.php';
22-
$this->customFunctionMap = require \Safe\FileCreator::getSafeRootDir() . '/generator/config/CustomPhpStanFunctionMap.php';
23+
$this->functionMap = require 'phar://' . FileCreator::getSafeRootDir() . '/generator/vendor/phpstan/phpstan/phpstan.phar/resources/functionMap.php';
24+
$this->customFunctionMap = require FileCreator::getSafeRootDir() . '/generator/config/CustomPhpStanFunctionMap.php';
2325
}
2426

2527
public function hasFunction(string $functionName): bool

generator/src/PhpStanFunctions/PhpStanParameter.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
namespace Safe\PhpStanFunctions;
66

7-
use Safe\Type;
7+
use Safe\XmlDocParser\Type;
88

99
class PhpStanParameter
1010
{

generator/src/PhpStanFunctions/PhpStanType.php

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@
44

55
namespace Safe\PhpStanFunctions;
66

7-
use Safe\Method;
8-
use Safe\Type;
7+
use Safe\XmlDocParser\Method;
8+
use Safe\XmlDocParser\Type;
99

1010
/**
1111
* This class will parse the type from either parameters or return as given by phpstan and generate appropriate doc-block comments or typehints

generator/src/DocPage.php renamed to generator/src/XmlDocParser/DocPage.php

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
declare(strict_types=1);
44

5-
namespace Safe;
5+
namespace Safe\XmlDocParser;
66

77
use function explode;
88
use function strpos;
@@ -15,7 +15,7 @@ public function __construct(private readonly string $path)
1515

1616
public static function findDocDir(): string
1717
{
18-
return __DIR__ . '/../doc';
18+
return __DIR__ . '/../../doc';
1919
}
2020

2121
public static function findReferenceDir(): string

generator/src/Method.php renamed to generator/src/XmlDocParser/Method.php

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,12 @@
22

33
declare(strict_types=1);
44

5-
namespace Safe;
5+
namespace Safe\XmlDocParser;
66

77
use Safe\PhpStanFunctions\PhpStanFunction;
88
use Safe\PhpStanFunctions\PhpStanFunctionMapReader;
99
use Safe\PhpStanFunctions\PhpStanType;
10+
use Safe\Generator\FileCreator;
1011

1112
class Method
1213
{

generator/src/Parameter.php renamed to generator/src/XmlDocParser/Parameter.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
declare(strict_types=1);
44

5-
namespace Safe;
5+
namespace Safe\XmlDocParser;
66

77
use Safe\PhpStanFunctions\PhpStanFunction;
88
use Safe\PhpStanFunctions\PhpStanParameter;

generator/src/Scanner.php renamed to generator/src/XmlDocParser/Scanner.php

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,12 @@
22

33
declare(strict_types=1);
44

5-
namespace Safe;
5+
namespace Safe\XmlDocParser;
66

77
use function array_merge;
88
use function iterator_to_array;
99
use Safe\PhpStanFunctions\PhpStanFunctionMapReader;
10+
use Safe\Generator\FileCreator;
1011
use Symfony\Component\Finder\Finder;
1112
use Symfony\Component\Console\Helper\ProgressBar;
1213
use Symfony\Component\Console\Output\OutputInterface;

generator/src/ScannerResponse.php renamed to generator/src/XmlDocParser/ScannerResponse.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
declare(strict_types=1);
44

5-
namespace Safe;
5+
namespace Safe\XmlDocParser;
66

77
class ScannerResponse
88
{

generator/src/Type.php renamed to generator/src/XmlDocParser/Type.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
declare(strict_types=1);
44

5-
namespace Safe;
5+
namespace Safe\XmlDocParser;
66

77
class Type
88
{

generator/tests/ComposerJsonEditorTest.php renamed to generator/tests/Generator/ComposerJsonEditorTest.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
declare(strict_types=1);
44

5-
namespace Safe;
5+
namespace Safe\Generator;
66

77
use PHPUnit\Framework\TestCase;
88

generator/tests/PhpStanFunctions/PhpStanTypeTest.php

Lines changed: 17 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,12 @@
44

55
namespace Safe\PhpStanFunctions;
66

7-
87
use PHPUnit\Framework\TestCase;
9-
use Safe\Method;
8+
use Safe\XmlDocParser\Method;
109

1110
class PhpStanTypeTest extends TestCase
1211
{
13-
public function testMixedTypes(): void
12+
public function testMixedTypes(): void
1413
{
1514
$param = new PhpStanType('array|string|int');
1615
$this->assertEquals('array|string|int', $param->getDocBlockType());
@@ -54,8 +53,8 @@ public function testGenerics(): void
5453
$this->assertEquals('array{0:float,1:float,2:float,3:float,4:float,5:float}', $param->getDocBlockType());
5554
$this->assertEquals('array', $param->getSignatureType());
5655
}
57-
58-
public function testNullable(): void
56+
57+
public function testNullable(): void
5958
{
6059
$param = new PhpStanType('array|null');
6160
$this->assertEquals(true, $param->isNullable());
@@ -77,8 +76,8 @@ public function testNullable(): void
7776
$this->assertEquals('\HashContext|null', $param->getDocBlockType());
7877
$this->assertEquals('?\HashContext', $param->getSignatureType());
7978
}
80-
81-
public function testParenthesisOutsideOfCallable(): void
79+
80+
public function testParenthesisOutsideOfCallable(): void
8281
{
8382
$param = new PhpStanType('(?int)|(?string)');
8483
$this->assertEquals(true, $param->isNullable());
@@ -93,8 +92,8 @@ public function testFalsable(): void
9392
$this->assertEquals('string|false', $param->getDocBlockType());
9493
$this->assertEquals('string', $param->getSignatureType());
9594
}
96-
97-
public function testResource(): void
95+
96+
public function testResource(): void
9897
{
9998
$param = new PhpStanType('resource');
10099
$this->assertEquals('resource', $param->getDocBlockType());
@@ -107,8 +106,8 @@ public function testNamespace(): void
107106
$this->assertEquals('\GMP', $param->getDocBlockType());
108107
$this->assertEquals('\GMP', $param->getSignatureType());
109108
}
110-
111-
public function testVoid(): void
109+
110+
public function testVoid(): void
112111
{
113112
$param = new PhpStanType('');
114113
$this->assertEquals('', $param->getDocBlockType());
@@ -122,8 +121,8 @@ public function testVoid(): void
122121
$this->assertEquals('void', $param->getDocBlockType());
123122
$this->assertEquals('void', $param->getSignatureType());
124123
}
125-
126-
public function testOciSpecialCases(): void
124+
125+
public function testOciSpecialCases(): void
127126
{
128127
$param = new PhpStanType('OCI-Collection');
129128
$this->assertEquals('\OCI-Collection', $param->getDocBlockType());
@@ -133,14 +132,14 @@ public function testOciSpecialCases(): void
133132
$this->assertEquals('\OCI-Lob', $param->getDocBlockType());
134133
$this->assertEquals('', $param->getSignatureType());
135134
}
136-
137-
public function testErrorTypeInteraction(): void
135+
136+
public function testErrorTypeInteraction(): void
138137
{
139138
//bool => void if the method is falsy
140139
$param = new PhpStanType('bool');
141140
$this->assertEquals('void', $param->getDocBlockType(Method::FALSY_TYPE));
142141
$this->assertEquals('void', $param->getSignatureType(Method::FALSY_TYPE));
143-
142+
144143
//int|false => int if the method is falsy
145144
$param = new PhpStanType('int|false');
146145
$this->assertEquals('int', $param->getDocBlockType(Method::FALSY_TYPE));
@@ -155,8 +154,8 @@ public function testErrorTypeInteraction(): void
155154
$this->assertEquals('array|null', $param->getDocBlockType(Method::FALSY_TYPE));
156155
$this->assertEquals('?array', $param->getSignatureType(Method::FALSY_TYPE));
157156
}
158-
159-
public function testDuplicateType(): void
157+
158+
public function testDuplicateType(): void
160159
{
161160
$param = new PhpStanType('array<string,string>|array<string,false>|array<string,array<int,mixed>>');
162161
$this->assertEquals('array<string,string>|array<string,false>|array<string,array<int,mixed>>', $param->getDocBlockType());

generator/tests/DocPageTest.php renamed to generator/tests/XmlDocParser/DocPageTest.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
declare(strict_types=1);
44

5-
namespace Safe;
5+
namespace Safe\XmlDocParser;
66

77
use PHPUnit\Framework\TestCase;
88

generator/tests/MethodTest.php renamed to generator/tests/XmlDocParser/MethodTest.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
declare(strict_types=1);
44

5-
namespace Safe;
5+
namespace Safe\XmlDocParser;
66

77
use PHPUnit\Framework\TestCase;
88
use Safe\PhpStanFunctions\PhpStanFunctionMapReader;

generator/tests/ScannerTest.php renamed to generator/tests/XmlDocParser/ScannerTest.php

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
declare(strict_types=1);
44

5-
namespace Safe;
5+
namespace Safe\XmlDocParser;
66

77
use PHPUnit\Framework\TestCase;
88

@@ -20,7 +20,7 @@ public function testGetMethodsPaths(): void
2020

2121
public function testGetFunctionsPaths(): void
2222
{
23-
$scanner = new Scanner(DocPage::findReferenceDir());
23+
$scanner = new Scanner(DocPage::findReferenceDir() . '/');
2424
$paths = $scanner->getMethodsPaths();
2525

2626
$this->assertArrayNotHasKey(DocPage::findReferenceDir() . '/filesystem/functions/chmod.xml', $paths);

generator/tests/TypeTest.php renamed to generator/tests/XmlDocParser/TypeTest.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
declare(strict_types=1);
44

5-
namespace Safe;
5+
namespace Safe\XmlDocParser;
66

77
use PHPUnit\Framework\TestCase;
88

0 commit comments

Comments
 (0)