Beans são o modelo na arquitetura MVC (Model View Controller) do SuiteCRM. Eles permitem recuperar dados do banco de dados como objetos e permitem persistir e editar registros. Esta seção examinará as várias maneiras de trabalhar com feijão.
The BeanFactory
O BeanFactory permite carregar instâncias de bean dinamicamente ou criar novos registros. Por exemplo, para criar um novo bean, você pode usar:
Exemplo 3.1: Criando um novo Bean usando a BeanFactory
$bean = BeanFactory :: newBean (”);
// Por exemplo, um novo bean de conta:
$accountBean = BeanFactory :: newBean (‘Contas’);
A recuperação de um bean existente pode ser realizada de maneira semelhante:
Exemplo 3.2: Recuperando um bean com a BeanFactory
$bean = BeanFactory :: getBean (”, $ beanId);
// Por exemplo, para recuperar um ID de conta
$bean = BeanFactory :: getBean (‘Contas’, $ beanId);
getBean retornará um objeto de bean não preenchido se $ beanId não for fornecido ou se não houver tal registro.
Recuperar um bean não preenchido pode ser útil se você deseja usar os métodos estáticos do bean (por exemplo, consulte a seção Procurando por Beans). Para recuperar deliberadamente um bean não preenchido, você pode omitir o segundo argumento da chamada getBean.
Exemplo 3.3: Recuperando um bean não preenchido
$bean = BeanFactory :: getBean (”);
O uso de BeanFactory garante que o bean esteja configurado corretamente e os arquivos necessários sejam incluídos, etc.
Sugarbean
O SugarBean é a classe de bean pai e todos os beans em SuiteCRM estendem esta classe. Ele fornece várias maneiras de recuperar e interagir com os registros.
Procurando Bean
Os exemplos a seguir mostram como pesquisar por beans usando uma classe de bean. Os exemplos fornecidos assumem que um bean de conta está disponível com os nomes $ accountBean. Isso pode ter sido recuperado usando a chamada getBean mencionada na seção BeanFactory.
Exemplo 3.4: Recuperando um bean de conta não preenchido
$accountBean = BeanFactory :: getBean (‘Contas’);
get_list
O método get_list permite obter uma lista de beans correspondentes e permite a paginação dos resultados.
Exemplo 3.5: assinatura do método get_list
get_list(
$order_by = “”,
$where = “”,
$row_offset = 0,
$limit = -1,
$max = -1,
$show_deleted = 0)
$order_by
Controla a ordem da lista retornada. $ order_by é especificado como uma string que será usada na cláusula SQL ORDER BY, por exemplo para classificar por nome você pode simplesmente passar nome, para classificar por date_entered descendente use date_entered DESC. Você também pode classificar por vários campos. Por exemplo, classificação por date_modified e id descendente date_modified, id DESC.
$where
Permite filtrar os resultados usando uma cláusula SQL WHERE. $ onde deve ser uma string contendo as condições SQL. Por exemplo, no módulo de contatos, pesquisando contatos com nomes específicos, podemos usar contacts.first_name = ‘Jim’. Observe que especificamos a tabela, a consulta pode acabar se juntando a outras tabelas, portanto, queremos garantir que não haja ambigüidade no campo que almejamos.
$row_offset
A linha para começar. Pode ser usado para paginar os resultados.
$limit
O número máximo de registros a serem retornados pela consulta. -1 significa sem limite.
$max
O número máximo de entradas a serem retornadas por página. -1 significa o máximo padrão (geralmente 20).
$show_deleted
Se deve incluir resultados excluídos.
Resultados
get_list retornará um array. Isso conterá as informações de paginação e também a lista de beans. Esta matriz conterá as seguintes chaves:
list
Uma matriz dos grãos retornados pela consulta de lista
row_count
O número total de linhas no resultado
next_offset
O deslocamento a ser usado para a próxima página ou -1 se não houver mais páginas.
anterior_offset
O deslocamento a ser usado para a página anterior ou -1 se esta for a primeira página.
current_offset
O deslocamento usado para os resultados atuais.
Exemplo
Vejamos um exemplo concreto. Retornaremos a terceira página de todas as contas com a mídia da indústria usando 10 como tamanho de página e ordenadas por nome.
Exemplo 3.6: Exemplo de chamada
get_list $beanList = $accountBean-> get_list ( // Ordene pelo nome da conta ‘nome’,
// Apenas contas com ‘Media’ da indústria “accounts.industry = ‘Media'”,
// Comece com o 30º registro (terceira página) 30,
// Sem limite – o padrão será o tamanho máximo da página -1,
// 10 itens por página
);
Isso retornará:
Exemplo 3.7: Exemplo de resultados get_list
Array (
// Snipped for brevity – a lista de Account SugarBeans [lista] => Array ()
// O número total de resultados
[row_count] => 36
// Esta é a última página, então o próximo deslocamento é -1 [next_offset] => -1
// Deslocamento da página anterior
[offset_ anterior] => 20
// O deslocamento usado para esses resultados [deslocamento_atual] => 30
)
get_full_list
get_list é útil quando você precisa de resultados paginados. No entanto, se você está apenas interessado em obter uma lista de todos os beans correspondentes, pode usar get_full_list. A assinatura do método get_full_list se parece com isto:
Exemplo 3.8: assinatura do método get_full_list
get_full_list
(
$order_by = “”,
$where = “”,
$check_dates = false,
$show_deleted = 0
Esses argumentos são idênticos ao seu uso em get_list, a única diferença é o argumento $check_dates.
Isso é usado para indicar se os campos de data devem ser convertidos em seus valores de exibição (ou seja, convertidos para o formato de data do usuário).
Resultados
A chamada get_full_list simplesmente retorna uma matriz dos beans correspondentes.
Exemplo
Vamos retrabalhar nosso exemplo get_list para obter a lista completa de contas correspondentes:
Exemplo 3.9: Exemplo de chamada get_full_list
$beanList = $accountBean-> get_full_list (
// Ordene pelo nome da conta
‘nome’,
// Apenas contas com ‘Media’ da indústria
“accounts.industry = ‘Media'”
);
retrieve_by_string_fields
Às vezes, você deseja recuperar apenas uma linha, mas pode não ter o id do registro. retrieve_by_string_fields permite recuperar um único registro com base em campos de string correspondentes.
Exemplo 3.10: assinatura do método retrieve_by_string_fields
retrieve_by_string_fields (
$fields_array,
$encode = true,
$excluído = verdadeiro
)
$ fields_array
Uma matriz de nomes de campo para o valor desejado.
$encode
Se os resultados devem ou não ser codificados em HTML.
$deleted
Se deve ou não adicionar o filtro excluído.
Resultados
retrieve_by_string_fields retorna um único bean como resultado ou nulo se não houver bean correspondente.
Exemplo
Por exemplo, para recuperar a conta com o nome Tortoise Corp e account_type Customer, poderíamos usar o seguinte:
Exemplo 3.11: Exemplo de chamada retrieve_by_string_fields
$beanList = $ accountBean-> retrieve_by_string_fields ( array (
‘nome’ => ‘Tortoise Corp’, ‘account_type’ => ‘Cliente’
)
);
Acessando campos
Se você usou um dos métodos acima, agora temos um registro de bean. Este bean representa o registro que recuperamos. Podemos acessar os campos desse registro simplesmente acessando propriedades no bean, assim como qualquer outro objeto PHP. Da mesma forma, podemos usar o acesso à propriedade para definir os valores dos beans. Alguns exemplos são os seguintes:
Exemplo 3.12: Acessando exemplos de campos
// Obtenha o campo Nome no bean de conta
$accountBean-> name;
// Obtenha a data de início da reunião
$meetingBean-> date_start;
// Obtenha um campo personalizado em um caso
$caseBean-> third_party_code_c;
// Defina o nome de um caso
$caseBean-> name = ‘Novo nome de caso’;
// Defina o código postal do endereço de cobrança de uma conta
$accountBean-> billing_address_postalcode = ‘12345’;
Quando mudanças são feitas em uma instância de bean, elas não são persistidas imediatamente.
Podemos salvar as alterações no banco de dados com uma chamada ao método de salvamento de beans.
Da mesma forma, uma chamada para salvar em um novo bean adicionará esse registro ao banco de dados:
Exemplo 3.13: Mudanças de bean persistentes
// Obtenha o campo Nome no bean de conta
$accountBean-> name = ‘Novo nome de conta’;
// Defina o código postal do endereço de cobrança de uma conta
$accountBean-> billing_address_postalcode = ‘12345’;
// Salve ambas as alterações.
$accountBean-> save ();
// Crie um novo caso (veja a seção BeanFactory)
$caseBean = BeanFactory :: newBean (‘Casos’);
// Dê um nome e salve $caseBean-> name = ‘Novo nome de caso’;
$caseBean-> save ();
Marcando um Bean como excluído
Use o método mark_deleted para isso.
Isso definirá o campo excluído como 1, também marcará qualquer relacionamento desse Bean como excluído e removerá a referência a esse item das listas Visualizadas recentemente.
$bean->mark_deleted($id); // Saving is required afterwards $bean->save();
Este método também chamará os ganchos lógicos before_delete e after_delete apropriados.
Bean relacionado
Vimos como salvar registros únicos, mas, em um sistema CRM, os relacionamentos entre os 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 na qual se enquadra etc.
Podemos obter e definir relacionamentos entre os beans 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,
$ deletada = 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 tem certeza do que deve ser, pode dar uma olhada nos vardefs em cache de um módulo em cache / modules / / Vardefs.php para a definição do link.
$bean_name
Usado para especificar o nome do bean dos grãos que você está esperando de volta. Não necessário nas versões atuais, mantido para compatibilidade com versões anteriores ou para o caso improvável de você ter um relacionamento de estilo antigo.
$order_by
Opcionalmente, adicione uma cláusula como last_name DESC para obter resultados classificados (disponível apenas a partir do SuiteCRM 7.4 em diante).
$begin_index
Ignora os resultados iniciais de $ begin_index. Pode ser usado para paginar.
$end_index
Retorne até o resultado $ end_index. Pode ser usado para paginar.
$deleted
Controla se os registros excluídos ou não excluídos são exibidos. Se verdadeiro, apenas os registros excluídos serão retornados. Se for falso, apenas os 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.
Resultados
get_linked_beans retorna uma matriz dos beans vinculados.
Exemplo 3.15: Exemplo de chamada get_linked_beans
$ accountBean-> get_linked_beans (
‘Contatos’,
‘Contatos’,
array (),
0,
10,
0,
“contacts.primary_address_country = ‘USA'”);
Relacionamentos
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 esteja disponível.
Essa chamada leva o nome do link do relacionamento (não o nome do relacionamento). Conforme mencionado anteriormente, você pode encontrar o nome do link em cache / modules / / Vardefs.php se não tiver certeza.
Exemplo 3.16: Carregando um relacionamento
// Carregar o relacionamento
$accountBean-> load_relationship (‘contatos’);
// Agora pode chamar métodos no objeto de relacionamento:
$contactIds = $ accountBean-> contacts-> get ();
Métodos
get
Retorna os ids dos registros relacionados neste 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.
add
Permite relacionar registros ao bean atual. add leva um único id ou bean ou um array de ids ou beans. Se o bean estiver disponível, isso deve ser usado, pois evita o recarregamento do 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
// Carregar o relacionamento
$accountBean-> load_relationship (‘contatos’);
// Crie um novo contato de demonstração
$contactBean = BeanFactory :: newBean (‘Contatos’);
$contactBean-> first_name = ‘Jim’;
$contactBean-> last_name = ‘Mackin’;
$contactBean-> save ();
// Vincule o bean a $accountBean$
accountBean-> contacts-> add ($contactBean);
delete
Delete permite beans 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 cancelar o relacionamento de uma conta e contato:
Exemplo 3.19: Removendo um novo contato de um relacionamento
//Carregar o relacionamento
$accountBean-> load_relationship (‘contatos’);
// Desvincular o contato da conta – assume que $contactBean é um contato SugarBean
$accountBean-> contacts-> delete ($accountBean-> id, $ contactBean);
