Add full vitepress documentation page (#69)

* Write UPGRADE guide

* Rewrote upgrade guide

* Add simple vitepress project

* Configure colors

* Finish first draft of "Getting started"

* Add first draft of installation chapter

* Add first draft of supported versions

* Add first draft of upgrade guide

* Add first draft of first fixture page, add uuid command

* Add first draft of the "Dependencies & Prioritization" page

* Add first draft of grouping chapter

* Add first draft of "Available commands" page

* Add first draft of "Fixture Helper" page

* Add first draft of "PHPUnit & Tests" chapter

* Add first draft of "Utility methods" page

* Add first draft of "media helper" page

* Add first draft of category helpers page

* Add first draft of sales channel helper page

* Add first draft of salutation page

* Add first draft of cms page

* Add first drafts for payment- and shipping method pages

* Add first draft of "Language & Locale" helpers

* Add first drafts of currency and tax page

* Finish first draft of all helper pages

* Finish examples

* Rewrote a lot of pages

* finalized all links

* Add first try at deployment

* Fix wrong variable

* Fix base path

* Only run on main branch

.github/workflows/deploy-docs.yml

@@ -0,0 +1,43 @@
+name: Deploy documentation
+
+on:
+    push:
+        branches: [main]
+
+permissions:
+    contents: read
+    pages: write
+    id-token: write
+
+concurrency:
+    group: pages
+    cancel-in-progress: false
+
+jobs:
+    build:
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v4
+            - uses: oven-sh/setup-bun@v1
+            - name: Setup pages
+              uses: actions/configure-pages@v4
+            - name: Install dependencies
+              run: bun install
+            - name: Build vitepress
+              run: bun run docs:build
+            - name: Upload artifact
+              uses: actions/upload-pages-artifact@v3
+              with:
+                path: docs/.vitepress/dist
+
+    deploy:
+        environment:
+            name: github-pages
+            url: ${{ steps.deployment.outputs.page_url }}
+        needs: build
+        runs-on: ubuntu-latest
+        steps:
+            - name: Deploy to Github Pages
+              id: deployment
+              uses: actions/deploy-pages@v4

.github/workflows/linting.yml

@@ -107,8 +107,10 @@ jobs:
             -   name: Check out code
                 uses: actions/checkout@v4
 
+            - uses: oven-sh/setup-bun@v1
+
             -   name: Install dependencies
-                run: npm ci
+                run: bun install
 
             -   name: Run Prettier
                 run: './node_modules/.bin/prettier --check "src/**/*.{js,scss,yaml,yml,json,md,ts}"'

.gitignore

@@ -8,3 +8,6 @@
 /src/Resources/app/storefront/node_modules/
 composer.lock
 src/Examples
+/docs/.vitepress/dist
+/docs/.vitepress/cache
+package-lock.json

CHANGELOG.md

@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `deleteEntities` takes an entity name and criteria and deletes all entities which match the criteria
 - Added a small cache for all utilities. It prevents loading data twice within the same request / command execution
 - Added small helper function: `$fixtureHelper->ensureNotEmpty` which throws an exception if something is empty (using the PHP empty function)
+- Added command `fixture:uuid` which just prints a random UUID
 
 ### Changed
 - Changed argument type on `SalesChannelUtils::getTax()` from `int` to `float`

Makefile

@@ -44,7 +44,7 @@ shell:
 ## Install all dependencies
 dependencies:
 	make docker COMMAND="composer install --no-interaction --optimize-autoloader"
-	make docker COMMAND="npm ci"
+	make docker COMMAND="npm install"
 
 ## Install all dependencies and prepare everything
 install:

UPGRADE.md

@@ -1,5 +1,110 @@
 # Upgrade
 
+## v2.x -> v3.x
+### See changelog
+First, review the changes documented in CHANGELOG.md.
+
+### Support for older versions (Impact: High)
+Release V3 has dropped support for PHP 8.1 and Shopware 6.3 & 6.4. The supported versions are now PHP 8.2, PHP 8.3, and Shopware 6.5 and 6.6.
+
+### Dropped FixtureBag (Impact: High)
+Support for the FixtureBag parameter in every `load` method has been removed. Each fixture needs to be updated accordingly:
+
+#### Before
+```php
+class CustomerFixture extends Fixture
+{
+    public function load(FixtureBag $bag): void 
+    {
+        // ...
+    }
+}
+```
+
+#### After
+```php
+class CustomerFixture extends Fixture
+{
+    public function load(): void 
+    {
+        // ...
+    }
+}
+```
+
+### Vendor Fixtures (Impact: Low)
+In version 2, fixtures within the `vendor` folder were executed alongside project-specific fixtures. This behavior has changed in V3. Now, only direct fixtures (those not within the `vendor` folder) will be executed.
+
+Every fixture command now supports an additional flag `--vendor` to include vendor fixtures:
+```shell
+bin/console fixture:load --vendor
+bin/console fixture:load:single --vendor MyFixture
+bin/console fixture:load:group --vendor MyGroup
+```
+
+### Fixture Loader (Impact: Low)
+All fixture are loaded from a `FixtureLoader` service. If you never directly accessed the loader and only used the built-in trait and commands, you can ignore this section.
+
+We have completely rewritten the logic to define which fixtures are executed. The fixture loader now accepts a single argument: `$options`. Within this options object, you can specify exactly how the fixture plugin loads fixtures:
+
+```php
+readonly class FixtureOption
+{
+    public function __construct(
+        public bool $dryMode = false,
+        public ?string $groupName = null,
+        public array $fixtureNames = [],
+        public bool $withDependencies = false,
+        public bool $withVendor = false,
+    ) {
+    }
+}
+```
+
+All options are combinable, and the internal commands and traits also use this options object.
+
+### FixtureTrait
+The `FixtureTrait` used for testing has been rewritten to use the new `FixtureOption` structure.
+
+The `runFixtures` method, which previously took an array of fixture names, now takes a `FixtureOption` class. To achieve the original behavior, you can either provide a `FixtureOption` class with the `$fixtureNames` parameter filled out or use our new alias method: `runSpecificFixtures`, which works like the previous `runFixtures`. The new method also includes a parameter to load all dependencies of those fixtures.
+
+```php
+// Either:
+$this->runFixtures(new FixtureOption(fixtureNames: ['MyFixture', 'AnotherFixture']));
+
+// Or:
+$this->runSpecificFixtures(['MyFixture', 'AnotherFixture']);
+```
+
+The `runSingleFixtureWithDependencies` method has been replaced with `runSingleFixture`. The first argument is the name of the fixture, and the second argument is a boolean to determine if dependencies should be loaded.
+
+```php
+// Before:
+$this->runSingleFixtureWithDependencies('MyFixture');
+
+// After:
+$this->runSingleFixture('MyFixture', true);
+```
+
+### Helper methods moved / deleted
+Many of our helper methods have been updated. Below is a list of affected methods. All not mentioned helpers still work like in V2:
+
+- `$this->helper->Category()->getFirst()` is removed. No replacement is available
+- `$this->helper->Category()->getByName()` is removed. No replacement is available
+- `$this->helper->Customer()->getNotSpecifiedSalutation()` has moved to `$this->helper->Salutation()->getNotSpecifiedSalutation()`
+- `$this->helper->SalesChannel()->getCurrencyEuro()` has moved to `$this->helper->Currency()->getCurrencyEuro()`
+- `$this->helper->SalesChannel()->getLanguage()` has moved to `$this->helper->LanguageAndLocale()->getLanguage()`
+- `$this->helper->SalesChannel()->getLocale()` has moved to `$this->helper->LanguageAndLocale()->getLocale()`
+- `$this->helper->SalesChannel()->getCountry()` has moved to `$this->helper->LanguageAndLocale()->getCountry()`
+- `$this->helper->SalesChannel()->getSnippetSet()` has moved to `$this->helper->LanguageAndLocale()->getSnippetSet()`
+- `$this->helper->SalesChannel()->getTax19()` has moved to `$this->helper->Tax()->getTax19()`
+- `$this->helper->SalesChannel()->getTax()` has moved to `$this->helper->Tax()->getTax()`
+
+### Recommendation: Fixture Helper is now given to any fixture
+In V3, every fixture has access to the fixture helper by default using $this->helper.
+Therefore, while not strictly a breaking change, we advise against manually loading the fixture helper via dependency injection and instead using the provided helper.
+
+
 ## v1.x -> v2.x
 ### See changelog
 First have a look at the changes in the CHANGELOG.md

_examples/CustomerFixture.php

@@ -5,46 +5,43 @@
 namespace Basecom\FixturePlugin;
 
 use Shopware\Core\Framework\Context;
-use Shopware\Core\Framework\DataAbstractionLayer\EntityRepositoryInterface;
+use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
 
 class CustomerFixture extends Fixture
 {
     private const CUSTOMER_ID = '0d8eefdd6d32456385580e2ff42431b9';
     private const ADDRESS_ID  = 'e27dc2b4e85f4a0f9a912a09f07701b0';
 
-    private FixtureHelper $helper;
-    private EntityRepositoryInterface $customerRepository;
-
-    public function __construct(FixtureHelper $helper, EntityRepositoryInterface $customerRepository)
-    {
-        $this->helper             = $helper;
-        $this->customerRepository = $customerRepository;
+    public function __construct(
+        private readonly EntityRepository $customerRepository
+    ) {
     }
 
-    public function load(FixtureBag $bag): void
+    public function load(): void
     {
         $salesChannel = $this->helper->SalesChannel()->getStorefrontSalesChannel();
+        $this->helper->ensureNotEmpty($salesChannel);
 
         $this->customerRepository->upsert([[
             'id'                     => self::CUSTOMER_ID,
             'salesChannelId'         => $salesChannel->getId(),
             'groupId'                => $salesChannel->getCustomerGroupId(),
-            'defaultPaymentMethodId' => $this->helper->PaymentMethod()->getInvoicePaymentMethod()->getId(),
+            'defaultPaymentMethodId' => $this->helper->PaymentMethod()->getInvoicePaymentMethod()?->getId(),
             'defaultBillingAddress'  => [
                 'id'           => self::ADDRESS_ID,
-                'salutationId' => $this->helper->Salutation()->getNotSpecifiedSalutation()->getId(),
-                'firstName'    => 'John',
-                'lastName'     => 'Doe',
+                'salutationId' => $this->helper->Salutation()->getNotSpecifiedSalutation()?->getId(),
+                'firstName'    => 'Zoey',
+                'lastName'     => 'Smith',
                 'zipcode'      => '1234',
                 'street'       => 'Sample Street',
                 'city'         => 'Berlin',
-                'countryId'    => $this->helper->SalesChannel()->getCountry('DE')->getId(),
+                'countryId'    => $this->helper->LanguageAndLocale()->getCountry('DE')?->getId(),
             ],
             'defaultShippingAddressId' => self::ADDRESS_ID,
-            'salutationId'             => $this->helper->Salutation()->getNotSpecifiedSalutation()->getId(),
+            'salutationId'             => $this->helper->Salutation()->getNotSpecifiedSalutation()?->getId(),
             'customerNumber'           => '1122',
-            'firstName'                => 'John',
-            'lastName'                 => 'Doe',
+            'firstName'                => 'Zoey',
+            'lastName'                 => 'Smith',
             'email'                    => '[email protected]',
             'password'                 => 'notset',
         ]], Context::createDefaultContext());

docs/.vitepress/config.mts

@@ -0,0 +1,95 @@
+import { defineConfig } from 'vitepress'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "Shopware 6 Fixture Plugin",
+  description: "The fixture plugin is really helpful if you want to create some static demo data",
+  base: "/FixturesPlugin",
+  lastUpdated: true,
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Getting started', link: '/getting-started' },
+    ],
+
+    sidebar: [
+      {
+        text: 'Basics',
+        items: [
+          { text: 'Getting started', link: '/getting-started' },
+          { text: 'Installation', link: '/installation' },
+          { text: 'Supported versions', link: '/supported-versions' },
+          { text: 'Upgrade guide', link: '/upgrade' },
+          { text: 'Changelog', link: 'https://github.com/basecom/FixturesPlugin/blob/main/CHANGELOG.md' },
+        ]
+      },
+      {
+        text: 'Writing fixtures',
+        items: [
+          { text: 'Your first fixture', link: '/writing/first-fixture' },
+          { text: 'Dependencies & Prioritization', link: '/writing/dependencies-prioritization' },
+          { text: 'Grouping', link: '/writing/groups' },
+          { text: 'Available commands', link: '/writing/available-commands' },
+          { text: 'Fixture Helper', link: '/writing/fixture-helper' },
+          { text: 'PHPUnit & Tests', link: '/writing/phpunit-tests' },
+        ]
+      },
+      {
+        text: 'Fixture Helpers',
+        items: [
+          { text: 'Utility methods', link: '/helpers/utility' },
+          { text: 'Media Helpers', link: '/helpers/media' },
+          { text: 'Category Helpers', link: '/helpers/category' },
+          { text: 'Sales Channel Helpers', link: '/helpers/sales-channel' },
+          { text: 'Salutation Helpers', link: '/helpers/salutation' },
+          { text: 'CMS Helpers', link: '/helpers/cms' },
+          { text: 'Payment Method Helpers', link: '/helpers/payment-method' },
+          { text: 'Shipping Method Helpers', link: '/helpers/shipping-method' },
+          { text: 'Language & Locale Helpers', link: '/helpers/language-locale' },
+          { text: 'Currency Helpers', link: '/helpers/currency' },
+          { text: 'Tax Helpers', link: '/helpers/tax' },
+          { text: 'Database Helpers', link: '/helpers/database' },
+        ]
+      },
+      {
+        text: 'Examples',
+        items: [
+          { text: 'Overview', link: '/examples/' },
+          { text: 'Create a customer', link: '/examples/customer' },
+          { text: 'Create a product', link: '/examples/product' },
+        ],
+      },
+      //{
+      //  text: 'Contributing',
+      //  items: [
+      //    { text: 'Internals', link: '/contributing/internals' },
+      //    { text: 'Contribution guide', link: '/contributing/guide' },
+      //  ]
+      //}
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/basecom/FixturesPlugin' },
+      { icon: 'instagram', link: 'https://www.instagram.com/basecom.de/?hl=en' },
+      { icon: 'linkedin', link: 'https://www.linkedin.com/company/basecom-gmbh-&-co.-kg/' },
+    ],
+
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'Copyright © 2021-2024 basecom GmbH & Co. KG'
+    },
+
+    editLink: {
+      pattern: 'https://github.com/basecom/FixturesPlugin/edit/main/docs/:path',
+      text: 'Edit this page on GitHub'
+    },
+
+    search: {
+      provider: 'local'
+    }
+  },
+  markdown: {
+    lineNumbers: true
+  }
+})

docs/.vitepress/theme/custom.css

@@ -0,0 +1,5 @@
+:root {
+    --vp-c-brand-1: #0099ff;
+    --vp-c-brand-2: #006eff;
+  }
+

docs/.vitepress/theme/index.js

@@ -0,0 +1,4 @@
+import DefaultTheme from 'vitepress/theme'
+import './custom.css'
+
+export default DefaultTheme