README

Installation
Features
Examples
Quality
Contribute
Authors
License

Installation

Use Composer to install the package:

$ composer require jimmyoak/utilities

For PHP 5.3 compatibility use *.*.*b versions (yep, I marked them as beta versions):

$ composer require jimmyoak/utilities:2.5.1b

Features

Collection and Set utilities (Typed/Untyped collections and sets)
Enum base class
SimpleValueObject base class
Event publisher
Array utilities
File utilities
String utilities

Examples

Collections

Collection

$collection = new \JimmyOak\Collection\Collection();
$collection[] = 'Foo';
$collection[] = 'Bar';

foreach ($collection as $value) {
    echo $value . ' ';
}

//prints: Foo Bar

TypedCollection

$collection = new \JimmyOak\Collection\TypedCollection(\DateTime::class);
$collection[] = new \DateTime();
$collection[] = new \DateInterval('P1D'); //Throws \JimmyOak\Exception\Collection\NotValidObjectTypeException

Set

You can fill the collection with object, scalars...

$collection = new \JimmyOak\Collection\Set();
$collection[] = 'Foo';
$collection[] = 'Foo';
$collection[] = 'Bar';

foreach ($collection as $value) {
    echo $value . ' ';
}

//prints: Foo Bar

TypedSet

You can fill the collection with object, scalars...

$collection = new \JimmyOak\Collection\TypedSet(\DateTime::class);
$aDateTime = new \DateTime('1992-10-07');
$collection[] = $aDateTime;
$collection[] = $aDateTime;
try {
    $collection[] = new \DateInterval('P1D'); //throws \JimmyOak\Exception\Collection\NotValidObjectTypeException
} catch (\JimmyOak\Exception\Collection\NotValidObjectTypeException $e) {
    //Do nothing ^^'
}

foreach ($collection as $value) {
    echo $value->format('Y-m-d') . ' ';
}

//prints: 1992-10-07

Of course you can hipervitaminate these classes:

class DateTimeCollection extends \JimmyOak\Collection\TypedSet
{
    public function __construct() {
        $this->setObjectType(\DateTime::class);
    }
    
    public function asStrings()
    {
        $dates = [];
        foreach ($this as $value) {
            $dates[] = $value->format('Y-m-d');
        }
        
        return $dates;
    }
}

$dateTimeCollection = new \DateTimeCollection();
$aDateTime = new \DateTime('1992-10-07');
$dateTimeCollection[] = $aDateTime;
$dateTimeCollection[] = $aDateTime;
$dateTimeCollection[] = new \DateTime('1992-09-08');

foreach ($dateTimeCollection->asStrings() as $dateTimeString) {
    echo $dateTimeString . ' - ';
}

// prints: 1992-10-07 - 1992-09-08 -

EventPublisher

class MessageEvent extends Event
{
    private $message;

    public function __construct($message)
    {
        parent::__construct();
        $this->message = $message;
    }

    public function getMessage()
    {
        return $this->message;
    }
}

class MessageSubscriber extends EventSubscriber
{
    public function isSubscribedTo(Event $event)
    {
        return $event instanceof MessageEvent;
    }

    public function handle(Event $event)
    {
        printf(
            '[%s]: %s %s',
            $event->getOccurredOn()->format('Y-m-d H:i:s'),
            $event->getMessage(),
            PHP_EOL
        );
    }
}

SingleEventPublisher::instance()
    ->subscribe(new MessageSubscriber())
    ->publish(new MessageEvent('Hi!'))
    ->publish(new MessageEvent('Bye!'));

DataType

Enum

class FuelType extends \JimmyOak\DataType\Enum
{
    const GASOLINE = 'gasoline';
    const DIESEL = 'diesel';
    const KEROSENE = 'kerosene';
}

echo 'Available fuels: ' . PHP_EOL;
foreach (FuelType::getConstList() as $constName => $value) {
    echo $constName . ' => ' . $value . PHP_EOL;
}

echo PHP_EOL;
//prints:
// Available fuels:
// GASOLINE => gasoline
// DIESEL => diesel
// KEROSENE => kerosene

$gasoline = new FuelType(FuelType::GASOLINE);
echo $gasoline->value() . PHP_EOL; //prints: 'gasoline'
echo (string) $gasoline . PHP_EOL; //prints: 'gasoline'

$nonExistentFuelType = new FuelType('grass'); //throws \InvalidArgumentException

SimpleValueObject

class Amount extends \JimmyOak\DataType\SimpleValueObject
{
    public function add(Amount $amount) {
        return $this->mutate($this->value() + $amount->value());
    }
}

$amount = new \Amount(500);
echo (string) $amount . PHP_EOL; //prints: 500
echo $amount->value() . PHP_EOL; //prints: 500

$anotherAmount = new \Amount(700);
echo ($amount->equals($anotherAmount) ? 'EQUAL' : 'NOT EQUAL') . PHP_EOL; //prints: NOT EQUAL

