From 13d27ece0022251813ece690364642ca43ef2b67 Mon Sep 17 00:00:00 2001 From: brabli <67018167+Brabli@users.noreply.github.com> Date: Fri, 9 Aug 2024 10:42:40 +0100 Subject: [PATCH] Work on readme --- README.md | 143 +++++++++++++++++++++--------------------------------- 1 file changed, 55 insertions(+), 88 deletions(-) diff --git a/README.md b/README.md index 28ab80d..18a058d 100644 --- a/README.md +++ b/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 +{{ job.kind.label }} -The `greet()` method returns a string welcoming someone who's name you can specify in the bundle configuration file. +{{ job.kind.label }} +Sale 20% off -# 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 +Danger! ``` -The Makefile has some common shorthands as usual. +
-# 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 #} + +{{ job.kind.value }} ``` -### 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 +# 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 +Danger ``` -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 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. + +
+ +# 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.