Innovative Computer Solutions,
Development & Technical Support

07975 997026 • enquiries[delete-me]@[delete-me]harpanet.com

User Tools

Site Tools


guides:quad:magento-global-functions-and-methods-toolset

Magento Global Functions - A Toolset for Templates

QUAD Guide Pre-requisites

So you have read the basic guides to creating Magento templates, and have played around a bit with the layout xml files, and possibly even tried some local.xml modifications to switch things on and off.

Next Steps:

Now you want to understand what is in the template blocks of .phtml files, or even begin creating your own blocks, containing various bits of Magento content. But what is available?

Breaking through the complexity of Magento is unweildly for new-comers, so welcome to this hArpanet QUAD Guide to Magento Templates. By the end of this guide we will have dug a little deeper into the morass and should have eased your headache somewhat.

This is not a how-to guide, but more of a what-can-I guide to give you an awareness of what is available. I'll leave it up to you to decide how to use this information to achieve your own goals.

Terminology

First, some terminology used in the content here.

I use… To refer to…
toolset The range of Magento functions that are available for us to use
function any PHP function or method created within .php files or classes.

Enter the Toolset:

To begin the act of creating something new, I find it useful to know what my Toolbox contains first, so that I know what the possibilities are. In Magento, your tools come from Globally available functions (methods) defined by Magento.

You've already seen them used in Magento .phtml files, such as…

  echo $this->__('Add to Wishlist') ...
 
  echo $this->getPriceHtml($_product, true) ...
 
  echo $this->getReviewsSummaryHtml($_product, 'short') ...
 
  if ($this->helper('wishlist')->isAllow()) ...

… and many others.

You will see in the above examples that the phtml file is calling functions from various objects: $this, $this→helper. Each of these locations is a 'toolbox' in its own right, and depending on the plugins you have installed then the number of toolboxes could be endless. Combine all these together and you have your working 'toolset'.

This QUAD Guide will just introduce the out-of-the-box functions available in a basic Magento Community Edition installation, using the demo products. We will begin by showing the most globally available functions, then look at context specific functions within $this.

Global Functions

Fairly early on, Magento loads code/core/Mage/core/functions.php which gives us a small number of useful functions…

NOTES:

  • The 'tags' shown below are not relevant to Magento, they are provided here to allow for easier searching within this QUAD Guide for a particular function type.
  • Parameters with angle brackets like <string> are required, while those in square brackets like [bool] are optional.

__(<string>)

Translate the english <string> to the current store language. Note that this function name simply contains two underscores.
eg. echo __('Add to Wishlist')
NOTE: This is a different __() function to the one listed in the example above (which uses $this->__()) but they both end up at the same translate() function in \app\code\core\Mage\Core\Model\Translate.php
Tags: text, convert, language

now([bool])

Get the current date and time (if [bool] is omitted or false). If [bool] is true, only the current date is returned. Date format is Y-m-d.
eg. echo now() or echo now(true)
Tags: datetime

mageParseCsv(<string>, [delimiter], [enclosure], [escape])

Returns an array containing the individual elements from the passed csv <string>.
[delimiter] is the character(s) that delimit the csv value. Default is , (a comma)
[enclosure] is the string enclosure character(s). Default is (a quotation mark)
[escape] is not used in current Magento code.
eg. $opts = mageParseCsv('these,are,”a lot of”,csv,options')

mageDebugBacktrace($return=false, $html=true, $showFirst=false)

Return or echo a backtrace for debugging.
$return indicates whether to return the trace as a string (true), or echo it (false)
$html wraps backtrace in <pre></pre> tags if true
$showFirst indicates whether to include the current page in the backtrace if true
eg. mageDebugBacktrace(false,true,true); or echo mageDebugBacktrace()

Other Functions

These are less useful initially, so are only listed here for completeness.

From: \app\code\core\Mage\Core\functions.php …

uc_words($str, $destSep='_', $srcSep='_')

Capitalise first letters of each word in $str and convert separators.
eg. uc_words('hello magento_world') gives Hello_Magento_World

