Download the PHP package whitedigital-eu/audit-service without Composer

Audit Service

IMPORTANT: When migrating from 0.4 (or earlier) to 0.5, configuration and usage has changed slightly:

1. When used outside of this package, AuditService can now be accessed as WhiteDigital\Audit\Contracts\AuditServiceInterface instead of WhiteDigital\Audit\Service\AuditServiceLocator. AuditServiceLocator class has been removed.
2. Configuration has changed and now it is one level higher:
   Old version:

New version:

If used in php config, it is now AuditConfig instead of WhitedigitalConfig

As this bundle now comes enabled, enabled parameter has been removed

What is it?

Audit is service needed to audit (log) events into database. For now package only ships with doctrine implementation to save data, but you can easily extend functionality (see below) to use other means of storage.

System Requirements

PHP 8.1+
Symfony 6.3+

Project Requirements

2 separate Doctrine entity managers (if using provided AuditService)

Installation

The recommended way to install is via Composer:

Configuration

Configuration differs between default setup and overridden one. If you are interested in configuration for overriding part of package, scroll down to appropriate section.

audit_entity_manager is entity manager used for audit
default_entity_manager is entity manager you use for database operations

Logic is split between 2 managers because it is easier to audit database exception this way. If done with one entity manager, a lot extra steps need to be taken (opening closed entity manager, checking status of operations, etc.)

After this, you need to update your database schema to use Audit entity.
If using migrations:

If by schema update:

This is it, now you can use audit. It is configured and autowired as AuditServiceInterface.

Audit service comes with 2 event subscribers: one for exceptions and one for database events.

Exception subscriber:
By default exception subscriber audits all exceptions, except 404 response code. you can override this logic by:

By default exception subscriber audits all exceptions on all routes and paths. you can override this logic by: Path:

Route:

Allowed Audit types

To not to create chaos within audit records, it is only allowed to use specified audit types.
Default values are: AUTHENTICATION, DATABASE, ETL_PIPELINE, EXCEPTION and EXTERNAL_CALL.

If you don't have any custom types, you can use WhiteDigital\Audit\Contracts\AuditType class for default constants.

If you wish to add more types, configure new types as so:

It is possible to run symfony command that generates interface based on default and added types for easier code complete:

This command will generate new file based on package configuration. By default, this command will make App\Audit\AuditType class. You can override this name in configuration:

If you have this defined interface and want to add more allowed types, you can just add new types to it without adding types to package configuration. Allowed types will be merged from configuration and interface.

Api Resource

This package comes with AuditResource for api-platform, it's iri is /api/audits.

Overriding parts of bundle

Overriding audit service
If you wish not to use audit service this package comes with, you can override it with your own.
To do so, implement AuditServiceInterface into your service:

AuditService in this package comes with priority of 1. To override it, make sure to add priority higher than that.

If your custom AuditService does not use database as an audit storage, you need to disable part of this package that requires 2 entity managers. You can do it like this:

Overriding default api resource (and therefore api endpoints)

By default, Audit resource is based on AuditResource
If you wish not to use this resource and not expose the api endpoints it provides, just set a custom api resource path with a configuration value. If you set it as null, api platform will not register api resource located within this package.

After overriding default api resource, do not forget to update ClassMapperConfigurator configuration that is used for resource <-> entity mapping in whitedigital-eu/entity-resource-mapper-bundle

Overriding default entity
By default, Audit entity is based on BaseEntity that comes from whitedigital-eu/entity-resource-mapper-bundle.
If you wish not to use this base at all, you need to create new Entity and implement AuditEntityInterface into it:

or you can use Model from package:

If you wish to add new properties or, maybe, use different name for Audit entity that comes from package:

Now when you use audit() or auditException() functions in your project, you need to tell service to use your entity:

This bundle automatically adds WhiteDigital\Audit\Entity namespace to both given entity managers. If you wish to not it to do it, for example, if you don't use default entity or maybe don't store audits in database at all, you need to configure this to disable it:

Overriding auditing of entity events
You can disable entity event auditing in runtime by calling setIsEnabled setter for entity event subscriber

PHP CS Fixer

IMPORTANT: When running php-cs-fixer, make sure not to format files in skeleton folder. Otherwise maker command will stop working.