Shapesとは
これまでCollectionやHackの配列について触れてきましたが、
PHPライクな配列を扱いたい場面は多くあります。
PHPの関数の戻り値を扱う場合や、PHPのコードをHackにおき買う場合などなど
Shapesは配列ライクなフィールドに対して型を定義したものです。
これを利用することでTypecheckerでフィールド内の型を判定できますので、
不確実な値が入り込みやすい配列に対してのもう一つのアプローチと言えます。
ただし配列ライク、というだけあって次のものは利用できません。
- 定義されていない・存在しないキーに対してのアクセスはできません
$shape[$var] - 配列でよく利用する
[]オペレーターは利用できません - Traversableは実装されていないため、foreachなどは利用できません
*json_encodeを利用するとjsonに変換することができます。
それでは早速Shapesについて見ていきましょう
Shapesの使い方
<?hh // strict
namespace Acme\Shapes;
class Standard {
public function introduction(): shape('a' => int, 'b' => int) {
return shape(
'a' => 0,
'b' => 1
);
}
}
shape('フィールド名' => 型) を指定することでshapeが利用できます。
型宣言に shape(なんたらかんたら) と記述するのが面倒くさそう。。
そんな時にはtype aliasを利用することでshape利用が簡単になります。
<?hh // strict
namespace Acme\Shapes;
type SampleShape = shape('a' => int, 'b' => int);
class Standard {
public function introduction(): SampleShape {
return shape(
'a' => 0,
'b' => 1
);
}
}
shapeの出力は下記の通りです。
arrayと表示されますが、arrayと同一のものではありません。
array(2) {
["a"]=>
int(0)
["b"]=>
int(1)
}
定数に対しても利用できますが、
文字列型か、int型となります。
<?hh // strict
namespace Acme\Shapes;
type PointS = shape(Standard::KEYA => int, Standard::KEYB => int);
type PointI = shape(Standard::KEYX => int, Standard::KEYY => int);
class Standard {
const string KEYA = 'x';
const string KEYB = 'y';
const int KEYX = 10;
const int KEYY = 23;
public function constants(): PointI {
return shape(Standard::KEYX => -1, Standard::KEYY => 2);
}
}
定数以外では様々な型を利用できます。
<?hh // strict
namespace Acme\Shapes;
type SampleShape = shape('a' => int, 'b' => int);
type NestShape = shape('sample' => SampleShape, 'vec' => vec<string>);
class Standard {
public function nest(): NestShape {
return shape(
'sample' => shape(
'a' => 0,
'b' => 1
),
'vec' => vec[
'shapes'
],
);
}
}
幅広く利用できるのではないでしょうか
filedをオプションにしたい場合
フィールドをオプションとしたい場合は、
フィールド名の前に ? をつけることでフィールド自体がなくてもTypecheckerには警告されません。
<?hh
type OptionalShape = shape('q' => string, 'w' => string, ?'e' => int);
存在しないフィールドを追加するとどうなるでしょうか？
<?hh // strict
namespace Acme\Shapes;
type OptionalShape = shape('q' => string, 'w' => string, ?'e' => int);
class Standard {
public function optional(): OptionalShape {
return shape(
'q' => 'qwerty',
'w' => 'wertyu',
'z' => 1,
);
}
}
Typecheckerで以下のエラーとなります。
The field 'z' is not defined in this shape type, and this shape type does not allow unknown fields.
The field 'z' is set in the shape.
値をnullableにしたい場合
フィールドの値をnullableにしたい場合は、型に ? をつければOKです。
<?hh
type NullableShape = shape('q' => string, 'w' => string, 'e' => ?int);
Shapes: Functions
Shapesで用意されているメソッドがいくつかあります。
idx
Shapesのフィールドがあるかどうかを調べて、
フィールドがない場合は、デフォルトの値を指定して利用します。(オプショナルのフィールドのみ)
<?hh // strict
namespace Acme\Shapes;
type NullableShape = shape('q' => string, 'w' => string, ?'e' => int);
use function var_dump;
class Standard {
public function index(): void {
$shapes = $this->optinal();
var_dump(Shapes::idx($shapes, 'e', 123));
var_dump(Shapes::idx($shapes, 'e'));
}
public function optinal(): NullableShape {
return shape(
'q' => 'qwerty',
'w' => 'wertyu'
);
}
}
存在しないフィールドを指定する場合は、デフォルトの値を指定する必要があります。
var_dump(Shapes::idx($shapes, 'z', 'asd'));
toArray
Shapesを配列に変換する場合に利用します。
<?hh // strict
namespace Acme\Shapes;
type NullableShape = shape('q' => string, 'w' => string, ?'e' => int);
use function var_dump;
class Standard {
public function index(): void {
$shapes = $this->optinal();
var_dump(Shapes::toDict($shapes), Shapes::toArray($shapes));
}
public function optinal(): NullableShape {
return shape(
'q' => 'qwerty',
'w' => 'wertyu'
);
}
}
構造体ライクにShapesを利用する
Shapesらしい実践的な利用方法を紹介します。
値を確認するだけではなく、通常の配列に対してのvalidationライクに検査を行うことができます。
つまり、マイクロサービスや、サービス間の連携で利用するメッセージングブローカーのメッセージなどに対して、
値の厳格な検査ができるようになります。
静的型付言語のjson変換と同様に、
不確実な値の混入を防ぐことができます。
例を見てみましょう。
最初に問題なしとして処理されるパターンです。
<?hh // strict
namespace Acme\Shapes;
use function var_dump;
class Standard {
const type embeddedLinks = shape(
'name' => string,
'_links' => shape(
'self' => shape(
'href' => string
)
)
);
public function index(): void {
$url = [
'name' => 'hack',
'_links' => [
'self' => [
'href' =>'uri'
]
]
];
var_dump($url as this::embeddedLinks);
}
}
shapesを使って、フィールドの検査を行う場合は、Hackの as が利用できます。
shapesで定義した型と一致していれば、var_dumpが実行されます。
この例ではType Constantsを利用していますが、
通常のshapesでも構いません。
HHVM3.27までは、hhvm/type-assert の、
TypeAssert\matches_type_structureを利用していました。
<?hh // strict
use namespace Facebook\TypeAssert;
class Foo {
const type TAPIResponse = shape(
'id' => int,
'user' => string,
'data' => shape(
/* ... */
),
);
public static function getAPIResponse(): self::TAPIResponse {
$json_string = file_get_contents('https://api.example.com');
$array = json_decode($json_string, /* associative = */ true);
return TypeAssert\matches_type_structure(
type_structure(self::class, 'TAPIResponse'),
$array,
);
}
}
これは複雑な、例えばHypertext Application Language (HAL) や、
JSONAPIといったハイパーメディアにはもちろん、
様々なものに利用できます。
HALに対して利用する場合は、以下のようになります。
const type embeddedLinks = shape(
'name' => string,
'_links' => shape(
'self' => shape(
'href' => string
)
)
);
const type hateoasStructure = shape(
'id' => int,
'name' => string,
'title' => string,
'_links' => shape(
'self' => shape(
'href' => string,
'type' => string
)
),
'_embedded' => shape(
'environments' => array<self::embeddedLinks>
)
);
次に失敗する場合です。
一部の値をShapesで宣言した型と異なるものを利用してみます。
<?hh // strict
namespace Acme\Shapes;
use function var_dump;
class Standard {
const type embeddedLinks = shape(
'name' => string,
'_links' => shape(
'self' => shape(
'href' => string
)
)
);
public function index(): void {
$url = [
'name' => 1,
'_links' => [
'self' => [
'href' =>'uri'
]
]
];
var_dump($url as this::embeddedLinks);
}
}
これを実行すると、以下のエラーとなります。
Fatal error: Uncaught exception 'TypeAssertionException' with message 'Expected string at ["name"], got int' in oath/to/hack.file
Shapesで宣言したフィールドに含まれないフィールドがある場合も同様にエラーとなります。
素晴らしい！
PHPではなかなか難しい処理もHackで用意されている様々な機能を利用することで、
厳格なアプリケーションが開発できるようになります。
チーム開発などで是非利用してみてください。