pecs

KO | EN

gitlite — search

#typescript #ai-agents #deepseek-harness #dsh-plugin #open-source #ai #cli #dsh #claude-code #codex #developer-tools #react

★ 32 Open GitHub ↗

PECS simplifies logging in PHP with the power of Elastic Common Schema.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# PECS
PHP ECS (Elastic Common Schema)

[![Latest Version on Packagist](https://img.shields.io/packagist/v/hamidrezaniazi/pecs.svg?style=flat-square)](https://packagist.org/packages/hamidrezaniazi/pecs)
[![License](https://poser.pugx.org/hamidrezaniazi/pecs/license)](https://packagist.org/packages/hamidrezaniazi/pecs)
[![Total Downloads](https://img.shields.io/packagist/dt/hamidrezaniazi/pecs.svg?style=flat-square)](https://packagist.org/packages/hamidrezaniazi/pecs)

PECS is a PHP package that facilitates the usage of [ECS (Elastic Common Schema)](https://www.elastic.co/guide/en/ecs/current/ecs-reference.html) within PHP applications. ECS is a specification that helps structure and standardize log events.

PECS offers a practical approach for integrating ECS into PHP applications. By utilizing type-hinted classes, you can enhance your data layers with ECS fields. PECS simplifies the transformation of these data layers into the standard ECS schema.

1. [Installation](#installation)
1. [Integrations](#integrations)
   1. [Monolog](#monolog)
   1. [Symfony](#symfony)
   1. [Laravel](#laravel)
1. [Usage](#usage)
   1. [Helpers](#helpers)
   1. [Multiple Fields](#multiple-fields)
   1. [Custom Fields](#custom-fields)
      1. [Wrapper](#wrapper)
      1. [Empty Values](#empty-values)
   1. [Custom Formatter](#custom-formatter)
   1. [Collection](#collection)
1. [Testing](#testing)
1. [Security](#security)
1. [License](#license)
1. [Changelog](#changelog)
1. [Contributing](#contributing)

## Installation

You can install the package via composer:

```bash
composer require hamidrezaniazi/pecs
```

## Integrations

### Monolog
PECS can be used with the popular PHP logging library, [Monolog](https://github.com/Seldaek/monolog) to apply the formatter to handlers.

```php
use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Hamidrezaniazi\Pecs\Monolog\EcsFormatter;
use Hamidrezaniazi\Pecs\Fields\Event;

$log = new Logger('logger name');
$handler = new StreamHandler('ecs.logs');

$log->pushHandler($handler->setFormatter(new EcsFormatter()));

$log->info('message', [
    new Event(action: 'test event'),
]);
```
The `EcsFormatter` ensures that the default records generated by Monolog are correctly mapped to the corresponding ECS fields. Additionally, it takes care of rendering the remaining fields in the context array to align with the ECS schema. Here is the output of the above example:

```php
[
    '@timestamp' => '2023-05-27T00:13:16Z',
    'message' => 'message',
    'log' => [
        'level' => 'INFO',
        'logger' => 'logger name',
    ],
    'event' => [
        'action' => 'test event',
    ],
]
```

### Symfony
In Symfony applications, you can apply the `EcsFormatter` to a logging channel. First, you need to define it as a service in `config/services.yaml`:

```yaml
services:
    ecs:
        class: Hamidrezaniazi\Pecs\Monolog\EcsFormatter
```

Then define a custom channel in `config/packages/monolog.yaml`:

```yaml
monolog:
    channels:
        - ecs
    handlers:
        ecs:
            formatter: ecs
            type: stream
            path: '%kernel.logs_dir%/ecs.log'
            channels: [ "ecs" ]
```

Now, you can use the `ecs` channel in your Symfony application by autowring the logger channel:

```php
public function __construct(LoggerInterface $ecsLogger)
{
    $ecsLogger->info('sample message', [
        new Event(kind: EventKind::METRIC),
    ]);
}
```

> See [Symfony's documentation](https://symfony.com/doc/current/logging/channels_handlers.html#how-to-autowire-logger-channels) for more information.

### Laravel

In Laravel applications, you can apply the `EcsFormatter` to a logging driver. First, you need to create a class that implements the `__invoke` method like bellow:

```php
use Illuminate\Log\Logger;
use Monolog\Handler\FormattableHandlerInterface;
use Hamidrezaniazi\Pecs\Monolog\EcsFormatter;

class LaravelEcsFormatter
{
    public function __invoke(Logger $logger): void
    {
        foreach ($logger->getHandlers() as $handler) {
            /** @var FormattableHandlerInterface $handler */
            $handler->setFormatter(app(EcsFormatter::class));
        }
    }
}
```

Then to apply this formatter to the logging driver, you need to add the `tap` key to the desired logging configuration in `config/logging.php`:

```php
'ecs' => [
    'driver' => 'single',
    'tap' => [LaravelEcsFormatter::class],
    'path' => storage_path('logs/ecs.log'),
    'level' => 'debug',
],
```

> See [Laravel's documentation](https://laravel.com/docs/master/logging#customizing-monolog-for-channels) for more information about this method.

Now, you can use the `ecs` driver in your Laravel application's logging configuration to apply the ECS formatter to the logs.

```php
Log::channel('ecs')->info('sample message', [
    new Event(kind: EventKind::METRIC),
]);
```

Since Laravel utilizes Monolog as its underlying logging system, the same behavior is applicable here regarding the automatic configuration of the `@timestamp`, `message`, `level`, and `logger` fields.

## Usage
> It's important to note that empty values such as `null`, `[]`, etc., in the data layers are eliminated automatically. You don't need to handle them explicitly as strings like `N/A`. However, these values `0`, `0.0`, `'0'`, `'0.0'`, `false`, `'false'` are whitelisted and will appear in the logs.

### Helpers
The syntax can get a little bit verbose when you want to log with several fields. To make it more concise, you can implement helper classes:

```php
use Hamidrezaniazi\Pecs\Fields\Error;
use Hamidrezaniazi\Pecs\Fields\Log;

class ThrowableHelper
{
    public static function from(Throwable $throwable): array
    {
        return [
            new Error(
                code: $throwable->getCode(),
                message: $throwable->getMessage(),
                stackTrace: $throwable->getTraceAsString(),
                type: get_class($throwable),
            ),
            new Log(
                originFileLine: $throwable->getLine(),
                originFileName: $throwable->getFile(),
            )
        ];
    }
}
```

Then the usage would be shortened to:

```php
try {
    // ...
} catch (Throwable $throwable) {
    Log::error('helpers example', ThrowableHelper::from($throwable));
}
```

### Multiple Fields

It is completely possible to have multiple fields of the same type. In case of a conflict, the most recent properties will take priority.

```php
use Hamidrezaniazi\Pecs\EcsFieldsCollection;
use Hamidrezaniazi\Pecs\Fields\Base;
use Hamidrezaniazi\Pecs\Properties\ValueList;

(new EcsFieldsCollection([
    new Base(message: 'Hello World'),
    new Base(message: 'test', tags: (new ValueList())->push('staging')),
]))->render()->toArray();
```

```php
[
    'message' => 'test',
    'tags' => [
        'staging',
    ],
]
```

You can find the available classes for defining ECS fields in the [this](https://github.com/hamidrezaniazi/pecs/tree/master/src/Fields) directory.

### Custom Fields

You can also create your own custom fields by extending the `AbstractEcsField` class.

```php
use Hamidrezaniazi\Pecs\Fields\AbstractEcsField;

class FooField extends AbstractEcsField
{
    public function __construct(
        private string $input
    ) {
        parent::__construct();
    }

protected function key(): ?string
    {
        return 'Foo';
    }

protected function custom(): Collection
    {
        return collect([
            'Input' => $this->input
        ]);
    }
}
```

> Check the [ECS custom fields documentation](https://www.elastic.co/guide/en/ecs/master/ecs-custom-fields-in-ecs.html) for naming conventions and use cases. It is important to note that custom field key and property names must be in PascalCase not to conflict with the ECS fields.

#### Wrapper

You may need to combine your custom fields with the existed ECS field classes. It's feasible by overwriting the `wrapper` in your class:

```php
use Hamidrezaniazi\Pecs\Fields\AbstractEcsField;
use Hamidrezaniazi\Pecs\Fields\Event;
use Hamidrezaniazi\Pecs\Properties\EventKind;

class BarField extends AbstractEcsField
{
    protected function key(): ?string
    {
        return 'Bar';
    }

protected function custom(): Collection
    {
        return collect([
            'Bleep' => 'bloop'
        ]);
    }
    
    public function wrapper(): EcsFieldsCollection
    {
        return parent::wrapper()->push(new Event(kind: EventKind::METRIC));
    }
```

All the fields in the wrapper will be rendered at the same level as the custom field. In the given example, the rendered array will be:

```php
[
    'Bar' => [
        'Bleep' => 'bloop',
    ],
    'event' => [
        'kind' => 'metric',
    ],
]
```

#### Empty Values

It's also possible to customize the empty value behavior by overriding the whitelisted array:

```php
class FooFields extends AbstractEcsField
{
    protected array $validEmpty = [0, 0.0];
````
Now only `0` and `0.0` are whitelisted and will appear in the logs. The rest of the empty values such as `null`, `[]`, `false`, `'0'`, etc., will be eliminated.

### Custom Formatter
The default formatter is the `EcsFormatter` class as mentioned in the [integration](#integration) section. However, you can load more default fields by overriding the `prepare` method:

```php
<?php

use Hamidrezaniazi\Pecs\Fields\Ecs;
use Hamidrezaniazi\Pecs\Monolog\EcsFormatter;

class CustomEcsFormatter extends EcsFormatter
{
    protected function prepare(array $record): EcsFieldsCollection
    {
        return parent::prepare($record)->push(new Ecs(version: '1.0.0'));
    }
}
```

By registering the above formatter, the rendered array will contain the `ecs.version` in addition to the default fields.

### Collection
Here's the usage example of the `EcsFieldsCollection` to render an array of ECS fields:

```php
use Hamidrezaniazi\Pecs\EcsFieldsCollection;
use Hamidrezaniazi\Pecs\Fields\Base;
use Hamidrezaniazi\Pecs\Fields\Log;

(new EcsFieldsCollection([
    new Base(message: 'Hello World'),
    new Log(level: 'info'),
]))->render()->toArray();
```

The above code will output:

```php
[
    'message' => 'Hello World',
    'log' => [
        'level' => 'info',
    ],
]
```

> The `EcsFieldsCollection` is adaptable and can be used with various logging drivers, not just limited to Monolog. Practical use cases for Monolog are mentioned in the [integrations](#integrations) section.

### Testing

``` bash
composer test
```

### Changelog

Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.

## Contributing

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

## Credits

- [Hamidreza Niazi](https://github.com/hamidrezaniazi)
- [All Contributors](https://github.com/hamidrezaniazi/pecs/contributors)

## License

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

pecs

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README