README

The AppSignal for PHP library.

Requirements

This package requires:

• PHP version >= 8.4
• opentelemetry extension

Installing opentelemetry PHP extension

First, make sure the build dependencies required to install the OpenTelemetry PHP extension are installed.

On Ubuntu/Debian:

sudo apt-get install gcc make autoconf

or macOS:

brew install gcc make autoconf

Then, install the OpenTelemetry PHP extension using PECL:

pecl install opentelemetry

Finally, enable the extension in php.ini

[opentelemetry]
extension=opentelemetry.so

For more ways to install opentelemetry extension (pie, pickle, Docker), see the Installing the OpenTelemetry extension section in AppSignal Docs.

Installation

Install the latest version of AppSignal with:

composer require appsignal/appsignal-php

After that, run:

vendor/bin/appsignal init

This command will scaffold a config file in config/appsignal.php and install auto-instrumentations for your application framework (Laravel or Symfony).

Basic usage

use Appsignal\Appsignal;

// add a custom instrumentation span to the current trace
Appsignal::instrument('some_event', closure: fn() => sleep(1));

// add a custom instrumentation span to the current trace with data
Appsignal::instrument('some_event', ['region' => 'eu'], closure: fn() => sleep(1));

// customize the name of the trace
Appsignal::setAction('my action'),

// add attributes to the current span
Appsignal::addAttributes([
    'string-attribute' => 'abcdef',
    'int-attribute' => 1234,
    'bool-attribute' => true,
]);

// add tags to the current span
Appsignal::addTags([
    'string-tag' => 'some value',
    'integer-tag' => 1234,
    'bool-tag' => true,
]);

// report a handled exception
Appsignal::setError($exception);

// add metrics
Appsignal::setGauge('my_gauge', 12);
Appsignal::setGauge('my_gauge_with_attributes', 13, ['region' => 'eu']);

Appsignal::addDistributionValue('memory_usage', 50);
Appsignal::addDistributionValue('memory_usage', 70);

Appsignal::addDistributionValue('with_attributes', 10, ['region' => 'eu']);
Appsignal::addDistributionValue('with_attributes', 20, ['region' => 'eu']);
Appsignal::addDistributionValue('with_attributes', 30, ['region' => 'eu']);

Appsignal::incrementCounter('my_counter', 1);
Appsignal::incrementCounter('my_counter', 3, ['region' => 'eu']);

Development

Installation

This package uses Composer as the dependency manager. Once you have Composer installed, install all dependencies:

composer install

If you'd rather not install PHP and Composer locally, you can run Composer commands in a Docker container using the scripts/call_composer command:

scripts/call_composer any_composer_command_or_script

Testing

Run the following command in the root of this repository to run all PHPUnit tests:

composer test

# or with Docker
scripts/test

or run a single test file:

composer test tests/Path/To/YourTest.php

# or with Docker
scripts/test tests/Path/To/YourTest.php

or a single test case:

composer test --filter testMethodName

# or with Docker
scripts/test --filter testMethodName

This package supports PHP versions >= 8.4. If you want to run tests against a specific version of PHP, pass PHP_VERSION environment variable to the scripts/test command:

PHP_VERSION=8.5 scripts/test

Linting

You can run PHPStan anaylzer:

composer lint

# or with Docker
scripts/call_composer lint

or run PHP Coding Standards Fixer:

composer cs                    # check
composer cs:fix                # fix

# or with Docker
scripts/call_composer cs       # check
scripts/call_composer cs:fix   # fix

Contributing

Thinking of contributing to this repo? Awesome! 🚀

Please follow our Contributing guide in our documentation and follow our Code of Conduct.

Also, we would be very happy to send you Stroopwafels. Have look at everyone we have sent a package to so far on our Stroopwafels page.

Support

Contact us and speak directly with the engineers working on AppSignal. They will help you get set up, tweak your code and make sure you get the most out of using AppSignal.