Creating software for Magento as separate modules brings several advantages. First of all, it gives the possibility of using it in another project. But will we do it successfully? If we were to give it to a friend, will he be back after five minutes saying, “Look, something’s not working” – it depends only on us. I would like to present a few tips that you may or may not know, which are worth taking into account while creating your first re-usable Magento module.
1. Do not hardcode any values in the code that may change in the future.
Such values are characterized by the fact that, after some time, programmers have trouble remembering what that value meant in the past. If we already assume that some parameters are to remain unchanged, create constants in the model class. With this method, when changing a parameter, simply change the value in the definition of the constant and all references to it will continue to work. However, the best solution will be the possibility to define the value of a parameter in the system configuration using the admin panel. This allows us to adapt the module to work on another system, without any changes in the code. However, to avoid errors caused by the lack of a defined value (e.g. Right after the deployment onto a production server) we should always define the default values for these fields. Magento gives us this opportunity to use the default section in the configuration files of the modules. Here is a sample XML for the field that defines the time when the product is treated as a newly added one. This field is located in the configuration in the directory section, “block” “store on the customer’s side”.
2. Do not use any custom modules in your own code.
A situation may happen, where in one project we installed an extra module bought for big cash. When writing code, we use it often, because it’s easy and it will work for sure. Remember however, that the second project doesn’t necessarily has to have it. Such dependence on a module can ruin the career of our plug-in right at the start. Of course we can use core modules, because they will certainly be present in every project based on the same version of Magento. Each module can be turned off, that’s why we should remember about the so-called “dependencies” in the module configuration files.
3. Nomenclature – each method should be a verb and should specify the operation it performs.
However, don’t overdo it by giving them lengthy names. You should also avoid naming the variables too short such as ‘$ret’, ‘$ob’ or ‘$a’ over which someone, who doesn’t know our customs will wonder. In a strong typed programming languages it’s much easier because at least we know what type a given variable is, but in PHP we can’t do it without debugging or “throwing out” variables to the browser screen. It’s worth noting that declaring the types of variables in PHP is very possible, however, hardly anyone does it, because PHP doesn’t require it. Also remember, that in the era of globalization the world’s leading language is English, so we should always try and use it.
4. We shouldn’t use complex syntax.
At a certain stage of coding, there always comes the moment when we have to decide whether to perform operation A or B. You can’t carry the weight of decision-making onto a different method forever. In such situations, we should always keep in mind not to build huge conditional statements which are nested several times within themselves. If our decision-making mechanism suspiciously begins to grow, you could most likely refactor this code. Such ‘spaghetti code’ isn’t worth leaving, because it’s very likely that in a few months, when we change something in it, we’ll ask ourselves: “Did I really write it? What is it that I wanted to write”. When coding, you should also adopt a certain coding convention and stick to it consistently. Both Zend and Magento provide guides on accepted coding standards.
5. If, for some reason, we are forced to create some twisted logic or any other hacks, we should create comments to the code.
Such comments should be useful not only for you, but also for someone, who will work with this code in the future, so keep them as understandable as possible. Just as it is with naming variables and methods, if you are able to use a coherent language, use English.
6. Use the MVC pattern.
I’m not going to quote the definition, because everyone, who works in Magento knows it, and everyone also knows that Magento MVC is a little different from the standard. Namely, in addition to the views, models, controllers and helpers we have also blocks, which together with the layout and templates, make up the view of the application layer. So the letter ‘V’ in Magento has its own small MVC. What logic should be in the block? Generally speaking, the block takes over a part of the model’s responsibilities, which means that the block should collect data, prepare it if needed, and pass them to the template. We can also put aliases methods in blocks, just like in helpers, which don’t do anything except for calling another method, and thanks to the fact that they wrap up complex syntax in an elegant way, making use of them in the template has a positive effect on the readability of the code.
7. Don’t use short tags in PHTML templates.
When even PHP developers discourage anyone from doing this, you should know that something’s going on …;). Short tags will be removed in future versions of PHP so you can connect the dots:)
8. Always validate the data that we can take from the user.
We must always be aware of the fact that not every user has good intentions, and sometimes instead of politely filling out the form, he will give us a piece of code that could seriously mess up in our database, if it’s not properly secured. Where the data validation should be then ? – in the model layer. Magento has Zend libraries used for validating data, which are great for this type of task.
9. Don’t use Magento rewrite mechanism.
Certain classes often require the addition of an extra logic. In that case we could probably use the rewrite mechanism to overwrite parent class. But what if the project has another module, which also overwrites the same class? If we don’t tell it to inherit from our class, or our class doesn’t inherit after the first one, it’s guaranteed that any class will fall out of circulation. A much safer method (although not necessarily easier) is to use the Magento events mechanism to make changes in the operation of objects. Let’s suppose you want to add a new column to the product grid in the admin panel. Using the events mechanism we should prepare the Observer class, which include one method that will be a callback after colletion is prepared (to join the new data), and the second method, that will be called after the displaying of the form (in order to insert an additional column for the previously added data to the collection).
10. Create a functional documentation for the modules.
Even if you have an Eidetic memory, you should always write down all the information concerning the module: how to configure it, what are the dependencies on other modules, what are the deviations from the conventions and simply, what does it do. Thanks to this we’ll save our time because we don’t have to explain how does it work, and the eager one’s won’t have to look for us in the ever expanding office :) Of course in this optimistic scenario, our module is already in the repository, and anyone interested has access to it.
Surely, there would be still a lot of rules and tips to be found, and each of us has probably his own programming credo, which guides him. Therefore, ask questions, exchange experience and discuss problems and solutions that arise during work. I guarantee you that you’ll profit from it. So today, ask the person sitting next to you, what is the most important thing when creating your own re-usable module. Who knows, maybe you’ll learn something new?
Interested in Magento implementation? Let’s get in touch.
Published March 23, 2015
