Create first version

.github/FUNDING.yml

@@ -0,0 +1,12 @@
+# These are supported funding model platforms
+
+github: ngmy
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+otechie: # Replace with a single Otechie username
+custom: https://flattr.com/@ngmy

.github/workflows/php.yml

@@ -0,0 +1,80 @@
+name: test
+
+on: [push, pull_request]
+
+jobs:
+  test:
+
+    runs-on: ubuntu-18.04
+
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ['8.1']
+        deps: [highest, lowest]
+        include:
+          - php: '8.1'
+            deps: current
+
+    name: Test (PHP ${{ matrix.php }}, ${{ matrix.deps }} dependencies)
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v2
+
+      - name: Set up PHP ${{ matrix.php }}
+        run: sudo update-alternatives --set php /usr/bin/php${{ matrix.php }}
+
+      - name: Update Composer to latest version
+        run: sudo composer self-update
+
+      - name: Allow Composer bin plugin
+        run: composer global config allow-plugins.bamarni/composer-bin-plugin true
+
+      - name: Install Composer bin plugin
+        run: composer global require bamarni/composer-bin-plugin
+
+      - name: Validate composer.json and composer.lock
+        run: composer validate
+
+      - name: Cache Composer packages
+        if: matrix.deps == 'current'
+        id: composer-cache
+        uses: actions/cache@v2
+        with:
+          path: vendor
+          key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-php-
+
+      - name: Install dependencies
+        run: |
+          if [[ "${{ matrix.deps }}" == 'current' && "${{ steps.composer-cache.outputs.cache-hit }}" != 'true' ]]; then
+            composer install --no-interaction
+          fi
+          if [[ "${{ matrix.deps }}" == 'highest' ]]; then
+            composer update --no-interaction
+          fi
+          if [[ "${{ matrix.deps }}" == 'lowest' ]]; then
+            composer update --no-interaction --prefer-lowest --prefer-stable
+          fi
+
+      - name: Install tools
+        run: composer bin all install
+
+      - name: Run lint
+        run: vendor/bin/phpstan analyse
+
+      - name: Run unit tests
+        env:
+          XDEBUG_MODE: coverage
+        run: vendor/bin/phpunit
+
+      - name: Upload coverage results to Coveralls
+        env:
+          COVERALLS_REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        uses: nick-invision/retry@v2
+        with:
+          timeout_minutes: 10
+          max_attempts: 3
+          command: vendor/bin/php-coveralls --coverage_clover=build/logs/clover.xml -v

.gitignore

@@ -0,0 +1,10 @@
+# Composer
+/vendor/
+/vendor-bin/**/vendor/
+
+# PHPUnit
+/phpunit.xml
+/.phpunit.result.cache
+
+# PHPStan
+/phpstan.neon

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Yuta Nagamiya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,19 @@
+default: help
+
+-include tasks/Makefile.*
+
+## コマンドのヘルプを表示する
+help:
+	@printf "Available targets:\n\n"
+	@awk '/^[a-zA-Z\-_0-9%:\\]+/ { \
+		helpMessage = match(lastLine, /^## (.*)/); \
+		if (helpMessage) { \
+			helpCommand = $$1; \
+			helpMessage = substr(lastLine, RSTART + 3, RLENGTH); \
+			gsub("\\\\", "", helpCommand); \
+			gsub(":+$$", "", helpCommand); \
+			printf "  \x1b[32;01m%-35s\x1b[0m %s\n", helpCommand, helpMessage; \
+		} \
+	} \
+	{ lastLine = $$0 }' $(MAKEFILE_LIST) | sort -u
+	@printf "\n"

README-ja.md