$newAmount = $amount->add(new Amount(200));
echo $amount->value() . PHP_EOL; //prints: 500
echo $newAmount->value() . PHP_EOL; //prints: 700

echo ($anotherAmount->equals($newAmount) ? 'EQUAL' : 'NOT EQUAL') . PHP_EOL; //prints: EQUAL

Utility

ArrayUtils

Flatten

$array = [
    'FOO',
    [ 'BAR' ],
    'CHILDREN' => [
        'FOO2' => 'FOOBAR',
        'BAR2' => 'FOOBAR2',
        [
            'FOO2' => 'FOOBAR3'
        ]
    ]
];

$notPreservedKeys = \JimmyOak\Utility\ArrayUtils::instance()->flatten($array, \JimmyOak\Utility\ArrayUtils::NO_PRESERVE_KEYS);
// Overrides existing keys (overrides keys 0 and FOO2 existing in children)
$preservedKeys = \JimmyOak\Utility\ArrayUtils::instance()->flatten($array, \JimmyOak\Utility\ArrayUtils::PRESERVE_KEYS);
// Overrides only ASSOCIATIVE KEYS
$preservedAssociativeKeys = \JimmyOak\Utility\ArrayUtils::instance()->flatten($array, \JimmyOak\Utility\ArrayUtils::PRESERVE_ASSOCIATIVE_KEYS);

var_export($notPreservedKeys);
echo PHP_EOL . PHP_EOL;
var_export($preservedKeys);
echo PHP_EOL . PHP_EOL;
var_export($preservedAssociativeKeys);

// prints:
// array (
//   0 => 'FOO',
//   1 => 'BAR',
//   2 => 'FOOBAR',
//   3 => 'FOOBAR2',
//   4 => 'FOOBAR3',
// )
// 
// array (
//   0 => 'BAR',
//   'FOO2' => 'FOOBAR3',
//   'BAR2' => 'FOOBAR2',
// )
// 
// array (
//   0 => 'FOO',
//   1 => 'BAR',
//   'FOO2' => 'FOOBAR3',
//   'BAR2' => 'FOOBAR2',
// )

ToXmlString and ToXml

$array = [
    'details' => [
        'media' => [
            'image' => [
                'anImage.png',
                'anotherImage.png',
            ],
            'video' => 'aVideo.mp4',
            'audio' => [],
        ]
    ]
];

$xml = \JimmyOak\Utility\ArrayUtils::instance()->toXmlString($array);
echo $xml . PHP_EOL . PHP_EOL;

// prints: <?xml version="1.0" encoding="UTF-8"? ><details><media><image>anImage.png</image><image>anotherImage.png</image><video>aVideo.mp4</video><audio/></media></details>

// Converts array into SimpleXmlElement
$xml = \JimmyOak\Utility\ArrayUtils::instance()->toXml($array);
var_dump($xml);

// prints:
// class SimpleXMLElement#3 (1) {
//     public $media =>
//     class SimpleXMLElement#4 (3) {
//         public $image =>
//         array(2) {
//             [0] =>
//             string(11) "anImage.png"
//             [1] =>
//             string(16) "anotherImage.png"
//         }
//         public $video =>
//         string(10) "aVideo.mp4"
//         public $audio =>
//         class SimpleXMLElement#5 (0) {
//         }
//     }
// }

ObjectUtils

ToArray

class Foo
{
    public $public = 'public';
    protected $protected = 'protected';
    private $private = 'private';
    private $anObject;

    /**
     * Foo constructor.
     *
     * @param $anObject
     */
    public function __construct($anObject)
    {
        $this->anObject = $anObject;
    }
}

class Bar
{
    private $value = 'value';
}

$foo = new Foo(new Bar());

//Shallow
$arrayed = \JimmyOak\Utility\ObjectUtils::instance()->toArray($foo, \JimmyOak\Utility\ObjectUtils::SHALLOW);
var_export($arrayed);
// prints:
//array (
//    'public' => 'public',
//)

echo PHP_EOL . PHP_EOL;

//Deep
$arrayed = \JimmyOak\Utility\ObjectUtils::instance()->toArray($foo, \JimmyOak\Utility\ObjectUtils::DEEP);
var_export($arrayed);
// prints:
//array (
//    'public' => 'public',
//    'protected' => 'protected',
//    'private' => 'private',
//    'anObject' =>
//        array (
//            'value' => 'value',
//        ),
//)

ToXmlString and ToXml

Note: ToXml would do the same but returns a SimpleXml object

class Foo
{
    public $public = 'public';
    protected $protected = 'protected';
    private $private = 'private';
    private $anObject;

    /**
     * Foo constructor.
     *
     * @param $anObject
     */
    public function __construct($anObject)
    {
        $this->anObject = $anObject;
    }
}

class Bar
{
    private $value = 'value';
}

$foo = new Foo(new Bar());

