API Platform Core

https://github.com/api-platform/core
Admin
API Platform Core is a system for creating hypermedia-driven REST and GraphQL APIs with support for...
Tokens:21,586
Snippets:200
Trust Score:9.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Run the test application

Source: https://github.com/api-platform/core/blob/main/CONTRIBUTING.md

Alternative workflow using the provided test application: install assets, start the Symfony server, or use the PHP built-in web server.

```shell
cd tests/Fixtures/app
./console assets:install --symlink
symfony serve
```

```shell
# if you prefer keeping the server in your terminal:
symfony server:start --dir tests/Fixtures/app
```

```shell
# or if you prefer using the PHP built-in web server
php -S localhost:8000 -t public/
```

--------------------------------

### Set up and run tests

Source: https://github.com/api-platform/core/blob/main/src/Laravel/CONTRIBUTING.md

Commands to install dependencies, link the core package, build the workbench, install API Platform, and run tests using either testbench or PHPUnit.

```bash
cd src/Laravel
composer global require soyuka/pmu
composer global link ../../
vendor/bin/testbench workbench:build
vendor/bin/testbench api-platform:install 
vendor/bin/testbench package:test
# or
vendor/bin/phpunit
```

--------------------------------

### Preload guides for WASM execution

Source: https://github.com/api-platform/core/blob/main/docs/README.md

Preloads the guides for browser execution using php-wasm. Requires a php-wasm build in the public/php-wasm directory.

```bash
docker run -v $(pwd):/src -v $(pwd)/public/php-wasm:/public -w /public php-wasm python3 /emsdk/upstream/emscripten/tools/file_packager.py php-web.data --preload "/src" --js-output=php-web.data.js --no-node --exclude '*Tests*' '*features*' '*public*' '*/.*'
```

--------------------------------

### Get employees behind a company with DQL

Source: https://github.com/api-platform/core/blob/main/docs/adr/0003-uri-variables.md

Example to get the employees behind a company. The Employee resource uses #[GetCollection] and a UriVariable on the company property. The Company resource is defined with an identifier. The generated DQL is shown.

```php
<?php

#[ApiResource("/companies/{companyId}/employees")]
#[GetCollection]
class Employee {
  public $id;
  #[UriVariable('companyId')]
  public Company $company;
}
```

```php
<?php

#[ApiResource]
class Company {
  #[ApiProperty(identifier=true)]
  public $id;
}
```

```sql
SELECT * FROM Employee::class e
JOIN e.company c 
WHERE c.id = :companyId
```

--------------------------------

### Run a guide test with pdg-phpunit

Source: https://github.com/api-platform/core/blob/main/docs/README.md

Runs a single guide test using pdg-phpunit. Requires composer update and the pdg-phpunit binary. Uses KERNEL_CLASS and PDG_AUTOLOAD environment variables.

```bash
APP_DEBUG=0 \
PDG_AUTOLOAD='pdg-autoload.php' \
KERNEL_CLASS='\ApiPlatform\Playground\Kernel' pdg-phpunit guides/doctrine-search-filter.php
```

--------------------------------

### Start the test server

Source: https://github.com/api-platform/core/blob/main/src/Laravel/CONTRIBUTING.md

Command to serve the test application using testbench.

```bash
vendor/bin/testbench serve
```

--------------------------------

### ParameterExtension.php

Source: https://github.com/api-platform/core/blob/main/docs/adr/0006-filtering-system-and-parameters.md

Example of how to add filter logic based on parameter filter information, using the filter locator to retrieve and apply filters to the query builder.

```php
// src/Doctrine/Orm/Extension/ParameterExtension.php
$values = $request->attributes->get('_api_query_parameters');
foreach ($operation->getParameters() as $key => $parameter) {
    if (!array_key_exists($key, $values) || !($filterId = $parameter->getFilter())) {
        continue;
    }

    $filter = $this->filterLocator->has($filterId) ? $this->filterLocator->get($filterId) : null;

    if ($filter instanceof FilterInterface) {
        $context['parameter'] = $parameter;
        $context['value'] = $values[$key];
        $filter->apply($queryBuilder, $queryNameGenerator, $resourceClass, $operation, $context);
    }
}
```

--------------------------------

### Inverted Link Example with Employee and Company

Source: https://github.com/api-platform/core/blob/main/docs/adr/0004-link.md

Inverted example where the relation is only held by the employee. The Employee class uses a Link with toProperty: 'company' in the uriVariables, and the Company class uses a shorthand #[Link('company')] equivalent to #[Link(fromClass: Company::class, toClass: Employee::class, toProperty: 'company')]. The GraphQL query is the same as the classical example.

```php
<?php

#[Query]
#[GetCollection('/companies/{companyId}/employees', uriVariables: [
    'companyId' => new Link(
        fromClass: Company::class,
        toProperty: 'company'
    )
])]
class Employee
{
  public $id;

  #[ORM\ManyToMany(targetEntity: Company::class)]
  #[ORM\JoinTable(name: 'employees_companies')]
  #[ORM\JoinColumn(name: 'employee_id', referencedColumnName: 'id')]
  #[ORM\InverseJoinColumn(name: 'company_id', referencedColumnName: 'id', unique: true)]
  public Company $company;
}
```

```php
<?php

#[Query]
#[Get]
class Company
{
  public $id;

  #[Link('company')]
  // equivalent to:
  #[Link(fromClass: Company::class, toClass: Employee::class, toProperty: 'company')]
  /** @var Employee[] */
  public iterable $employees;
}
```

```graphql
{
  companies(id: "/companies/2") {
    employees {
      edges {
        node {
          id
        }
      }
    }
  }
}
```

--------------------------------

### Run MongoDB via Docker

Source: https://github.com/api-platform/core/blob/main/CONTRIBUTING.md

