pcm-libraries/pcm-metadata-bundle
4
0
Fork 0
Code Issues Packages Releases Activity

Update readme

Browse Source
This commit is contained in:
brabli
2025-11-27 15:17:26 +00:00
parent 0b5bebc2af
commit b1dd0c0ffc
1 changed files with 13 additions and 121 deletions
Download Patch File Download Diff File Expand all files Collapse all files

134
README.md
View File

@@ -1,127 +1,19 @@
# Bundle Skeleton # PCM Metadata Bundle
A skeleton project for creating Symfony bundles. Easily add metadata to a Symfony entity via the use of a key-value interface.
This skeleton is a very basic bundle with comments explaining what various bits are doing. # Usage
1. Use the `MetadataTrait` inside an entity:
The bundle is called `PcmExampleBundle` and contains a `Greeting` class with a `greet(): string` method. ```php
class MyEntity
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:
```sh
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:
```json
{ {
"minimum-stability": "dev", use MetadataTrait;
"prefer-stable": true,
} }
``` ```
2. Create and execute a new migration. The trait adds a `metadata` database field and as such we need to create a migration.
Next, you need to add the repository to the `composer.json` file, just as you would any other PCM bundle: 3. Access the metadata object with the readonly property `metadata`:
```json ```php
{ $entity->metadata->set("name", "PCM");
"repositories": [ $entity->metadata->get("name"); // "PCM"
{ $entity->metadata->isSet("name"); // true
"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:
```sh
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:
```sh
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:
```sh
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](https://semver.org/#summary) and tag the first release as `0.1.0`.
```sh
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:
```sh
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.