neomerx/json-api

The performance test suite uses Blackfire for profiling. To set it up, ensure you have Docker and Docker Compose installed, then configure your Blackfire credentials.

1. Prerequisites:

   • Install Docker.
   • Install Docker Compose.

2. Configuration:

   • Copy the sample environment file to the active environment file: cp blackfire.io.env.sample blackfire.io.env
   • Open blackfire.io.env and populate the following fields with your credentials from the Blackfire.io credentials page:
     • Client ID
     • Client Token
     • Server ID
     • Server Token

To install the sample application and its dependencies, use Composer from the project root.

$ composer install

Run the performance profiling suite using Docker Compose. This command executes the sample script through Blackfire to generate performance metrics.

Note: The first execution will be slow as it must download the necessary Docker images. Subsequent runs will be faster.

To run the profile:

docker-compose run --rm cli_php blackfire run php -d zend.assertions=-1 /app/sample/sample.php -t=100

The output provides basic performance information and a URL that links to a detailed profiling graph on Blackfire.io.

The sample application includes built-in performance testing capabilities. You can run tests using the -t flag.

Default execution: Run with default parameters:

$ php sample.php -t

Custom iterations: Run with a specific number of iterations (e.g., 10,000) and measure execution time using the system time command:

$ time php sample.php -t=10000

Docker-based testing: If you have docker-compose installed, you can run performance tests across different PHP versions (7.1, 7.2, 7.3, and 7.4) using the provided Composer scripts:

$ composer perf-test-php-7-1
$ composer perf-test-php-7-2
$ composer perf-test-php-7-3
$ composer perf-test-php-7-4

If you need to free up space on your local machine, you can remove the container image created by the performance suite using the following command:

docker rmi perf_cli_php

When calling Parser::parse($data, $paths), you can provide an array of strings to $paths to control which relationships are traversed.

Paths are normalized using the DocumentInterface::PATH_SEPARATOR (typically .). If you provide a path like a.b.c, the parser internally treats it as requesting a, a.b, and a.b.c.

A relationship is only parsed if:

1. Its path is present in the requested $paths.
2. The relationship contains data (it is not empty/null).

This mechanism prevents the parser from unnecessarily traversing deep relationship trees that were not explicitly requested.

The Parser::parse() method determines how to process the input based on the type of $data provided and its corresponding schema:

• Resource: If the data has a schema in the SchemaContainerInterface, it is parsed as a resource. The parser will then recursively parse its relationships if they are requested in the $paths argument.
• Identifier: If the data is an instance of SchemaIdentifierInterface, it is parsed as an identifier.
• Collection: If the data is an array or Traversable and contains items that have schemas or are identifiers, it is parsed as a collection of resources or identifiers.
• Null: If the data is null, it is parsed as null document data.
• Error: If no schema can be found for the provided data type, an InvalidArgumentException is thrown with the message: No Schema found for top-level resource ‘%s‘.

The project provides a docker-compose.yml file in the sample/ directory to spin up various PHP CLI environments for development or testing. Each service maps the project root to /app inside the container and provides a TTY for interactive use.

Available services include:

• cli_7_1_php (PHP 7.1)
• cli_7_2_php (PHP 7.2)
• cli_7_3_php (PHP 7.3)
• cli_7_4_php (PHP 7.4)

cli_7_4_php:
  image: php:7.4-cli
  container_name: cli_php_7_4_json_api
  volumes:
    - ./..:/app
  working_dir: /app
  tty: true

Run the sample application using the PHP CLI. The application demonstrates various JSON API encoding scenarios, including:

• Encoding a resource with no relationships.
• Encoding a resource with included relationships.
• Demonstrating sparse fieldset and filter usage.
• Demonstrating top-level links and meta information usage.

$ php sample.php

To convert a domain object into a JSON API compliant string, use the Encoder class. You must provide a mapping between your object classes and their corresponding BaseSchema implementations. You can also configure a URL prefix for generated links and pass standard PHP JSON encoding options.

$encoder = Encoder::instance([
        Author::class => AuthorSchema::class,
    ])
    ->withUrlPrefix('http://example.com/api/v1')
    ->withEncodeOptions(JSON_PRETTY_PRINT);

echo $encoder->encodeData($author) . PHP_EOL;