This is part of a series on Magento Best Practices. Click here to read more.
Magento is a big application. There are tens of thousands of files and directories to navigate when developing for the platform. It can be very overwhelming in the beginning. It can also be very confusing knowing where to put your own custom files. This article helps you know where to place your files and why they should be placed there.
The principles to follow are:
- Place PHP Libraries in Appropriate Folders
- Namespace Your Folders
- Namespace Class Rewrites
- Use the Var Folder Correctly
- Leverage The Shell Directory
So, what’s the difference? An example of the difference would be a banner slider on your home page. You leveraged the JQuery library to write a banner slider script. JQuery would belong inside the js/ folder, and the script you wrote to create the slider functionality would belong inside the skin/ folder.
An easy rule to follow is: “If your team didn’t write it, it usually belongs in the js/ folder.”
Place PHP Libraries in Appropriate Folders
There is another rule of libraries. If you have common code shared among multiple modules, (such as APIs), you can place those inside of the lib/ folder, making it easier to manage dependencies among modules.
For example, lets say you have an integration API to your ERP. You need it for multiple modules. You can create a library for the ERP API that other modules can leverage.
Namespace Your Folders
Whenever you are placing files of different sorts among the Magento application, it is important to place these files inside a namespaced subdirectory. This applies whenever you are placing files in folders that are also shared among the Magento core. Examples of this would be the var/, media/ and js/ folders. This helps avoid naming conflicts in these folders.
An example would be the var/import folder. It is very common to create order import functionality. All too often, modules name their csv files very generic names, (such as orders.csv). If you place your files in the same folders as other modules, you run the risk of overwriting or conflicting with other modules. So, instead of just placing orders.csv inside of var/import, place it in var/import/namespace instead.
Namespace Class Rewrites
Another area where you should use appropriate namespacing is whenever you rewrite classes of other modules. This makes it much easier to manage rewritten classes. You can tell immediately where your rewritten module classes belong.
A simple example would be rewriting helper classes. Many modules have a Data.php helper class. If you need to rewrite the base helper of multiple modules, you will have a naming conflict unless you separate them into multiple subdirectories.
app/code/local/Namespace/Module/Helper/Data.php // base helper for my module
app/code/local/Namespace/Module/Helper/Catalog/Data.php // rewritten catalog helper
app/code/local/Namespace/Module/Helper/Cms/Data.php // rewritten cms helper
// and so on...
Use the Var Folder Correctly
All to often, this seems to be a confusing folder for many developers. Leveraged like the linux var/ directory, this folder contains all data that is specific to your particular installation. You’ll see subdirectories such as var/cache, var/log, var/import, etc.
This folder should not contain any sort critical data for your application to run. Meaning the moment you are about to commit something from the var/ folder into version control, STOP. This folder is meant for dynamically generated data that is intended to have a limited lifespan. Files like temp files, log files, cache files, lock files are good examples.
A good rule for the var/ folder is: “This folder can be deleted at any point, and the application should still be able to run. “
Leverage The Shell Directory
Many times, developers write command line scripts to be executed on cron, or on demand when they are inside the console. Many times, they write a php script, place it in the root directory, and attach to the cron. What many developers do not know is that Magento gives them two different means to create console scripts.
The first method is via standard Magento Cron Jobs, that they can attach to their Magento modules. You can create cron jobs that are handled by the Magento Cron.
The second method is via the shell/ directory. You can create scripts that let you run scripts via the command line. You can even leverage the shell abstract class already provided by Magento. It is located in the shell/abstract.php file. It will bootstrap the Magento runtime for you, so all you have to do is write your customization. Writing shell scripts is beyond the scope of this article, but take a look at this file and others in this folder to get an idea of what to do.
In conclusion, Magento is a big application. It can be very confusing in the beginning to know what goes where. With a little practice, you will learn exactly where to place your files for maximum flexibility and organization.