Starts a MongoDB instance using Docker, mapping port 27017. Useful for running the MongoDB functional tests.

```bash
docker run -p 27017:27017 mongo:latest
```

--------------------------------

### Link operations with identifiers using uriVariables

Source: https://github.com/api-platform/core/blob/main/docs/adr/0002-resource-definition.md

Shows how to link operations with identifiers using the uriVariables parameter of the Get attribute. This example references the URI Variables decision record and demonstrates mapping URI variables to entity properties.

```php
<?php
use Company;

#[Get(
    uriTemplate: "/companies/{companyId}/users/{id}", 
    uriVariables: [
        "companyId" => ["class" => Company::class, "identifiers" => ["id"], "property" => "user"], 
        "id" => ["class" => User::class, "identifiers" => ["id"]]
    ]
)]
class User {
  #[ApiProperty(identifier=true)]
  public $id;
  public Company $company;
}
```

--------------------------------

### Install MongoDB ODM Packages for PHPStan

Source: https://github.com/api-platform/core/blob/main/AGENTS.md

Install MongoDB ODM packages to fix PHPStan errors about missing MongoDB classes.

```bash
composer require --dev doctrine/mongodb-odm-bundle doctrine/mongodb-odm
```

--------------------------------

### UriVariable configuration example

Source: https://github.com/api-platform/core/blob/main/docs/adr/0003-uri-variables.md

Illustrates the decision outcome: using a POPO (UriVariable) to define URI variables with options like targetClass, targetProperty, property, identifiers, and compositeIdentifier. Note the typo 'targetClas' in the source.

```php
uriVariables: [
    'companyId' => new UriVariable(
        targetClass: Company::class,
        targetProperty: null,
        property: 'company'
        identifiers: ['id'],
        compositeIdentifier: true,
    ),
    'id' => new UriVariable( 
        targetClas: Employee::class,
        identifiers: ['id']
    )
]
```

--------------------------------

### Declare GET operation

Source: https://github.com/api-platform/core/blob/main/docs/adr/0002-resource-definition.md

Declares a single GET operation for the resource, which maps to GET /users/{id}.

```php
#[Get]
class User {}
```

--------------------------------

### Declare GET operation with custom path

Source: https://github.com/api-platform/core/blob/main/docs/adr/0002-resource-definition.md

Declares a GET operation with a custom path, mapping to GET /users.

```php
#[Get("/users")]
class User {}
```

--------------------------------

### Define API resources with ApiResource and ApiProperty attributes

Source: https://github.com/api-platform/core/blob/main/docs/adr/0002-resource-definition.md

Shows the proposed PHP 8 attributes for defining API resources and operations, including the use of ApiResource and ApiProperty attributes. The example includes two classes: Users and User, with the latter demonstrating multiple ApiResource attributes for different route configurations.

```php
<?php

#[ApiResource]
class Users
{
    #[ApiProperty(types="hydra:member")]
    public iterable $member = [];

    public float $averageRate;
}

#[ApiResource("/companies/{companyId}/users/{id}", normalizationContext=["groups"= [....]]), operations={}]
#[ApiResource(normalizationContext=["groups"= [....]], operations=[
 new Get(),
 new Post(),
])]
class User
{
    #[ApiProperty(identifier=true)]
    public $id;
}
```

--------------------------------

### Use :property URL pattern with filter substitution

Source: https://github.com/api-platform/core/blob/main/docs/adr/0006-filtering-system-and-parameters.md

Demonstrates the `:property` URL pattern in a parameter key, combined with a `QueryParameter` filter and an `ApiFilter` attribute. The filter alias 'app_filter_date_and_search' is used, and the example shows how to search on nested properties.

```php
#[GetCollection(
    uriTemplate: 'search_filter_parameter{._format}',
    parameters: [
        'searchOnTextAndDate[:property]' => new QueryParameter(filter: 'app_filter_date_and_search'),
    ]
)]

#[ApiFilter(SearchTextAndDateFilter::class, alias: 'app_filter_date_and_search', properties: ['foo', 'createdAt'], arguments: ['dateFilterProperties' => ['createdAt' => 'exclude_null'], 'searchFilterProperties' => ['foo' => 'exact']])]
class Foo {}
```

--------------------------------

### Classical Link Example with Company and Employee

Source: https://github.com/api-platform/core/blob/main/docs/adr/0004-link.md

Classical example showing the Link attribute usage for a one-to-many relation. The Company class uses #[Link(fromClass: Company::class, fromProperty: 'employees')] to define the relation, and the Employee class uses a Link in the uriVariables of the GetCollection operation. The GraphQL query retrieves employees of a company using the companies field with an id argument.

```php
<?php

#[Query]
#[Get]
class Company
{
  public $id;

  #[ORM\OneToMany(targetEntity: Employee::class, mappedBy: 'company')]
  // will automatically create:
  #[Link(fromClass: Company::class, fromProperty: 'employees')]
  /** @var Employee[] */
  public iterable $employees;
}
```

```php
<?php

#[Query]
#[GetCollection('/companies/{companyId}/employees', uriVariables: [
    'companyId' => new Link(
        fromClass: Company::class,
        fromProperty: 'employees'
    )
])]
class Employee
{
  public $id;

  #[ORM\ManyToOne(targetEntity: Company::class, inversedBy: 'employees')]
  public Company $company;
}
```

```graphql
{
  companies(id: "/companies/2") {
    employees {
      edges {
        node {
          id
        }
      }
    }
  }
}
```

--------------------------------

### Company resource with inverse relation property and DQL

Source: https://github.com/api-platform/core/blob/main/docs/adr/0003-uri-variables.md

Example of the Company resource that belongs to an employee when the inverse relation is mapped to a property. The UriVariable is placed on the employees property. The corresponding DQL is shown.

```php
<?php

#[ApiResource]
class Employee {
  public $id;
  public Company $company;
}
```

