SugarCRM Logic Hooks

Logic hooks are developer's bread and butter for custom coding in SugarCRM.  Logic hooks allow you to alter the functionality and behavior of Sugar to meet  customer requirements.  Unfortunately, there is too much to cover to completely cover logic hooks in one article, so we'll do this with a couple of articles.  With this article I want to show you how to create a logic hook.

Logic hooks are normally created for a particular module.  You want to alter a particular modules behavior.  It is also possible to create a global logic hook that will fire across all modules.  To create a logic hook in Sugar you need two files.  The first is always called logic_hooks.php and the second can be called anything you'd like with some restrictions.

These files are located in custom/modules/[the module your working with], for example, for a logic hook for the Accounts module, you would place the two files in the "custom/modules/Accounts" folder.  If you want to have a global logic hook that fires across the application when an event happens, then you would place the two files in the "custom/modules" folder.

Let's start with the logic_hooks.php file.  The purpose of the logic_hook file is to fire your custom code when a particular event happens in Sugar.  An event is a specific dynamic change in Sugar, caused by a user or system interaction, for example, a record is saved, or a page is loaded.  There is a long list of events that can be used to trigger a logic hook, which then triggers your custom code, which I'll cover in my next article.  Let's see what a typical logic_hooks.php file looks like:



This particular logic_hooks file contains two "before_save" hooks, two "after_retrieve" hooks, and a "process_record" hook.   More on these in my next article.

You're creating an array of information for the particular event used to fire your custom code.  The array for your event is initialized with this line:  $hook_array = Array();.  Each event has its own array.   In the picture, a "before_save" event is started with: $hook_array['before_save'] =

The order of execution for a "before_save" event is, when a record is saved in the front-end of the application by a user clicking on a record's save button, right before that record is saved to the database, the logic hook fires, and runs your custom code, after your custom code runs, the record will be saved to the database.  Just so you know, there's also an "after_save" event which fires right after the record has been saved to the database.

Let's concentrate on one hook, the "before_save" hook for an explanation of the array components.  Here it is again:


Reading from the left, this is a "before_save" hook, in the brackets you enter the event you want to use to fire your custom code.  Please note the blank square brackets [] after the event brackets, they need to be there.  Inside the array, you first see the number 1, this is used to determine the order when many "before_save" hooks need to fire.  In the first picture, you see a "before_save" 1 and 2.

Next we have a comment, 'update Email Addr', this is put in the the array for a short description of the hook.  When you have a bunch of logic hooks in the file as in the first picture, it makes it easy to pick out the logic hook your looking for in the logic_hooks file.

The next three entries in the array is the heart of the hook.  The next section, 'custom/modules/Accounts/updateEmailAddr.php', tells Sugar the exact path and file name where your custom code resides, that you want to fire with this hook.  This is the name of the second file you need for the hook.

The next entry is the name of the class of your custom code.  It has a restriction.  Your class has to have the same name as your file name.  The "updateEmailAddr.php" file should have the class called "UpdateEmailAddr."    The class name in the logic_hooks file  directs Sugar to your class.

The last entry, 'updateStoredEmailAddr', is the name of the method inside your custom class that will be fired when the hook fires.

Let's take a look at the second file you'll need, the "updateEmailAddr.php" file:



Alright, here's the custom code for the hook.  This particular hook fires before the record is saved to the database, checks to see if there's been a change to a type of user's email address field to be saved, and if there has been a change, it will look up what it should be and replace whatever was entered in the field with the primary email assigned to the account.  In this case, that email address is not allowed to be changed without certain procedures being followed, so this, in essence, is a validation hook.

Let's talk about the code.  You create a class to contain your code, called, you guessed it "updateEmailAddr," that you put in the logic hooks file.  And the method that runs when the hook fires is: "updateStoredEmailAddr" just like you described in the logic hooks file.

The file should always start out with:  if (!defined('sugarEntry') || !sugarEntry) die('Not A Valid Entry Point');  This prevents unauthorized access the file, and is seen at the start in most of the Sugar files.

The method "updateStoredEmailAddr(&$bean, $event, $arguments)" usually contains the parameters "&$bean", "$event", and "$arguments".  This passes the database ORM Sugar $bean into the method by reference, so you can use it in your method.  The $event is "before_save," or the event that fires the hook.  The $arguments can be an array of parameters that are specific to the event you'd like to send into the method.  Most of the time the last two parameters are not used in the method.

Inside the method, "updateStoredEmailAddr," you'll notice like other methods you can include other code from other files.  In this case, the included file  contains the method, getPrimaryEmail().

The return at the end of the class returns back to Sugar which then proceeds to save the record to the database.  Next time, I'll go over the various events you can use to fire your custom code.

Comments are closed.