包简介

A vtiger api wrapper

README 文档

README

This package might work with older versions of Vtiger, and possibly with laravel 6 or 7.

BerliCRM (based on Vtiger) has a better documentation, files are added in the documentation folder.

Use the Vtiger webservice (REST) API from within Laravel for the following operations.

ListTypes
Create
Retrieve
Update
Delete
Search
Query
Describe

See Third Party App Integration (REST APIs)

Installation, Configuration and Usage

Installing

In order to install the Vtiger package in your Laravel project, just run the composer require command from your terminal:
```
composer require "jbtje/vtiger-laravel"
```

Add ENV variables:

VTIGER_URL=https://your-crm-domain.com/webservice.php
VTIGER_USERNAME=
VTIGER_KEY=
VTIGER_PERSISTENT=true
VTIGER_RETRIES=10

Username and Access Key can be found within Vtiger under My Preferences

Optional: Publish the configuration file:

php artisan vendor:publish --tag="vtiger"

Configuration

You can create a new user in Vtiger for the API to use, or use an existing user.

Usage

Include the Vtiger package in your controller:

use JBtje\VtigerLaravel\Vtiger;

ListTypes

List types is a command to provide you with all possible types the Vtiger CRM supports. For each type, you can run the describe() command, to obtain the data structure.

Obtain all the list types:

$vtiger = new Vtiger();
$data = $vtiger->listTypes();

For a clean install, this will return: (click to expand)

  {
    "success": true,
    "result": {
        "types": [
            "Campaigns",
            "Vendors",
            "Faq",
            "Quotes",
            "PurchaseOrder",
            "SalesOrder",
            "Invoice",
            "PriceBooks",
            "Calendar",
            "Leads",
            "Accounts",
            "Contacts",
            "Potentials",
            "Products",
            "Documents",
            "Emails",
            "HelpDesk",
            "Events",
            "Users",
            "PBXManager",
            "ServiceContracts",
            "Services",
            "Assets",
            "ModComments",
            "ProjectMilestone",
            "ProjectTask",
            "Project",
            "SMSNotifier",
            "Groups",
            "Currency",
            "DocumentFolders",
            "CompanyDetails",
            "LineItem",
            "Tax",
            "ProductTaxes"
        ],
        "information": {
            "Campaigns": {
                "isEntity": true,
                "label": "Campaigns",
                "singular": "Campaign"
            },
            "Vendors": {
                "isEntity": true,
                "label": "Vendors",
                "singular": "Vendor"
            },
            "Faq": {
                "isEntity": true,
                "label": "FAQ",
                "singular": "FAQ"
            },
            "Quotes": {
                "isEntity": true,
                "label": "Quotes",
                "singular": "Quote"
            },
            "PurchaseOrder": {
                "isEntity": true,
                "label": "Purchase Orders",
                "singular": "Purchase Order"
            },
            "SalesOrder": {
                "isEntity": true,
                "label": "Sales Orders",
                "singular": "Sales Order"
            },
            "Invoice": {
                "isEntity": true,
                "label": "Invoices",
                "singular": "Invoice"
            },
            "PriceBooks": {
                "isEntity": true,
                "label": "Price Books",
                "singular": "Price Book"
            },
            "Calendar": {
                "isEntity": true,
                "label": "Calendar",
                "singular": "Task"
            },
            "Leads": {
                "isEntity": true,
                "label": "Leads",
                "singular": "Lead"
            },
            "Accounts": {
                "isEntity": true,
                "label": "Organizations",
                "singular": "Organization"
            },
            "Contacts": {
                "isEntity": true,
                "label": "Contacts",
                "singular": "Contact"
            },
            "Potentials": {
                "isEntity": true,
                "label": "Opportunities",
                "singular": "Opportunity"
            },
            "Products": {
                "isEntity": true,
                "label": "Products",
                "singular": "Product"
            },
            "Documents": {
                "isEntity": true,
                "label": "Documents",
                "singular": "Document"
            },
            "Emails": {
                "isEntity": true,
                "label": "Emails",
                "singular": "Email"
            },
            "HelpDesk": {
                "isEntity": true,
                "label": "Tickets",
                "singular": "Ticket"
            },
            "Events": {
                "isEntity": true,
                "label": "Events",
                "singular": "Event"
            },
            "Users": {
                "isEntity": true,
                "label": "Users",
                "singular": "User"
            },
            "PBXManager": {
                "isEntity": true,
                "label": "PBX Manager",
                "singular": "Call Record"
            },
            "ServiceContracts": {
                "isEntity": true,
                "label": "Service Contracts",
                "singular": "Service Contract"
            },
            "Services": {
                "isEntity": true,
                "label": "Services",
                "singular": "Service"
            },
            "Assets": {
                "isEntity": true,
                "label": "Assets",
                "singular": "Asset"
            },
            "ModComments": {
                "isEntity": true,
                "label": "Comments",
                "singular": "Comment"
            },
            "ProjectMilestone": {
                "isEntity": true,
                "label": "Project Milestones",
                "singular": "Project Milestone"
            },
            "ProjectTask": {
                "isEntity": true,
                "label": "Project Tasks",
                "singular": "Project Task"
            },
            "Project": {
                "isEntity": true,
                "label": "Projects",
                "singular": "Project"
            },
            "SMSNotifier": {
                "isEntity": true,
                "label": "SMS Notifier",
                "singular": "SMS Notifier"
            },
            "Groups": {
                "isEntity": false,
                "label": "Groups",
                "singular": "Groups"
            },
            "Currency": {
                "isEntity": false,
                "label": "Currency",
                "singular": "Currency"
            },
            "DocumentFolders": {
                "isEntity": false,
                "label": "DocumentFolders",
                "singular": "DocumentFolders"
            },
            "CompanyDetails": {
                "isEntity": false,
                "label": "CompanyDetails",
                "singular": "CompanyDetails"
            },
            "LineItem": {
                "isEntity": false,
                "label": "LineItem",
                "singular": "LineItem"
            },
            "Tax": {
                "isEntity": false,
                "label": "Tax",
                "singular": "Tax"
            },
            "ProductTaxes": {
                "isEntity": false,
                "label": "ProductTaxes",
                "singular": "ProductTaxes"
            }
        }
    }
}

