Merge pull request #277 from feature/config-shorthands

Add action and condition shorthands to simplify the configuration

Author: sebastianfeldmann

composer.json

@@ -3,7 +3,7 @@
   "type": "library",
   "description": "PHP git hook manager",
   "keywords": ["git", "hooks", "pre-commit", "pre-push", "commit-msg", "prepare-commit-msg", "post-merge"],
-  "homepage": "http://php.captainhook.info/",
+  "homepage": "https://php.captainhook.info/",
   "license": "MIT",
   "authors": [
     {

src/Hook/Branch/Action/BlockFixupAndSquashCommits.php

@@ -27,17 +27,17 @@
  * This action blocks pushes that contain fixup! or squash! commits.
  * Just as a security layer, so you are not pushing stuff you wanted to autosquash.
  *
- * Configure like this:
- *
+ * Example configuration:
+ * <code>
  * {
- *    "action": "\\CaptainHook\\App\\Hook\\Branch\\Action\\BlockFixupAndSquashCommits",
- *    "options": {
- *      "blockSquashCommits": true,
- *      "blockFixupCommits": true,
- *      "protectedBranches": ["main", "master", "integration"]
- *    },
- *    "conditions": []
- *  }
+ *   "action": "CaptainHook.Branch.PreventPushOfFixupAndSquashCommits",
+ *   "options": {
+ *     "blockSquashCommits": true,
+ *     "blockFixupCommits": true,
+ *     "protectedBranches": ["main", "master", "integration"]
+ *   }
+ * }
+ * </code>
  *
  * @package CaptainHook
  * @author  Sebastian Feldmann <[email protected]>

src/Hook/Branch/Action/EnsureNaming.php

@@ -22,6 +22,20 @@
 /**
  * Class EnsureNaming
  *
+ * This Action makes sure you are on a branch that follows your naming conventions.
+ *
+ * Example configuration:
+ * <code>
+ * {
+ *   "action": "CaptainHook.Branch.EnsureNaming",
+ *   "options": {
+ *     "regex": "#feature/issue[0-9]+-.*#i",
+ *     "error": "Arr matey! Ye be on the wrong branch!",
+ *     "success": "All clear, Captain! Full speed ahead!",
+ *   }
+ * }
+ * </code>
+ *
  * @package CaptainHook
  * @author  Felix Edelmann <[email protected]>
  * @link    https://github.com/captainhook-git/captainhook

src/Hook/Condition/Branch/NotOn.php

@@ -18,7 +18,20 @@
 use SebastianFeldmann\Git\Repository;
 
 /**
- * NotOn condition
+ * NotOn Branch condition
+ *
+ * Example configuration:
+ * <code>
+ * {
+ *   "action": "some-action",
+ *   "conditions": [
+ *     {
+ *       "exec": "CaptainHook.Status.NotOnBranch",
+ *       "args": ["not-on-this-branch"]
+ *     }
+ *   ]
+ * }
+ * </code>
  *
  * @package CaptainHook
  * @author  Sebastian Feldmann <[email protected]>

src/Hook/Condition/Branch/NotOnMatching.php

@@ -18,7 +18,20 @@
 use SebastianFeldmann\Git\Repository;
 
 /**
- * NotOnMatching condition
+ * NotOnMatching Branch condition
+ *
+ * Example configuration:
+ * <code>
+ * {
+ *   "action": "some-action",
+ *   "conditions": [
+ *     {
+ *       "exec": "CaptainHook.Status.NotOnMatchingBranch",
+ *       "args": ["#^branches-names/not-matching[0-9]+-this-regex$#i"]
+ *     }
+ *   ]
+ * }
+ * </code>
  *
  * @package CaptainHook
  * @author  Sebastian Feldmann <[email protected]>

src/Hook/Condition/Branch/On.php

@@ -18,7 +18,20 @@
 use SebastianFeldmann\Git\Repository;
 
 /**
- * On condition
+ * On Branch condition
+ *
+ * Example configuration:
+ * <code>
+ * {
+ *   "action": "some-action",
+ *   "conditions": [
+ *     {
+ *       "exec": "CaptainHook.Status.OnBranch",
+ *       "args": ["only-on-this-branch"]
+ *     }
+ *   ]
+ * }
+ * </code>
  *
  * @package CaptainHook
  * @author  Sebastian Feldmann <[email protected]>

src/Hook/Condition/Branch/OnMatching.php

@@ -18,7 +18,20 @@
 use SebastianFeldmann\Git\Repository;
 
 /**
- * OnMatching condition
+ * OnMatching Branch condition
+ *
+ * Example configuration:
+ * <code>
+ * {
+ *   "action": "some-action",
+ *   "conditions": [
+ *     {
+ *       "exec": "CaptainHook.Status.OnMatchingBranch",
+ *       "args": ["#^branches-names/matching[0-9]+-this-regex$#i"]
+ *     }
+ *   ]
+ * }
+ * </code>
  *
  * @package CaptainHook
  * @author  Sebastian Feldmann <[email protected]>

src/Hook/Condition/Config/CustomValueIsFalsy.php

@@ -17,22 +17,31 @@
 use SebastianFeldmann\Git\Repository;
 
 /**
- * Class CustomValueIsFalsy
+ * Condition CustomValueIsFalsy
+ *
+ * With this condition, you can check if a given custom value is falsy.
+ * The Action only is executed if the custom value is falsy.
+ * Values considered falsy are, 0, null, empty string, empty array and false.
  *
  * Example configuration:
  *
- * "action": "some-action"
- * "conditions": [
- *   {"exec": "\\CaptainHook\\App\\Hook\\Condition\\Config\\CustomValueIsFalsy",
- *    "args": [
- *      "NAME_OF_CUSTOM_VALUE"
- *    ]}
- * ]
+ * <code>
+ * {
+ *   "action": "some-action"
+ *   "conditions": [
+ *     {
+ *       "exec": "CaptainHook.Config.CustomValueIsFalsy",
+ *       "args": ["NAME_OF_CUSTOM_VALUE"]
+ *     }
+ *   ]
+ * }
+ * </code>
  *
  * @package CaptainHook
  * @author  Sebastian Feldmann <[email protected]>
  * @link    https://github.com/captainhook-git/captainhook
  * @since   Class available since Release 5.17.2
+ * @short   CaptainHook.Config.CustomValueIsFalsy
  */
 class CustomValueIsFalsy extends Condition\Config
 {

src/Hook/Condition/Config/CustomValueIsTruthy.php

@@ -21,13 +21,17 @@
  *
  * Example configuration:
  *
- * "action": "some-action"
- * "conditions": [
- *   {"exec": "\\CaptainHook\\App\\Hook\\Condition\\Config\\CustomValueIsTruthy",
- *    "args": [
- *      "NAME_OF_CUSTOM_VALUE"
- *    ]}
- * ]
+ * <code>
+ * {
+ *   "action": "some-action"
+ *   "conditions": [
+ *     {
+ *       "exec": "CaptainHook.Config.CustomValueIsTruthy",
+ *       "args": ["NAME_OF_CUSTOM_VALUE"]
+ *     }
+ *   ]
+ * }
+ * </code>
  *
  * @package CaptainHook
  * @author  Sebastian Feldmann <[email protected]>

src/Hook/Condition/FileChanged/All.php

@@ -21,6 +21,22 @@
  * The FileChange condition is applicable for `post-merge` and `post-checkout` hooks.
  * It checks if all configured files are updated within the last change set.
  *
+ * Example configuration:
+ *
+ *  <code>
+ *  {
+ *    "action": "some-action"
+ *    "conditions": [
+ *      {
+ *        "exec": "CaptainHook.FileChanged.All",
+ *        "args": [
+ *          ["list", "of", "files"]
+ *        ]
+ *      }
+ *    ]
+ *  }
+ *  </code>
+ *
  * @package CaptainHook
  * @author  Sebastian Feldmann <[email protected]>
  * @link    https://github.com/captainhook-git/captainhook