```php
<?php

#[ApiResource("/employees/{employeeId}/company")]
class Company {
  #[ApiProperty(identifier=true)]
  public $id;

  #[UriVariable('employeeId')]
  /** @var Employee[] */
  public $employees;
}
```

```sql
SELECT * FROM Company::class c
JOIN c.employees u
WHERE u.id = :id
```

--------------------------------

### Declare GetCollection operation

Source: https://github.com/api-platform/core/blob/main/docs/adr/0002-resource-definition.md

Declares a collection GET operation, which maps to GET /users.

```php
#[GetCollection]
class User {}
```

--------------------------------

### Declare subresources for employees and administrators

Source: https://github.com/api-platform/core/blob/main/docs/adr/0000-subresources-definition.md

Declares subresources for company employees and administrators using multiple ApiResource annotations. This example requires a custom DataProvider because the discriminator needs to be explicit.

```php
/**
 * @ApiResource(path="/users")
 * @ApiResource(path="/companies/{companyId}/administrators")
 * @ApiResource(path="/companies/{companyId}/employees")
 */
class User {
  /** @ApiProperty(identifier=true) */
  public int $id;

  /** @var Company[] */
  public array $companies = [];
}

class Company {
  /** @ApiProperty(identifier=true) */
  public int $id;

  /** @var User[] **/
  public array $employees;

  /** @var User[] **/
  public array $administrators;
}
```

--------------------------------

### FilterExtension.php

Source: https://github.com/api-platform/core/blob/main/docs/adr/0006-filtering-system-and-parameters.md

Example of the current filter extension logic in API Platform, showing how filters are applied to the Doctrine query builder. It also includes a comment about the OrderFilter edge case.

```php
// src/Doctrine/Orm/Extension/FilterExtension.php
foreach ($operation->getFilters() ?? [] as $filterId) {
    $filter = $this->filterLocator->has($filterId) ? $this->filterLocator->get($filterId) : null;
    if ($filter instanceof FilterInterface) {
        // Apply the OrderFilter after every other filter to avoid an edge case where OrderFilter would do a LEFT JOIN instead of an INNER JOIN
        if ($filter instanceof OrderFilter) {
            $orderFilters[] = $filter;
            continue;
        }

        $context['filters'] ??= [];
        $filter->apply($queryBuilder, $queryNameGenerator, $resourceClass, $operation, $context);
    }
}
```

--------------------------------

### Conventional commit message examples

Source: https://github.com/api-platform/core/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification. Allowed types include fix, feat, docs, spec, test, perf, ci, and chore. Only the first commit on a Pull Request needs to use a conventional commit.

```text
fix(metadata): resource identifiers from properties 
```

```text
feat(validation): introduce a number constraint
```

```text
feat(metadata)!: new resource metadata system, BC break
```

```text
docs(doctrine): search filter on uuids
```

```text
test(doctrine): mongodb disambiguation
```

--------------------------------

### Get employees collection with composite URI variable and generated DQL

Source: https://github.com/api-platform/core/blob/main/docs/adr/0003-uri-variables.md

Defines a collection endpoint to get employees of a company using a composite URI variable. The Employee class uses the 'company' property to link to Company, and the generated DQL filters by the company ID.

```php
<?php

#[ApiResource("/companies/{companyId}/employees", uriVariables: [
    'companyId' => new UriVariable(
        targetClass: Company::class,
        identifiers: ['id'],
        compositeIdentifier: true,
        property: 'company'
    )
])]
#[GetCollection]
class Employee {
  #[ApiProperty(identifier=true)]
  public $id;
  public Company $company;
}
```

```php
<?php

#[ApiResource]
class Company {
  #[ApiProperty(identifier=true)]
  public $id;
}
```

```sql
SELECT * FROM Employee::class e
JOIN e.company c 
WHERE c.id = :companyId
```

--------------------------------

### Declare operations with nested resource paths

Source: https://github.com/api-platform/core/blob/main/docs/adr/0002-resource-definition.md

Declares GET and DELETE operations with nested resource paths, acting as aliases to the /users/{id} resource.

```php
// See these as aliases to the `/users/{id}` Resource:
#[Get("/companies/{companyId}/users/{id}")]
#[Delete("/companies/{companyId}/users/{id}")]
class User {}
```

--------------------------------

### Declare two-level subresource with implicit identifiers

Source: https://github.com/api-platform/core/blob/main/docs/adr/0000-subresources-definition.md

Declares a two-level subresource to get users belonging to a company in a specific country, e.g., /countries/fr/companies/1/users. Uses implicit identifiers.

```php
/**
 * @ApiResource(path="/users")
 * @ApiResource(path="/countries/{countryId}/companies/{companyId}/users")
 */
class User {
  /** @ApiProperty(identifier=true) */
  public int $id;

  /** @var Company[] */
  public array $companies = [];
}

class Company {
  /** @ApiProperty(identifier=true) */
  public int $id;

  /** @var Country[] **/
  public array $countries = [];
}

class Country {
  /** @ApiProperty(identifier=true) */
  public string $shortName;
}
```

--------------------------------

### Initial problem with identifiers map

Source: https://github.com/api-platform/core/blob/main/docs/adr/0003-uri-variables.md

Shows the initial problem where a tuple of class and property is insufficient for URI variables in nested resources. The example uses an ApiResource attribute with an identifiers map to define URI variables for a company and an employee.

```php
<?php
use Company;

#[ApiResource("/companies/{companyId}/employees/{id}", [identifiers=["companyId" => [Company::class, "id"], "id" => [Employee::class, "id"]]])]
class Employee {
  #[ApiProperty(identifier=true)]
  public $id;
  public Company $company;
}
```

--------------------------------

### Specify operation properties on verb attribute

Source: https://github.com/api-platform/core/blob/main/docs/adr/0002-resource-definition.md

