From 7101db71f09862bd4ce529d125b24ded8f1e3369 Mon Sep 17 00:00:00 2001 From: Baptiste Leduc Date: Tue, 25 Aug 2026 11:38:39 +0200 Subject: [PATCH] Improve JanePHP recipes first-run experience (#2033) * Improve JanePHP recipes first-run experience Recipes pointed the generator configs to specification files they never created, hid all generator output behind a NullOutput (so failures showed up as raw PHP fatals and successes printed nothing) and always exited 0, even when generation failed. - document every config key and the spec file prerequisite in config/jane/*.php - render generator output, format thrown errors and propagate exit codes in the recipe bin scripts - reorder post-install steps: placing the specification file now comes before running the generator - explain when/how to uncomment the generated normalizer service in config/packages/jane.yaml Refs: https://github.com/janephp/janephp/issues/860 * Point recipes to the current documentation website jane.readthedocs.io is outdated, jane.jolicode.com/latest/ is the current documentation home. * Re-trigger QA after adding the license header to the PR description --- .../json-schema/6.0/bin/jane-json-schema-generate | 14 +++++++++++--- .../json-schema/6.0/config/jane/json_schema.php | 15 +++++++++++++++ .../json-schema/6.0/config/packages/jane.yaml | 3 +++ jane-php/json-schema/6.0/post-install.txt | 10 +++++----- .../json-schema/7.0/bin/jane-json-schema-generate | 12 ++++++++++-- .../json-schema/7.0/config/jane/json_schema.php | 15 +++++++++++++++ .../json-schema/7.0/config/packages/jane.yaml | 3 +++ jane-php/json-schema/7.0/post-install.txt | 10 +++++----- .../6.0/bin/jane-open-api-generate | 14 +++++++++++--- .../open-api-common/6.0/config/jane/open_api.php | 14 ++++++++++++++ .../open-api-common/6.0/config/packages/jane.yaml | 3 +++ jane-php/open-api-common/6.0/post-install.txt | 10 +++++----- .../7.0/bin/jane-open-api-generate | 12 ++++++++++-- .../open-api-common/7.0/config/jane/open_api.php | 14 ++++++++++++++ .../open-api-common/7.0/config/packages/jane.yaml | 3 +++ jane-php/open-api-common/7.0/post-install.txt | 10 +++++----- 16 files changed, 132 insertions(+), 30 deletions(-) diff --git a/jane-php/json-schema/6.0/bin/jane-json-schema-generate b/jane-php/json-schema/6.0/bin/jane-json-schema-generate index 7fa9edfc..489159ee 100755 --- a/jane-php/json-schema/6.0/bin/jane-json-schema-generate +++ b/jane-php/json-schema/6.0/bin/jane-json-schema-generate @@ -4,12 +4,20 @@ require __DIR__ . '/../vendor/autoload.php'; use Jane\JsonSchema\Console\Command\GenerateCommand; -use Symfony\Component\Console\Input\ArrayInput; -use Symfony\Component\Console\Output\NullOutput; use Jane\JsonSchema\Console\Loader\ConfigLoader; use Jane\JsonSchema\Console\Loader\SchemaLoader; +use Symfony\Component\Console\Application; +use Symfony\Component\Console\Input\ArrayInput; +use Symfony\Component\Console\Output\ConsoleOutput; $command = new GenerateCommand(new ConfigLoader(), new SchemaLoader()); $inputArray = new ArrayInput(['--config-file' => __DIR__ . '/../config/jane/json_schema.php'], $command->getDefinition()); +$output = new ConsoleOutput(); -$command->execute($inputArray, new NullOutput()); +try { + exit($command->execute($inputArray, $output)); +} catch (\Throwable $throwable) { + (new Application())->renderThrowable($throwable, $output->getErrorOutput()); + + exit(1); +} diff --git a/jane-php/json-schema/6.0/config/jane/json_schema.php b/jane-php/json-schema/6.0/config/jane/json_schema.php index 83506b6c..339ff943 100644 --- a/jane-php/json-schema/6.0/config/jane/json_schema.php +++ b/jane-php/json-schema/6.0/config/jane/json_schema.php @@ -1,5 +1,20 @@ __DIR__ . '/json-schema.json', 'root-class' => 'MyModel', diff --git a/jane-php/json-schema/6.0/config/packages/jane.yaml b/jane-php/json-schema/6.0/config/packages/jane.yaml index 4bc2f383..24c19a11 100644 --- a/jane-php/json-schema/6.0/config/packages/jane.yaml +++ b/jane-php/json-schema/6.0/config/packages/jane.yaml @@ -3,4 +3,7 @@ services: autowire: true autoconfigure: true + # Uncomment the line below once you have generated your code to autowire + # the generated normalizers (and the models using them). The namespace + # must match the "namespace" key of your config/jane/*.php config file. # MyApp\Library\Generated\Normalizer\JaneObjectNormalizer: null diff --git a/jane-php/json-schema/6.0/post-install.txt b/jane-php/json-schema/6.0/post-install.txt index f9596417..09ab4e60 100644 --- a/jane-php/json-schema/6.0/post-install.txt +++ b/jane-php/json-schema/6.0/post-install.txt @@ -1,8 +1,8 @@ * Finish package configuration: - 1. Configure config/jane/json_schema.php with your specification details - 2. Run bin/jane-json-schema-generate + 1. Place your JSON Schema at config/jane/json-schema.json, or update json-schema-file in config/jane/json_schema.php + 2. Replace MyApp\Library\Generated with your own namespace in config/jane/json_schema.php and in config/packages/jane.yaml 3. Add generated/ directory to your composer autoload definition (eg. "MyApp\\Library\\Generated\\": "generated/") - 4. Open config/packages/jane.yaml and replace MyApp\Library\Generated namespace with your generated namespace. - 5. Then remove line comments + 4. Run bin/jane-json-schema-generate + 5. Once generation succeeded, uncomment the service in config/packages/jane.yaml to enable autowiring of the generated normalizer -Documentation: https://jane.readthedocs.io/en/latest/ +Documentation: https://jane.jolicode.com/latest/ diff --git a/jane-php/json-schema/7.0/bin/jane-json-schema-generate b/jane-php/json-schema/7.0/bin/jane-json-schema-generate index 55e71e67..fcffa548 100755 --- a/jane-php/json-schema/7.0/bin/jane-json-schema-generate +++ b/jane-php/json-schema/7.0/bin/jane-json-schema-generate @@ -6,10 +6,18 @@ require __DIR__ . '/../vendor/autoload.php'; use Jane\Component\JsonSchema\Console\Command\GenerateCommand; use Jane\Component\JsonSchema\Console\Loader\ConfigLoader; use Jane\Component\JsonSchema\Console\Loader\SchemaLoader; +use Symfony\Component\Console\Application; use Symfony\Component\Console\Input\ArrayInput; -use Symfony\Component\Console\Output\NullOutput; +use Symfony\Component\Console\Output\ConsoleOutput; $command = new GenerateCommand(new ConfigLoader(), new SchemaLoader()); $inputArray = new ArrayInput(['--config-file' => __DIR__ . '/../config/jane/json_schema.php'], $command->getDefinition()); +$output = new ConsoleOutput(); -$command->execute($inputArray, new NullOutput()); +try { + exit($command->execute($inputArray, $output)); +} catch (\Throwable $throwable) { + (new Application())->renderThrowable($throwable, $output->getErrorOutput()); + + exit(1); +} diff --git a/jane-php/json-schema/7.0/config/jane/json_schema.php b/jane-php/json-schema/7.0/config/jane/json_schema.php index 83506b6c..339ff943 100644 --- a/jane-php/json-schema/7.0/config/jane/json_schema.php +++ b/jane-php/json-schema/7.0/config/jane/json_schema.php @@ -1,5 +1,20 @@ __DIR__ . '/json-schema.json', 'root-class' => 'MyModel', diff --git a/jane-php/json-schema/7.0/config/packages/jane.yaml b/jane-php/json-schema/7.0/config/packages/jane.yaml index 4bc2f383..24c19a11 100644 --- a/jane-php/json-schema/7.0/config/packages/jane.yaml +++ b/jane-php/json-schema/7.0/config/packages/jane.yaml @@ -3,4 +3,7 @@ services: autowire: true autoconfigure: true + # Uncomment the line below once you have generated your code to autowire + # the generated normalizers (and the models using them). The namespace + # must match the "namespace" key of your config/jane/*.php config file. # MyApp\Library\Generated\Normalizer\JaneObjectNormalizer: null diff --git a/jane-php/json-schema/7.0/post-install.txt b/jane-php/json-schema/7.0/post-install.txt index f9596417..09ab4e60 100644 --- a/jane-php/json-schema/7.0/post-install.txt +++ b/jane-php/json-schema/7.0/post-install.txt @@ -1,8 +1,8 @@ * Finish package configuration: - 1. Configure config/jane/json_schema.php with your specification details - 2. Run bin/jane-json-schema-generate + 1. Place your JSON Schema at config/jane/json-schema.json, or update json-schema-file in config/jane/json_schema.php + 2. Replace MyApp\Library\Generated with your own namespace in config/jane/json_schema.php and in config/packages/jane.yaml 3. Add generated/ directory to your composer autoload definition (eg. "MyApp\\Library\\Generated\\": "generated/") - 4. Open config/packages/jane.yaml and replace MyApp\Library\Generated namespace with your generated namespace. - 5. Then remove line comments + 4. Run bin/jane-json-schema-generate + 5. Once generation succeeded, uncomment the service in config/packages/jane.yaml to enable autowiring of the generated normalizer -Documentation: https://jane.readthedocs.io/en/latest/ +Documentation: https://jane.jolicode.com/latest/ diff --git a/jane-php/open-api-common/6.0/bin/jane-open-api-generate b/jane-php/open-api-common/6.0/bin/jane-open-api-generate index ab6ef287..138094e1 100755 --- a/jane-php/open-api-common/6.0/bin/jane-open-api-generate +++ b/jane-php/open-api-common/6.0/bin/jane-open-api-generate @@ -4,13 +4,21 @@ require __DIR__ . '/../vendor/autoload.php'; use Jane\OpenApiCommon\Console\Command\GenerateCommand; -use Symfony\Component\Console\Input\ArrayInput; -use Symfony\Component\Console\Output\NullOutput; use Jane\OpenApiCommon\Console\Loader\ConfigLoader; use Jane\OpenApiCommon\Console\Loader\OpenApiMatcher; use Jane\OpenApiCommon\Console\Loader\SchemaLoader; +use Symfony\Component\Console\Application; +use Symfony\Component\Console\Input\ArrayInput; +use Symfony\Component\Console\Output\ConsoleOutput; $command = new GenerateCommand(new ConfigLoader(), new SchemaLoader(), new OpenApiMatcher()); $inputArray = new ArrayInput(['--config-file' => __DIR__ . '/../config/jane/open_api.php'], $command->getDefinition()); +$output = new ConsoleOutput(); -$command->execute($inputArray, new NullOutput()); +try { + exit($command->execute($inputArray, $output)); +} catch (\Throwable $throwable) { + (new Application())->renderThrowable($throwable, $output->getErrorOutput()); + + exit(1); +} diff --git a/jane-php/open-api-common/6.0/config/jane/open_api.php b/jane-php/open-api-common/6.0/config/jane/open_api.php index cc34865e..b567fad4 100644 --- a/jane-php/open-api-common/6.0/config/jane/open_api.php +++ b/jane-php/open-api-common/6.0/config/jane/open_api.php @@ -1,5 +1,19 @@ __DIR__ . '/open-api.yaml', 'namespace' => 'MyApp\Library\Generated', diff --git a/jane-php/open-api-common/6.0/config/packages/jane.yaml b/jane-php/open-api-common/6.0/config/packages/jane.yaml index 4bc2f383..70a415e2 100644 --- a/jane-php/open-api-common/6.0/config/packages/jane.yaml +++ b/jane-php/open-api-common/6.0/config/packages/jane.yaml @@ -3,4 +3,7 @@ services: autowire: true autoconfigure: true + # Uncomment the line below once you have generated your code to autowire + # the generated normalizers (and the client using them). The namespace + # must match the "namespace" key of your config/jane/*.php config file. # MyApp\Library\Generated\Normalizer\JaneObjectNormalizer: null diff --git a/jane-php/open-api-common/6.0/post-install.txt b/jane-php/open-api-common/6.0/post-install.txt index 9c48ddef..fb9794bc 100644 --- a/jane-php/open-api-common/6.0/post-install.txt +++ b/jane-php/open-api-common/6.0/post-install.txt @@ -1,8 +1,8 @@ * Finish package configuration: - 1. Configure config/jane/open_api.php with your specification details - 2. Run bin/jane-open-api-generate + 1. Place your API specification at config/jane/open-api.yaml, or update openapi-file in config/jane/open_api.php + 2. Replace MyApp\Library\Generated with your own namespace in config/jane/open_api.php and in config/packages/jane.yaml 3. Add generated/ directory to your composer autoload definition (eg. "MyApp\\Library\\Generated\\": "generated/") - 4. Open config/packages/jane.yaml and replace MyApp\Library\Generated namespace with your generated namespace. - 5. Then remove line comments + 4. Run bin/jane-open-api-generate + 5. Once generation succeeded, uncomment the service in config/packages/jane.yaml to enable autowiring of the generated normalizer -Documentation: https://jane.readthedocs.io/en/latest/ +Documentation: https://jane.jolicode.com/latest/ diff --git a/jane-php/open-api-common/7.0/bin/jane-open-api-generate b/jane-php/open-api-common/7.0/bin/jane-open-api-generate index 7f5f95a6..b7e3bdf7 100755 --- a/jane-php/open-api-common/7.0/bin/jane-open-api-generate +++ b/jane-php/open-api-common/7.0/bin/jane-open-api-generate @@ -7,10 +7,18 @@ use Jane\Component\OpenApiCommon\Console\Command\GenerateCommand; use Jane\Component\OpenApiCommon\Console\Loader\ConfigLoader; use Jane\Component\OpenApiCommon\Console\Loader\OpenApiMatcher; use Jane\Component\OpenApiCommon\Console\Loader\SchemaLoader; +use Symfony\Component\Console\Application; use Symfony\Component\Console\Input\ArrayInput; -use Symfony\Component\Console\Output\NullOutput; +use Symfony\Component\Console\Output\ConsoleOutput; $command = new GenerateCommand(new ConfigLoader(), new SchemaLoader(), new OpenApiMatcher()); $inputArray = new ArrayInput(['--config-file' => __DIR__ . '/../config/jane/open_api.php'], $command->getDefinition()); +$output = new ConsoleOutput(); -$command->execute($inputArray, new NullOutput()); +try { + exit($command->execute($inputArray, $output)); +} catch (\Throwable $throwable) { + (new Application())->renderThrowable($throwable, $output->getErrorOutput()); + + exit(1); +} diff --git a/jane-php/open-api-common/7.0/config/jane/open_api.php b/jane-php/open-api-common/7.0/config/jane/open_api.php index cc34865e..b567fad4 100644 --- a/jane-php/open-api-common/7.0/config/jane/open_api.php +++ b/jane-php/open-api-common/7.0/config/jane/open_api.php @@ -1,5 +1,19 @@ __DIR__ . '/open-api.yaml', 'namespace' => 'MyApp\Library\Generated', diff --git a/jane-php/open-api-common/7.0/config/packages/jane.yaml b/jane-php/open-api-common/7.0/config/packages/jane.yaml index 4bc2f383..70a415e2 100644 --- a/jane-php/open-api-common/7.0/config/packages/jane.yaml +++ b/jane-php/open-api-common/7.0/config/packages/jane.yaml @@ -3,4 +3,7 @@ services: autowire: true autoconfigure: true + # Uncomment the line below once you have generated your code to autowire + # the generated normalizers (and the client using them). The namespace + # must match the "namespace" key of your config/jane/*.php config file. # MyApp\Library\Generated\Normalizer\JaneObjectNormalizer: null diff --git a/jane-php/open-api-common/7.0/post-install.txt b/jane-php/open-api-common/7.0/post-install.txt index 9c48ddef..fb9794bc 100644 --- a/jane-php/open-api-common/7.0/post-install.txt +++ b/jane-php/open-api-common/7.0/post-install.txt @@ -1,8 +1,8 @@ * Finish package configuration: - 1. Configure config/jane/open_api.php with your specification details - 2. Run bin/jane-open-api-generate + 1. Place your API specification at config/jane/open-api.yaml, or update openapi-file in config/jane/open_api.php + 2. Replace MyApp\Library\Generated with your own namespace in config/jane/open_api.php and in config/packages/jane.yaml 3. Add generated/ directory to your composer autoload definition (eg. "MyApp\\Library\\Generated\\": "generated/") - 4. Open config/packages/jane.yaml and replace MyApp\Library\Generated namespace with your generated namespace. - 5. Then remove line comments + 4. Run bin/jane-open-api-generate + 5. Once generation succeeded, uncomment the service in config/packages/jane.yaml to enable autowiring of the generated normalizer -Documentation: https://jane.readthedocs.io/en/latest/ +Documentation: https://jane.jolicode.com/latest/