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

Added documentation for bulk entity extension #1543

Merged
merged 1 commit into from
Nov 29, 2024
+36 −1
Merged

Added documentation for bulk entity extension #1543

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
37 changes: 36 additions & 1 deletion ...lugins/plugins/framework/data-handling/add-complex-data-to-existing-entities.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -325,4 +325,39 @@

## Entity extension vs. Custom fields

[Custom fields](../custom-field/add-custom-field) are by default configurable by the admin user in the Administration, and they mostly support scalar types, e.g. a text-field, a number field, or the likes. If you'd like to create associations between entities, you'll need to use an entity extension, just like we did here. Of course, you can also add scalar values without an association to an entity via an extension.
[Custom fields](../custom-field/add-custom-field) are by default configurable by the admin user in the Administration, and they mostly support scalar types, e.g. a text-field, a number field, or the likes. If you'd like to create associations between entities, you'll need to use an entity extension, just like we did here. Of course, you can also add scalar values without an association to an entity via an extension.

## Bulk entity extensions
In case your project or plugin requires a lot of entity extensions, you can register also a `BulkEntityExtension` which allows to extend multiple entities at once:

Check warning on line 331 in guides/plugins/plugins/framework/data-handling/add-complex-data-to-existing-entities.md

View workflow job for this annotation

GitHub Actions / Runner 

[LanguageTool] reported by reviewdog 🐶
Did you mean “extending”? Or maybe you should add a pronoun? In active voice, ‘allow’ + ‘to’ takes an object, usually a pronoun. (ALLOW_TO[1])
Suggestions: `extending`
URL: http://www.ef.com/english-resources/english-grammar/gerund-equals-infinitive/ 
Rule: https://community.languagetool.org/rule/show/ALLOW_TO?lang=en-US&subId=1
Category: GRAMMAR

Raw Output:
guides/plugins/plugins/framework/data-handling/add-complex-data-to-existing-entities.md:331:127: Did you mean “extending”? Or maybe you should add a pronoun? In active voice, ‘allow’ + ‘to’ takes an object, usually a pronoun. (ALLOW_TO[1])
 Suggestions: `extending`
 URL: http://www.ef.com/english-resources/english-grammar/gerund-equals-infinitive/ 
 Rule: https://community.languagetool.org/rule/show/ALLOW_TO?lang=en-US&subId=1
 Category: GRAMMAR

```php

Check warning on line 333 in guides/plugins/plugins/framework/data-handling/add-complex-data-to-existing-entities.md

View workflow job for this annotation

GitHub Actions / Runner 

[LanguageTool] reported by reviewdog 🐶
File types are normally capitalized. (FILE_EXTENSIONS_CASE[1])
Suggestions: `PHP`
URL: https://languagetool.org/insights/post/spelling-capital-letters/ 
Rule: https://community.languagetool.org/rule/show/FILE_EXTENSIONS_CASE?lang=en-US&subId=1
Category: CASING

Raw Output:
guides/plugins/plugins/framework/data-handling/add-complex-data-to-existing-entities.md:333:3: File types are normally capitalized. (FILE_EXTENSIONS_CASE[1])
 Suggestions: `PHP`
 URL: https://languagetool.org/insights/post/spelling-capital-letters/ 
 Rule: https://community.languagetool.org/rule/show/FILE_EXTENSIONS_CASE?lang=en-US&subId=1
 Category: CASING
<?php

namespace Examples;

class MyBulkExtension extends BulkEntityExtension
{
public function collect(): \Generator
{
yield 'product' => [
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
yield 'product' => [
yield \Shopware\Core\Content\Product\ProductDefinition::ENTITY_NAME => [

should we encourage the usage of the constants? 🤔

Copy link
Contributor Author

@OliverSkroblin OliverSkroblin Nov 7, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see what you mean. I would document it in this way because Entities via Attributes or custom entities don't have such constants and the constant is also no "official" requirement right?
It also refer to the "definition" again, something which might be obsolete in the future

Therefore i would recommend to show it in this way i guess.

Copy link
Contributor

@JoshuaBehrens JoshuaBehrens Nov 7, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@OliverSkroblin yes and the entities via attributes are a hell without these constants! I will provide a fix soon, that allows using the AttributeEntity::class as reference. This is such a mess as this will hold us back from using it the Doctrine ORM way.

It was really difficult to find out how to extend an attribute entity >:(

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is that such a hassle? You can simply reference the table name. You don’t always have to use constants everywhere ;).

If this is important for all of you, i would recommend to add a class constant again. I would always go the way of using a simple string which make it much more readable.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fun thing. I would always go for the PHP symbol so I can ensure the "magic string" is stored on a symbol, that is affected by refactorings correctly. This helps to understand by just looking at the uses what my real-life dependencies are. I see the benefit in the simplicity at time of writing, not at time of maintaining.

new FkField('main_category_id', 'mainCategoryId', CategoryDefinition::class),
];

yield 'category' => [
new FkField('product_id', 'productId', ProductDefinition::class),
new ManyToOneAssociationField('product', 'product_id', ProductDefinition::class),
];
}
}
```

Each yield defines the entity name which should be extended and the array value defines the fields which should be added. In this example, the `product` and `category` entities got extended.

Check warning on line 354 in guides/plugins/plugins/framework/data-handling/add-complex-data-to-existing-entities.md

View workflow job for this annotation

GitHub Actions / Runner 

[LanguageTool] reported by reviewdog 🐶
Use a comma before “and” if it connects two independent clauses (unless they are closely connected and short). (COMMA_COMPOUND_SENTENCE_2[4])
Suggestions: `, and`
URL: https://languagetool.org/insights/post/types-of-sentences/#compound-sentence 
Rule: https://community.languagetool.org/rule/show/COMMA_COMPOUND_SENTENCE_2?lang=en-US&subId=4
Category: PUNCTUATION

Raw Output:
guides/plugins/plugins/framework/data-handling/add-complex-data-to-existing-entities.md:354:59: Use a comma before “and” if it connects two independent clauses (unless they are closely connected and short). (COMMA_COMPOUND_SENTENCE_2[4])
 Suggestions: `, and`
 URL: https://languagetool.org/insights/post/types-of-sentences/#compound-sentence 
 Rule: https://community.languagetool.org/rule/show/COMMA_COMPOUND_SENTENCE_2?lang=en-US&subId=4
 Category: PUNCTUATION

In this case you also just have to register a single file inside your services.xml

```
<service id="Examples\MyBulkExtension">
<tag name="shopware.bulk.entity.extension"/>
</service>
```

Loading