$xml = \JimmyOak\Utility\ObjectUtils::instance()->toXmlString($foo, \JimmyOak\Utility\ObjectUtils::SHALLOW);
echo $xml . PHP_EOL;
// prints: <?xml version="1.0" encoding="UTF-8"? ><public>public</public>

$xml = \JimmyOak\Utility\ObjectUtils::instance()->toXmlString($foo, \JimmyOak\Utility\ObjectUtils::DEEP);
echo $xml . PHP_EOL;
// prints: <?xml version="1.0" encoding="UTF-8"? ><public>public</public><protected>protected</protected><private>private</private><anObject><value>value</value></anObject>

StringUtils

BeginsWith

echo (\JimmyOak\Utility\StringUtils::instance()->beginsWith('Foo', 'fo') ? 'true' : 'false') . PHP_EOL;
//prints: false
echo (\JimmyOak\Utility\StringUtils::instance()->beginsWith('Foo', 'fo', \JimmyOak\Utility\StringUtils::CASE_INSENSITIVE) ? 'true' : 'false') . PHP_EOL;
//returns: true

echo (\JimmyOak\Utility\StringUtils::instance()->beginsWith('Fóo', 'Fo') ? 'true' : 'false') . PHP_EOL;
//prints: false
echo (\JimmyOak\Utility\StringUtils::instance()->beginsWith('Fóo', 'Fo', \JimmyOak\Utility\StringUtils::ACCENT_INSENSITIVE) ? 'true' : 'false') . PHP_EOL;
//returns: true

echo (\JimmyOak\Utility\StringUtils::instance()->beginsWith(
        'Fóo',
        'fo',
        \JimmyOak\Utility\StringUtils::ACCENT_INSENSITIVE | \JimmyOak\Utility\StringUtils::CASE_INSENSITIVE
    ) ? 'true' : 'false') . PHP_EOL;
//returns: true

EndsWith

Same behaviour as beginsWith but with ending needle.

RemoveAccents

echo \JimmyOak\Utility\StringUtils::instance()->removeAccents('Fóôñ');
// prints: Foon

RemoveExtraSpaces

echo \JimmyOak\Utility\StringUtils::instance()->removeExtraSpaces('  Foo    Bar     ');
// prints: Foo Bar

IsUrl and IsEmail

echo (\JimmyOak\Utility\StringUtils::instance()->isUrl('http://github.com/jimmyoak') ? 'true' : 'false') . PHP_EOL;
// prints: true

echo (\JimmyOak\Utility\StringUtils::instance()->isUrl('github.com/jimmyoak') ? 'true' : 'false') . PHP_EOL;
// prints: false

echo (\JimmyOak\Utility\StringUtils::instance()->isEmail('adrian.robles.maiz@gmail.com') ? 'true' : 'false') . PHP_EOL;
// prints: true

echo (\JimmyOak\Utility\StringUtils::instance()->isEmail('adrian.robles.maiz') ? 'true' : 'false') . PHP_EOL;
// prints: false

FileUtils

ExtensionIs

echo (\JimmyOak\Utility\FileUtils::instance()->extensionIs('foo.php', 'php') ? 'true' : 'false') . PHP_EOL;
// prints: true

echo (\JimmyOak\Utility\FileUtils::instance()->extensionIs('foo.php', 'bar') ? 'true' : 'false') . PHP_EOL;
// prints: false

MakePath

echo \JimmyOak\Utility\FileUtils::instance()->makePath('/some', 'awesome/', 'and/incredible', 'nice.file');
// prints: /some/awesome/and/incredible/nice.file

GetExtension

echo \JimmyOak\Utility\FileUtils::instance()->getExtension('file.php');
// prints: php

GetNameWithoutExtension

echo \JimmyOak\Utility\FileUtils::instance()->getExtension('file.php');
// prints: file

ScanDir

See FileUtilsTest better :P

Quality

To run the PHPUnit tests at the command line, go to the tests directory and issue phpunit.

This library attempts to comply with PSR-2 and PSR-4.

If you notice compliance oversights, please send a patch via pull request.

Contribute

Contributions to the package are always welcome!

Report any bugs or issues you find on the issue tracker.
You can grab the source code at the package's Git repository.

Authors

[Adrián Robles Maiz (a.k.a Jimmy K. Oak)] (http://github.com/jimmyoak)

License

The code base is licensed under the MIT license.

jimmyoak / utilities

Maintainers

Details

README

Installation

Features

Examples

Collections

Collection

TypedCollection

Set

TypedSet

EventPublisher

DataType

Enum

SimpleValueObject

Utility

ArrayUtils

Flatten

ToXmlString and ToXml

ObjectUtils

ToArray

ToXmlString and ToXml

StringUtils

BeginsWith

EndsWith

RemoveAccents

RemoveExtraSpaces

IsUrl and IsEmail

FileUtils

ExtensionIs

MakePath

GetExtension

GetNameWithoutExtension

ScanDir

Quality

Contribute

Authors

License