From c7ef644e1d45ff33b6088aedab0062dc8e3f315f Mon Sep 17 00:00:00 2001 From: Jordan Kniest Date: Mon, 17 Jun 2024 17:04:05 +0200 Subject: [PATCH] Prepare release v3 (#70) --- CHANGELOG.md | 3 +- README.md | 161 +++------------------------------- UPGRADE.md | 126 +------------------------- _examples/CategoryFixture.php | 46 ---------- _examples/CustomerFixture.php | 49 ----------- _examples/ProductFixture.php | 78 ---------------- 6 files changed, 14 insertions(+), 449 deletions(-) delete mode 100644 _examples/CategoryFixture.php delete mode 100644 _examples/CustomerFixture.php delete mode 100644 _examples/ProductFixture.php diff --git a/CHANGELOG.md b/CHANGELOG.md index 3525604..891dee5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## Unreleased +## [3.0.0] - 2024-06-17 ### Added - Added support for PHP 8.3 - Added support for Shopware 6.6 @@ -173,6 +173,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `getNotSpecifiedSalutationId` - `getGermanCountryId` +[3.0.0]: https://github.com/basecom/FixturesPlugin/compare/2.4.0...3.0.0 [2.4.0]: https://github.com/basecom/FixturesPlugin/compare/2.3.0...2.4.0 [2.3.0]: https://github.com/basecom/FixturesPlugin/compare/2.2.1...2.3.0 [2.2.1]: https://github.com/basecom/FixturesPlugin/compare/2.2.0...2.2.1 diff --git a/README.md b/README.md index be0f34c..f0d2dc7 100644 --- a/README.md +++ b/README.md @@ -1,165 +1,26 @@ # Fixture Plugin -The fixture plugin is really helpful if you want to create some static demo data for your shopware instance. +The FixturePlugin for Shopware 6 offers convenient commands and structures to create and manage fixtures for your shop project or plugin. -## Installation +## [Documentation](https://basecom.github.io/FixturesPlugin/getting-started.html) -Just add it to your project via composer: +Please see the [official documentation](https://basecom.github.io/FixturesPlugin/getting-started.html) to see how to get started! -```shell -composer require basecom/sw6-fixtures-plugin -``` +## Installation -Afterwards you can install the plugin, like any other Shopware Plugin using the administration or console command: +You can easily install the plugin via Composer in any existing Shopware shop: ```shell -./bin/console plugin:install --activate BasecomFixturePlugin -``` - -## PHP & Shopware compatibility -Please use the following table to check which version can be used for your PHP and shopware version - -| Shopware Version | PHP Versions | Newest FixturePlugin version | Supported | -|------------------|--------------|------------------------------|-----------| -| 6.6.* | v8.2, v8.3 | v3.0.* | ✅ | -| 6.5.* | v8.2, v8.3 | v3.0.* | ✅ | -| 6.5.* | v8.1 | v2.0.* | ❌ | -| 6.4.* | v8.1, v8.2 | v2.0.* | ❌ | -| 6.3.* | v8.1, v8.2 | v2.0.* | ❌ | - -## Create Fixtures - -### Basic Fixture -Create a new file in the specific folder of your project for the fixtures and extend this file from abstract class "**Fixture**" in the library. - -Then just implement the "**load()**" method with fixture logic. - -```php -class CustomerFixture extends Fixture -{ - /** - * @param FixtureBag $bag - * @return void - */ - public function load(FixtureBag $bag): void - { - // custom code - } -} -``` - -### Priority and Dependency -You can also add an optional priority or dependency of other Fixture classes via the corresponding "**dependsOn()**" or "**priority()**" method. - -```php -public function priority(): int -{ - return 0; -} -``` - - -### Groups -If you want to run specific fixtures as a group later, implement the "**groups()**" method from the abstact class and return an array of strings as group names. - -```php -/** @return string[] */ -public function groups(): array -{ - return []; -} -``` - - -## Register Fixtures -If you're using service autowiring, then nothing needs to be done to register your fixtures. -If you're not using autowiring, then please register your fixtures with the tag `basecom.fixture`. - - -```xml - - - - - -``` - - -## Running Fixtures - -### Run all fixtures -To run all registered fixtures, just use this command. -```bash -bin/console fixture:load -``` - -### Run single fixture -To run a single fixture, use this command with your fixture name as parameter. - -```bash -bin/console fixture:load:single - -# fixture class is named "DummyFixture.php", (it´s case-insensitive) -bin/console fixture:load:single dummyFixture -``` - -By default, if you run a single fixture it will ignore all its dependencies. If you want to run the single fixture, -including all dependencies recursively, use the `--with-dependencies` option. - -```bash -bin/console fixture:load:single --with-dependencies - -# fixture class is named "DummyFixture.php", (it´s case-insensitive) -bin/console fixture:load:single --with-dependencies dummyFixture -``` - -### Run group -To run a group of fixture, run this command with group name as parameter (specified via **groups()** method). It´s also case-insensitive. - -```bash -bin/console fixture:load:group -``` - - -## Best Practices - -### Plugin Development -When you want to add fixtures to a plugin that you build, you might not want to deliver these fixtures in a production version of your plugin. -In this case, we only want to add it to the "development" or "testing" scope of our plugin. - -Create a new folder for your fixtures in a folder that is not your source folder that is delivered. -You could use your "tests" folder for instance. - -We then use the Shopware `build()` function of our main `Plugin` class to add the code below. -This code will verify if our DEV dependencies from our composer dependencies are installed (just use any check like, is PHPUnit existing?...). -Once it recognizes that DEV requirements are installed, we verify that our fixtures directory also exists, and then simply load -those files with our correct namespace in our class loader. -Afterwards we also load our custom XML services for our fixtures. - -With this approach, the `bin/console` command of this FixturePlugin will only find fixtures, if dev-dependencies are installed in our plugin that we develop. -If only production dependencies are installed, nothing is found and therefore no fixtures are (accidentally) loaded. - -```php -# use any of your dev-dependencies as "indicator" -$composerDevReqsInstalled = file_exists(__DIR__ . '/../../vendor/bin/phpunit'); - -if ($composerDevReqsInstalled) { - - $dirFixtures = __DIR__ . '/../../tests/Fixtures'; - - if (is_dir($dirFixtures)) { - $classLoader = new ClassLoader(); - $classLoader->addPsr4("MyNamespace\\Fixtures\\", $dirFixtures, true); - $classLoader->register(); +# Install the plugin via Composer +composer require basecom/sw6-fixtures-plugin - $loader->load('services/fixtures/fixtures.xml'); - } -} +# Refresh the plugin list and install/activate the plugin +bin/console plugin:refresh +bin/console plugin:install --activate BasecomFixturePlugin ``` - ## Contribution -This template uses a full-featured Dockware docker image. It already comes with a pre-installed Shopware 6 instance and everything you need to start developing. +This plugin uses a full-featured Dockware docker image. It already comes with a pre-installed Shopware 6 instance and everything you need to start developing. Please see the [Dockware documentation](https://dockware.io/docs). diff --git a/UPGRADE.md b/UPGRADE.md index 757cbc4..bef5d05 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -1,127 +1,3 @@ # 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 - -### Helper methods have been split -Instead of calling the helper methods like `$helper->getInvoicePaymentMethod()`, you now need to call the -sub util class: `$helper->PaymentMethod()->getInvoicePaymentMethod()`. - -The following util classes have been added: -```php -$fixtureHelper->Media() -$fixtureHelper->Category() -$fixtureHelper->SalesChannel() -$fixtureHelper->Customer() -$fixtureHelper->Cms() -$fixtureHelper->PaymentMethod() -$fixtureHelper->ShippingMethod() -``` - -**Info:** We haven't removed any helper methods in this release. We only moved them! \ No newline at end of file +See the [offical upgrade guide](https://basecom.github.io/FixturesPlugin/upgrade.html) diff --git a/_examples/CategoryFixture.php b/_examples/CategoryFixture.php deleted file mode 100644 index bd0a887..0000000 --- a/_examples/CategoryFixture.php +++ /dev/null @@ -1,46 +0,0 @@ -helper = $helper; - $this->categoryRepository = $categoryRepository; - } - - public function load(FixtureBag $bag): void - { - $this->categoryRepository->upsert([ - [ - 'id' => '0d8eefdd6d12456335280e2ff42431b9', - 'translations' => [ - 'de-DE' => [ - 'name' => 'Gutscheine', - ], - 'en-GB' => [ - 'name' => 'Voucher', - ], - ], - 'productAssignmentType' => 'product', - 'level' => 2, - 'active' => true, - 'displayNestedProducts' => true, - 'visible' => true, - 'type' => 'page', - 'cmsPageId' => $this->helper->Cms()->getDefaultCategoryLayout()->getId(), - 'afterCategoryId' => null, - 'parentId' => $this->helper->Category()->getByName('Catalogue #1')->getId(), - ], - ], Context::createDefaultContext()); - } -} diff --git a/_examples/CustomerFixture.php b/_examples/CustomerFixture.php deleted file mode 100644 index e615393..0000000 --- a/_examples/CustomerFixture.php +++ /dev/null @@ -1,49 +0,0 @@ -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(), - 'defaultBillingAddress' => [ - 'id' => self::ADDRESS_ID, - 'salutationId' => $this->helper->Salutation()->getNotSpecifiedSalutation()?->getId(), - 'firstName' => 'Zoey', - 'lastName' => 'Smith', - 'zipcode' => '1234', - 'street' => 'Sample Street', - 'city' => 'Berlin', - 'countryId' => $this->helper->LanguageAndLocale()->getCountry('DE')?->getId(), - ], - 'defaultShippingAddressId' => self::ADDRESS_ID, - 'salutationId' => $this->helper->Salutation()->getNotSpecifiedSalutation()?->getId(), - 'customerNumber' => '1122', - 'firstName' => 'Zoey', - 'lastName' => 'Smith', - 'email' => 'test@shopware.dev', - 'password' => 'notset', - ]], Context::createDefaultContext()); - } -} diff --git a/_examples/ProductFixture.php b/_examples/ProductFixture.php deleted file mode 100644 index b4e87ff..0000000 --- a/_examples/ProductFixture.php +++ /dev/null @@ -1,78 +0,0 @@ -helper = $helper; - $this->repoProducts = $repoProducts; - } - - public function load(FixtureBag $bag): void - { - $this->helper->Media()->upload( - self::MEDIA_ID, - $this->helper->Media()->getDefaultFolder('product')->getId(), - __DIR__.'/Assets/subscription-product.png', - 'png', - 'image/png', - ); - - $this->repoProducts->upsert([ - [ - 'id' => self::PRODUCT_ID, - 'name' => 'Subscription Product', - 'taxId' => $this->helper->SalesChannel()->getTax19()->getId(), - 'productNumber' => 'SUB-123', - 'description' => 'Subscription Product for testing purpose in development environment.', - 'visibilities' => [ - [ - 'id' => '0d8fffdd6d33436353580e2ad42431b9', - 'salesChannelId' => $this->helper->SalesChannel()->getStorefrontSalesChannel()->getId(), - 'visibility' => 30, - ], - ], - 'categories' => [ - [ - 'id' => $this->helper->Category()->getByName('Clothing')->getId(), - ], - ], - 'stock' => 10, - 'price' => [ - [ - 'currencyId' => $this->helper->SalesChannel()->getCurrencyEuro()->getId(), - 'gross' => 19.99, - 'net' => 16.80, - 'linked' => true, - ], - ], - 'customFields' => [ - 'my_field_abc' => true, - ], - 'media' => [ - [ - 'id' => self::COVER_ID, - 'mediaId' => self::MEDIA_ID, - ], - ], - 'coverId' => self::COVER_ID, - ], - ], - Context::createDefaultContext() - ); - } -}