rgzone/folk-bundle

Symfony bundle for integration with the PHP Folk extension.

0.0.3 2026-06-15 14:23 UTC

Requires

• php: >=8.4
• ext-folk: >=0.1 <0.1.8
• folk/sdk: ^0.2.6
• symfony/framework-bundle: ^8.0
• symfony/runtime: ^8.0

Requires (Dev)

• phpunit/phpunit: ^11.5

MIT

• Alexey Buldyk

• symfony
• http
• runtime
• gRPC
• php-extension
• folk

README

rgzone/folk-bundle is a Symfony bundle for applications running on folk-project/ext-folk. It implements folk/sdk through symfony/dependency-injection.

The bundle was inspired by Folk-Project/folk-symfony and focuses on symfony/runtime integration.

Installation

If your project uses Symfony Flex, configure the custom recipes repository first:

composer config --json extra.symfony.endpoint '["https://bitbucket.org/stelzek/symfony-recipes/raw/master/recipes/index.json","flex://defaults"]'
composer config --json extra.symfony.allow-contrib true

Install the bundle package into your Symfony application:

composer require rgzone/folk-bundle

If you do not install through Flex recipes, enable the bundle in config/bundles.php and create folk.toml manually in the project root:

return [
    // ...
    RGZ\FolkBundle\FolkBundle::class => ['all' => true],
];

[workers]
script = "vendor/rgzone/folk-bundle/bin/folk-server"
count = 6

[http]
listen = "0.0.0.0:18181"

[grpc]
listen = "0.0.0.0:15051"

[metrics]
listen = "0.0.0.0:19191"

With the Flex recipe, the same file is created automatically. Configuration details are documented in the official Folk configuration guide: https://folk-project.github.io/folk-releases/configuration/.

The server bootstrap reads folk.toml from the project root.

Handler Services

WorkerLoop consumes handlers by interface id.

Default bundle bindings:

• Folk\Sdk\Http\HttpModeHandler -> RGZ\FolkBundle\Handler\Http\FolkHttpHandler
• Folk\Sdk\Grpc\GrpcModeHandler -> Folk\Sdk\Grpc\GrpcRouter

The bundle does not register a default binding for:

• Folk\Sdk\Jobs\JobsModeHandler

Jobs are application-defined only.

Examples for config/services.yaml:

HTTP override:

services:
  App\Folk\Http\AppHttpHandler:
    autowire: true

  Folk\Sdk\Http\HttpModeHandler: '@App\Folk\Http\AppHttpHandler'

gRPC router override:

services:
  App\Folk\Grpc\AppGrpcRouter:
    class: Folk\Sdk\Grpc\GrpcRouter

  Folk\Sdk\Grpc\GrpcModeHandler: '@App\Folk\Grpc\AppGrpcRouter'

gRPC service registration inside the router:

services:
  App\Grpc\GreeterService:
    tags:
      - { name: 'folk.grpc', service: 'helloworld.Greeter' }

The tagged service itself is passed to GrpcRouter::register() as the handler object.

Jobs binding:

services:
  App\Folk\Jobs\AppJobsHandler:
    autowire: true

  Folk\Sdk\Jobs\JobsModeHandler: '@App\Folk\Jobs\AppJobsHandler'

If you need direct access to a concrete class, register that concrete service under its own id and alias the interface to it.

Reset Between Requests

The bundle bridges Symfony service resetting into the Folk worker loop.

If your services implement Symfony's reset contract, they are reset between loop iterations through services_resetter:

use Symfony\Contracts\Service\ResetInterface;

final class SomeStatefulService implements ResetInterface
{
    public function reset(): void
    {
        // clear per-request state here
    }
}

For bundle-specific reset hooks, implement Folk\Sdk\Reset\ResettableInterface. Such services are auto-tagged and registered in the worker loop automatically:

use Folk\Sdk\Reset\ResettableInterface;

final class SomeFolkResetter implements ResettableInterface
{
    public function reset(): void
    {
        // clear loop-local state here
    }
}

Use this for state that must survive service construction but must not leak from one handled request or job to the next.