Bundle Skeleton

A skeleton project for creating Symfony bundles.

This skeleton is a very basic bundle with comments explaining what various bits are doing.

The bundle is called PcmExampleBundle and contains a Greeting class with a greet(): string method.

The greet() method returns a string welcoming someone who's name you can specify in the bundle configuration file.

Quickstart

There is a quickstart shell script located at bin/quickstart.

Running this script will prompt you to enter a PascalCase name for your bundle, for example if you wanted to create a bundle called pcm/my-cool-bundle you should enter MyCoolBundle.

This performs a crude search and replace across the example bundle to update the class names and namespaces before installing the project dependencies.

You will still need to manually update the repository name and description in composer.json.

Adding a deploy key to new repositories

When this project is used as a template the resulting repository will need a deploy token associated with it before other projects can composer install it.

This is done in Gitea by going to Settings -> Deploy Keys -> Add Deploy Key, then pasting in the deploy key's public key.

The deploy key in question is located in Keeper under "Deploy key for Piermont bundles".

Installing dependencies during development

You need to run docker compose run php before any composer commands. EG:

docker compose run php composer require symfony/twig-bundle

The Makefile has some common shorthands as usual.

PHPUnit testing

The bundle and it's configuration can be tested with PHPUnit.

Installing a development version of the bundle

If you need to install the bundle to test stuff (EG to see how certain Twig templates look, etc) you can do so by using a development version of the bundle.

Preparing the composer.json file

First, make sure your Symfony project has the following in it's composer.json file:

{
    "minimum-stability": "dev",
    "prefer-stable": true,
}

Next, you need to add the repository to the composer.json file, just as you would any other PCM bundle:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "ssh://example/bundle.git"
        },
    ]
}

Installing the development bundle

You can now install the bundle with composer. Because the bundle does not yet have a tagged version we have to specify that it's a dev bundle alongside a branch to use. For example:

composer require pcm/example-bundle:dev-develop

The dev-develop part is specifying both that it's a dev package and that we want to use the develop branch. If you wanted to use the master branch you would specify as so: dev-master.

If your project has minimum-stability: dev set you can run a composer install without specifying the dev version and it will automatically install a dev version with the repo's default branch. I think that specifying the dev branch manually is less confusing though so I'd recommend against doing it this way.

If a flex recipe is present it will prompt you to install it.

NOTE If a flex recipe with a dev version set as it's minimum version is present and installed, the "symfony.lock" file will generate an incorrect version number "develop.9999999". This causes issues when uninstalling, so manually change this value to be dev-develop or whichever version you installed.

Updating the development bundle

You can make changes to the bundle whilst it's installed. Once you've pushed your changes with git you can run a composer update to retrieve the most recent changes:

composer update pcm/example-bundle

Uninstalling your development bundle

Make sure that the bundle version is correct in the symfony.lock file (see above) before running the usual uninstall command:

composer remove pcm/example-bundle

Versioning

Once you have a version of your bundle you are happy with you can give it a tag.

Follow semantic versioning and tag the first release as 0.1.0.

git tag 0.1.0
git push origin 0.1.0

Now you should be able to install the package by running the composer require command without an additional version:

composer require pcm/example-bundle

Creating a flex recipe

I recommend not creating a recipe until at least the first tagged release of your bundle. This is because creating a flex recipe with dev-develop as it's version number works, however it causes an error in the symfony.lock file (see above). This can be resolved by manually editing the file, but it's still a bit annoying.

See the flex recipe repository for info on how to create a flex recipe.