# PhalApi 2.x for PHP API Services and Generated API Documentation

> PhalApi is a lightweight PHP framework for API services, with request routing, parameter rules, database configuration, generated documentation, and optional extensions. It suits PHP teams that need a dedicated interface layer, but deployment still involves a web server, PHP-FPM, and writable runtime directories, with database settings when needed.

**phalapi/phalapi** — PhalApi开源接口框架，简称π框架，一个轻量级PHP开源接口框架，专注于接口服务开发。接口，从简单开始！

- Repository: https://github.com/phalapi/phalapi
- Website: http://www.phalapi.net
- Stars: 1,600 · Forks: 367
- Language: PHP
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/phalapi-phalapi

## PhalApi's PHP API Service Scope

PhalApi, also called the π framework, is a lightweight PHP open source interface framework focused on API service development. Its intended users are PHP developers who need a structured place to define endpoints, declare request parameters, return service results, and publish documentation about those endpoints. The repository identifies API development, microservices, REST-style interfaces, and SOAP web services among its topics, although the README concentrates on HTTP requests and does not explain a SOAP-specific configuration.

The repository separates request-facing code from business and persistence code. API sources are placed in `src/app/Api`, business logic in `src/app/Domain`, shared utilities in `src/app/Common`, and data operations in `src/app/Model`. The README calls this arrangement the ADM pattern. This gives an endpoint a predictable location and leaves room to isolate domain logic from the HTTP-facing method. It does not, however, prescribe all application logic automatically. A team still has to decide whether an operation belongs in the API method, domain layer, model, or shared utility code.

PhalApi is not described as a general-purpose website framework. Its documented entry point accepts a service request, and its online documentation page is part of the distribution. Teams looking for conventional web application routing, page templates, user-facing administration, or broader framework conventions would need to investigate whether PhalApi's API-oriented model fits those requirements.

## Service Routing, Rules, and Response Flow

A request selects an API service through the `service` parameter, with `s` accepted as the short form. The README uses `App.Site.Index` as the default example. The corresponding class is `App\Api\Site`, stored in `./src/app/Api/Site.php`, and it extends `PhalApi\Api`.

The API class declares request parameters in `getRules()`. In the documented example, the `index` action accepts `username`. Its rule includes the parameter name, a default value of `PhalApi`, and a Chinese description. The `index()` method then returns an array containing a title, the `PHALAPI_VERSION` constant, and `$_SERVER['REQUEST_TIME']`.

The visible data flow is direct. An HTTP request names a service, the framework resolves that name to API code, parameter rules describe the request contract, the API method performs the operation, and the framework emits a response envelope. The README's example response contains `ret`, `data`, and `msg`, with `ret` set to `200` in the successful case. The API annotations also declare `@exception 400` for invalid requests, but the README does not show the implementation that produces that error. Authentication, serialization settings, and the complete error-handling flow also require consultation of the PhalApi 2.x documentation.

## Composer Installation and Nginx Deployment

The README provides a Composer command for creating a PhalApi project. No version constraint appears in this installation command, so the version written into a new project should be recorded for deployment tracking.

```bash
$ composer create-project phalapi/phalapi
```

Manual installation is also documented. After downloading and extracting the Git project, Composer dependencies can be updated with the command below. The repository includes a `vendor` directory, but the README states that Composer packages should be managed through `composer install` or `composer update` rather than edited manually.

```bash
$ composer update
```

For Nginx, the README says the website root must point to the `public` directory. Its example listens on port `80`, uses `dev.phalapi.net` as the server name, and passes PHP requests to `127.0.0.1:9000`. It also contains a commented Unix socket option. These are deployment examples, not universal settings.

```nginx
server {
    listen 80;
    server_name dev.phalapi.net;
    root /path/to/phalapi/public;
    charset utf-8;

    location / {
        index index.php;
    }
}
```

The complete Nginx example also defines a `location ~ \.php$` block with `SCRIPT_FILENAME`, `fastcgi_index`, and `fastcgi_params`. The README says to restart Nginx after changing the configuration. Database access is configured in `./config/dbs.php`, and the `runtime` directory requires write permission.

## Generated Documentation and the First Endpoint

The first documented API request uses `App.Site.Index` with the short `s` parameter:

```text
http://dev.phalapi.net/?s=App.Site.Index
```

The README shows a successful response containing `ret`, `data`, and `msg`. Within `data`, it shows a title, framework version, and request timestamp. Because the default `username` is `PhalApi`, the documented output includes `Hello PhalApi`. This request provides a basic check that Nginx, PHP, service resolution, parameter rules, and response generation are connected correctly.

PhalApi also exposes `docs.php` as its online API documentation entry point. According to the README, it derives documentation from parameter configuration and code comments. The documented page supports testing an interface, displaying request examples, generating offline HTML documentation, and updating as the endpoint definitions change. That keeps some contract information close to the implementation, but it does not mean every operational concern is documented automatically. The README does not explain access control for `docs.php`, publication workflows for generated HTML, or whether endpoint documentation is intended to be exposed publicly in production.

The offline output belongs under `public/docs`, while the online entry point is `public/docs.php`. Teams that publish generated documentation must therefore treat that directory as deployable content and avoid assuming that source comments alone are the only artifact involved.

## Database Configuration and Directory Permissions

Database connectivity is configured in `config/dbs.php`. The README example defines a `servers` collection and an entry named `db_master`. Its settings include database type, host, name, user, password, port, charset, PDO attribute behavior, and PDO driver options. The example uses `mysql`, `127.0.0.1`, `phalapi`, `root`, port `3306`, and `UTF8`.

