It has been more than four months since the release of Magento 2 and the ecosystem around Magento 2 including the extensions market place is growing at a faster pace than expected.
This blog is a summary of our experiences in developing Magento 2 extensions and the lessons learnt while doing so. If imbibed, these lessons will help extension providers and developers to avoid the issues we faced.
Creating Magento 2 Extensions – Lessons Learnt
Follow Naming Conventions
Magento 2 strictly follows file naming conventions and it is very important to know and follow them when creating file names.
For example, if you name the registration.php as Registration.php, your module will not get registered because of the wrong case used.
If you get ‘File Not Found’ error and if your module is not working as expected , check the file names first to ensure you have followed the naming conventions.
Allow Linux/Ubuntu to Read/Write Files
If you encounter an empty or a broken page, it may be because of permission issues.
Alan Storm had summed this up in one of this blogs…
If you take a close look at how Magento handles UNIX file permissions in its code generation systems, one thing is clear. The core team are not fans of Apache’s mod_php module, and probably run their systems using some sort of PHP-FPM/FastCGI implementation.
As a result, if you’re running PHP with the Apache mod_php module (the most common out of the box way of running PHP) you may end up running into problems with Magento created files. Specifically, files created via command line mode that PHP can’t read/write when running in web server mode, or vice versa.
To know more, read the blog by Alan Storm.
Before and after running any CLI commands, change the permissions (chmod 777) to allow Linux/Ubuntu to read/write the files. Else, you may encounter exception errors or end up with an empty/broken page.
Work in Developer Mode
Most of the developers often work in default mode instead of developer mode. The drawback of using default mode is that when you make changes in static files, the result might not get reflected in it.
This is because, in default mode, Magento fetches the cached static files instead of original files. To load the original file, you would have to delete /var/cache and /var/view_preprocessed folder every time.
In order to avoid that, change your mode to developer since it fetches the original static files every time irrespective of cached static files.
# php bin/magento deploy:mode:show
Displays the current mode
# php bin/magento deploy:mode:set developer
Change mode to developer
Avoid Modifying Files in the pub Folder
At times, Magento 2 beginners modify the files in the /<root folder>/pub.
The files in pub folder are cached static files. Whenever you run the CLI command to deploy the static files, the files get replaced with the original static files. So all the modifications made by you in pub folder will be lost. So avoid modifying files in the pub folder.
# bin/magento setup:static-content:deploy
Deploys static view files
Load custom js Using require.js
Magento allows developers to load jquery files by calling in layout or using require js.
Calling through layout, loads the custom.js in the page. It can be used if your custom.js is independent of any other js. The drawback is that you can’t load the js files in required order.
In case, you would like to load your custom js after any other js like jquery, it is recommended to use require.js.
First declare your js files in requirejs-config.js
And call the jquery and your custom js files before executing your script.
This will help you to load the js files in the required order. Now, custom.js will be loaded after jquery.js.
Fix Recoverable Injection Error
When you try to inject new dependency in __construct function of any controllers or models or resource models , you may encounter the below error…
Argument 1 passed to Namespace/Module/Controller/Action/Config::__construct() must be an instance of Magento/Framework/App/Action/Context
This happens because Magento 2 generates the dependency injections of the particular class and caches it in /var/generation for future implementations.
So, when you inject a new dependency, clear the /var/generation folder to make injection work.
Reusing Existing Code
Best coding practices includes reusing the code instead of coding all over again. At times, you may use the same code not knowing that it is already available on that page.
For example, Magento uses object managers to instantiate an object to access any existing or custom collections / factories.
To create an object of a collection or factory, you often end up creating new object manager as given below.
But if you have already created a context object in your constructor, it is possible to access the object manager / scope information via the context object.
By running the CLI command below, you will be able to get the dependency information for reusing objects that are already available.
# bin/magento setup:di:compile
Generates DI configuration and all non-existing interceptors and factories
Using the above command, you will be able to receive alerts for reusing the objects of factories. Also, if any errors are found, it will display them.
The above are some of the lessons that we learnt when we developed extensions for Magento 2. As always, we are happy to share our knowledge with you and shorten your learning curve.
Let us know what you think about the blog and feel free to write your comments in the box below.