Work on readme
This commit is contained in:
brabli
143
README.md
143
README.md
@@ -1,119 +1,86 @@
|
||||
# Symfony Bundle Skeleton
|
||||
# PCM Badge Bundle
|
||||
|
||||
A **WORK IN PROGRESS** skeleton for creating Symfony Bundles.
|
||||
Create badges from objects or as standalone elements.
|
||||
|
||||
This skeleton is a very basic bundle with comments explaining what various bits are doing.
|
||||
IMAGE HERE
|
||||
|
||||
The bundle is called `PcmExampleBundle` and contains a `Greeting` class with a `greet(): string` method.
|
||||
```twig
|
||||
<twig:Pcm:Badge :obj="job.kind">{{ job.kind.label }}</twig:Pcm:Badge>
|
||||
|
||||
The `greet()` method returns a string welcoming someone who's name you can specify in the bundle configuration file.
|
||||
<twig:Pcm:Badge :obj="job.kind" outline>{{ job.kind.label }}</twig:Pcm:Badge>
|
||||
|
||||
<twig:Pcm:Badge colour="green">Sale 20% off</twig:Pcm:Badge>
|
||||
|
||||
# Installing dependencies
|
||||
|
||||
You need to run `docker compose run php` before any composer commands. EG:
|
||||
```sh
|
||||
docker compose run php composer require symfony/twig-bundle
|
||||
<twig:Pcm:Badge class="text-xl p-8" colour="maroon" outline>Danger!</twig:Pcm:Badge>
|
||||
```
|
||||
The Makefile has some common shorthands as usual.
|
||||
|
||||
<br>
|
||||
|
||||
# Modifying this bundle
|
||||
# Badgeable interface
|
||||
|
||||
To change this bundle from `pcm/example-bundle` to something new there are few files you need to change.
|
||||
Any object that you would like to be able to be turned into a badge must implement `BadgeableInterface`.
|
||||
|
||||
1. **Bundle PHP file and namespace**
|
||||
This interface specifies a single method `getBadgeColour()` and is used to determine what colour the badge should be rendered as.
|
||||
|
||||
The file at `src/PcmExampleBundle.php` should have it's class name and filename changed.
|
||||
This method can contain as much logic in it as you'd like to return different colours of badge under different circumstances. EG:
|
||||
|
||||
If you are creating a bundle called `pcm/epic-login-bundle` the namespace should be `Pcm\EpicLogin`
|
||||
while the class name should be `PcmEpicLoginBundle`.
|
||||
```php
|
||||
// Job.php
|
||||
|
||||
Subsequently, all namespaces should be changed to start with `pcm\epiclogin`.
|
||||
|
||||
2. **composer metadata**
|
||||
|
||||
Update the `name` and `description` fields of the `composer.json` file with appropriate names.
|
||||
The name should
|
||||
|
||||
You will also need to update the PSR autoload classes with your bundle's class name.
|
||||
|
||||
Optionally edit the authors if required.
|
||||
|
||||
3. **Config files**
|
||||
|
||||
- Chamge 'bundles.php` to use your new bundle class
|
||||
- Modify `services.yaml` when required
|
||||
- Update `definition.yaml` to specify your config structure (or remove if no config is required)
|
||||
|
||||
4. **Test files**
|
||||
|
||||
The `TestKernel` needs to return an array containing your bundle class.
|
||||
|
||||
Again, namespaces need changing to whatever is appropriate.
|
||||
|
||||
# PHPUnit testing
|
||||
|
||||
The bundle and it's configuration can be tested with PHPUnit.
|
||||
|
||||
This was a worthwhile section to add.
|
||||
|
||||
|
||||
# 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
|
||||
public function getBadgeColour(): Badge
|
||||
{
|
||||
"minimum-stability": "dev",
|
||||
"prefer-stable": true,
|
||||
return match ($this->getKind()) {
|
||||
JobKind::Investigation => Badge::BLUE,
|
||||
JobKind::Interrogation => Badge::RED,
|
||||
JobKind::Shootout => Badge::BLACK,
|
||||
JobKind::SipWhiskey => Badge::FOREST,
|
||||
default => Badge::GREY
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
Next, you need to add the repository to the `composer.json` file, just as you would any other PCM bundle:
|
||||
```json
|
||||
{
|
||||
"repositories": [
|
||||
{
|
||||
"type": "vcs",
|
||||
"url": "ssh://example/bundle.git"
|
||||
},
|
||||
]
|
||||
}
|
||||
You then specify the object using the `obj` prop when rendering the badge:
|
||||
|
||||
```twig
|
||||
{# job.html.twig #}
|
||||
|
||||
<twig:Pcm:Badge :obj="job">{{ job.kind.value }}</twig:Pcm:Badge>
|
||||
```
|
||||
|
||||
### Installing the development bundle
|
||||
<br>
|
||||
|
||||
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
|
||||
# Standalone badges
|
||||
|
||||
If you just want a badge of a certain colour instead of associating it with an object, you can specify a `colour` prop instead.
|
||||
|
||||
```twig
|
||||
<twig:Pcm:Badge colour="red">Danger</twig:Pcm:Badge>
|
||||
```
|
||||
|
||||
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`.
|
||||
<br>
|
||||
|
||||
If a flex recipe is present it will prompt you to install it.
|
||||
# Props overview
|
||||
|
||||
**NOTE** that 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.
|
||||
A badge must contain either an `obj` or a `colour`, but not both.
|
||||
|
||||
### Updating the development bundle
|
||||
`obj` - An instance of an object that implements `BadgeableInterface`. You can use either of the follow syntaxes:
|
||||
```twig
|
||||
:obj="job.kind"
|
||||
|
||||
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
|
||||
obj="{{ job.kind }}"
|
||||
```
|
||||
|
||||
### Uninstalling your development bundle
|
||||
`colour` - One of the available colours specified by the `Badge` enum. For a full list of acceptable values type in some junk and read the exception message.
|
||||
|
||||
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
|
||||
`outline` - A boolean attribute that changes the style of the badge to an outline.
|
||||
|
||||
`class` - Extra classes you want to add to the badge element. These will override the base classes in case of conflicts.
|
||||
|
||||
<br>
|
||||
|
||||
# Config
|
||||
|
||||
```yaml
|
||||
pcm_badge:
|
||||
base_classes: "base classes here"
|
||||
```
|
||||
|
||||
# Creating a flex recipe
|
||||
|
||||
See the flex recipe repo for info on how to do this.
|
||||
|
||||
Reference in New Issue
Block a user