@@ -0,0 +1,161 @@
+[English](README.md) | [日本語](README-ja.md)
+
+# PHP Specification
+
+[![test](https://github.com/ngmy/php-specification/actions/workflows/php.yml/badge.svg)](https://github.com/ngmy/php-specification/actions/workflows/php.yml)
+[![coverage](https://coveralls.io/repos/github/ngmy/php-specification/badge.svg?branch=master)](https://coveralls.io/github/ngmy/php-specification?branch=master)
+
+これはPHPで[仕様パターン](https://www.martinfowler.com/apsupp/spec.pdf)を実装するのを手助けするライブラリです。  
+メモリー上での検証、メモリー上およびORMでの選択、および仕様の合成を提供します。
+
+## インストール方法
+
+```console
+composer require ngmy/specification
+```
+
+## 使用方法
+
+### 仕様の作成およびメモリー上での検証・選択
+
+`AbstractSpecification`クラスを継承しあなたの仕様クラスを作成します。
+
+そして`isSatisfiedBy`メソッドを実装します。  
+このメソッドに仕様を満たす条件を記述します。
+
+さらに`@extends`アノテーションで`isSatisfiedBy`メソッドが期待するオブジェクトの型を記述しておくと静的解析が捗ります。
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Ngmy\Specification\AbstractSpecification;
+
+/**
+ * 人気ユーザー仕様。
+ *
+ * @extends AbstractSpecification<User>
+ */
+class PopularUserSpecification extends AbstractSpecification
+{
+    /**
+     * @inheritdoc
+     */
+    public function isSatisfiedBy($candidate): bool
+    {
+        return $candidate->getVotes() > 100;
+    }
+}
+```
+
+`isSatisfiedBy`メソッドに検証したいオブジェクトを渡して呼び出すことで、
+そのオブジェクトが仕様を満たすかどうかを検証できます。
+
+```php
+$spec = new PopularUserSpecification();
+$spec->isSatisfiedBy($user);
+```
+
+もちろん選択にも使えます。
+
+```php
+$spec = new PopularUserSpecification();
+$popularUsers = array_filter(function (User $users) use ($spec): void {
+    return $spec->isSatisfiedBy($user);
+}, $users);
+```
+
+### ORMでの選択
+
+#### Eloquent
+
+`applyToEloquent`メソッドを実装します。  
+このメソッドに`where`メソッド等で選択条件を記述します。
+
+```php
+use Illuminate\Contracts\Database\Eloquent\Builder as EloquentBuilder;
+
+/**
+ * @inheritdoc
+ */
+public function applyToEloquent(EloquentBuilder $query): void
+{
+    $query->where('votes', '>', 100);
+}
+```
+
+`applyToEloquent`メソッドにEloquentビルダーを渡して呼び出すことで、クエリーに選択条件を追加できます。
+
+```php
+$query = User::query(); // UserはあなたのEloquentモデルです
+$spec = new PopularUserSpecification();
+$spec->applyToEloquent($query);
+$popularUsers = $query->get();
+```
+
+#### Doctrine
+
+`applyToDoctrine`メソッドを実装します。  
+このメソッドに`andWhere`メソッド等で選択条件を記述します。
+
+```php
+use Doctrine\ORM\QueryBuilder as DoctrineQueryBuilder;
+
+/**
+ * @inheritdoc
+ */
+public function applyToDoctrine(DoctrineQueryBuilder $queryBuilder): void
+{
+    $queryBuilder->andWhere(sprintf('%s.votes > 100', $queryBuilder->getRootAliases()[0]));
+}
+```
+
+`applyToDoctrine`メソッドにクエリビルダーを渡して呼び出すことで、クエリーに選択条件を追加できます。
+
+```php
+/** @var \Doctrine\ORM\EntityManager $entityManager */
+$queryBuilder = $entityManager->createQueryBuilder();
+$queryBuilder->select('u')->from(User::class, 'u'); // UserはあなたのDoctrineエンティティーです
+$spec = new PopularUserSpecification();
+$spec->applyToEloquent($queryBuilder);
+$popularUsers = $query->getQuery()->getResult();
+```
+
+### 合成
+
+仕様をAND、OR、NOTで合成できます。  
+仕様を合成すると`isSatisfiedBy`メソッドや`applyToEloquent`、`applyToDoctrine`メソッドに記述した条件も合成されます。
+
+#### AND
+
+仕様の`and`メソッドに別の仕様のインスタンスを渡して呼び出すことで、2つの仕様をANDした新しい仕様を生成できます。
+
+```php
+$spec1 = new Specification1();
+$spec2 = new Specification2();
+$spec3 = $spec1->and($spec2);
+```
+
+#### OR
+
+仕様の`or`メソッドに別の仕様のインスタンスを渡して呼び出すことで、2つの仕様をORした新しい仕様を生成できます。
+
+```php
+$spec1 = new Specification1();
+$spec2 = new Specification2();
+$spec3 = $spec1->or($spec2);
+```
+
+#### NOT
+
+仕様の`not`メソッドを呼び出すことで、自分自身をNOTした新しい仕様を生成できます。
+
+```php
+$spec1 = new Specification1();
+$spec2 = $spec1->not();
+```
+
+## License
+
+PHP Specificationは[MITライセンス](http://opensource.org/licenses/MIT)の下で提供されるオープンソースソフトウェアです。