Development

Development

Setup

git clone https://github.com/dcarbone/php-consul-api.git
cd php-consul-api
composer install

The static analysis and refactoring tools each have their own composer.json under tools/, so their dependencies don't conflict with the library's:

composer install --working-dir tools/rector
composer install --working-dir tools/phpstan
composer install --working-dir tools/psalm

Tests

Tests live under tests/Unit and tests/Integration.

# unit tests only; no Consul needed
./vendor/bin/phpunit -c phpunit.xml --testsuite unit

# everything
./vendor/bin/phpunit -c phpunit.xml

# a single integration suite
./vendor/bin/phpunit -c phpunit.xml --testsuite usage-kv

Suite	Contents
unit	tests/Unit
usage-config	Config integration
usage-config-states	Config end-to-end: address formats, unix socket, token precedence, TLS/mTLS
usage-request	Request integration
usage-acl	ACL client
usage-agent	Agent client
usage-catalog	Catalog client
usage-coordinate	Coordinate client
usage-event	Event client
usage-kv	KV client
usage-operator	Operator client
usage-session	Session client
usage-random	additional client coverage (tests/Integration/Random)

Integration tests

Integration tests start and stop a single consul agent -dev themselves (tests/ConsulManager.php, tests/run_consul.sh, tests/stop_consul.sh). This means:

• The consul binary must be on your PATH. CI uses the version in CONSUL_VERSION in .github/workflows/tests.yaml.
• Nothing else may be listening on 127.0.0.1:8500.
• The agent uses tests/consul.hcl, with ACLs enabled and management token 00000000-0000-0000-0000-000000000001.
• Data, the PID file, and logs are written to tmp/ (tmp/consul.log is useful when a test fails).
• usage-config-states also generates a CA and certificates with consul tls into tmp/tls, and starts the agent with a unix socket (tmp/consul.sock) and an HTTPS listener on 127.0.0.1:8501 that requires a client certificate. openssl is used to build a hashed CAPath directory; the CAPath test is skipped without it.

Static analysis and code style

composer rector -- --dry-run   # check
composer rector                # apply
composer phpstan
composer psalm

Rector (rector.php) handles both refactoring and code style. CI runs all three, plus the test suite against PHP 8.2, 8.3, 8.4, and 8.5.

Conventions

• declare(strict_types=1); in every source file. Test files don't use it.
• Use null|Foo rather than ?Foo.
• Use self as the return type of fluent setters.
• List fields have variadic setters (setTags(string ...$Tags)). array parameters have a docblock giving the element type.
• Each model field has a matching constructor parameter, getter, and setter, all with the same casing as the property.
• Methods that return nothing are declared : void, including test methods.
• Use named arguments where possible.
• Only add docblocks to describe types that can't be expressed natively.
• uint64 fields are BigInteger (see Big Integers). Duration fields are Time\Duration (see Durations and Time).
• New models should mirror the Go struct in hashicorp/consul/api, including field names and omitempty behaviour.
• Model tests should set fields through both the constructor and the setters, and verify them through both the getters and the properties.