DEVELOPMENT.md

Development

For repeatability and consistency across different operating systems, we use the 3 Musketeers pattern. If you're on Windows, it might be a good idea to use Git bash for following the steps below.

Note: After cloning the repository, copy .env.dist to .env.

Skipping the step above would result in a "The "PHP_USER" variable is not set. Defaulting to a blank string" warning

We use docker and docker compose to perform a lot of our static analysis and testing. If you're planning to develop for this library, it'll help to install docker engine and the compose plugin.

Development tasks are generally run through a Makefile. Running make or make help will list available targets.

To ensure you have all the correct packages installed locally in your dev environment, you can run

make install

This will install all the library dependencies to the /vendor directory.

To update these dependencies, you can run

make update

To downgrade to the lowest dependencies, you can run

make update-lowest

To run all checks without doing a composer update:

make all-checks

Coding Guidelines

Even though it may not be reflected everywhere in the codebase yet, we aim to provide software which is easy to read and change. The methods described in Clean Code book(s) by Robert C. Martin (Uncle Bob) are a de facto industry standards nowadays. Reading those books is highly recommended, however you can take a look at the examples given at Clean Code PHP. While we have no rule to strictly follow said methods and patterns, they are highly recommended as an orientation for your pull requests and to be referenced in reviews.

We might add additional guidelines regarding for example testing in the future.

Pull Requests

To propose changes to the codebase, you need to open a pull request to the opentelemetry-php project.

After you open the pull request, the CI will run all the associated github actions.

To ensure your PR doesn't emit a failure with GitHub actions, it's recommended that you run important the CI tests locally with the following command:

make all # composer update, then run all checks
make all-lowest # composer update to lowest dependencies, then run all checks

This does the following things:

• Installs/updates all the required dependencies for the project
• Uses Rector to refactor your code according to our standards.
• Uses php-cs-fixer to style your code using our style preferences.
• Uses Deptrac to check for dependency violations inside our code base
• Makes sure the composer files for the different components are valid
• Runs all of our phpunit unit tests.
• Performs static analysis with Phan, Psalm and PHPStan

Other PHP versions

We aim to support officially supported PHP versions, according to https://www.php.net/supported-versions.php. The developer image ghcr.io/open-telemetry/opentelemetry-php/opentelemetry-php-base is tagged as 8.1, 8.2 and 8.3 respectively, with 8.1 being the default. You can execute the test suite against other PHP versions by running the following command:

PHP_VERSION=8.1 make all
#or
PHP_VERSION=8.3 make all

Proto Generation

Our protobuf files are committed to the repository into the /proto folder. These are used in gRPC connections to the upstream. These get updated when the opentelemetry-proto repo has a meaningful update. The maintainer SIG is discussing a way to make this more automatic in the future.

To generate protobuf files for use with this repository, you can run the following command:

make protobuf

This will replace proto/otel/Opentelemetry and proto/otel/GPBMetadata with freshly generated code based on the latest tag from opentelemetry-proto, which can then be committed.

Semantic Conventions Generation

Autogenerated semantic convention files are committed to the repository in the /src/SemConv directory. These files get updated when new version of opentelemetry-specification released.

SEMCONV_VERSION=1.8.0 make semconv

Run this command in the root of this repository.

Automatic Refactoring and Upgrading

We use Rector to automatically refactor our code according to given standards and upgrade the code to supported PHP versions. The associated configuration can be found here

If you want to check what changes would be applied by rector, you can run:

make rector

This command will simply print out the changes rector would make without actually changing any code.

To refactor your code following our given standards, you can run:

make rector-write

This command applies the changes to the code base. Make sure to run make style (see below) after running the rectorcommand as the changes might not follow our coding standard.

Styling

We use PHP-CS-Fixer for our code linting and standards fixer. The associated configuration can be found here

To ensure that your code follows our coding standards, you can run:

make style

This command executes a required check that also runs during CI. This process performs the required fixes and prints them out. Code that doesn't meet the style pattern will emit a failure with GitHub actions.

Static Analysis

We use Phan for static analysis. Currently, our phan configuration is just a standard default analysis configuration. You can use our phan docker wrapper to easily perform static analysis on your changes.

To run Phan, one can run the following command:

make phan

This process will return 0 on success. Usually this process is performed as part of a code checkin. This process runs during CI and is a required check. Code that doesn't match the standards that we have defined in our phan config will emit a failure in CI.

We also use Psalm as a second static analysis tool.
You can use our psalm docker wrapper to easily perform static analysis on your changes.

To run Psalm, one can run the following command:

make psalm

This process will return 0 on success. Usually this process is performed as part of a code checkin. This process runs during CI and is a required check. Code that doesn't match the standards that we have defined in our psalm config will emit a failure in CI.

We use PHPStan as our third tool for static analysis. You can use our PHPStan docker wrapper to easily perform static analysis on your changes.

To perform static analysis with PHPStan run:

make phpstan

This process will return 0 on success. Usually this process is performed as part of a code checkin. This process runs during CI and is a required check. Code that doesn't match the standards that we have defined in our PHPStan config will emit a failure in CI.

Testing

To make sure the tests in this repo work as you expect, you can use the included docker test wrapper.
To run the test suite, execute

make test

This will output the test output as well as a test coverage analysis (text + html - see tests/coverage/html). Code that doesn't pass our currently defined tests will emit a failure in CI

Code Coverage

We use codecov.io to track code coverage for this repo. This is configured in the php.yaml github action. We don't require a specific level of code coverage for PRs to pass - we just use this tool in order to understand how a PR will potentially change the amount of code coverage we have across the code base. This tool isn't perfect - sometimes we'll see small deltas in code coverage where there shouldn't be any - this is nothing to fret about.

If code coverage does decrease on a pull request, you will see a red X in the CI for the repo, but that's ok - the reviewer will use their judgement to determine whether or not we have sufficient code coverage for the change.

Dependency Validation

To make sure the different components of the library are distributable as separate packages, we have to check for dependency violations inside the code base. Dependencies must create a DAC in order to not create recursive dependencies. For this purpose we use Deptrac and the respective configuration can be found here

To validate the dependencies inside the code base, you can run:

make deptrac

This command will create an error for any violation of the defined dependencies. If you add new dependencies to the code base, please configure them in the rector configuration.

PhpMetrics

To generate a report showing a variety of metrics for the library and its classes, you can run:

make phpmetrics

This will generate a HTML PhpMetrics report in the var/metrics directory. Make sure to run make test before to create the test log-file, used by the metrics report.

API Documentation

We use phpDocumentor to automatically generate API documentation from DocBlocks in the code.

To generate a recent version of the API documentation, you can run:

make phpdoc

To preview the documentation and changes you might expect, you can run:

make phpdoc-preview

This will start a HTTP server running at http://localhost:8080 serving the updated documentation files.