From a64a1d58d6f702d02925e39069aaf259cedbe383 Mon Sep 17 00:00:00 2001 From: Aleksei Lebedev <1329824+LastDragon-ru@users.noreply.github.com> Date: Mon, 6 May 2024 09:22:30 +0400 Subject: [PATCH 01/14] New `Instruction` contract. --- .../documentator/src/Commands/Preprocess.php | 8 --- .../documentator/src/Preprocessor/Context.php | 13 ++++ .../Preprocessor/Contracts/Instruction.php | 24 ++++++- .../Contracts/ParameterizableInstruction.php | 10 +-- .../Contracts/ProcessableInstruction.php | 5 +- .../Preprocessor/Contracts/TargetResolver.php | 18 +++++ .../IncludeDocBlock/Instruction.php | 59 +++++----------- .../IncludeDocBlock/InstructionTest.php | 18 ++--- .../IncludeDocumentList/Instruction.php | 57 ++++++---------- .../IncludeDocumentList/InstructionTest.php | 18 +++-- .../IncludeExample/Instruction.php | 48 ++++++------- .../IncludeExample/InstructionTest.php | 41 ++++++++--- .../Instructions/IncludeExec/Instruction.php | 26 ++++--- .../IncludeExec/InstructionTest.php | 5 +- .../Instructions/IncludeExec/Target.php | 25 +++++++ .../Instructions/IncludeFile/Instruction.php | 36 ++++------ .../IncludeFile/InstructionTest.php | 16 ++--- .../IncludeGraphqlDirective/Instruction.php | 26 ++++--- .../InstructionTest.php | 13 ++-- .../IncludeGraphqlDirective/Target.php | 25 +++++++ .../IncludePackageList/Instruction.php | 68 ++++++++----------- .../IncludePackageList/InstructionTest.php | 18 +++-- .../IncludeTemplate/Instruction.php | 59 ++++++---------- .../IncludeTemplate/InstructionTest.php | 48 +++++-------- .../src/Preprocessor/Preprocessor.php | 11 ++- .../Preprocessor/Targets/DirectoryPath.php | 36 ++++++++++ .../Targets/DirectoryPathTest.php | 49 +++++++++++++ .../src/Preprocessor/Targets/FileContent.php | 28 ++++++++ .../src/Preprocessor/Targets/FilePath.php | 36 ++++++++++ .../src/Preprocessor/Targets/FilePathTest.php | 49 +++++++++++++ 30 files changed, 568 insertions(+), 325 deletions(-) create mode 100644 packages/documentator/src/Preprocessor/Context.php create mode 100644 packages/documentator/src/Preprocessor/Contracts/TargetResolver.php create mode 100644 packages/documentator/src/Preprocessor/Instructions/IncludeExec/Target.php create mode 100644 packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Target.php create mode 100644 packages/documentator/src/Preprocessor/Targets/DirectoryPath.php create mode 100644 packages/documentator/src/Preprocessor/Targets/DirectoryPathTest.php create mode 100644 packages/documentator/src/Preprocessor/Targets/FileContent.php create mode 100644 packages/documentator/src/Preprocessor/Targets/FilePath.php create mode 100644 packages/documentator/src/Preprocessor/Targets/FilePathTest.php diff --git a/packages/documentator/src/Commands/Preprocess.php b/packages/documentator/src/Commands/Preprocess.php index 46b7a7d87..064e097bc 100644 --- a/packages/documentator/src/Commands/Preprocess.php +++ b/packages/documentator/src/Commands/Preprocess.php @@ -183,14 +183,6 @@ protected function getInstructionsHelp(): string { * @return array */ protected function getInstructionParameters(string $instruction): array { - // Explicit? (deprecated) - $parameters = $instruction::getParametersDescription(); - - if ($parameters) { - return $parameters; - } - - // Nope $class = new ReflectionClass($instruction::getParameters()); $properties = $class->getProperties(ReflectionProperty::IS_PUBLIC); $parameters = []; diff --git a/packages/documentator/src/Preprocessor/Context.php b/packages/documentator/src/Preprocessor/Context.php new file mode 100644 index 000000000..e4a143729 --- /dev/null +++ b/packages/documentator/src/Preprocessor/Context.php @@ -0,0 +1,13 @@ + + */ interface Instruction { public static function getName(): string; - public static function getDescription(): string; + /** + * @return class-string + */ + public static function getTarget(): string; + + /** + * @return class-string|null + */ + public static function getParameters(): ?string; - public static function getTargetDescription(): ?string; + /** + * @param Context $context + * @param TTargetValue $target + * @param TParameters $parameters + */ + public function process(Context $context, mixed $target, mixed $parameters): string; } diff --git a/packages/documentator/src/Preprocessor/Contracts/ParameterizableInstruction.php b/packages/documentator/src/Preprocessor/Contracts/ParameterizableInstruction.php index d00c38b87..720575675 100644 --- a/packages/documentator/src/Preprocessor/Contracts/ParameterizableInstruction.php +++ b/packages/documentator/src/Preprocessor/Contracts/ParameterizableInstruction.php @@ -5,21 +5,15 @@ use LastDragon_ru\LaraASP\Serializer\Contracts\Serializable; /** + * @deprecated * @template TParameters of Serializable */ -interface ParameterizableInstruction extends Instruction { +interface ParameterizableInstruction { /** * @return class-string */ public static function getParameters(): string; - /** - * @deprecated 6.2.0 Use docblock instead. - * - * @return array - */ - public static function getParametersDescription(): array; - /** * @param TParameters $parameters */ diff --git a/packages/documentator/src/Preprocessor/Contracts/ProcessableInstruction.php b/packages/documentator/src/Preprocessor/Contracts/ProcessableInstruction.php index 7e3211de3..762c0788a 100644 --- a/packages/documentator/src/Preprocessor/Contracts/ProcessableInstruction.php +++ b/packages/documentator/src/Preprocessor/Contracts/ProcessableInstruction.php @@ -2,6 +2,9 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts; -interface ProcessableInstruction extends Instruction { +/** + * @deprecated + */ +interface ProcessableInstruction { public function process(string $path, string $target): string; } diff --git a/packages/documentator/src/Preprocessor/Contracts/TargetResolver.php b/packages/documentator/src/Preprocessor/Contracts/TargetResolver.php new file mode 100644 index 000000000..dd8cbbc72 --- /dev/null +++ b/packages/documentator/src/Preprocessor/Contracts/TargetResolver.php @@ -0,0 +1,18 @@ + + * Includes the docblock of the first PHP class/interface/trait/enum/etc + * from `` file. Inline tags include as is except `@see`/`@link` + * which will be replaced to FQCN (if possible). Other tags are ignored. + * + * @implements InstructionContract> */ -class Instruction implements ParameterizableInstruction { +class Instruction implements InstructionContract { public function __construct() { // empty } @@ -40,44 +41,19 @@ public static function getName(): string { } #[Override] - public static function getDescription(): string { - return <<<'DESC' - Includes the docblock of the first PHP class/interface/trait/enum/etc - from `` file. Inline tags include as is except `@see`/`@link` - which will be replaced to FQCN (if possible). Other tags are ignored. - DESC; + public static function getTarget(): string { + return FileContent::class; } #[Override] - public static function getTargetDescription(): ?string { - return 'File path.'; - } - - #[Override] - public static function getParameters(): string { + public static function getParameters(): ?string { return Parameters::class; } - /** - * @inheritDoc - */ #[Override] - public static function getParametersDescription(): array { - return []; - } - - #[Override] - public function process(string $path, string $target, Serializable $parameters): string { - // File? - $file = Path::getPath(dirname($path), $target); - $content = file_get_contents($file); - - if ($content === false) { - throw new TargetIsNotFile($path, $target); - } - + public function process(Context $context, mixed $target, mixed $parameters): string { // Class? - [$class, $context] = ((array) $this->getClass($content, $path, $target) + [null, null]); + [$class, $context] = ((array) $this->getClass($context, $target) + [null, null]); if (!$class || !$context) { return ''; @@ -109,22 +85,21 @@ public function process(string $path, string $target, Serializable $parameters): /** * @return array{ClassLike, NameContext}|null */ - private function getClass(string $content, string $path, string $target): ?array { + private function getClass(Context $context, string $content): ?array { try { $class = null; $resolver = new NameResolver(); $stmts = $this->parse($resolver, $content); - $context = $resolver->getNameContext(); $finder = new NodeFinder(); $class = $finder->findFirst($stmts, static function (Node $node): bool { return $node instanceof ClassLike; }); } catch (Exception $exception) { - throw new TargetIsNotValidPhpFile($path, $target, $exception); + throw new TargetIsNotValidPhpFile($context->path, $context->target, $exception); } return $class instanceof ClassLike - ? [$class, $context] + ? [$class, $resolver->getNameContext()] : null; } diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeDocBlock/InstructionTest.php b/packages/documentator/src/Preprocessor/Instructions/IncludeDocBlock/InstructionTest.php index 98342fc3c..b286de2d4 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeDocBlock/InstructionTest.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeDocBlock/InstructionTest.php @@ -3,11 +3,13 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Instructions\IncludeDocBlock; use Exception; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\TargetIsNotValidPhpFile; use LastDragon_ru\LaraASP\Documentator\Testing\Package\TestCase; use PHPUnit\Framework\Attributes\CoversClass; use PHPUnit\Framework\Attributes\DataProvider; +use function file_get_contents; use function str_replace; /** @@ -19,26 +21,18 @@ final class InstructionTest extends TestCase { // ========================================================================= #[DataProvider('dataProviderProcess')] public function testProcess(Exception|string $expected, string $file, Parameters $params): void { - $file = self::getTestData()->file($file); - $instance = $this->app()->make(Instruction::class); - if ($expected instanceof Exception) { self::expectExceptionObject($expected); } else { $expected = self::getTestData()->content($expected); } - self::assertEquals($expected, $instance->process($file->getPathname(), $file->getFilename(), $params)); - } - - public function testProcessAbsolute(): void { - $path = 'invalid/directory'; - $file = self::getTestData()->path('Valid.txt'); - $params = new Parameters(); + $file = self::getTestData()->file($file); + $target = (string) file_get_contents($file->getPathname()); + $context = new Context($file->getPathname(), $file->getFilename(), null); $instance = $this->app()->make(Instruction::class); - $expected = self::getTestData()->content('ValidExpected.txt'); - self::assertEquals($expected, $instance->process($path, $file, $params)); + self::assertEquals($expected, $instance->process($context, $target, $params)); } // diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/Instruction.php index a591cca1f..bcb50452d 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/Instruction.php @@ -4,25 +4,28 @@ use LastDragon_ru\LaraASP\Core\Utils\Path; use LastDragon_ru\LaraASP\Documentator\PackageViewer; -use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\ParameterizableInstruction; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\Instruction as InstructionContract; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\DocumentTitleIsMissing; -use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\TargetIsNotDirectory; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Targets\DirectoryPath; use LastDragon_ru\LaraASP\Documentator\Utils\Markdown; -use LastDragon_ru\LaraASP\Serializer\Contracts\Serializable; use Override; use Symfony\Component\Finder\Finder; use function basename; use function dirname; use function file_get_contents; -use function is_dir; use function strcmp; use function usort; /** - * @implements ParameterizableInstruction + * Returns the list of `*.md` files in the `` directory. Each file + * must have `# Header` as the first construction. The first paragraph + * after the Header will be used as a summary. + * + * @implements InstructionContract> */ -class Instruction implements ParameterizableInstruction { +class Instruction implements InstructionContract { public function __construct( protected readonly PackageViewer $viewer, ) { @@ -35,45 +38,23 @@ public static function getName(): string { } #[Override] - public static function getDescription(): string { - return <<<'DESC' - Returns the list of `*.md` files in the `` directory. Each file - must have `# Header` as the first construction. The first paragraph - after the Header will be used as a summary. - DESC; + public static function getTarget(): string { + return DirectoryPath::class; } #[Override] - public static function getTargetDescription(): ?string { - return 'Directory path.'; - } - - #[Override] - public static function getParameters(): string { + public static function getParameters(): ?string { return Parameters::class; } - /** - * @inheritDoc - */ #[Override] - public static function getParametersDescription(): array { - return []; - } - - #[Override] - public function process(string $path, string $target, Serializable $parameters): string { - // Directory? - $base = dirname($path); - $root = Path::getPath($base, $target); - - if (!is_dir($root)) { - throw new TargetIsNotDirectory($path, $target); - } - + public function process(Context $context, mixed $target, mixed $parameters): string { /** @var list $documents */ $documents = []; - $target = Path::normalize($target); + $path = basename($context->path); + $base = dirname($context->path); + $root = $target; + $target = Path::normalize($context->target); $finder = Finder::create()->in($root)->name('*.md'); if ($parameters->depth !== null) { @@ -82,7 +63,7 @@ public function process(string $path, string $target, Serializable $parameters): foreach ($finder->files() as $file) { // Same? - if ($target === '' && $file->getFilename() === basename($path)) { + if ($target === '' && $file->getFilename() === $path) { continue; } @@ -104,7 +85,7 @@ public function process(string $path, string $target, Serializable $parameters): 'summary' => Markdown::getSummary($content), ]; } else { - throw new DocumentTitleIsMissing($path, $target, $docPath); + throw new DocumentTitleIsMissing($context->path, $context->target, $docPath); } } diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/InstructionTest.php b/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/InstructionTest.php index 72f37990b..4bbcc34b6 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/InstructionTest.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/InstructionTest.php @@ -2,7 +2,9 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Instructions\IncludeDocumentList; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\DocumentTitleIsMissing; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Targets\DirectoryPath; use LastDragon_ru\LaraASP\Documentator\Testing\Package\TestCase; use PHPUnit\Framework\Attributes\CoversClass; @@ -16,8 +18,10 @@ final class InstructionTest extends TestCase { public function testProcessSameDirectory(): void { $path = self::getTestData()->file('Document.md'); $params = new Parameters(); + $context = new Context($path->getPathname(), './', ''); $instance = $this->app()->make(Instruction::class); - $actual = $instance->process($path->getPathname(), './', $params); + $target = (new DirectoryPath())->resolve($context, $params); + $actual = $instance->process($context, $target, $params); self::assertEquals( self::getTestData()->content('~SameDirectory.md'), @@ -32,8 +36,10 @@ public function testProcessSameDirectory(): void { public function testProcessAnotherDirectory(): void { $path = self::getTestData()->file('~AnotherDirectory.md'); $params = new Parameters(); + $context = new Context($path->getPathname(), basename(self::getTestData()->path('/')), ''); $instance = $this->app()->make(Instruction::class); - $actual = $instance->process($path->getPathname(), basename(self::getTestData()->path('/')), $params); + $target = (new DirectoryPath())->resolve($context, $params); + $actual = $instance->process($context, $target, $params); self::assertEquals( self::getTestData()->content('~AnotherDirectory.md'), @@ -48,8 +54,10 @@ public function testProcessAnotherDirectory(): void { public function testProcessNestedDirectories(): void { $path = self::getTestData()->file('nested/Document.md'); $params = new Parameters(null); + $context = new Context($path->getPathname(), './', ''); $instance = $this->app()->make(Instruction::class); - $actual = $instance->process($path->getPathname(), './', $params); + $target = (new DirectoryPath())->resolve($context, $params); + $actual = $instance->process($context, $target, $params); self::assertEquals( self::getTestData()->content('~NestedDirectories.md'), @@ -65,7 +73,9 @@ public function testProcessWithoutTitle(): void { $path = self::getTestData()->file('invalid/Document.md'); $target = './'; $params = new Parameters(); + $context = new Context($path->getPathname(), './', ''); $instance = $this->app()->make(Instruction::class); + $target = (new DirectoryPath())->resolve($context, $params); self::expectExceptionObject( new DocumentTitleIsMissing( @@ -75,6 +85,6 @@ public function testProcessWithoutTitle(): void { ), ); - $instance->process($path->getPathname(), $target, $params); + $instance->process($context, $target, $params); } } diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeExample/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeExample/Instruction.php index baeb6dc66..281427769 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeExample/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeExample/Instruction.php @@ -5,13 +5,13 @@ use Exception; use Illuminate\Process\Factory; use LastDragon_ru\LaraASP\Core\Utils\Path; -use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\ProcessableInstruction; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\Instruction as InstructionContract; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\TargetExecFailed; -use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\TargetIsNotFile; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Targets\FileContent; use Override; use function dirname; -use function file_get_contents; use function is_file; use function pathinfo; use function preg_match; @@ -22,7 +22,18 @@ use const PATHINFO_EXTENSION; use const PREG_UNMATCHED_AS_NULL; -class Instruction implements ProcessableInstruction { +/** + * Includes contents of the `` file as an example wrapped into + * ` ```code block``` `. It also searches for `.run` file, execute + * it if found, and include its result right after the code block. + * + * By default, output of `.run` will be included as ` ```plain text``` ` + * block. You can wrap the output into `text` tags to + * insert it as is. + * + * @implements InstructionContract> + */ +class Instruction implements InstructionContract { public const Limit = 50; protected const MarkdownRegexp = '/^\<(?Pmarkdown)\>(?P.*?)\<\/(?P=tag)\>$/msu'; @@ -38,32 +49,21 @@ public static function getName(): string { } #[Override] - public static function getDescription(): string { - return <<<'DESC' - Includes contents of the `` file as an example wrapped into - ` ```code block``` `. It also searches for `.run` file, execute - it if found, and include its result right after the code block. - - By default, output of `.run` will be included as ` ```plain text``` ` - block. You can wrap the output into `text` tags to - insert it as is. - DESC; + public static function getTarget(): string { + return FileContent::class; } #[Override] - public static function getTargetDescription(): ?string { - return 'Example file path.'; + public static function getParameters(): ?string { + return null; } #[Override] - public function process(string $path, string $target): string { - // Content - $file = Path::getPath(dirname($path), $target); - $content = file_get_contents($file); - - if ($content === false) { - throw new TargetIsNotFile($path, $target); - } + public function process(Context $context, mixed $target, mixed $parameters): string { + // Prepare + $content = $target; + $target = $context->target; + $path = $context->path; // Process $language = $this->getLanguage($path, $target); diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeExample/InstructionTest.php b/packages/documentator/src/Preprocessor/Instructions/IncludeExample/InstructionTest.php index 88594b80e..55eaffeb2 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeExample/InstructionTest.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeExample/InstructionTest.php @@ -4,6 +4,7 @@ use Illuminate\Process\Factory; use Illuminate\Process\PendingProcess; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; use LastDragon_ru\LaraASP\Documentator\Testing\Package\TestCase; use PHPUnit\Framework\Attributes\CoversClass; @@ -21,13 +22,17 @@ final class InstructionTest extends TestCase { public function testProcessNoRun(): void { $path = self::getTestData()->path('~example.md'); $file = basename(self::getTestData()->path('~example.md')); - $expected = trim(self::getTestData()->content('~example.md')); + $params = null; + $context = new Context($path, $file, $params); + $content = self::getTestData()->content('~example.md'); + $expected = trim($content); $factory = $this->override(Factory::class, function (): Factory { return $this->app()->make(Factory::class) ->preventStrayProcesses() ->fake(); }); $instance = $this->app()->make(Instruction::class); + $actual = $instance->process($context, $content, $params); self::assertEquals( <<process($path, $file), + $actual, ); $factory->assertNothingRan(); @@ -44,8 +49,11 @@ public function testProcessNoRun(): void { public function testProcess(): void { $path = self::getTestData()->path('~runnable.md'); $file = basename(self::getTestData()->path('~runnable.md')); + $params = null; + $context = new Context($path, $file, $params); + $content = self::getTestData()->content('~runnable.md'); $command = self::getTestData()->path('~runnable.run'); - $expected = trim(self::getTestData()->content('~runnable.md')); + $expected = trim($content); $output = 'command output'; $factory = $this->override(Factory::class, function () use ($command, $output): Factory { $factory = $this->app()->make(Factory::class); @@ -57,6 +65,7 @@ public function testProcess(): void { return $factory; }); $instance = $this->app()->make(Instruction::class); + $actual = $instance->process($context, $content, $params); self::assertEquals( <<process($path, $file), + $actual, ); $factory->assertRan(static function (PendingProcess $process) use ($path, $command): bool { @@ -82,8 +91,11 @@ public function testProcess(): void { public function testProcessLongOutput(): void { $path = self::getTestData()->path('~runnable.md'); $file = self::getTestData()->path('~runnable.md'); + $params = null; + $context = new Context($path, $file, $params); + $content = self::getTestData()->content('~runnable.md'); $command = self::getTestData()->path('~runnable.run'); - $expected = trim(self::getTestData()->content('~runnable.md')); + $expected = trim($content); $output = implode("\n", range(0, Instruction::Limit + 1)); $factory = $this->override(Factory::class, function () use ($command, $output): Factory { $factory = $this->app()->make(Factory::class); @@ -95,6 +107,7 @@ public function testProcessLongOutput(): void { return $factory; }); $instance = $this->app()->make(Instruction::class); + $actual = $instance->process($context, $content, $params); self::assertEquals( << EXPECTED, - $instance->process($path, $file), + $actual, ); $factory->assertRan(static function (PendingProcess $process) use ($path, $command): bool { @@ -122,8 +135,11 @@ public function testProcessLongOutput(): void { public function testProcessMarkdown(): void { $path = self::getTestData()->path('~runnable.md'); $file = basename(self::getTestData()->path('~runnable.md')); + $params = null; + $context = new Context($path, $file, $params); + $content = self::getTestData()->content('~runnable.md'); $command = self::getTestData()->path('~runnable.run'); - $expected = trim(self::getTestData()->content('~runnable.md')); + $expected = trim($content); $output = 'command output'; $factory = $this->override(Factory::class, function () use ($command, $output): Factory { $factory = $this->app()->make(Factory::class); @@ -135,6 +151,7 @@ public function testProcessMarkdown(): void { return $factory; }); $instance = $this->app()->make(Instruction::class); + $actual = $instance->process($context, $content, $params); self::assertEquals( <<process($path, $file), + $actual, ); $factory->assertRan(static function (PendingProcess $process) use ($path, $command): bool { @@ -156,8 +173,11 @@ public function testProcessMarkdown(): void { public function testProcessMarkdownLongOutput(): void { $path = self::getTestData()->path('~runnable.md'); $file = self::getTestData()->path('~runnable.md'); + $params = null; + $context = new Context($path, $file, $params); + $content = self::getTestData()->content('~runnable.md'); $command = self::getTestData()->path('~runnable.run'); - $expected = trim(self::getTestData()->content('~runnable.md')); + $expected = trim($content); $output = implode("\n", range(0, Instruction::Limit + 1)); $factory = $this->override(Factory::class, function () use ($command, $output): Factory { $factory = $this->app()->make(Factory::class); @@ -169,6 +189,7 @@ public function testProcessMarkdownLongOutput(): void { return $factory; }); $instance = $this->app()->make(Instruction::class); + $actual = $instance->process($context, $content, $params); self::assertEquals( << EXPECTED, - $instance->process($path, $file), + $actual, ); $factory->assertRan(static function (PendingProcess $process) use ($path, $command): bool { diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeExec/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeExec/Instruction.php index b206365b7..96eba9602 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeExec/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeExec/Instruction.php @@ -4,14 +4,20 @@ use Exception; use Illuminate\Process\Factory; -use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\ProcessableInstruction; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\Instruction as InstructionContract; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\TargetExecFailed; use Override; use function dirname; use function trim; -class Instruction implements ProcessableInstruction { +/** + * Executes the `` and returns result. + * + * @implements InstructionContract> + */ +class Instruction implements InstructionContract { public function __construct( protected readonly Factory $factory, ) { @@ -24,21 +30,23 @@ public static function getName(): string { } #[Override] - public static function getDescription(): string { - return 'Executes the `` and returns result.'; + public static function getTarget(): string { + return Target::class; } #[Override] - public static function getTargetDescription(): ?string { - return 'Path to the executable.'; + public static function getParameters(): ?string { + return null; } #[Override] - public function process(string $path, string $target): string { + public function process(Context $context, mixed $target, mixed $parameters): string { try { - return trim($this->factory->newPendingProcess()->path(dirname($path))->run($target)->throw()->output()); + return trim( + $this->factory->newPendingProcess()->path(dirname($context->path))->run($target)->throw()->output(), + ); } catch (Exception $exception) { - throw new TargetExecFailed($path, $target, $exception); + throw new TargetExecFailed($context->path, $context->target, $exception); } } } diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeExec/InstructionTest.php b/packages/documentator/src/Preprocessor/Instructions/IncludeExec/InstructionTest.php index ecacc3b0a..c5a4066d2 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeExec/InstructionTest.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeExec/InstructionTest.php @@ -4,6 +4,7 @@ use Illuminate\Process\Factory; use Illuminate\Process\PendingProcess; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; use LastDragon_ru\LaraASP\Documentator\Testing\Package\TestCase; use PHPUnit\Framework\Attributes\CoversClass; @@ -16,8 +17,10 @@ final class InstructionTest extends TestCase { public function testProcess(): void { $path = 'current/working/directory/file.md'; + $params = null; $expected = 'result'; $command = 'command to execute'; + $context = new Context($path, $command, $params); $factory = $this->override(Factory::class, function () use ($command, $expected): Factory { $factory = $this->app()->make(Factory::class); $factory->preventStrayProcesses(); @@ -29,7 +32,7 @@ public function testProcess(): void { }); $instance = $this->app()->make(Instruction::class); - self::assertEquals($expected, $instance->process($path, $command)); + self::assertEquals($expected, $instance->process($context, $command, $params)); $factory->assertRan(static function (PendingProcess $process) use ($path, $command): bool { return $process->path === dirname($path) diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeExec/Target.php b/packages/documentator/src/Preprocessor/Instructions/IncludeExec/Target.php new file mode 100644 index 000000000..f82e58c97 --- /dev/null +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeExec/Target.php @@ -0,0 +1,25 @@ + + */ +class Target implements TargetResolver { + public function __construct() { + // empty + } + + #[Override] + public function resolve(Context $context, mixed $parameters): string { + return $context->target; + } +} diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeFile/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeFile/Instruction.php index 706f1f34a..f1a6e9b38 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeFile/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeFile/Instruction.php @@ -2,16 +2,19 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Instructions\IncludeFile; -use LastDragon_ru\LaraASP\Core\Utils\Path; -use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\ProcessableInstruction; -use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\TargetIsNotFile; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\Instruction as InstructionContract; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Targets\FileContent; use Override; -use function dirname; -use function file_get_contents; use function rtrim; -class Instruction implements ProcessableInstruction { +/** + * Includes the `` file. + * + * @implements InstructionContract> + */ +class Instruction implements InstructionContract { public function __construct() { // empty } @@ -22,26 +25,17 @@ public static function getName(): string { } #[Override] - public static function getDescription(): string { - return 'Includes the `` file.'; + public static function getTarget(): string { + return FileContent::class; } #[Override] - public static function getTargetDescription(): ?string { - return 'File path.'; + public static function getParameters(): ?string { + return null; } #[Override] - public function process(string $path, string $target): string { - // Content - $file = Path::getPath(dirname($path), $target); - $content = file_get_contents($file); - - if ($content === false) { - throw new TargetIsNotFile($path, $target); - } - - // Return - return rtrim($content)."\n"; + public function process(Context $context, mixed $target, mixed $parameters): string { + return rtrim($target)."\n"; } } diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeFile/InstructionTest.php b/packages/documentator/src/Preprocessor/Instructions/IncludeFile/InstructionTest.php index 0daa3b58c..d71462be5 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeFile/InstructionTest.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeFile/InstructionTest.php @@ -2,6 +2,7 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Instructions\IncludeFile; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; use LastDragon_ru\LaraASP\Documentator\Testing\Package\TestCase; use PHPUnit\Framework\Attributes\CoversClass; @@ -10,20 +11,13 @@ */ #[CoversClass(Instruction::class)] final class InstructionTest extends TestCase { - public function testProcessRelative(): void { - $file = self::getTestData()->file('.md'); - $instance = $this->app()->make(Instruction::class); - $expected = self::getTestData()->content('.md'); - - self::assertEquals($expected, $instance->process($file->getPathname(), $file->getFilename())); - } - - public function testProcessAbsolute(): void { - $path = 'invalid/directory'; + public function testProcess(): void { $file = self::getTestData()->path('.md'); + $params = null; + $context = new Context($file, $file, $params); $instance = $this->app()->make(Instruction::class); $expected = self::getTestData()->content('.md'); - self::assertEquals($expected, $instance->process($path, $file)); + self::assertEquals($expected, $instance->process($context, $expected, $params)); } } diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Instruction.php index 6cc2f31fa..db27e12a4 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Instruction.php @@ -2,7 +2,8 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Instructions\IncludeGraphqlDirective; -use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\ProcessableInstruction; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\Instruction as InstructionContract; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\DependencyIsMissing; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\TargetIsNotDirective; use LastDragon_ru\LaraASP\GraphQLPrinter\Contracts\Printer; @@ -12,7 +13,12 @@ use function mb_substr; use function trim; -class Instruction implements ProcessableInstruction { +/** + * Includes the definition of the directive as a Markdown code block. + * + * @implements InstructionContract> + */ +class Instruction implements InstructionContract { public function __construct( protected readonly ?Printer $printer = null, ) { @@ -25,22 +31,20 @@ public static function getName(): string { } #[Override] - public static function getDescription(): string { - return <<<'DESC' - Includes the definition of the directive as a Markdown code block. - DESC; + public static function getTarget(): string { + return Target::class; } #[Override] - public static function getTargetDescription(): ?string { - return 'Directive name (started with `@` sign)'; + public static function getParameters(): ?string { + return null; } #[Override] - public function process(string $path, string $target): string { + public function process(Context $context, mixed $target, mixed $parameters): string { // Dependencies? if (!$this->printer) { - throw new DependencyIsMissing($path, $target, Printer::class); + throw new DependencyIsMissing($context->path, $context->target, Printer::class); } // Directive? @@ -48,7 +52,7 @@ public function process(string $path, string $target): string { $definition = $this->printer->getDirectiveResolver()?->getDefinition($directive); if ($definition === null) { - throw new TargetIsNotDirective($path, $target); + throw new TargetIsNotDirective($context->path, $context->target); } // Print diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/InstructionTest.php b/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/InstructionTest.php index 859679709..71ef4d359 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/InstructionTest.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/InstructionTest.php @@ -3,6 +3,7 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Instructions\IncludeGraphqlDirective; use GraphQL\Language\Parser; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\DependencyIsMissing; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\TargetIsNotDirective; use LastDragon_ru\LaraASP\Documentator\Testing\Package\TestCase; @@ -41,7 +42,8 @@ public function testProcess(): void { }); $instance = $this->app()->make(Instruction::class); - $actual = $instance->process('path/to/file.md', '@test'); + $context = new Context('path/to/file.md', '@test', null); + $actual = $instance->process($context, $context->target, null); self::assertEquals( <<app()->make(Instruction::class); self::expectExceptionObject( new DependencyIsMissing($path, $target, PrinterContract::class), ); - $instance->process($path, $target); + $instance->process($context, $context->target, null); } public function testProcessNoDirective(): void { @@ -83,13 +86,14 @@ public function testProcessNoDirective(): void { $path = 'path/to/file.md'; $target = '@test'; + $context = new Context($path, $target, null); $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( new TargetIsNotDirective($path, $target), ); - $instance->process($path, $target); + $instance->process($context, $context->target, null); } public function testProcessNoDirectiveResolver(): void { @@ -99,12 +103,13 @@ public function testProcessNoDirectiveResolver(): void { $path = 'path/to/file.md'; $target = '@test'; + $context = new Context($path, $target, null); $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( new TargetIsNotDirective($path, $target), ); - $instance->process($path, $target); + $instance->process($context, $context->target, null); } } diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Target.php b/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Target.php new file mode 100644 index 000000000..b1a5c58a1 --- /dev/null +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Target.php @@ -0,0 +1,25 @@ + + */ +class Target implements TargetResolver { + public function __construct() { + // empty + } + + #[Override] + public function resolve(Context $context, mixed $parameters): string { + return $context->target; + } +} diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/Instruction.php index da81f23a2..b742bb3b0 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/Instruction.php @@ -5,21 +5,20 @@ use Exception; use LastDragon_ru\LaraASP\Core\Utils\Path; use LastDragon_ru\LaraASP\Documentator\PackageViewer; -use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\ParameterizableInstruction; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\Instruction as InstructionContract; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\DocumentTitleIsMissing; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\PackageComposerJsonIsMissing; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\PackageReadmeIsMissing; -use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\TargetIsNotDirectory; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Targets\DirectoryPath; use LastDragon_ru\LaraASP\Documentator\Utils\Markdown; -use LastDragon_ru\LaraASP\Serializer\Contracts\Serializable; use Override; use Symfony\Component\Finder\Finder; use function assert; -use function dirname; +use function basename; use function file_get_contents; use function is_array; -use function is_dir; use function is_file; use function is_string; use function json_decode; @@ -29,9 +28,12 @@ use const JSON_THROW_ON_ERROR; /** - * @implements ParameterizableInstruction + * Generates package list from `` directory. The readme file will be + * used to determine package name and summary. + * + * @implements InstructionContract> */ -class Instruction implements ParameterizableInstruction { +class Instruction implements InstructionContract { public function __construct( protected readonly PackageViewer $viewer, ) { @@ -44,45 +46,23 @@ public static function getName(): string { } #[Override] - public static function getDescription(): string { - return <<<'DESC' - Generates package list from `` directory. The readme file will be - used to determine package name and summary. - DESC; + public static function getTarget(): string { + return DirectoryPath::class; } #[Override] - public static function getTargetDescription(): ?string { - return 'Directory path.'; - } - - #[Override] - public static function getParameters(): string { + public static function getParameters(): ?string { return Parameters::class; } - /** - * @inheritDoc - */ #[Override] - public static function getParametersDescription(): array { - return []; - } - - #[Override] - public function process(string $path, string $target, Serializable $parameters): string { - // Directory? - $root = Path::getPath(dirname($path), $target); - - if (!is_dir($root)) { - throw new TargetIsNotDirectory($path, $target); - } - + public function process(Context $context, mixed $target, mixed $parameters): string { /** @var list $packages */ $packages = []; + $basePath = basename($target); $directories = Finder::create() ->ignoreVCSIgnored(true) - ->in($root) + ->in($target) ->depth(0) ->exclude('vendor') ->exclude('node_modules') @@ -94,7 +74,11 @@ public function process(string $path, string $target, Serializable $parameters): $packageInfo = $this->getPackageInfo($packagePath); if (!$packageInfo) { - throw new PackageComposerJsonIsMissing($path, $target, Path::join($target, $package->getFilename())); + throw new PackageComposerJsonIsMissing( + $context->path, + $context->target, + Path::join($basePath, $package->getFilename()), + ); } // Readme @@ -104,17 +88,21 @@ public function process(string $path, string $target, Serializable $parameters): : false; if (!$readme || $content === false) { - throw new PackageReadmeIsMissing($path, $target, Path::join($target, $package->getFilename())); + throw new PackageReadmeIsMissing( + $context->path, + $context->target, + Path::join($basePath, $package->getFilename()), + ); } // Extract $packageTitle = Markdown::getTitle($content); - $readmePath = Path::join($target, $package->getFilename(), $readme); + $readmePath = Path::join($basePath, $package->getFilename(), $readme); if ($packageTitle) { $upgrade = $this->getPackageUpgrade($packagePath, $packageInfo); $upgradePath = $upgrade - ? Path::join($target, $package->getFilename(), $upgrade) + ? Path::join($basePath, $package->getFilename(), $upgrade) : null; $packages[] = [ @@ -124,7 +112,7 @@ public function process(string $path, string $target, Serializable $parameters): 'upgrade' => $upgradePath, ]; } else { - throw new DocumentTitleIsMissing($path, $target, $readmePath); + throw new DocumentTitleIsMissing($context->path, $context->target, $readmePath); } } diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/InstructionTest.php b/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/InstructionTest.php index 6ff66e21c..cfb4bfdd3 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/InstructionTest.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/InstructionTest.php @@ -2,9 +2,11 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Instructions\IncludePackageList; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\DocumentTitleIsMissing; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\PackageComposerJsonIsMissing; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\PackageReadmeIsMissing; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Targets\DirectoryPath; use LastDragon_ru\LaraASP\Documentator\Testing\Package\TestCase; use PHPUnit\Framework\Attributes\CoversClass; use PHPUnit\Framework\Attributes\DataProvider; @@ -23,8 +25,10 @@ public function testProcess(string $expected, string $template): void { $path = self::getTestData()->file('Document.md')->getPathname(); $target = basename(self::getTestData()->path('/packages')); $params = new Parameters(template: $template); + $context = new Context($path, $target, ''); + $resolved = (new DirectoryPath())->resolve($context, $params); $instance = $this->app()->make(Instruction::class); - $actual = $instance->process($path, $target, $params); + $actual = $instance->process($context, $resolved, $params); self::assertEquals( self::getTestData()->content($expected), @@ -40,6 +44,8 @@ public function testProcessNotAPackage(): void { $path = self::getTestData()->file('Document.md')->getPathname(); $target = basename(self::getTestData()->path('/invalid')); $params = new Parameters(); + $context = new Context($path, $target, ''); + $resolved = (new DirectoryPath())->resolve($context, $params); $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( @@ -50,13 +56,15 @@ public function testProcessNotAPackage(): void { ), ); - $instance->process($path, $target, $params); + $instance->process($context, $resolved, $params); } public function testProcessNoReadme(): void { $path = self::getTestData()->file('Document.md')->getPathname(); $target = basename(self::getTestData()->path('/no readme')); $params = new Parameters(); + $context = new Context($path, $target, ''); + $resolved = (new DirectoryPath())->resolve($context, $params); $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( @@ -67,13 +75,15 @@ public function testProcessNoReadme(): void { ), ); - $instance->process($path, $target, $params); + $instance->process($context, $resolved, $params); } public function testProcessNoTitle(): void { $path = self::getTestData()->file('Document.md')->getPathname(); $target = basename(self::getTestData()->path('/no title')); $params = new Parameters(); + $context = new Context($path, $target, ''); + $resolved = (new DirectoryPath())->resolve($context, $params); $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( @@ -84,7 +94,7 @@ public function testProcessNoTitle(): void { ), ); - $instance->process($path, $target, $params); + $instance->process($context, $resolved, $params); } // diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeTemplate/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeTemplate/Instruction.php index dd46bb763..2c91c8331 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeTemplate/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeTemplate/Instruction.php @@ -2,30 +2,29 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Instructions\IncludeTemplate; -use LastDragon_ru\LaraASP\Core\Utils\Path; -use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\ParameterizableInstruction; -use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\TargetIsNotFile; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\Instruction as InstructionContract; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\TemplateDataMissed; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\TemplateVariablesMissed; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\TemplateVariablesUnused; -use LastDragon_ru\LaraASP\Serializer\Contracts\Serializable; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Targets\FileContent; use Override; use function array_diff; use function array_key_exists; use function array_keys; use function array_values; -use function dirname; -use function file_get_contents; use function preg_replace_callback; use function rtrim; use const PREG_UNMATCHED_AS_NULL; /** - * @implements ParameterizableInstruction + * Includes the `` as a template. + * + * @implements InstructionContract> */ -class Instruction implements ParameterizableInstruction { +class Instruction implements InstructionContract { public function __construct() { // empty } @@ -36,48 +35,28 @@ public static function getName(): string { } #[Override] - public static function getDescription(): string { - return 'Includes the `` as a template.'; + public static function getTarget(): string { + return FileContent::class; } #[Override] - public static function getTargetDescription(): ?string { - return 'File path.'; - } - - #[Override] - public static function getParameters(): string { + public static function getParameters(): ?string { return Parameters::class; } - /** - * @inheritDoc - */ #[Override] - public static function getParametersDescription(): array { - return []; - } - - #[Override] - public function process(string $path, string $target, Serializable $parameters): string { - // Content - $file = Path::getPath(dirname($path), $target); - $content = file_get_contents($file); - - if ($content === false) { - throw new TargetIsNotFile($path, $target); - } - + public function process(Context $context, mixed $target, mixed $parameters): string { // Data? if (!$parameters->data) { - throw new TemplateDataMissed($path, $target); + throw new TemplateDataMissed($context->path, $context->target); } // Replace - $vars = array_keys($parameters->data); - $used = []; - $known = []; - $count = 0; + $vars = array_keys($parameters->data); + $used = []; + $known = []; + $count = 0; + $content = $target; do { $content = (string) preg_replace_callback( @@ -104,14 +83,14 @@ public function process(string $path, string $target, Serializable $parameters): $unused = array_diff($vars, $used); if ($unused) { - throw new TemplateVariablesUnused($path, $target, array_values($unused)); + throw new TemplateVariablesUnused($context->path, $context->target, array_values($unused)); } // Missed $missed = array_diff($known, $used); if ($missed) { - throw new TemplateVariablesMissed($path, $target, array_values($missed)); + throw new TemplateVariablesMissed($context->path, $context->target, array_values($missed)); } // Return diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeTemplate/InstructionTest.php b/packages/documentator/src/Preprocessor/Instructions/IncludeTemplate/InstructionTest.php index 52b49a1dd..977a9fb79 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeTemplate/InstructionTest.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeTemplate/InstructionTest.php @@ -2,6 +2,7 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Instructions\IncludeTemplate; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\TemplateDataMissed; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\TemplateVariablesMissed; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\TemplateVariablesUnused; @@ -13,12 +14,13 @@ */ #[CoversClass(Instruction::class)] final class InstructionTest extends TestCase { - public function testProcessRelative(): void { - $file = self::getTestData()->file('.md'); + public function testProcess(): void { $params = new Parameters([ 'a' => 'Relative', 'b' => 'Inner reference ${a}', ]); + $content = self::getTestData()->content('.md'); + $context = new Context('/path/to/file.md', '/path/to/file.md', ''); $instance = $this->app()->make(Instruction::class); self::assertEquals( @@ -29,44 +31,22 @@ public function testProcessRelative(): void { FILE , - $instance->process($file->getPathname(), $file->getFilename(), $params), - ); - } - - public function testProcessAbsolute(): void { - $path = 'invalid/directory'; - $file = self::getTestData()->path('.md'); - $params = new Parameters([ - 'a' => 'Absolute', - 'b' => 'Inner reference ${a}', - ]); - $instance = $this->app()->make(Instruction::class); - - self::assertEquals( - <<<'FILE' - # Template Absolute - - Content of the file Absolute with variable "Inner reference Absolute" - - FILE - , - $instance->process($path, $file, $params), + $instance->process($context, $content, $params), ); } public function testProcessNoData(): void { - $file = self::getTestData()->file('.md'); + $file = 'path/to/file.md'; $params = new Parameters([]); + $content = 'content'; + $context = new Context($file, $file, ''); $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( - new TemplateDataMissed( - $file->getPathname(), - $file->getFilename(), - ), + new TemplateDataMissed($file, $file), ); - $instance->process($file->getPathname(), $file->getFilename(), $params); + $instance->process($context, $content, $params); } public function testProcessVariablesUnused(): void { @@ -77,6 +57,8 @@ public function testProcessVariablesUnused(): void { 'c' => 'C', 'd' => 'D', ]); + $content = self::getTestData()->content('.md'); + $context = new Context($file->getPathname(), $file->getFilename(), ''); $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( @@ -87,7 +69,7 @@ public function testProcessVariablesUnused(): void { ), ); - $instance->process($file->getPathname(), $file->getFilename(), $params); + $instance->process($context, $content, $params); } public function testProcessVariablesMissed(): void { @@ -95,6 +77,8 @@ public function testProcessVariablesMissed(): void { $params = new Parameters([ 'a' => 'A', ]); + $content = self::getTestData()->content('.md'); + $context = new Context($file->getPathname(), $file->getFilename(), ''); $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( @@ -105,6 +89,6 @@ public function testProcessVariablesMissed(): void { ), ); - $instance->process($file->getPathname(), $file->getFilename(), $params); + $instance->process($context, $content, $params); } } diff --git a/packages/documentator/src/Preprocessor/Preprocessor.php b/packages/documentator/src/Preprocessor/Preprocessor.php index d6915f850..0a9cce5e5 100644 --- a/packages/documentator/src/Preprocessor/Preprocessor.php +++ b/packages/documentator/src/Preprocessor/Preprocessor.php @@ -81,7 +81,7 @@ class Preprocessor { REGEXP; /** - * @var array, ?Instruction}> + * @var array>, ?Instruction<*,*,*>}> */ private array $instructions = []; @@ -100,14 +100,16 @@ public function __construct( } /** - * @return list> + * @return list>> */ public function getInstructions(): array { return array_column($this->instructions, 0); } /** - * @param Instruction|class-string $instruction + * @template I of Instruction<*,*,*> + * + * @param I|class-string $instruction */ public function addInstruction(Instruction|string $instruction): static { $this->instructions[$instruction::getName()] = $instruction instanceof Instruction @@ -117,6 +119,9 @@ public function addInstruction(Instruction|string $instruction): static { return $this; } + /** + * @return Instruction<*,*,*>|null + */ protected function getInstruction(string $name): ?Instruction { if (!isset($this->instructions[$name])) { return null; diff --git a/packages/documentator/src/Preprocessor/Targets/DirectoryPath.php b/packages/documentator/src/Preprocessor/Targets/DirectoryPath.php new file mode 100644 index 000000000..17870135a --- /dev/null +++ b/packages/documentator/src/Preprocessor/Targets/DirectoryPath.php @@ -0,0 +1,36 @@ + + */ +class DirectoryPath implements TargetResolver { + public function __construct() { + // empty + } + + #[Override] + public function resolve(Context $context, mixed $parameters): string { + $path = Path::getPath(dirname($context->path), $context->target); + + if (!is_dir($path)) { + throw new TargetIsNotDirectory($context->path, $context->target); + } + + return $path; + } +} diff --git a/packages/documentator/src/Preprocessor/Targets/DirectoryPathTest.php b/packages/documentator/src/Preprocessor/Targets/DirectoryPathTest.php new file mode 100644 index 000000000..550844a19 --- /dev/null +++ b/packages/documentator/src/Preprocessor/Targets/DirectoryPathTest.php @@ -0,0 +1,49 @@ +resolve($context, $params)); + } + + public function testResolveAbsolute(): void { + $dir = __DIR__; + $target = $dir; + $params = null; + $context = new Context($dir, $target, null); + $resolver = new DirectoryPath(); + + self::assertSame($dir, $resolver->resolve($context, $params)); + } + + public function testResolveNotADirectory(): void { + $dir = __DIR__; + $target = 'not/a/directory'; + $params = null; + $context = new Context($dir, $target, null); + $resolver = new DirectoryPath(); + + self::expectException(TargetIsNotDirectory::class); + self::expectExceptionMessage("The `{$target}` is not a directory (in `{$dir}`)."); + + self::assertSame($dir, $resolver->resolve($context, $params)); + } +} diff --git a/packages/documentator/src/Preprocessor/Targets/FileContent.php b/packages/documentator/src/Preprocessor/Targets/FileContent.php new file mode 100644 index 000000000..28366bc3c --- /dev/null +++ b/packages/documentator/src/Preprocessor/Targets/FileContent.php @@ -0,0 +1,28 @@ + + */ +class FileContent extends FilePath { + #[Override] + public function resolve(Context $context, mixed $parameters): string { + $path = parent::resolve($context, $parameters); + $content = file_get_contents($path); + + if ($content === false) { + throw new TargetIsNotFile($context->path, $context->target); + } + + return $content; + } +} diff --git a/packages/documentator/src/Preprocessor/Targets/FilePath.php b/packages/documentator/src/Preprocessor/Targets/FilePath.php new file mode 100644 index 000000000..ee216c390 --- /dev/null +++ b/packages/documentator/src/Preprocessor/Targets/FilePath.php @@ -0,0 +1,36 @@ + + */ +class FilePath implements TargetResolver { + public function __construct() { + // empty + } + + #[Override] + public function resolve(Context $context, mixed $parameters): string { + $path = Path::getPath(dirname($context->path), $context->target); + + if (!is_file($path) || !is_readable($path)) { + throw new TargetIsNotFile($context->path, $context->target); + } + + return $path; + } +} diff --git a/packages/documentator/src/Preprocessor/Targets/FilePathTest.php b/packages/documentator/src/Preprocessor/Targets/FilePathTest.php new file mode 100644 index 000000000..902fdc060 --- /dev/null +++ b/packages/documentator/src/Preprocessor/Targets/FilePathTest.php @@ -0,0 +1,49 @@ +resolve($context, $params)); + } + + public function testResolveAbsolute(): void { + $file = __FILE__; + $target = $file; + $params = null; + $context = new Context($file, $target, null); + $resolver = new FilePath(); + + self::assertSame($file, $resolver->resolve($context, $params)); + } + + public function testResolveNotAFile(): void { + $file = __FILE__; + $target = 'not/a/file'; + $params = null; + $context = new Context($file, $target, null); + $resolver = new FilePath(); + + self::expectException(TargetIsNotFile::class); + self::expectExceptionMessage("The `{$target}` is not a file (in `{$file}`)."); + + self::assertSame($file, $resolver->resolve($context, $params)); + } +} From d45a5862d4546d765544d0c19da4b02e61a81503 Mon Sep 17 00:00:00 2001 From: Aleksei Lebedev <1329824+LastDragon-ru@users.noreply.github.com> Date: Mon, 6 May 2024 11:50:33 +0400 Subject: [PATCH 02/14] Better generic types for `Instruction`. --- .../src/Preprocessor/Contracts/Instruction.php | 7 +++---- .../Instructions/IncludeDocBlock/Instruction.php | 2 +- .../Instructions/IncludeDocumentList/Instruction.php | 2 +- .../Instructions/IncludeDocumentList/InstructionTest.php | 9 ++++----- .../Instructions/IncludeExample/Instruction.php | 2 +- .../Instructions/IncludeExec/Instruction.php | 2 +- .../Instructions/IncludeFile/Instruction.php | 2 +- .../Instructions/IncludeGraphqlDirective/Instruction.php | 2 +- .../Instructions/IncludePackageList/Instruction.php | 2 +- .../Instructions/IncludePackageList/InstructionTest.php | 8 ++++---- .../Instructions/IncludeTemplate/Instruction.php | 2 +- .../src/Preprocessor/Targets/DirectoryPath.php | 4 +--- .../src/Preprocessor/Targets/FileContent.php | 5 ----- .../documentator/src/Preprocessor/Targets/FilePath.php | 4 +--- 14 files changed, 21 insertions(+), 32 deletions(-) diff --git a/packages/documentator/src/Preprocessor/Contracts/Instruction.php b/packages/documentator/src/Preprocessor/Contracts/Instruction.php index 06bcbb8e5..4baf7bb14 100644 --- a/packages/documentator/src/Preprocessor/Contracts/Instruction.php +++ b/packages/documentator/src/Preprocessor/Contracts/Instruction.php @@ -5,15 +5,14 @@ use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; /** + * @template TTarget * @template TParameters - * @template TTargetValue - * @template TTargetResolver of TargetResolver */ interface Instruction { public static function getName(): string; /** - * @return class-string + * @return class-string|TargetResolver> */ public static function getTarget(): string; @@ -24,7 +23,7 @@ public static function getParameters(): ?string; /** * @param Context $context - * @param TTargetValue $target + * @param TTarget $target * @param TParameters $parameters */ public function process(Context $context, mixed $target, mixed $parameters): string; diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeDocBlock/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeDocBlock/Instruction.php index 506bfc25a..c5619908b 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeDocBlock/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeDocBlock/Instruction.php @@ -28,7 +28,7 @@ * from `` file. Inline tags include as is except `@see`/`@link` * which will be replaced to FQCN (if possible). Other tags are ignored. * - * @implements InstructionContract> + * @implements InstructionContract */ class Instruction implements InstructionContract { public function __construct() { diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/Instruction.php index bcb50452d..027d0c00c 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/Instruction.php @@ -23,7 +23,7 @@ * must have `# Header` as the first construction. The first paragraph * after the Header will be used as a summary. * - * @implements InstructionContract> + * @implements InstructionContract */ class Instruction implements InstructionContract { public function __construct( diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/InstructionTest.php b/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/InstructionTest.php index 4bbcc34b6..9045f3f1a 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/InstructionTest.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/InstructionTest.php @@ -20,7 +20,7 @@ public function testProcessSameDirectory(): void { $params = new Parameters(); $context = new Context($path->getPathname(), './', ''); $instance = $this->app()->make(Instruction::class); - $target = (new DirectoryPath())->resolve($context, $params); + $target = (new DirectoryPath())->resolve($context, null); $actual = $instance->process($context, $target, $params); self::assertEquals( @@ -38,7 +38,7 @@ public function testProcessAnotherDirectory(): void { $params = new Parameters(); $context = new Context($path->getPathname(), basename(self::getTestData()->path('/')), ''); $instance = $this->app()->make(Instruction::class); - $target = (new DirectoryPath())->resolve($context, $params); + $target = (new DirectoryPath())->resolve($context, null); $actual = $instance->process($context, $target, $params); self::assertEquals( @@ -56,7 +56,7 @@ public function testProcessNestedDirectories(): void { $params = new Parameters(null); $context = new Context($path->getPathname(), './', ''); $instance = $this->app()->make(Instruction::class); - $target = (new DirectoryPath())->resolve($context, $params); + $target = (new DirectoryPath())->resolve($context, null); $actual = $instance->process($context, $target, $params); self::assertEquals( @@ -71,11 +71,10 @@ public function testProcessNestedDirectories(): void { public function testProcessWithoutTitle(): void { $path = self::getTestData()->file('invalid/Document.md'); - $target = './'; $params = new Parameters(); $context = new Context($path->getPathname(), './', ''); $instance = $this->app()->make(Instruction::class); - $target = (new DirectoryPath())->resolve($context, $params); + $target = (new DirectoryPath())->resolve($context, null); self::expectExceptionObject( new DocumentTitleIsMissing( diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeExample/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeExample/Instruction.php index 281427769..a03f781b1 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeExample/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeExample/Instruction.php @@ -31,7 +31,7 @@ * block. You can wrap the output into `text` tags to * insert it as is. * - * @implements InstructionContract> + * @implements InstructionContract */ class Instruction implements InstructionContract { public const Limit = 50; diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeExec/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeExec/Instruction.php index 96eba9602..e8639233b 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeExec/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeExec/Instruction.php @@ -15,7 +15,7 @@ /** * Executes the `` and returns result. * - * @implements InstructionContract> + * @implements InstructionContract */ class Instruction implements InstructionContract { public function __construct( diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeFile/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeFile/Instruction.php index f1a6e9b38..ea66916db 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeFile/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeFile/Instruction.php @@ -12,7 +12,7 @@ /** * Includes the `` file. * - * @implements InstructionContract> + * @implements InstructionContract */ class Instruction implements InstructionContract { public function __construct() { diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Instruction.php index db27e12a4..0c74bf124 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Instruction.php @@ -16,7 +16,7 @@ /** * Includes the definition of the directive as a Markdown code block. * - * @implements InstructionContract> + * @implements InstructionContract */ class Instruction implements InstructionContract { public function __construct( diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/Instruction.php index b742bb3b0..399bbce59 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/Instruction.php @@ -31,7 +31,7 @@ * Generates package list from `` directory. The readme file will be * used to determine package name and summary. * - * @implements InstructionContract> + * @implements InstructionContract */ class Instruction implements InstructionContract { public function __construct( diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/InstructionTest.php b/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/InstructionTest.php index cfb4bfdd3..40bd446e7 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/InstructionTest.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/InstructionTest.php @@ -26,7 +26,7 @@ public function testProcess(string $expected, string $template): void { $target = basename(self::getTestData()->path('/packages')); $params = new Parameters(template: $template); $context = new Context($path, $target, ''); - $resolved = (new DirectoryPath())->resolve($context, $params); + $resolved = (new DirectoryPath())->resolve($context, null); $instance = $this->app()->make(Instruction::class); $actual = $instance->process($context, $resolved, $params); @@ -45,7 +45,7 @@ public function testProcessNotAPackage(): void { $target = basename(self::getTestData()->path('/invalid')); $params = new Parameters(); $context = new Context($path, $target, ''); - $resolved = (new DirectoryPath())->resolve($context, $params); + $resolved = (new DirectoryPath())->resolve($context, null); $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( @@ -64,7 +64,7 @@ public function testProcessNoReadme(): void { $target = basename(self::getTestData()->path('/no readme')); $params = new Parameters(); $context = new Context($path, $target, ''); - $resolved = (new DirectoryPath())->resolve($context, $params); + $resolved = (new DirectoryPath())->resolve($context, null); $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( @@ -83,7 +83,7 @@ public function testProcessNoTitle(): void { $target = basename(self::getTestData()->path('/no title')); $params = new Parameters(); $context = new Context($path, $target, ''); - $resolved = (new DirectoryPath())->resolve($context, $params); + $resolved = (new DirectoryPath())->resolve($context, null); $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeTemplate/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeTemplate/Instruction.php index 2c91c8331..af28dd47f 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeTemplate/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeTemplate/Instruction.php @@ -22,7 +22,7 @@ /** * Includes the `` as a template. * - * @implements InstructionContract> + * @implements InstructionContract */ class Instruction implements InstructionContract { public function __construct() { diff --git a/packages/documentator/src/Preprocessor/Targets/DirectoryPath.php b/packages/documentator/src/Preprocessor/Targets/DirectoryPath.php index 17870135a..c2af1319a 100644 --- a/packages/documentator/src/Preprocessor/Targets/DirectoryPath.php +++ b/packages/documentator/src/Preprocessor/Targets/DirectoryPath.php @@ -14,9 +14,7 @@ /** * Directory path. * - * @template TParameters - * - * @implements TargetResolver + * @implements TargetResolver */ class DirectoryPath implements TargetResolver { public function __construct() { diff --git a/packages/documentator/src/Preprocessor/Targets/FileContent.php b/packages/documentator/src/Preprocessor/Targets/FileContent.php index 28366bc3c..06c9cb918 100644 --- a/packages/documentator/src/Preprocessor/Targets/FileContent.php +++ b/packages/documentator/src/Preprocessor/Targets/FileContent.php @@ -8,11 +8,6 @@ use function file_get_contents; -/** - * @template TParameters - * - * @extends FilePath - */ class FileContent extends FilePath { #[Override] public function resolve(Context $context, mixed $parameters): string { diff --git a/packages/documentator/src/Preprocessor/Targets/FilePath.php b/packages/documentator/src/Preprocessor/Targets/FilePath.php index ee216c390..78ed92055 100644 --- a/packages/documentator/src/Preprocessor/Targets/FilePath.php +++ b/packages/documentator/src/Preprocessor/Targets/FilePath.php @@ -14,9 +14,7 @@ /** * File path. * - * @template TParameters - * - * @implements TargetResolver + * @implements TargetResolver */ class FilePath implements TargetResolver { public function __construct() { From 5f89961f04f3ef150a161f3caf63b45d55760d96 Mon Sep 17 00:00:00 2001 From: Aleksei Lebedev <1329824+LastDragon-ru@users.noreply.github.com> Date: Mon, 6 May 2024 16:03:31 +0400 Subject: [PATCH 03/14] `Preprocessor` updated to work with new `Instruction`. --- .../Preprocessor/Contracts/Instruction.php | 12 +- .../src/Preprocessor/Preprocessor.php | 47 ++-- .../src/Preprocessor/PreprocessorTest.php | 224 +++++++++++------- 3 files changed, 162 insertions(+), 121 deletions(-) diff --git a/packages/documentator/src/Preprocessor/Contracts/Instruction.php b/packages/documentator/src/Preprocessor/Contracts/Instruction.php index 4baf7bb14..87196f707 100644 --- a/packages/documentator/src/Preprocessor/Contracts/Instruction.php +++ b/packages/documentator/src/Preprocessor/Contracts/Instruction.php @@ -6,7 +6,7 @@ /** * @template TTarget - * @template TParameters + * @template TParameters of object|null */ interface Instruction { public static function getName(): string; @@ -17,14 +17,16 @@ public static function getName(): string; public static function getTarget(): string; /** - * @return class-string|null + * @return class-string|null + * fixme(documentator): The correct type is `(TParameters is object ? class-string : null)` + * but it is not yet supported by phpstan (see https://github.com/phpstan/phpstan/issues/10553) */ public static function getParameters(): ?string; /** - * @param Context $context - * @param TTarget $target - * @param TParameters $parameters + * @param Context $context + * @param TTarget $target + * @param TParameters $parameters */ public function process(Context $context, mixed $target, mixed $parameters): string; } diff --git a/packages/documentator/src/Preprocessor/Preprocessor.php b/packages/documentator/src/Preprocessor/Preprocessor.php index 0a9cce5e5..d92b26cbc 100644 --- a/packages/documentator/src/Preprocessor/Preprocessor.php +++ b/packages/documentator/src/Preprocessor/Preprocessor.php @@ -2,15 +2,11 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor; -// @phpcs:disable Generic.Files.LineLength.TooLong - use Exception; use LastDragon_ru\LaraASP\Core\Application\ContainerResolver; use LastDragon_ru\LaraASP\Core\Utils\Path; use LastDragon_ru\LaraASP\Documentator\Commands\Preprocess; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\Instruction; -use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\ParameterizableInstruction; -use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\ProcessableInstruction; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\PreprocessFailed; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Instructions\IncludeDocBlock\Instruction as IncludeDocBlock; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Instructions\IncludeDocumentList\Instruction as IncludeDocumentList; @@ -39,7 +35,7 @@ use const PREG_UNMATCHED_AS_NULL; /** - * Replaces special instructions in Markdown. Instruction is the link reference + * Replaces special instructions in Markdown. Instruction is the link reference * definition, so the syntax is: * * []: @@ -62,7 +58,7 @@ * @todo Use https://github.com/thephpleague/commonmark? * @todo Sync with {@see Preprocess} command * - * @see Preprocess + * @see Preprocess */ class Preprocessor { protected const Warning = 'Generated automatically. Do not edit.'; @@ -81,7 +77,7 @@ class Preprocessor { REGEXP; /** - * @var array>, ?Instruction<*,*,*>}> + * @var array>,?Instruction}> */ private array $instructions = []; @@ -100,18 +96,19 @@ public function __construct( } /** - * @return list>> + * @return list>> */ public function getInstructions(): array { return array_column($this->instructions, 0); } /** - * @template I of Instruction<*,*,*> + * @template I of Instruction * * @param I|class-string $instruction */ public function addInstruction(Instruction|string $instruction): static { + // @phpstan-ignore-next-line Assigment is fine... $this->instructions[$instruction::getName()] = $instruction instanceof Instruction ? [$instruction::class, $instruction] : [$instruction, null]; @@ -120,7 +117,7 @@ public function addInstruction(Instruction|string $instruction): static { } /** - * @return Instruction<*,*,*>|null + * @return Instruction|null */ protected function getInstruction(string $name): ?Instruction { if (!isset($this->instructions[$name])) { @@ -151,31 +148,19 @@ public function process(string $path, string $string): string { $target = str_starts_with($target, '<') && str_ends_with($target, '>') ? mb_substr($target, 1, -1) : rawurldecode($target); - $params = null; - $hash = $this->getHash("{$matches['instruction']}({$target})"); - - if ($instruction instanceof ParameterizableInstruction) { - $json = $this->getParametersJson($matches['parameters'] ?: '{}'); - $hash = $this->getHash("{$matches['instruction']}({$target}, {$json})"); - $params = $this->serializer->deserialize( - $instruction::getParameters(), - $matches['parameters'] ?: '{}', - 'json', - ); - } + $json = $this->getParametersJson($matches['parameters'] ?: '{}'); + $hash = $this->getHash("{$matches['instruction']}({$target}, {$json})"); // Content $content = $cache[$hash] ?? null; - if ($content === null) { - if ($instruction instanceof ParameterizableInstruction) { - $content = $instruction->process($path, $target, $params); - } elseif ($instruction instanceof ProcessableInstruction) { - $content = $instruction->process($path, $target); - } else { - $content = ''; - } - + if ($instruction && $content === null) { + $params = $instruction::getParameters(); + $params = $params ? $this->serializer->deserialize($params, $json, 'json') : null; + $context = new Context($path, $target, $matches['parameters']); + $resolver = $this->container->getInstance()->make($instruction::getTarget()); + $resolved = $resolver->resolve($context, $params); + $content = $instruction->process($context, $resolved, $params); $content = trim($content); $cache[$hash] = $content; } diff --git a/packages/documentator/src/Preprocessor/PreprocessorTest.php b/packages/documentator/src/Preprocessor/PreprocessorTest.php index a764857fb..2aa7cc022 100644 --- a/packages/documentator/src/Preprocessor/PreprocessorTest.php +++ b/packages/documentator/src/Preprocessor/PreprocessorTest.php @@ -3,33 +3,36 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\Instruction; -use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\ParameterizableInstruction; -use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\ProcessableInstruction; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\TargetResolver; use LastDragon_ru\LaraASP\Documentator\Testing\Package\TestCase; use LastDragon_ru\LaraASP\Serializer\Contracts\Serializable; -use Mockery; -use Mockery\Matcher\IsEqual; +use Override; use PHPUnit\Framework\Attributes\CoversClass; +use function json_encode; +use function sprintf; + +use const JSON_THROW_ON_ERROR; + /** * @internal */ #[CoversClass(Preprocessor::class)] final class PreprocessorTest extends TestCase { public function testProcess(): void { - $content = <<<'MARKDOWN' + $content = <<<'MARKDOWN' Bla bla bla [processable]: ./path/to/file should be ignored. [unknown]: ./path/to/file - [empty]: ./path/to/file + [test:empty]: ./path/to/file - [processable]: ./path/to/file + [test:instruction]: ./path/to/file - [processable]: <./path/to/file> + [test:instruction]: <./path/to/file> [//]: # (start: hash) - [processable]: ./path/to/file + [test:instruction]: ./path/to/file [//]: # (start: nested-hash) outdated @@ -38,61 +41,18 @@ public function testProcess(): void { [//]: # (end: hash) - [parameterizable]: ./path/to/file + [test:instruction]: ./path/to/file - [parameterizable]: ./path/to/file + [test:instruction]: ./path/to/file - [parameterizable]: ./path/to/file/parametrized ({"a": "aa", "b": {"a": "a", "b": "b"}}) + [test:instruction]: ./path/to/file/parametrized ({"a": "aa", "b": {"a": "a", "b": "b"}}) - [parameterizable]: ./path/to/file/parametrized ({"b":{ "b": "b","a": "a"},"a":"aa"}) + [test:instruction]: ./path/to/file/parametrized ({"b":{ "b": "b","a": "a"},"a":"aa"}) MARKDOWN; - $parameterizableInstruction = Mockery::mock(ParameterizableInstruction::class); - $parameterizableInstruction - ->shouldReceive('getName') - ->once() - ->andReturn('parameterizable'); - $parameterizableInstruction - ->shouldReceive('getParameters') - ->times(4) - ->andReturn(PreprocessorTest__Parameters::class); - $parameterizableInstruction - ->shouldReceive('process') - ->with('path', './path/to/file', new IsEqual(new PreprocessorTest__Parameters())) - ->once() - ->andReturn('parameterizable()'); - $parameterizableInstruction - ->shouldReceive('process') - ->with( - 'path', - './path/to/file/parametrized', - new IsEqual( - new PreprocessorTest__Parameters('aa', ['a' => 'a', 'b' => 'b']), - ), - ) - ->once() - ->andReturn('parameterizable(aa, bb)'); - - $processableInstruction = Mockery::mock(ProcessableInstruction::class); - $processableInstruction - ->shouldReceive('getName') - ->once() - ->andReturn('processable'); - $processableInstruction - ->shouldReceive('process') - ->with('path', './path/to/file') - ->once() - ->andReturn('content'); - - $emptyInstruction = Mockery::mock(Instruction::class); - $emptyInstruction - ->shouldReceive('getName') - ->once() - ->andReturn('empty'); $preprocessor = $this->app()->make(Preprocessor::class) - ->addInstruction($parameterizableInstruction) - ->addInstruction($processableInstruction) - ->addInstruction($emptyInstruction); + ->addInstruction(new PreprocessorTest__EmptyInstruction()) + ->addInstruction(new PreprocessorTest__TestInstruction()); self::assertEquals( <<<'MARKDOWN' @@ -100,59 +60,59 @@ public function testProcess(): void { [unknown]: ./path/to/file - [empty]: ./path/to/file - [//]: # (start: 8619b6a617a04e2b1ed8916cd29b8e9947a9157ffdef8d2e8a51fe60fbc13948) + [test:empty]: ./path/to/file + [//]: # (start: caf14319a44edf638bf2ba4b4c76caab5a3d85ee06d5c86387fbdb703c8b5c84) [//]: # (warning: Generated automatically. Do not edit.) [//]: # (empty) - [//]: # (end: 8619b6a617a04e2b1ed8916cd29b8e9947a9157ffdef8d2e8a51fe60fbc13948) + [//]: # (end: caf14319a44edf638bf2ba4b4c76caab5a3d85ee06d5c86387fbdb703c8b5c84) - [processable]: ./path/to/file - [//]: # (start: 378a07bc67ecbe88f5d2f642e70681461f61d3f2f5e83379015b879110c83947) + [test:instruction]: ./path/to/file + [//]: # (start: 15a77bf03e0261f0d7d2af698861fc23733fb4f09e0570e3b2570f4fe7b2694c) [//]: # (warning: Generated automatically. Do not edit.) - content + result(./path/to/file/a, {"a":"a","b":[]}) - [//]: # (end: 378a07bc67ecbe88f5d2f642e70681461f61d3f2f5e83379015b879110c83947) + [//]: # (end: 15a77bf03e0261f0d7d2af698861fc23733fb4f09e0570e3b2570f4fe7b2694c) - [processable]: <./path/to/file> - [//]: # (start: 378a07bc67ecbe88f5d2f642e70681461f61d3f2f5e83379015b879110c83947) + [test:instruction]: <./path/to/file> + [//]: # (start: 15a77bf03e0261f0d7d2af698861fc23733fb4f09e0570e3b2570f4fe7b2694c) [//]: # (warning: Generated automatically. Do not edit.) - content + result(./path/to/file/a, {"a":"a","b":[]}) - [//]: # (end: 378a07bc67ecbe88f5d2f642e70681461f61d3f2f5e83379015b879110c83947) + [//]: # (end: 15a77bf03e0261f0d7d2af698861fc23733fb4f09e0570e3b2570f4fe7b2694c) - [parameterizable]: ./path/to/file - [//]: # (start: 5d070af95e5691621d63e901616cc0fa03d3253c24d1dcf27023d8a1ce01d9fb) + [test:instruction]: ./path/to/file + [//]: # (start: 15a77bf03e0261f0d7d2af698861fc23733fb4f09e0570e3b2570f4fe7b2694c) [//]: # (warning: Generated automatically. Do not edit.) - parameterizable() + result(./path/to/file/a, {"a":"a","b":[]}) - [//]: # (end: 5d070af95e5691621d63e901616cc0fa03d3253c24d1dcf27023d8a1ce01d9fb) + [//]: # (end: 15a77bf03e0261f0d7d2af698861fc23733fb4f09e0570e3b2570f4fe7b2694c) - [parameterizable]: ./path/to/file - [//]: # (start: 5d070af95e5691621d63e901616cc0fa03d3253c24d1dcf27023d8a1ce01d9fb) + [test:instruction]: ./path/to/file + [//]: # (start: 15a77bf03e0261f0d7d2af698861fc23733fb4f09e0570e3b2570f4fe7b2694c) [//]: # (warning: Generated automatically. Do not edit.) - parameterizable() + result(./path/to/file/a, {"a":"a","b":[]}) - [//]: # (end: 5d070af95e5691621d63e901616cc0fa03d3253c24d1dcf27023d8a1ce01d9fb) + [//]: # (end: 15a77bf03e0261f0d7d2af698861fc23733fb4f09e0570e3b2570f4fe7b2694c) - [parameterizable]: ./path/to/file/parametrized ({"a": "aa", "b": {"a": "a", "b": "b"}}) - [//]: # (start: a91869c99598538f0f98ed293004603fd2c24d938c8c6d5a8e7267ba56aeb86e) + [test:instruction]: ./path/to/file/parametrized ({"a": "aa", "b": {"a": "a", "b": "b"}}) + [//]: # (start: ebe11a5c6bf74b7f70eec0c6b14ad768e159a9699273d7f07824ef116b37dfd3) [//]: # (warning: Generated automatically. Do not edit.) - parameterizable(aa, bb) + result(./path/to/file/parametrized/aa, {"a":"aa","b":{"a":"a","b":"b"}}) - [//]: # (end: a91869c99598538f0f98ed293004603fd2c24d938c8c6d5a8e7267ba56aeb86e) + [//]: # (end: ebe11a5c6bf74b7f70eec0c6b14ad768e159a9699273d7f07824ef116b37dfd3) - [parameterizable]: ./path/to/file/parametrized ({"b":{ "b": "b","a": "a"},"a":"aa"}) - [//]: # (start: a91869c99598538f0f98ed293004603fd2c24d938c8c6d5a8e7267ba56aeb86e) + [test:instruction]: ./path/to/file/parametrized ({"b":{ "b": "b","a": "a"},"a":"aa"}) + [//]: # (start: ebe11a5c6bf74b7f70eec0c6b14ad768e159a9699273d7f07824ef116b37dfd3) [//]: # (warning: Generated automatically. Do not edit.) - parameterizable(aa, bb) + result(./path/to/file/parametrized/aa, {"a":"aa","b":{"a":"a","b":"b"}}) - [//]: # (end: a91869c99598538f0f98ed293004603fd2c24d938c8c6d5a8e7267ba56aeb86e) + [//]: # (end: ebe11a5c6bf74b7f70eec0c6b14ad768e159a9699273d7f07824ef116b37dfd3) MARKDOWN, $preprocessor->process('path', $content), ); @@ -162,6 +122,100 @@ public function testProcess(): void { // @phpcs:disable PSR1.Classes.ClassDeclaration.MultipleClasses // @phpcs:disable Squiz.Classes.ValidClassName.NotCamelCaps +/** + * @internal + * @noinspection PhpMultipleClassesDeclarationsInOneFile + * + * @implements Instruction + */ +class PreprocessorTest__EmptyInstruction implements Instruction { + #[Override] + public static function getName(): string { + return 'test:empty'; + } + + #[Override] + public static function getTarget(): string { + return PreprocessorTest__TargetAsIs::class; + } + + #[Override] + public static function getParameters(): ?string { + return null; + } + + #[Override] + public function process(Context $context, mixed $target, mixed $parameters): string { + return ''; + } +} + +/** + * @internal + * @noinspection PhpMultipleClassesDeclarationsInOneFile + * + * @implements Instruction + */ +class PreprocessorTest__TestInstruction implements Instruction { + #[Override] + public static function getName(): string { + return 'test:instruction'; + } + + #[Override] + public static function getTarget(): string { + return PreprocessorTest__TargetAsValue::class; + } + + #[Override] + public static function getParameters(): ?string { + return PreprocessorTest__Parameters::class; + } + + #[Override] + public function process(Context $context, mixed $target, mixed $parameters): string { + return sprintf('result(%s, %s)', $target->value, json_encode($parameters, JSON_THROW_ON_ERROR)); + } +} + +/** + * @internal + * @noinspection PhpMultipleClassesDeclarationsInOneFile + */ +class PreprocessorTest__Value { + public function __construct( + public string $value, + ) { + // empty + } +} + +/** + * @internal + * @noinspection PhpMultipleClassesDeclarationsInOneFile + * + * @implements TargetResolver + */ +class PreprocessorTest__TargetAsIs implements TargetResolver { + #[Override] + public function resolve(Context $context, mixed $parameters): mixed { + return $context->target; + } +} + +/** + * @internal + * @noinspection PhpMultipleClassesDeclarationsInOneFile + * + * @implements TargetResolver + */ +class PreprocessorTest__TargetAsValue implements TargetResolver { + #[Override] + public function resolve(Context $context, mixed $parameters): mixed { + return new PreprocessorTest__Value("{$context->target}/{$parameters->a}"); + } +} + /** * @internal * @noinspection PhpMultipleClassesDeclarationsInOneFile From 0d06e9c3d6606ba809d41eb05fac3f012b2cd644 Mon Sep 17 00:00:00 2001 From: Aleksei Lebedev <1329824+LastDragon-ru@users.noreply.github.com> Date: Tue, 7 May 2024 09:30:08 +0400 Subject: [PATCH 04/14] Better names for contracts and their methods. --- .../src/Preprocessor/Contracts/Instruction.php | 4 ++-- .../{TargetResolver.php => Resolver.php} | 2 +- .../IncludeDocBlock/Instruction.php | 2 +- .../IncludeDocumentList/Instruction.php | 2 +- .../IncludeExample/Instruction.php | 2 +- .../Instructions/IncludeExec/Instruction.php | 4 ++-- .../IncludeExec/{Target.php => Resolver.php} | 8 +++----- .../Instructions/IncludeFile/Instruction.php | 2 +- .../IncludeGraphqlDirective/Instruction.php | 4 ++-- .../{Target.php => Resolver.php} | 8 +++----- .../IncludePackageList/Instruction.php | 2 +- .../IncludeTemplate/Instruction.php | 2 +- .../src/Preprocessor/Preprocessor.php | 2 +- .../src/Preprocessor/PreprocessorTest.php | 18 +++++++++--------- .../src/Preprocessor/Targets/DirectoryPath.php | 6 +++--- .../src/Preprocessor/Targets/FilePath.php | 6 +++--- 16 files changed, 35 insertions(+), 39 deletions(-) rename packages/documentator/src/Preprocessor/Contracts/{TargetResolver.php => Resolver.php} (93%) rename packages/documentator/src/Preprocessor/Instructions/IncludeExec/{Target.php => Resolver.php} (68%) rename packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/{Target.php => Resolver.php} (69%) diff --git a/packages/documentator/src/Preprocessor/Contracts/Instruction.php b/packages/documentator/src/Preprocessor/Contracts/Instruction.php index 87196f707..88195b235 100644 --- a/packages/documentator/src/Preprocessor/Contracts/Instruction.php +++ b/packages/documentator/src/Preprocessor/Contracts/Instruction.php @@ -12,9 +12,9 @@ interface Instruction { public static function getName(): string; /** - * @return class-string|TargetResolver> + * @return class-string|Resolver> */ - public static function getTarget(): string; + public static function getResolver(): string; /** * @return class-string|null diff --git a/packages/documentator/src/Preprocessor/Contracts/TargetResolver.php b/packages/documentator/src/Preprocessor/Contracts/Resolver.php similarity index 93% rename from packages/documentator/src/Preprocessor/Contracts/TargetResolver.php rename to packages/documentator/src/Preprocessor/Contracts/Resolver.php index dd8cbbc72..6b8267b3a 100644 --- a/packages/documentator/src/Preprocessor/Contracts/TargetResolver.php +++ b/packages/documentator/src/Preprocessor/Contracts/Resolver.php @@ -8,7 +8,7 @@ * @template TParameters * @template TValue */ -interface TargetResolver { +interface Resolver { /** * @param TParameters $parameters * diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeDocBlock/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeDocBlock/Instruction.php index c5619908b..c9082fe44 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeDocBlock/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeDocBlock/Instruction.php @@ -41,7 +41,7 @@ public static function getName(): string { } #[Override] - public static function getTarget(): string { + public static function getResolver(): string { return FileContent::class; } diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/Instruction.php index 027d0c00c..45fc3a285 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/Instruction.php @@ -38,7 +38,7 @@ public static function getName(): string { } #[Override] - public static function getTarget(): string { + public static function getResolver(): string { return DirectoryPath::class; } diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeExample/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeExample/Instruction.php index a03f781b1..0a607851c 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeExample/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeExample/Instruction.php @@ -49,7 +49,7 @@ public static function getName(): string { } #[Override] - public static function getTarget(): string { + public static function getResolver(): string { return FileContent::class; } diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeExec/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeExec/Instruction.php index e8639233b..e6c98cce3 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeExec/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeExec/Instruction.php @@ -30,8 +30,8 @@ public static function getName(): string { } #[Override] - public static function getTarget(): string { - return Target::class; + public static function getResolver(): string { + return Resolver::class; } #[Override] diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeExec/Target.php b/packages/documentator/src/Preprocessor/Instructions/IncludeExec/Resolver.php similarity index 68% rename from packages/documentator/src/Preprocessor/Instructions/IncludeExec/Target.php rename to packages/documentator/src/Preprocessor/Instructions/IncludeExec/Resolver.php index f82e58c97..884e502a6 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeExec/Target.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeExec/Resolver.php @@ -3,17 +3,15 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Instructions\IncludeExec; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; -use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\TargetResolver; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\Resolver as ResolverContract; use Override; /** * Path to the executable. * - * @template TParameters - * - * @implements TargetResolver + * @implements ResolverContract */ -class Target implements TargetResolver { +class Resolver implements ResolverContract { public function __construct() { // empty } diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeFile/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeFile/Instruction.php index ea66916db..1d45dc233 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeFile/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeFile/Instruction.php @@ -25,7 +25,7 @@ public static function getName(): string { } #[Override] - public static function getTarget(): string { + public static function getResolver(): string { return FileContent::class; } diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Instruction.php index 0c74bf124..867fc2aad 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Instruction.php @@ -31,8 +31,8 @@ public static function getName(): string { } #[Override] - public static function getTarget(): string { - return Target::class; + public static function getResolver(): string { + return Resolver::class; } #[Override] diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Target.php b/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Resolver.php similarity index 69% rename from packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Target.php rename to packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Resolver.php index b1a5c58a1..b5a539d9b 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Target.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Resolver.php @@ -3,17 +3,15 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Instructions\IncludeGraphqlDirective; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; -use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\TargetResolver; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\Resolver as ResolverContract; use Override; /** * Directive name (started with `@` sign) * - * @template TParameters - * - * @implements TargetResolver + * @implements ResolverContract */ -class Target implements TargetResolver { +class Resolver implements ResolverContract { public function __construct() { // empty } diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/Instruction.php index 399bbce59..28ab4c261 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/Instruction.php @@ -46,7 +46,7 @@ public static function getName(): string { } #[Override] - public static function getTarget(): string { + public static function getResolver(): string { return DirectoryPath::class; } diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeTemplate/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeTemplate/Instruction.php index af28dd47f..b80d349cd 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeTemplate/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeTemplate/Instruction.php @@ -35,7 +35,7 @@ public static function getName(): string { } #[Override] - public static function getTarget(): string { + public static function getResolver(): string { return FileContent::class; } diff --git a/packages/documentator/src/Preprocessor/Preprocessor.php b/packages/documentator/src/Preprocessor/Preprocessor.php index d92b26cbc..55a78b748 100644 --- a/packages/documentator/src/Preprocessor/Preprocessor.php +++ b/packages/documentator/src/Preprocessor/Preprocessor.php @@ -158,7 +158,7 @@ public function process(string $path, string $string): string { $params = $instruction::getParameters(); $params = $params ? $this->serializer->deserialize($params, $json, 'json') : null; $context = new Context($path, $target, $matches['parameters']); - $resolver = $this->container->getInstance()->make($instruction::getTarget()); + $resolver = $this->container->getInstance()->make($instruction::getResolver()); $resolved = $resolver->resolve($context, $params); $content = $instruction->process($context, $resolved, $params); $content = trim($content); diff --git a/packages/documentator/src/Preprocessor/PreprocessorTest.php b/packages/documentator/src/Preprocessor/PreprocessorTest.php index 2aa7cc022..75212249d 100644 --- a/packages/documentator/src/Preprocessor/PreprocessorTest.php +++ b/packages/documentator/src/Preprocessor/PreprocessorTest.php @@ -3,7 +3,7 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\Instruction; -use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\TargetResolver; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\Resolver; use LastDragon_ru\LaraASP\Documentator\Testing\Package\TestCase; use LastDragon_ru\LaraASP\Serializer\Contracts\Serializable; use Override; @@ -135,8 +135,8 @@ public static function getName(): string { } #[Override] - public static function getTarget(): string { - return PreprocessorTest__TargetAsIs::class; + public static function getResolver(): string { + return PreprocessorTest__TargetResolverAsIs::class; } #[Override] @@ -163,8 +163,8 @@ public static function getName(): string { } #[Override] - public static function getTarget(): string { - return PreprocessorTest__TargetAsValue::class; + public static function getResolver(): string { + return PreprocessorTest__TargetResolverAsValue::class; } #[Override] @@ -194,9 +194,9 @@ public function __construct( * @internal * @noinspection PhpMultipleClassesDeclarationsInOneFile * - * @implements TargetResolver + * @implements Resolver */ -class PreprocessorTest__TargetAsIs implements TargetResolver { +class PreprocessorTest__TargetResolverAsIs implements Resolver { #[Override] public function resolve(Context $context, mixed $parameters): mixed { return $context->target; @@ -207,9 +207,9 @@ public function resolve(Context $context, mixed $parameters): mixed { * @internal * @noinspection PhpMultipleClassesDeclarationsInOneFile * - * @implements TargetResolver + * @implements Resolver */ -class PreprocessorTest__TargetAsValue implements TargetResolver { +class PreprocessorTest__TargetResolverAsValue implements Resolver { #[Override] public function resolve(Context $context, mixed $parameters): mixed { return new PreprocessorTest__Value("{$context->target}/{$parameters->a}"); diff --git a/packages/documentator/src/Preprocessor/Targets/DirectoryPath.php b/packages/documentator/src/Preprocessor/Targets/DirectoryPath.php index c2af1319a..0eca494e1 100644 --- a/packages/documentator/src/Preprocessor/Targets/DirectoryPath.php +++ b/packages/documentator/src/Preprocessor/Targets/DirectoryPath.php @@ -4,7 +4,7 @@ use LastDragon_ru\LaraASP\Core\Utils\Path; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; -use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\TargetResolver; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\Resolver; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\TargetIsNotDirectory; use Override; @@ -14,9 +14,9 @@ /** * Directory path. * - * @implements TargetResolver + * @implements Resolver */ -class DirectoryPath implements TargetResolver { +class DirectoryPath implements Resolver { public function __construct() { // empty } diff --git a/packages/documentator/src/Preprocessor/Targets/FilePath.php b/packages/documentator/src/Preprocessor/Targets/FilePath.php index 78ed92055..0406fd326 100644 --- a/packages/documentator/src/Preprocessor/Targets/FilePath.php +++ b/packages/documentator/src/Preprocessor/Targets/FilePath.php @@ -4,7 +4,7 @@ use LastDragon_ru\LaraASP\Core\Utils\Path; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; -use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\TargetResolver; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\Resolver; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\TargetIsNotFile; use Override; @@ -14,9 +14,9 @@ /** * File path. * - * @implements TargetResolver + * @implements Resolver */ -class FilePath implements TargetResolver { +class FilePath implements Resolver { public function __construct() { // empty } From 9d9ad8c794092ef2ebf0afa4e474300b8c16f3c2 Mon Sep 17 00:00:00 2001 From: Aleksei Lebedev <1329824+LastDragon-ru@users.noreply.github.com> Date: Tue, 7 May 2024 10:44:02 +0400 Subject: [PATCH 05/14] `Markdown::setPadding()` added. --- packages/documentator/src/Utils/Markdown.php | 29 +++++++++ .../documentator/src/Utils/MarkdownTest.php | 59 +++++++++++++++++++ 2 files changed, 88 insertions(+) diff --git a/packages/documentator/src/Utils/Markdown.php b/packages/documentator/src/Utils/Markdown.php index 9063a2ca6..c29c8bba6 100644 --- a/packages/documentator/src/Utils/Markdown.php +++ b/packages/documentator/src/Utils/Markdown.php @@ -14,11 +14,17 @@ use function array_slice; use function implode; use function ltrim; +use function mb_strlen; +use function mb_substr; +use function min; use function preg_split; use function str_ends_with; +use function str_repeat; use function str_starts_with; use function trim; +use const PHP_INT_MAX; + class Markdown { /** * Returns the first `# Header` if present. @@ -44,6 +50,29 @@ public static function getSummary(string $string): ?string { return $summary; } + /** + * @param int<0, max> $spaces + */ + public static function setPadding(string $string, int $spaces): string { + $prefix = str_repeat(' ', $spaces); + $lines = preg_split('/\R/u', $string) ?: []; + $cut = PHP_INT_MAX; + + foreach ($lines as $line) { + $trimmed = ltrim($line); + $padding = mb_strlen($line) - mb_strlen($trimmed); + $cut = min($cut, $padding); + } + + foreach ($lines as $i => $line) { + $line = mb_substr($line, $cut); + $line = ($line ? $prefix : '').$line; + $lines[$i] = $line; + } + + return implode("\n", $lines); + } + protected static function getDocumentNode(string $string): Document { $converter = new GithubFlavoredMarkdownConverter(); $environment = $converter->getEnvironment(); diff --git a/packages/documentator/src/Utils/MarkdownTest.php b/packages/documentator/src/Utils/MarkdownTest.php index 7522116ee..8a2d3b9b8 100644 --- a/packages/documentator/src/Utils/MarkdownTest.php +++ b/packages/documentator/src/Utils/MarkdownTest.php @@ -139,4 +139,63 @@ public function testGetSummary(): void { ), ); } + + public function testSetPadding(): void { + self::assertEquals( + <<<'TEXT' + # Header + + fsdfsdfsdf + fsdfsdfsdf + + * a + * a.a + * a.b + * b + TEXT, + Markdown::setPadding( + <<<'MARKDOWN' + # Header + + fsdfsdfsdf + fsdfsdfsdf + + * a + * a.a + * a.b + * b + MARKDOWN, + 4, + ), + ); + self::assertEquals( + <<<'MARKDOWN' + # Header + + fsdfsdfsdf + fsdfsdfsdf + + * a + * a.a + * a.b + + * b + MARKDOWN, + Markdown::setPadding( + <<<'MARKDOWN' + # Header + + fsdfsdfsdf + fsdfsdfsdf + + * a + * a.a + * a.b + + * b + MARKDOWN, + 4, + ), + ); + } } From a2f17380cedac765a5ebe1d9a23c9f934359ad6a Mon Sep 17 00:00:00 2001 From: Aleksei Lebedev <1329824+LastDragon-ru@users.noreply.github.com> Date: Tue, 7 May 2024 13:59:23 +0400 Subject: [PATCH 06/14] Help generation updated for `lara-asp-documentator:preprocess` command. --- .../documentator/src/Commands/Preprocess.php | 158 ++++++----- .../src/Commands/PreprocessTest.php | 260 +++++++++++++++--- .../src/Preprocessor/Preprocessor.php | 35 +-- 3 files changed, 331 insertions(+), 122 deletions(-) diff --git a/packages/documentator/src/Commands/Preprocess.php b/packages/documentator/src/Commands/Preprocess.php index 064e097bc..25d255809 100644 --- a/packages/documentator/src/Commands/Preprocess.php +++ b/packages/documentator/src/Commands/Preprocess.php @@ -5,8 +5,9 @@ use Illuminate\Console\Command; use LastDragon_ru\LaraASP\Core\Utils\Cast; use LastDragon_ru\LaraASP\Documentator\Package; -use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\ParameterizableInstruction; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\Instruction; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Preprocessor; +use LastDragon_ru\LaraASP\Documentator\Utils\Markdown; use LastDragon_ru\LaraASP\Documentator\Utils\PhpDoc; use LastDragon_ru\LaraASP\Serializer\Contracts\Serializable; use Override; @@ -16,8 +17,6 @@ use Symfony\Component\Filesystem\Filesystem; use Symfony\Component\Finder\Finder; -use function array_map; -use function explode; use function getcwd; use function gettype; use function implode; @@ -25,7 +24,6 @@ use function is_scalar; use function ksort; use function rtrim; -use function str_replace; use function strtr; use function trim; use function var_export; @@ -53,32 +51,11 @@ class Preprocess extends Command { * @var string */ public $help = <<<'HELP' - Replaces special instructions in Markdown. Instruction is the [link - reference definition](https://github.github.com/gfm/#link-reference-definitions), - so the syntax is: - - ```plain - []: - []: () - [=name]: - ``` - - Where: - * `` the instruction name (unknown instructions will be ignored) - * `` usually the path to the file or directory, but see the instruction description - * `` optional JSON string with additional parameters - (can be wrapped by `(...)`, `"..."`, or `'...'`) + %description% ## Instructions %instructions% - - ## Limitations - - * `` will be processed everywhere in the file (eg within - the code block) and may give unpredictable results. - * `` cannot be inside text. - * Nested `` doesn't support. HELP; public function __construct( @@ -117,56 +94,49 @@ function () use ($filesystem, $file): void { #[Override] public function getProcessedHelp(): string { return strtr(parent::getProcessedHelp(), [ - '%instructions%' => $this->getInstructionsHelp(), + '%description%' => $this->getProcessedHelpDescription(), + '%instructions%' => $this->getProcessedHelpInstructions(), ]); } - protected function getInstructionsHelp(): string { + protected function getProcessedHelpDescription(): string { + return $this->getDocBlock(new ReflectionClass(Preprocessor::class)); + } + + protected function getProcessedHelpInstructions(): string { $instructions = $this->preprocessor->getInstructions(); $help = []; foreach ($instructions as $instruction) { - $name = $instruction::getName(); - $desc = $instruction::getDescription(); - $target = $instruction::getTargetDescription(); - $params = is_a($instruction, ParameterizableInstruction::class, true) - ? $this->getInstructionParameters($instruction) - : null; - - if ($target !== null && $params !== null) { - $parameters = []; - - foreach ($params as $paramName => $paramDescription) { - $paramName = trim($paramName); - $paramDescription = trim($paramDescription); - $parameters[] = "`{$paramName}` - {$paramDescription}"; - } - - $prefix = ' * '; - $parameters = $prefix.implode("\n{$prefix}", $parameters); - $help[$name] = <<getDocBlock($class); + $resolver = $this->getProcessedHelpInstructionResolver($instruction, 2); + $resolver = trim($resolver); + $parameters = $this->getProcessedHelpInstructionParameters($instruction, 2); + + if ($parameters !== null) { + $help[$name] = rtrim( + << ` - * `` - {$target} + * `` - {$resolver} * `` - additional parameters {$parameters} {$desc} - HELP; - } elseif ($target !== null) { - $help[$name] = <<` - * `` - {$target} + * `` - {$resolver} {$desc} - HELP; - } else { - $help[$name] = <<> $instruction - * - * @return array + * @param class-string> $instruction + * @param int<0, max> $padding + */ + protected function getProcessedHelpInstructionResolver(string $instruction, int $padding): string { + $class = new ReflectionClass($instruction::getResolver()); + $help = $this->getDocBlock($class, $padding); + $help = rtrim($help); + + return $help; + } + + /** + * @param class-string> $instruction + * @param int<0, max> $padding */ - protected function getInstructionParameters(string $instruction): array { - $class = new ReflectionClass($instruction::getParameters()); + protected function getProcessedHelpInstructionParameters(string $instruction, int $padding): ?string { + // Has? + $class = $instruction::getParameters(); + + if ($class === null) { + return null; + } elseif (!is_a($class, Serializable::class, true)) { + return ''; // not yet supported... + } else { + // empty + } + + // Extract + $class = new ReflectionClass($class); $properties = $class->getProperties(ReflectionProperty::IS_PUBLIC); $parameters = []; @@ -225,17 +216,36 @@ protected function getInstructionParameters(string $instruction): array { // empty } - // Description - $doc = new PhpDoc($property->getDocComment() ?: null); - $description = $doc->getSummary() ?: '_No description provided_.'; - $description = trim( - implode(' ', array_map(rtrim(...), explode("\n", str_replace("\r\n", "\n", $description)))), + // Add + $parameters[trim($definition)] = trim( + $this->getDocBlock($property, $padding) ?: '_No description provided_.', ); + } - // Add - $parameters[$definition] = $description; + // Serialize + $list = ''; + + foreach ($parameters as $definition => $description) { + $list .= "* `{$definition}` - {$description}\n"; } - return $parameters; + $list = Markdown::setPadding($list, $padding); + $list = rtrim($list); + + // Return + return $list; + } + + /** + * @param ReflectionClass|ReflectionProperty $object + * @param int<0, max> $padding + */ + private function getDocBlock(ReflectionClass|ReflectionProperty $object, int $padding = 0): string { + $doc = new PhpDoc($object->getDocComment() ?: null); + $help = $doc->getText(); + $help = Markdown::setPadding($help, $padding); + $help = rtrim($help); + + return $help; } } diff --git a/packages/documentator/src/Commands/PreprocessTest.php b/packages/documentator/src/Commands/PreprocessTest.php index 7823879a2..0b66cfd9b 100644 --- a/packages/documentator/src/Commands/PreprocessTest.php +++ b/packages/documentator/src/Commands/PreprocessTest.php @@ -2,40 +2,163 @@ namespace LastDragon_ru\LaraASP\Documentator\Commands; -use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\ParameterizableInstruction; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\Instruction; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\Resolver; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Preprocessor; use LastDragon_ru\LaraASP\Documentator\Testing\Package\TestCase; use LastDragon_ru\LaraASP\Serializer\Contracts\Serializable; use Mockery; use Override; use PHPUnit\Framework\Attributes\CoversClass; +use stdClass; /** * @internal */ #[CoversClass(Preprocess::class)] final class PreprocessTest extends TestCase { - public function testGetInstructionParameters(): void { + public function testGetProcessedHelpInstructions(): void { + $preprocessor = Mockery::mock(Preprocessor::class); + $preprocessor->shouldAllowMockingProtectedMethods(); + $preprocessor + ->shouldReceive('getInstructions') + ->once() + ->andReturn([ + PreprocessTest__Instruction::class, + PreprocessTest__InstructionNoParameters::class, + PreprocessTest__InstructionNotSerializable::class, + ]); + + $command = new class($preprocessor) extends Preprocess { + #[Override] + public function getProcessedHelpInstructions(): string { + return parent::getProcessedHelpInstructions(); + } + }; + + self::assertEquals( + <<<'MARKDOWN' + ### `[test:instruction]: ` + + * `` - Target target target target target. + + Target target target target target target target target target + target target target target target target target target target. + * `` - additional parameters + * `publicPropertyWithoutDefaultValue: int` - Description. + * `publicPropertyWithDefaultValue: float = 123.0` - _No description provided_. + * `publicPromotedPropertyWithoutDefaultValue: int` - Description. + * `publicPromotedPropertyWithDefaultValue: int = 321` - Summary. + + Description description description description description + description description description description. + + Summary summary summary. + + Description description description description description description + description description description description description description + description. + + ### `[test:instruction-no-parameters]: ` + + * `` - Target target target target target. + + Target target target target target target target target target + target target target target target target target target target. + + ### `[test:instruction-not-serializable]: ` + + * `` - Target target target target target. + + Target target target target target target target target target + target target target target target target target target target. + * `` - additional parameters + MARKDOWN, + $command->getProcessedHelpInstructions(), + ); + } + + public function testGetProcessedHelpInstructionResolver(): void { + $preprocessor = Mockery::mock(Preprocessor::class); + $command = new class($preprocessor) extends Preprocess { + #[Override] + public function getProcessedHelpInstructionResolver(string $instruction, int $padding): string { + return parent::getProcessedHelpInstructionResolver($instruction, $padding); + } + }; + + self::assertEquals( + <<<'MARKDOWN' + Target target target target target. + + Target target target target target target target target target + target target target target target target target target target. + MARKDOWN, + $command->getProcessedHelpInstructionResolver( + PreprocessTest__Instruction::class, + 4, + ), + ); + } + + public function testGetProcessedHelpInstructionParameters(): void { + $preprocessor = Mockery::mock(Preprocessor::class); + $command = new class($preprocessor) extends Preprocess { + #[Override] + public function getProcessedHelpInstructionParameters(string $instruction, int $padding): ?string { + return parent::getProcessedHelpInstructionParameters($instruction, $padding); + } + }; + + self::assertEquals( + <<<'MARKDOWN' + * `publicPropertyWithoutDefaultValue: int` - Description. + * `publicPropertyWithDefaultValue: float = 123.0` - _No description provided_. + * `publicPromotedPropertyWithoutDefaultValue: int` - Description. + * `publicPromotedPropertyWithDefaultValue: int = 321` - Summary. + + Description description description description description + description description description description. + MARKDOWN, + $command->getProcessedHelpInstructionParameters( + PreprocessTest__Instruction::class, + 4, + ), + ); + } + + public function testGetProcessedHelpInstructionParametersNoParameters(): void { + $preprocessor = Mockery::mock(Preprocessor::class); + $command = new class($preprocessor) extends Preprocess { + #[Override] + public function getProcessedHelpInstructionParameters(string $instruction, int $padding): ?string { + return parent::getProcessedHelpInstructionParameters($instruction, $padding); + } + }; + + self::assertNull( + $command->getProcessedHelpInstructionParameters( + PreprocessTest__InstructionNoParameters::class, + 4, + ), + ); + } + + public function testGetProcessedHelpInstructionParametersNotSerializable(): void { $preprocessor = Mockery::mock(Preprocessor::class); $command = new class($preprocessor) extends Preprocess { - /** - * @inheritDoc - */ #[Override] - public function getInstructionParameters(string $instruction): array { - return parent::getInstructionParameters($instruction); + public function getProcessedHelpInstructionParameters(string $instruction, int $padding): ?string { + return parent::getProcessedHelpInstructionParameters($instruction, $padding); } }; self::assertEquals( - [ - 'publicPropertyWithoutDefaultValue: int' => 'Description.', - 'publicPropertyWithDefaultValue: float = 123.0' => '_No description provided_.', - 'publicPromotedPropertyWithoutDefaultValue: int' => 'Description.', - 'publicPromotedPropertyWithDefaultValue: int = 321' => '_No description provided_.', - ], - $command->getInstructionParameters( - PreprocessTest__ParameterizableInstruction::class, + '', + $command->getProcessedHelpInstructionParameters( + PreprocessTest__InstructionNotSerializable::class, + 4, ), ); } @@ -45,51 +168,118 @@ public function getInstructionParameters(string $instruction): array { // @phpcs:disable Squiz.Classes.ValidClassName.NotCamelCaps /** + * Summary summary summary. + * + * Description description description description description description + * description description description description description description + * description. + * * @internal * @noinspection PhpMultipleClassesDeclarationsInOneFile * - * @implements ParameterizableInstruction + * @implements Instruction */ -class PreprocessTest__ParameterizableInstruction implements ParameterizableInstruction { +class PreprocessTest__Instruction implements Instruction { #[Override] public static function getName(): string { - return 'test:parameterizable-instruction'; + return 'test:instruction'; } #[Override] - public static function getDescription(): string { - return 'Description description description description description.'; + public static function getResolver(): string { + return PreprocessTest__Target::class; } #[Override] - public static function getTargetDescription(): ?string { - return 'Target target target target target.'; + public static function getParameters(): ?string { + return PreprocessTest__Parameters::class; } #[Override] - public static function getParameters(): string { - return PreprocessTest__ParameterizableInstructionParameters::class; + public function process(Context $context, mixed $target, mixed $parameters): string { + return $target; + } +} + +/** + * @internal + * @noinspection PhpMultipleClassesDeclarationsInOneFile + * + * @implements Instruction + */ +class PreprocessTest__InstructionNoParameters implements Instruction { + #[Override] + public static function getName(): string { + return 'test:instruction-no-parameters'; + } + + #[Override] + public static function getResolver(): string { + return PreprocessTest__Target::class; + } + + #[Override] + public static function getParameters(): ?string { + return null; + } + + #[Override] + public function process(Context $context, mixed $target, mixed $parameters): string { + return $target; + } +} + +/** + * @internal + * @noinspection PhpMultipleClassesDeclarationsInOneFile + * + * @implements Instruction + */ +class PreprocessTest__InstructionNotSerializable implements Instruction { + #[Override] + public static function getName(): string { + return 'test:instruction-not-serializable'; + } + + #[Override] + public static function getResolver(): string { + return PreprocessTest__Target::class; } - /** - * @inheritDoc - */ #[Override] - public static function getParametersDescription(): array { - return []; + public static function getParameters(): ?string { + return stdClass::class; } #[Override] - public function process(string $path, string $target, Serializable $parameters): string { - return $path; + public function process(Context $context, mixed $target, mixed $parameters): string { + return $target; } } /** + * Target target target target target. + * + * Target target target target target target target target target + * target target target target target target target target target. + * * @internal * @noinspection PhpMultipleClassesDeclarationsInOneFile + * + * @implements Resolver */ -class PreprocessTest__ParameterizableInstructionParameters implements Serializable { +class PreprocessTest__Target implements Resolver { + #[Override] + public function resolve(Context $context, mixed $parameters): mixed { + return $context->target; + } +} + +/** + * @internal + * @noinspection PhpMultipleClassesDeclarationsInOneFile + */ +class PreprocessTest__Parameters implements Serializable { public static bool $publicStaticProperty = true; /** @@ -103,6 +293,12 @@ public function __construct( * Description. */ public int $publicPromotedPropertyWithoutDefaultValue, + /** + * Summary. + * + * Description description description description description + * description description description description. + */ public int $publicPromotedPropertyWithDefaultValue = 321, protected bool $protectedProperty = true, protected bool $privateProperty = true, diff --git a/packages/documentator/src/Preprocessor/Preprocessor.php b/packages/documentator/src/Preprocessor/Preprocessor.php index 55a78b748..f2c074c70 100644 --- a/packages/documentator/src/Preprocessor/Preprocessor.php +++ b/packages/documentator/src/Preprocessor/Preprocessor.php @@ -35,28 +35,31 @@ use const PREG_UNMATCHED_AS_NULL; /** - * Replaces special instructions in Markdown. Instruction is the link reference - * definition, so the syntax is: + * Replaces special instructions in Markdown. Instruction is the [link + * reference definition](https://github.github.com/gfm/#link-reference-definitions), + * so the syntax is: * - * []: - * []: () - * [=name]: + * ```plain + * []: + * []: () + * [=name]: + * [=name]: () + * ``` * * Where: - * - `` the instruction name (unknown instructions will be ignored) - * - `` usually the path to the file or directory, but see the - * instruction description - * - `` optional JSON string with additional parameters (can be wrapped - * by `(...)`, `"..."`, or `'...'`) + * * `` the instruction name (unknown instructions will be ignored) + * * `` usually the path to the file or directory, but see the instruction description + * * `` optional JSON string with additional parameters + * (can be wrapped by `(...)`, `"..."`, or `'...'`) * - * Limitations: - * - `` will be processed everywhere in the file (eg within the code - * block) and may give unpredictable results. - * - `` cannot be inside text. - * - Nested `` doesn't supported. + * ## Limitations + * + * * `` will be processed everywhere in the file (eg within + * the code block) and may give unpredictable results. + * * `` cannot be inside text. + * * Nested `` doesn't support. * * @todo Use https://github.com/thephpleague/commonmark? - * @todo Sync with {@see Preprocess} command * * @see Preprocess */ From 1d9c6228b92ab9e292a60679c3453fd8ad377bd3 Mon Sep 17 00:00:00 2001 From: Aleksei Lebedev <1329824+LastDragon-ru@users.noreply.github.com> Date: Tue, 7 May 2024 14:12:28 +0400 Subject: [PATCH 07/14] Code cleanup. --- .../Preprocessor/Contracts/Instruction.php | 1 - .../Contracts/ParameterizableInstruction.php | 21 ------------------- .../Contracts/ProcessableInstruction.php | 10 --------- .../src/Preprocessor/Preprocessor.php | 2 ++ .../src/Preprocessor/PreprocessorTest.php | 2 +- .../src/Preprocessor/Targets/FilePath.php | 1 + 6 files changed, 4 insertions(+), 33 deletions(-) delete mode 100644 packages/documentator/src/Preprocessor/Contracts/ParameterizableInstruction.php delete mode 100644 packages/documentator/src/Preprocessor/Contracts/ProcessableInstruction.php diff --git a/packages/documentator/src/Preprocessor/Contracts/Instruction.php b/packages/documentator/src/Preprocessor/Contracts/Instruction.php index 88195b235..9d26dcd81 100644 --- a/packages/documentator/src/Preprocessor/Contracts/Instruction.php +++ b/packages/documentator/src/Preprocessor/Contracts/Instruction.php @@ -24,7 +24,6 @@ public static function getResolver(): string; public static function getParameters(): ?string; /** - * @param Context $context * @param TTarget $target * @param TParameters $parameters */ diff --git a/packages/documentator/src/Preprocessor/Contracts/ParameterizableInstruction.php b/packages/documentator/src/Preprocessor/Contracts/ParameterizableInstruction.php deleted file mode 100644 index 720575675..000000000 --- a/packages/documentator/src/Preprocessor/Contracts/ParameterizableInstruction.php +++ /dev/null @@ -1,21 +0,0 @@ - - */ - public static function getParameters(): string; - - /** - * @param TParameters $parameters - */ - public function process(string $path, string $target, Serializable $parameters): string; -} diff --git a/packages/documentator/src/Preprocessor/Contracts/ProcessableInstruction.php b/packages/documentator/src/Preprocessor/Contracts/ProcessableInstruction.php deleted file mode 100644 index 762c0788a..000000000 --- a/packages/documentator/src/Preprocessor/Contracts/ProcessableInstruction.php +++ /dev/null @@ -1,10 +0,0 @@ - Date: Tue, 7 May 2024 14:21:16 +0400 Subject: [PATCH 08/14] `Preprocessor` will not try to parse unknown instructions. --- .../src/Preprocessor/Preprocessor.php | 22 +++++++++++-------- .../src/Preprocessor/PreprocessorTest.php | 4 ++-- 2 files changed, 15 insertions(+), 11 deletions(-) diff --git a/packages/documentator/src/Preprocessor/Preprocessor.php b/packages/documentator/src/Preprocessor/Preprocessor.php index 1f4d9f94c..a62ac8e71 100644 --- a/packages/documentator/src/Preprocessor/Preprocessor.php +++ b/packages/documentator/src/Preprocessor/Preprocessor.php @@ -147,19 +147,25 @@ public function process(string $path, string $string): string { $result = preg_replace_callback( pattern : static::Regexp, callback: function (array $matches) use (&$cache, $path): string { - // Hash + // Instruction? $instruction = $this->getInstruction($matches['instruction']); - $target = $matches['target']; - $target = str_starts_with($target, '<') && str_ends_with($target, '>') + + if (!$instruction) { + return $matches['expression']; + } + + // Hash + $target = $matches['target']; + $target = str_starts_with($target, '<') && str_ends_with($target, '>') ? mb_substr($target, 1, -1) : rawurldecode($target); - $json = $this->getParametersJson($matches['parameters'] ?: '{}'); - $hash = $this->getHash("{$matches['instruction']}({$target}, {$json})"); + $json = $this->getParametersJson($matches['parameters'] ?: '{}'); + $hash = $this->getHash("{$matches['instruction']}({$target}, {$json})"); // Content $content = $cache[$hash] ?? null; - if ($instruction && $content === null) { + if ($content === null) { $params = $instruction::getParameters(); $params = $params ? $this->serializer->deserialize($params, $json, 'json') : null; $context = new Context($path, $target, $matches['parameters']); @@ -189,14 +195,12 @@ public function process(string $path, string $string): string { {$suffix} RESULT; - } elseif ($instruction) { + } else { $content = << Date: Tue, 7 May 2024 14:22:13 +0400 Subject: [PATCH 09/14] Missed description. --- packages/documentator/src/Commands/Preprocess.php | 2 +- packages/documentator/src/Preprocessor/Targets/FileContent.php | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/packages/documentator/src/Commands/Preprocess.php b/packages/documentator/src/Commands/Preprocess.php index 25d255809..dc3bf4b16 100644 --- a/packages/documentator/src/Commands/Preprocess.php +++ b/packages/documentator/src/Commands/Preprocess.php @@ -112,7 +112,7 @@ protected function getProcessedHelpInstructions(): string { $name = $instruction::getName(); $desc = $this->getDocBlock($class); $resolver = $this->getProcessedHelpInstructionResolver($instruction, 2); - $resolver = trim($resolver); + $resolver = trim($resolver ?: '_No description provided_.'); $parameters = $this->getProcessedHelpInstructionParameters($instruction, 2); if ($parameters !== null) { diff --git a/packages/documentator/src/Preprocessor/Targets/FileContent.php b/packages/documentator/src/Preprocessor/Targets/FileContent.php index 06c9cb918..bef9c06c8 100644 --- a/packages/documentator/src/Preprocessor/Targets/FileContent.php +++ b/packages/documentator/src/Preprocessor/Targets/FileContent.php @@ -8,6 +8,9 @@ use function file_get_contents; +/** + * File path. + */ class FileContent extends FilePath { #[Override] public function resolve(Context $context, mixed $parameters): string { From ced606ae043a84c44c5f06ee40569d23ce149b77 Mon Sep 17 00:00:00 2001 From: Aleksei Lebedev <1329824+LastDragon-ru@users.noreply.github.com> Date: Tue, 7 May 2024 14:27:46 +0400 Subject: [PATCH 10/14] docs: rebuild. --- README.md | 12 +++++----- UPGRADE.md | 4 ++-- packages/core/README.md | 12 +++++----- packages/core/UPGRADE.md | 12 +++++----- packages/dev/README.md | 12 +++++----- packages/dev/UPGRADE.md | 4 ++-- packages/documentator/README.md | 12 +++++----- packages/documentator/UPGRADE.md | 12 +++++----- .../documentator/docs/Commands/preprocess.md | 22 +++++++++-------- packages/eloquent/README.md | 12 +++++----- packages/eloquent/UPGRADE.md | 12 +++++----- packages/formatter/README.md | 24 +++++++++---------- packages/formatter/UPGRADE.md | 12 +++++----- packages/graphql-printer/README.md | 24 +++++++++---------- packages/graphql-printer/UPGRADE.md | 4 ++-- .../AssertGraphQLExportableEquals.md | 4 ++-- .../AssertGraphQLPrintableEquals.md | 4 ++-- packages/graphql/README.md | 24 +++++++++---------- packages/graphql/UPGRADE.md | 12 +++++----- .../AssertGraphQLIntrospectionEquals.md | 4 ++-- .../Assertions/AssertGraphQLSchemaEquals.md | 4 ++-- .../AssertGraphQLSchemaNoBreakingChanges.md | 4 ++-- .../AssertGraphQLSchemaNoDangerousChanges.md | 4 ++-- .../Assertions/AssertGraphQLSchemaValid.md | 4 ++-- packages/graphql/docs/Directives/@searchBy.md | 16 ++++++------- packages/graphql/docs/Directives/@sortBy.md | 12 +++++----- packages/graphql/docs/Directives/@stream.md | 8 +++---- packages/graphql/docs/Directives/@type.md | 4 ++-- packages/graphql/docs/Scalars/JsonString.md | 4 ++-- packages/migrator/README.md | 12 +++++----- packages/migrator/UPGRADE.md | 12 +++++----- packages/serializer/README.md | 16 ++++++------- packages/serializer/UPGRADE.md | 12 +++++----- packages/spa/README.md | 12 +++++----- packages/spa/UPGRADE.md | 12 +++++----- packages/testing/README.md | 20 ++++++++-------- packages/testing/UPGRADE.md | 12 +++++----- .../Assertions/AssertDatabaseQueryEquals.md | 4 ++-- .../Assertions/AssertJsonMatchesSchema.md | 4 ++-- .../docs/Assertions/AssertPsrResponse.md | 4 ++-- .../docs/Assertions/AssertQueryLogEquals.md | 4 ++-- .../docs/Assertions/AssertScheduled.md | 4 ++-- .../docs/Assertions/AssertScoutQueryEquals.md | 4 ++-- .../docs/Assertions/AssertThatResponse.md | 4 ++-- .../docs/Assertions/AssertXmlMatchesSchema.md | 4 ++-- 45 files changed, 220 insertions(+), 218 deletions(-) diff --git a/README.md b/README.md index d0666f4a8..d70aa4b91 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ The set provides best practices to make development more fun and classes/services that I found very useful while working on big extensible applications. [include:exec]: <./dev/artisan lara-asp-documentator:requirements> -[//]: # (start: 3d045d7a4689231a18ef4436deb0b7c931a93959113b45d9f544bd2b0edcf45d) +[//]: # (start: 5a6479e01ca04242d936b5543af76210a1af5db5468e2f480f167a2a046b62db) [//]: # (warning: Generated automatically. Do not edit.) # Requirements @@ -25,7 +25,7 @@ The set provides best practices to make development more fun and classes/service | | `^8.22.1` | `3.0.0 ⋯ 0.2.0` | | | `^8.0` | `0.1.0` | -[//]: # (end: 3d045d7a4689231a18ef4436deb0b7c931a93959113b45d9f544bd2b0edcf45d) +[//]: # (end: 5a6479e01ca04242d936b5543af76210a1af5db5468e2f480f167a2a046b62db) # Installation @@ -112,14 +112,14 @@ Independent (from Laravel and Lighthouse) package that allow you to print GraphQ [//]: # (end: df3ee6374fabefbdeb79b26164b3f2ef88f6ed94646bb5d44751ea6da758de19) [include:file]: ./docs/Shared/Upgrading.md -[//]: # (start: 58c515c01daf29a92b704a09f78da2fa719462cc37e47d3abde0331a7b1da0a3) +[//]: # (start: cdb14a15bab8920d27c60204790e96bf814a9d780f6a55d5e93422db9bf56f64) [//]: # (warning: Generated automatically. Do not edit.) # Upgrading Please follow [Upgrade Guide](UPGRADE.md). -[//]: # (end: 58c515c01daf29a92b704a09f78da2fa719462cc37e47d3abde0331a7b1da0a3) +[//]: # (end: cdb14a15bab8920d27c60204790e96bf814a9d780f6a55d5e93422db9bf56f64) # Development @@ -129,7 +129,7 @@ Please follow [Upgrade Guide](UPGRADE.md). 4. Enjoy [include:file]: ./docs/Legend.md -[//]: # (start: a974316bcb5b40e0fcedb0c38b2c3c43c80c2cadfbf95a8caf27d6f163abff0d) +[//]: # (start: 68b5a2c9955bc3698c6033103ab34e32d67edfcff7b726f187662b5ce2e15a67) [//]: # (warning: Generated automatically. Do not edit.) # Legend @@ -148,4 +148,4 @@ Please follow [Upgrade Guide](UPGRADE.md). | 🆆 | CI | Running on Windows | | 🅼 | CI | Running on Mac OS X | -[//]: # (end: a974316bcb5b40e0fcedb0c38b2c3c43c80c2cadfbf95a8caf27d6f163abff0d) +[//]: # (end: 68b5a2c9955bc3698c6033103ab34e32d67edfcff7b726f187662b5ce2e15a67) diff --git a/UPGRADE.md b/UPGRADE.md index cd8721c15..a9ecad721 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -1,7 +1,7 @@ # Upgrade Guide [include:file]: ./docs/Shared/Upgrade.md -[//]: # (start: 39d35167e0d4cea1b3b411d449b79f0b6df5fcbf65c5d8b9775671fe5603b7c9) +[//]: # (start: 556e36b93ca9f82e94056295c197aa9a4c8c042054927a9bf08dd9140ad872b8) [//]: # (warning: Generated automatically. Do not edit.) ## Instructions @@ -25,7 +25,7 @@ Please also see [changelog](https://github.com/LastDragon-ru/lara-asp/releases) | 🤝 | Backward-compatible change. Please note that despite you can ignore it now, but it will be mandatory in the future. | |:--:|:--------------------------------------------------------------------------------------------------------------------| -[//]: # (end: 39d35167e0d4cea1b3b411d449b79f0b6df5fcbf65c5d8b9775671fe5603b7c9) +[//]: # (end: 556e36b93ca9f82e94056295c197aa9a4c8c042054927a9bf08dd9140ad872b8) # Packages diff --git a/packages/core/README.md b/packages/core/README.md index ef77f62e9..8bfcd959a 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -3,7 +3,7 @@ This package contains useful utilities and classes. [include:exec]: <../../dev/artisan lara-asp-documentator:requirements> -[//]: # (start: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b) +[//]: # (start: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea) [//]: # (warning: Generated automatically. Do not edit.) # Requirements @@ -24,7 +24,7 @@ This package contains useful utilities and classes. | | `^9.0.0` | `5.0.0-beta.0 ⋯ 0.12.0` | | | `^8.22.1` | `3.0.0 ⋯ 0.4.0` | -[//]: # (end: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b) +[//]: # (end: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea) [include:template]: ../../docs/Shared/Installation.md ({"data": {"package": "core"}}) [//]: # (start: 701034cd4b15ff1d0ee9742e3d839f3a0c70ba66d75ff6c56f712d2f69e254ae) @@ -43,21 +43,21 @@ composer require lastdragon-ru/lara-asp-core Please see the [source code](./src) to find something interesting 😅 [include:file]: ../../docs/Shared/Upgrading.md -[//]: # (start: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b) +[//]: # (start: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a) [//]: # (warning: Generated automatically. Do not edit.) # Upgrading Please follow [Upgrade Guide](UPGRADE.md). -[//]: # (end: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b) +[//]: # (end: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a) [include:file]: ../../docs/Shared/Contributing.md -[//]: # (start: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89) +[//]: # (start: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8) [//]: # (warning: Generated automatically. Do not edit.) # Contributing This package is the part of Awesome Set of Packages for Laravel. Please use the [main repository](https://github.com/LastDragon-ru/lara-asp) to [report issues](https://github.com/LastDragon-ru/lara-asp/issues), send [pull requests](https://github.com/LastDragon-ru/lara-asp/pulls), or [ask questions](https://github.com/LastDragon-ru/lara-asp/discussions). -[//]: # (end: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89) +[//]: # (end: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8) diff --git a/packages/core/UPGRADE.md b/packages/core/UPGRADE.md index afed3828d..0ba72f4c4 100644 --- a/packages/core/UPGRADE.md +++ b/packages/core/UPGRADE.md @@ -1,7 +1,7 @@ # Upgrade Guide [include:file]: ../../docs/Shared/Upgrade.md -[//]: # (start: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2) +[//]: # (start: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d) [//]: # (warning: Generated automatically. Do not edit.) ## Instructions @@ -25,26 +25,26 @@ Please also see [changelog](https://github.com/LastDragon-ru/lara-asp/releases) | 🤝 | Backward-compatible change. Please note that despite you can ignore it now, but it will be mandatory in the future. | |:--:|:--------------------------------------------------------------------------------------------------------------------| -[//]: # (end: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2) +[//]: # (end: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d) # Upgrade from v6 [include:file]: ../../docs/Shared/Upgrade/FromV6.md -[//]: # (start: 6b55bf5daea407a4590344596d41efd8368a783e2666bfe431a88a5eeaff3a95) +[//]: # (start: 8dae6cc48a78a268dcc7b747e512f85b410c9a9392ffac0734f4b17d390f1883) [//]: # (warning: Generated automatically. Do not edit.) * [ ] Direct usages of `Container::getInstances()` were replaced by explicit constructor parameters. You may need to update your code accordingly (#151). -[//]: # (end: 6b55bf5daea407a4590344596d41efd8368a783e2666bfe431a88a5eeaff3a95) +[//]: # (end: 8dae6cc48a78a268dcc7b747e512f85b410c9a9392ffac0734f4b17d390f1883) * [ ] `\LastDragon_ru\LaraASP\Core\Provider\WithRoutes::bootRoutes()` requires settings. # Upgrade from v5 [include:file]: ../../docs/Shared/Upgrade/FromV5.md -[//]: # (start: fd146cf51ef5a8d9d13e0317c09860f472c63cb3d60d02f4d95deb3e12cae73d) +[//]: # (start: 599c87007f162e34f4fd0c7874d4fcf8676e5d8c761d27a9456b284c7d1d12f2) [//]: # (warning: Generated automatically. Do not edit.) * [ ] Laravel v9 is not supported anymore. Migrate to the newer version. -[//]: # (end: fd146cf51ef5a8d9d13e0317c09860f472c63cb3d60d02f4d95deb3e12cae73d) +[//]: # (end: 599c87007f162e34f4fd0c7874d4fcf8676e5d8c761d27a9456b284c7d1d12f2) diff --git a/packages/dev/README.md b/packages/dev/README.md index 76e615c08..703f67d20 100644 --- a/packages/dev/README.md +++ b/packages/dev/README.md @@ -3,7 +3,7 @@ Various internal tools and helpers to develop the package itself. [include:exec]: <../../dev/artisan lara-asp-documentator:requirements> -[//]: # (start: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b) +[//]: # (start: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea) [//]: # (warning: Generated automatically. Do not edit.) # Requirements @@ -15,7 +15,7 @@ Various internal tools and helpers to develop the package itself. | | `^8.1` | `HEAD ⋯ 6.2.0` | | PHPStan | `^1.10` | `HEAD ⋯ 6.2.0` | -[//]: # (end: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b) +[//]: # (end: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea) [include:template]: ../../docs/Shared/InstallationDev.md ({"data": {"package": "dev"}}) [//]: # (start: e7fd13bb6d43bcc48d9fe51411b607bee0e47ccbcb1b788889f59b733865e0f1) @@ -38,21 +38,21 @@ composer require --dev lastdragon-ru/lara-asp-dev _In progress_. [include:file]: ../../docs/Shared/Upgrading.md -[//]: # (start: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b) +[//]: # (start: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a) [//]: # (warning: Generated automatically. Do not edit.) # Upgrading Please follow [Upgrade Guide](UPGRADE.md). -[//]: # (end: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b) +[//]: # (end: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a) [include:file]: ../../docs/Shared/Contributing.md -[//]: # (start: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89) +[//]: # (start: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8) [//]: # (warning: Generated automatically. Do not edit.) # Contributing This package is the part of Awesome Set of Packages for Laravel. Please use the [main repository](https://github.com/LastDragon-ru/lara-asp) to [report issues](https://github.com/LastDragon-ru/lara-asp/issues), send [pull requests](https://github.com/LastDragon-ru/lara-asp/pulls), or [ask questions](https://github.com/LastDragon-ru/lara-asp/discussions). -[//]: # (end: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89) +[//]: # (end: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8) diff --git a/packages/dev/UPGRADE.md b/packages/dev/UPGRADE.md index 7f94b9128..9da8be17d 100644 --- a/packages/dev/UPGRADE.md +++ b/packages/dev/UPGRADE.md @@ -1,7 +1,7 @@ # Upgrade Guide [include:file]: ../../docs/Shared/Upgrade.md -[//]: # (start: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2) +[//]: # (start: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d) [//]: # (warning: Generated automatically. Do not edit.) ## Instructions @@ -25,4 +25,4 @@ Please also see [changelog](https://github.com/LastDragon-ru/lara-asp/releases) | 🤝 | Backward-compatible change. Please note that despite you can ignore it now, but it will be mandatory in the future. | |:--:|:--------------------------------------------------------------------------------------------------------------------| -[//]: # (end: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2) +[//]: # (end: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d) diff --git a/packages/documentator/README.md b/packages/documentator/README.md index 6eda48360..bf2382ae3 100644 --- a/packages/documentator/README.md +++ b/packages/documentator/README.md @@ -3,7 +3,7 @@ This package provides various utilities for documentation generation such as Markdown Preprocessor, Requirements Dumper and more. [include:exec]: <../../dev/artisan lara-asp-documentator:requirements> -[//]: # (start: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b) +[//]: # (start: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea) [//]: # (warning: Generated automatically. Do not edit.) # Requirements @@ -18,7 +18,7 @@ This package provides various utilities for documentation generation such as Mar | | `^10.0.0` | `6.1.0 ⋯ 5.0.0-beta.1` | | | `^9.21.0` | `5.6.0 ⋯ 5.0.0-beta.1` | -[//]: # (end: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b) +[//]: # (end: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea) [include:template]: ../../docs/Shared/Installation.md ({"data": {"package": "documentator"}}) [//]: # (start: d830b5dad8950e88a29e14aa443ca509cfa19889b5c3792b00691760fb8618bb) @@ -59,21 +59,21 @@ Generates a table with the required versions of PHP/Laravel/etc in Markdown form [//]: # (end: 3183e17484393f086cbec523de70a97446749151d781d55ef8f480075e5c75b9) [include:file]: ../../docs/Shared/Upgrading.md -[//]: # (start: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b) +[//]: # (start: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a) [//]: # (warning: Generated automatically. Do not edit.) # Upgrading Please follow [Upgrade Guide](UPGRADE.md). -[//]: # (end: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b) +[//]: # (end: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a) [include:file]: ../../docs/Shared/Contributing.md -[//]: # (start: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89) +[//]: # (start: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8) [//]: # (warning: Generated automatically. Do not edit.) # Contributing This package is the part of Awesome Set of Packages for Laravel. Please use the [main repository](https://github.com/LastDragon-ru/lara-asp) to [report issues](https://github.com/LastDragon-ru/lara-asp/issues), send [pull requests](https://github.com/LastDragon-ru/lara-asp/pulls), or [ask questions](https://github.com/LastDragon-ru/lara-asp/discussions). -[//]: # (end: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89) +[//]: # (end: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8) diff --git a/packages/documentator/UPGRADE.md b/packages/documentator/UPGRADE.md index ab61c2fbc..91ab03c9c 100644 --- a/packages/documentator/UPGRADE.md +++ b/packages/documentator/UPGRADE.md @@ -1,7 +1,7 @@ # Upgrade Guide [include:file]: ../../docs/Shared/Upgrade.md -[//]: # (start: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2) +[//]: # (start: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d) [//]: # (warning: Generated automatically. Do not edit.) ## Instructions @@ -25,27 +25,27 @@ Please also see [changelog](https://github.com/LastDragon-ru/lara-asp/releases) | 🤝 | Backward-compatible change. Please note that despite you can ignore it now, but it will be mandatory in the future. | |:--:|:--------------------------------------------------------------------------------------------------------------------| -[//]: # (end: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2) +[//]: # (end: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d) # Upgrade from v6 [include:file]: ../../docs/Shared/Upgrade/FromV6.md -[//]: # (start: 6b55bf5daea407a4590344596d41efd8368a783e2666bfe431a88a5eeaff3a95) +[//]: # (start: 8dae6cc48a78a268dcc7b747e512f85b410c9a9392ffac0734f4b17d390f1883) [//]: # (warning: Generated automatically. Do not edit.) * [ ] Direct usages of `Container::getInstances()` were replaced by explicit constructor parameters. You may need to update your code accordingly (#151). -[//]: # (end: 6b55bf5daea407a4590344596d41efd8368a783e2666bfe431a88a5eeaff3a95) +[//]: # (end: 8dae6cc48a78a268dcc7b747e512f85b410c9a9392ffac0734f4b17d390f1883) # Upgrade from v5 [include:file]: ../../docs/Shared/Upgrade/FromV5.md -[//]: # (start: fd146cf51ef5a8d9d13e0317c09860f472c63cb3d60d02f4d95deb3e12cae73d) +[//]: # (start: 599c87007f162e34f4fd0c7874d4fcf8676e5d8c761d27a9456b284c7d1d12f2) [//]: # (warning: Generated automatically. Do not edit.) * [ ] Laravel v9 is not supported anymore. Migrate to the newer version. -[//]: # (end: fd146cf51ef5a8d9d13e0317c09860f472c63cb3d60d02f4d95deb3e12cae73d) +[//]: # (end: 599c87007f162e34f4fd0c7874d4fcf8676e5d8c761d27a9456b284c7d1d12f2) * [ ] Replace `LastDragon_ru\LaraASP\Documentator\Preprocessor\InstructionContract` by `LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\ProcessableInstruction` or `LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\ParameterizableInstruction`. diff --git a/packages/documentator/docs/Commands/preprocess.md b/packages/documentator/docs/Commands/preprocess.md index 2d766bdae..07b95d4f1 100644 --- a/packages/documentator/docs/Commands/preprocess.md +++ b/packages/documentator/docs/Commands/preprocess.md @@ -18,6 +18,7 @@ so the syntax is: []: []: () [=name]: +[=name]: () ``` Where: @@ -25,7 +26,14 @@ Where: * `` the instruction name (unknown instructions will be ignored) * `` usually the path to the file or directory, but see the instruction description * `` optional JSON string with additional parameters - (can be wrapped by `(...)`, `"..."`, or `'...'`) + (can be wrapped by `(...)`, `"..."`, or `'...'`) + +## Limitations + +* `` will be processed everywhere in the file (eg within + the code block) and may give unpredictable results. +* `` cannot be inside text. +* Nested `` doesn't support. ## Instructions @@ -44,7 +52,8 @@ which will be replaced to FQCN (if possible). Other tags are ignored. * `` - Directory path. * `` - additional parameters - * `depth: array|string|int|null = 0` - [Directory Depth](https://symfony.com/doc/current/components/finder.html#directory-depth) (eg the `0` means no nested directories, the `null` removes limits). + * `depth: array|string|int|null = 0` - [Directory Depth](https://symfony.com/doc/current/components/finder.html#directory-depth) + (eg the `0` means no nested directories, the `null` removes limits). * `template: string = 'default'` - Blade template. Returns the list of `*.md` files in the `` directory. Each file @@ -53,7 +62,7 @@ after the Header will be used as a summary. ### `[include:example]: ` -* `` - Example file path. +* `` - File path. Includes contents of the `` file as an example wrapped into ` ```code block``` `. It also searches for `.run` file, execute @@ -98,13 +107,6 @@ used to determine package name and summary. Includes the `` as a template. -## Limitations - -* `` will be processed everywhere in the file (eg within - the code block) and may give unpredictable results. -* `` cannot be inside text. -* Nested `` doesn't support. - ## Arguments ### `path?` diff --git a/packages/eloquent/README.md b/packages/eloquent/README.md index 69a842777..97e44f976 100644 --- a/packages/eloquent/README.md +++ b/packages/eloquent/README.md @@ -3,7 +3,7 @@ This package contains useful extensions and mixins for [Eloquent](https://laravel.com/docs/eloquent). [include:exec]: <../../dev/artisan lara-asp-documentator:requirements> -[//]: # (start: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b) +[//]: # (start: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea) [//]: # (warning: Generated automatically. Do not edit.) # Requirements @@ -25,7 +25,7 @@ This package contains useful extensions and mixins for [Eloquent](https://larave | | `^8.22.1` | `3.0.0 ⋯ 0.2.0` | | | `^8.0` | `0.1.0` | -[//]: # (end: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b) +[//]: # (end: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea) [include:template]: ../../docs/Shared/Installation.md ({"data": {"package": "eloquent"}}) [//]: # (start: 1c6aa4607fbf4f4c0efb2249a42271075a45316e15a4fe7f914d8bb883f71ea2) @@ -101,21 +101,21 @@ foreach ($query->getChangeSafeIterator() as $user) { | `getChangeSafeIteratorIterator()` | Return [`ChunkedChangeSafeIterator`](./src/Iterators/ChunkedChangeSafeIterator.php) instance. | [include:file]: ../../docs/Shared/Upgrading.md -[//]: # (start: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b) +[//]: # (start: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a) [//]: # (warning: Generated automatically. Do not edit.) # Upgrading Please follow [Upgrade Guide](UPGRADE.md). -[//]: # (end: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b) +[//]: # (end: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a) [include:file]: ../../docs/Shared/Contributing.md -[//]: # (start: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89) +[//]: # (start: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8) [//]: # (warning: Generated automatically. Do not edit.) # Contributing This package is the part of Awesome Set of Packages for Laravel. Please use the [main repository](https://github.com/LastDragon-ru/lara-asp) to [report issues](https://github.com/LastDragon-ru/lara-asp/issues), send [pull requests](https://github.com/LastDragon-ru/lara-asp/pulls), or [ask questions](https://github.com/LastDragon-ru/lara-asp/discussions). -[//]: # (end: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89) +[//]: # (end: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8) diff --git a/packages/eloquent/UPGRADE.md b/packages/eloquent/UPGRADE.md index 52e5ca98a..4db3e25b6 100644 --- a/packages/eloquent/UPGRADE.md +++ b/packages/eloquent/UPGRADE.md @@ -1,7 +1,7 @@ # Upgrade Guide [include:file]: ../../docs/Shared/Upgrade.md -[//]: # (start: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2) +[//]: # (start: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d) [//]: # (warning: Generated automatically. Do not edit.) ## Instructions @@ -25,24 +25,24 @@ Please also see [changelog](https://github.com/LastDragon-ru/lara-asp/releases) | 🤝 | Backward-compatible change. Please note that despite you can ignore it now, but it will be mandatory in the future. | |:--:|:--------------------------------------------------------------------------------------------------------------------| -[//]: # (end: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2) +[//]: # (end: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d) # Upgrade from v6 [include:file]: ../../docs/Shared/Upgrade/FromV6.md -[//]: # (start: 6b55bf5daea407a4590344596d41efd8368a783e2666bfe431a88a5eeaff3a95) +[//]: # (start: 8dae6cc48a78a268dcc7b747e512f85b410c9a9392ffac0734f4b17d390f1883) [//]: # (warning: Generated automatically. Do not edit.) * [ ] Direct usages of `Container::getInstances()` were replaced by explicit constructor parameters. You may need to update your code accordingly (#151). -[//]: # (end: 6b55bf5daea407a4590344596d41efd8368a783e2666bfe431a88a5eeaff3a95) +[//]: # (end: 8dae6cc48a78a268dcc7b747e512f85b410c9a9392ffac0734f4b17d390f1883) # Upgrade from v5 [include:file]: ../../docs/Shared/Upgrade/FromV5.md -[//]: # (start: fd146cf51ef5a8d9d13e0317c09860f472c63cb3d60d02f4d95deb3e12cae73d) +[//]: # (start: 599c87007f162e34f4fd0c7874d4fcf8676e5d8c761d27a9456b284c7d1d12f2) [//]: # (warning: Generated automatically. Do not edit.) * [ ] Laravel v9 is not supported anymore. Migrate to the newer version. -[//]: # (end: fd146cf51ef5a8d9d13e0317c09860f472c63cb3d60d02f4d95deb3e12cae73d) +[//]: # (end: 599c87007f162e34f4fd0c7874d4fcf8676e5d8c761d27a9456b284c7d1d12f2) diff --git a/packages/formatter/README.md b/packages/formatter/README.md index 5057a94bb..eec043db9 100644 --- a/packages/formatter/README.md +++ b/packages/formatter/README.md @@ -3,7 +3,7 @@ This package provides a customizable wrapper around [Intl](https://www.php.net/manual/en/book.intl) formatters to use it inside Laravel application. [include:exec]: <../../dev/artisan lara-asp-documentator:requirements> -[//]: # (start: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b) +[//]: # (start: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea) [//]: # (warning: Generated automatically. Do not edit.) # Requirements @@ -25,7 +25,7 @@ This package provides a customizable wrapper around [Intl](https://www.php.net/m | | `^8.22.1` | `3.0.0 ⋯ 0.2.0` | | | `^8.0` | `0.1.0` | -[//]: # (end: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b) +[//]: # (end: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea) [include:template]: ../../docs/Shared/Installation.md ({"data": {"package": "formatter"}}) [//]: # (start: ca18ec42d5b2c99e52f3a550acc6e29f65958871ab3405d38e82ef8eab2ad415) @@ -44,7 +44,7 @@ composer require lastdragon-ru/lara-asp-formatter Formatter is very simple to use: [include:example]: ./docs/Examples/Usage.php -[//]: # (start: 25c8cf0ee2862aeda3cd8ff6bf8d2d3592fee1c00042550be5ee7686ead4cc44) +[//]: # (start: c709a4b715d1bde109a5d27982a2a5d6f481b5c72338e162e394ccbb6fc9208a) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -79,7 +79,7 @@ The `$locale->decimal(123.454321)` is: "123,45" ``` -[//]: # (end: 25c8cf0ee2862aeda3cd8ff6bf8d2d3592fee1c00042550be5ee7686ead4cc44) +[//]: # (end: c709a4b715d1bde109a5d27982a2a5d6f481b5c72338e162e394ccbb6fc9208a) Please check [source code](./src/Formatter.php) to see available methods and [config example](defaults/config.php) to available settings 🤗 @@ -92,7 +92,7 @@ php artisan vendor:publish --provider=LastDragon_ru\\LaraASP\\Formatter\\Provide ``` [include:example]: ./docs/Examples/Config.php -[//]: # (start: a0315c77f2fd2868ad7a67f118ff4816a93add9ae6e7d35899828ddc32cfac37) +[//]: # (start: 5a587883c875573a9d3678bc736730f7a394c6f0ed287bfe4ccd2d2b9009a42e) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -156,7 +156,7 @@ The `$locale->date($datetime, 'custom')` is: "30.12.2023" ``` -[//]: # (end: a0315c77f2fd2868ad7a67f118ff4816a93add9ae6e7d35899828ddc32cfac37) +[//]: # (end: 5a587883c875573a9d3678bc736730f7a394c6f0ed287bfe4ccd2d2b9009a42e) # Duration @@ -184,7 +184,7 @@ The syntax is the same as [ICU Date/Time format syntax](https://unicode-org.gith [//]: # (end: 363cfceaffb54119c82e514732db74b5265a5fc6724699580b2d3c677c1258f7) [include:example]: ./docs/Examples/Duration.php -[//]: # (start: bb574f6b1315aa7b33a56d897b23ecc4d18dece9ea201b85b54154e144931d3b) +[//]: # (start: faff341985cd0ca05372c01461e1e4c151f5131fc7a76722fd00aac905a68ff9) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -219,24 +219,24 @@ The `$locale->duration(1234543)` is: "342:55:43.000" ``` -[//]: # (end: bb574f6b1315aa7b33a56d897b23ecc4d18dece9ea201b85b54154e144931d3b) +[//]: # (end: faff341985cd0ca05372c01461e1e4c151f5131fc7a76722fd00aac905a68ff9) [include:file]: ../../docs/Shared/Upgrading.md -[//]: # (start: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b) +[//]: # (start: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a) [//]: # (warning: Generated automatically. Do not edit.) # Upgrading Please follow [Upgrade Guide](UPGRADE.md). -[//]: # (end: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b) +[//]: # (end: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a) [include:file]: ../../docs/Shared/Contributing.md -[//]: # (start: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89) +[//]: # (start: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8) [//]: # (warning: Generated automatically. Do not edit.) # Contributing This package is the part of Awesome Set of Packages for Laravel. Please use the [main repository](https://github.com/LastDragon-ru/lara-asp) to [report issues](https://github.com/LastDragon-ru/lara-asp/issues), send [pull requests](https://github.com/LastDragon-ru/lara-asp/pulls), or [ask questions](https://github.com/LastDragon-ru/lara-asp/discussions). -[//]: # (end: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89) +[//]: # (end: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8) diff --git a/packages/formatter/UPGRADE.md b/packages/formatter/UPGRADE.md index 5fca9d10b..bdfeb0e03 100644 --- a/packages/formatter/UPGRADE.md +++ b/packages/formatter/UPGRADE.md @@ -1,7 +1,7 @@ # Upgrade Guide [include:file]: ../../docs/Shared/Upgrade.md -[//]: # (start: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2) +[//]: # (start: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d) [//]: # (warning: Generated automatically. Do not edit.) ## Instructions @@ -25,26 +25,26 @@ Please also see [changelog](https://github.com/LastDragon-ru/lara-asp/releases) | 🤝 | Backward-compatible change. Please note that despite you can ignore it now, but it will be mandatory in the future. | |:--:|:--------------------------------------------------------------------------------------------------------------------| -[//]: # (end: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2) +[//]: # (end: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d) # Upgrade from v6 [include:file]: ../../docs/Shared/Upgrade/FromV6.md -[//]: # (start: 6b55bf5daea407a4590344596d41efd8368a783e2666bfe431a88a5eeaff3a95) +[//]: # (start: 8dae6cc48a78a268dcc7b747e512f85b410c9a9392ffac0734f4b17d390f1883) [//]: # (warning: Generated automatically. Do not edit.) * [ ] Direct usages of `Container::getInstances()` were replaced by explicit constructor parameters. You may need to update your code accordingly (#151). -[//]: # (end: 6b55bf5daea407a4590344596d41efd8368a783e2666bfe431a88a5eeaff3a95) +[//]: # (end: 8dae6cc48a78a268dcc7b747e512f85b410c9a9392ffac0734f4b17d390f1883) # Upgrade from v5 [include:file]: ../../docs/Shared/Upgrade/FromV5.md -[//]: # (start: fd146cf51ef5a8d9d13e0317c09860f472c63cb3d60d02f4d95deb3e12cae73d) +[//]: # (start: 599c87007f162e34f4fd0c7874d4fcf8676e5d8c761d27a9456b284c7d1d12f2) [//]: # (warning: Generated automatically. Do not edit.) * [ ] Laravel v9 is not supported anymore. Migrate to the newer version. -[//]: # (end: fd146cf51ef5a8d9d13e0317c09860f472c63cb3d60d02f4d95deb3e12cae73d) +[//]: # (end: 599c87007f162e34f4fd0c7874d4fcf8676e5d8c761d27a9456b284c7d1d12f2) * [ ] If you are passing `\IntlDateFormatter::*` constants as `$format` argument for `Formatter::time()`/`Formatter::date()`/`Formatter::datetime()`, add a new custom format(s) which will refer to `\IntlDateFormatter::*` constant(s). diff --git a/packages/graphql-printer/README.md b/packages/graphql-printer/README.md index f3fe00c9e..c9fdeb5ce 100644 --- a/packages/graphql-printer/README.md +++ b/packages/graphql-printer/README.md @@ -3,7 +3,7 @@ Independent (from Laravel and Lighthouse) package that allow you to print GraphQL Schema and Queries in highly customized way eg you can choose indent size, print only used/wanted/all types, print only one type, print used/wanted/all directives ([it is not possible with standard printer](https://github.com/webonyx/graphql-php/issues/552)) and even check which types/directives are used in the Schema/Query. [include:exec]: <../../dev/artisan lara-asp-documentator:requirements> -[//]: # (start: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b) +[//]: # (start: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea) [//]: # (warning: Generated automatically. Do not edit.) # Requirements @@ -18,7 +18,7 @@ Independent (from Laravel and Lighthouse) package that allow you to print GraphQ | | `^15.2.4` | `4.2.0 ⋯ 4.0.0` | | | `^14.11.9` | `3.0.0` | -[//]: # (end: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b) +[//]: # (end: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea) [include:template]: ../../docs/Shared/Installation.md ({"data": {"package": "graphql-printer"}}) [//]: # (start: dcf3043aff3a50970117872a9bba432cb3ef84a034a0fc88bcdc6d9dcae2ec06) @@ -37,7 +37,7 @@ composer require lastdragon-ru/lara-asp-graphql-printer There are two primary methods: `Printer::print()` and `Printer::export()`. The `print()` will print the current type only, meanwhile `export()` will print the current type and all used types/directives: [include:example]: ./docs/Examples/Usage.php -[//]: # (start: 25c8cf0ee2862aeda3cd8ff6bf8d2d3592fee1c00042550be5ee7686ead4cc44) +[//]: # (start: c709a4b715d1bde109a5d27982a2a5d6f481b5c72338e162e394ccbb6fc9208a) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -113,7 +113,7 @@ type B } ``` -[//]: # (end: 25c8cf0ee2862aeda3cd8ff6bf8d2d3592fee1c00042550be5ee7686ead4cc44) +[//]: # (end: c709a4b715d1bde109a5d27982a2a5d6f481b5c72338e162e394ccbb6fc9208a) # Customization @@ -132,7 +132,7 @@ Please see: The Printer allows filter out types and directives. This may be useful to exclude them from the schema completely. Filtering also works for queries. Please note that types filtering will work only if the schema is known (the schema is required to determine the type of argument nodes). For some AST node types, their type may also be required. [include:example]: ./docs/Examples/Filtering.php -[//]: # (start: 292c33ba589c3d1a9a6b77c55aad173396a11c5fed1da07af456c995f3f55838) +[//]: # (start: 963f066509a17e2999eaa0fa940bd0f608ad2fc212eb6511f11b69eae9f7478e) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -215,7 +215,7 @@ query { } ``` -[//]: # (end: 292c33ba589c3d1a9a6b77c55aad173396a11c5fed1da07af456c995f3f55838) +[//]: # (end: 963f066509a17e2999eaa0fa940bd0f608ad2fc212eb6511f11b69eae9f7478e) # Laravel/Lighthouse @@ -242,29 +242,29 @@ Prints and compares two GraphQL schemas/types/nodes/etc. [//]: # (end: 86d73ad55f2c494dfe35350837400088c82dfa7457eafd0d30392ba96bbbdc9a) [include:file]: ../../docs/Shared/Upgrading.md -[//]: # (start: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b) +[//]: # (start: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a) [//]: # (warning: Generated automatically. Do not edit.) # Upgrading Please follow [Upgrade Guide](UPGRADE.md). -[//]: # (end: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b) +[//]: # (end: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a) [include:file]: ../../docs/Shared/Contributing.md -[//]: # (start: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89) +[//]: # (start: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8) [//]: # (warning: Generated automatically. Do not edit.) # Contributing This package is the part of Awesome Set of Packages for Laravel. Please use the [main repository](https://github.com/LastDragon-ru/lara-asp) to [report issues](https://github.com/LastDragon-ru/lara-asp/issues), send [pull requests](https://github.com/LastDragon-ru/lara-asp/pulls), or [ask questions](https://github.com/LastDragon-ru/lara-asp/discussions). -[//]: # (end: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89) +[//]: # (end: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8) [include:file]: ../../docs/Shared/Links.md -[//]: # (start: 6c180b37114202a8766bad1a59a3c0699948cc875617c85fd14a024e3bca64fe) +[//]: # (start: 9ac5c57eb03fcabb221c8db950c2dc20215f17f6e4ab17fd3a5def405da61f91) [//]: # (warning: Generated automatically. Do not edit.) [pkg:graphql#Printer]: https://github.com/LastDragon-ru/lara-asp/tree/main/packages/graphql#Printer -[//]: # (end: 6c180b37114202a8766bad1a59a3c0699948cc875617c85fd14a024e3bca64fe) +[//]: # (end: 9ac5c57eb03fcabb221c8db950c2dc20215f17f6e4ab17fd3a5def405da61f91) diff --git a/packages/graphql-printer/UPGRADE.md b/packages/graphql-printer/UPGRADE.md index 7f94b9128..9da8be17d 100644 --- a/packages/graphql-printer/UPGRADE.md +++ b/packages/graphql-printer/UPGRADE.md @@ -1,7 +1,7 @@ # Upgrade Guide [include:file]: ../../docs/Shared/Upgrade.md -[//]: # (start: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2) +[//]: # (start: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d) [//]: # (warning: Generated automatically. Do not edit.) ## Instructions @@ -25,4 +25,4 @@ Please also see [changelog](https://github.com/LastDragon-ru/lara-asp/releases) | 🤝 | Backward-compatible change. Please note that despite you can ignore it now, but it will be mandatory in the future. | |:--:|:--------------------------------------------------------------------------------------------------------------------| -[//]: # (end: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2) +[//]: # (end: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d) diff --git a/packages/graphql-printer/docs/Assertions/AssertGraphQLExportableEquals.md b/packages/graphql-printer/docs/Assertions/AssertGraphQLExportableEquals.md index e0909ee64..0de5dafe1 100644 --- a/packages/graphql-printer/docs/Assertions/AssertGraphQLExportableEquals.md +++ b/packages/graphql-printer/docs/Assertions/AssertGraphQLExportableEquals.md @@ -3,7 +3,7 @@ Exports and compares two GraphQL schemas/types/nodes/etc. [include:example]: ./AssertGraphQLExportableEqualsTest.php -[//]: # (start: 133d4e1cb1ecae97bc0bc725a805d078526526302c85ce377f2d8494690c3070) +[//]: # (start: f79b9dacbf93b9659f2c2a8a84646ad6b8603e38651064954060c16eac2f3fc0) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -81,4 +81,4 @@ final class AssertGraphQLExportableEqualsTest extends TestCase { } ``` -[//]: # (end: 133d4e1cb1ecae97bc0bc725a805d078526526302c85ce377f2d8494690c3070) +[//]: # (end: f79b9dacbf93b9659f2c2a8a84646ad6b8603e38651064954060c16eac2f3fc0) diff --git a/packages/graphql-printer/docs/Assertions/AssertGraphQLPrintableEquals.md b/packages/graphql-printer/docs/Assertions/AssertGraphQLPrintableEquals.md index 6e3a6c1ea..c01451484 100644 --- a/packages/graphql-printer/docs/Assertions/AssertGraphQLPrintableEquals.md +++ b/packages/graphql-printer/docs/Assertions/AssertGraphQLPrintableEquals.md @@ -3,7 +3,7 @@ Prints and compares two GraphQL schemas/types/nodes/etc. [include:example]: ./AssertGraphQLPrintableEqualsTest.php -[//]: # (start: 4db955285a38dee14fe701f8fbe05e7862fd773a0ea1c03e91009e86bbc0ca22) +[//]: # (start: 50e51325f68526f816540bf59f9479e5a12f5183dcf5feacf1ed62c2a5bcadb7) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -63,4 +63,4 @@ final class AssertGraphQLPrintableEqualsTest extends TestCase { } ``` -[//]: # (end: 4db955285a38dee14fe701f8fbe05e7862fd773a0ea1c03e91009e86bbc0ca22) +[//]: # (end: 50e51325f68526f816540bf59f9479e5a12f5183dcf5feacf1ed62c2a5bcadb7) diff --git a/packages/graphql/README.md b/packages/graphql/README.md index b146fab2e..2e1c6b159 100644 --- a/packages/graphql/README.md +++ b/packages/graphql/README.md @@ -3,7 +3,7 @@ This package provides highly powerful `@searchBy`, `@sortBy`, `@stream` directives for [lighthouse-php](https://lighthouse-php.com/). The `@searchBy` directive provides basic conditions like `=`, `>`, `<`, etc, relations, `not ()`, enums, and custom operators support. All are strictly typed so you no need to use `Mixed` type anymore. The `@sortBy` is not only about standard sorting by columns but also allows use relations. 😎 [include:exec]: <../../dev/artisan lara-asp-documentator:requirements> -[//]: # (start: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b) +[//]: # (start: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea) [//]: # (warning: Generated automatically. Do not edit.) # Requirements @@ -29,7 +29,7 @@ This package provides highly powerful `@searchBy`, `@sortBy`, `@stream` directiv | | `^5.6.1` | `0.12.0` , `0.11.0` | | | `^5.4` | `0.10.0 ⋯ 0.5.0` | -[//]: # (end: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b) +[//]: # (end: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea) [include:template]: ../../docs/Shared/Installation.md ({"data": {"package": "graphql"}}) [//]: # (start: 3672f37b7c4365391f12ad7a15e2e629126d25f774c584c29e7930695f44040a) @@ -182,7 +182,7 @@ class Comment extends Model { If you implement custom directives which internally enhance the Builder (like standard directives do), you may get `BuilderUnknown` error because the proper/expected builder type was not detected. In this case, your directive should implement [`BuilderInfoProvider`](./src/Builder/Contracts/BuilderInfoProvider.php) interface and to specify the builder type explicitly. [include:example]: docs/Examples/BuilderInfoProvider.php -[//]: # (start: 1484174aafe709bdcddfbae43df1e4400693ef8a41420873835aea07d36a63b3) +[//]: # (start: b68f7337a010486bff0e1669240841cc48572f37ac74466da4fc0364db6a1067) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -214,14 +214,14 @@ class CustomDirective implements Directive, BuilderInfoProvider { } ``` -[//]: # (end: 1484174aafe709bdcddfbae43df1e4400693ef8a41420873835aea07d36a63b3) +[//]: # (end: b68f7337a010486bff0e1669240841cc48572f37ac74466da4fc0364db6a1067) # Printer The package provides bindings for [`Printer`][pkg:graphql-printer] so you can simply use: [include:example]: ./docs/Examples/Printer.php -[//]: # (start: 518647e0d4a82c1d00956d3649304d6a454b183b3a926a8b403e94d33fb4301c) +[//]: # (start: 7a581dc1c9875e776a31524d2dd484da37a2b4dd60025986e9ef348c06d29a3d) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -552,7 +552,7 @@ type User { -[//]: # (end: 518647e0d4a82c1d00956d3649304d6a454b183b3a926a8b403e94d33fb4301c) +[//]: # (end: 7a581dc1c9875e776a31524d2dd484da37a2b4dd60025986e9ef348c06d29a3d) # Testing Assertions @@ -593,27 +593,27 @@ Validates default internal schema (with all directives). Faster than `lighthouse [//]: # (end: 86d73ad55f2c494dfe35350837400088c82dfa7457eafd0d30392ba96bbbdc9a) [include:file]: ../../docs/Shared/Upgrading.md -[//]: # (start: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b) +[//]: # (start: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a) [//]: # (warning: Generated automatically. Do not edit.) # Upgrading Please follow [Upgrade Guide](UPGRADE.md). -[//]: # (end: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b) +[//]: # (end: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a) [include:file]: ../../docs/Shared/Contributing.md -[//]: # (start: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89) +[//]: # (start: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8) [//]: # (warning: Generated automatically. Do not edit.) # Contributing This package is the part of Awesome Set of Packages for Laravel. Please use the [main repository](https://github.com/LastDragon-ru/lara-asp) to [report issues](https://github.com/LastDragon-ru/lara-asp/issues), send [pull requests](https://github.com/LastDragon-ru/lara-asp/pulls), or [ask questions](https://github.com/LastDragon-ru/lara-asp/discussions). -[//]: # (end: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89) +[//]: # (end: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8) [include:file]: ../../docs/Shared/Links.md -[//]: # (start: 6c180b37114202a8766bad1a59a3c0699948cc875617c85fd14a024e3bca64fe) +[//]: # (start: 9ac5c57eb03fcabb221c8db950c2dc20215f17f6e4ab17fd3a5def405da61f91) [//]: # (warning: Generated automatically. Do not edit.) [pkg:graphql#@searchBy]: https://github.com/LastDragon-ru/lara-asp/tree/main/packages/graphql/docs/Directives/@searchBy.md @@ -622,4 +622,4 @@ This package is the part of Awesome Set of Packages for Laravel. Please use the [pkg:graphql-printer]: https://github.com/LastDragon-ru/lara-asp/tree/main/packages/graphql-printer -[//]: # (end: 6c180b37114202a8766bad1a59a3c0699948cc875617c85fd14a024e3bca64fe) +[//]: # (end: 9ac5c57eb03fcabb221c8db950c2dc20215f17f6e4ab17fd3a5def405da61f91) diff --git a/packages/graphql/UPGRADE.md b/packages/graphql/UPGRADE.md index b9e8dc499..39fb7e5cd 100644 --- a/packages/graphql/UPGRADE.md +++ b/packages/graphql/UPGRADE.md @@ -1,7 +1,7 @@ # Upgrade Guide [include:file]: ../../docs/Shared/Upgrade.md -[//]: # (start: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2) +[//]: # (start: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d) [//]: # (warning: Generated automatically. Do not edit.) ## Instructions @@ -25,7 +25,7 @@ Please also see [changelog](https://github.com/LastDragon-ru/lara-asp/releases) | 🤝 | Backward-compatible change. Please note that despite you can ignore it now, but it will be mandatory in the future. | |:--:|:--------------------------------------------------------------------------------------------------------------------| -[//]: # (end: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2) +[//]: # (end: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d) ## Tips @@ -38,12 +38,12 @@ Please also see [changelog](https://github.com/LastDragon-ru/lara-asp/releases) ## General [include:file]: ../../docs/Shared/Upgrade/FromV6.md -[//]: # (start: 6b55bf5daea407a4590344596d41efd8368a783e2666bfe431a88a5eeaff3a95) +[//]: # (start: 8dae6cc48a78a268dcc7b747e512f85b410c9a9392ffac0734f4b17d390f1883) [//]: # (warning: Generated automatically. Do not edit.) * [ ] Direct usages of `Container::getInstances()` were replaced by explicit constructor parameters. You may need to update your code accordingly (#151). -[//]: # (end: 6b55bf5daea407a4590344596d41efd8368a783e2666bfe431a88a5eeaff3a95) +[//]: # (end: 8dae6cc48a78a268dcc7b747e512f85b410c9a9392ffac0734f4b17d390f1883) * [ ] The `\LastDragon_ru\LaraASP\GraphQL\Scalars\JsonStringType` is not implement `\LastDragon_ru\LaraASP\GraphQL\Builder\Contracts\TypeDefinition` anymore. To add the scalar into the Schema, you can use `@type`/`@scalar` directive, or create a custom implementation of `TypeDefinition` contract to use with `Builder`/`Manipulator`. @@ -71,12 +71,12 @@ This section is actual only if you are extending the package. Please review and ## General [include:file]: ../../docs/Shared/Upgrade/FromV5.md -[//]: # (start: fd146cf51ef5a8d9d13e0317c09860f472c63cb3d60d02f4d95deb3e12cae73d) +[//]: # (start: 599c87007f162e34f4fd0c7874d4fcf8676e5d8c761d27a9456b284c7d1d12f2) [//]: # (warning: Generated automatically. Do not edit.) * [ ] Laravel v9 is not supported anymore. Migrate to the newer version. -[//]: # (end: fd146cf51ef5a8d9d13e0317c09860f472c63cb3d60d02f4d95deb3e12cae73d) +[//]: # (end: 599c87007f162e34f4fd0c7874d4fcf8676e5d8c761d27a9456b284c7d1d12f2) * [ ] [Input type auto-generation](README.md#input-type-auto-generation) reworked and may include more/fewer fields. Please check the documentation and update the schema if needed. diff --git a/packages/graphql/docs/Assertions/AssertGraphQLIntrospectionEquals.md b/packages/graphql/docs/Assertions/AssertGraphQLIntrospectionEquals.md index b96491b50..852a5ede1 100644 --- a/packages/graphql/docs/Assertions/AssertGraphQLIntrospectionEquals.md +++ b/packages/graphql/docs/Assertions/AssertGraphQLIntrospectionEquals.md @@ -6,7 +6,7 @@ Compares default public schema (as the client sees it through introspection). [include:example]: ./AssertGraphQLIntrospectionEqualsTest.php -[//]: # (start: 8af2ec624f2d1e816e2d2feea212f379c6a2ceb87a3802714eeacc695690aa97) +[//]: # (start: 1e34791857e79d61db977fbe4be017b38ffb53811f06d451e227c376c5c218c6) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -436,6 +436,6 @@ final class AssertGraphQLIntrospectionEqualsTest extends TestCase { } ``` -[//]: # (end: 8af2ec624f2d1e816e2d2feea212f379c6a2ceb87a3802714eeacc695690aa97) +[//]: # (end: 1e34791857e79d61db977fbe4be017b38ffb53811f06d451e227c376c5c218c6) diff --git a/packages/graphql/docs/Assertions/AssertGraphQLSchemaEquals.md b/packages/graphql/docs/Assertions/AssertGraphQLSchemaEquals.md index f41534b0c..f4022f661 100644 --- a/packages/graphql/docs/Assertions/AssertGraphQLSchemaEquals.md +++ b/packages/graphql/docs/Assertions/AssertGraphQLSchemaEquals.md @@ -3,7 +3,7 @@ Compares default internal schema (with all directives). [include:example]: ./AssertGraphQLSchemaEqualsTest.php -[//]: # (start: 78ece08930d16eb88ea81e7d464ee55ccbdbdc1f5fc092bd0903eaa297981bbe) +[//]: # (start: 1bcc4bdce373bad283736df3c40bf88ff6b8faa72cbd12e3a5750ae22ac6f439) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -110,4 +110,4 @@ final class AssertGraphQLSchemaEqualsTest extends TestCase { } ``` -[//]: # (end: 78ece08930d16eb88ea81e7d464ee55ccbdbdc1f5fc092bd0903eaa297981bbe) +[//]: # (end: 1bcc4bdce373bad283736df3c40bf88ff6b8faa72cbd12e3a5750ae22ac6f439) diff --git a/packages/graphql/docs/Assertions/AssertGraphQLSchemaNoBreakingChanges.md b/packages/graphql/docs/Assertions/AssertGraphQLSchemaNoBreakingChanges.md index 07add5ee0..7f89baaba 100644 --- a/packages/graphql/docs/Assertions/AssertGraphQLSchemaNoBreakingChanges.md +++ b/packages/graphql/docs/Assertions/AssertGraphQLSchemaNoBreakingChanges.md @@ -3,7 +3,7 @@ Checks that no breaking changes in the default internal schema (with all directives). [include:example]: ./AssertGraphQLSchemaNoBreakingChangesTest.php -[//]: # (start: 706279a16f059e26ab824a9fc038dcf9dc88c9d7e8e0a505cbbdd7f643cb1fa9) +[//]: # (start: e9f72298446f8034d254998ac3b4396702a8981a7c00f14eb9ccebdadf73ea3f) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -80,4 +80,4 @@ final class AssertGraphQLSchemaNoBreakingChangesTest extends TestCase { } ``` -[//]: # (end: 706279a16f059e26ab824a9fc038dcf9dc88c9d7e8e0a505cbbdd7f643cb1fa9) +[//]: # (end: e9f72298446f8034d254998ac3b4396702a8981a7c00f14eb9ccebdadf73ea3f) diff --git a/packages/graphql/docs/Assertions/AssertGraphQLSchemaNoDangerousChanges.md b/packages/graphql/docs/Assertions/AssertGraphQLSchemaNoDangerousChanges.md index 7060b11b5..39abea36e 100644 --- a/packages/graphql/docs/Assertions/AssertGraphQLSchemaNoDangerousChanges.md +++ b/packages/graphql/docs/Assertions/AssertGraphQLSchemaNoDangerousChanges.md @@ -3,7 +3,7 @@ Checks that no dangerous changes in the default internal schema (with all directives). [include:example]: ./AssertGraphQLSchemaNoDangerousChangesTest.php -[//]: # (start: e89808347215c25407fece361d856f4087c43ac0599c7f65bba42fc4afc4fd51) +[//]: # (start: b1e5a522b2299596e819ef4f028b17963100062611b89a1ee97699e6e847dc6c) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -79,4 +79,4 @@ final class AssertGraphQLSchemaNoDangerousChangesTest extends TestCase { } ``` -[//]: # (end: e89808347215c25407fece361d856f4087c43ac0599c7f65bba42fc4afc4fd51) +[//]: # (end: b1e5a522b2299596e819ef4f028b17963100062611b89a1ee97699e6e847dc6c) diff --git a/packages/graphql/docs/Assertions/AssertGraphQLSchemaValid.md b/packages/graphql/docs/Assertions/AssertGraphQLSchemaValid.md index f1b59db70..bed96dbb9 100644 --- a/packages/graphql/docs/Assertions/AssertGraphQLSchemaValid.md +++ b/packages/graphql/docs/Assertions/AssertGraphQLSchemaValid.md @@ -3,7 +3,7 @@ Validates default internal schema (with all directives). Faster than `lighthouse:validate-schema` command because loads only used directives. [include:example]: ./AssertGraphQLSchemaValidTest.php -[//]: # (start: 1ea7c7a03ef9aacec28855402c5dc9a0417ce9d201dcdd26ad946d25f7dd56f0) +[//]: # (start: dd5e2cd2a0dfa08e0c41fb2cebb63acf79841b33dcf16658c765936ca150b73e) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -74,4 +74,4 @@ final class AssertGraphQLSchemaValidTest extends TestCase { } ``` -[//]: # (end: 1ea7c7a03ef9aacec28855402c5dc9a0417ce9d201dcdd26ad946d25f7dd56f0) +[//]: # (end: dd5e2cd2a0dfa08e0c41fb2cebb63acf79841b33dcf16658c765936ca150b73e) diff --git a/packages/graphql/docs/Directives/@searchBy.md b/packages/graphql/docs/Directives/@searchBy.md index cced27d74..c3c3393ae 100644 --- a/packages/graphql/docs/Directives/@searchBy.md +++ b/packages/graphql/docs/Directives/@searchBy.md @@ -3,7 +3,7 @@ Probably the most powerful directive to provide search (`where` conditions) for your GraphQL queries. [include:graphql-directive]: @searchBy -[//]: # (start: c9edf68d4e62631cb07d4200b30e989eaa67d65012ea5f605060a4567a197392) +[//]: # (start: 6fc59903c0b30f293d154a4e848626ee52d76fad258360243058c413339a0ba4) [//]: # (warning: Generated automatically. Do not edit.) ```graphql @@ -15,7 +15,7 @@ on | ARGUMENT_DEFINITION ``` -[//]: # (end: c9edf68d4e62631cb07d4200b30e989eaa67d65012ea5f605060a4567a197392) +[//]: # (end: 6fc59903c0b30f293d154a4e848626ee52d76fad258360243058c413339a0ba4) ## Basic usage @@ -33,7 +33,7 @@ Out of the box directives provides following features: Let's start: [include:example]: ../../src/SearchBy/Directives/DirectiveTest/Example.schema.graphql -[//]: # (start: e552ccbddb2cf6a9dd4e14f9295ad974ca19c375ba683681d959d5190028ded4) +[//]: # (start: cc0325309f64ed94ef1e996dc2a624162a7ebb35fb0e02191bf74e20a17cb2f3) [//]: # (warning: Generated automatically. Do not edit.) ```graphql @@ -67,7 +67,7 @@ type Comment { } ``` -[//]: # (end: e552ccbddb2cf6a9dd4e14f9295ad974ca19c375ba683681d959d5190028ded4) +[//]: # (end: cc0325309f64ed94ef1e996dc2a624162a7ebb35fb0e02191bf74e20a17cb2f3) That's all, just search 😃 (or look at [generated GraphQL schema](../../src/SearchBy/Directives/DirectiveTest/Example.expected.graphql)) @@ -158,7 +158,7 @@ As you can see in the example above you can use the special placeholder `_` inst The `@searchByIgnored` can be used as Ignored marker. [include:graphql-directive]: @searchByIgnored -[//]: # (start: 0344645522503dd5c49c35bbe2e023f2b8c6c02dfbc8d2fa2d41ae285d9cf0a1) +[//]: # (start: a9b2c25f23dff4186502cc93cc34a25e406edce92710315aecdfae2bbe0d1d1a) [//]: # (warning: Generated automatically. Do not edit.) ```graphql @@ -175,7 +175,7 @@ on | SCALAR ``` -[//]: # (end: 0344645522503dd5c49c35bbe2e023f2b8c6c02dfbc8d2fa2d41ae285d9cf0a1) +[//]: # (end: a9b2c25f23dff4186502cc93cc34a25e406edce92710315aecdfae2bbe0d1d1a) ## Operators @@ -234,7 +234,7 @@ scalar MyScalar Keep in mind, when you define/extend the scalar/enum, it will override all existing operators, so if you just want to add new operators, the `@searchByExtendOperators` directive should be used. [include:graphql-directive]: @searchByExtendOperators -[//]: # (start: fcfc25099864ad3b862835be85a0b621ab899c318715cd7e9fcee13691868eba) +[//]: # (start: df58b83a1ba68755665e0657a0ec9e4040fa2887c91de730680491d84e9e3251) [//]: # (warning: Generated automatically. Do not edit.) ```graphql @@ -250,7 +250,7 @@ on | SCALAR ``` -[//]: # (end: fcfc25099864ad3b862835be85a0b621ab899c318715cd7e9fcee13691868eba) +[//]: # (end: df58b83a1ba68755665e0657a0ec9e4040fa2887c91de730680491d84e9e3251) ### Schema diff --git a/packages/graphql/docs/Directives/@sortBy.md b/packages/graphql/docs/Directives/@sortBy.md index 4d1754e5a..2147c3ca2 100644 --- a/packages/graphql/docs/Directives/@sortBy.md +++ b/packages/graphql/docs/Directives/@sortBy.md @@ -3,7 +3,7 @@ Probably the most powerful directive to provide sort (`order by` conditions) for your GraphQL queries. [include:graphql-directive]: @sortBy -[//]: # (start: e2d33c9307e49d5f53ac135415329a0b01b87bd56ea6f0dc6ca4ac9143395ffa) +[//]: # (start: b8a3b70da2455b8cbed2b3385a56c1e1cd9865302ab83b073700e4608bd628d2) [//]: # (warning: Generated automatically. Do not edit.) ```graphql @@ -15,14 +15,14 @@ on | ARGUMENT_DEFINITION ``` -[//]: # (end: e2d33c9307e49d5f53ac135415329a0b01b87bd56ea6f0dc6ca4ac9143395ffa) +[//]: # (end: b8a3b70da2455b8cbed2b3385a56c1e1cd9865302ab83b073700e4608bd628d2) ## Basic usage How to use (and [generated GraphQL schema](../../src/SortBy/Directives/DirectiveTest/Example.expected.graphql)): [include:example]: ../../src/SortBy/Directives/DirectiveTest/Example.schema.graphql -[//]: # (start: f4e6a88c853cd9b15aa5c3388c1b61148589eddbc18b410b0e846695c5765e4f) +[//]: # (start: 49b8762fdb7c1c571d71e331c248f86862b782b2981072697949f5dd0f8616ee) [//]: # (warning: Generated automatically. Do not edit.) ```graphql @@ -50,7 +50,7 @@ type User { } ``` -[//]: # (end: f4e6a88c853cd9b15aa5c3388c1b61148589eddbc18b410b0e846695c5765e4f) +[//]: # (end: 49b8762fdb7c1c571d71e331c248f86862b782b2981072697949f5dd0f8616ee) And: @@ -75,7 +75,7 @@ Addition rules for Implicit type: The `@sortByIgnored` can be used as Ignored marker. [include:graphql-directive]: @sortByIgnored -[//]: # (start: a49887f25c9b44ee37b7df8d7fe960d16fcb8a2ddc8681ffad8100c6b4a7462e) +[//]: # (start: 9466556f0c9243ad61ee9e72054a332e844bfe6346c488ba279f76aa7a3a0609) [//]: # (warning: Generated automatically. Do not edit.) ```graphql @@ -92,7 +92,7 @@ on | SCALAR ``` -[//]: # (end: a49887f25c9b44ee37b7df8d7fe960d16fcb8a2ddc8681ffad8100c6b4a7462e) +[//]: # (end: 9466556f0c9243ad61ee9e72054a332e844bfe6346c488ba279f76aa7a3a0609) ## Operators diff --git a/packages/graphql/docs/Directives/@stream.md b/packages/graphql/docs/Directives/@stream.md index 0e99ada04..af50efe5a 100644 --- a/packages/graphql/docs/Directives/@stream.md +++ b/packages/graphql/docs/Directives/@stream.md @@ -7,7 +7,7 @@ Unlike the `@paginate` (and similar) directive, the `@stream` provides a uniform > The directive is experimental. The true cursor pagination is not implemented yet, the limit/offset is used internally. Any feedback would be greatly appreciated. [include:graphql-directive]: @stream -[//]: # (start: edeacae9cacd4fc8137617d32f19385275282061c175ced459f6a6ac36d4f74a) +[//]: # (start: c6aae43244e8267f05923095595267c57bd8ff8b55fd9ff5cf802851fbf5c3de) [//]: # (warning: Generated automatically. Do not edit.) ```graphql @@ -69,7 +69,7 @@ input StreamBuilder { } ``` -[//]: # (end: edeacae9cacd4fc8137617d32f19385275282061c175ced459f6a6ac36d4f74a) +[//]: # (end: c6aae43244e8267f05923095595267c57bd8ff8b55fd9ff5cf802851fbf5c3de) ## Motivation @@ -176,11 +176,11 @@ Keep in mind: * Some engines may perform counting (seems actual for `Database` only) [include:file]: ../../../../docs/Shared/Links.md -[//]: # (start: 195358817c4e94ba188ca00989a67a1bf40c7db486d0f3714391b888b0143693) +[//]: # (start: a1d73b35e4ad53ef7c5e723c17abd87804cf0221167e796513476212788cd826) [//]: # (warning: Generated automatically. Do not edit.) [pkg:graphql#@searchBy]: https://github.com/LastDragon-ru/lara-asp/tree/main/packages/graphql/docs/Directives/@searchBy.md [pkg:graphql#@sortBy]: https://github.com/LastDragon-ru/lara-asp/tree/main/packages/graphql/docs/Directives/@sortBy.md -[//]: # (end: 195358817c4e94ba188ca00989a67a1bf40c7db486d0f3714391b888b0143693) +[//]: # (end: a1d73b35e4ad53ef7c5e723c17abd87804cf0221167e796513476212788cd826) diff --git a/packages/graphql/docs/Directives/@type.md b/packages/graphql/docs/Directives/@type.md index 673a684f3..5115edd2b 100644 --- a/packages/graphql/docs/Directives/@type.md +++ b/packages/graphql/docs/Directives/@type.md @@ -3,7 +3,7 @@ Converts scalar into GraphQL Type. Similar to Lighthouse's `@scalar` directive, but uses Laravel Container to resolve instance and also supports PHP enums. [include:graphql-directive]: @type -[//]: # (start: e5116f159b1c6694ddc254bd60a91ba482a2a2236554cf86e77ed1cfb1b48bbd) +[//]: # (start: 185f96f580a0c2ae26608f2c53ad97a03a28301e4c189b5abe2c3163adecc2f9) [//]: # (warning: Generated automatically. Do not edit.) ```graphql @@ -32,4 +32,4 @@ on | SCALAR ``` -[//]: # (end: e5116f159b1c6694ddc254bd60a91ba482a2a2236554cf86e77ed1cfb1b48bbd) +[//]: # (end: 185f96f580a0c2ae26608f2c53ad97a03a28301e4c189b5abe2c3163adecc2f9) diff --git a/packages/graphql/docs/Scalars/JsonString.md b/packages/graphql/docs/Scalars/JsonString.md index 6a23eeb9c..2bfce067f 100644 --- a/packages/graphql/docs/Scalars/JsonString.md +++ b/packages/graphql/docs/Scalars/JsonString.md @@ -7,9 +7,9 @@ By default, the type validates the string and throws an error if it is not a val Please note that the scalar doesn't encode/decode value to/from JSON, it just contains a valid JSON string. If you want automatically convert value to/from JSON, you can use the `JSON` type from [`mll-lab/graphql-php-scalars`](https://github.com/mll-lab/graphql-php-scalars) package. If you need something more typesafe, consider using [`Serializer`][pkg:serializer]. [include:file]: ../../../../docs/Shared/Links.md -[//]: # (start: 195358817c4e94ba188ca00989a67a1bf40c7db486d0f3714391b888b0143693) +[//]: # (start: a1d73b35e4ad53ef7c5e723c17abd87804cf0221167e796513476212788cd826) [//]: # (warning: Generated automatically. Do not edit.) [pkg:serializer]: https://github.com/LastDragon-ru/lara-asp/tree/main/packages/serializer -[//]: # (end: 195358817c4e94ba188ca00989a67a1bf40c7db486d0f3714391b888b0143693) +[//]: # (end: a1d73b35e4ad53ef7c5e723c17abd87804cf0221167e796513476212788cd826) diff --git a/packages/migrator/README.md b/packages/migrator/README.md index 45105dd9b..b219bf70a 100644 --- a/packages/migrator/README.md +++ b/packages/migrator/README.md @@ -7,7 +7,7 @@ This package improves standard Laravel migrations to add support for raw SQL fil > The Migrator uses the same mechanism as [Squashing Migrations](https://laravel.com/docs/migrations#squashing-migrations) so not all databases are supported, please see Laravel Documentation for more details. [include:exec]: <../../dev/artisan lara-asp-documentator:requirements> -[//]: # (start: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b) +[//]: # (start: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea) [//]: # (warning: Generated automatically. Do not edit.) # Requirements @@ -29,7 +29,7 @@ This package improves standard Laravel migrations to add support for raw SQL fil | | `^8.22.1` | `3.0.0 ⋯ 0.2.0` | | | `^8.0` | `0.1.0` | -[//]: # (end: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b) +[//]: # (end: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea) [include:template]: ../../docs/Shared/Installation.md ({"data": {"package": "migrator"}}) [//]: # (start: 71480f577837f2b64afb81d2af134daeb17eef704953d93e8f393d804443e2a4) @@ -102,21 +102,21 @@ class MySeeder extends RawSeeder { ``` [include:file]: ../../docs/Shared/Upgrading.md -[//]: # (start: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b) +[//]: # (start: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a) [//]: # (warning: Generated automatically. Do not edit.) # Upgrading Please follow [Upgrade Guide](UPGRADE.md). -[//]: # (end: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b) +[//]: # (end: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a) [include:file]: ../../docs/Shared/Contributing.md -[//]: # (start: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89) +[//]: # (start: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8) [//]: # (warning: Generated automatically. Do not edit.) # Contributing This package is the part of Awesome Set of Packages for Laravel. Please use the [main repository](https://github.com/LastDragon-ru/lara-asp) to [report issues](https://github.com/LastDragon-ru/lara-asp/issues), send [pull requests](https://github.com/LastDragon-ru/lara-asp/pulls), or [ask questions](https://github.com/LastDragon-ru/lara-asp/discussions). -[//]: # (end: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89) +[//]: # (end: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8) diff --git a/packages/migrator/UPGRADE.md b/packages/migrator/UPGRADE.md index 52e5ca98a..4db3e25b6 100644 --- a/packages/migrator/UPGRADE.md +++ b/packages/migrator/UPGRADE.md @@ -1,7 +1,7 @@ # Upgrade Guide [include:file]: ../../docs/Shared/Upgrade.md -[//]: # (start: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2) +[//]: # (start: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d) [//]: # (warning: Generated automatically. Do not edit.) ## Instructions @@ -25,24 +25,24 @@ Please also see [changelog](https://github.com/LastDragon-ru/lara-asp/releases) | 🤝 | Backward-compatible change. Please note that despite you can ignore it now, but it will be mandatory in the future. | |:--:|:--------------------------------------------------------------------------------------------------------------------| -[//]: # (end: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2) +[//]: # (end: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d) # Upgrade from v6 [include:file]: ../../docs/Shared/Upgrade/FromV6.md -[//]: # (start: 6b55bf5daea407a4590344596d41efd8368a783e2666bfe431a88a5eeaff3a95) +[//]: # (start: 8dae6cc48a78a268dcc7b747e512f85b410c9a9392ffac0734f4b17d390f1883) [//]: # (warning: Generated automatically. Do not edit.) * [ ] Direct usages of `Container::getInstances()` were replaced by explicit constructor parameters. You may need to update your code accordingly (#151). -[//]: # (end: 6b55bf5daea407a4590344596d41efd8368a783e2666bfe431a88a5eeaff3a95) +[//]: # (end: 8dae6cc48a78a268dcc7b747e512f85b410c9a9392ffac0734f4b17d390f1883) # Upgrade from v5 [include:file]: ../../docs/Shared/Upgrade/FromV5.md -[//]: # (start: fd146cf51ef5a8d9d13e0317c09860f472c63cb3d60d02f4d95deb3e12cae73d) +[//]: # (start: 599c87007f162e34f4fd0c7874d4fcf8676e5d8c761d27a9456b284c7d1d12f2) [//]: # (warning: Generated automatically. Do not edit.) * [ ] Laravel v9 is not supported anymore. Migrate to the newer version. -[//]: # (end: fd146cf51ef5a8d9d13e0317c09860f472c63cb3d60d02f4d95deb3e12cae73d) +[//]: # (end: 599c87007f162e34f4fd0c7874d4fcf8676e5d8c761d27a9456b284c7d1d12f2) diff --git a/packages/serializer/README.md b/packages/serializer/README.md index 910de4249..7aff772e9 100644 --- a/packages/serializer/README.md +++ b/packages/serializer/README.md @@ -3,7 +3,7 @@ This package provides a customizable wrapper around the [Symfony Serializer Component](https://symfony.com/doc/current/components/serializer.html) to use it inside Laravel application. [include:exec]: <../../dev/artisan lara-asp-documentator:requirements> -[//]: # (start: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b) +[//]: # (start: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea) [//]: # (warning: Generated automatically. Do not edit.) # Requirements @@ -19,7 +19,7 @@ This package provides a customizable wrapper around the [Symfony Serializer Comp | | `^9.21.0` | `5.6.0 ⋯ 5.0.0-beta.1` | | | `^9.0.0` | `5.0.0-beta.0` | -[//]: # (end: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b) +[//]: # (end: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea) [include:template]: ../../docs/Shared/Installation.md ({"data": {"package": "serializer"}}) [//]: # (start: d8b5372aebffede51da53eb1cdc31143e965ae14f00992219dae456a565cda4a) @@ -36,7 +36,7 @@ composer require lastdragon-ru/lara-asp-serializer # Usage [include:example]: ./docs/Examples/Usage.php -[//]: # (start: 25c8cf0ee2862aeda3cd8ff6bf8d2d3592fee1c00042550be5ee7686ead4cc44) +[//]: # (start: c709a4b715d1bde109a5d27982a2a5d6f481b5c72338e162e394ccbb6fc9208a) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -92,7 +92,7 @@ LastDragon_ru\LaraASP\Serializer\Docs\Examples\Usage\User { } ``` -[//]: # (end: 25c8cf0ee2862aeda3cd8ff6bf8d2d3592fee1c00042550be5ee7686ead4cc44) +[//]: # (end: c709a4b715d1bde109a5d27982a2a5d6f481b5c72338e162e394ccbb6fc9208a) # Extending @@ -115,7 +115,7 @@ php artisan vendor:publish --provider=LastDragon_ru\\LaraASP\\Serializer\\Provid You can use the [`LastDragon_ru\LaraASP\Serializer\Casts\Serialized`](./src/Casts/Serialized.php) attribute to populate a model attribute to/from an object: [include:example]: ./docs/Examples/Attribute.php -[//]: # (start: 211a5dc77435fa2d79fcb5afce955fdd851bd0be575b7eae03d69d3fe5111b0a) +[//]: # (start: 772b9d40577fb51685a1f6f6851c03c48d3b8bf3c966be28f918c966eeb102ad) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -174,7 +174,7 @@ The `$user->getAttributes()` is: ] ``` -[//]: # (end: 211a5dc77435fa2d79fcb5afce955fdd851bd0be575b7eae03d69d3fe5111b0a) +[//]: # (end: 772b9d40577fb51685a1f6f6851c03c48d3b8bf3c966be28f918c966eeb102ad) # Upgrading @@ -183,13 +183,13 @@ Please follow [Upgrade Guide](UPGRADE.md). [//]: # (end: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b) [include:file]: ../../docs/Shared/Contributing.md -[//]: # (start: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89) +[//]: # (start: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8) [//]: # (warning: Generated automatically. Do not edit.) # Contributing This package is the part of Awesome Set of Packages for Laravel. Please use the [main repository](https://github.com/LastDragon-ru/lara-asp) to [report issues](https://github.com/LastDragon-ru/lara-asp/issues), send [pull requests](https://github.com/LastDragon-ru/lara-asp/pulls), or [ask questions](https://github.com/LastDragon-ru/lara-asp/discussions). -[//]: # (end: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89) +[//]: # (end: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8) [^1]: diff --git a/packages/serializer/UPGRADE.md b/packages/serializer/UPGRADE.md index 52e5ca98a..4db3e25b6 100644 --- a/packages/serializer/UPGRADE.md +++ b/packages/serializer/UPGRADE.md @@ -1,7 +1,7 @@ # Upgrade Guide [include:file]: ../../docs/Shared/Upgrade.md -[//]: # (start: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2) +[//]: # (start: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d) [//]: # (warning: Generated automatically. Do not edit.) ## Instructions @@ -25,24 +25,24 @@ Please also see [changelog](https://github.com/LastDragon-ru/lara-asp/releases) | 🤝 | Backward-compatible change. Please note that despite you can ignore it now, but it will be mandatory in the future. | |:--:|:--------------------------------------------------------------------------------------------------------------------| -[//]: # (end: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2) +[//]: # (end: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d) # Upgrade from v6 [include:file]: ../../docs/Shared/Upgrade/FromV6.md -[//]: # (start: 6b55bf5daea407a4590344596d41efd8368a783e2666bfe431a88a5eeaff3a95) +[//]: # (start: 8dae6cc48a78a268dcc7b747e512f85b410c9a9392ffac0734f4b17d390f1883) [//]: # (warning: Generated automatically. Do not edit.) * [ ] Direct usages of `Container::getInstances()` were replaced by explicit constructor parameters. You may need to update your code accordingly (#151). -[//]: # (end: 6b55bf5daea407a4590344596d41efd8368a783e2666bfe431a88a5eeaff3a95) +[//]: # (end: 8dae6cc48a78a268dcc7b747e512f85b410c9a9392ffac0734f4b17d390f1883) # Upgrade from v5 [include:file]: ../../docs/Shared/Upgrade/FromV5.md -[//]: # (start: fd146cf51ef5a8d9d13e0317c09860f472c63cb3d60d02f4d95deb3e12cae73d) +[//]: # (start: 599c87007f162e34f4fd0c7874d4fcf8676e5d8c761d27a9456b284c7d1d12f2) [//]: # (warning: Generated automatically. Do not edit.) * [ ] Laravel v9 is not supported anymore. Migrate to the newer version. -[//]: # (end: fd146cf51ef5a8d9d13e0317c09860f472c63cb3d60d02f4d95deb3e12cae73d) +[//]: # (end: 599c87007f162e34f4fd0c7874d4fcf8676e5d8c761d27a9456b284c7d1d12f2) diff --git a/packages/spa/README.md b/packages/spa/README.md index 6ad2d3ce6..e6a3142e9 100644 --- a/packages/spa/README.md +++ b/packages/spa/README.md @@ -1,7 +1,7 @@ # (Laravel) SPA Helpers [include:exec]: <../../dev/artisan lara-asp-documentator:requirements> -[//]: # (start: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b) +[//]: # (start: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea) [//]: # (warning: Generated automatically. Do not edit.) # Requirements @@ -21,7 +21,7 @@ | | `^9.0.0` | `5.0.0-beta.0 ⋯ 0.12.0` | | | `^8.22.1` | `3.0.0 ⋯ 0.4.0` | -[//]: # (end: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b) +[//]: # (end: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea) [include:template]: ../../docs/Shared/Installation.md ({"data": {"package": "spa"}}) [//]: # (start: 457a42c9e8cb9eef36f7f83a3cdfc837870f5d9814b59bd304b8383789bc83fb) @@ -36,21 +36,21 @@ composer require lastdragon-ru/lara-asp-spa [//]: # (end: 457a42c9e8cb9eef36f7f83a3cdfc837870f5d9814b59bd304b8383789bc83fb) [include:file]: ../../docs/Shared/Upgrading.md -[//]: # (start: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b) +[//]: # (start: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a) [//]: # (warning: Generated automatically. Do not edit.) # Upgrading Please follow [Upgrade Guide](UPGRADE.md). -[//]: # (end: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b) +[//]: # (end: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a) [include:file]: ../../docs/Shared/Contributing.md -[//]: # (start: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89) +[//]: # (start: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8) [//]: # (warning: Generated automatically. Do not edit.) # Contributing This package is the part of Awesome Set of Packages for Laravel. Please use the [main repository](https://github.com/LastDragon-ru/lara-asp) to [report issues](https://github.com/LastDragon-ru/lara-asp/issues), send [pull requests](https://github.com/LastDragon-ru/lara-asp/pulls), or [ask questions](https://github.com/LastDragon-ru/lara-asp/discussions). -[//]: # (end: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89) +[//]: # (end: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8) diff --git a/packages/spa/UPGRADE.md b/packages/spa/UPGRADE.md index 52e5ca98a..4db3e25b6 100644 --- a/packages/spa/UPGRADE.md +++ b/packages/spa/UPGRADE.md @@ -1,7 +1,7 @@ # Upgrade Guide [include:file]: ../../docs/Shared/Upgrade.md -[//]: # (start: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2) +[//]: # (start: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d) [//]: # (warning: Generated automatically. Do not edit.) ## Instructions @@ -25,24 +25,24 @@ Please also see [changelog](https://github.com/LastDragon-ru/lara-asp/releases) | 🤝 | Backward-compatible change. Please note that despite you can ignore it now, but it will be mandatory in the future. | |:--:|:--------------------------------------------------------------------------------------------------------------------| -[//]: # (end: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2) +[//]: # (end: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d) # Upgrade from v6 [include:file]: ../../docs/Shared/Upgrade/FromV6.md -[//]: # (start: 6b55bf5daea407a4590344596d41efd8368a783e2666bfe431a88a5eeaff3a95) +[//]: # (start: 8dae6cc48a78a268dcc7b747e512f85b410c9a9392ffac0734f4b17d390f1883) [//]: # (warning: Generated automatically. Do not edit.) * [ ] Direct usages of `Container::getInstances()` were replaced by explicit constructor parameters. You may need to update your code accordingly (#151). -[//]: # (end: 6b55bf5daea407a4590344596d41efd8368a783e2666bfe431a88a5eeaff3a95) +[//]: # (end: 8dae6cc48a78a268dcc7b747e512f85b410c9a9392ffac0734f4b17d390f1883) # Upgrade from v5 [include:file]: ../../docs/Shared/Upgrade/FromV5.md -[//]: # (start: fd146cf51ef5a8d9d13e0317c09860f472c63cb3d60d02f4d95deb3e12cae73d) +[//]: # (start: 599c87007f162e34f4fd0c7874d4fcf8676e5d8c761d27a9456b284c7d1d12f2) [//]: # (warning: Generated automatically. Do not edit.) * [ ] Laravel v9 is not supported anymore. Migrate to the newer version. -[//]: # (end: fd146cf51ef5a8d9d13e0317c09860f472c63cb3d60d02f4d95deb3e12cae73d) +[//]: # (end: 599c87007f162e34f4fd0c7874d4fcf8676e5d8c761d27a9456b284c7d1d12f2) diff --git a/packages/testing/README.md b/packages/testing/README.md index 1f6175912..9529252b8 100644 --- a/packages/testing/README.md +++ b/packages/testing/README.md @@ -3,7 +3,7 @@ This package provides various useful asserts for [PHPUnit](https://phpunit.de/) and better solution for HTTP tests - testing HTTP response has never been so easy! And this not only about `TestResponse` but any PSR response 😎 [include:exec]: <../../dev/artisan lara-asp-documentator:requirements> -[//]: # (start: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b) +[//]: # (start: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea) [//]: # (warning: Generated automatically. Do not edit.) # Requirements @@ -27,7 +27,7 @@ This package provides various useful asserts for [PHPUnit](https://phpunit.de/) | PHPUnit | `^11.0.0` | `HEAD ⋯ 6.2.0` | | | `^10.1.0` | `HEAD ⋯ 6.0.0` | -[//]: # (end: 876a9177c0e8e3722ac84e8f3888245fc9070a64a87dedfe7c9d9ba2a13b374b) +[//]: # (end: 196f435a1c8bc8d5966e42b9fd090d5ccc17c75206e617d7f8369cd9328846ea) [include:template]: ../../docs/Shared/InstallationDev.md ({"data": {"package": "testing"}}) [//]: # (start: 9c57d43303e5ef82308c0c83e328e2a47be808a50cd12d6fc5bcfd9229e2fa7c) @@ -54,7 +54,7 @@ composer require --dev lastdragon-ru/lara-asp-testing In the general case, you just need to update `tests/TestCase.php` to include most important things, but you also can include only desired features, please see related traits and extensions below. [include:example]: ./docs/Examples/TestCase.php -[//]: # (start: d64050243e2262fdd649a43b4d5b7f9784ba701372776c15d760357c38e581e1) +[//]: # (start: e4763d33cca5eca34565862b6815638a0c60d817f1a34476f47915afd0ad952e) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -80,7 +80,7 @@ abstract class TestCase extends BaseTestCase { } ``` -[//]: # (end: d64050243e2262fdd649a43b4d5b7f9784ba701372776c15d760357c38e581e1) +[//]: # (end: e4763d33cca5eca34565862b6815638a0c60d817f1a34476f47915afd0ad952e) # Comparators @@ -835,7 +835,7 @@ Limitations/Notes: [//]: # (end: 998fe7ccccc11e3c54b93f9d6ea507c288be425a1dc4eca1cf5abe09d77c572e) [include:example]: ./docs/Examples/MockProperties.php -[//]: # (start: 412cdd988d467ebb6083e17127a01aae689692590c8bf6273d2f3073cbf068cd) +[//]: # (start: bbc1e289c2ec3a43c467e48c9785aea2ba6bbff92b4c966f1ac934c1b1b6c9d1) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -877,7 +877,7 @@ $mock $mock->a(); ``` -[//]: # (end: 412cdd988d467ebb6083e17127a01aae689692590c8bf6273d2f3073cbf068cd) +[//]: # (end: bbc1e289c2ec3a43c467e48c9785aea2ba6bbff92b4c966f1ac934c1b1b6c9d1) # Custom Test Requirements @@ -913,21 +913,21 @@ class SomePackageTest extends TestCase { ``` [include:file]: ../../docs/Shared/Upgrading.md -[//]: # (start: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b) +[//]: # (start: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a) [//]: # (warning: Generated automatically. Do not edit.) # Upgrading Please follow [Upgrade Guide](UPGRADE.md). -[//]: # (end: e9139abedb89f69284102c9112b548fd7add07cf196259916ea4f1c98977223b) +[//]: # (end: 3c3826915e1d570b3982fdc6acf484950f0add7bb09d71c8c99b4a0e0fc5b43a) [include:file]: ../../docs/Shared/Contributing.md -[//]: # (start: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89) +[//]: # (start: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8) [//]: # (warning: Generated automatically. Do not edit.) # Contributing This package is the part of Awesome Set of Packages for Laravel. Please use the [main repository](https://github.com/LastDragon-ru/lara-asp) to [report issues](https://github.com/LastDragon-ru/lara-asp/issues), send [pull requests](https://github.com/LastDragon-ru/lara-asp/pulls), or [ask questions](https://github.com/LastDragon-ru/lara-asp/discussions). -[//]: # (end: 057ec3a599c54447e95d6dd2e9f0f6a6621d9eb75446a5e5e471ba9b2f414b89) +[//]: # (end: 6b81b030ae74b2d149ec76cbec1b053da8da4e0ac4fd865f560548f3ead955e8) diff --git a/packages/testing/UPGRADE.md b/packages/testing/UPGRADE.md index 3d44e7634..d289b8958 100644 --- a/packages/testing/UPGRADE.md +++ b/packages/testing/UPGRADE.md @@ -1,7 +1,7 @@ # Upgrade Guide [include:file]: ../../docs/Shared/Upgrade.md -[//]: # (start: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2) +[//]: # (start: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d) [//]: # (warning: Generated automatically. Do not edit.) ## Instructions @@ -25,17 +25,17 @@ Please also see [changelog](https://github.com/LastDragon-ru/lara-asp/releases) | 🤝 | Backward-compatible change. Please note that despite you can ignore it now, but it will be mandatory in the future. | |:--:|:--------------------------------------------------------------------------------------------------------------------| -[//]: # (end: c70a9a43c0a80bd2e7fa6010a9b2c0fbcab4cb4d536d7a498216d9df7431f7e2) +[//]: # (end: 5af9759519da3fa710fb21785e61682fda687a6ebdfb6f0dde4ed03162cb031d) # Upgrade from v6 [include:file]: ../../docs/Shared/Upgrade/FromV6.md -[//]: # (start: 6b55bf5daea407a4590344596d41efd8368a783e2666bfe431a88a5eeaff3a95) +[//]: # (start: 8dae6cc48a78a268dcc7b747e512f85b410c9a9392ffac0734f4b17d390f1883) [//]: # (warning: Generated automatically. Do not edit.) * [ ] Direct usages of `Container::getInstances()` were replaced by explicit constructor parameters. You may need to update your code accordingly (#151). -[//]: # (end: 6b55bf5daea407a4590344596d41efd8368a783e2666bfe431a88a5eeaff3a95) +[//]: # (end: 8dae6cc48a78a268dcc7b747e512f85b410c9a9392ffac0734f4b17d390f1883) * [ ] Following traits required `app()` method to get access to the Container (#151) * `\LastDragon_ru\LaraASP\Testing\Assertions\Application\ScheduleAssertions` @@ -55,11 +55,11 @@ Please also see [changelog](https://github.com/LastDragon-ru/lara-asp/releases) # Upgrade from v5 [include:file]: ../../docs/Shared/Upgrade/FromV5.md -[//]: # (start: fd146cf51ef5a8d9d13e0317c09860f472c63cb3d60d02f4d95deb3e12cae73d) +[//]: # (start: 599c87007f162e34f4fd0c7874d4fcf8676e5d8c761d27a9456b284c7d1d12f2) [//]: # (warning: Generated automatically. Do not edit.) * [ ] Laravel v9 is not supported anymore. Migrate to the newer version. -[//]: # (end: fd146cf51ef5a8d9d13e0317c09860f472c63cb3d60d02f4d95deb3e12cae73d) +[//]: # (end: 599c87007f162e34f4fd0c7874d4fcf8676e5d8c761d27a9456b284c7d1d12f2) * [ ] Replace `CronableAssertions::assertCronableRegistered()` to `ScheduleAssertions::assertScheduled()`. diff --git a/packages/testing/docs/Assertions/AssertDatabaseQueryEquals.md b/packages/testing/docs/Assertions/AssertDatabaseQueryEquals.md index b7fee9873..c9220d510 100644 --- a/packages/testing/docs/Assertions/AssertDatabaseQueryEquals.md +++ b/packages/testing/docs/Assertions/AssertDatabaseQueryEquals.md @@ -3,7 +3,7 @@ Asserts that SQL Query equals SQL Query. [include:example]: ./AssertDatabaseQueryEqualsTest.php -[//]: # (start: 9693a703a5c0c92fcdfb0d85ff2776ced3b270c7fb0712f7c4af1f6d50f00502) +[//]: # (start: 65d62248ad4d9d80f20c4988a5dfc7a946864fb5d63547ccee2b721b84c9b46f) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -57,4 +57,4 @@ final class AssertDatabaseQueryEqualsTest extends TestCase { } ``` -[//]: # (end: 9693a703a5c0c92fcdfb0d85ff2776ced3b270c7fb0712f7c4af1f6d50f00502) +[//]: # (end: 65d62248ad4d9d80f20c4988a5dfc7a946864fb5d63547ccee2b721b84c9b46f) diff --git a/packages/testing/docs/Assertions/AssertJsonMatchesSchema.md b/packages/testing/docs/Assertions/AssertJsonMatchesSchema.md index 8be383e31..bf9b55c28 100644 --- a/packages/testing/docs/Assertions/AssertJsonMatchesSchema.md +++ b/packages/testing/docs/Assertions/AssertJsonMatchesSchema.md @@ -3,7 +3,7 @@ Asserts that JSON matches [schema](https://json-schema.org/). Validation based on the [Opis JSON Schema](https://github.com/opis/json-schema) package. [include:example]: ./AssertJsonMatchesSchemaTest.php -[//]: # (start: 37b5139d86f40272bd033e33712c5a9f63453e328c23a5d03d1366c4ac0c4b90) +[//]: # (start: a6b4c98bfb1a397c027ee2360f01310c9319d9742b9361bab757e4c1b4d7caa3) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -61,4 +61,4 @@ final class AssertJsonMatchesSchemaTest extends TestCase { } ``` -[//]: # (end: 37b5139d86f40272bd033e33712c5a9f63453e328c23a5d03d1366c4ac0c4b90) +[//]: # (end: a6b4c98bfb1a397c027ee2360f01310c9319d9742b9361bab757e4c1b4d7caa3) diff --git a/packages/testing/docs/Assertions/AssertPsrResponse.md b/packages/testing/docs/Assertions/AssertPsrResponse.md index 6c82b852e..cff2721e1 100644 --- a/packages/testing/docs/Assertions/AssertPsrResponse.md +++ b/packages/testing/docs/Assertions/AssertPsrResponse.md @@ -3,7 +3,7 @@ Asserts that PSR Response satisfies given constraint (we have a lot of built-in [constraints](../../src/Constraints/Response) and [responses](../../src/Responses), but, of course, you can create a custom). [include:example]: ./AssertPsrResponseTest.php -[//]: # (start: 6deaa19d07c3e7b38c7a395e63719237f3d6ac13d2c044357eb3630b7625cea5) +[//]: # (start: d56396d7203ebdf44cbccb48d522ccf24fea7657aac3b2508e11e1850086dd37) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -97,4 +97,4 @@ final class AssertPsrResponseTest extends TestCase { } ``` -[//]: # (end: 6deaa19d07c3e7b38c7a395e63719237f3d6ac13d2c044357eb3630b7625cea5) +[//]: # (end: d56396d7203ebdf44cbccb48d522ccf24fea7657aac3b2508e11e1850086dd37) diff --git a/packages/testing/docs/Assertions/AssertQueryLogEquals.md b/packages/testing/docs/Assertions/AssertQueryLogEquals.md index cbb4620e6..9a4b91856 100644 --- a/packages/testing/docs/Assertions/AssertQueryLogEquals.md +++ b/packages/testing/docs/Assertions/AssertQueryLogEquals.md @@ -3,7 +3,7 @@ Asserts that `QueryLog` equals `QueryLog`. [include:example]: ./AssertQueryLogEqualsTest.php -[//]: # (start: 3ef530658feaa07626c932caaaa1e1815225f65d1c36369abd30c445d65f18af) +[//]: # (start: 709fad07f8fc6f28709758f6f33f1a1773cf0652c99028faa15f621efa619a93) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -74,4 +74,4 @@ final class AssertQueryLogEqualsTest extends TestCase { } ``` -[//]: # (end: 3ef530658feaa07626c932caaaa1e1815225f65d1c36369abd30c445d65f18af) +[//]: # (end: 709fad07f8fc6f28709758f6f33f1a1773cf0652c99028faa15f621efa619a93) diff --git a/packages/testing/docs/Assertions/AssertScheduled.md b/packages/testing/docs/Assertions/AssertScheduled.md index 3c6f6c466..92424c9d4 100644 --- a/packages/testing/docs/Assertions/AssertScheduled.md +++ b/packages/testing/docs/Assertions/AssertScheduled.md @@ -3,7 +3,7 @@ Asserts that Schedule contains task. [include:example]: ./AssertScheduledTest.php -[//]: # (start: 7b7d3362391a553d8728619185eafc2fe1f3dda4112eab18a7be8c53321dec70) +[//]: # (start: f506843658b5143b195bd01075e1807073a382bfbeb5f689afa2063fed136a69) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -58,4 +58,4 @@ final class AssertScheduledTest extends TestCase { } ``` -[//]: # (end: 7b7d3362391a553d8728619185eafc2fe1f3dda4112eab18a7be8c53321dec70) +[//]: # (end: f506843658b5143b195bd01075e1807073a382bfbeb5f689afa2063fed136a69) diff --git a/packages/testing/docs/Assertions/AssertScoutQueryEquals.md b/packages/testing/docs/Assertions/AssertScoutQueryEquals.md index c5687e6a9..a80e40e35 100644 --- a/packages/testing/docs/Assertions/AssertScoutQueryEquals.md +++ b/packages/testing/docs/Assertions/AssertScoutQueryEquals.md @@ -3,7 +3,7 @@ Asserts that Scout Query equals Scout Query. [include:example]: ./AssertScoutQueryEqualsTest.php -[//]: # (start: e96037f5fdf72df5c84fc1257d56c11de0b67d95b37524ee7cd7889a212f5053) +[//]: # (start: 5046607ec467c82fe8c461c1bb3f7ca5d3c8ea78b67a4cd01448cc96ac775551) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -56,4 +56,4 @@ final class AssertScoutQueryEqualsTest extends TestCase { } ``` -[//]: # (end: e96037f5fdf72df5c84fc1257d56c11de0b67d95b37524ee7cd7889a212f5053) +[//]: # (end: 5046607ec467c82fe8c461c1bb3f7ca5d3c8ea78b67a4cd01448cc96ac775551) diff --git a/packages/testing/docs/Assertions/AssertThatResponse.md b/packages/testing/docs/Assertions/AssertThatResponse.md index 6eefd9282..05b8ff1c2 100644 --- a/packages/testing/docs/Assertions/AssertThatResponse.md +++ b/packages/testing/docs/Assertions/AssertThatResponse.md @@ -7,7 +7,7 @@ Asserts that PSR Response satisfies given constraint (we have a lot of built-in > Assertion is deprecated, please use [`assertPsrResponse()`](./AssertPsrResponse.md) instead. [include:example]: ./AssertThatResponseTest.php -[//]: # (start: fef995e7dea4e96b1398204ed11e6026d59490486273866194ec75545254c806) +[//]: # (start: 132bbbc2e0a7ab0e29a2a98ce604860cb8685539926640afeae680ebc8e2c2f3) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -101,4 +101,4 @@ final class AssertThatResponseTest extends TestCase { } ``` -[//]: # (end: fef995e7dea4e96b1398204ed11e6026d59490486273866194ec75545254c806) +[//]: # (end: 132bbbc2e0a7ab0e29a2a98ce604860cb8685539926640afeae680ebc8e2c2f3) diff --git a/packages/testing/docs/Assertions/AssertXmlMatchesSchema.md b/packages/testing/docs/Assertions/AssertXmlMatchesSchema.md index 49bb54195..9ea391646 100644 --- a/packages/testing/docs/Assertions/AssertXmlMatchesSchema.md +++ b/packages/testing/docs/Assertions/AssertXmlMatchesSchema.md @@ -3,7 +3,7 @@ Asserts that XML matches schema [XSD](https://en.wikipedia.org/wiki/XML_Schema_(W3C)) or [Relax NG](https://en.wikipedia.org/wiki/RELAX_NG). Validation based on the standard methods of [`DOMDocument`](https://www.php.net/manual/en/class.domdocument.php) class. [include:example]: ./AssertXmlMatchesSchemaTest.php -[//]: # (start: 6b932963255cda2827631e81e89adbae79060e3c45d352647af85b19201928b0) +[//]: # (start: 85e7c95b662fc2552c7a3083d2b6415feedc20e27ab7e3cc11232f1f3de52c1a) [//]: # (warning: Generated automatically. Do not edit.) ```php @@ -65,4 +65,4 @@ final class AssertXmlMatchesSchemaTest extends TestCase { } ``` -[//]: # (end: 6b932963255cda2827631e81e89adbae79060e3c45d352647af85b19201928b0) +[//]: # (end: 85e7c95b662fc2552c7a3083d2b6415feedc20e27ab7e3cc11232f1f3de52c1a) From 1fc1557bff38aca9961ea201afa837ced0aa6305 Mon Sep 17 00:00:00 2001 From: Aleksei Lebedev <1329824+LastDragon-ru@users.noreply.github.com> Date: Sat, 18 May 2024 09:21:52 +0400 Subject: [PATCH 11/14] Upgrade note. --- packages/documentator/UPGRADE.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/documentator/UPGRADE.md b/packages/documentator/UPGRADE.md index 91ab03c9c..d3069bd60 100644 --- a/packages/documentator/UPGRADE.md +++ b/packages/documentator/UPGRADE.md @@ -37,6 +37,8 @@ Please also see [changelog](https://github.com/LastDragon-ru/lara-asp/releases) [//]: # (end: 8dae6cc48a78a268dcc7b747e512f85b410c9a9392ffac0734f4b17d390f1883) +* [ ] Migrate to the new contract `\LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\Instruction`. + # Upgrade from v5 [include:file]: ../../docs/Shared/Upgrade/FromV5.md From 5995294520576b26617bab47ef3cc3a9027b5d09 Mon Sep 17 00:00:00 2001 From: Aleksei Lebedev <1329824+LastDragon-ru@users.noreply.github.com> Date: Sat, 18 May 2024 09:58:13 +0400 Subject: [PATCH 12/14] Exceptions will use `Context`. --- .../Exceptions/DependencyIsMissing.php | 9 ++++----- .../Exceptions/DocumentTitleIsMissing.php | 9 ++++----- .../Exceptions/InstructionFailed.php | 12 ++++-------- .../PackageComposerJsonIsMissing.php | 9 ++++----- .../Exceptions/PackageReadmeIsMissing.php | 9 ++++----- .../Exceptions/TargetExecFailed.php | 10 +++++----- .../Exceptions/TargetIsNotDirective.php | 10 +++++----- .../Exceptions/TargetIsNotDirectory.php | 10 +++++----- .../Exceptions/TargetIsNotFile.php | 10 +++++----- .../Exceptions/TargetIsNotValidPhpFile.php | 10 +++++----- .../Exceptions/TemplateDataMissed.php | 12 ++++-------- .../Exceptions/TemplateVariablesMissed.php | 9 ++++----- .../Exceptions/TemplateVariablesUnused.php | 9 ++++----- .../IncludeDocBlock/Instruction.php | 2 +- .../IncludeDocBlock/InstructionTest.php | 7 +++++-- .../IncludeDocumentList/Instruction.php | 2 +- .../IncludeDocumentList/InstructionTest.php | 7 +++++-- .../IncludeExample/Instruction.php | 2 +- .../Instructions/IncludeExec/Instruction.php | 2 +- .../IncludeGraphqlDirective/Instruction.php | 4 ++-- .../InstructionTest.php | 6 +++--- .../IncludePackageList/Instruction.php | 8 +++----- .../IncludePackageList/InstructionTest.php | 18 +++--------------- .../IncludeTemplate/Instruction.php | 6 +++--- .../IncludeTemplate/InstructionTest.php | 14 +++----------- .../src/Preprocessor/Targets/DirectoryPath.php | 2 +- .../src/Preprocessor/Targets/FileContent.php | 2 +- .../src/Preprocessor/Targets/FilePath.php | 2 +- 28 files changed, 91 insertions(+), 121 deletions(-) diff --git a/packages/documentator/src/Preprocessor/Exceptions/DependencyIsMissing.php b/packages/documentator/src/Preprocessor/Exceptions/DependencyIsMissing.php index 7bf207793..54182ede0 100644 --- a/packages/documentator/src/Preprocessor/Exceptions/DependencyIsMissing.php +++ b/packages/documentator/src/Preprocessor/Exceptions/DependencyIsMissing.php @@ -2,6 +2,7 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; use Throwable; use function sprintf; @@ -11,18 +12,16 @@ class DependencyIsMissing extends InstructionFailed { * @param class-string $class */ public function __construct( - string $path, - string $target, + Context $context, private readonly string $class, Throwable $previous = null, ) { parent::__construct( - $path, - $target, + $context, sprintf( 'The dependency `%s` is missed (in `%s`).', $this->class, - $path, + $context->path, ), $previous, ); diff --git a/packages/documentator/src/Preprocessor/Exceptions/DocumentTitleIsMissing.php b/packages/documentator/src/Preprocessor/Exceptions/DocumentTitleIsMissing.php index 2ac043cde..b114141ac 100644 --- a/packages/documentator/src/Preprocessor/Exceptions/DocumentTitleIsMissing.php +++ b/packages/documentator/src/Preprocessor/Exceptions/DocumentTitleIsMissing.php @@ -2,24 +2,23 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; use Throwable; use function sprintf; class DocumentTitleIsMissing extends InstructionFailed { public function __construct( - string $path, - string $target, + Context $context, private readonly string $document, Throwable $previous = null, ) { parent::__construct( - $path, - $target, + $context, sprintf( "The `%s` doesn't contain `# Header` (in `%s`).", $this->document, - $path, + $context->path, ), $previous, ); diff --git a/packages/documentator/src/Preprocessor/Exceptions/InstructionFailed.php b/packages/documentator/src/Preprocessor/Exceptions/InstructionFailed.php index 08d12da20..e980f3c39 100644 --- a/packages/documentator/src/Preprocessor/Exceptions/InstructionFailed.php +++ b/packages/documentator/src/Preprocessor/Exceptions/InstructionFailed.php @@ -2,23 +2,19 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; use Throwable; abstract class InstructionFailed extends PreprocessFailed { public function __construct( - private readonly string $path, - private readonly string $target, + private readonly Context $context, string $message, Throwable $previous = null, ) { parent::__construct($message, $previous); } - public function getPath(): string { - return $this->path; - } - - public function getTarget(): string { - return $this->target; + public function getContext(): Context { + return $this->context; } } diff --git a/packages/documentator/src/Preprocessor/Exceptions/PackageComposerJsonIsMissing.php b/packages/documentator/src/Preprocessor/Exceptions/PackageComposerJsonIsMissing.php index 1f839d3fb..ae0e9319c 100644 --- a/packages/documentator/src/Preprocessor/Exceptions/PackageComposerJsonIsMissing.php +++ b/packages/documentator/src/Preprocessor/Exceptions/PackageComposerJsonIsMissing.php @@ -2,24 +2,23 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; use Throwable; use function sprintf; class PackageComposerJsonIsMissing extends InstructionFailed { public function __construct( - string $path, - string $target, + Context $context, private readonly string $package, Throwable $previous = null, ) { parent::__construct( - $path, - $target, + $context, sprintf( "The package `%s` doesn't contain `composer.json` (in `%s`).", $this->package, - $path, + $context->path, ), $previous, ); diff --git a/packages/documentator/src/Preprocessor/Exceptions/PackageReadmeIsMissing.php b/packages/documentator/src/Preprocessor/Exceptions/PackageReadmeIsMissing.php index 9ef99f9d6..83fdcef2a 100644 --- a/packages/documentator/src/Preprocessor/Exceptions/PackageReadmeIsMissing.php +++ b/packages/documentator/src/Preprocessor/Exceptions/PackageReadmeIsMissing.php @@ -2,24 +2,23 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; use Throwable; use function sprintf; class PackageReadmeIsMissing extends InstructionFailed { public function __construct( - string $path, - string $target, + Context $context, private readonly string $package, Throwable $previous = null, ) { parent::__construct( - $path, - $target, + $context, sprintf( "The package `%s` doesn't contain readme (in `%s`).", $this->package, - $path, + $context->path, ), $previous, ); diff --git a/packages/documentator/src/Preprocessor/Exceptions/TargetExecFailed.php b/packages/documentator/src/Preprocessor/Exceptions/TargetExecFailed.php index 84d25ae93..77938ceb0 100644 --- a/packages/documentator/src/Preprocessor/Exceptions/TargetExecFailed.php +++ b/packages/documentator/src/Preprocessor/Exceptions/TargetExecFailed.php @@ -2,19 +2,19 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; use Throwable; use function sprintf; class TargetExecFailed extends InstructionFailed { - public function __construct(string $path, string $target, Throwable $previous = null) { + public function __construct(Context $context, Throwable $previous = null) { parent::__construct( - $path, - $target, + $context, sprintf( 'Failed to execute the `%s` command (in `%s`).', - $target, - $path, + $context->target, + $context->path, ), $previous, ); diff --git a/packages/documentator/src/Preprocessor/Exceptions/TargetIsNotDirective.php b/packages/documentator/src/Preprocessor/Exceptions/TargetIsNotDirective.php index abd7f3d2a..f36a0e53e 100644 --- a/packages/documentator/src/Preprocessor/Exceptions/TargetIsNotDirective.php +++ b/packages/documentator/src/Preprocessor/Exceptions/TargetIsNotDirective.php @@ -2,19 +2,19 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; use Throwable; use function sprintf; class TargetIsNotDirective extends InstructionFailed { - public function __construct(string $path, string $target, Throwable $previous = null) { + public function __construct(Context $context, Throwable $previous = null) { parent::__construct( - $path, - $target, + $context, sprintf( 'The `%s` is not a directive (in `%s`).', - $target, - $path, + $context->target, + $context->path, ), $previous, ); diff --git a/packages/documentator/src/Preprocessor/Exceptions/TargetIsNotDirectory.php b/packages/documentator/src/Preprocessor/Exceptions/TargetIsNotDirectory.php index 0fb0270a7..fb39be30d 100644 --- a/packages/documentator/src/Preprocessor/Exceptions/TargetIsNotDirectory.php +++ b/packages/documentator/src/Preprocessor/Exceptions/TargetIsNotDirectory.php @@ -2,19 +2,19 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; use Throwable; use function sprintf; class TargetIsNotDirectory extends InstructionFailed { - public function __construct(string $path, string $target, Throwable $previous = null) { + public function __construct(Context $context, Throwable $previous = null) { parent::__construct( - $path, - $target, + $context, sprintf( 'The `%s` is not a directory (in `%s`).', - $target, - $path, + $context->target, + $context->path, ), $previous, ); diff --git a/packages/documentator/src/Preprocessor/Exceptions/TargetIsNotFile.php b/packages/documentator/src/Preprocessor/Exceptions/TargetIsNotFile.php index 98105f6f9..e279c0ba1 100644 --- a/packages/documentator/src/Preprocessor/Exceptions/TargetIsNotFile.php +++ b/packages/documentator/src/Preprocessor/Exceptions/TargetIsNotFile.php @@ -2,19 +2,19 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; use Throwable; use function sprintf; class TargetIsNotFile extends InstructionFailed { - public function __construct(string $path, string $target, Throwable $previous = null) { + public function __construct(Context $context, Throwable $previous = null) { parent::__construct( - $path, - $target, + $context, sprintf( 'The `%s` is not a file (in `%s`).', - $target, - $path, + $context->target, + $context->path, ), $previous, ); diff --git a/packages/documentator/src/Preprocessor/Exceptions/TargetIsNotValidPhpFile.php b/packages/documentator/src/Preprocessor/Exceptions/TargetIsNotValidPhpFile.php index 6c0b7336b..43e807ea5 100644 --- a/packages/documentator/src/Preprocessor/Exceptions/TargetIsNotValidPhpFile.php +++ b/packages/documentator/src/Preprocessor/Exceptions/TargetIsNotValidPhpFile.php @@ -2,19 +2,19 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; use Throwable; use function sprintf; class TargetIsNotValidPhpFile extends InstructionFailed { - public function __construct(string $path, string $target, Throwable $previous = null) { + public function __construct(Context $context, Throwable $previous = null) { parent::__construct( - $path, - $target, + $context, sprintf( 'The `%s` is not a valid PHP file (in `%s`).', - $target, - $path, + $context->target, + $context->path, ), $previous, ); diff --git a/packages/documentator/src/Preprocessor/Exceptions/TemplateDataMissed.php b/packages/documentator/src/Preprocessor/Exceptions/TemplateDataMissed.php index 97c412cb7..332f58b9f 100644 --- a/packages/documentator/src/Preprocessor/Exceptions/TemplateDataMissed.php +++ b/packages/documentator/src/Preprocessor/Exceptions/TemplateDataMissed.php @@ -2,22 +2,18 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; use Throwable; use function sprintf; class TemplateDataMissed extends InstructionFailed { - public function __construct( - string $path, - string $target, - Throwable $previous = null, - ) { + public function __construct(Context $context, Throwable $previous = null) { parent::__construct( - $path, - $target, + $context, sprintf( 'The `data` is required for `%s`.', - $path, + $context->path, ), $previous, ); diff --git a/packages/documentator/src/Preprocessor/Exceptions/TemplateVariablesMissed.php b/packages/documentator/src/Preprocessor/Exceptions/TemplateVariablesMissed.php index 718e0b271..319c79df3 100644 --- a/packages/documentator/src/Preprocessor/Exceptions/TemplateVariablesMissed.php +++ b/packages/documentator/src/Preprocessor/Exceptions/TemplateVariablesMissed.php @@ -2,6 +2,7 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; use Throwable; use function implode; @@ -12,18 +13,16 @@ class TemplateVariablesMissed extends InstructionFailed { * @param non-empty-list $variables */ public function __construct( - string $path, - string $target, + Context $context, private readonly array $variables, Throwable $previous = null, ) { parent::__construct( - $path, - $target, + $context, sprintf( 'Variables `%s` required in `%s`, but missed.', '`'.implode('`, `', $this->variables).'`', - $path, + $context->path, ), $previous, ); diff --git a/packages/documentator/src/Preprocessor/Exceptions/TemplateVariablesUnused.php b/packages/documentator/src/Preprocessor/Exceptions/TemplateVariablesUnused.php index 35fb35aef..b816b8b09 100644 --- a/packages/documentator/src/Preprocessor/Exceptions/TemplateVariablesUnused.php +++ b/packages/documentator/src/Preprocessor/Exceptions/TemplateVariablesUnused.php @@ -2,6 +2,7 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions; +use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; use Throwable; use function implode; @@ -12,18 +13,16 @@ class TemplateVariablesUnused extends InstructionFailed { * @param non-empty-list $variables */ public function __construct( - string $path, - string $target, + Context $context, private readonly array $variables, Throwable $previous = null, ) { parent::__construct( - $path, - $target, + $context, sprintf( 'Variables `%s` are not used in `%s`.', '`'.implode('`, `', $this->variables).'`', - $path, + $context->path, ), $previous, ); diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeDocBlock/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeDocBlock/Instruction.php index c9082fe44..590298259 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeDocBlock/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeDocBlock/Instruction.php @@ -95,7 +95,7 @@ private function getClass(Context $context, string $content): ?array { return $node instanceof ClassLike; }); } catch (Exception $exception) { - throw new TargetIsNotValidPhpFile($context->path, $context->target, $exception); + throw new TargetIsNotValidPhpFile($context, $exception); } return $class instanceof ClassLike diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeDocBlock/InstructionTest.php b/packages/documentator/src/Preprocessor/Instructions/IncludeDocBlock/InstructionTest.php index b286de2d4..5db24d251 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeDocBlock/InstructionTest.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeDocBlock/InstructionTest.php @@ -65,8 +65,11 @@ public static function dataProviderProcess(): array { ], 'invalid' => [ new TargetIsNotValidPhpFile( - str_replace('\\', '/', __DIR__.'/InstructionTest/Invalid.txt'), - 'Invalid.txt', + new Context( + str_replace('\\', '/', __DIR__.'/InstructionTest/Invalid.txt'), + 'Invalid.txt', + null, + ), ), 'Invalid.txt', new Parameters(), diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/Instruction.php index 45fc3a285..48402c0d1 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/Instruction.php @@ -85,7 +85,7 @@ public function process(Context $context, mixed $target, mixed $parameters): str 'summary' => Markdown::getSummary($content), ]; } else { - throw new DocumentTitleIsMissing($context->path, $context->target, $docPath); + throw new DocumentTitleIsMissing($context, $docPath); } } diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/InstructionTest.php b/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/InstructionTest.php index 9045f3f1a..f10fc64bd 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/InstructionTest.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeDocumentList/InstructionTest.php @@ -78,8 +78,11 @@ public function testProcessWithoutTitle(): void { self::expectExceptionObject( new DocumentTitleIsMissing( - $path->getPathname(), - $target, + new Context( + $path->getPathname(), + $target, + null, + ), 'WithoutTitle.md', ), ); diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeExample/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeExample/Instruction.php index 0a607851c..32724271d 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeExample/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeExample/Instruction.php @@ -81,7 +81,7 @@ public function process(Context $context, mixed $target, mixed $parameters): str $output = $this->factory->newPendingProcess()->path(dirname($path))->run($command)->throw()->output(); $output = trim($output); } catch (Exception $exception) { - throw new TargetExecFailed($path, $target, $exception); + throw new TargetExecFailed($context, $exception); } // Markdown? diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeExec/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeExec/Instruction.php index e6c98cce3..72b623b72 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeExec/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeExec/Instruction.php @@ -46,7 +46,7 @@ public function process(Context $context, mixed $target, mixed $parameters): str $this->factory->newPendingProcess()->path(dirname($context->path))->run($target)->throw()->output(), ); } catch (Exception $exception) { - throw new TargetExecFailed($context->path, $context->target, $exception); + throw new TargetExecFailed($context, $exception); } } } diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Instruction.php index 867fc2aad..761eef3bc 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Instruction.php @@ -44,7 +44,7 @@ public static function getParameters(): ?string { public function process(Context $context, mixed $target, mixed $parameters): string { // Dependencies? if (!$this->printer) { - throw new DependencyIsMissing($context->path, $context->target, Printer::class); + throw new DependencyIsMissing($context, Printer::class); } // Directive? @@ -52,7 +52,7 @@ public function process(Context $context, mixed $target, mixed $parameters): str $definition = $this->printer->getDirectiveResolver()?->getDefinition($directive); if ($definition === null) { - throw new TargetIsNotDirective($context->path, $context->target); + throw new TargetIsNotDirective($context); } // Print diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/InstructionTest.php b/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/InstructionTest.php index 71ef4d359..994c17895 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/InstructionTest.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/InstructionTest.php @@ -64,7 +64,7 @@ public function testProcessNoPrinter(): void { $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( - new DependencyIsMissing($path, $target, PrinterContract::class), + new DependencyIsMissing($context, PrinterContract::class), ); $instance->process($context, $context->target, null); @@ -90,7 +90,7 @@ public function testProcessNoDirective(): void { $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( - new TargetIsNotDirective($path, $target), + new TargetIsNotDirective($context), ); $instance->process($context, $context->target, null); @@ -107,7 +107,7 @@ public function testProcessNoDirectiveResolver(): void { $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( - new TargetIsNotDirective($path, $target), + new TargetIsNotDirective($context), ); $instance->process($context, $context->target, null); diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/Instruction.php index 28ab4c261..4dd29e4b0 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/Instruction.php @@ -75,8 +75,7 @@ public function process(Context $context, mixed $target, mixed $parameters): str if (!$packageInfo) { throw new PackageComposerJsonIsMissing( - $context->path, - $context->target, + $context, Path::join($basePath, $package->getFilename()), ); } @@ -89,8 +88,7 @@ public function process(Context $context, mixed $target, mixed $parameters): str if (!$readme || $content === false) { throw new PackageReadmeIsMissing( - $context->path, - $context->target, + $context, Path::join($basePath, $package->getFilename()), ); } @@ -112,7 +110,7 @@ public function process(Context $context, mixed $target, mixed $parameters): str 'upgrade' => $upgradePath, ]; } else { - throw new DocumentTitleIsMissing($context->path, $context->target, $readmePath); + throw new DocumentTitleIsMissing($context, $readmePath); } } diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/InstructionTest.php b/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/InstructionTest.php index 40bd446e7..f75bc4cf2 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/InstructionTest.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludePackageList/InstructionTest.php @@ -49,11 +49,7 @@ public function testProcessNotAPackage(): void { $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( - new PackageComposerJsonIsMissing( - $path, - $target, - 'invalid/package', - ), + new PackageComposerJsonIsMissing($context, 'invalid/package'), ); $instance->process($context, $resolved, $params); @@ -68,11 +64,7 @@ public function testProcessNoReadme(): void { $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( - new PackageReadmeIsMissing( - $path, - $target, - 'no readme/package', - ), + new PackageReadmeIsMissing($context, 'no readme/package'), ); $instance->process($context, $resolved, $params); @@ -87,11 +79,7 @@ public function testProcessNoTitle(): void { $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( - new DocumentTitleIsMissing( - $path, - $target, - 'no title/package/README.md', - ), + new DocumentTitleIsMissing($context, 'no title/package/README.md'), ); $instance->process($context, $resolved, $params); diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeTemplate/Instruction.php b/packages/documentator/src/Preprocessor/Instructions/IncludeTemplate/Instruction.php index b80d349cd..f53960493 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeTemplate/Instruction.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeTemplate/Instruction.php @@ -48,7 +48,7 @@ public static function getParameters(): ?string { public function process(Context $context, mixed $target, mixed $parameters): string { // Data? if (!$parameters->data) { - throw new TemplateDataMissed($context->path, $context->target); + throw new TemplateDataMissed($context); } // Replace @@ -83,14 +83,14 @@ public function process(Context $context, mixed $target, mixed $parameters): str $unused = array_diff($vars, $used); if ($unused) { - throw new TemplateVariablesUnused($context->path, $context->target, array_values($unused)); + throw new TemplateVariablesUnused($context, array_values($unused)); } // Missed $missed = array_diff($known, $used); if ($missed) { - throw new TemplateVariablesMissed($context->path, $context->target, array_values($missed)); + throw new TemplateVariablesMissed($context, array_values($missed)); } // Return diff --git a/packages/documentator/src/Preprocessor/Instructions/IncludeTemplate/InstructionTest.php b/packages/documentator/src/Preprocessor/Instructions/IncludeTemplate/InstructionTest.php index 977a9fb79..f8b06109a 100644 --- a/packages/documentator/src/Preprocessor/Instructions/IncludeTemplate/InstructionTest.php +++ b/packages/documentator/src/Preprocessor/Instructions/IncludeTemplate/InstructionTest.php @@ -43,7 +43,7 @@ public function testProcessNoData(): void { $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( - new TemplateDataMissed($file, $file), + new TemplateDataMissed($context), ); $instance->process($context, $content, $params); @@ -62,11 +62,7 @@ public function testProcessVariablesUnused(): void { $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( - new TemplateVariablesUnused( - $file->getPathname(), - $file->getFilename(), - ['c', 'd'], - ), + new TemplateVariablesUnused($context, ['c', 'd']), ); $instance->process($context, $content, $params); @@ -82,11 +78,7 @@ public function testProcessVariablesMissed(): void { $instance = $this->app()->make(Instruction::class); self::expectExceptionObject( - new TemplateVariablesMissed( - $file->getPathname(), - $file->getFilename(), - ['b'], - ), + new TemplateVariablesMissed($context, ['b']), ); $instance->process($context, $content, $params); diff --git a/packages/documentator/src/Preprocessor/Targets/DirectoryPath.php b/packages/documentator/src/Preprocessor/Targets/DirectoryPath.php index 0eca494e1..2b5a2d391 100644 --- a/packages/documentator/src/Preprocessor/Targets/DirectoryPath.php +++ b/packages/documentator/src/Preprocessor/Targets/DirectoryPath.php @@ -26,7 +26,7 @@ public function resolve(Context $context, mixed $parameters): string { $path = Path::getPath(dirname($context->path), $context->target); if (!is_dir($path)) { - throw new TargetIsNotDirectory($context->path, $context->target); + throw new TargetIsNotDirectory($context); } return $path; diff --git a/packages/documentator/src/Preprocessor/Targets/FileContent.php b/packages/documentator/src/Preprocessor/Targets/FileContent.php index bef9c06c8..9967ca068 100644 --- a/packages/documentator/src/Preprocessor/Targets/FileContent.php +++ b/packages/documentator/src/Preprocessor/Targets/FileContent.php @@ -18,7 +18,7 @@ public function resolve(Context $context, mixed $parameters): string { $content = file_get_contents($path); if ($content === false) { - throw new TargetIsNotFile($context->path, $context->target); + throw new TargetIsNotFile($context); } return $content; diff --git a/packages/documentator/src/Preprocessor/Targets/FilePath.php b/packages/documentator/src/Preprocessor/Targets/FilePath.php index bde50e92f..068e5748f 100644 --- a/packages/documentator/src/Preprocessor/Targets/FilePath.php +++ b/packages/documentator/src/Preprocessor/Targets/FilePath.php @@ -27,7 +27,7 @@ public function resolve(Context $context, mixed $parameters): string { $path = Path::getPath(dirname($context->path), $context->target); if (!is_file($path) || !is_readable($path)) { - throw new TargetIsNotFile($context->path, $context->target); + throw new TargetIsNotFile($context); } return $path; From dd9eefb9adca1b5840bfb18e01582c5480ffd35e Mon Sep 17 00:00:00 2001 From: Aleksei Lebedev <1329824+LastDragon-ru@users.noreply.github.com> Date: Sat, 18 May 2024 10:07:53 +0400 Subject: [PATCH 13/14] A bit better exceptions hierarchy. --- .../Exceptions/InstructionFailed.php | 2 +- .../Exceptions/PreprocessingFailed.php | 17 +++++++++++++++++ ...eprocessFailed.php => PreprocessorError.php} | 2 +- .../src/Preprocessor/Preprocessor.php | 9 +++++---- 4 files changed, 24 insertions(+), 6 deletions(-) create mode 100644 packages/documentator/src/Preprocessor/Exceptions/PreprocessingFailed.php rename packages/documentator/src/Preprocessor/Exceptions/{PreprocessFailed.php => PreprocessorError.php} (74%) diff --git a/packages/documentator/src/Preprocessor/Exceptions/InstructionFailed.php b/packages/documentator/src/Preprocessor/Exceptions/InstructionFailed.php index e980f3c39..edddfb0e8 100644 --- a/packages/documentator/src/Preprocessor/Exceptions/InstructionFailed.php +++ b/packages/documentator/src/Preprocessor/Exceptions/InstructionFailed.php @@ -5,7 +5,7 @@ use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; use Throwable; -abstract class InstructionFailed extends PreprocessFailed { +abstract class InstructionFailed extends PreprocessorError { public function __construct( private readonly Context $context, string $message, diff --git a/packages/documentator/src/Preprocessor/Exceptions/PreprocessingFailed.php b/packages/documentator/src/Preprocessor/Exceptions/PreprocessingFailed.php new file mode 100644 index 000000000..13b6922c2 --- /dev/null +++ b/packages/documentator/src/Preprocessor/Exceptions/PreprocessingFailed.php @@ -0,0 +1,17 @@ + Date: Sat, 18 May 2024 10:55:54 +0400 Subject: [PATCH 14/14] Tests fixes (win). --- .../src/Preprocessor/Targets/DirectoryPathTest.php | 13 ++++++++++--- .../src/Preprocessor/Targets/FilePathTest.php | 13 ++++++++++--- 2 files changed, 20 insertions(+), 6 deletions(-) diff --git a/packages/documentator/src/Preprocessor/Targets/DirectoryPathTest.php b/packages/documentator/src/Preprocessor/Targets/DirectoryPathTest.php index 550844a19..224666197 100644 --- a/packages/documentator/src/Preprocessor/Targets/DirectoryPathTest.php +++ b/packages/documentator/src/Preprocessor/Targets/DirectoryPathTest.php @@ -2,6 +2,7 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Targets; +use LastDragon_ru\LaraASP\Core\Utils\Path; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\TargetIsNotDirectory; use LastDragon_ru\LaraASP\Documentator\Testing\Package\TestCase; @@ -21,7 +22,10 @@ public function testResolveRelative(): void { $context = new Context($dir, $target, null); $resolver = new DirectoryPath(); - self::assertSame($dir, $resolver->resolve($context, $params)); + self::assertSame( + Path::normalize($dir), + $resolver->resolve($context, $params), + ); } public function testResolveAbsolute(): void { @@ -31,7 +35,10 @@ public function testResolveAbsolute(): void { $context = new Context($dir, $target, null); $resolver = new DirectoryPath(); - self::assertSame($dir, $resolver->resolve($context, $params)); + self::assertSame( + Path::normalize($dir), + $resolver->resolve($context, $params), + ); } public function testResolveNotADirectory(): void { @@ -44,6 +51,6 @@ public function testResolveNotADirectory(): void { self::expectException(TargetIsNotDirectory::class); self::expectExceptionMessage("The `{$target}` is not a directory (in `{$dir}`)."); - self::assertSame($dir, $resolver->resolve($context, $params)); + $resolver->resolve($context, $params); } } diff --git a/packages/documentator/src/Preprocessor/Targets/FilePathTest.php b/packages/documentator/src/Preprocessor/Targets/FilePathTest.php index 902fdc060..79d5d8390 100644 --- a/packages/documentator/src/Preprocessor/Targets/FilePathTest.php +++ b/packages/documentator/src/Preprocessor/Targets/FilePathTest.php @@ -2,6 +2,7 @@ namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Targets; +use LastDragon_ru\LaraASP\Core\Utils\Path; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Context; use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\TargetIsNotFile; use LastDragon_ru\LaraASP\Documentator\Testing\Package\TestCase; @@ -21,7 +22,10 @@ public function testResolveRelative(): void { $context = new Context($file, $target, null); $resolver = new FilePath(); - self::assertSame($file, $resolver->resolve($context, $params)); + self::assertSame( + Path::normalize($file), + $resolver->resolve($context, $params), + ); } public function testResolveAbsolute(): void { @@ -31,7 +35,10 @@ public function testResolveAbsolute(): void { $context = new Context($file, $target, null); $resolver = new FilePath(); - self::assertSame($file, $resolver->resolve($context, $params)); + self::assertSame( + Path::normalize($file), + $resolver->resolve($context, $params), + ); } public function testResolveNotAFile(): void { @@ -44,6 +51,6 @@ public function testResolveNotAFile(): void { self::expectException(TargetIsNotFile::class); self::expectExceptionMessage("The `{$target}` is not a file (in `{$file}`)."); - self::assertSame($file, $resolver->resolve($context, $params)); + $resolver->resolve($context, $params); } }