# dingtalk-dcat-admin

**Repository Path**: 1575810034/dingtalk-dcat-admin

## Basic Information

- **Project Name**: dingtalk-dcat-admin
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-01
- **Last Updated**: 2025-12-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DingTalk DCat Admin

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

## Installation

You can install the package via composer:

```bash
composer require dingtalk/dcat-admin
```

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

```bash
composer require dingtalk/dcat-admin:dev-master
```

## Basic Usage

### DingTalkConfig

The `DingTalkConfig` class is used to encapsulate DingTalk configuration.

```php
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.

```php
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.

```php
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.

```php
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:
    ```json
    {
        "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](LICENSE.md) for more information.