api-filter skill
API Platformのコレクションに対して、検索、ソート、範囲フィルタリングを行うための標準的なQueryParameterアプローチを用いたフィルタ機能を追加します。
- GitHubスター
- 29
- ファイル
- 1
- 最終コミット
- 2026年10月22日
- ライセンス
- —
- 許可されたツール
- —
api-filter skillは何をしますか
API Platformのコレクションに対して、検索、ソート、範囲フィルタリングを行うための標準的なQueryParameterアプローチを用いたフィルタ機能を追加します。
skillのSKILL.mdから生成された要約。
api-filter skill について
このSKILLは、バックエンド開発者がAPI Platformのコレクションに対して、検索、ソート、範囲フィルタリングを実装できるようにします。API Platform 4.4以降で必須となる、操作のparameters配列内でQueryParameterアプローチを使用してフィルタを宣言する方法を提供します。このアプローチは操作ごとに明示的に定義され、あらゆるstate providerで動作するため、特定のデータサブセットに対するクライアントのリクエストを処理する信頼性の高い手段となります。
開発者はこれを利用して、#[ApiFilter] のような非推奨のクラスレベル属性や、SearchFilter、BooleanFilter、OrderFilterといった特定のフィルタを置き換えることができます。このSKILLは、ExactFilter、PartialSearchFilter、DateFilter、SortFilterなどの単一目的のフィルタセットを通じて、Doctrine ORMとMongoDB ODMの両方をサポートしています。また、IriFilterによるIRIルックアップや、FreeTextQueryFilterを使用した複数フィールドにわたる単一値のブロードキャストといった、特殊なニーズにも対応しています。Laravelを使用している場合は、特定のEloquentフィルタセットやLaravelのバリデーションルールを使用した方法についてもガイダンスを提供します。
エージェントができること
- 1レガシーなAPIフィルタの移行非推奨となったクラスレベルの #[ApiFilter] 属性を、モダンなQueryParameterアプローチに変換します。
- 2複数フィールドのフリーテキスト検索の追加複数の異なるプロパティに対して値をチェックする、単一の検索パラメータを作成します。
- 3Laravel Eloquentフィルタの設定特定のEloquentフィルタクラスとバリデーションルールを使用して、Laravelモデルのフィルタリングを設定します。
skill の SKILL.md から作成されています。すべてのユースケースは、その引用と照合されています。
api-filter skillのインストール方法
各コマンドはskillフォルダをクライアントのskillsディレクトリにコピーします。読み込むには、クライアントを再起動するか新しいセッションを開始してください。プラグインにapi-filter skillをインストールする
/plugin marketplace add api-platform/skillset /plugin install api-platform@api-platform-skillset
Claude Codeにapi-filter skillをインストールする
~/.claude/skills/api-filter/SKILL.md
$ npx degit api-platform/skillset/skills/api-filter ~/.claude/skills/api-filterClaude Code (project)にapi-filter skillをインストールする
.claude/skills/api-filter/SKILL.md
$ npx degit api-platform/skillset/skills/api-filter .claude/skills/api-filterCodexにapi-filter skillをインストールする
~/.agents/skills/api-filter/SKILL.md
$ npx degit api-platform/skillset/skills/api-filter ~/.agents/skills/api-filterGemini CLIにapi-filter skillをインストールする
~/.gemini/skills/api-filter/SKILL.md
$ npx degit api-platform/skillset/skills/api-filter ~/.gemini/skills/api-filterClaude.aiにapi-filter skillをインストールする
npx degit api-platform/skillset/skills/api-filter api-filter && zip -r api-filter.zip api-filter # claude.ai → Customize → Skills → + → Create skill → Upload a skill → api-filter.zip
自動チェック
実行日 2026年11月16日完全なレポート →まだ検証されていません。スキルにはスコア 80、重大な指摘なし、チェックに十分なデータが必要です。 チェックの仕組み · 点数を上げるための改善点
- ソースリポジトリがリンクされており、アクセス可能api-platform/skillset/skills/api-filter is public and reachablegithub.com/api-platform/skillset/tree/HEAD/skills/api-filter ↗合格
- オープンソースライセンス (OSI)No license検出事項
- 過去1年以内にコミットまたはリリースありLast commit 2026-10-22github.com/api-platform/skillset/commits ↗合格
- スクリプトにダウンロード実行や認証情報の窃取がないNo scripts in the skill folder合格
- SKILL.md に隠れた指示がないNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/api-platform/skillset/blob/HEAD/skills/api-filter ↗合格
- 事前許可ツールが限定されているNo pre-approved tools; the agent asks before using onegithub.com/api-platform/skillset/blob/HEAD/skills/api-filter ↗合格
- SKILL.md が Agent Skills の形式に従っているValid name and description; says when to use it; 252 linesgithub.com/api-platform/skillset/blob/HEAD/skills/api-filter ↗合格
SKILL.md
GitHubで表示Adding Filters to Collections
Declare filters with QueryParameter in the operation's parameters: array. The
key is the query-string parameter exposed to clients; the filter: is the filter
instance. This is the canonical approach for API Platform 4.4+ — it works with any
state provider and is per-operation explicit.
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\QueryParameter;
use ApiPlatform\Doctrine\Orm\Filter\ExactFilter;
#[GetCollection(
parameters: [
'status' => new QueryParameter(filter: new ExactFilter()),
],
)]
class Order {}
Client: GET /orders?status=shipped
#[ApiFilter]is legacy. The class-level#[ApiFilter(SearchFilter::class, ...)]attribute and the multi-strategy filters (SearchFilter,BooleanFilter,NumericFilter,OrderFilter,BackedEnumFilter) are deprecated in 4.4 and removed in 6.0. Don't teach or add them in new code. If you encounter them, the migration target is theQueryParameter+ single-purpose filter set below. The mapping is in the table at the bottom.
Canonical filter set
Each filter does one thing. They live in two parallel namespaces — pick the one matching your persistence layer:
| Filter | Purpose | ORM | MongoDB ODM |
|---|---|---|---|
ExactFilter |
equality, multi-value (IN); booleans/ints/enums via nativeType |
ApiPlatform\Doctrine\Orm\Filter\ExactFilter |
ApiPlatform\Doctrine\Odm\Filter\ExactFilter |
PartialSearchFilter |
LIKE %x% substring |
…\Orm\Filter\PartialSearchFilter |
…\Odm\Filter\PartialSearchFilter |
ComparisonFilter |
gt/gte/lt/lte/ne (decorates an equality filter) |
…\Orm\Filter\ComparisonFilter |
…\Odm\Filter\ComparisonFilter |
SortFilter |
ORDER BY |
…\Orm\Filter\SortFilter |
…\Odm\Filter\SortFilter |
DateFilter |
before/after date ranges |
…\Orm\Filter\DateFilter |
…\Odm\Filter\DateFilter |
RangeFilter |
between/gt/lt on numbers |
…\Orm\Filter\RangeFilter |
…\Odm\Filter\RangeFilter |
ExistsFilter |
IS NULL / IS NOT NULL |
…\Orm\Filter\ExistsFilter |
…\Odm\Filter\ExistsFilter |
IriFilter |
relationship lookup by IRI | …\Orm\Filter\IriFilter |
…\Odm\Filter\IriFilter |
OrFilter |
decorator: switches a primary's WHERE to orWhere |
…\Orm\Filter\OrFilter |
…\Odm\Filter\OrFilter |
FreeTextQueryFilter |
decorator: broadcasts one value across N properties | …\Orm\Filter\FreeTextQueryFilter |
…\Odm\Filter\FreeTextQueryFilter |
ComparisonFilterandOrFilterare still marked@experimentalin 4.4 — they are the intended migration target but their API may shift before stabilizing.
Common filters
Exact match
'status' => new QueryParameter(filter: new ExactFilter())
GET /orders?status=shipped. Arrays produce an IN: ?status[]=draft&status[]=sent.
Boolean / integer / enum — ExactFilter + nativeType
There is no BooleanFilter in the canonical set. Use ExactFilter and declare the
native type so values are cast and documented correctly:
use Symfony\Component\TypeInfo\Type\BuiltinType;
use Symfony\Component\TypeInfo\TypeIdentifier;
'active' => new QueryParameter(
filter: new ExactFilter(),
nativeType: new BuiltinType(TypeIdentifier::BOOL),
),
GET /orders?active=true. Use TypeIdentifier::INT for integers; pass an enum's
native type for backed enums.
Partial search (LIKE)
use ApiPlatform\Doctrine\Orm\Filter\PartialSearchFilter;
'q' => new QueryParameter(filter: new PartialSearchFilter(), property: 'title')
GET /books?q=harry. property: maps the public param name to the entity field.
Comparison (gt/gte/lt/lte/ne)
use ApiPlatform\Doctrine\Orm\Filter\ComparisonFilter;
'price' => new QueryParameter(filter: new ComparisonFilter(new ExactFilter()))
GET /products?price[gt]=100&price[lte]=500.
Date range
use ApiPlatform\Doctrine\Orm\Filter\DateFilter;
'createdAt' => new QueryParameter(filter: new DateFilter())
GET /orders?createdAt[after]=2024-01-01&createdAt[before]=2024-12-31.
Numeric range
use ApiPlatform\Doctrine\Orm\Filter\RangeFilter;
'price' => new QueryParameter(filter: new RangeFilter())
GET /products?price[between]=10..100.
Exists (null check)
use ApiPlatform\Doctrine\Orm\Filter\ExistsFilter;
'deletedAt' => new QueryParameter(filter: new ExistsFilter())
GET /orders?deletedAt[exists]=false.
Relation (IRI)
use ApiPlatform\Doctrine\Orm\Filter\IriFilter;
'author' => new QueryParameter(filter: new IriFilter())
GET /books?author=/authors/1.
Sorting — SortFilter
There is no OrderFilter in the canonical set. Use SortFilter. Two forms:
use ApiPlatform\Doctrine\Orm\Filter\SortFilter;
// Per-property named parameter
'orderName' => new QueryParameter(filter: new SortFilter(), property: 'name'),
// → GET /books?orderName=desc
// Dynamic, OrderFilter-style: one parameter, any allowed property
'order[:property]' => new QueryParameter(filter: new SortFilter()),
// → GET /books?order[name]=asc&order[createdAt]=desc
property: can traverse relations ('department.company.name' sorts across joins).
Control null placement with nullsComparison:
use ApiPlatform\Doctrine\Common\Filter\OrderFilterInterface;
'orderHireDate' => new QueryParameter(
filter: new SortFilter(nullsComparison: OrderFilterInterface::NULLS_ALWAYS_FIRST),
property: 'hireDate',
),
Free-text across multiple fields
FreeTextQueryFilter decorates a primary and broadcasts one value to several
properties; wrap with OrFilter to match any of them:
use ApiPlatform\Doctrine\Orm\Filter\FreeTextQueryFilter;
use ApiPlatform\Doctrine\Orm\Filter\OrFilter;
use ApiPlatform\Doctrine\Orm\Filter\ExactFilter;
'autocomplete' => new QueryParameter(
filter: new FreeTextQueryFilter(new OrFilter(new ExactFilter())),
properties: ['name', 'email', 'description'],
),
GET /users?autocomplete=alice.
Validating filter parameters
use Symfony\Component\Validator\Constraints as Assert;
'length' => new QueryParameter(
filter: new ExactFilter(),
constraints: [new Assert\Length(max: 100)],
)
Invalid values yield a 422 before the query runs.
Default ordering
Set a default sort directly on the operation (no parameter needed):
new GetCollection(order: ['createdAt' => 'DESC'])
Legacy → canonical migration map
| Legacy (deprecated 4.4, removed 6.0) | Canonical replacement |
|---|---|
#[ApiFilter(SearchFilter::class, ['x' => 'exact'])] |
'x' => new QueryParameter(filter: new ExactFilter()) |
SearchFilter strategy partial |
PartialSearchFilter |
BooleanFilter |
ExactFilter + nativeType: BOOL |
NumericFilter |
ExactFilter + nativeType: INT |
BackedEnumFilter |
ExactFilter + enum nativeType |
OrderFilter |
SortFilter |
RangeFilter, DateFilter, ExistsFilter |
same class — survives as drop-in, just move to QueryParameter |
Laravel (Eloquent)
The QueryParameter wiring is identical, but Laravel ships its own Eloquent
filter set under ApiPlatform\Laravel\Eloquent\Filter\ — these are not the Doctrine
classes and the names differ. Declare them with class-level #[QueryParameter] /
#[GetCollection(parameters: …)] on the model (or DTO). The key, property,
properties, :property placeholder and constraints options work the same.
| Need | Doctrine (above) | Laravel Eloquent class |
|---|---|---|
| equality | ExactFilter |
EqualsFilter |
LIKE %x% |
PartialSearchFilter |
PartialSearchFilter |
LIKE x% / %x |
StartSearchFilter / EndSearchFilter |
StartSearchFilter / EndSearchFilter |
| boolean | ExactFilter + nativeType |
BooleanFilter |
| date range | DateFilter |
DateFilter (filterContext: ['include_nulls' => true] to keep nulls; default excludes) |
| numeric range | RangeFilter |
RangeFilter |
| sort | SortFilter |
OrderFilter |
| OR | OrFilter |
OrFilter (decorator: new OrFilter(new EqualsFilter())) |
use ApiPlatform\Laravel\Eloquent\Filter\EqualsFilter;
use ApiPlatform\Laravel\Eloquent\Filter\OrderFilter;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\QueryParameter;
#[ApiResource]
#[QueryParameter(key: 'name', filter: EqualsFilter::class)]
#[QueryParameter(key: 'sort[:property]', filter: OrderFilter::class, properties: ['name', 'id'])]
class Book extends Model {}
Constraints are Laravel validation rules (a string/array), not Symfony
constraints: new QueryParameter(key: 'name', filter: PartialSearchFilter::class, constraints: 'min:2').
Custom filters implement ApiPlatform\Laravel\Eloquent\Filter\FilterInterface
(apply(Builder $builder, mixed $values, Parameter $parameter, array $context = []): Builder);
scaffold with php artisan make:filter. There is no ExistsFilter, ComparisonFilter,
IriFilter or FreeTextQueryFilter in the Eloquent set — nativeType on a parameter
is also unused (use BooleanFilter for booleans). #[ApiFilter] is not the Laravel
idiom; models declare #[QueryParameter] directly.
このスキルのファイル
1api-filter skillに関する質問
Claude Codeにapi-filter skillをインストールするには
npx degit api-platform/skillset/skills/api-filter ~/.claude/skills/api-filterを実行してください。Claude Codeは~/.claude/skills(すべてのプロジェクト)または.claude/skills(単一プロジェクト)からskillsを読み込み、説明がタスクに一致する場合にskillを使用します。
api-filter skillはどのクライアントで使用できますか
Agent Skills形式を読み込むすべてのクライアントで使用できます: Claude Code、Codex、Gemini CLI、claude.ai(ZIPとしてアップロード)。skill内のスクリプトは、クライアントがコード実行を許可した場合にのみ実行されます。
非推奨となった #[ApiFilter] 属性をどのように置き換えればよいですか?
操作(operation)のparameters配列内でQueryParameterアプローチを使用するように移行してください。従来のフィルタを、単一目的の標準的なフィルタにマッピングします。
新しい標準的な方法で、boolean型やinteger型のフィルタリングを実装するにはどうすればよいですか?
専用のBooleanFilterを使用する代わりに、ExactFilterを使用してください。その際、SymfonyのTypeInfoを使用してネイティブ型を宣言することで、正しいキャストが保証されます。
このSKILLはLaravel Eloquentをサポートしていますか?
はい。ただし、Doctrineのクラスではなく、ApiPlatformLaravelEloquentFilterが提供する特定のEloquentフィルタクラスを使用する必要があります。