Download the PHP package ryunosuke/castella without Composer

On this page you can find all versions of the php package ryunosuke/castella. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package castella

php configuration and DI container

Description

設定ファイルをベースとした DI コンテナです。 下記の機能があります。

Install

Concept

Spec

Usage

基本

このパッケージは端的に言えば「依存関係を解決できるコンフィグレーションライブラリ」です。 環境や開発者間での設定を吸収する、下記のようなユースケースを想定しています。

まず、下記のようなデフォルト設定があるとします。

これは「アプリが動作するための最低限の動作 and 開発者向けの参考・スキーマ」のようなファイルです。 環境を問わず必ず読み込まれるようなベース設定です。 これだけだと設定に意味はなく、まともな動作はしない事が多いです。

次に環境変数やホスト名等に基づいて下記のような個別設定があるとします。

配列はマージされるため、「デフォルトから上書きしたいエントリ」だけを指定します。 上記ではデフォルトを尊重しつつ、「ログレベルは DEBUG にしたい」「DB は docker の mysql を使いたい」「S3 は minio を使いたい」といった形で必要なもののみ上書きしています。 これが「設定ファイルベース」たる所以です。

さらに storage 設定や S3 のクライアントなどは平易な記法で依存関係を解決しています。遅延実行+キーの上書き機構により不必要な実行は一切行われませんし、インスタンスは使い回されます。 これが「設定ファイルを DI コンテナのように使いたい」たる所以です。

上記のとき、env.extension の値は $this->array しているため ['php'] であることに注意してください。 配列はマージされるため、この $this->array が無いと 0番目だけが上書きされた ['php', 'es', 'ts'] という値になってしまいます。 このように配列を完全に上書きしたい場合は $this->array を使用します。

また、 storage 以下のエントリは #[Factory] でファクトリを明示しています。

[Factory] を使うと引数が「そのエントリまでのキーパス」で可変引数で渡ってきます。

このように引数を活用するとキー値を使うときに重複した記述を避けることができます。

コンストラクタ

コンストラクタで各種オプションを設定します。 ここで設定したオプションは変更できません。 オプションはすべて省略可能で下記はデフォルト値です。

debugInfo: ?string

__debugInfo の挙動を指定します。

将来的な拡張のために string 型になっていますが、現在のところ null|"current"|"settled" の3択です。

現在のデフォルトは null ですが、往々にして有用なのは "current" のため、このデフォルト値は後々変更される可能性があります。 また、このデフォルト値の変更は互換性の担保に含まれません。

delimiter: string

アクセスするときの配列区切り文字を指定します。

このようなとき、 $container->get('a.b.c') のようにアクセスできます。

closureAsFactory: string

false にするとクロージャも「値」とみなされます。 クロージャが遅延実行されなくなるため、ファクトリとしての使用は #[Factory] 属性を付与します。

このようなとき、 $container->get('closure') でクロージャがそのまま得られます。つまりファクトリとして働かないということです。 $container->get('factory') でクロージャの結果が得られます。つまりファクトリとして働くということです。

なお、 closureAsFactory:true でも #[Factory] 属性自体は使えます。 その場合「ファクトリの明示」+「引数の変化」という使い方になります。

autowiring: bool

未登録エントリにアクセスしようとしたときに型名で自動解決するかを指定します。

true にすると非エントリでもクラスが存在する場合はそのインスタンスが取得できます。 その際、依存関係は再帰的に解決されます。 false にすると非エントリを取得することはできません。

constructorInjection: bool

依存解決の際にコンストラクタの引数型・引数名を見てインジェクションするかを指定します。

true にすると後述の resolver で解決を試みます。 false にすると $arguments 引数で必須引数を完全にカバーする必要があります。

propertyInjection: bool

依存解決の際にプロパティの型・名前を見てインジェクションするかを指定します。

true にすると後述の resolver で解決を試みます。その際、nullable か初期化済みプロパティは対象外になります。 逆に言うと notnull で未初期化プロパティが解決されます。 false にするとプロパティを一切触らなくなります。

resolver: callable

依存関係の解決 callable を指定します。

callable のシグネチャは (ReflectionParameter|ReflectionProperty $reflection): mixed です。 ここで返した値が依存値として取得されます。

デフォルトでは下記の順で解決を試みます。

  1. $type がスカラー値の場合、 引数名やプロパティ名の _ を delimiter に置換したエントリ
  2. $type の型文字列表現エントリ
  3. $type と型が一致するエントリ(全走査)

「型が一致」とは一意であることを意味します。該当する型がなかったり複数ある場合は検出できません。

例えば __construct(TypeName $this_is_arg) の場合、まずエントリに TypeName という名前が登録されているか調べて、存在しなかった場合は全エントリから TypeName のインスタンスを走査します。 それでも解決できなかった場合は依存関係の解決に失敗し、例外を送出します。

エントリ設定

下記の設定メソッドにおいて、動的・静的・遅延を問わず一度でも取得したエントリを上書きすることはできません。 取得済みエントリを上書きしようとすると例外を送出します。