Shows specifying operation properties directly on the verb attribute, here normalizationContext on Get.

```php
<?php

#[Get("/users/{id}", normalizationContext=["group"])]
class User {}
```

--------------------------------

### Declare subresource with implicit identifiers

Source: https://github.com/api-platform/core/blob/main/docs/adr/0000-subresources-definition.md

Declares a subresource on the User model using two ApiResource annotations. The first defines the base path /users, the second defines the subresource path /companies/{companyId}/users. This example uses implicit identifiers.

```php
/**
 * @ApiResource(path="/users")
 * @ApiResource(path="/companies/{companyId}/users")
 */
class User {
  /** @ApiProperty(identifier=true) */
  public int $id;

  /** @var Company[] */
  public array $companies = [];
}
```

--------------------------------

### UuidParameter

Source: https://github.com/api-platform/core/blob/main/docs/adr/0006-filtering-system-and-parameters.md

Example of a parameter provider that alters the parameter context by converting parameter values to Uuid objects and optionally changing the filter to UuidFilter for parameters with a SearchFilter.

```php
class UuidParameter implements ParameterProviderInterface {
    public function provider(Parameter $parameter, array $uriVariables = [], array $context = []): HttpOperation 
    {
        $request = $context['request'];
        $operation = $context['operation'];
        $parameters = $request->attributes->get('_api_query_parameters');
        foreach ($parameters as $key => $value) {
            $parameter = $operation->getParameter($key);
            if (!$parameter) {
                continue;
            }

            if (!in_array('uuid', $parameter->getSchema()['type'])) {
                continue;
            }

            // TODO: should handle array values
            try {
                $parameters[$key] = Uuid::fromString($value);
            } catch (\Exception $e) {}
            
            if ($parameter->getFilter() === SearchFilter::class) {
                // Additionnaly, we are now sure we want an uuid filter so we could change it:
                $operation->withParameter($key, $parameter->withFilter(UuidFilter::class));
            }
        }

        return $operation;
    }
}
```

--------------------------------

### GroupsParameterProvider

Source: https://github.com/api-platform/core/blob/main/docs/adr/0006-filtering-system-and-parameters.md

Example of a parameter provider that alters the HTTP Operation to provide additional context, specifically setting normalization groups from request query parameters.

```php
class GroupsParameterProvider implements ParameterProviderInterface {
    public function provider(Parameter $parameter, array $uriVariables = [], array $context = []): HttpOperation 
    {
        $request = $context['request'];
        return $context['operation']->withNormalizationContext(['groups' => $request->query->all('groups')]);
    }
}
```

--------------------------------

### Company resource with inverse relation and DQL

Source: https://github.com/api-platform/core/blob/main/docs/adr/0003-uri-variables.md

Example of the Company resource that belongs to an employee using the inverse relation. The UriVariable is defined with a shortcut: new UriVariable(Employee::class, 'company') which is equivalent to targetClass: Employee::class, targetProperty: 'company'. The corresponding DQL is shown.

```php
<?php

#[ApiResource]
class Employee {
  public $id;
  public Company $company;
}
```

```php
<?php

#[ApiResource("/employee/{employeeId}/company", uriVariables: [
    'employeeId' => new UriVariable(Employee::class, 'company')
])]
class Company {
  public $id;
}
```

```sql
SELECT * FROM Company::class c
JOIN Employee::class e WITH e.companyId = c.id
WHERE e.id = :id
```

--------------------------------

### Employee resource with UriVariable and generated DQL

Source: https://github.com/api-platform/core/blob/main/docs/adr/0003-uri-variables.md

Example of an Employee resource that belongs to a Company, using the #[UriVariable] attribute on the company property. The Company resource is defined separately. The generated DQL is shown.

```php
<?php

#[ApiResource("/companies/{companyId}/employees/{id}")]
class Employee {
  public $id;

  // Note that this is the same as defining UriVariable(property: company), see below on the complex example
  #[UriVariable('companyId')] 
  public Company $company;
}
```

```php
<?php

#[ApiResource]
class Company {
  public $id;
}
```

```sql
SELECT * FROM Employee::class e
JOIN e.company c 
WHERE e.id = :id AND c.id = :companyId
```

--------------------------------

### Prepare a patch in vendor/

Source: https://github.com/api-platform/core/blob/main/CONTRIBUTING.md

Steps to prepare a patch directly in the vendor/ directory of an existing project: remove the existing copy, reinstall with Git metadata, create a branch, add a remote, and push to open a Pull Request.

```shell
rm -Rf vendor/api-platform/core
```

```shell
composer install --prefer-source
```

```shell
git checkout -b my_patch
```

```shell
git remote add <your-name> git@github.com:<your-name>/core.git
```

```shell
git push <your-name> my_patch
```

--------------------------------

### Run unit tests with PHPUnit

Source: https://github.com/api-platform/core/blob/main/CONTRIBUTING.md

Launches the unit tests for the project. The --stop-on-defect flag stops execution on the first failure or error.

```bash
vendor/bin/phpunit --stop-on-defect
```

--------------------------------

### Testing Quick-Reference Commands

Source: https://github.com/api-platform/core/blob/main/AGENTS.md

Common commands for testing in the API Platform monorepo. Includes Symfony console usage, cache clearing, removing stale vendor directories, running PHPUnit with a filter, and component testing with composer link.

```bash
# symfony console
tests/Fixtures/app/console

# Clear cache (Critical when switching branches/modes)
rm -rf tests/Fixtures/app/var/cache/test

# Remove stale vendor dirs inside src/ (if PHPUnit hangs)
# Component packages under src/ may have leftover vendor/ directories
# from previous `composer link` runs. These cause PHPUnit to scan them
# indefinitely. Remove them before running tests:
find src -name vendor -exec rm -rf {} +

# PHPUnit
vendor/bin/phpunit --filter testMethodName

#Component Testing
cd src/Metadata
composer link ../../
./vendor/bin/phpunit
```

