README

Welcome to the Paddock! Paddock is a lightweight monitoring & configuration-check framework for your web servers, driven by simple YAML files.

Like a racing team in its paddock, it inspects your machines between two laps: it collects values from your systems, checks them against rules, and can even fix them when something goes wrong. Results are available as console reports, JSON, or NRPE responses for Nagios-like monitoring.

This package is the Core Bundle: the engine that powers all Paddock extensions (System, MySql, MongoDb, Backups, Nrpe, Sentry, Seo, ...).

Concepts

Concept	Role
Collector	Collects raw data from a system (PHP config, shell, SQL variables, ...)
Rule	A constraint verified against a collected value, with a severity level
Track	A named collection of rules, configured via YAML, may have children tracks
Championship	The whole set of tracks executed during a run
Fixer	An optional action that repairs a value when a rule fails

Requirements

PHP 8.1+
Symfony 5.4, 6.4, 7.4 or 8.x

Version	PHP	Symfony	Status
5.x	^8.1	5.4 → 8.x	Active
4.x	^7.4	4.4 → 7.x	Maintenance

Installation

composer require badpixxel/paddock-core

To load configurations from a remote SFTP server, also install:

composer require league/flysystem-sftp-v3

Quick Start

Create a paddock.yml file at the root of your project:

tracks:

    my-first-track:
        collector:      "system-php-constant"
        description:    "Check PHP Configuration"
        rules:
            # Verify PHP Version
            PHP_VERSION:        { rule: version, gt: { error: "8.1.0" } }
            # Verify a PHP Constant Value
            PHP_INT_SIZE:       { rule: value, eq: 8 }

Then run it:

php bin/paddock paddock:run

Each rule entry maps a data key (provided by the track collector) to a rule code and its options. Options may define per-severity thresholds:

rules:
    my-value:       { rule: value, gte: { warning: 10, error: 5 } }

Tracks may import other files and compose children tracks:

imports:
    - 'tracks/php.yml'
    - 'tracks/mysql.yml'

tracks:
    all-checks:
        collector:      "none"
        description:    "Master Track"
        children:
            - php-checks
            - mysql-checks

Available Rules

Code	Verification
`value`	Generic value checks (eq, ne, gt, gte, lt, lte, same, empty, ...)
`version`	Semantic version comparisons
`equal`	Value equality (loose)
`same`	Value identity (strict)
`greater`	Greater than
`greaterOrEqual`	Greater than or equal
`lower`	Lower than
`lowerOrEqual`	Lower than or equal
`empty`	Value is empty
`not-empty`	Value is not empty
`scalar`	Value is a scalar

Run php bin/paddock paddock:rules for the complete list, including rules registered by installed extensions.

Console Commands

Command	Description
`paddock:run`	Run one or all defined tracks
`paddock:tracks`	List available tracks
`paddock:rules`	List available rules / constraints
`paddock:collectors`	List available collectors
`paddock:fixers`	List available data fixers
`paddock:export`	Export tracks configuration

Useful paddock:run options:

# Run a single track
php bin/paddock paddock:run my-first-track

# Run rules in parallel (auto = one process per CPU)
php bin/paddock paddock:run -p 4

# Execute fixers when rules fail (add --fix-risky for risky fixers)
php bin/paddock paddock:run --fix

# Select output format (i.e: NRPE for Nagios)
php bin/paddock paddock:run -f nrpe

Remote Configurations

The PADDOCK_CONFIG environment variable defines where the main configuration is loaded from:

# Local file (default: paddock.yml in project dir)
PADDOCK_CONFIG="paddock.yml"

# Remote file via SFTP (requires league/flysystem-sftp-v3)
PADDOCK_CONFIG="sftp://user:password@my-server.com:22/configs/paddock.yml"

YAML imports may also target http(s):// urls, so a central server can distribute shared tracks to a whole fleet.

Extending Paddock

Paddock discovers collectors, rules, tracks & fixers via Symfony services:

services:
    App\Paddock\MyCollector:
        tags:    [ 'paddock.collector' ]

    App\Paddock\MyFixer:
        tags:    [ 'paddock.fixer' ]

Custom tracks are registered by listening to Paddock events (see src/Events & src/EventSubscriber for examples), or simply defined in YAML as shown above.

Development & Tests

All checks run identically in CI and locally: the GitLab pipeline executes the exact same commands as the docker containers (one per Symfony version, 5.4 → 8.x):

# Start all containers & run everything (composer, quality, tests)
make verify

# Run PhpUnit tests in all containers
make test

# Quality suites (GrumPHP: lint, code style, PhpStan)
php vendor/bin/grumphp run --testsuite=travis
php vendor/bin/grumphp run --testsuite=csfixer
php vendor/bin/grumphp run --testsuite=phpstan

# PhpUnit testsuites: core (unit), integration, operational
vendor/bin/phpunit --testsuite=core
vendor/bin/phpunit --testsuite=integration
vendor/bin/phpunit --testsuite=operational

License

Paddock is released under the MIT License.

badpixxel / paddock-core

Maintainers

Package info

Statistics

Security