Introduction
N98-Magerun (http://magerun.net/) is an essential tool for all Magento developers. It was developed and provided free of charge by netz98.de and it provides you with a simple to use Command Line Interface (CLI) tool that can work with your Magento instance. By using a CLI tool we are able to easily use N98-Magerun on any local or remote installation of Magento.
It’s fairly common for a Magento developer to know about N98-Magerun, but most developers haven’t taken the time to become familiar with it. This is probably because they do not see the value of learning yet another set of commands. This is usually due to the developer not fully understanding what benefits this set of commands provides. That being said, I feel that if you give N98-Magerun a try, you will most certainly find ways to automate and speed up your current process.
Installation
Getting started with N98-Magerun’s installation is very simple. Head on over to their GitHub page and look at the most recent installation notes.
Most users may install the tool by following these steps (this is typically installed on the same machine as the Magento installation that the tool will be operating on):
# Download the tool wget https://files.magerun.net/n98-magerun.phar # Set permissions to executable chmod +x ./n98-magerun.phar # Copy to a PATH folder to make this easily executable sudo cp ./n98-magerun.phar /usr/local/bin/
For those of you looking to automate the process I have provided a simple bash script to install N98-Magerun here.
General Usage & Documentation Reference
On a day to day basis you should find yourself using N98-Magerun to do everything from bootstrapping a new extension to toggling template hints. Here I will cover several of the N98-Magerun commands that I have found most helpful, but you may access the full list of commands and parameters at any time using this page.
The primary reason that N98-Magerun is much simpler than manually running these types of commands via php or bash is because it automatically parses your Magento install for credentials and information- meaning you just point it to your Magento install and dump if you’re after a database. So, to begin, navigate to your Magento install’s root folder. Then do the following:
Database
Dump A Database:
n98-magerun.phar db:dump [filename]
This will automatically connect to your DB and dump the database to [filename]. [filename] is relative to your Magento installation. This uses the same dump command each time, and provides a consistent way for an entire team to dump their databases.
Dump A Stripped Database (No sensitive data, such as customers, orders, carts, logs, or other):
n98-magerun.phar db:dump --stripped="@development" [filename]
This command works much the same way as the standard dump, however it does not include any sensitive customer data. This dump will be much smaller than a standard dump, because it includes no data for orders, quotes, customers, logs and more. This is a great tool for sending a copy of the database to a developer for working locally or for creating a dump to be used in continuous integration situations, since the smaller size will speed up automated processes. Local developers should take note of the customer:create:dummy command. This allows you to generate many dummy customers for local environments, which is very useful during debugging and/or testing.
Import A Database:
n98-magerun.phar db:import [filename]
This will automatically connect to your DB and import the database from [filename]. [filename] is relative to your Magento install.
Manually Run A Query:
n98-magerun.phar db:query [query]
This will automatically connect to your DB and run the provided [query] using the MySQL CLI tool. This does require the CLI tool be installed on the server.
Extensions
List Extensions:
n98-magerun.phar dev:module:list [--codepool[="..."]] [--status[="..."]] [--vendor=[="..."]] [--format[="..."]]
This will boot up Magento and pull a list of all extensions from the configuration XML based on the parameters passed. Therefore, it is very helpful for listing out all of the disabled extensions, or auditing a site for local/community extensions.
List Extension Rewrite Conflicts:
n98-magerun.phar dev:module:rewrite:list
This will simply list any potential rewrite conflicts for your Magento installation. This is incredibly useful for debugging a problem with multiple extensions because there are usually many that operate on the same functionality in Magento.
Bootstrap A New Extension:
n98-magerun.phar dev:module:create [--add-blocks] [--add-helpers] [--add-models] [--add-setup] [--add-all] [--modman] [--add-readme] [--add-composer] [--author-name[="..."]] [--author-email[="..."]] [--description[="..."]] vendorNamespace moduleName [codePool]
This command is one of the larger commands offered by N98-Magerun, and for good reason. As you can see, using this command you can easily create a new module with any vendor name, module name, code pool, and components. This command supports modman, which will be covered in a later blog post.
Cache
Clear The Cache:
n98-magerun.phar cache:flush
This will completely empty the Magento cache by using the built-in Magento method to do so. This also means that if your cache is in REmote DIctionary Server (Redis), it will also clear it there.
Enable The Cache:
n98-magerun.phar cache:enable [code]
This enables all caching by default. However, if a [code] is specified it will only enable that specific cache.
Disable The Cache:
n98-magerun.phar cache:disable [code]
This will disable all caching by default. However, if a [code] is specified it will only disable that specific cache.
Config
Change A Config Setting:
n98-magerun.phar config:set [--scope[="..."]] [--scope-id[="..."]] [--encrypt] [--force] path value
This command utilizes Magento to set a configuration value in the database. It supports setting the value of your config path for individual scopes. This is extremely helpful for writing a simple bash script to quickly change a Magento installation so that you can configure it for a new environment.
Toggle Template Hints:
n98-magerun.phar dev:template-hints [store_code]
This is especially relevant for developers working locally. You can easily toggle template hints without loading up the admin panel from directly in your terminal. It supports providing a [store_code] to enable or disable templates on a particular store.
Dump A Portion of XML Config:
n98-magerun.phar config:dump [path]
This tool simplifies debugging of config nodes greatly. With this, you can supply any config node (such as ‘modules’ or ‘global/catalog’). This will instantly return data about these XML nodes.
Use Cases
As previously mentioned, N98-Magerun should be used in day to day development. However, it fills a large void when it comes to automating the development workflow. N98-Magerun’s command line-based approach allows for easy use within Continous Integration tools.
For example, when we deploy a sprint for a project we automatically acquire a stripped dump for the development team within their local machines. After this, we audit the site using a simple script and N98-Magerun when our staging environment is built. We then dynamically update our Confluence pages to reflect all current extensions, observers, and extension dependencies within that copy of Magento.
Below is a list of some useful ways that you can utilize N98-Magerun locally during development. If you take advantage of the tools that N98-Magerun provides, as a result, I can assure you that you that you will have a much easier time debugging any issues that you might come across, and in the long run, you will become a better developer for doing so. Because I feel this is such an important topic, I plan to add more specific blog posts in the future that will extend your knowledge of this great tool. These posts will contain information about how we utilize each of the following convenient examples within our continuous integration tools:
- Dump a stripped copy of the db (no sensitive user data) with n98-magerun
- Create an admin user with n98-magerun
- Clear the cache properly with n98-magerun
- Toggle template hints with n98-magerun
- List extensions for automated audits of the Magento install with n98-magerun
- Manually trigger a Magento cron job to fire with n98-magerun
Conclusion
I hope this gives you a good basic understanding of what is available using n98-magerun. It seems like the biggest hurdle here is going to be just getting people to try the tool once. Once you’re in, theres no looking back- so give it a shot!