--------------------------------

### Link root dependencies and build workbench

Source: https://github.com/api-platform/core/blob/main/src/Laravel/AGENTS.md

Run from the src/Laravel directory. Links the root dependencies and builds the testbench workbench, which is required before running tests.

```bash
composer link ../../
vendor/bin/testbench workbench:build
```

--------------------------------

### Generate changelog with tools/generate-changelog.sh

Source: https://github.com/api-platform/core/blob/main/CONTRIBUTING.md

Generates a new changelog file from the previous version to the current one, then replaces the existing CHANGELOG.md with the generated content.

```bash
bash tools/generate-changelog.sh v4.1.11 v4.1.12 > CHANGELOG.new
mv CHANGELOG.new CHANGELOG.md
```

--------------------------------

### Run all component tests

Source: https://github.com/api-platform/core/blob/main/CONTRIBUTING.md

Run tests for all API Platform components. Iterates over a list of components, cleans vendor directories, links dependencies, and runs PHPUnit with deprecation checks.

```bash
#!/bin/bash

set -e

COMPONENTS=(
  "api-platform/doctrine-common"
  "api-platform/doctrine-orm"
  "api-platform/doctrine-odm"
  "api-platform/metadata"
  "api-platform/hydra"
  "api-platform/json-api"
  "api-platform/json-schema"
  "api-platform/elasticsearch"
  "api-platform/openapi"
  "api-platform/graphql"
  "api-platform/http-cache"
  "api-platform/ramsey-uuid"
  "api-platform/serializer"
  "api-platform/state"
  "api-platform/symfony"
  "api-platform/validator"
)

PROJECT_ROOT=$(pwd)
for component in "${COMPONENTS[@]}"; do
  cd "$PROJECT_ROOT"
  find src -name vendor -exec rm -r {} \; || true
  COMPONENT_DIR=$(composer "$component" --cwd)
  cd $COMPONENT_DIR
  composer link $PROJECT_ROOT
  ./vendor/bin/phpunit --fail-on-deprecation --display-deprecations
done
exit 0
```

--------------------------------

### Debug configuration with console

Source: https://github.com/api-platform/core/blob/main/CONTRIBUTING.md

Access the console to debug configuration with APP_DEBUG=1.

```shell
APP_DEBUG=1 tests/Fixtures/app/console debug:config
```

--------------------------------

### Run a specific test file

Source: https://github.com/api-platform/core/blob/main/src/Laravel/AGENTS.md

Executes a single test file using the testbench package:test command. Replace the filename with the target test.

```bash
vendor/bin/testbench package:test Tests/NoOperationResourceTest.php
```

--------------------------------

### Define a route `/users/{keya}/{keyb}` with compositeIdentifier=false

Source: https://github.com/api-platform/core/blob/main/docs/adr/0001-resource-identifiers.md

Shows the `@ApiResource` annotation with identifiers `keya` and `keyb` and `compositeIdentifier=false`, resulting in a route with two path parameters.

```php
/**
 * @ApiResource(identifiers={"keya", "keyb"}, compositeIdentifier=false)
 */
 class User {
  /** @ApiProperty(identifier=true) */
  public string $keya;
  /** @ApiProperty(identifier=true) */
  public string $keyb;
 }
```

--------------------------------

### Run a component test

Source: https://github.com/api-platform/core/blob/main/CONTRIBUTING.md

Run tests for a single API Platform component. Requires linking dependencies with `composer link` and uses `api-platform/doctrine-common cwd` to locate the component directory.

```bash
COMPONENT_DIR=$(api-platform/doctrine-common cwd)
ROOT_DIR=$(pwd)
cd $COMPONENT_DIR
composer link $ROOT_DIR
./vendor/bin/phpunit
```

--------------------------------

### Define a route `/users/{keya}/{keyb}` with explicit composite identifiers

Source: https://github.com/api-platform/core/blob/main/docs/adr/0001-resource-identifiers.md

Shows the `@ApiResource` annotation with explicit identifiers mapping `keya` and `keyb` to the `User` class properties, and `compositeIdentifier=false`.

```php
/**
 * @ApiResource(identifiers={"keya"={User::class, "keya"}, "keyb"={User::class, "keyb"}}, compositeIdentifier=false)
 */
 class User {
  /** @ApiProperty(identifier=true) */
  public string $keya;
  /** @ApiProperty(identifier=true) */
  public string $keyb;
 }
```

--------------------------------

### Generate coverage with PHPUnit

Source: https://github.com/api-platform/core/blob/main/CONTRIBUTING.md

Generates an HTML coverage report in the 'coverage' directory. Requires the 'pcov' PHP extension. The --stop-on-defect flag stops on the first failure.

```bash
vendor/bin/phpunit --coverage-html coverage --stop-on-defect
```

--------------------------------

### Define a route `/users/{username}` using the property shortName

Source: https://github.com/api-platform/core/blob/main/docs/adr/0001-resource-identifiers.md

Shows the `@ApiResource` annotation with identifiers mapping `username` to the `User` class and the `shortName` property. The property is marked as identifier.

```php
/**
 * @ApiResource(identifiers={"username"={User::class, "shortName"}})
 */
 class User {
  /** @ApiProperty(identifier=true) */
  public string $shortName;
 }
```

--------------------------------

### Run MongoDB functional tests

Source: https://github.com/api-platform/core/blob/main/CONTRIBUTING.md

Runs functional tests for MongoDB. Requires a running MongoDB instance and sets the MONGODB_URL and APP_ENV environment variables.

```bash
MONGODB_URL=mongodb://localhost:27017 APP_ENV=mongodb vendor/bin/phpunit --group mongodb
```

--------------------------------

