PHPackages                             pinga/pinga - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Queues & Workers](/categories/queues)
4. /
5. pinga/pinga

ActiveProject[Queues & Workers](/categories/queues)

pinga/pinga
===========

Pinga Framework is a PHP microframework that seamlessly integrates with Swoole, Swow or Workerman, allowing for lightning-fast web applications

v0.9.5(3y ago)3233MITPHPPHP ^8.1

Since Mar 1Pushed 3y ago1 watchersCompare

[ Source](https://github.com/getpinga/pinga)[ Packagist](https://packagist.org/packages/pinga/pinga)[ RSS](/packages/pinga-pinga/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (15)Versions (27)Used By (0)

Pinga
=====

[](#pinga)

[![StandWithUkraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/badges/StandWithUkraine.svg)](https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md)

[![SWUbanner](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg)](https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md)

 [![Pinga](https://camo.githubusercontent.com/b45efef1ffb282f020ae3a9196ef20651953fce7e65dd7c869ff30de6a1c043d/68747470733a2f2f67657470696e67612e636f6d2f6c6f676f2e737667)](https://camo.githubusercontent.com/b45efef1ffb282f020ae3a9196ef20651953fce7e65dd7c869ff30de6a1c043d/68747470733a2f2f67657470696e67612e636f6d2f6c6f676f2e737667)

Pinga is a high-performance, non-blocking, event-driven PHP framework built on top of the Swoole, Swow, and Workerman frameworks. It provides a simple yet powerful way to create HTTP APIs and web applications with support for route handling, environment configuration, logging, templating, and custom session management. The framework can be easily extended and customized to fit any project's needs, making it a versatile solution for creating scalable, efficient, and feature-rich APIs and web applications. Based on the wonderful [refortunato/SwooleApiHttpExample](https://github.com/refortunato/SwooleApiHttpExample).

Table of Contents
=================

[](#table-of-contents)

- [Requirements](#requirements)
- [Components](#components)
- [Installation](#installation)
- [Configuration](#configuration)
- [Basic Usage](#basic-usage)
- [Routing](#routing)
- [Controllers](#controllers)
- [Templating](#templating)
- [Logging](#logging)
- [Sessions](#sessions)
- [Cookies](#cookies)
- [Static File Loader](#static-file-loader)
- [File Upload](#file-upload)
- [Contributing](#contributing)
- [License](#license)

Requirements
------------

[](#requirements)

- PHP 8.1 or higher
- Swoole, Swow, or Workerman installed and enabled
- Composer

Components
----------

[](#components)

- Logging.
- Database: [Pinga\\Db](https://github.com/getpinga/db). For the Swoole version, use [Pinga/db-swoole](https://github.com/getpinga/db-swoole) or [Pinga/db-pool](https://github.com/getpinga/db-pool).
- Caching: [Pinga\\Cache](https://github.com/getpinga/cache).
- Templates: [Twig](https://github.com/twigphp/Twig) or [Plates](https://github.com/thephpleague/plates).
- Support for .env files: required settings will be changed from .env file.
- Sessions.
- Cookies.

Installation
------------

[](#installation)

1. Make sure that Swoole, Swow, or Workerman are installed and enabled.
2. Create your application:

```
composer create-project --prefer-dist pinga/pinga myapp
```

3. Copy the **sample-env** file to create a new **.env** file:

```
cp sample-env .env
```

Configuration
-------------

[](#configuration)

Edit the .env file to configure the following environment variables:

- **HOST**: The host address for the server to bind to.
- **HOSTNAME**: The domain of the server.
- **PORT**: The port for the server to listen on.
- **PIDFILE**: The file path to store the process ID of the server.

Basic Usage
-----------

[](#basic-usage)

Start the server using one of the following commands:

```
php start-swoole-http.php
php start-swow-http.php
php start-workerman-http.php
```

For Swoole version, you can also use `run.sh`.

Access the API in your browser or via a REST client using the configured **HOSTNAME** and **PORT**.

Routing
-------

[](#routing)

To define routes for the API, edit the **config/routes.php** file. Use the following methods to define routes:

- **get()**: Define a route for the **GET** HTTP method.
- **post()**: Define a route for the **POST** HTTP method.
- **put()**: Define a route for the **PUT** HTTP method.
- **delete()**: Define a route for the **DELETE** HTTP method.

Controllers
-----------

[](#controllers)

Create a controller class in the **src/Controllers** directory. The controller class should include methods that handle specific route actions.

Use the **IndexController.php** as template to create a new controller.

Templating
----------

[](#templating)

Pinga API supports both Twig and Plates for templating.

To render a Twig template, use **TwigController.php** in a controller method.

To render a Plates template, use **PlatesController.php** in a controller method.

Logging
-------

[](#logging)

Pinga API includes a basic logging class, **PiLogger**, that can be customized to fit your needs. To use the logger, choose the option you would like and replace `$app['logger'] = new PiLogger(null, true);` with one of those:

### Log to a file

[](#log-to-a-file)

```
$app['logger'] = new PiLogger('/tmp/file.log');
```

### Log to stdout

[](#log-to-stdout)

```
$app['logger'] = new PiLogger(null, true);
```

### Log to both file and stdout

[](#log-to-both-file-and-stdout)

```
$app['logger'] = new PiLogger($logFilePath, true);
```

### Log action

[](#log-action)

```
 $app['logger']->info("Log details");
```

All log levels are available:

- debug
- info
- notice
- warning
- error
- critical
- alert
- emergency

Sessions
--------

[](#sessions)

Pinga API provides a custom session handling class, **PiSession**, that leverages the Pinga\\Cache library for storing session data. This class ensures non-blocking session handling to maintain the performance benefits of Swoole, Swow, or Workerman.

Here's how to use the **PiSession** class in your project:

1. Add in the beginning of your start-xxx-http.php file:

```
use App\PiSession;

$app['session'] = new PiSession();
$app['session']->start();
```

2. Include the **PiSession** class in your controller:

```
use App\PiSession;
```

3. Add in the beginning of your controller:

```
private $session;

public function __construct($app) {
    $this->session = $app['session'];
}
```

4. Set a session value:

```
$this->session->set('key', 'value');
```

5. Get a session value:

```
$value = $this->session->get('key', 'default_value');
```

Note: Ensure that the **/cache** directory exists and has the proper permissions to allow the session handler to read and write session data.

Cookies
-------

[](#cookies)

Cookies are a convenient way to store small amounts of data on the client-side, which can be useful for maintaining session state, tracking user preferences, and more. This guide will show you how to work with cookies in your controllers using the **PiCookie** class which provides two methods for working with cookies: **setCookie** and **getCookie**. You can use these methods in your controllers to set and get cookies easily.

### Set a Cookie

[](#set-a-cookie)

To set a cookie in a controller, use the **setCookie** method of the **PiCookie** class. This method takes the following parameters:

1. **$response**: The response object that you want to add the cookie to.
2. **$name**: The name of the cookie.
3. **$value**: The value of the cookie.
4. **$expire** (optional): The number of seconds until the cookie expires. The default value is **3600** seconds (1 hour).
5. **$path** (optional): The path on the server where the cookie will be available. The default value is **/**.
6. **$domain** (optional): The domain that the cookie is available to. The default value is an **empty** string.
7. **$secure** (optional): Whether the cookie should be transmitted only over a secure HTTPS connection. The default value is **false**.
8. **$httpOnly** (optional): Whether the cookie should be accessible only through the HTTP protocol. The default value is **true**.

Here's an example of how to use the setCookie method in a controller:

In the beginning of your controller method place:

```
$cookie = new PiCookie();
```

Right before **$return** place:

```
$response = $cookie->setCookie($response, 'cookie_name', 'cookie_value');
```

### Get a Cookie

[](#get-a-cookie)

To get the value of a cookie in a controller, use the **getCookie** method of the **PiCookie** class. This method takes the following parameters:

1. **$request**: The request object that contains the cookies.
2. **$name**: The name of the cookie.
3. **$default** (optional): The default value to return if the cookie is not found. The default value is **null**.

Here's an example of how to use the getCookie method in a controller:

In the beginning of your controller method place:

```
$cookie = new PiCookie();
```

Change your response like:

```
$cookieValue = $cookie->getCookie($request, 'cookie_name', 'default_value');
$responseBody = json_encode(['name' => 'Foo', 'cookieValue' => $cookieValue]);
$contentLength = strlen($responseBody);
```

Static File Loader
------------------

[](#static-file-loader)

The Static File Loader is a utility class that allows your application to serve static files, such as CSS, JavaScript, images, or other assets, from the **/public** directory. It is designed to work seamlessly with Swoole, Swow, and Workerman frameworks, ensuring non-blocking and efficient serving of static content. When a request is received for a static file, the **PiStaticFileHandler** class will handle it and return an appropriate response. If the file is not found, the request will continue to be processed by your application's other route handlers.

Note: Make sure your static files are placed in the **/public** directory, as this is the default location that the **PiStaticFileHandler** class will look for files.

File Upload
-----------

[](#file-upload)

In this section, we will cover how to handle file uploads using the provided controller with Swoole, Swow, and Workerman servers. The example assumes you have already set up the server request object correctly, as demonstrated in previous topics. Then you use the following code in your controller that will process uploaded files:

```
// Get the uploaded files from the request
$uploadedFiles = $request->getUploadedFiles();

// Process the uploaded files
foreach ($uploadedFiles as $uploadedFile) {
// Check if the file is uploaded without any errors
   if ($uploadedFile->getError() === UPLOAD_ERR_OK) {
        // Get the file information
        $filename = $uploadedFile->getClientFilename();
        $fileSize = $uploadedFile->getSize();
        $fileType = $uploadedFile->getClientMediaType();

        // Process the uploaded file, e.g., save it to a specific directory
        $targetPath = '/path/to/save/' . $filename;
        $uploadedFile->moveTo($targetPath);
    }
}
```

Contributing
------------

[](#contributing)

We welcome contributions to improve and extend Pinga. Please follow these steps to contribute:

1. Fork the repository.
2. Create a new branch for your changes.
3. Commit your changes with descriptive commit messages.
4. Push your changes to your fork.
5. Create a pull request describing your changes and referencing any related issues.

License
-------

[](#license)

Pinga is released under the [MIT License](https://opensource.org/licenses/MIT). See the **LICENSE** file for more information.

###  Health Score

26

—

LowBetter than 43% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity12

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

25

Last Release

1147d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/f8f87416e80fdfb906a1e9d206c9a20584ae27bdd20815170b69efd49e8e9436?d=identicon)[getpinga](/maintainers/getpinga)

---

Top Contributors

[![getpinga](https://avatars.githubusercontent.com/u/121483313?v=4)](https://github.com/getpinga "getpinga (146 commits)")

---

Tags

asynccoroutineframeworkmicroframeworkmicroservicephpswooleswowworkermanasyncswooleproject templatemicroframeworkswow

### Embed Badge

![Health badge](/badges/pinga-pinga/health.svg)

```
[![Health](https://phpackages.com/badges/pinga-pinga/health.svg)](https://phpackages.com/packages/pinga-pinga)
```

###  Alternatives

[cakephp/cakephp

The CakePHP framework

8.8k18.5M1.6k](/packages/cakephp-cakephp)[shopware/platform

The Shopware e-commerce core

3.3k1.5M3](/packages/shopware-platform)[contao/core-bundle

Contao Open Source CMS

1231.6M2.4k](/packages/contao-core-bundle)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

595.2M386](/packages/shopware-core)[ec-cube/ec-cube

EC-CUBE EC open platform.

78527.0k1](/packages/ec-cube-ec-cube)[tempest/framework

The PHP framework that gets out of your way.

2.1k23.1k9](/packages/tempest-framework)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)