extends(array $values): self

指定された配列をエントリとして取り込みます。 指定済みのキーは再帰的にマージ(上書き)されます。

キーを空白で区切ると左側がエントリ名、右側がエイリアスとして機能します。 エイリアスを指定するとそのエイリアス名でもアクセスすることができるようになります。

上記のようにすると a.b.c でも abc でもアクセスできます。

include(string $filename): self

コンテナのコンテキストでファイルを読み込んで返り値を取り込みます。 実質的に $container->extends((fn() => include $filename)->call($container)) とほぼ同義です。

違いは $this['entry'] が使える点です。 include のコンテキストで $this['entry'] のように直参照すると特殊な遅延評価オブジェクトに変換され、参照時点で未定義でもその値が使用できます。 つまり、下記の fuga と piyo は同義となります。

自身のエントリを参照するわけなので、static 固定です。

mount(string $directory, ?array $pathes = null, ?string $user = null): self

指定ディレクトリ内の $pathes に基づくファイルをすべて読み込みます。 拡張子は .php 固定です。

「$pathes に基づく」とは単純にファイルシステムの階層構造を表します。 その際、ディレクトリ内の .php (名前なし php ファイル)は必ず読み込まれます。

このような階層の時、mount ディレクトリ指定で $pathes で読み込まれるファイルは下記となります。

要するに apache の htaccess のような関係性で、指定階層のファイルとその通過中のディレクトリの .php が読み込まれます。 読み込みはディレクトリ優先です。

上記は com は完全なるネスト構造、 net は完全なるフラット構造、 org はその中間(必要が無ければディレクトリが結合できる)の例示になっています。 これらの配置が混在しているときの動作は規定していないことに注意してください(おそらくすべてが読み込まれる。弊害はないだろうが無駄が多くなる)。

$pathes はデフォルトではホスト名の逆順です。 引数を与えた場合、変に加工せずそのまま使います。典型的には環境変数由来の値を与えることが多いでしょう。

$user を与えると最終的なファイル名が basename@{$user}.php であるファイルも追加で読み込まれるようになります。 これは既存設定ファイルにバリエーションを持たせるための機能で、user という引数に特別な意味合いはありません(敢えて言うならデフォルト値でユーザー名が使用される)。 そのようなファイルを読みたい場合は $pathes で指定すれば十分であり、この機能が活きるのはかなり局所的な使い方になります。

set(string $id, $value): self

id 指定でエントリを設定します。 id は delimiter で潜ります。 $container->set('a.b.c', 'X') は実質的に $container->extends(['a' => ['b' => ['c' => 'X']]]) と同義です。

エントリ取得

has(string $id): bool

エントリが存在するか bool を返します。

get(string $id): mixed

エントリを取得します。 取得されたエントリはクロージャ/ファクトリが解決されており、完全なる値を得ることができます。

$container->get('') のように空文字を与えると全エントリを配列で得られますが推奨しません。 これで得られる値は「配下すべてが解決済みの配列」であり、すべての遅延取得を無に帰す禁断の取得方法です。

'' に限らず、遅延取得を有効に活かすためには出来るだけ小さい単位で get するのがコツです。

fn(string $id): Closure

エントリを取得するクロージャを返します。 実質的に fn() => $container->get($id) と同義です。

「まだ使うか分からないのでクロージャでラップして取得したい」といった場合の糖衣構文として使えます。

エントリその他

MagicAccess

プロパティのオーバーロードメソッドが実装されており、プロパティライクなアクセスも可能です。 下記のように対応します。

ArrayAccess

ArrayAccess が実装されており、配列ライクなアクセスも可能です。 下記のように対応します。

cache(string $filename, Closure $initializer): bool

$filename が存在しないとき、$initializer を実行してその結果を $filename に書き出します。 存在する場合は $filename を読むだけになり、$initializer は実行されません。

ただし $initializer が true を返すと次回は $filename を読み込みつつも $initializer も実行されます。 これは下記の要求を満たしたいためです。

要するにキャッシュですが、非常に実験的な機能であり、今後予告なく変更・削除される可能性があります。 そもそもよほど変なことをしない限り、キャッシュせずとも十分高速に動きます。

オブジェクトやリソースは書き出し出来ません。 (include した場合はともかく、set や extends されるとそのオブジェクトの生成方法が分からなくなるため)。

その代わりクロージャはそのまま活きるため fn() => new Object() 等とすれば遅延実行により実質的に同じ挙動にできます。

ユーティリティ

unset(): object

最終結果からそのエントリを取り除きます。

「親で定義されているが、子では取り除きたい」という状況で使用します。 つまり、下記の設定の最終結果に hoge は含まれません。

const($value, ?string $name = null): Closure

値をそのまま返します。

このメソッドで与えられた値は後述の define を呼ぶとその値が定数として定義されます。 定義場所は問いません。const された位置を覚えておいて、define で一気に登録するイメージです。

define(): array

const で返した値を一括で定数定義します。

これの何が嬉しいかというと

です。