Describe

To obtain the data sctructure of a module in Vtiger, run the describe method with the module name. Module names can be obtained using listTypes()

$vtiger = new Vtiger();
$data = $vtiger->describe( 'Contacts' );

Partial result for "Contacts": (click to expand)

{
    "success": true,
    "result": {
        "label": "Contacts",
        "name": "Contacts",
        "createable": true,
        "updateable": true,
        "deleteable": true,
        "retrieveable": true,
        "fields": [
            {
                "name": "firstname",
                "label": "First Name",
                "mandatory": false,
                "type": {
                    "name": "string"
                },
                "isunique": false,
                "nullable": true,
                "editable": true,
                "default": ""
            },
            {
                "name": "lastname",
                "label": "Last Name",
                "mandatory": true,
                "type": {
                    "name": "string"
                },
                "isunique": false,
                "nullable": false,
                "editable": true,
                "default": ""
            },
            {
                "name": "assigned_user_id",
                "label": "Assigned To",
                "mandatory": true,
                "type": {
                    "name": "owner"
                },
                "isunique": false,
                "nullable": false,
                "editable": true,
                "default": ""
            },
            ...
        ],
        "idPrefix": "12",
        "isEntity": true,
        "allowDuplicates": true,
        "labelFields": "firstname,lastname"
    }
}

Please note the mandatory field.

Create

To insert a record into the CRM, first create an array of data to insert. Using describe(), you can see which fields are mandatory.

$vtiger = new Vtiger();
$data = [
    'assigned_user_id' => '4x1',
    ...
];
$data = $vtiger->create( $MODULE_NAME, json_encode( $data ) );

Retrieve

To retrieve a record from the CRM, you need the id of the record you want to find (i.e. '4x1').

$vtiger = new Vtiger();
$data = $vtiger->retrieve( '4x1' );

Update

The easiest way to update a record in the CRM is to retrieve the record first.

$vtiger = new Vtiger();
$obj = $vtiger->retrieve( '4x1' );

Then update the object:

$obj->result->field_name = 'Your new value';
$data = $vtiger->update( $obj->result );

Delete

To delete a record from the CRM, you need the id of the record you want to delete (e.g. '4x1').

$vtiger = new Vtiger();
$data = $vtiger->delete( '4x1' );

Lookup

This function uses the Vtiger Lookup API endpoint to search for a single piece of information within multiple columns of a Vtiger module. This function is often multitudes faster than the search function.

$dataType = 'phone';
$phoneNumber = '1234567890';
$module = 'Leads';
$columns = ['phone', 'fax']; // Must be an array
    
$vtiger = new Vtiger();
$data = $vtiger->lookup( $dataType, $phoneNumber, $module, $columns );

Search

This function is a sql query builder wrapped around the query function. Accepts instance of laravels QueryBuilder.

$vtiger = new Vtiger();
$query = DB::table( 'Leads' )->select( 'id', 'firstname', 'lastname' )->where( 'firstname', 'John' );
$data = $vtiger->search( $query );

foreach( $data->result as $result ) {
    // Do something
}

By default, the function will quote but not escape your inputs, if you wish for your data to not be quoted, set the 2nd paramater to false:

$vtiger = new Vtiger();
$data = $vtiger->search( $query, false );

Also keep in mind that Vtiger has several limitations on it's sql query capabilities. You can not use conditional grouping i.e "where (firstname = 'John' AND 'lastname = 'Doe') OR (firstname = 'Jane' AND lastname = 'Smith')" will fail.

Query

To use the Query Operation , you first need to create the SQL query.

$query = "SELECT * FROM ModuleName;";

Then run the query...

$vtiger = new Vtiger();
$data = $vtiger->query($query);

foreach( $data->result as $result ) {
    // Do something
}

Contributing

Please report any issue you find in the issues page. Pull requests are more than welcome.

License

This project is licensed under the MIT licence - see the LICENSE.md file for details

Contributors

This package is based upon Clystnet/Vtiger

This project follows the all-contributors specification. Contributions of any kind welcome!

jbtje/vtiger-laravel 适用场景与选型建议

jbtje/vtiger-laravel 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 792 次下载、GitHub Stars 达 3，最近一次更新时间为 2021 年 11 月 01 日，在 PHP 生态内属于活跃度较高的组件。

我们在过去多个企业项目中使用过 jbtje/vtiger-laravel 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 jbtje/vtiger-laravel 我们能提供哪些服务？

定制开发 / 二次开发

基于 jbtje/vtiger-laravel 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

jbtje/vtiger-laravel

包简介