Registros Relacionados

Vimos como salvar registros únicos, mas, em um sistema de CRM, os relacionamentos entre registros são tão importantes quanto os próprios registros. Por exemplo, uma conta pode ter uma lista de casos associados a ela, um contato terá uma conta em que se enquadra etc. Podemos obter e definir relacionamentos entre registros usando vários métodos.

get_linked_beans

O método get_linked_beans permite recuperar uma lista de beans relacionados para um determinado registro.

Exemplo 3.14: Assinatura do método get_linked_beans

get_linked_beans(
                $field_name,
                $bean_name = '',
                $order_by = '',
                $begin_index = 0,
                $end_index = -1,
                $deleted = 0,
                $optional_where = "");

$field_name: O nome do campo do link para este link. Observe que este não é o mesmo que o nome do relacionamento. Se você não tiver certeza do que deveria ser, pode dar uma olhada no cache vardefs de um módulo em cache/modules/<TheModule>/<TheModule>Vardefs.php para a definição de link.
$bean_name: Usado para especificar o nome do bean que você espera voltar. Não é necessário nas versões atuais, mantido para compatibilidade com versões anteriores ou para o evento improvável de você ter um relacionamento de estilo antigo.
$order_by: Opcionalmente, adicione uma clausula like last_name DESC para obter resultados classificados.
$begin_index: Ignora os resultados iniciais $begin_index. Pode ser usado para paginar.
$end_index: Até o resultado $end_index. Pode ser usado para paginar.
$deleted: Controla se os registros excluídos ou não excluídos são mostrados. Se verdadeiro, somente os registros excluídos serão retornados. Se falso, somente registros não excluídos serão retornados.
$optional_where: Permite filtrar os resultados usando uma cláusula SQL WHERE. Veja o método get_list para mais detalhes.

Results

get_linked_beans retorna uma matriz dos registros vinculados.

Exemplo 3.15: Exemplo de chamada get_linked_beans

$accountBean->get_linked_beans(
                'contacts',
                'Contacts',
                array(),
                0,
                10,
                0,
                "contacts.primary_address_country = 'USA'");

Relationships

Além da chamada get_linked_beans , você também pode carregar e acessar os relacionamentos mais diretamente.

Carregando

Antes de acessar um relacionamento, você deve usar a chamada load_relationship para garantir que ele esteja disponível. Essa chamada leva o nome do link do relacionamento (não o nome do relacionamento). Como mencionado anteriormente, você pode encontrar o nome do link em cache/modules/<TheModule>/<TheModule>Vardefs.php se você não tiver certeza.

Exemplo 3.16: Carregando um relacionamento

//Load the relationship
$accountBean->load_relationship('contacts');
//Can now call methods on the relationship object:
$contactIds = $accountBean->contacts->get();

Methods

get: Retorna os IDs dos registros relacionados nesse relacionamento, por exemplo, para o relacionamento conta-contatos no exemplo acima, ele retornará a lista de IDs para contatos associados à conta.
getBeans: Semelhante a get, mas retorna uma matriz de beans em vez de apenas ids.

getBeans carregará o bean completo para cada registro relacionado. Isso pode causar um desempenho ruim nos relacionamentos com um grande número de beans.

add: Permite relacionar registros ao bean atual. add usa um único ID ou bean ou uma matriz de IDs ou beans. Se o bean estiver disponível, isso deve ser usado, pois evita recarregar o bean. Por exemplo, para adicionar um contato ao relacionamento em nosso exemplo, podemos fazer o seguinte:

Exemplo 3.18: Adicionando um novo contato a um relacionamento

//Load the relationship
$accountBean->load_relationship('contacts');

//Create a new demo contact
$contactBean = BeanFactory::newBean('Contacts');
$contactBean->first_name = 'Jim';
$contactBean->last_name = 'Mackin';
$contactBean->save();

//Link the bean to $accountBean
$accountBean->contacts->add($contactBean);

delete: delete permite grãos não relacionados. Contra-intuitivamente, ele aceita os IDs do bean e do bean relacionado. Para o bean relacionado, você deve passar o bean, se estiver disponível, por exemplo, ao não relacionar uma conta e entrar em contato:

Exemplo 3.19: Removendo um novo contato de um relacionamento

//Load the relationship
$accountBean->load_relationship('contacts');

//Unlink the contact from the account - assumes $contactBean is a Contact SugarBean
$accountBean->contacts->delete($accountBean->id, $contactBean);

Tenha cuidado com o método de exclusão. A omissão do segundo argumento fará com que todos os relacionamentos desse bean sejam removidos.