How to generate a private recipe JSON from the contents of a recipe directory?

Question

I've developed a Symfony bundle, and I am trying to create a recipe. Before submitting it to recipes-contrib, I want to test it, so I followed the instructions for private recipes -- not because I want a private recipe (that is, neither the bundle nor the recipe is "private" in the sense of a private GitHub project).

I have read, re-read, then read again the documentation for creating a recipe, and I feel like I'm missing a very important step. The documentation for a private repository only talks about the package.version.json file, e.g.

{
    "manifests": {
        "acme/private-bundle": {
            "manifest": {
                "bundles": {
                    "Acme\\PrivateBundle\\AcmePrivateBundle": [
                        "all"
                    ]
                },
                "copy-from-recipe": {
                    "config/": "%CONFIG_DIR%"
                }
            },
            "files": {
                "config/packages/acme_private.yaml": {
                    "contents": [
                        "acme_private:",
                        "    encode: true",
                        ""
                    ],
                    "executable": false
                }
            },
            "ref": "7405f3af1312d1f9121afed4dddef636c6c7ff00"
        }
    }
}

This file appears to be the output of some command that reads the file in the format as expected for a contrib recipe: a directory structure that has a config directory for routes and packages, maybe a src directory, etc.

Obviously, no one is typing in by hand line by line a YAML file (or PHP!) as a list of strings in the content key.

It appears that the master branch of recipes and recipes-contrib contains the directory structure, and flex/main branch contains the "compiled" JSON recipe file.

But in the private recipe instructions, there are no instructions as to how to get from the DX-friendly files to the JSON recipe.

TL;DR; How do I create a package.version.json recipe from the package/version/ directory that contains manifest.json, config, etc.?

Answer 1

I had the same problem few hours ago and I finally get it. Clues were given by the blog post https://symfony.com/blog/symfony-flex-is-going-serverless were we can see that a script and a tool exist.

I duplicated the Github Actions and adapted those files in one of my repositories: https://github.com/web-token/recipes

• The main branch contains the compiled files, including the index.json: this is what you want to have to get it working.
• The tree branch is the one where developer friendly files live.

The tree branch contains the Github Actions workflows that update the main branch. Feel free to copy and adapt the folder https://github.com/web-token/recipes/tree/tree/.github with your parameters.

Note that the server URL to declare in the composer file will look like https://api.github.com/repos/web-token/recipes/contents/index.json?ref=main

Answer 2

Yeah, I agree that the instructions are a big opaque there.

The missing step is performed by by symfony-tools/recipe-checker (link).

The repo is (sadly) not available as a package on Packagist, so to install and run it locally you'd it you either modify your configuration to add a custom repository pointing there, or you clone/download without using composer.

E.g.

git clone https://github.com/symfony-tools/recipes-checker
cd recipes-checker
composer install

Now you have the script ready to use. Assuming you downloaded it in your home directory, you could run:

~/recipe-checker/run generate:flex-endpoint <repository> <source_branch> <flex_branch> <output_directory>

The different arguments are (as gotten from run generate:flex-endpoint --help):

Arguments:
  repository            The name of the GitHub repository
  source_branch         The source branch of recipes
  flex_branch           The branch of the target Flex endpoint
  output_directory      The directory where generated files should be stored
  versions_json         The file where versions of Symfony are described

So if you have a recipe repository for a package like yivi/stub-bundle, version 1.0, with the repository hosted at https://github.com/yivi/stub-bundle-recipe

<dir>
└── yivi
     └─stub-bundle
          └── 1.0
               ├── bin
               │   └── something.sh
               ├ manifest.json
               └ post-install.json

You could simply cd into the package directory and run:

~/recipe-checker/run generate:flex-endpoint yivi/stub-bundle-recipe main main .

This would generate locally the "compiled" recipe (or recipes, if you have multiple on that directory) and you'd end up with this in that directory:

• index.json
• yivi.stub-bundle.1.0.json
• archived/ (dir)

To "test" this locally, it would simply a matter to commit and push this repo, and on a project that will want to use the recipes hosted here update the composer.json extra.symfony field to include:

"extra": {
    "symfony": {
       "endpoint": [
           "https://api.github.com/repos/yivi/stub-bundle-recipe/contents/index.json",
           "flex://defaults"
            ]
        }
}

The nice answer by Spomky links to a GitHub action that could do this for you automatically on the receiving repo, cleanly separating in different branches the "source" recipes and the "compiled" recipes, but I think this example will more easily show how to perform the process step by step by yourself.