README

通用工具，简单集成到任何项目中。

索引

• 需求：使用此组件所需的要求。
• DataTrait：创建自定义配置类的一个特性。
• 数据：使用DataTrait的类，可以从头开始使用。
• OptionsTrait：一个特性，用于向类中添加简单的选项API。
• 系统服务：此服务提供了一个简单的API来与系统交互，包括执行CLI命令、创建目录等方法。
• 示例文件：我们提供的一组示例PHP文件列表，您可以通过它们了解如何使用此组件的功能。

需求

• PHP 7.2+

DataTrait

此特性提供了强大的API来访问和操作数组中的数据。它有简单的方法来访问/设置/检查数组中任何深度的元素的存在。

注意：此特性使用OptionsTrait。

用法

<?php

require_once('/path/to/autoload.php');

use IronEdge\Component\CommonUtils\Data\DataTrait;

class YourClass
{
    use DataTrait;


    // You need to implement this method to set the
    // default options of OptionsTrait

    public function getDefaultOptions()
    {
        return [
            'enabled'       => true
        ];
    }
}

$yourClass = new YourClass();

// Set the initial data

$originalData = [
    'user' => [
        'id'        => '123456',
        'username'  => 'foo',
        'profile'   => 'custom_profile',
        'groups'    => [
            'primary'       => 'administrator',
            'secondary'     => ['development']
        ]
    ],
    'defaultUser'   => '%my_username%',
    'allowedIps'    => [
        '127.0.0.1'     => [
            'grants'        => 'all'
        ]
    ]
];

$yourClass->setData($originalData);

// Obtain user array. Result: ['id' => '123456', 'username' => 'foo', 'profile' => ... ]

$yourClass->get('user');

// Obtain data at any depth. Result: 'administrator'

$yourClass->get('user.groups.primary');

// Use default value if an attribute is not set. Result: 'defaultValue'

$yourClass->get('iDontExist', 'defaultValue');

// Check if an attribute exist. Result: true

$yourClass->has('user.groups.primary');

// This time, it returns: false

$yourClass->has('user.groups.admin');

// You can use template variables that will be replaced
// when you set the data.

// First, it returns: '%my_username%'

$yourClass->get('defaultUser');

$yourClass->setOptions(
    [
        'templateVariables'         => [
            '%my_username%'             => 'admin'
        ]
    ]
);

// We need to set the data again so the template variables get replaced.

$yourClass->setData($originalData);

// Now it returns: 'admin'

$yourClass->get('defaultUser');

// By default, element separator is '.'. You can change it
// overriding the default options, or on demand like in the following code.
// It should return: 'all'

$yourClass->get('allowedIps|127.0.0.1|grants', null, ['separator' => '|']);

// ------------------
// Get a casted value
// ------------------

// Returns an int value: 1234

$yourClass->getInt('user.id');

// Returns a float value: 1234

$yourClass->getFloat('user.id');

// Returns a string value: '1234'

$yourClass->getString('user.id');

// Returns a boolean value: true

$yourClass->getBoolean('user.id');

Data

我们还包含一个使用DataTrait的类。

<?php

require_once('/path/to/autoload.php');

use IronEdge\Component\CommonUtils\Data\Data;

$myData = new Data(
    [
        'myParameter'   => 'myValue'
    ]
);

// Should return 'myValue'.

$myData->get('myParameter');

OptionsTrait

此特性允许您向类中添加简单的选项API。

用法

<?php

require_once('/path/to/autoload.php');

use IronEdge\Component\CommonUtils\Options\OptionsTrait;

class YourClass
{
    use OptionsTrait;


    // You need to implement this method to set the
    // default options of OptionsTrait

    public function getDefaultOptions()
    {
        return [
            'enabled'       => true
        ];
    }
}

$yourClass = new YourClass();

// true

$yourClass->getOption('enabled');

// 'defaultValue'

$yourClass->getOption('iDontExist!', 'defaultValue');

// Set new options.

$yourClass->setOptions(['newOption' => 'newValue']);

// true - 'enabled' is still present as it's a default option.

$yourClass->hasOption('enabled');

// true

$yourClass->getOption('enabled');

// 'newValue'

$yourClass->getOption('newOption');

// ['enabled' => true, 'newOption' => 'newValue']

$yourClas->getOptions();

系统服务

此服务提供了一个API来执行常见的系统操作。它通过抽象PHP函数的使用，允许您以面向对象的方式使用它们，并添加了许多有用的额外工具。

命令执行:

<?php

use \IronEdge\Component\CommonUtils\System\SystemService;

$systemService = new SystemService();

// Simple usage. Returns: ['Hello world!']
$output = $systemService->executeCommand('echo "Hello world!"');

// Escape arguments: Returns: ['Hello world!']
$output = $systemService->executeCommand('echo', ['Hello', 'world!']);

// Returns last executed command, including escaped arguments
$systemService->getLastExecutedCommand();

// Returns last executed command's arguments
$systemService->getLastExecutedCommandArguments();

// Returns last executed command's options
$systemService->getLastExecutedCommandOptions();

// Returns last executed command's exit code
$systemService->getLastExecutedCommandExitCode();

// Returns last executed command's output
$systemService->getLastExecutedCommandOutput();

// Exception when a command fails
try {
    $systemService->executeCommand('invalid command!');
} catch (\IronEdge\Component\CommonUtils\Exception\CommandException $e) {
    // Returns exit code
    $e->getCode();

    // Returns last executed command, including escaped arguments
    $e->getCmd();

    // Returns the array of arguments
    $e->getArguments();

    // Returns command output
    $e->getOutput();
}

// You can pass several options to the "executeCommand" method:

// Option "returnString" returns a string instead of an array. It
// uses option "implodeSeparator" as the separator used by "implode"
// function. By default, we use PHP_EOL.
//
// Result: "a\nb"

$output = $systemService->executeCommand(
    'echo a && echo b',
    [],
    [
        'returnString'      => true
    ]
);

// Same example, by with a different implode separator.
//
// Result: a,b

$output = $systemService->executeCommand(
    'echo a && echo b',
    [],
    [
        'returnString'      => true,
        'implodeSeparator'  => ','
    ]
);

// In the case you pass arguments as the second argument of this method,
// you can use option "postCommand" to set, for example, a redirection

$output = $systemService->executeCommand(
    'echo a',
    [],
    [
        'postCommand' => '>> /tmp/my_file'
    ]
);

// Returns: "echo a >> /tmp/my_file"

$systemService->getLastExecutedCommand();

示例文件

使用此组件，我们提供了一组实现此组件功能的简单示例PHP文件。您可以直接在示例目录中执行它们

cd resources/examples;

# Replace here "example-file.php" with the example file name you want to execute.

php example-file.php;

• resources/examples/data.php：展示了Data类的用法。
• resources/examples/options.php：展示了OptionsTrait的用法。
• resources/examples/system-service.php：展示了系统服务的用法。

安装

执行以下命令使用composer安装此组件

cd /path/to/your/project;

composer require ironedge/common-utils;