### Apply Parameter to a class and a single operation

Source: https://github.com/api-platform/core/blob/main/docs/adr/0006-filtering-system-and-parameters.md

Shows how to apply the `QueryParameter` attribute both globally (on a class) and per-operation (on a `GetCollection` operation). The `parameters` argument on the operation and the attribute on the class both use the key 'and'.

```php
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\QueryParameter;

#[GetCollection(parameters: ['and' => new QueryParameter])]
#[QueryParameter('and')]
class Book {}
```

--------------------------------

### Define a subresource `/companies/{companyId}/users/{id}`

Source: https://github.com/api-platform/core/blob/main/docs/adr/0001-resource-identifiers.md

Shows two `@ApiResource` annotations on the `User` class: one for the base path `/users` and one for the subresource path `/companies/{companyId}/users`. The subresource defines identifiers for both `companyId` and `id`.

```php
/**
 * @ApiResource(path="/users", identifiers={"id": {User::class, "id"}})
 * @ApiResource(path="/companies/{companyId}/users", identifiers={"companyId": {Company::class, "id"}, "id": {User::class, "id"}})
 */
class User {
  /** @ApiProperty(identifier=true) */
  public int $id;

  /** @var Company[] */
  public array $companies = [];
}

class Company {
  /** @ApiProperty(identifier=true) */
  public int $id;

  /** @var User[] */
  public $users;
}
```

--------------------------------

### Run PHPStan Analysis

Source: https://github.com/api-platform/core/blob/main/AGENTS.md

Run PHPStan static analysis on a component. Requires running at least one PHPUnit test first to warm up the cache.

```bash
vendor/bin/phpstan analyse src/YourComponent
```

--------------------------------

### Clean Stale Vendor Directories for PHPStan

Source: https://github.com/api-platform/core/blob/main/AGENTS.md

Clean up nested vendor directories inside src/ components that can confuse PHPStan.

```bash
find src -name vendor -exec rm -r {} \;
```

--------------------------------

### Define the Parameter attribute class

Source: https://github.com/api-platform/core/blob/main/docs/adr/0006-filtering-system-and-parameters.md

Defines the new `ApiPlatform\Metadata\Parameter` class with constructor properties for key, schema, OpenAPI parameter, provider, filter, property, description, required, priority, and extra properties. This class is the base for parameter definitions.

```php
namespace ApiPlatform\Metadata;

use ApiPlatform\OpenApi;

final class Parameter {
    /**
     * @param array{type?: string}|null              $schema
     * @param array<string, mixed>                   $extraProperties
     * @param ProviderInterface|callable|string|null $provider
     * @param FilterInterface|string|null            $filter
     */
    public function __construct(
        protected ?string $key = null,
        protected ?array $schema = null,
        protected ?OpenApi\Model\Parameter $openApi = null,
        protected mixed $provider = null,
        protected mixed $filter = null,
        protected ?string $property = null,
        protected ?string $description = null,
        protected ?bool $required = null,
        protected ?int $priority = null,
        protected ?array $extraProperties = [],
    ) {
    }
}
```

--------------------------------

### Increase ulimit for coverage generation

Source: https://github.com/api-platform/core/blob/main/CONTRIBUTING.md

Increases the open file limit to avoid 'too many open files' errors when generating coverage. Run this before the coverage command if needed.

```bash
ulimit -n 4000
```

--------------------------------

### Define a route `/users/{composite}` with composite identifiers

Source: https://github.com/api-platform/core/blob/main/docs/adr/0001-resource-identifiers.md

Shows the `@ApiResource` annotation with identifiers set to `composite`, enabling composite identifiers. The route uses the format `/users/keya=value1;keyb=value2`.

```php
/**
 * @ApiResource(identifiers={"composite"})
 */
 class User {
  /** @ApiProperty(identifier=true) */
  public string $keya;
  /** @ApiProperty(identifier=true) */
  public string $keyb;
 }
```

--------------------------------

### Company resource via inverse relation with targetProperty and generated DQL

Source: https://github.com/api-platform/core/blob/main/docs/adr/0003-uri-variables.md

Defines a Company resource that is accessed through an inverse relation from Employee. The Company class uses 'targetProperty' to specify the inverse property, and the generated DQL joins Employee with a WITH condition on the company ID.

```php
<?php

#[ApiResource]
class Employee {
  public $id;
  public Company $company;
}
```

```php
<?php

#[ApiResource("/employees/{employeeId}/company", uriVariables: [
    'employeeId' => new UriVariable(
        targetClass: Employee::class, 
        targetProperty: 'company'
        property: null,
        identifiers: ['id'],
        compositeIdentifier: true
    )
])]
class Company {
  #[ApiProperty(identifier=true)]
  public $id;
}
```

```sql
SELECT * FROM Company::class c
JOIN Employee::class e WITH e.companyId = c.id
WHERE e.id = :id
```

--------------------------------

### Declare two-level subresource with explicit identifiers

Source: https://github.com/api-platform/core/blob/main/docs/adr/0000-subresources-definition.md

Declares a two-level subresource with explicit identifiers, mapping each path parameter to a class and property.

```php
/**
 * @ApiResource(path="/users", identifiers={"id": {User::class, "id"}})
 * @ApiResource(path="/countries/{countryId}/companies/{companyId}/users", identifiers={"companyId": {Company::class, "id"}, "countryId": {Country::class, "shortName"}, "id": {User::class, "id"}})
 */
class User {
  /** @ApiProperty(identifier=true) */
  public int $id;

  /** @var Company[] */
  public array $companies = [];
}

class Company {
  /** @ApiProperty(identifier=true) */
  public int $id;

  /** @var Country[] **/
  public array $countries = [];
}

class Country {
  /** @ApiProperty(identifier=true) */
  public string $shortName;
}
```

--------------------------------

### Define a route `/users/{id}` with explicit identifiers

