idevlab/owlhooks

Gestionnaire modulaire et extensible des hooks Git pour projets PHP (Laravel, Symfony, etc.)

v0.1.0 2025-05-13 21:32 UTC

Requires

• php: ^8.2
• symfony/console: ^6.4 || ^7.0
• symfony/yaml: ^6.4 || ^7.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.30
• pestphp/pest: ^2.36
• phpstan/phpstan: ^1.11
• rector/rector: ^0.18
• squizlabs/php_codesniffer: ^3.7

MIT

• Florian SINAMA

README

🎯 OwlHooks est un gestionnaire de hooks Git modulaire, sécurisé, extensible et 100% configurable pour tous projets PHP (Laravel, Symfony, etc.)

✨ Objectifs

• ✅ Exécuter automatiquement vos outils de qualité, tests et sécurité à chaque commit/push
• ✅ Centraliser et versionner la configuration des hooks dans un seul fichier owlhooks.json
• ✅ Permettre un fonctionnement en solo ou en équipe, avec ou sans outils globaux
• ✅ Supporter l'exécution des hooks en local ou dans un conteneur Docker

🧩 Sommaire

• 🚀 Installation
• ⚙️ Configuration
• 🔧 Commandes disponibles
• 📦 Presets intégrés
• 🔒 Sécurité
• 🐳 Exécution dans Docker
• 🧪 Tests
• 📜 Changelog
• 📝 Licence

🚀 Installation

composer require idevlab/owlhooks --dev

Puis initialisez les hooks :

vendor/bin/owlhooks install --preset=all

⚙️ Configuration

Le fichier owlhooks.json est la seule source de vérité. Exemple :

{
  "meta": {
    "version": 1,
    "preset": "all"
  },
  "tools": {
    "fallback_to_global": true
  },
  "execution": {
    "mode": "local",
    "docker": {
      "container_name": "php-app"
    }
  },
  "hooks": {
    "pre-commit": {
      "enabled": true,
      "sequence": [
        { "tool": "phpcs", "options": { "standard": "PSR12" } },
        { "tool": "phpstan", "options": { "level": "max" } }
      ]
    }
  }
}

💡 Vous pouvez également lancer vendor/bin/owlhooks init pour générer un fichier interactif.

🔧 Commandes disponibles

vendor/bin/owlhooks help
vendor/bin/owlhooks install [--preset=all|light|auto] [--force] [--ignore-existing]
vendor/bin/owlhooks uninstall
vendor/bin/owlhooks run <hook> [options]
vendor/bin/owlhooks validate [--fix]
vendor/bin/owlhooks init
vendor/bin/owlhooks status
vendor/bin/owlhooks update
vendor/bin/owlhooks audit
vendor/bin/owlhooks preset:list

Options de la commande run :

• --only=tool : Exécute uniquement un outil spécifique (ex : phpstan)
• --dry-run : Simule l’exécution sans rien exécuter
• --no-fallback : Interdit les outils globaux
• --sandbox : Bloque tous les outils non whitelistés
• --json : Affiche la sortie au format JSON
• --verbose : Affiche des informations détaillées lors de l'exécution
• --mode=local|docker : Définit le mode d'exécution (local ou Docker)
• --container=name : Nom du conteneur Docker à utiliser (si mode Docker)

📦 Presets intégrés

Nom	Contenu par défaut
all	Tous les outils : linters, tests, sécurité, fixers, etc.
light	gitleaks, pest uniquement
custom	Configuration vide à personnaliser
auto	Basé sur les fichiers présents dans votre projet

🔒 Sécurité

• 🧼 Sanitation stricte des arguments
• 🔐 Mode --sandbox pour bloquer tout outil non whitelisté
• 🔏 Journal owlhooks.audit.log dans .git/hooks
• ✅ Désactivation automatique du sandbox si .env contient OWLHOOKS_TRUSTED=true

🐳 Exécution dans Docker

OwlHooks permet d'exécuter les hooks dans un conteneur Docker. Pour cela, configurez la section execution dans owlhooks.json :

"execution": {
  "mode": "docker",
  "docker": {
    "container_name": "php-app"
  }
}

Vous pouvez également spécifier le mode et le conteneur en ligne de commande :

vendor/bin/owlhooks run pre-commit --mode=docker --container=php-app

🧪 Tests

composer test
# ou
vendor/bin/pest

Pour générer un rapport de couverture de code :

vendor/bin/pest --coverage

Pour générer un badge de couverture de code, utilisez l'action GitHub suivante :

- name: Generate test coverage badge
  uses: timkrase/phpunit-coverage-badge@v1.2.0
  with:
    coverage_badge_path: 'badge-coverage.svg'
    push_badge: true
    repo_token: ${{ secrets.GITHUB_TOKEN }}

📜 Changelog

Voir CHANGELOG.md

📝 Licence

Code publié sous licence MIT.

Développé par Florian SINAMA – [e-mail]

🧠 Pour plus d'informations sur la configuration de la couverture de code avec Pest, consultez la documentation officielle : Pest - Test Coverage