Zurmo – Developers Tip – using Item::getByName()

This post is about how to use a very handy, but quirky core Zurmo framework function. The intended audience is intermediate PHP developers who already know how to extend Zurmo CRM and how to build and run tests under the Zurmo test framework.

If you are just starting out with Zurmo, don’t worry, we will be posting many future articles for beginners to get you up to speed. Every once in a while, though, we will be throwing the developers a few bones.

Most custom model classes in Zurmo are derived at some point from the ‘Item’ class.  As such they inherit, and you should override, the getByName($name) function.  The purpose of this method, as you might expect, is to return object(s) of the current model class type, from the database which match on the specified ‘$name’ attribute. Here’s an example from the standard Zurmo “Account” class.

public static function getByName($name){
            return self::getByNameOrEquivalent('name', $name);

Here, the static function getByName ($name) takes a string as its only parameter.  So for an Account with the name attribute set to “Acme”, you might try:

$account              = new Account();
$account->name        = 'Acme';

$result               = Account::getByName('Acme');

What do you think will be returned in the $result variable?

If you said “An object of type Account named Acme,” you would be only partially correct. Therein lies the quirky-ness to which I alluded. Intuitively, we make the assumption that there is only one Account with the name ‘Acme’. That very-well-could-be the case in your business, but Zurmo makes no such assumption, and that is why you are permitted, nay, encouraged to override this method when you are extending Zurmo with your own models.

By the way the proper place to enforce such a business rule, would be in Account::getDefaultMetadata() as a validation rule.

Furthermore, you actually want, this behavior, because it gives you the flexibility to handle multiple Accounts with the same name.

If you were to try something like this, for example in a test case:

$result = Account::getByName('Acme');
$this->assertEquals('Account', get_class($result);

You will get an error like this:

get_class() expects parameter 1 to be object, array given

So that is your first clue that you are dealing with an array, which is actually a set of objects which are being returned from the database via RedBeanPHP.   If you know that the Account name is a unique attribute you can retrieve the Acme Account this way:

$result = Account::getByName('Acme');
$this->assertEquals('Account', get_class($result[0]);

Having gotten burned for the nth time on this issue, I figured it might help me as well as the other aspiring Zurmo developers remember how to correctly use this method.

(c) 2013 Windsor Wallaby. All rights reserved.

Tags: , , , , , , , , | Posted under Zurmo | RSS 2.0

Author Spotlight

Windsor Wallaby

Windsor Wallaby is an independent and enthusiastic Zurmo CRM supporter and Open Source contributor. Active on the Zurmo user forums and a regular personality on the weekly Zurmo developer's conference call, Windsor is committed to building helping relationships by Listening, Learning, Doing, and Sharing. Windsor works with Zurmo CRM daily to track business opportunities and contacts. Windsor also integrates Zurmo as a core platform component for in-house and bespoke IT development projects.

Leave a Reply

Your email address will not be published. Required fields are marked *