api-filter skill
검색, 정렬 및 범위 필터링을 위해 canonical QueryParameter 방식을 사용하여 API Platform 컬렉션에 필터를 추가합니다.
- GitHub 스타
- 29
- 파일
- 1
- 마지막 커밋
- 2026년 10월 22일
- 라이선스
- —
- 허용된 도구
- —
api-filter skill은 무엇을 하나요?
검색, 정렬 및 범위 필터링을 위해 canonical QueryParameter 방식을 사용하여 API Platform 컬렉션에 필터를 추가합니다.
skill의 SKILL.md에서 생성된 요약입니다.
api-filter skill 정보
이 SKILL은 백엔드 개발자가 API Platform 컬렉션에 검색, 정렬 및 범위 필터링을 구현할 수 있도록 지원합니다. API Platform 4.4 이상 버전에서 요구되는 방식인 operation의 parameters array 내 QueryParameter 방식을 사용하여 필터를 선언하는 방법을 제공합니다. 이 방식은 operation별로 명시적이며 모든 state provider와 함께 작동하므로, 특정 데이터 서브셋에 대한 클라이언트 요청을 처리하는 신뢰할 수 있는 방법입니다.
개발자는 이를 통해 #[ApiFilter]와 같은 더 이상 사용되지 않는 클래스 수준의 속성이나 SearchFilter, BooleanFilter, OrderFilter와 같은 특정 필터를 대체할 수 있습니다. 이 SKILL은 ExactFilter, PartialSearchFilter, DateFilter, SortFilter를 포함한 단일 목적 필터 세트를 통해 Doctrine ORM과 MongoDB ODM을 모두 지원합니다. 또한 IriFilter를 사용한 IRI 조회나 FreeTextQueryFilter를 사용하여 여러 필드에 걸쳐 단일 값을 브로드캐스팅하는 것과 같은 특수한 요구 사항도 처리합니다. Laravel 사용자의 경우, 특정 Eloquent 필터 세트 및 Laravel validation rules 사용에 대한 가이드를 제공합니다.
agent가 수행할 수 있는 작업
- 1레거시 API 필터 마이그레이션더 이상 사용되지 않는 클래스 수준의 #[ApiFilter] 속성을 현대적인 QueryParameter 방식으로 변환합니다.
- 2다중 필드 자유 텍스트 검색 추가여러 다른 속성에서 값을 확인하는 단일 검색 파라미터를 생성합니다.
- 3Laravel Eloquent 필터 구성특정 Eloquent 필터 클래스와 validation rules를 사용하여 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 array 내에서 QueryParameter 방식을 사용하도록 마이그레이션해야 하며, 기존 필터를 단일 목적의 canonical 대체 필터로 매핑해야 합니다.
새로운 canonical 방식으로 boolean 또는 integer 필터링을 어떻게 구현하나요?
전용 BooleanFilter 대신 ExactFilter를 사용하고, Symfony의 TypeInfo를 사용하여 네이티브 타입을 선언함으로써 올바른 캐스팅을 보장합니다.
이 SKILL은 Laravel Eloquent를 지원하나요?
네, 하지만 Doctrine 클래스 대신 ApiPlatformLaravelEloquentFilter에서 제공하는 특정 Eloquent 필터 클래스를 사용해야 합니다.