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
|
<twig:Pcm:Badge class="text-xl p-8" colour="maroon" outline>Danger!</twig:Pcm:Badge>
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
|
<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`
|
```php
|
||||||
while the class name should be `PcmEpicLoginBundle`.
|
// Job.php
|
||||||
|
|
||||||
Subsequently, all namespaces should be changed to start with `pcm\epiclogin`.
|
public function getBadgeColour(): Badge
|
||||||
|
|
||||||
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
|
|
||||||
{
|
{
|
||||||
"minimum-stability": "dev",
|
return match ($this->getKind()) {
|
||||||
"prefer-stable": true,
|
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:
|
You then specify the object using the `obj` prop when rendering the badge:
|
||||||
```json
|
|
||||||
{
|
```twig
|
||||||
"repositories": [
|
{# job.html.twig #}
|
||||||
{
|
|
||||||
"type": "vcs",
|
<twig:Pcm:Badge :obj="job">{{ job.kind.value }}</twig:Pcm:Badge>
|
||||||
"url": "ssh://example/bundle.git"
|
|
||||||
},
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Installing the development bundle
|
<br>
|
||||||
|
|
||||||
You can now install the bundle with composer. Because the bundle does not yet have a tagged version we
|
# Standalone badges
|
||||||
have to specify that it's a dev bundle alongside a branch to use. For example:
|
|
||||||
```sh
|
If you just want a badge of a certain colour instead of associating it with an object, you can specify a `colour` prop instead.
|
||||||
composer require pcm/example-bundle:dev-develop
|
|
||||||
|
```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:
|
obj="{{ job.kind }}"
|
||||||
```sh
|
|
||||||
composer update pcm/example-bundle
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 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:
|
`outline` - A boolean attribute that changes the style of the badge to an outline.
|
||||||
```sh
|
|
||||||
composer remove pcm/example-bundle
|
`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