Download the PHP package hamidrezaniazi/pecs without Composer

PECS

PHP ECS (Elastic Common Schema)

PECS is a PHP package that facilitates the usage of ECS (Elastic Common Schema) 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
2. Integrations
   1. Monolog
   2. Symfony
   3. Laravel
3. Usage
   1. Helpers
   2. Multiple Fields
   3. Custom Fields
      1. Wrapper
      2. Empty Values
   4. Custom Formatter
   5. Collection
4. Testing
5. Security
6. License
7. Changelog
8. Contributing

Installation

You can install the package via composer:

Integrations

Monolog

PECS can be used with the popular PHP logging library, Monolog to apply the formatter to handlers.

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:

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:

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

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

See Symfony's documentation 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:

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:

See Laravel's documentation 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.

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:

Then the usage would be shortened to:

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.

You can find the available classes for defining ECS fields in the this directory.

Custom Fields

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

Check the ECS custom fields documentation 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:

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:

Empty Values

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

Now only0and0.0are whitelisted and will appear in the logs. The rest of the empty values such asnull,[],false,'0'`, etc., will be eliminated.

Custom Formatter

The default formatter is the EcsFormatter class as mentioned in the integration section. However, you can load more default fields by overriding the prepare method:

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:

The above code will output:

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 section.

Testing

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Credits

• Hamidreza Niazi
• All Contributors

License

The MIT License (MIT). Please see License File for more information.