mageUndoMagicQuotes($array, $topLevel=true)

Disable magic quotes in runtime if needed.

destruct($object)

Object destructor.

is_empty_date($date)

Check whether sql date is empty.

mageFindClassFile($class)

Look through include_path for specified class file. Returns filename or false.

mageCoreErrorHandler($errno, $errstr, $errfile, $errline)

Custom error handler.

mageDelTree($path)

Delete file or folder at specified $path. This is a recursive delete, therefore all sub folders/files will also be deleted.

is_dir_writeable($dir)

Determine if the specified $dir directory is writeable. Returns true or false.

sys_get_temp_dir()

Try and determine temp directory. Returns directory or false.

$this

When working within OOP applications such as Magento, the variable $this refers to the current scope or context, which means it changes what it contains on a regular basis.

For our journey into Magento $this we need a little help, rather than guessing what may or may not be available. Thankfully, PHP also gives us tools to investigate what is happening, so let's create a small function to show what $this can give us.

Although the 'proper' way to do this is to create a new module to Create Global Functions in Magento, we are going to do it the QUAD (QUick And Dirty) way. So, without further ado, let's…

  1. Create a directory in your local code area to hold our new functions. Let's call ours 'hArpanet'…
    • \app\code\local\hArpanet
  2. Download the following file and save it into the new folder so that it becomes \app\code\local\hArpanet\my_functions.php (you could actually save it anywhere, say in the Magento root folder, but the above folder keeps things tidy for us)
    1. my_functions.php
      <?php
       
      /**
       * hArpanet Magento Method Viewer
       * ==============================
       *
       * Place the following in a Magento .phtml block to view methods available...
       *
       *   include Mage::getBaseDir().'/app/code/local/hArpanet/my_functions.php';
       *   show_hierarchy($this);
       *
       */
       
      function show_hierarchy(& $obj) {
          echo "<h2>CLASS HIERARCHY:</h2>";
          $p = get_class($obj);
          do
          {
              echo "<strong>$p</strong><div style='padding:10px 0px 20px 50px;'>";
       
              foreach (get_class_methods_that_are_not_inherited_from_any_other_class($p) as $m) {
                  echo "$m <br/>";
              }
       
              echo "</div>";
       
          } while ($p = get_parent_class($p));
      }
       
      // http://uk3.php.net/manual/en/function.get-class-methods.php#112648 ...
      function get_class_methods_that_are_not_inherited_from_any_other_class($class)
      {
          $classReflection = new ReflectionClass($class);
          $classMethods = $classReflection->getMethods();
       
          $classMethodNames = [];
          foreach ($classMethods as $index => $method) {
              if ($method->getDeclaringClass()->getName() !== $class) {
                  unset($classMethods[$index]);
              } else {
                  $classMethodNames[] = $method->getName();
              }
          }
       
          return $classMethodNames;
      }
       
      ?>

OK, we've got the code, now how do we use it? Well, going by the comment in the code, we need to find an appropriate .phtml file to stick it in. Let's choose the product listing page within a category.

Ideally you will already have created your own template that you have been playing around with (see pre-requisites above). If you haven't, you can edit the core :-X file located at \app\design\frontend\default\default\template\catalog\product\list.phtml (it is a test website you're playing with, right???)

The list.phtml file contains this near the top…

<?php
/**
 * Product list template
 *
 * @see Mage_Catalog_Block_Product_List
 */
?>
 
<?php
    $_productCollection=$this->getLoadedProductCollection();
    $_helper = $this->helper('catalog/output');
?>
<?php if(!$_productCollection->count()): ?>
<p class="note-msg"><?php echo $this->__('There are no products matching the selection.') ?></p>
<?php else: ?>
etc...

To show us the $this functions available to this .phtml file, let's insert a call to our new function. Put this code…

<?php
  include Mage::getBaseDir().'/app/code/local/hArpanet/my_functions.php';
  show_hierarchy($this);
?>

…into list.phtml so it looks like…

<?php
/**
 * Product list template
 *
 * @see Mage_Catalog_Block_Product_List
 */
?>
 
