README

[[目录]]

概述

Datadumper包帮助您解析和保存CSV、JSON和YAML格式的平面文件到本地磁盘、S3存储桶或提交到Git仓库。您还可以将数据数组推送到Google Sheets并替换现有数据或添加新行。

此包包括带有更改日志追加功能的清单创建功能。

此包由开源社区维护，不由任何公司维护。请自行承担风险，并为您遇到的任何错误创建合并请求。

问题陈述

当在平面文件中处理大量数据数组时，您可能需要支持多种格式（例如CSV、JSON、YAML）。在您努力保持这些文件与最新数组数据同步的同时，您还需要能够更新现有文件并检查任何应该记录的差异。

此包最初是为从Okta API获取用户目录并监视用户属性更改而创建的，但此包可能对广泛的通用用例都有帮助。

问题跟踪和错误报告

我们不维护功能请求路线图，但我们邀请您贡献，我们将乐意审查您的合并请求。

请创建问题来报告错误。

贡献

请参阅CONTRIBUTING.md以了解有关如何贡献的更多信息。

维护者

贡献者信用

• Jeff Martin

安装

需求

升级指南

请参阅changelog以获取发行说明。

添加Composer包

composer require provisionesta/datadumper

如果您正在为此包做出贡献，请参阅CONTRIBUTING.md以获取配置带有符号链接的本地Composer包的说明。

发布配置文件

这是可选的。配置文件指定了用于各种配置的.env变量名称。

php artisan vendor:publish --tag=datadumper

解析文件

解析CSV、JSON或YAML文件时，内容将作为数组返回。如果您设置了key参数，则将创建一个集合，数组将使用命名的参数键入，而不是整数。

解析CSV文件

use Provisionesta\Datadumper\Csv;

$data = Csv::parse(
    file_path: 'folder-name/file-name.csv',
    event_type: null,
    key_by: 'id'
);

解析JSON文件

use Provisionesta\Datadumper\Json;

$data = Json::parse(
    file_path: 'folder-name/file-name.json',
    event_type: null,
    key_by: 'id'
);

解析YAML文件

use Provisionesta\Datadumper\Yaml;

$data = Yaml::parse(
    file_path: 'folder-name/file-name.yaml',
    event_type: null,
    key_by: 'id'
);

解析Google Sheets

use Provisionesta\Datadumper\GoogleSheet;

$data = GoogleSheet::parse(
    sheet: '1ga1b2c3d4e5f6g7h8i9h0i1j2k3l4m5n6o7p8q9r0s1',
    tab: 'Sheet 1'
    // connection:
);

解析GitLab仓库文件

use Provisionesta\Datadumper\Gitlab;
use Symfony\Component\Yaml\Yaml as SymfonyYaml;

$file_contents = Gitlab::parse(
    project: 'group-path/child-group-path/project-path',
    file_path: 'folder/filename.json'
    branch: 'main'
    // connection:
);

// Parse JSON File
$data = json_decode($file_contents);

use Symfony\Component\Yaml\Yaml as SymfonyYaml;

// Parse YAML File
$data = collect(SymfonyYaml::parse($file_contents));

保存文件

您可以使用此包同时将相同的数组保存到多种格式，或者分别保存每种格式。当解析现有数据以创建清单时，将使用JSON格式，并重新生成和保存更新的CSV和YAML。

将多种格式保存到磁盘

use Provisionesta\Datadumper\Disk;

// $data =

// Override existing files
Disk::save(
    data: $data,
    file_path: 'folder/filename',
    event_type: null,
    key_by: 'id',
    csv: true
    json: true
    yaml: true
);

use Provisionesta\Datadumper\Disk;

// $data =

// Append existing files
Disk::append(
    data: $data,
    file_path: 'folder/filename',
    event_type: null,
    key_by: 'id',
    csv: true
    json: true
    yaml: true
);

将多种格式保存到GitLab仓库

use Provisionesta\Datadumper\GitlabCommit;

// $data =

GitlabCommit::save(
    data: $data,
    file_path: 'folder/filename',
    project: 'group-path/child-group-path/project-path',
    commit_branch: 'main', // A new branch will be created if it doesn't exist
    source_branch: 'main',
    commit_message: 'Auto-generated commit by the datadumper package',
    // connection:
    event_type: null,
    key_by: 'id',
    csv: true
    json: true
    yaml: true
);

保存CSV文件

use Provisionesta\Datadumper\Csv;

// You can create an array however you want. CSV files should have values only.
$data = collect($records)->transform(fn($item) => array_values($item))->toArray();

$file_contents = Csv::save(
    file_path: 'folder-name/file-name.csv',
    data: $data,
    event_type: null
);

保存JSON文件

use Provisionesta\Datadumper\Json;

// $data =

$file_contents = Json::save(
    file_path: 'folder-name/file-name.json',
    data: $data,
);

保存YAML文件

