README

This project aims to deliver an extendable tool to analyze a project's source code for various metrics. Whether you have a code coverage report, baselines for static analyzers, or file system metrics, Panaly can aggregate them based on your custom configuration and provide comprehensive reporting.

The plugin system ensures customization at every step, from configuration to metric collection, storage, and reporting. Future updates will enable active event listening, allowing plugins to further customize the analysis process.

Features

Extensible plugin system
Customizable metric collection
Comprehensive reporting

Setup

⚠️ Work in Progress Project

Install the package using Composer:

composer require --dev panaly/panaly

Create a panaly.dist.yaml file and configure it based on the plugins you need. Without any plugins, no actions will be performed. Refer to the example configuration in this repository for guidance.

Usage

By default, the CLI command searches for a panaly.dist.yaml configuration file. You can specify a different configuration file using the -c option:

vendor/bin/panaly -c my-own-config.yaml

Curated List of Plugins

Metric Plugins

Storage Plugins

JSON Timeline Storage

Reporting Plugins

Other Plugins

CODEOWNERS Paths

Example Configuration

panaly.dist.yaml

# panaly.dist.yaml
plugins: # Registered plugins that deliver single metrics that could be utilized for metric groups
  Namespace/Of/The/Project/FilesystemPlugin: ~ # registers a "filesystem_directory_count" and a "filesystem_file_count" metric
  Namespace/Of/Another/Project/PHPStanBaselinePlugin: ~ # registers a simple "phpstan_baseline_total_count" metric
  I/Have/A/Storage/Engine/LocalJsonStoragePlugin: ~ # registers a "local_json" storage and also a "metric_history_timeframe" metric that shows from / to string of all-time metric reading
  My/Own/Plugin/HtmlReportPlugin: ~ # registers the "my_own_html_reporting" reporting that takes the result collection of the metrics and does something with it

groups:
  group1:
      title: "My Metrics"
      metrics:
          metric_history_timeframe:
              title: "Metrics in Storage (Timeframe)"
              storage: local_json
  group2:
      title: "Filesystem Metrics"
      metrics:
          filesystem_directory_count: ~
          filesystem_file_count:
              title: "Total project files"
              paths:
                  - src
                  - tests
          i_am_a_custom_identifier:
              metric: filesystem_file_count # This overwrites the key and is the metric to be utilized
              title: "Just test files"
              paths:
                  - src
                  - tests
  group3:
      title: "Static Analysis Metrics"
      metrics:
          phpstan_baseline_total_count:
              title: "PHPStan Debts"
              baseline: .baselines/phpstan-baseline.neon

storage:
  local_json:
      path: var/metric_storage

reporting:
  my_own_html_reporting: ~

Plugins

Panaly relies on a wide plugin system and does not provide metric collection, storage, or reporting features by itself. Each plugin can specialize in a single task or deliver a full feature set from metric collection to storage handling and report generation.

Plugins are essential for configuring a Panaly run. Each plugin has a base class that defines how it interacts with Panaly and the features it provides. A plugin must implement the Panaly\Plugin\Plugin interface, which defines an initialize method.

The plugin will receive the full application configuration, the specific configuration associated with it, and the runtime configuration where metrics, storage, and reports can be added. It also has access to the event dispatcher to register listeners/subscribers for customizations.

A plugin example:

<?php

declare(strict_types=1);

namespace MyNamespace;

use Panaly\Configuration\ConfigurationFile;
use Panaly\Configuration\RuntimeConfiguration;
use Panaly\Plugin\Plugin;

final class BaselinePlugin implements Plugin
{
    public function initialize(
        ConfigurationFile $configurationFile,
        RuntimeConfiguration $runtimeConfiguration,
        array $options,
    ): void {
        $runtimeConfiguration->addMetric(new MyMetric());
        $runtimeConfiguration->addReporting(new MyReport());
        $runtimeConfiguration->addStorage(new MyStorage());
    }
}

Events

The event system is a work in progress. Future updates will allow plugins to register event listeners, enabling them to hook into events beyond delivering metrics, reporting, or storage.

Thanks and License

Inspired by PHPMetrics - Thanks for your tool!

GitHub @dzunke · Twitter @DZunke

dzunke / panaly

Maintainers

Details