README

Common utilities, simple to integrate in any project.

Index

Requirements: These are the requirements to use this component.
DataTrait: A Trait to create your own configuration classes.
Data: A class using DataTrait so you can start using it right from scratch.
OptionsTrait: A Trait to add a simple options API to your classes.
System Service: This service provides a simple API to interact with your system, with methods to execute CLI commands, create directories, etc.
Example Files: A list of example PHP files that we provide so you can see how to use the features of this component.

Requirements

PHP 7.2+

DataTrait

This trait gives you a powerful API to access and manipulate data in an array. It has simple methods to access / set / check of presence of elements at any depth in an array.

NOTE: This trait uses OptionsTrait.

Usage:

<?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

We also include a class that already uses the 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

This trait allows you to add a simple Options API to your classes.

Usage:

<?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();

System Service

This service provides an API to common system operations. It abstracts away the usage of PHP functions to allow you to use them in an OOP way, and adds a lot of useful additional tools.

Command Execution:

<?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();

Example Files

With this component we provide a set of simple example PHP files implementing the features of this component. You can just go to the examples directories and execute them:

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: Shows the usage of the Data class.
resources/examples/options.php: Shows the usage of the OptionsTrait.
resources/examples/system-service.php: Shows the usage of the System Service.

Installation

Execute the following command to install this component with composer:

cd /path/to/your/project;

composer require ironedge/common-utils;

ironedge / common-utils

Maintainers

Details