README

rgzone/folk-bundle is a Symfony bundle for integration with the PHP Folk extension.

The current direction is inspired by Folk-Project/folk-symfony, but this bundle is being developed as a dedicated Symfony bundle with a focus on runtime integration.

Repository: https://bitbucket.org/stelzek/symfony-folk-bundle

Folk SDK: https://github.com/Folk-Project/folk-sdk

Requirements

• PHP >= 8.4
• Symfony ^8.0
• PHP extension ext-folk >=0.1 <0.1.8
• folk/sdk:^0.2.6

The PHP version floor is intentionally set to 8.4+, which also excludes older Symfony generations from the supported matrix.

Installation

Once the public API stabilizes, installation is expected to look like this:

If your project uses Symfony Flex with the custom recipes repository, configure it 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

composer require rgzone/folk-bundle

If you do not install through Flex recipes, create folk.toml manually in the project root:

[workers]
script = "vendor/bin/folk-server"
count = 5

[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 and the default listen addresses are also exposed through FOLK_HTTP_LISTEN, FOLK_GRPC_LISTEN, and FOLK_METRICS_LISTEN.

Worker binary:

vendor/bin/folk-worker

TOML worker command example:

[worker]
command = ["vendor/bin/folk-worker"]

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.

Autoload namespace: RGZ\FolkBundle\