The configuration comment says the database type currently supports `mysql` and `sqlserver`. The `pdo_attr_string` setting controls whether query results are returned uniformly as strings. Setting it to `false`, as in the README example, leaves normal PDO result typing in place. That matters for code expecting integers, booleans, or strings because a deployment-wide database setting can affect application behavior.

The repository also contains `.env.example`, which lists `PHALAPI_DB_TYPE`, `PHALAPI_DB_HOST`, `PHALAPI_DB_NAME`, `PHALAPI_DB_USER`, `PHALAPI_DB_PASSWORD`, `PHALAPI_DB_PORT`, and `PHALAPI_DB_CHARSET`. The README does not explain when to prefer those variables over `config/dbs.php`, so a deployment should follow the linked setup documentation rather than assume both configuration paths are interchangeable.

Schema setup is also less automated than the interface layer. The repository includes `data/phalapi.sql`, identified as the installation database file, but the README does not show a migration command. Projects should plan how that SQL file is applied and how subsequent schema changes are managed.

## Runtime Storage, SDKs, and Extension Boundaries

The `runtime` directory contains file cache and log subdirectories. The README explicitly requires write access to it. The public directory also contains an `uploads` directory marked as requiring write permission. These are concrete deployment constraints: installing the source without granting the required permissions can lead to cache, logging, or upload failures depending on which features the application uses.

The project includes an `sdk` directory, but the README does not document an SDK generation command, supported client languages, or a synchronization process between endpoint definitions and generated clients. Teams should not assume that the presence of this directory means SDK maintenance is automatic. A change to parameter rules can affect a client contract, so generated client artifacts would need explicit review if they are used.

The README lists separate projects for features that would otherwise expand the core application. These include `phalapi/auth` for authorization, `phalapi/cli` for command-line support, and `phalapi/fast-route` for FastRoute-based routing. It also lists storage and messaging extensions for Aliyun OSS, PHPMailer, Qiniu, and QR codes. This modular approach lets a basic API installation remain smaller, but each adopted extension introduces another Composer dependency whose compatibility and upgrade path must be checked separately.

## FastRoute Extension and Other Architectural Choices

The clearest documented routing alternative is `phalapi/fast-route`. The default flow uses a service name such as `App.Site.Index` and maps it to a class under `src/app/Api`. The FastRoute extension offers a different routing mechanism for projects that need its conventions. The README does not provide performance measurements, a configuration example, or a migration guide for this extension, so its effect on routing and maintenance cannot be stated beyond the fact that it exists.

Another architectural choice is the separation between API, domain, and model directories. A smaller project may place more behavior directly in an API class, while a larger service can keep validation-facing methods separate from domain and persistence code. That flexibility is useful, but the repository does not force all projects to use the same balance between those layers.

The README does not name a competing full-stack framework, so it provides no factual comparison with Laravel, Symfony, Slim, or another PHP project. The meaningful distinction available from the repository is narrower. PhalApi explicitly centers its distribution and documentation around API services, generated interface documentation, parameter rules, database access, and a service-oriented directory layout. A general application framework may serve different routing, UI, and project-structure requirements, but those differences require project-specific documentation rather than an invented comparison.

## Maintenance, Licensing, and Upgrade Work

The repository is not archived. Its last push was on 2026-07-23. Recent listed releases include `v2.23.4` on 2026-01-29, `v2.23.3` on 2025-03-31, and `2.23.2` on 2024-10-17. These dates establish repository activity and release cadence, but the README excerpt does not promise long-term support for every earlier version.

The declared license is `Apache-2.0`, and the repository contains a `LICENSE` file along with a Composer license badge. That identifies the project's declared licensing terms. Determining obligations for a modified or distributed deployment requires reviewing the actual license text and distribution context.

An upgrade can affect more than `composer.json`. The framework, application classes, database configuration, generated documentation, and extensions are separate upgrade surfaces. The repository contains `tests`, but the README does not describe how to execute them or which environments they cover. It also does not document a rollback procedure or a compatibility matrix.

The most concrete maintenance boundary is therefore the project structure. Operators must preserve the public web root, validate `config/dbs.php` and database settings, keep `runtime` writable, check upload permissions if uploads are enabled, and review each adopted extension separately. Without release-specific migration notes, this is manual verification work rather than a documented one-command framework upgrade.

## Conclusion

PhalApi is a reasonable fit for PHP teams building documented HTTP API services with separate API, domain, and model layers. It is less suitable for teams seeking a general web framework or a deployment without web-server configuration. Verify first that PHP-FPM can serve the `public` directory, then confirm database settings where used, directory permissions, and the generated documentation route.

## FAQ

### How do I install PhalApi with Composer?

The README documents `composer create-project phalapi/phalapi` for creating a project. The command shown there does not specify a version constraint.

### How do I call a service in PhalApi?

Use the `service` parameter or the short `s` form to select the API service. The documented example is `http://dev.phalapi.net/?s=App.Site.Index`, which corresponds to `App\Api\Site::index()` in `./src/app/Api/Site.php`.

### Does PhalApi generate API documentation?

Yes. The README says `docs.php` generates online documentation from parameter configuration and code comments. It also lists interface testing, request examples, offline HTML generation, and real-time updates.

### Which directory should Nginx use as the PhalApi website root?

The README says to point the website root to the `public` directory. Its example uses `/path/to/phalapi/public` and configures PHP requests through FastCGI.

## Sources

- [License: Apache-2.0](https://github.com/phalapi/phalapi/blob/master-2x/LICENSE)
- [phalapi/phalapi on GitHub](https://github.com/phalapi/phalapi)
- [Project website](http://www.phalapi.net)
- [README](https://github.com/phalapi/phalapi/blob/master-2x/README.md)
- [Releases](https://github.com/phalapi/phalapi/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/phalapi-phalapi