{"id":31806787,"url":"https://github.com/hamidrezaniazi/pecs","last_synced_at":"2025-10-11T03:50:17.579Z","repository":{"id":169907044,"uuid":"504318659","full_name":"hamidrezaniazi/pecs","owner":"hamidrezaniazi","description":"PECS simplifies logging in PHP with the power of Elastic Common Schema.","archived":false,"fork":false,"pushed_at":"2025-02-12T12:12:23.000Z","size":257,"stargazers_count":33,"open_issues_count":0,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-08-23T12:39:05.996Z","etag":null,"topics":["ecs","elastic-common-schema","filebeat","laravel","logging","monolog","monolog-formatter","php","php-ecs","phpecs","symfony"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hamidrezaniazi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-16T22:04:24.000Z","updated_at":"2025-08-12T11:49:34.000Z","dependencies_parsed_at":"2023-07-07T14:46:46.320Z","dependency_job_id":"6501a879-213f-4747-9f24-0004a34adcff","html_url":"https://github.com/hamidrezaniazi/pecs","commit_stats":null,"previous_names":["hamidrezaniazi/pecs"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/hamidrezaniazi/pecs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamidrezaniazi%2Fpecs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamidrezaniazi%2Fpecs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamidrezaniazi%2Fpecs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamidrezaniazi%2Fpecs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hamidrezaniazi","download_url":"https://codeload.github.com/hamidrezaniazi/pecs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamidrezaniazi%2Fpecs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279002602,"owners_count":26083426,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ecs","elastic-common-schema","filebeat","laravel","logging","monolog","monolog-formatter","php","php-ecs","phpecs","symfony"],"created_at":"2025-10-11T03:50:16.702Z","updated_at":"2025-10-11T03:50:17.573Z","avatar_url":"https://github.com/hamidrezaniazi.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PECS\nPHP ECS (Elastic Common Schema)\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/hamidrezaniazi/pecs.svg?style=flat-square)](https://packagist.org/packages/hamidrezaniazi/pecs)\n[![License](https://poser.pugx.org/hamidrezaniazi/pecs/license)](https://packagist.org/packages/hamidrezaniazi/pecs)\n[![Total Downloads](https://img.shields.io/packagist/dt/hamidrezaniazi/pecs.svg?style=flat-square)](https://packagist.org/packages/hamidrezaniazi/pecs)\n\nPECS 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.\n\nPECS 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.\n\n1. [Installation](#installation)\n1. [Integrations](#integrations)\n   1. [Monolog](#monolog)\n   1. [Symfony](#symfony)\n   1. [Laravel](#laravel)\n1. [Usage](#usage)\n   1. [Helpers](#helpers)\n   1. [Multiple Fields](#multiple-fields)\n   1. [Custom Fields](#custom-fields)\n      1. [Wrapper](#wrapper)\n      1. [Empty Values](#empty-values)\n   1. [Custom Formatter](#custom-formatter)\n   1. [Collection](#collection)\n1. [Testing](#testing)\n1. [Security](#security)\n1. [License](#license)\n1. [Changelog](#changelog)\n1. [Contributing](#contributing)\n\n## Installation\n\nYou can install the package via composer:\n\n```bash\ncomposer require hamidrezaniazi/pecs\n```\n\n## Integrations\n\n### Monolog\nPECS can be used with the popular PHP logging library, [Monolog](https://github.com/Seldaek/monolog) to apply the formatter to handlers.\n\n```php\nuse Monolog\\Logger;\nuse Monolog\\Handler\\StreamHandler;\nuse Hamidrezaniazi\\Pecs\\Monolog\\EcsFormatter;\nuse Hamidrezaniazi\\Pecs\\Fields\\Event;\n\n$log = new Logger('logger name');\n$handler = new StreamHandler('ecs.logs');\n\n$log-\u003epushHandler($handler-\u003esetFormatter(new EcsFormatter()));\n\n$log-\u003einfo('message', [\n    new Event(action: 'test event'),\n]);\n```\nThe `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:\n\n```php\n[\n    '@timestamp' =\u003e '2023-05-27T00:13:16Z',\n    'message' =\u003e 'message',\n    'log' =\u003e [\n        'level' =\u003e 'INFO',\n        'logger' =\u003e 'logger name',\n    ],\n    'event' =\u003e [\n        'action' =\u003e 'test event',\n    ],\n]\n```\n\n### Symfony\nIn Symfony applications, you can apply the `EcsFormatter` to a logging channel. First, you need to define it as a service in `config/services.yaml`:\n\n```yaml\nservices:\n    ecs:\n        class: Hamidrezaniazi\\Pecs\\Monolog\\EcsFormatter\n```\n\nThen define a custom channel in `config/packages/monolog.yaml`:\n\n```yaml\nmonolog:\n    channels:\n        - ecs\n    handlers:\n        ecs:\n            formatter: ecs\n            type: stream\n            path: '%kernel.logs_dir%/ecs.log'\n            channels: [ \"ecs\" ]\n```\n\nNow, you can use the `ecs` channel in your Symfony application by autowring the logger channel:\n\n```php\npublic function __construct(LoggerInterface $ecsLogger)\n{\n    $ecsLogger-\u003einfo('sample message', [\n        new Event(kind: EventKind::METRIC),\n    ]);\n}\n```\n\n\u003e See [Symfony's documentation](https://symfony.com/doc/current/logging/channels_handlers.html#how-to-autowire-logger-channels) for more information.\n\n### Laravel\n\nIn 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:\n\n```php\nuse Illuminate\\Log\\Logger;\nuse Monolog\\Handler\\FormattableHandlerInterface;\nuse Hamidrezaniazi\\Pecs\\Monolog\\EcsFormatter;\n\nclass LaravelEcsFormatter\n{\n    public function __invoke(Logger $logger): void\n    {\n        foreach ($logger-\u003egetHandlers() as $handler) {\n            /** @var FormattableHandlerInterface $handler */\n            $handler-\u003esetFormatter(app(EcsFormatter::class));\n        }\n    }\n}\n```\n\nThen to apply this formatter to the logging driver, you need to add the `tap` key to the desired logging configuration in `config/logging.php`:\n\n```php\n'ecs' =\u003e [\n    'driver' =\u003e 'single',\n    'tap' =\u003e [LaravelEcsFormatter::class],\n    'path' =\u003e storage_path('logs/ecs.log'),\n    'level' =\u003e 'debug',\n],\n```\n\n\u003e See [Laravel's documentation](https://laravel.com/docs/master/logging#customizing-monolog-for-channels) for more information about this method.\n\nNow, you can use the `ecs` driver in your Laravel application's logging configuration to apply the ECS formatter to the logs.\n\n```php\nLog::channel('ecs')-\u003einfo('sample message', [\n    new Event(kind: EventKind::METRIC),\n]);\n```\n\nSince 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.\n\n## Usage\n\u003e 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.\n\n### Helpers\nThe 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:\n\n```php\nuse Hamidrezaniazi\\Pecs\\Fields\\Error;\nuse Hamidrezaniazi\\Pecs\\Fields\\Log;\n\nclass ThrowableHelper\n{\n    public static function from(Throwable $throwable): array\n    {\n        return [\n            new Error(\n                code: $throwable-\u003egetCode(),\n                message: $throwable-\u003egetMessage(),\n                stackTrace: $throwable-\u003egetTraceAsString(),\n                type: get_class($throwable),\n            ),\n            new Log(\n                originFileLine: $throwable-\u003egetLine(),\n                originFileName: $throwable-\u003egetFile(),\n            )\n        ];\n    }\n}\n```\n\nThen the usage would be shortened to:\n\n```php\ntry {\n    // ...\n} catch (Throwable $throwable) {\n    Log::error('helpers example', ThrowableHelper::from($throwable));\n}\n```\n\n### Multiple Fields\n\nIt is completely possible to have multiple fields of the same type. In case of a conflict, the most recent properties will take priority.\n\n```php\nuse Hamidrezaniazi\\Pecs\\EcsFieldsCollection;\nuse Hamidrezaniazi\\Pecs\\Fields\\Base;\nuse Hamidrezaniazi\\Pecs\\Properties\\ValueList;\n\n(new EcsFieldsCollection([\n    new Base(message: 'Hello World'),\n    new Base(message: 'test', tags: (new ValueList())-\u003epush('staging')),\n]))-\u003erender()-\u003etoArray();\n```\n\n```php\n[\n    'message' =\u003e 'test',\n    'tags' =\u003e [\n        'staging',\n    ],\n]\n```\n\nYou can find the available classes for defining ECS fields in the [this](https://github.com/hamidrezaniazi/pecs/tree/master/src/Fields) directory.\n\n### Custom Fields\n\nYou can also create your own custom fields by extending the `AbstractEcsField` class.\n\n```php\nuse Hamidrezaniazi\\Pecs\\Fields\\AbstractEcsField;\n\nclass FooField extends AbstractEcsField\n{\n    public function __construct(\n        private string $input\n    ) {\n        parent::__construct();\n    }\n\n    protected function key(): ?string\n    {\n        return 'Foo';\n    }\n\n    protected function custom(): Collection\n    {\n        return collect([\n            'Input' =\u003e $this-\u003einput\n        ]);\n    }\n}\n```\n\n\u003e 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.\n\n#### Wrapper\n\nYou may need to combine your custom fields with the existed ECS field classes. It's feasible by overwriting the `wrapper` in your class:\n\n```php\nuse Hamidrezaniazi\\Pecs\\Fields\\AbstractEcsField;\nuse Hamidrezaniazi\\Pecs\\Fields\\Event;\nuse Hamidrezaniazi\\Pecs\\Properties\\EventKind;\n\nclass BarField extends AbstractEcsField\n{\n    protected function key(): ?string\n    {\n        return 'Bar';\n    }\n\n    protected function custom(): Collection\n    {\n        return collect([\n            'Bleep' =\u003e 'bloop'\n        ]);\n    }\n    \n    public function wrapper(): EcsFieldsCollection\n    {\n        return parent::wrapper()-\u003epush(new Event(kind: EventKind::METRIC));\n    }\n```\n\nAll 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:\n\n```php\n[\n    'Bar' =\u003e [\n        'Bleep' =\u003e 'bloop',\n    ],\n    'event' =\u003e [\n        'kind' =\u003e 'metric',\n    ],\n]\n```\n\n#### Empty Values\n\nIt's also possible to customize the empty value behavior by overriding the whitelisted array:\n\n```php\nclass FooFields extends AbstractEcsField\n{\n    protected array $validEmpty = [0, 0.0];\n````\nNow 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.\n\n### Custom Formatter\nThe 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:\n\n```php\n\u003c?php\n\nuse Hamidrezaniazi\\Pecs\\Fields\\Ecs;\nuse Hamidrezaniazi\\Pecs\\Monolog\\EcsFormatter;\n\nclass CustomEcsFormatter extends EcsFormatter\n{\n    protected function prepare(array $record): EcsFieldsCollection\n    {\n        return parent::prepare($record)-\u003epush(new Ecs(version: '1.0.0'));\n    }\n}\n```\n\nBy registering the above formatter, the rendered array will contain the `ecs.version` in addition to the default fields.\n\n### Collection\nHere's the usage example of the `EcsFieldsCollection` to render an array of ECS fields:\n\n```php\nuse Hamidrezaniazi\\Pecs\\EcsFieldsCollection;\nuse Hamidrezaniazi\\Pecs\\Fields\\Base;\nuse Hamidrezaniazi\\Pecs\\Fields\\Log;\n\n(new EcsFieldsCollection([\n    new Base(message: 'Hello World'),\n    new Log(level: 'info'),\n]))-\u003erender()-\u003etoArray();\n```\n\nThe above code will output:\n\n```php\n[\n    'message' =\u003e 'Hello World',\n    'log' =\u003e [\n        'level' =\u003e 'info',\n    ],\n]\n```\n\n\u003e 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.\n\n### Testing\n\n``` bash\ncomposer test\n```\n\n### Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.\n\n## Contributing\n\nPlease see [CONTRIBUTING](CONTRIBUTING.md) for details.\n\n## Credits\n\n- [Hamidreza Niazi](https://github.com/hamidrezaniazi)\n- [All Contributors](https://github.com/hamidrezaniazi/pecs/contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhamidrezaniazi%2Fpecs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhamidrezaniazi%2Fpecs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhamidrezaniazi%2Fpecs/lists"}