Plugin development guide v1.0 #9592
Conversation
Zales0123
changed the title
Zales0123
added
the
Documentation
|
I'd replace the entire "Plugins" part of docs with "Plugin Development Guide" and make it a first-level element, like the book. The "Creating plugin" doc could be first or second step of the guide. |
|
|
||
| .. important:: | ||
|
|
||
| Of course you need to remember about entity mapping customization as well. |
There was a problem hiding this comment.
I think we should add example here, it will be really simple but important and easy to miss if you are new to Sylius.
| classes: | ||
| model: IronMan\SyliusProductOnDemandPlugin\Entity\ProductVariant | ||
|
|
||
| This configuration should be placed in ``src/Resources/config/config.yml``. It also has to be imported |
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
| } | ||
| } | ||
|
|
||
| Translation keys placed in ``src/Resources/translations/message.{locale}.yml`` will be resolved automatically. |
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
There was a problem hiding this comment.
Example or link to example?
|
|
||
| .. code-block:: yaml | ||
|
|
||
| services: |
There was a problem hiding this comment.
I think these services should be inside of the plugin not the test app. Because you want to load them automatically and not define for each app manually.
There was a problem hiding this comment.
totally agreed, I was thinking about src/Resources/config/services.yml, it's a typo 😄
| * by writing a theme | ||
|
|
||
| For the needs of this tutorial, we would go the first way. What's crucial, we need to determine which template should be overwritten. | ||
| Naming for twig files in Sylius, both in **Shop** and **AdminBundle** are pretty clear and straightforward. In this specific case, |
There was a problem hiding this comment.
Inconsistency, one has a suffix (Bundle) and the other does not.
|
|
||
| * ``src/Controller/GreetingController.php`` | ||
|
|
||
| * ``src/Resources/config/admin_routing.yml`` |
There was a problem hiding this comment.
I'd recommend src/Resources/config/routing/admin.yml.
There was a problem hiding this comment.
So it needs to be changed in PluginSkeleton, as it's about removing this file :)
| .. image:: ../../_images/product_variant_available_on_demand.png | ||
| :align: center | ||
|
|
||
| What's next? |
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
| -------------- | ||
|
|
||
| The goal of our plugin is simple - we need to extend ``ProductVariant`` entity and provide new flag, that could be set | ||
| on product variant form. Following customizations uses information provided in **Sylius Customization Guide**, especially |
There was a problem hiding this comment.
Following customization uses... or Following customizations use...
|
|
||
| then don't be afraid to make a regular Sylius customization. | ||
|
|
||
| For needs of this tutorial, we would implement a simple plugin, making possible to mark product variant **available on demand**. |
There was a problem hiding this comment.
And could we make an info box out of this information?
| Model | ||
| ***** | ||
|
|
||
| The only field we need to add is additional ``$availableOnDemand`` boolean. Of course we should start with the unit tests (written with |
|
|
||
| .. code-block:: yaml | ||
|
|
||
| sylius_product: |
There was a problem hiding this comment.
In other dosc we are using a comment indicting in which file are we adding stuff, wdyt about doing it everywhere in this tutorial also?
| .. warning:: | ||
|
|
||
| Remember that if you modify or add some mapping, you should either provide a migration for the plugin user (that could be | ||
| copied to their migration folder) or mention in installation process requirement of migration generation! |
There was a problem hiding this comment.
mention the requirement of migration generation in the installation process!
| .. note:: | ||
|
|
||
| Remember about naming convention! Sylius plugin should start with your vendor name, followed by ``Sylius`` prefix and with ``Plugin`` suffix at the end. | ||
| Let's say your vendor name is **IronMan** |
There was a problem hiding this comment.
Missing dot ;)
I'd add sth like
Come on **IronMan**, let's create your plugin! 🎉
|
|
||
| You **don't** have to remove all these files mentioned above. They can be adapted to suit your plugin functionality. However, as | ||
| they provide a default, dummy features only for the presentation reasons, it's just easier to delete them and implement new ones by | ||
| your own. |
| Then I should be notified that it has been successfully edited | ||
| And this variant should be available on demand | ||
|
|
||
| What is really important, usually you don't need to write the whole Behat scenario on your own! In the example above only 2 steps |
There was a problem hiding this comment.
you don't need to write the whole Behat scenario on your own! - well actually, you do. You just don;t need to implement all these steps you've written :D
| .. important:: | ||
|
|
||
| If you're not familiar with our BDD workflow, with Behat, take a look at | ||
| :doc:`our BDD guide</bdd/index>`. All Behat configuration (contexts, pages, services, suites etc.) are explained |
There was a problem hiding this comment.
configuration -> configurations
or All -> Whole
| } | ||
| } | ||
|
|
||
| First step is done - we have a failing test, that would be green when we implement a desired functionality. |
There was a problem hiding this comment.
that is going to go green ?
| @@ -0,0 +1,59 @@ | |||
| Naming changes | |||
There was a problem hiding this comment.
Just a general thought: it would be great to have some way to achieve it automatically (e.g. only pass your vendor plus plugin name and it would rename all the things and delete exemplary stuff).
There was a problem hiding this comment.
Totally agreed 👍 However right now it has to be done manually, so I'm documenting it anyway
|
@pjedrzejewski I agree that the "plugins" section can be a little bit restructured. I would personally leave the separate "creating plugin" chapter, as it only explains a few simple steps how to start with plugin development, not involving the whole big tutorial. However, I would leave it as it is for now, as this PR already provides plenty of lines to review - we could make these rearrangements a little bit later in one, simple, tiny PR :) |
|
Dear @Zales0123! I'm really impressed with your work. Just found a sec to read it and it's so clear and simple that I'm keen on creating a plugin, even though I've never written a single line of code. Keep on rocking! 💃 #goodvibes |
| Summary | ||
| ------- | ||
|
|
||
| Congratulations! You've created your first, fully tested and documented, customization to Sylius inside a Sylius plugin! |
| Naming changes | ||
| -------------- | ||
|
|
||
| ``PluginSkeleton`` provides some default classes and configurations. However, they must have some default values and names that should be changed, |
There was a problem hiding this comment.
Although the whole text is very well-written, I'm pretty sure that a comma after changed is unnecessary :D
| ------- | ||
|
|
||
| Congratulations! You've created your first, fully tested and documented, customization to Sylius inside a Sylius plugin! | ||
| As you can see, there are some things to do at the beginning of development, but know, when you are already familiar with |
|
|
||
| Congratulations! You've created your first, fully tested and documented, customization to Sylius inside a Sylius plugin! | ||
| As you can see, there are some things to do at the beginning of development, but know, when you are already familiar with | ||
| the whole structure, each next feature can be provided faster than the previous one. |
There was a problem hiding this comment.
can be delivered faster than the previous ones ?
| customizing the whole :doc:`order processing</components_and_bundles/bundles/SyliusOrderBundle/processors>` and :doc:`inventory operations</components_and_bundles/bundles/SyliusInventoryBundle/services>` | ||
|
|
||
| and even more. The limit is only your imagination (and business value, of course!), for more inspiration, we strongly recommend | ||
| our :doc:`customizing guide</customization/index>`. |
There was a problem hiding this comment.
The limit is only your imagination (and business value, of course!). For more inspiration, we strongly recommend...
?
|
|
||
| .. important:: | ||
|
|
||
| If you're not familiar with our BDD workflow, with Behat, take a look at |
There was a problem hiding this comment.
If you're not familiar with our BDD workflow with Behat, [...]
Unnecessary comma
|
Now that's a piece of outstanding work! 🥇 |
Zales0123
force-pushed
the
plugin-development-guide
branch
from
12e464f
to
da0c077
Compare
| -------------- | ||
|
|
||
| The goal of our plugin is simple - we need to extend ``ProductVariant`` entity and provide new flag, that could be set | ||
| on product variant form. Following customizations use information provided in **Sylius Customization Guide**, especially |
There was a problem hiding this comment.
Following customizations are done just like in the **Sylius Customization Guide**, take a look at :doc:`customizing models</customization/model>`, :doc:`form</customization/form>` and :doc:`template</customization/template>`.
|
|
||
| ``PluginSkeleton`` is focused on delivering the most friendly and testable environment. That's why in ``tests/Application`` directory, | ||
| there is a **tiny Sylius application** placed, with your plugin already used. Thanks to that, you can test your plugin with Behat scenarios | ||
| **within** Sylius application without installing it to any test app manually! There is, however, one important consequence of such an architecture. |
There was a problem hiding this comment.
why bold on within? and Everything below? :D
There was a problem hiding this comment.
To note about an awesome feature (you can test plugin in the application without installing it into the application 🎉) and make reader 100% aware about the need of copying everything that is needed to the test application :)
| type: boolean | ||
| nullable: true | ||
|
|
||
| Then our new entity should be configured as sylius product variant resource model: |
There was a problem hiding this comment.
Then our new entity should be configured as a resource model:
| .. warning:: | ||
|
|
||
| Remember that if you modify or add some mapping, you should either provide a migration for the plugin user (that could be | ||
| copied to their migration folder) or mention the requirement of migration generation in the installation process! |
There was a problem hiding this comment.
installation process -> installation instructions?
|
|
||
| * ``Tests\\Acme\\SyliusExamplePlugin\\`` -> ``Tests\\IronMan\\SyliusProductOnDemandPlugin\\`` (the same changes should be done in namespaces in ``tests/`` directory | ||
|
|
||
| * ``AcmeSyliusExamplePlugin`` should be renamed to ``IronManSyliusProductOnDemandPlugin`` |
There was a problem hiding this comment.
why some of these points are tabbed and some are not?
There was a problem hiding this comment.
Some of them are sub-points for other points (e.g. "In composer.json" have few of them, as there are few things that need to be changed in composer.json file)
|
|
||
| That's it! All other files are just a boilerplate to show you what can be done in the Sylius plugin. They can be deleted with no harm. | ||
|
|
||
| * All files from ``features/`` directory |
There was a problem hiding this comment.
To point out every file that should be removed
|
|
||
| .. important:: | ||
|
|
||
| You **don't** have to remove all these files mentioned above. They can be adapted to suit your plugin functionality. However, as |
| .. important:: | ||
|
|
||
| You **don't** have to remove all these files mentioned above. They can be adapted to suit your plugin functionality. However, as | ||
| they provide a default, dummy features only for the presentation reasons, it's just easier to delete them and implement new ones on |
| And this variant should be available on demand | ||
|
|
||
| What is really important, usually you don't need to implement the whole Behat scenario on your own! In the example above only 2 steps | ||
| would need a custom implementation. Rest of them can be easily reused from **Sylius** Behat system. |
There was a problem hiding this comment.
Behat system? or rather Behat suite?
| As a result, you should see a new field in product variant form: | ||
|
|
||
| .. image:: ../../_images/product_variant_available_on_demand.png | ||
| :align: center |
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
Zales0123
force-pushed
the
plugin-development-guide
branch
from
da0c077
to
8e44c16
Compare
|
|
||
| .. tip:: | ||
|
|
||
| For needs of this tutorial, we will implement a simple plugin, making possible to mark product variant **available on demand**. |
There was a problem hiding this comment.
For the purpose of this tutorial, we will implement a simple plugin: making it possible to mark a product variant **available on demand**.
| Implementation | ||
| -------------- | ||
|
|
||
| The goal of our plugin is simple - we need to extend ``ProductVariant`` entity and provide new flag, that could be set |
There was a problem hiding this comment.
we need to extend the ProductVariant entity
There was a problem hiding this comment.
and provide a new flag
that could be set on the product variant form
| Model | ||
| ***** | ||
|
|
||
| The only field we need to add is an additional ``$availableOnDemand`` boolean. Of course we should start with the unit tests (written with |
There was a problem hiding this comment.
Not sure it's good to use of course in tutorials - same as words like simply, just do, just add, etc. These actions are not familiar to everyone yet and might require a link or additional explanation.
|
Nice guide! :-) |
| ***** | ||
|
|
||
| The only field we need to add is an additional ``$availableOnDemand`` boolean. We should start with the unit tests (written with | ||
| PHPSpec/PHPUnit/any other unit testing tool): |
There was a problem hiding this comment.
"PHPSpec, PHPUnit or any other...?" would prevent us from having onelongwordwithoutspaces. :)
|
|
||
| use Sylius\Component\Core\Model\ProductVariant as BaseProductVariant; | ||
|
|
||
| class ProductVariant extends BaseProductVariant implements ProductVariantInterface |
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
| class ProductVariant extends BaseProductVariant implements ProductVariantInterface | ||
| { | ||
| /** @var bool */ | ||
| private $availableOnDemand; |
There was a problem hiding this comment.
What do you think about providing a default value for this property and removing nullable typehints? I think it makes sense for a boolean.
|
|
||
| * ``Acme\SyliusExamplePlugin`` -> ``IronMan\SyliusProductOnDemandPlugin`` | ||
|
|
||
| That's it! All other files are just a boilerplate to show you what can be done in the Sylius plugin. They can be deleted with no harm. |
There was a problem hiding this comment.
"They can be deleted with no harm." -> "They can be deleted with no harm:" in order to indicate, that the list below is directly connected with this sentence?
| and even more. The limit is only your imagination (and business value, of course!). For more inspiration, we strongly recommend | ||
| our :doc:`customizing guide</customization/index>`. | ||
|
|
||
| At the end, do not hesitate to contact us on contact@sylius.com when you manage to implement a new plugin. We would be happy to check it out |
| our :doc:`customizing guide</customization/index>`. | ||
|
|
||
| At the end, do not hesitate to contact us on contact@sylius.com when you manage to implement a new plugin. We would be happy to check it out | ||
| and add it to our `official plugins list`_! |
There was a problem hiding this comment.
We should mention, that the plugin needs to be high-quality (with tests etc.) in order to be in our official plugins list.
Zales0123
force-pushed
the
plugin-development-guide
branch
from
fd7fc9b
to
79df1b0
Compare
|
Thank you, Mateusz! 🎉 |
This is the first version of a new Plugin Development Guide - providing the simplest, fastest and the most explained way to create a new Sylius Plugin. I would like to see your opinion, what is missing, what is incomplete, what is not necessary. The implementation works, I've been checking it during writing the guide 😄