Source: https://github.com/api-platform/core/blob/main/docs/adr/0001-resource-identifiers.md

Shows the `@ApiResource` annotation with explicit identifiers mapping `id` to the `User` class and `id` property. This is an alternative to the default configuration.

```php
/**
 * @ApiResource(identifiers={"id": {User::class, "id"}})
 */
 class User {
  /** @ApiProperty(identifier=true) */
  public int $id;
 }
```

--------------------------------

### Pseudo-SQL for employee belonging to company

Source: https://github.com/api-platform/core/blob/main/docs/adr/0003-uri-variables.md

Pseudo-SQL query that would be generated to fetch an employee belonging to a company using the URI variables from the decision outcome.

```sql
SELECT * FROM Employee::class e
JOIN e.company c 
WHERE e.id = :id AND c.id = :companyId
```

--------------------------------

### Employee resource with composite URI variable and generated DQL

Source: https://github.com/api-platform/core/blob/main/docs/adr/0003-uri-variables.md

Defines an Employee resource with a composite URI variable that includes the company identifier. The Employee class uses a property 'company' to link to the Company class, and the generated DQL joins the company and filters by both employee and company IDs.

```php
<?php

#[ApiResource("/companies/{companyId}/employees/{id}", uriVariables: [
    'companyId' => new UriVariable(
        targetClass: Company::class,
        property: 'company',
        identifiers: ['id'],
        compositeIdentifier: true
    ],
    'id' => new UriVariable(
        targetClass: Employee::class,
        identifiers: ['id']
    )
])]
class Employee {
  #[ApiProperty(identifier=true)]
  public $id;
  public Company $company;
}
```

```php
<?php

#[ApiResource]
class Company {
  #[ApiProperty(identifier=true)]
  public $id;
}
```

```sql
SELECT * FROM Employee::class e
JOIN e.company c 
WHERE e.id = :id AND c.id = :companyId
```

--------------------------------

### Define a route `/users/{username}` with explicit username identifier mapping

Source: https://github.com/api-platform/core/blob/main/docs/adr/0001-resource-identifiers.md

Shows the `@ApiResource` annotation with identifiers mapping `username` to the `User` class and `username` property. This is an alternative to the shorthand form.

```php
/**
 * @ApiResource(identifiers={"username": {User::class, "username"}})
 */
 class User {
  /** @ApiProperty(identifier=true) */
  public string $username;
 }
```

--------------------------------

### Run PHPStan static analysis

Source: https://github.com/api-platform/core/blob/main/src/Laravel/AGENTS.md

Runs PHPStan analysis on the Laravel component. Use this to check for static analysis errors.

```bash
./vendor/bin/phpstan analyse
```

--------------------------------

### Define a route `/users/{username}` using the username identifier

Source: https://github.com/api-platform/core/blob/main/docs/adr/0001-resource-identifiers.md

Shows the `@ApiResource` annotation with identifiers set to `username`, using the property name as the identifier. The `@ApiProperty(identifier=true)` marks the property.

```php
/**
 * @ApiResource(identifiers={"username"})
 */
 class User {
  /** @ApiProperty(identifier=true) */
  public string $username;
 }
```

--------------------------------

### Define a route `/users/{id}` with default identifier

Source: https://github.com/api-platform/core/blob/main/docs/adr/0001-resource-identifiers.md

Shows the minimal `@ApiResource` annotation with no explicit identifiers, relying on the default `id` property. The `@ApiProperty(identifier=true)` marks the property as the identifier.

```php
/**
 * @ApiResource
 */
 class User {
  /** @ApiProperty(identifier=true) */
  public int $id;
 }
```

--------------------------------

### FilterInterface with getDescription method

Source: https://github.com/api-platform/core/blob/main/docs/adr/0006-filtering-system-and-parameters.md

Defines the current API Platform filter interface. The getDescription method returns an array keyed by filter parameter names, with values containing property, type, required, optional strategy, is_collection, swagger, openapi, and schema keys. The swagger and openapi keys allow additional path operation parameters, while schema defines a JSON Schema for the parameter.

```php
interface FilterInterface
{
    /**
     * Gets the description of this filter for the given resource.
     *
     * Returns an array with the filter parameter names as keys and array with the following data as values:
     *   - property: the property where the filter is applied
     *   - type: the type of the filter
     *   - required: if this filter is required
     *   - strategy (optional): the used strategy
     *   - is_collection (optional): if this filter is for collection
     *   - swagger (optional): additional parameters for the path operation,
     *     e.g. 'swagger' => [
     *       'description' => 'My Description',
     *       'name' => 'My Name',
     *       'type' => 'integer',
     *     ]
     *   - openapi (optional): additional parameters for the path operation in the version 3 spec,
     *     e.g. 'openapi' => [
     *       'description' => 'My Description',
     *       'name' => 'My Name',
     *       'schema' => [
     *          'type' => 'integer',
     *       ]
     *     ]
     *   - schema (optional): schema definition,
     *     e.g. 'schema' => [
     *       'type' => 'string',
     *       'enum' => ['value_1', 'value_2'],
     *     ]
     * The description can contain additional data specific to a filter.
     *
     * @see \ApiPlatform\OpenApi\Factory\OpenApiFactory::getFiltersParameters
     */
    public function getDescription(string $resourceClass): array;
}
```

--------------------------------

### Declare POST and PATCH operations

Source: https://github.com/api-platform/core/blob/main/docs/adr/0002-resource-definition.md

Declares POST and PATCH operations with custom paths, mapping to POST /users and PATCH /users/{id}.

```php
#[Post("/users")]
#[Patch("/users/{id}")]
class User {}
```

--------------------------------

### Company resource via inverse relation with property and generated DQL

Source: https://github.com/api-platform/core/blob/main/docs/adr/0003-uri-variables.md