上記は設定ファイルとしての値は const を使用していない場合と全く同じです(hoge'HOGE' で、nest.hoge'HOGE')。 この状態で define を呼ぶと

を実行したのと同じ効果になります。 const define を使用せず、定数定義すべきものをちまちま define("CONST_NAME", $container->get("key.to.const")); しても同じですが、得てして変更時に漏れが発生しやすくなります。 設定ファイル内で const しておけば「それが定数であること」と「定数定義されること」が保証されるため、漏れがなくなります。

なお、上記の通り定数名はオプションです。 指定しなかった場合はエントリのキーが大文字名前空間に変換されて定義されます。

env(string $name): ?string

getenv のラッパーで環境変数値を返します。

getenv の第2引数は true です。putenv(dotenv) で設定されている場合はそれを返します。

可変引数で、最初に見つかった環境変数を返します。 すべての環境変数が存在しない場合は(false ではなく) null を返します。 つまり、下記のように ?? を用いればデフォルト値を得ることが可能です。

new(string $classname, array $arguments = []): object

与えられたクラス名のインスタンスを生成します。

依存関係は自動解決しますが、$arguments で与えるとそれが優先されます。 $arguments は名前付き引数・位置引数の両方をサポートします。

実質的に「依存関係にある引数を省略することができる new 演算子」となります。 つまり、下記の hoge1 と hoge2 は同義となります。

yield(string $classname, array $arguments = []): Closure

$this->new する型付きクロージャを返します。

設定ファイル内でインスタンスを自動解決させるときの糖衣構文です。 つまり、下記の hoge1 と hoge2 と hoge3 は同義となります。

Hoge クラスのコンストラクタ引数が $hoge_arg1 だったり、 $hoge_arg2 が型付きで自動解決できる場合はこのような記述で Hoge インスタンスが(遅延)生成されます。 hoge3 は yield を使いつつ引数の遅延実行しています。

このように依存関係が完全に閉じているなら yield を使用して自動に任せたほうが楽なこともあるでしょう。 また、個人的に返り値の Hoge 宣言を忘れることが多いです。返り値の型なしのクロージャは依存関係解決の対象外となるため、この記法は「単純にその型のインスタンスが欲しい」場合に有用です。

static(string $classname, array $arguments = []): Closure

yield の static 版です。それ以外は全く同じです。 つまり、下記の hoge1 と hoge2 は同義となります。

parent(callable $callback): Closure

直近の親の値を受け取って値を変換するクロージャを返します。 親の設定を活かしつつ、軽微な変更を施したいときに使用します。

上記で array は ['a', 'b', 'c'] になります。 object は親の new Something() インスタンスの setSomething が呼ばれています。

callable(callable $entry): Closure

与えられた callable をクロージャにするクロージャを返します。 closureAsFactory:true の場合、クロージャを値として設定するためには「クロージャを返すクロージャ」を定義する必要がありますが、その時の糖衣構文です。 つまり、下記の callable1 と callable2 は同義となります。

自動的に static が付与されます。 これは「クロージャを返すクロージャは毎回生成する必要はないだろう」という前提に基づきます。

array(array $array): Closure

与えられた配列をそのまま返すクロージャを返します。 ただし、配列内のクロージャは実行時に解決されます。

配列をマージではなく完全に上書きしたいときの糖衣構文です。 つまり、下記の array1 と array2 は同義となります。

パッと見はほぼ同じですが、yield/static と同様、型宣言を忘れることが多いのと、配列をマージしてしまうと都合が悪い時に有用です。

annotate(?string $filename): array

設定されている実際の型を元に phpstorm.meta.php 形式で文字列を吐き出します。

この機能は開発支援機能なので遅延クロージャはすべて解決されます。本運用時に呼ぶことは想定されていません。 $filename を与えるとそのファイルに $container['hoge']$container->get('hoge') でコード補完が効くようになりかつ型を活かすことができるような map 配列が書き出されます。 返り値として名前の型配列を返します。

typehint(?string $filename): array

設定されている実際の型のプロパティを持ったクラス定義を吐き出します。

この機能は開発支援機能なので遅延クロージャはすべて解決されます。本運用時に呼ぶことは想定されていません。 $filename を与えるとそのファイルに $container->hoge でコード補完が効くようになりかつ型を活かすことができるようなクラス定義が書き出されます。 返り値として名前の型配列を返します。

dump(string $id = ''): string

設定されている実際の型を元に指定 id をダンプします。

この機能は開発支援機能なので遅延クロージャはすべて解決されます。本運用時に呼ぶことは想定されていません。 オブジェクトの一意性やちょっとした値の確認に使います。

Q&A

Lisence

MIT

Release

バージョニングは Romantic Versioning に従います。

2.0.3

2.0.2

2.0.1

2.0.0

1.0.8

1.0.7

1.0.6

1.0.5

1.0.4

1.0.3

1.0.2

1.0.1

1.0.0


All versions of castella with dependencies

PHP Build Version
Package Version
Requires php Version >=8.0
psr/container Version 1.* || 2.*
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package ryunosuke/castella contains the following files

Loading the files please wait ....