Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Prepare release v3 #70

Merged
merged 1 commit into from
Jun 17, 2024
Merged

Prepare release v3 #70

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
161 changes: 11 additions & 150 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
<service id="MyNamespace\Fixtures\Customer\CustomerFixture">
<argument type="service" id="Basecom\FixturePlugin\FixtureHelper"/>
<argument type="service" id="customer.repository"/>
<tag name="basecom.fixture"/>
</service>
```


## 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 <name>

# 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 <name>

# 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 <name>
```


## 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).

Expand Down
126 changes: 1 addition & 125 deletions UPGRADE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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!
See the [offical upgrade guide](https://basecom.github.io/FixturesPlugin/upgrade.html)
46 changes: 0 additions & 46 deletions _examples/CategoryFixture.php
View file
Open in desktop

This file was deleted.

Loading