Templates

README.md

@@ -5,31 +5,123 @@ Development toolkit for CodeIgniter libraries and projects
 
 * Install via Composer: `> composer require --dev codeigniter4/devkit`
 
-## Included
+## Included Dependencies
 
 ### Styles and Standards
 
 * [CodeIgniter Coding Standard](https://github.com/CodeIgniter/coding-standard)
-* NexusPHP CS Config
+* [NexusPHP CS Config](https://github.com/NexusPHP/cs-config)
 
 ### Testing and Analysis
 
-* NexusPHP Tachycardia
-* PHPStan
-* PHPUnit
+* [NexusPHP Tachycardia](https://github.com/NexusPHP/tachycardia)
+* [PHPStan](https://phpstan.org/user-guide/getting-started)
+* [PHPUnit](http://phpunit.readthedocs.io)
 
 ### Mocking
 
-* FakerPHP
-* VFS Stream
+* [FakerPHP](https://fakerphp.github.io)
+* [VFS Stream](https://github.com/bovigo/vfsStream/wiki)
 
-## Additional Tools
+### Security
 
-These are integrated into the workflows but not included via Composer so need to be installed separately.
-All of them are available via [Phive](https://phar.io/#Tools).
+* [Dependabot](https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/about-dependabot-version-updates)
+* [Roave Security Advisories](https://github.com/Roave/SecurityAdvisories)
+
+### Additional Tools
+
+These are integrated into the workflows but not included via Composer. If you want to use them
+locally they will need to be installed. All of them are available via [Phive](https://phar.io/#Tools).
 
 * [Composer Normalize](https://github.com/ergebnis/composer-normalize)
 * [Composer Unused](https://github.com/composer-unused/composer-unused)
+* [Deptrac](https://github.com/qossmic/deptrac)
 * [Infection](https://infection.github.io/)
 * [PHP Coveralls](https://php-coveralls.github.io/php-coveralls/)
 * [PHP CS Fixer](https://cs.symfony.com/)
+
+## Source Files
+
+The provided source files should be considered guidelines or templates for your own use, as
+they may need changing to fit your environment. These are based on the following assumptions:
+
+1. Your default repository branch is set to `develop`
+2. You use Composer to manage all necessary dependencies
+3. Your source code is located in **app/** (for projects) or **src/** (for libraries)
+4. Your unit tests are located in **tests/**
+5. Your CodeIgniter dependency is `codeigniter4/framework` (some paths need to be changed for `dev-develop`)
+
+### Workflows
+
+This kit includes a number of workflow templates for integrating [GitHub Actions](https://docs.github.com/en/actions)
+into your library or project development process. To add these to your repo simply copy the
+workflows into a **.github/workflows/** directory.
+
+> Hint: the [source files](src/.github) also include a configuration for Dependabot which will help keep your dependencies and workflows updated.
+
+Below is a brief description of each workflow; see the links above for help with each tool.
+
+#### Deptrac
+
+*Requires **depfile.yaml***
+
+Deptrac is a "dependency tracing" tool that allows developers to define which components should
+be allowed to access each other. This helps keep your project architecture logical and concise
+by enforcing the rules you set. For example, you may want to impose an MVC-style architecture
+by allowing a `Controller` to use any `Model` but not vice-versa.
+
+#### Infection
+
+*Requires **infection.json.dist***
+
+Just because your tests reach a high level of code coverage does not mean they are comprehensive.
+Mutation Testing is a way of gauging the *quality* of your unit tests. A silly example: your
+code has an increment function with a single unit test for 100% coverage:
+
+```php
+function increment(int $num1, int $num2): int
+{
+    return $num1 + $num2;
+}
+
+function testIncrementWithZero()
+{
+    $result = increment(42, 0);
+    $this->assertSame(42, $result);
+}
+```
+
+Infection will re-run your unit test against "mutated" versions of your code that *should*
+cause failures and report "escaped mutations" when they still pass. In this example, Infection
+mutates your `increment()` function to use `-` instead of `+`, but since your test case
+still asserts `42` as the result it is considered an "escape" and you should plan to add
+more tests.
+
+#### PHPCPD
+
+PHP Copy-Paste Detector analyzes your code and reports when there are blocks of duplicate code
+more than a certain number of lines long (default: 5). In most cases this is a sign of poor
+code structure and an opportunity to consolidate classes or functions.
+
+#### PHPStan
+
+*Requires **phpstan.neon.dist***
+
+Static analysis is a major factor in catching bugs and issues before they happen. PHPStan will
+analyze your code for mistakes based on the configuration supplied.
+
+#### PHPUnit
+
+*Requires **phpunit.xml.dist***
+
+Unit testing automates running your code through all the possible scenarios before putting it
+into use in production. PHPUnit is a highly-configurable framework and suite for writing and
+running unit tests. This workflow also configures PHPUnit to report on code coverage and
+upload the results to [Coveralls.io](https://coveralls.io) (you will need a free account,
+but it is also fine to use this workflow without Coveralls).
+
+#### Unused
+
+Composer Unused does one thing: checks that your code actually uses the dependencies you
+have included via Composer. It can be easy to forget to update your **composer.json** when
+your code drops a dependency, so this workflow will help track those down.

src/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+- package-ecosystem: composer
+  directory: "/"
+  schedule:
+    interval: daily
+  open-pull-requests-limit: 10
+
+- package-ecosystem: "github-actions"
+  directory: "/"
+  schedule:
+    interval: daily

src/.github/workflows/deptrac.yml

@@ -0,0 +1,74 @@
+name: Deptrac
+
+on:
+  pull_request:
+    branches:
+      - develop
+    paths:
+      - '**.php'
+      - 'composer.**'
+      - 'depfile.yaml'
+      - '.github/workflows/deptrac.yml'
+  push:
+    branches:
+      - develop
+    paths:
+      - '**.php'
+      - 'composer.**'
+      - 'depfile.yaml'
+      - '.github/workflows/deptrac.yml'
+
+jobs:
+  build:
+    name: Dependency Tracing
+    runs-on: ubuntu-latest
+    if: "!contains(github.event.head_commit.message, '[ci skip]')"
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.0'
+          tools: phive
+          extensions: intl, json, mbstring, xml
+          coverage: none
+        env:
+          COMPOSER_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Get composer cache directory
+        id: composer-cache
+        run: echo "::set-output name=dir::$(composer config cache-files-dir)"
+
+      - name: Cache composer dependencies
+        uses: actions/cache@v2
+        with:
+          path: ${{ steps.composer-cache.outputs.dir }}
+          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.json') }}-${{ hashFiles('**/composer.lock') }}
+          restore-keys: ${{ runner.os }}-composer-
+
+      - name: Create Deptrac cache directory
+        run: mkdir -p build/
+
+      - name: Cache Deptrac results
+        uses: actions/cache@v2
+        with:
+          path: build
+          key: ${{ runner.os }}-deptrac-${{ github.sha }}
+          restore-keys: ${{ runner.os }}-deptrac-
+
+      - name: Install dependencies
+        run: |
+          composer -q config -g github-oauth.github.com "${{ secrets.GITHUB_TOKEN }}"
+          if [ -f composer.lock ]; then
+            composer install --no-progress --no-interaction --prefer-dist --optimize-autoloader
+          else
+            composer update --no-progress --no-interaction --prefer-dist --optimize-autoloader
+          fi
+
+      - name: Trace dependencies
+        run: |
+          sudo phive --no-progress install --global --trust-gpg-keys B8F640134AB1782E,A98E898BB53EB748 qossmic/deptrac
+          deptrac analyze --cache-file=build/deptrac.cache

src/.github/workflows/infection.yml

@@ -0,0 +1,73 @@
+name: Infection
+
+on:
+  pull_request:
+    branches:
+      - develop
+    paths:
+      - '**.php'
+      - 'composer.**'
+      - 'phpunit*'
+      - '.github/workflows/infection.yml'
+  push:
+    branches:
+      - develop
+    paths:
+      - '**.php'
+      - 'composer.**'
+      - 'phpunit*'
+      - '.github/workflows/infection.yml'
+
+jobs:
+  main:
+    name: Mutation Testing
+    runs-on: ubuntu-latest
+    if: "!contains(github.event.head_commit.message, '[ci skip]')"
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.0'
+          tools: infection, phpunit
+          extensions: intl, json, mbstring, gd, xml, sqlite3
+          coverage: xdebug
+        env:
+          COMPOSER_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up problem matchers for PHPUnit
+        run: echo "::add-matcher::${{ runner.tool_cache }}/phpunit.json"
+
+      - name: Configure matchers
+        uses: mheap/phpunit-matcher-action@v1
+
+      - name: Get composer cache directory
+        id: composer-cache
+        run: echo "::set-output name=dir::$(composer config cache-files-dir)"
+
+      - name: Cache composer dependencies
+        uses: actions/cache@v2
+        with:
+          path: ${{ steps.composer-cache.outputs.dir }}
+          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.json') }}-${{ hashFiles('**/composer.lock') }}
+          restore-keys: ${{ runner.os }}-composer-
+
+      - name: Install dependencies
+        run: |
+          composer -q config -g github-oauth.github.com "${{ secrets.GITHUB_TOKEN }}"
+          if [ -f composer.lock ]; then
+            composer install --no-progress --no-interaction --prefer-dist --optimize-autoloader
+          else
+            composer update --no-progress --no-interaction --prefer-dist --optimize-autoloader
+          fi
+
+      - name: Test with PHPUnit
+        run: vendor/bin/phpunit --teamcity
+
+      - name: Mutate with Infection
+        run: |
+          git fetch --depth=1 origin $GITHUB_BASE_REF
+          infection --threads=2 --skip-initial-tests --coverage=build/phpunit --git-diff-base=origin/$GITHUB_BASE_REF --git-diff-filter=AM --logger-github --ignore-msi-with-no-mutations

src/.github/workflows/phpcpd.yml

@@ -0,0 +1,36 @@
+name: PHPCPD
+
+on:
+  pull_request:
+    branches:
+      - develop
+    paths:
+      - '**.php'
+      - '.github/workflows/phpcpd.yml'
+  push:
+    branches:
+      - develop
+    paths:
+      - '**.php'
+      - '.github/workflows/phpcpd.yml'
+
+jobs:
+  build:
+    name: Code Copy-Paste Detection
+    runs-on: ubuntu-latest
+    if: "!contains(github.event.head_commit.message, '[ci skip]')"
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.0'
+          tools: phpcpd
+          extensions: dom, mbstring
+          coverage: none
+
+      - name: Detect duplicate code
+        run: phpcpd app/ src/ tests/