README

DingTalk integration for DCat Admin, providing easy access to DingTalk APIs including YiDa forms.

Installation

You can install the package via composer:

composer require dingtalk/dcat-admin

For development purposes, you can also install directly from the git repository:

composer require dingtalk/dcat-admin:dev-master

Basic Usage

DingTalkConfig

The DingTalkConfig class is used to encapsulate DingTalk configuration.

use DingTalkDcatAdmin\DingDing\DingTalkConfig;

// Create config instance
$config = new DingTalkConfig(
    $appKey, 
    $appSecret, 
    $cacheKey // Used for caching access tokens
);

// Set YiDa config (optional)
$config->setYiDaConfig($appType, $systemToken);

DDAccessToken

The DDAccessToken class is used to get and manage DingTalk access tokens.

use DingTalkDcatAdmin\DDAccessToken;
use DingTalkDcatAdmin\DingDing\DingTalkConfig;
use Psr\SimpleCache\CacheInterface;
use Psr\Log\LoggerInterface;

// Create config instance
$config = new DingTalkConfig($appKey, $appSecret, $cacheKey);

// Get access token
$accessToken = DDAccessToken::make(
    $config, 
    $cache, // Optional, implements CacheInterface
    $logger // Optional, implements LoggerInterface
);

YiDa

The YiDa class provides methods to interact with DingTalk YiDa forms.

use DingTalkDcatAdmin\DingDing\YiDa;
use DingTalkDcatAdmin\DingDing\DingTalkConfig;
use Psr\Log\LoggerInterface;
use Psr\SimpleCache\CacheInterface;

// Create config instance
$config = new DingTalkConfig($appKey, $appSecret, $cacheKey);
$config->setYiDaConfig($appType, $systemToken);

// Create YiDa instance
$yiDa = new YiDa(
    $config, 
    $logger, // Optional, implements LoggerInterface
    $cache // Optional, implements CacheInterface
);

// Search form data
$result = $yiDa->searchForm($userId, $formUuid, $searchs, $extParams);

Attendance

The Attendance class provides methods to interact with DingTalk Attendance.

use DingTalkDcatAdmin\DingDing\Attendance;
use DingTalkDcatAdmin\DingDing\DingTalkConfig;
use Psr\Log\LoggerInterface;
use Psr\SimpleCache\CacheInterface;

// Create config instance
$config = new DingTalkConfig($appKey, $appSecret, $cacheKey);

// Create Attendance instance
$attendance = new Attendance(
    $config, 
    $logger, // Optional, implements LoggerInterface
    $cache // Optional, implements CacheInterface
);

// Check if smart report is open
$isOpen = $attendance->isOpenSmartReport();

// Get attendance columns
$columns = $attendance->getAttendanceColumns();

// Get attendance report by day
$result = $attendance->getAttendanceReportByDay($userId, $workDate);

// Get attendance column values
$columnVals = $attendance->getColumnVal($userId, $workDate, $columnIds);

Configuration

DingTalkConfig

The DingTalkConfig class accepts the following parameters:

• $appKey: The DingTalk app key
• $appSecret: The DingTalk app secret
• $cacheKey: Used for caching access tokens

DDAccessToken

The DDAccessToken::make method accepts the following parameters:

• $config: Instance of DingTalkConfig containing appKey and appSecret
• $cache: Optional, implements Psr\SimpleCache\CacheInterface for caching access tokens
• $logger: Optional, implements Psr\Log\LoggerInterface for logging

YiDa

The YiDa constructor accepts the following parameters:

• $config: Instance of DingTalkConfig containing appKey, appSecret, and optionally YiDa config
• $logger: Optional, implements Psr\Log\LoggerInterface for logging
• $cache: Optional, implements Psr\SimpleCache\CacheInterface for caching access tokens

Methods

DingTalkConfig

• __construct($appKey, $appSecret, $cacheKey): Create a new config instance
• setYiDaConfig($appType, $systemToken): Set YiDa configuration
• getAppKey(): Get appKey
• getAppSecret(): Get appSecret
• getCacheKey(): Get cacheKey
• getYiDaAppType(): Get YiDa appType
• getYiDaSystemToken(): Get YiDa systemToken

DDAccessToken

• make($config, $cache = null, $logger = null): Get access token using DingTalkConfig

YiDa

• __construct($config, $logger = null, $cache = null): Create a new YiDa instance
• saveProcessForm($userId, $formUuid, $processCode, $formDataJson): Save process form
• updateProcessForm($userId, $processInstanceId, $formDataJson): Update process form
• batchSaveForm($userId, $formUuid, $formDataJsonList): Batch save form data
• saveForm($userId, $formUuid, $formDataJson, $searchs = []): Save form data
• updateForm($userId, $formUuid, $formInstanceId, $formDataJson): Update form data
• searchForm($userId, $formUuid, $searchs = [], $extParams = [], $dynamicOrder = ''): Search form data
• getInstanceData($userId, $formUuid, $id): Get form instance data
• searchFormList($userId, $formUuid, $searchFields = [], $pageSize = 100, $pageNumber = 1): Advanced search form list
• getFormListByAppId($userId, $formTypes = 'receipt,process', $pageSize = 100, $pageNumber = 1): Get form list by app ID
• getFormFieldsByFormUuid($userId, $formUuid): Get form fields by form UUID

Attendance

• __construct($config, $logger = null, $cache = null): Create a new Attendance instance
• isOpenSmartReport(): Check if smart report is open
• getAttendanceColumns(): Get attendance columns
• getAttendanceReportByDay($userId, $workDate): Get attendance report by day for a user
• getColumnVal($userId, $workDate, $columnIds): Get attendance column values
  • Returns example:

    {
        "errcode": 0,
        "result": {
            "column_vals": [
                {
                    "column_vals": [
                        {
                            "date": "2020-09-07 00:00:00",
                            "value": "1.0"
                        },
                        {
                            "date": "2020-09-08 00:00:00",
                            "value": "1.0"
                        },
                        {
                            "date": "2020-09-09 00:00:00",
                            "value": "1.0"
                        }
                    ],
                    "column_vo": {
                        "id": 129339038
                    }
                }
            ]
        },
        "request_id": "45n2azecqj21"
    }
    

Dependencies

• PHP >= 7.4
• guzzlehttp/guzzle ^7.0
• alibabacloud/sdk ^2.0
• psr/log ^1.1 || ^2.0 || ^3.0
• psr/simple-cache ^1.0 || ^2.0 || ^3.0

License

The MIT License (MIT). Please see License File for more information.