Yii API application

An application template for a new API project

The package is an API application template. If you need console only or classic web please start with corresponding templates:

• Console application template
• Web application template

Requirements

• PHP 8.2 - 8.5.

Installation

Local installation

If you do not have Composer, you may install it by following the instructions at getcomposer.org.

Create a project:

composer create-project yiisoft/app-api myproject
cd myproject

Note

Ensure that Composer is executed with the same PHP version that will be used to run the application.

Copy the example environment file and adjust as needed:

cp .env.example .env

To run the app:

./yii serve

Now you should be able to access the application through the URL printed to console. Usually it is http://localhost:8080.

Tip

The .env file is for local development only and is excluded from version control. In production, configure environment variables via your server or container instead.

Installation with Docker

Warning

Docker compose version 2.24 or above is required.

Fork the repository, clone it, then:

cd myproject
make composer update

To run the app:

make up

To stop the app:

make down

The application is available at https://localhost.

The benchmarkable PostgreSQL endpoint is available at /postgres/orders. It reads recent joined rows from seeded orders and customers tables through yiisoft/db-pgsql using a persistent PDO connection.

Use make bench to benchmark / only, and make bench-db to benchmark /postgres/orders only. The latter gives an isolated RPS number for the database-backed endpoint.

Both targets accept BENCH_NAME="...", MODE=steady|ramp and CAPTURE_METRICS=0|1. The default benchmark name is FrankenPHP classic. When CAPTURE_METRICS=1, the run stores time-series metrics in runtime/benchmarks/: k6-timeseries.json for compact request/latency/failure series, summary.json for the aggregate k6 summary, docker-stats.csv for container CPU and memory samples, and metadata.env for the exact run settings. Runtime k6 warnings are suppressed by default with K6_LOG_OUTPUT=none so a failing target does not flood the console; use K6_LOG_OUTPUT=stderr to restore k6 log output when debugging.

By default, the benchmark runner auto-sizes PREALLOCATED_VUS and MAX_VUS from the configured request rate. For steady mode it uses RATE; for ramp mode it uses the highest target found in STAGES. You normally do not need to set VU counts manually, but both variables still work as explicit overrides. The default heuristic is intentionally aggressive and now prefers lower dropped-iteration rates over conservative VU usage. AUTO_MAX_VUS_LIMIT may be used as a higher or lower automatic safety ceiling when needed.

Examples:

make bench
make bench-db RATE=8000
make bench MODE=ramp
make bench-db MODE=ramp CAPTURE_METRICS=1
make bench-db BENCH_NAME="FrankenPHP worker" MODE=ramp CAPTURE_METRICS=1
make bench PREALLOCATED_VUS=500 MAX_VUS=3000

To turn one or more captured runs into a self-contained HTML report with graphs for RPS, failure rate, latency, dropped iterations, CPU, and memory:

make bench-report
make bench-report runtime/benchmarks
make bench-report runtime/benchmarks/<run-dir>
make bench-report runtime/benchmarks/<run-dir-1> runtime/benchmarks/<run-dir-2>

Other make commands are available in the Makefile and can be listed with:

make help

Directory structure

The application template has the following structure:

config/                     Configuration files.
    common/                 Common configuration and DI definitions.
    console/                Console-specific configuration.
    environments/           Environment-specific configuration (dev/test/prod).
    web/                    Web-specific configuration.
docker/                     Docker-specific files.
public/                     Files publically accessible from the Internet.
    index.php               Entry script.
runtime/                    Files generated during runtime.
src/                        Application source code.
    Api/                    API action handlers and API-specific code.
        Shared/             Shared API components (middleware, presenters, factories).
    Console/                Console commands.
    Shared/                 Code shared between API and console applications.
    bootstrap.php           Application bootstrap (autoloading, environment setup).
    Environment.php         Environment configuration class.
tests/                      A set of Codeception tests for the application.
    Api/                    API endpoints tests.
    Console/                Console command tests.
    Functional/             Functional tests.
    Unit/                   Unit tests.
vendor/                     Installed Composer packages.
Makefile                    Config for make command.
yii                         Console application entry point.

Testing

The template comes with ready to use Codeception configuration. To execute tests, in local installation run:

./vendor/bin/codecept build

APP_ENV=test ./yii serve > ./runtime/yii.log 2>&1 &
./vendor/bin/codecept run

For Docker:

make codecept build
make codecept run

The Docker environment also starts PostgreSQL and seeds realistic benchmark data from docker/postgres/initdb.d/10-benchmark.sql. To regenerate that dump:

make generate-pgsql-dump

Static analysis

The code is statically analyzed with Psalm. To run static analysis:

./vendor/bin/psalm

or, using Docker:

make psalm

Support

If you need help or have a question, check out Yii Community Resources.

License

The Yii3 API template is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.

Support the project

Follow updates