Module for Zend Framework that allows to register the application in Consul's Service Discovery.

dev-master 2017-07-25 16:19 UTC

This package is not auto-updated.

Last update: 2024-02-18 00:00:17 UTC


This module provides logic that allows the application to register itself in Consul's Service Discovery.

Build Status


  1. PHP: 5.6 or 7.X
  2. ZF3-compatible application
  3. reachable Consul Agent API


Require module with Composer:

composer require rstgroup/zf-consul-service-discovery-module

The next step is adding module to ZF system configuration (config/application.config.php):

return [
    'modules' => [

.. and (optionally, but we strongly suggest it) - install rstgroup/zf-local-config-module.


The module requires the presence of:

  • Consul API URL
  • service name
  • service ID (if service name is not unique across the same Consul Agent instance)

Example configuration:

return [
    'rst_group'       => [
        'service_discovery' => [
            'service_name' => 'my-service',
            'service_id'   => 'my-service-1',
            'consul'       => [
                'url' => 'http://consul-instance.loc:8500',
                'check' => [
                    'url' => 'http://my-service/check-endpoint',
                    'name' => 'check-endpoint',
                    'interval' => '30s',
                'tags' => [ 'service', 'httpd', 'php' ],

Minimal configuration:

return [
    'rst_group'       => [
        'service_discovery' => [
            'service_name' => 'my-service',
            'consul'       => [
                'url' => 'http://consul-instance.loc:8500',

We suggest using rstgroup/zf-external-config-module to pass rst_group.service_discovery.consul.url key during the provisioning stage - as infrastructure configuration should not be stored in application's repository.

If your service is about to be ran in many instances - then also its name should be passed during the provisioning state.


Module provides simple commands to register/deregister service in Consul Agent. Both of them are described when you run php public/index.php with no arguments.

Registering service in Consul Agent

In POST-install script:

  1. (optional) Provide required configuration for Consul Agent:

    php public/index.php local-config set rst_group.service_discovery.consul.url http://consul-instance.loc:8500

    Let's assume that service name and ID is already in configuration.

    Remeber that this command requires you to have rstgroup/zf-external-config-module installed as well.

  2. Register service:

    php public/index.php service-discovery consul register

Deregistering service

IN POST-uninstall stage:

php public/index.php service-discovery consul deregister

Running commands with parameters

service-discovery consul register command has defined set of optional attributes that allows you to override settings stored in your app's configuration. You can list the full usage information by simply typing:

php public/index.php

Here's the part that describes the zf-consul-service-discovery-module's commands:

    ZF Service Discovery - Consul
      index.php service-discovery consul register [--id=] [--name=] [--tags=] [--check] [--check-url=] [--check-name=] [--check-interval=]    Register service in Consul Agent's Service Discovery.                                       
      --id=               Override ID of service.                                                                                                                                                                                                               
      --name=             Override name of service.                                                                                                                                                                                                             
      --tags=             Override list of tags. Write tags as comma-separated list with no whitespaces.                                                                                                                                                                                            
      --check             If flag is set, the check is expected to be defined.                                                                                                                                                                                  
      --check-url         Override service's check URL                                                                                                                                                                                                          
      --check-name        Override service's check name                                                                                                                                                                                                         
      --check-interval    Override service's check interval                                                                                                                                                                                                     
      index.php service-discovery consul deregister [--id=]    Deregister service in Consul Agent' Service Discovery.                                                                                                                     
      --id=    Override ID of service.