Defines a Company resource accessed through an inverse relation mapped to a property 'employees' on the Company class. The generated DQL joins the employees property directly.

```php
<?php

#[ApiResource]
class Employee {
  public $id;
  public Company $company;
}
```

```php
<?php

#[ApiResource("/employees/{employeeId}/company", uriVariables: [
    'employeeId' => new UriVariable(
        targetClass: Employee::class,
        property: 'employees',
        identifiers: ['id'],
    )
])]
class Company {
  #[ApiProperty(identifier=true)]
  public $id;

  /** @var Employee[] */
  public $employees;
}
```

```sql
SELECT * FROM Company::class c
JOIN c.employees e
WHERE e.id = :id
```

--------------------------------

### Explicit default operations with verb attributes

Source: https://github.com/api-platform/core/blob/main/docs/adr/0002-resource-definition.md

The equivalent of the minimal ApiResource attribute, explicitly declaring the default operations using verb attributes. This shows the underlying operations generated by the convenience form.

```php
<?php

#[Get]
#[GetCollection]
#[PostCollection]
#[Put]
#[Delete]
class User {}
```

--------------------------------

### Remove the test database

Source: https://github.com/api-platform/core/blob/main/src/Laravel/CONTRIBUTING.md

Command to drop the SQLite database used by the test workbench.

```bash
vendor/bin/testbench workbench:drop-sqlite-db
```

--------------------------------

### Set default operation properties via ApiResource

Source: https://github.com/api-platform/core/blob/main/docs/adr/0002-resource-definition.md

Shows using the ApiResource attribute to set default properties on operations, such as normalizationContext.

```php
<?php

#[ApiResource(normalizationContext=["groups"= [....]])]
#[Get("/users/{id}")]
class User {}
```

--------------------------------

### Minimal ApiResource attribute usage

Source: https://github.com/api-platform/core/blob/main/docs/adr/0002-resource-definition.md

A minimal resource definition using the ApiResource attribute. This is the convenience form that generates default operations for the resource.

```php
<?php

#[ApiResource]
class User {}
```

--------------------------------

### Declare subresource with explicit identifiers

Source: https://github.com/api-platform/core/blob/main/docs/adr/0000-subresources-definition.md

Declares a subresource with explicit identifiers. The identifiers map each path parameter to a class and property, as explained in ADR-0001-resource-identifiers.

```php
/**
 * @ApiResource(path="/users", identifiers={"id": {User::class, "id"}})
 * @ApiResource(path="/companies/{companyId}/users", identifiers={"companyId": {Company::class, "id"}, "id": {User::class, "id"}})
 */
class User {
  /** @ApiProperty(identifier=true) */
  public int $id;

  /** @var Company[] */
  public array $companies = [];
}
```

--------------------------------

### Update composer version with composer blend

Source: https://github.com/api-platform/core/blob/main/CONTRIBUTING.md

Updates the version node in composer.json and all sub-component composer.json files.

```bash
composer blend --json-path=version
```

--------------------------------

### Fix coding standards with PHP CS Fixer

Source: https://github.com/api-platform/core/blob/main/CONTRIBUTING.md

Automatically fix coding standards issues using PHP CS Fixer. The first run may take some time; subsequent runs use cache.

```shell
vendor/bin/php-cs-fixer fix --diff
```

--------------------------------

### Set _api_query_parameters request attribute

Source: https://github.com/api-platform/core/blob/main/docs/adr/0006-filtering-system-and-parameters.md

Shows how API Platform parses the query string and sets the `_api_query_parameters` request attribute. The filter may or may not use this attribute.

```php
$queryString = RequestParser::getQueryString($request);
$request->attributes->set('_api_query_parameters', $queryString ? RequestParser::parseRequestParams($queryString) : []);
```

--------------------------------

### ApiResource metadata class definition

Source: https://github.com/api-platform/core/blob/main/docs/adr/0002-resource-definition.md

Shows the internal ApiResource class that holds metadata properties. The comment notes that $extraProperties was previously named $attributes.

```php
<?php

namespace ApiPlatform\Metadata;

class ApiResource {
    public string $iri;
    public bool $mercure;
    public string $security;
    public bool $paginationEnabled;
    // etc.

    /** this was named $attributes before **/
    public array $extraProperties;
}
```

--------------------------------

### Link filter property with required flag

Source: https://github.com/api-platform/core/blob/main/docs/adr/0006-filtering-system-and-parameters.md

Uses the `property` field to link a filter and document the `hydra:search` context. The `required` flag is set to true, and the key is 'q'.

```php
#[QueryParameter(key: 'q', property: 'hydra:freetextQuery', required: true)]
class Dummy {}
```

--------------------------------

### Declared hydra:search context JSON

Source: https://github.com/api-platform/core/blob/main/docs/adr/0006-filtering-system-and-parameters.md

The resulting `hydra:search` context JSON that the previous PHP attribute declares. It includes the template and mapping with the variable, property, and required flag.

```json
{
    "hydra:template": "/dummy{?q}",
    "hydra:mapping": [
        ["@type": "IriTemplateMapping", "variable": "q", "property": "hydra:freetextQuery", "required": true],
    ]
}
```

--------------------------------

### ParameterProviderInterface

Source: https://github.com/api-platform/core/blob/main/docs/adr/0006-filtering-system-and-parameters.md

Interface for a parameter provider that can optionally transform request parameters and provide modifications to the current operation. It is used during the Provider phase (RequestEvent::REQUEST).

```php
/**
 * Optionnaly transforms request parameters and provides modification to the current Operation.
 */
interface ParameterProviderInterface
{
    /**
     * @param array<string, mixed> $parameters
     * @param array<string, mixed> $context
     */
    public function provide(Parameter $parameter, array $parameters = [], array $context = []): ?HttpOperation;
}
```
Tokens:
Raw