README

我们在应用程序中使用的一些小工具。

PMG\Support\Types

获取输入的类型

use PMG\Support\Types;

var_dump(Types::of(new stdClass)); // 'stdClass'
var_dump(Types::of('test')); // 'string'

获取对象字符串表示

use PMG\Support\Types;

echo Types::repr(new stdClass), PHP_EOL; // object(stdClass)
echo Types::repr(['one']), PHP_EOL; // array(["one"])
echo Types::repr('test'), PHP_EOL; // test

PMG\Support\Json

这里的主要好处是，Json类会检查返回值，如果底层的json_{encode,decode}失败，则返回错误。

use PMG\Support\Json;

echo Json::encode(['one']), PHP_EOL;

$array = Json::decode('["one"]');
var_dump($array);

PMG\Support\Ids

我们倾向于使用值对象来表示标识符，这些对象都实现了PMG\Support\Id。默认情况下，这是一个PMG\Support\Ids\Uuid。

使用UUID

use PMG\Support\Ids;

// generate a new UUID
$newId = Ids::generate();

// convert a string into a UUID
$uuid = Ids::from('1295bf14-c1aa-43a0-8ad2-3985b4e552d2');

// or "ensure" a value is an `Id`

// if given an `Id`, then that object is return
$otherUuid = Ids::ensure($uuid); 
var_dump($otherUuid === $uuid); // true

// if given a string, it will attemp to convert it to a UUID
$uuid = Ids::ensure('1295bf14-c1aa-43a0-8ad2-3985b4e552d2');

// or a `PMG\Support\Ids\InvalidId` exception will be thrown for any other type
Ids::ensure(123); // error

// both `from` and `ensure will throw InvalidId with an invalid UUID format
Ids:from('nope'); // throws
Ids::ensure('nope'); // throws

PMG\Support\HasId

此接口用于标记一个对象具有标识符。提供了一个实现此接口的特质。

use PMG\Support\HasId;
use PMG\Support\Id;
use PMG\Support\Ids;
use PMG\Support\ImplementHasId;

class WithAnId implements HasId
{
    use ImplementsHasId;

    public function __construct(?Id $id)
    {
        // setIdentifier is a protected method from ImplementHasId
        $this->setIdentifier($id);
    }
}

// passing `null` to `setIdentifier` (via the constructor here) will
// generate a new UUID
$generated = new WithAnId(null);
var_dump($generated->getIdentifier()); // a `PMG\Support\Ids\Uuid` object is returned

// otherwise the ID object passed to the constructor will be returned
$id = Ids::generate();
$passed = new WithAnId($id);
$id === $passed->getIdentifier(); // true

在测试中使用ID

使用PMG\Support\Ids\StubId或PMG\Support\Ids\NullId。两者都可以从Ids生成。

use PMG\Support\Ids;

$stub = Ids::stub('testMe');

$none = Ids::none();

PMG\Support\Clock

这个抽象用于避免在各个地方都使用new DateTimeImmutable，因为我们想要控制创建过程（为了测试目的以及其他原因，比如更明确地控制时区）。

这里有两个实现

• PMG\Support\Clock\TzAwareClock -- 返回在构造函数中给出的时区的日期。
• PMG\Support\Clock\StubClock -- 总是返回在构造函数中给出的日期。这对于测试非常有用。

默认时钟

默认时钟，通过Clock::get获取，是一个UTC时区的TzAwareClock。

use PMG\Support\Clock;

/** @var $clock PMG\Support\Clock\TzAwareClock */
$clock = Clock::get();

主要API

// $clock from above

$now = $clock->now(); // current time, no microseconds

$date = $clock->from('2019-01-01'); // date time object from a date string

// TzAwareClock will do one of three things, each one sets the timezone to
// the DateTimeZone given in its constructor

// 1. convert a `DateTime` to `DateTimeImmutable`
$immutable = $clock->ensure(new DateTime('2019-01-01'));
var_dump($immutable); // DateTimeImmutable object

// 2. ensure that the timezone is set on immutable date time
$other = $clock->ensure(new DateTimeImmutable('2019-01-01'));
var_dump($other->getTimeZone()); // UTC (or whatever was passed in)

// 3. convert from a string
$date = $clock->ensure('2019-01-01'); 

Any other value will throw `PMG\Support\Exception\InvalidArgumentException
$clock->ensure(123); // not a string or datetime object, throws

测试

使用PMG\Support\Clock\StubClock，它将始终返回在构造函数中给出的DateTimeImmutable的一个副本。

use PMG\Support\Clock\StubClock;

$date = new DateTimeImmutable('2019-01-01');
$clock = new StubClock($date);

$date == $clock->now(); // true
$date === $clock->now(); // false, StubClock returns a clone

$date == $clock->from('ThisIsIgnored'); // true

$date == $clock->ensure(new DateTime('2019-02-01')); // true, the value passed is ignored