ElegantElephant

ElegantElephant - small library of PHP primitives in EO style. Inspired by Cactoos from @yegor256.

Motivation

PHP was designed and created like a procedural language. Then PHP started support OOP paradigm, but it's not really pure OOP. We got classes but we still use them in a procedural way. This library enforces you to write real objects in a real OOP.

Principles

Getting started:

Requirements

• PHP >= 8.0

Installation

composer require maxonfjvipon/elegant-elephant

Snippets

To get flatten array:

// The result will be [0, 1, 2, 2, 3, 3, 4, 5]
(new ArrFlatten(
  [0, [1], [[2, 2], [3, 3]], [4, 5]],
  deep: 2
))->asArray();

To merge arrays:

/* 
 * If user is admin, result array will contain permissions field
 *
 * [
 *    'name' => ...,
 *    'age' => ...,
 *    'permissions' => [...],
 *    'projects' => [
 *       ['name' => ..., 'created_at' => ...],
 *       [...],
 *       ...
 *    ]
 * ]
 */
(new ArrMerged(
  [
    'name' => $user->name,
    'age' => $user->age,
  ],
  new ArrIf(
    $user->isAdmin(),
    ArrOf::func(fn () => [
      'permissions' => [...]
    ])
  ),
  new ArrObject(
    'projects',
    new ArrMapped(
      $projects,
      fn (Project $project) => [
        'name' => $project->name,
        'created_at' => $project->created_at
      ]
    ) 
  )
))-asArray();

To manipulate with a text:

// To lower case
(new TxtLowered(
  TxtOf::str("Hello")
))->asString();

// To upper case
(new TxtUpper("Hello"))->asString();

// Join texts, if $isAdmin === TRUE the result will be "Hello Admin" else "Hello username, what'up"
(new TxtJoined([
  "Hello ",
  // Conditional text, behaves like first text if condition is TRUE, like second otherwise
  new TxtCond(
    $isAdmin,
    "Admin"
    TxtOf::func(fn () => $user->name())
  ),
  // Conditional text, behaves like first text if condition is TRUE, like empty string otherwise
  new TxtIf(
    !$isAdmin,
    ", what's up"
  )
]))->asString();

To get first x from array of x y points:

$points = [['x' => 1, 'y' => 1], ['x' => 2, 'y' => 2], [...], ...];

NumOf::any(
  new AtKey(
    'x',
    ArrOf::any(
      new FirstOf(
        $points
      )
    ) 
  )
)->asNumber(); // 1

To get length of filtered array:

(new LengthOf(
  new ArrFiltered(
    [1, 2, 3, 4, 5, 6],
    fn (int $num) => $num > 3
  )
))->asNum(); // 3

Complicated example from commercial project with no visible algorithm:

(new AtKey(                                                   // 12. Get element by key "pump" from given array
  'pump',
  ArrOf::any(                                                 // 11. Try to cast given element to array
    new FirstOf(                                              // 10. Get first element of given array
      new ArrCond(                                            // 9.1. If given sorted jockey pumps are not empty - take them
        new Not(
          new IsEmpty(
            $jockeyPumps = new ArrSticky(                     // 8. Cache given sorted jockey pumps
              new ArrSorted(                                  // 7. Sort given mapped jockey pumps by "cost" key
                new ArrMapped(                                // 6. Map given jockey pumps
                  new ArrCond(                                // 5.1. If optimized jockey pumps are not empty - take them
                    new Not(
                      new IsEmpty(
                        $optimized = new ArrSticky(           // 4. Cached optimized jockey pumps
                          new ArrFiltered(                    // 3. Filter cached jockey pumps with optimization
                            $dbPumps = new ArrSticky(         // 2. Cache jockey pumps
                              new ArrPumpsForJockeySelecting( // 1. Take jockey pumps from somewhere
                                $request->jockey_series_ids,
                                $request->accounting_rests
                              )
                            ),
                            $filterPump(threeFifths: true)
                          )
                        )
                      )
                    ),
                    $optimized,
                    new ArrFiltered(                           // 5.2. If opmtimized jockey pumps are empty - filter jockey pumps without optimization
                      $dbPumps,
                      $filterPump(threeFifths: false)
                    )
                  ),
                  fn (Pump $pump) => [
                    'pump' => $pump,
                    'cost' => $pump->priceByRates($rates),
                  ]
                ),
                'cost'
              )
            )
          )
        ),
        $jockeyPumps,
        [['pump' => null]]                                      // 9.2. or take [['pump' => null]] otherwise
      ),
    )
  ),
))->value();

Static methods

Since PHP does not allow you to have more than one constructor in the class, some classes in the library have public static methods that return an instance of the class and replace secondary constructors. Some classes have private primary constructor to prevent user to use them in a wrong way.

For example take a look at the class ArrOf that has private constructor but let you create an instance of Arr object in a several ways via static methods:

use Maxonfjvipon\ElegantElephant\Arr\ArrOf;
use Maxonfjvipon\ElegantElephant\Any\AnyOf;

// From items
ArrOf::items($item1, $item2, $item3)->asArray(); // [$item1, $item2, $item3]

// From array
ArrOf::array([1, 2, 3])->asArray(); // [1, 2, 3]

// From Maxonfjvipon\ElegantElephant\Any
ArrOf::any(AnyOf::arr(["Hello", "Jeff"]))->asArray(); // ["Hello", "Jeff"]

// From callback
ArrOf::func(fn () => ["Hello", "World"])->asArray(); // ["Hello", "World"]

If you write code and see that you can't create an object via new keyword - definitely it's the class with private constructor but public static methods that replace constructors, so try them.

Union arguments

Almost every classes allows you to pass union-typed arguments to the constructor.

For example, class TxtJoined behaves like a joined string and accepts an array or an instance of Arr that both may contains strings, instances of Txt or both of them.

use Maxonfjvipon\ElegantElephant\Txt\TxtJoined;
use Maxonfjvipon\ElegantElephant\Txt\TxtOf;
use Maxonfjvipon\ElegantElephant\Arr\ArrOf;
use Maxonfjvipon\ElegantElephant\Any\AnyOf;

$joined1 = new TxtJoined([
  TxtOf::str("Hello"), 
  " ", 
  TxtOf::any(AnyOf::str("Jeff"))
]);

$joined2 = new TxtJoined(
  ArrOf::func(fn () => [
    new TxtJoined(["Hello", " "]),
    "Jeff"
  ])
);

$joined1->asString() === $joined2->asString(); // "Hello Jeff" === "Hello Jeff" => TRUE

So when you write code you may not care about conversion an argument to the desired type, for example conversion string to Maxonfjvipon\ElegantElephant\Txt. Just pass what you have to the object, it knows how to deal with it.

Any

Something that has value of any (mixed) type. Any interface has only one public method value that must return something of mixed type.

Any objects

Tests

See Any unit tests for better undestanding.

Arr

Elegant arrays. Arr interface has only one public method asArray() that must return an array.

Spreading

There is one more interface that you can use in your own classes - IterableArr that extends Arr and \IteratorAggregate.

\IteratorAggregate allows you to apply spread operator ... to your class. If you want to use spread operator with your class without actual calling asArray() method you should make your class implement IterableArr and use HasArrIterator trait. The trait is the default implementation of spreading Arr classes. And now when you use ... with your class trait calls asArray() behind the scene.

And here is the example for better understanding:

use Maxonfjvipon\ElegantElephant\Arr;
use Maxonfjvipon\ElegantElephant\Arr\IterableArr;
use Maxonfjvipon\ElegantElephant\Arr\HasArrIterator;

class MyArr implements Arr { /** code */ }

class MyIterableArr implements IterableArr {
  use HasArrIterator;
  /** code */
}

$arr = [...(new MyArr())->asArray()];         // good
$arr = [...new MyIterableArr()];              // good, no actual calling asArray()
$arr = [...(new MyIterableArr())->asArray()]; // good, but verbose
$arr = [...new MyArr()];                      // wrong

All Arr classes in the library can be spead.

Arr classes

Tests

See Arr unit test for better undestanding.

Logic

Elegant boolean. Logic interface has only one method asBool() that must return bool.

Logic classes

Tests

See Logic unit tests for better undestanding.

Num

Elegant numbers. Num interface has only one method asNumber() that must return float or int.

Num classes

Tests

See Num unit tests for better undestanding.

Txt

Elegant strings. Txt interface has only one method asString() that must return string.

Txt->__toString()

There is one more interface that you can use in your own classes - StringableTxt that extends Txt and \Stringable.

\Stringable allows you to cast your class to string via calling __toString() method. So instead of Txt you can use StringableTxt interface and TxtToString helper trait that calls asString() behind the scene.

Here's an example for better undestanding:

use Maxonfjvipon\ElegantElephant\Txt\StringableTxt;
use Maxonfjvipon\ElegantElephant\Txt\TxtToString;
use Maxonfjvipon\ElegantElephant\Txt;

class MyTxt implements Txt { /** code */ }

class MyStringableTxt implements StringableTxt {
  use TxtToString;
  /** code */
}

$txt = new MyTxt();
$stringableTxt = new MyStringableTxt();

echo $txt->asString();           // good
echo $stringableTxt;             // good, no actual calling asString()
echo $stringableTxt->asString(); // good, but verbose
echo $txt;                       // wrong

All Txt classes in the library implements StringableTxt.

Txt classes

Tests

See Txt unit test for better undestanding.

Contribution

Fork repository, make changes, send a pull request. To avoid frustration, before sending your pull request please run:

$ ./pre-push.sh

And make sure you have no errors.