use Provisionesta\Datadumper\Yaml;

// $data =

$file_contents = Yaml::save(
    file_path: 'folder-name/file-name.yaml',
    data: $data,
);

清单和更改日志

此包包括全面的差异检测和更改日志生成。当从API获取更新数据并与现有平面文件数据进行状态更改比较时，这对于特定属性字段的比较非常有用。

use Provisionesta\Datadumper\Manifest;
use Provisionesta\Okta\ApiClient;

// An array of attribute keys to compare for changes
$attributes = ['title', 'department', 'manager'];

$data = ApiClient::get('users')->data;

// Local or S3 Disk Files
Manifest::make()->handle(
    attributes: $attributes,
    data: $data,
    file_path: 'okta/users',
    key_by: 'id',
    reference_key: 'email'
    driver: disk
    csv: true
    json: true
    yaml: true
);

// GitLab Repository Files
Manifest::make()->handle(
    attributes: $attributes,
    data: $data,
    file_path: 'okta/users',
    key_by: 'id',
    reference_key: 'email'
    git_commit_branch: 'main',
    git_commit_message: 'Auto-generated commit by the datadumper package',
    git_source_branch: 'main'
    // connection:
    driver: gitlab
    gitlab_project: '12345678',
    csv: true
    json: true
    yaml: true
);

环境变量

默认启用Google Sheets，如需禁用则可进行操作。这使用了provisionesta/google-api-client包。

DATADUMPER_GOOGLE_SHEET_ENABLED=true

当使用Google Sheets时，您将使用一个包含一个或多个OAuth2作用域的JSON API密钥，其中包括与Google Sheets工作所需的作用域之一（例如：https://www.googleapis.com/auth/{scope_suffix}）。请将此设置为密钥已授予的作用域后缀。

DATADUMPER_GOOGLE_SHEET_SCOPE="drive"
# DATADUMPER_GOOGLE_SHEET_SCOPE="drive.file"
# DATADUMPER_GOOGLE_SHEET_SCOPE="spreadsheets"

变更日志日期格式

当生成变更日志文件时，它将在与清单相同的目录下生成，格式为changelog/{date_format}.csv|json|yml。默认格式为Y-m（例如：2024-01）。您可以自定义任何想要的格式（例如：每日、季度等），当生成变更日志时，它使用Carbon生成指定格式的时间戳，并检查是否存在同名文件或创建一个新文件。

DATADUMPER_MANIFEST_CHANGELOG_DATE_FORMAT="Y-m"

文件系统驱动器

当生成清单时，您可以选择将清单保存到默认的Laravel文件系统磁盘（例如：FILESYSTEM_DISK=local或FILESYSTEM_DISK=s3）或GitLab仓库。建议从disk开始进行初始测试。

DATADUMPER_MANIFEST_FILE_DRIVER=disk
# DATADUMPER_MANIFEST_FILE_DRIVER=gitlab

GitLab连接

如果您使用GitLab驱动器，则需要指定具有对将提交文件的GitLab项目的访问权限的API凭证。在大多数情况下，这应该是一个项目访问令牌，除非您有具有有限权限的应用程序机器人或服务账户用户，这些权限仅限于您的应用程序使用的项目。出于安全原因，请不要使用个人访问令牌。

如果您不使用针对不同项目和权限的其他GitLab API调用，则可以使用GitLab API客户端变量。

在创建API令牌之前，请参阅安全最佳实践。

GITLAB_API_URL="https://gitlab.com"
GITLAB_API_TOKEN="glpat-a1b2c3d4e5f6g7h8i9j0"

如果您已经执行了GitLab API调用并希望使用不同的用户帐户或API令牌进行清单的读写更改或在不同的GitLab实例上，则可以使用DATADUMPER_MANIFEST_GITLAB_*变量。如果没有设置，这些将自动使用GITLAB_API_*变量。

DATADUMPER_MANIFEST_GITLAB_URL="https://gitlab.com"
# DATADUMPER_MANIFEST_GITLAB_URL="https://gitlab.example.com"
DATADUMPER_MANIFEST_GITLAB_TOKEN="glpat-a1b2c3d4e5f6g7h8i9j0"

对于高级连接用例，您还可以将配置在别处的数组传递给connection:或gitlab_connection:参数。出于安全原因，此数组应访问环境变量、机密管理器值或数据库中的加密值。

// config/services.php
[
    // ...
    'gitlab' => [
        'manifests' => [
            'url' => env('GITLAB_MANIFESTS_URL'),
            'token' => env('GITLAB_MANIFESTS_TOKEN')
        ]
    ]
    // ...
]

use Provisionesta\Datadumper\Gitlab;

$gitlab_file = GitLab::parse(
    project: 'group-path/child-group-path/project-name',
    file_path: 'folder-name/filename.json',
    branch: 'main',
    connection: config('services.gitlab.manifests')
);

$file_array = json_decode($gitlab_file);