nayjest/manipulator

Utilities for manipulating PHP objects

Manipulator (mp)

Small library for manipulating PHP objects., _(*1)

, _(*2)

, _(*3)

It's like symfony/property-access with more features, faster (no reflection usage) and without over-engineering (~300 lines of code, few functions)., _(*4)

Requirements

• PHP 5.4+ (hhvm & php7 are supported)

Installation

The recommended way of installing the component is through Composer., _(*5)

Run following command:, _(*6)

composer require nayjest/manipulator

Usage

Function mp\instantiate

Creates class instance using specified constructor arguments., _(*7)

Arguments

• string $class — Target class name
• array $arguments — Constructor arguments (optional)

Returned Value

Function returns instantiated object, _(*8)

Example

    $user = \mp\instantiate(MyApp\User::class, [$firstArgument, $secondArgument]);

Function mp\setPublicProperties

Assigns values from array to existing public properties of target object., _(*9)

By default this function ignores fields having no corresponding properties in target object, but this behavior can be changed if TRUE will be passed to third argument., _(*10)

Arguments

• object $targetObject — target object
• array $fields — fields to assign, keys must be same as target object property names
• bool $createProperties — (optional, default value: false) allows to create new properties in target object if value is TRUE

Returned Value

Function returns array containing names of successfully assigned properties., _(*11)

Function mp\setValuesUsingSetters

Assigns values from array to corresponding properties of target object using setters., _(*12)

This function works similar to mp\setPublicProperties(), but uses setter methods instead of public properties., _(*13)

Field names may be in snake or camel case, it will be converted to camel case and prefixed by 'set' to check availability of corresponding setter in target object., _(*14)

Fields having no corresponding setters in target object will be ignored., _(*15)

This function does not work with magic setters created using __set() php method., _(*16)

Arguments

• object $instance — target object
• array $fields — fields to assign, keys are used to check availability of corresponding setters in target object

Returned Value

Function returns array containing names of successfully assigned properties., _(*17)

Example

use mp;

class Target
{
     private $somePropery;
     public function setSomeProperty($value)
     {
          $this->someProperty = $value;
     }

     public function getSomeProperty()
     {
          return $this->someProperty;
     }
}

$target = new Target;

$result = mp\setValuesUsingSetters($target, [
    'some_property' => 1, // 'someProperty' => 1 will also work
    'some_other_property' => 2
]);
# $target->setSomeProperty(1) will be called.
# Value of 'some_other_property' will be ignored since $target has no 'setSomeOtherProperty' setter.

echo $target->getSomeProperty(); // 1
var_dump($result); // array(0 => 'some_property')

Function mp\setValues

Assigns values from $fields array to $target. Target may be object or array., _(*18)

By default mp\setValues ignores fields having no corresponding properties or setters in target object but this behavior can be changed if MP_CREATE_PROPERTIES option is used., _(*19)

Assigning values using setters can be disabled by removing MP_USE_SETTERS option (it's enabled by default)., _(*20)

When target is an array, mp\setValues will call array_merge PHP function., _(*21)

Arguments

• object|array &$target — target object or array
• array $fields — fields to assign
• int $options (optional, default value: MP_USE_SETTERS) supported options: MP_USE_SETTERS, MP_CREATE_PROPERTIES

Returned Value

Function returns array containing names of successfully assigned properties., _(*22)

Example

use mp;

class Target
{
     private $property1;
     public $property2;
     public function setProperty1($value)
     {
          $this->property1 = $value;
     }
}

$target1 = new Target;
$target2 = new Target;
$target3 = new Target;
$target4 = new Target;

$fieldsToSet = [
    'property1' => 1,
    'property2' => 2,
    'property3' => 3,
];
$result1 = mp\setValues($target1, $fieldsToSet); // MP_USE_SETTERS by default
$result2 = mp\setValues($target1, $fieldsToSet, MP_USE_SETTERS | MP_CREATE_PROPERTIES);
$result3 = mp\setValues($target1, $fieldsToSet, MP_CREATE_PROPERTIES);
$result4 = mp\setValues($target1, $fieldsToSet, 0);

Results:, _(*23)

Function mp\getWritable

Returns names of writable properties for objects and classes or existing keys for arrays., _(*24)

Only public object properties and properties having setters considered writable., _(*25)

For setters, this function will return property names based on setter names (setter names are converted to snake case, 'set' prefixes are removed)., _(*26)

Detecting properties by setters can be disabled by specifying second argument as FALSE., _(*27)

Arguments

• object|string|array $target — object or class name or array
• bool $useSetters — (optional, default value: true) if true, properties having setters will be added to results

Returned Value

Array containing names of writable properties., _(*28)

Function mp\getMethodsPrefixedBy

Returns method names from target object/class that starts from specified keyword and followed by uppercase character., _(*29)

Arguments

• string $keyword — method name prefix
• object|string $target — object or class name

Returned Value

Array containing method names., _(*30)

Example

class MyClass {
    public function getProperty1(){};
    public function getProperty2(){};
}

$objectMethodNames = \mp\getMethodsPrefixedBy('get', $obj);  // will return methods of $obj that looks like getters
$classMethodNames = \mp\getMethodsPrefixedBy('get', 'MyClass');  // will return methods of 'MyClass' class that looks like getters.
// $classMethodNames will contain ['getProperty1', 'getProperty2']

Function mp\getSetters

Returns method names from target object/class that looks like setters., _(*31)

Arguments

• object|string $target — object or class name

Returned Value

Array containing method names., _(*32)

Function mp\getGetters

Returns method names from target object/class that looks like setters., _(*33)

Arguments

• object|string $target — object or class name

Returned Value

Array containing method names., _(*34)

Function mp\getValues

Returns values of object properties or array elements specified in $propertyNames argument., _(*35)

This function supports getters, i. e. value returned by getSomeValue() method of target object can be requested as 'some_value' property., _(*36)

Arguments

• object|array $src
• string[] $propertyNames

Returned Value

Array containing required values., _(*37)

Function mp\getValue

Extracts value specified by property / field / method name from object or array. This function supports property paths (prop1.prop2.prop3) and getters., _(*38)

• For $propertyName = 'prop_name', this function will try to extract data in following order from:, _(*39)

• $src['prop_name'], _(*40)
• $src->prop_name
• $src->getPropName()
• $src->prop_name()
• $src->isPropName()

Arguments

• array|object $src
• string $propertyName
• mixed $default — (optional, default value: null) default value
• string|null $delimiter — (optional, default value: '.') used to specify property paths

Function mp\getValueByRef

Extracts value specified by property / field / method name from object or array by reference if possible. This function acts like mp\getValue with only difference that value will be returned by reference if possible., _(*41)

Function mp\setValue

Assigns value, supports property paths (prop1.prop2.prop3)., _(*42)

Arguments

• array|object &$target
• string $propertyName
• mixed $value
• string|null $delimiter — (optional, default value: '.') used to specify property paths

Returned Value

This function returns TRUE if value was successfully assigned, FALSE otherwise, _(*43)

Testing

This package bundled with PhpUnit tests., _(*44)

Command for running tests:, _(*45)

composer test

Contributing

Please see Contributing Guidelines and Code of Conduct for details., _(*46)

License

© 2014 — 2016 Vitalii Stepanenko, _(*47)

Licensed under the MIT License., _(*48)

Please see License File for more information., _(*49)