Magento 2 best practice for class locations and names

Question

In Magento 1 we were used to place our classes in these directories

• Block
• Helper
• Model
• Resource

and use a simple class name without any capital letters in the middle of the name.

If we take a look at some cases in Magento 2 Core

Helpers

Location:
- \Foo\Bar\Helper
Name:
- *.php
Examples:
- \Magento\ImportExport\Helper\Report
- \Magento\Cms\Helper\Wysiwyg\Images

---

Observers

Location:
- \Foo\Bar\Observer
Name:
- *.php
- *Observer.php
Examples:
- \Magento\CustomerCustomAttributes\Observer\SalesOrderAddressAfterLoad
- \Magento\CustomerBalance\Observer\ProcessBeforeOrderPlaceObserver

---

Plugins

Location:
- \Foo\Bar\Plugin
Name:
- *.php
- *Plugin.php
Examples:
- \Magento\Catalog\Plugin\Block\Topmenu
- \Magento\PageCache\Model\App\FrontController\BuiltinPlugin
Source: http://devdocs.magento.com/guides/v2.0/extension-dev-guide/plugins.html#declaring-a-plugin

---

ConfigProvider

Location:
- \Foo\Bar\Model
Name:
- *ConfigProvider.php
Examples:
- \Magento\Tax\Model\TaxConfigProvider
- \Magento\Payment\Model\IframeConfigProvider

---

My questions are :

• If there is any good / bad / best practices for that in Magento 2 ?
• If I want to create a custom DataProvider for example what it will be ?
  • \Foo\Bar\Provider\CustomDataProvider
  • \Foo\Bar\DataProvider\Custom
  • \Foo\Bar\Model\Provider\CustomDataProvider
  • \Foo\Bar\Helper\Provider\CustomDataProvider
• How to determine the construction of the class name and location, a folder at the root of the module, in Model, in Helper, etc?
• Does it depends on retrieved data source / data type ?
• When do we have to add the suffix to the class name ?

---

A part of a response for the Virtual Types : https://community.magento.com/t5/Magento-DevBlog/Virtual-Types-Naming-Convention/ba-p/61510

Answer 1

Magento 2 is not restricted as Magento 1 to only a few folders like block, helper, model and so on.
You can basically place a class in any folder you want. It's up to you since the class are instantiated using the full class name not with aliases as in Magento 1.

My recommendation is to group them by the functionality.

• observers in Vendor/Module/Observer.
• plugins in Vendor/Module/Plugin
• data providers in Vendor/Module/DataProvider.
• ui component related classes in Vendor/Module/Ui

but try to avoid name duplication. I mean Vendor/Module/DataProvider/CustomDataProvider would be redundant.

Maybe the suffix can be added for interfaces only, although people would argue against it.

To summarize, it's up to you how you do it, just be consistent in it.

From the functionality point of view it's not important where you place the classes. You can even go crazy with them and place all of them directly in Vendor/Module folder, but you probably don't want that.

I think (but not completely sure) that the only restriction is that controllers must be in the folder Controller.

Answer 2

I think the top priority should be to make the code as self documenting as possible. So rather than putting everything into Model or Helper directories, finding a good name that describes what the code underneath does is a better approach. Of course, it's also harder because it requires a lot more thinking.

For example, rather than using Model/Config/Converter.php, the name OrderStateMachine/TransitionsConfiguration/XmlToArrayConverter.php says a lot more what a Module and a class does.

Answer 3

I reckon it's opinion based but I agree that there are some inconsistencies regarding class naming and locations in M2.

Here's the list I came up with regarding folder naming. To me you should always use those folders when you can in order to make your module easier to browse and understand for anyone else:

• Block
• Controller
• Model
• Observer
• Setup
• Test
• Ui
• etc
• i18n
• view
• Cron
• Helper
• Console
• Api
• Plugin
• DataProvider

On top of that, M2 uses some very specific folders but I haven't included them in this list:

• Pricing
• App
• CustomerData
• Service
• Gateway
• Files
• Adapter
• Component
• TemplateEngine

The good thing with M2 is that you can use and create whatever folder you need. If something does not belong in the list above, create your own folder and put your classes in them just try to be consistent.

Answer 4

There are already some really good answers above. What I would like to add is that you should avoid placing code under app/code and instead use a composer based installation method which will end up placing your code under vendor/.