<?php
  include Mage::getBaseDir().'/app/code/local/hArpanet/my_functions.php';
  show_hierarchy($this);
?>
 
<?php
    $_productCollection=$this->getLoadedProductCollection();
    $_helper = $this->helper('catalog/output');
?>
<?php if(!$_productCollection->count()): ?>
<p class="note-msg"><?php echo $this->__('There are no products matching the selection.') ?></p>
<?php else: ?>
etc...

Now browse to a Magento category page containing some products (eg. http://magento.test/electronics/cell-phones.html) and you should see a hierarchical list of Magento Class names, with a list of all functions (Methods) contained within them.

eg.

Mage_Catalog_Block_Product_List
  _getProductCollection 
  getLayer 
  getLoadedProductCollection 
  getMode 
  _beforeToHtml 
  getToolbarBlock 
  getAdditionalHtml 
  getToolbarHtml 
  setCollection 
  addAttribute 
  getPriceBlockTemplate 
  _getConfig 
  prepareSortableFieldsByCategory 
  getCacheTags 

Mage_Catalog_Block_Product_Abstract
  getAddToCartUrl 
  _getSingletonModel 
  getSubmitUrl 
  getAddToWishlistUrl 
  getAddToCompareUrl 
  getMinimalQty 
  _getPriceBlock 
  _getPriceBlockTemplate 
  _preparePriceRenderer 
  getPriceHtml 

etc.

In the list, the first Class (Mage_Catalog_Block_Product_List) extends the second Class (Mage_Catalog_Block_Product_Abstract) which extends the third Class … and so on to the root Class (Varien_Object).

You now have a decent list of the functions available to you within a .phtml file. It is not the full list of available functions, as they may change from page to page, and some of these functions may also be loading other Classes, Models or Helpers (inchoo:getting things in Magento) to achieve their work.

As you can see, this list is far too big to discuss each of the functions, so I'll leave that up to your curious mind. Simply look in the associated file to find the function and all of it's requirements.

eg. To look at getToolbarBlock in the Mage_Catalog_Block_Product_List Class, you would open the file located at \app\code\core\Mage\Catalog\Block\Product and open the file named list.php.

Magento Magic Methods (mmm)

Let's finish off with some magic (or should we call it extra confusion) within Magento, which makes extensive use of PHP OOP 'magic' getters, setters and calls.

What this means in reality is that Magento code will call not-existent functions and variables. Yep, they don't exist! Instead, the 'magic' PHP methods turn these unknown calls into something meaningful.

Let's have a look at what this means in practice…

In the list.phtml file that we inserted our new show_hierarchy($this) call above, you can see the line…

  $_productCollection=$this->getLoadedProductCollection();

From our list of Classes and Methods (displayed by show_hierarchy()), we can see that getLoadedProductCollection() is defined in Mage_Catalog_Block_Product_List which relates to the file \app\code\core\Mage\Catalog\Block\Product\List.php.

Looking in List.php we see that getLoadedProductCollection() simply returns $this→_getProductCollection(); which our Class/Method list tells us is in the same List.php file.

_getProductCollection() begins with this bit of code (I have added the line numbers)…

1.  $layer = $this->getLayer();
2.  /* @var $layer Mage_Catalog_Model_Layer */
3.  if ($this->getShowRootCategory()) {
4.      $this->setCategoryId(Mage::app()->getStore()->getRootCategoryId());
5.  }
 
  etc.

Line 1 calls getLayer() which our Class/Method list tells us is also in List.php.
Line 3 calls getShowRootCategory() which doesn't exist anywhere.

So how can we find out what it is doing? Well rather than reinvent the digital wheel, I'll pass you over to Ben Robie at codegento who answers the question Where are my Getters and Setters?. Thanks Ben!

Also note that these 'magic' methods are intended to be removed in Magento 2.0 whenever that arrives, so some of this confusion will disappear (hopefully).

Comments



F U P O L U A V X P D I
guides/quad/magento-global-functions-and-methods-toolset.txt · Last modified: 18/09/2013 15:12 by harpanet