Initial commit

.editorconfig

@@ -0,0 +1,16 @@
+root = true
+
+[*]
+indent_style = tab
+charset = utf-8
+end_of_line = lf
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.py]
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml}]
+indent_style = space
+indent_size = 2

.gitattributes

@@ -0,0 +1,19 @@
+/.build            export-ignore
+/.github           export-ignore
+/.idea             export-ignore
+/.phan             export-ignore
+/.phpdoc           export-ignore
+/docs              export-ignore
+/examples          export-ignore
+/tests             export-ignore
+/.editorconfig     export-ignore
+/.gitattributes    export-ignore
+/.gitignore        export-ignore
+/.readthedocs.yml  export-ignore
+/composer.lock     export-ignore
+/phpcs.xml.dist    export-ignore
+/phpdoc.xml.dist   export-ignore
+/phpmd.xml.dist    export-ignore
+/phpunit.xml.dist  export-ignore
+
+*.php diff=php

.github/FUNDING.yml

@@ -0,0 +1 @@
+ko_fi: codemasher

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,51 @@
+---
+name: Bug report
+about: You have found a bug? Does the library not behave as expected? That's great (ok, not that great)! Please help us to improve!
+title: '[BUG]'
+labels: 'bug'
+---
+
+<!--
+Please FOLLOW THE ISSUE TEMPLATE unless you have a good reason not to.
+If you have a question or an issue that is not a bug,
+please use the Q&A section under discussions instead. Thanks!
+-->
+
+**Describe the bug or unexpected behaviour**
+
+A clear and concise description of what the bug is.
+
+
+**Steps to reproduce the behavior**
+
+- When i do ...
+- The code below ...
+- Error message: ...
+
+
+**Code sample** (if applicable)
+
+```php
+// your code here
+```
+
+
+**Expected behavior**
+
+A clear and concise description of what you expected to happen.
+
+
+**Screenshots**
+
+If applicable, add screenshots to help explain your problem.
+
+
+**Environment (please complete the following information):**
+
+- PHP version/OS: [e.g. 7.4.12, Ubuntu 20.04]
+- Library version: [e.g. 4.3.1]
+
+
+**Additional context**
+
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: "You have a question or an issue that is not a bug?"
+    about: "Please use the Q&A section under discussions. Thanks!"
+    url: https://github.com/chillerlan/php-library-template/discussions

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,33 @@
+---
+name: Feature request
+about: You have an idea for a new feature (or improve an existing one)? Great!
+title: '[ENHANCEMENT]'
+labels: 'enhancement'
+---
+
+<!--
+Please FOLLOW THE ISSUE TEMPLATE unless you have a good reason not to.
+If you have a question or an issue that is not a feature request,
+please use the Q&A section under discussions instead. Thanks!
+-->
+
+**Describe the feature**
+
+A clear and concise description of the requested feature.
+
+
+**Code sample** (if applicable)
+
+```php
+// your code here
+```
+
+
+**Additional context**
+
+Add any other context here (if applicable).
+
+
+**Are you (the requester) willing to submit a pull request for that feature?**
+
+[YES|NO] (A yes will greatly increase the chance that the feature will be added)

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,33 @@
+## Proposed changes
+
+<!-- Describe your changes here to communicate to the maintainers why you'd like to include this pull request.
+If it fixes a bug or resolves a feature request, be sure to link to that issue. -->
+
+
+<!-- You can erase any of the parts below that are not applicable to your Pull Request. -->
+
+## Types of changes
+
+<!-- Put an `x` in the boxes that apply -->
+
+What types of changes does your code introduce?
+
+- [ ] Bugfix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation fix or enhancement (no code was touched)
+- [ ] Other (CI, dependencies, etc., please describe)
+
+
+## Checklist:
+
+- [ ] I have checked to ensure there aren't other open [Issues](../../../issues) or [Pull Requests](../../../pulls) for the same update/change
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] I have added necessary documentation (if appropriate)
+- [ ] Any dependent changes have been merged and published in downstream modules
+- [ ] Static analysis and unit tests pass locally with my changes
+
+
+## Further comments
+
+If this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc...

.github/workflows/ci.yml

@@ -0,0 +1,105 @@
+# https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions
+# https://github.com/sebastianbergmann/phpunit/blob/main/.github/workflows/ci.yaml
+
+# https://github.com/actions/checkout
+# https://github.com/actions/upload-artifact
+# https://github.com/shivammathur/setup-php
+# https://github.com/ramsey/composer-install
+# https://github.com/codecov/codecov-action
+# https://github.com/codacy/codacy-coverage-reporter-action
+# https://github.com/JamesIves/github-pages-deploy-action
+# https://github.com/stefanzweifel/git-auto-commit-action
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+name: "Continuous Integration"
+
+env:
+  PHP_EXTENSIONS: "" # caution: setting 'none' resets/disables shared extensions
+  PHP_INI_VALUES: memory_limit=-1, error_reporting=-1, display_errors=On
+
+jobs:
+
+  static-code-analysis:
+    name: "Static Code Analysis"
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: true
+      matrix:
+        php-version:
+          - "8.1"
+          - "8.2"
+          - "8.3"
+
+    env:
+      PHAN_ALLOW_XDEBUG: 0
+      PHAN_DISABLE_XDEBUG_WARN: 1
+
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v4
+
+      - name: "Install PHP"
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-version }}
+          extensions: ast, ${{ env.PHP_EXTENSIONS }}
+          ini-values: ${{ env.PHP_INI_VALUES }}
+          coverage: none
+
+      - name: "Validate composer.json"
+        run: composer validate --ansi --strict
+
+      - name: "Install dependencies with composer"
+        uses: ramsey/composer-install@v3
+
+      - name: "Run phan"
+        run: php vendor/bin/phan --target-php-version=${{ matrix.php-version }}
+
+
+  tests:
+    name: "Unit Tests"
+    needs: static-code-analysis
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - windows-latest
+        php-version:
+          - "8.1"
+          - "8.2"
+          - "8.3"
+
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v4
+
+      - name: "Install PHP with extensions"
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-version }}
+          extensions: ${{ env.PHP_EXTENSIONS }}
+          ini-values: ${{ env.PHP_INI_VALUES }}
+          coverage: pcov
+
+      - name: "Install dependencies with composer"
+        uses: ramsey/composer-install@v3
+
+      - name: "Run tests with phpunit"
+        run: php vendor/bin/phpunit --colors=always --configuration=phpunit.xml.dist
+
+#      - name: "Send code coverage report to Codecov.io"
+#        uses: codecov/codecov-action@v4
+#        with:
+#          token: ${{ secrets.CODECOV_TOKEN }}
+#          files: .build/coverage/clover.xml

.gitignore

@@ -0,0 +1,20 @@
+# IDE - IntelliJ
+.idea/*
+# Keep the code styles.
+!.idea/codeStyles
+.idea/codeStyles/*
+!.idea/codeStyles/Project.xml
+!.idea/codeStyles/codeStyleConfig.xml
+# Keep the inspection levels
+!.idea/inspectionProfiles
+.idea/inspectionProfiles/*
+!.idea/inspectionProfiles/Project_Default.xml
+
+# project stuff
+.build/*
+vendor/*
+composer.lock
+phpcs.xml
+phpdoc.xml
+phpmd.xml
+phpunit.xml

.phan/config.php

@@ -0,0 +1,61 @@
+<?php
+/**
+ * This configuration will be read and overlaid on top of the
+ * default configuration. Command-line arguments will be applied
+ * after this file is read.
+ *
+ * @see https://github.com/phan/phan/wiki/Getting-Started#creating-a-config-file
+ */
+return [
+	// Supported values: `'5.6'`, `'7.0'`, `'7.1'`, `'7.2'`, `'7.3'`,
+	// `'7.4'`, `null`.
+	// If this is set to `null`,
+	// then Phan assumes the PHP version which is closest to the minor version
+	// of the php executable used to execute Phan.
+	//
+	// Note that the **only** effect of choosing `'5.6'` is to infer
+	// that functions removed in php 7.0 exist.
+	// (See `backward_compatibility_checks` for additional options)
+	'target_php_version'              => null,
+	'minimum_target_php_version'      => '8.1',
+
+	// A list of directories that should be parsed for class and
+	// method information. After excluding the directories
+	// defined in exclude_analysis_directory_list, the remaining
+	// files will be statically analyzed for errors.
+	//
+	// Thus, both first-party and third-party code being used by
+	// your application should be included in this list.
+	'directory_list'                  => [
+		'.phan/stubs',
+		'examples',
+		'src',
+		'tests',
+		'vendor',
+	],
+
+	// A regex used to match every file name that you want to
+	// exclude from parsing. Actual value will exclude every
+	// "test", "tests", "Test" and "Tests" folders found in
+	// "vendor/" directory.
+	'exclude_file_regex'              => '@^vendor/.*/(tests?|Tests?)/@',
+
+	// A directory list that defines files that will be excluded
+	// from static analysis, but whose class and method
+	// information should be included.
+	//
+	// Generally, you'll want to include the directories for
+	// third-party code (such as "vendor/") in this list.
+	//
+	// n.b.: If you'd like to parse but not analyze 3rd
+	//       party code, directories containing that code
+	//       should be added to both the `directory_list`
+	//       and `exclude_analysis_directory_list` arrays.
+	'exclude_analysis_directory_list' => [
+		'vendor/',
+		'.phan/stubs',
+	],
+	'suppress_issue_types'            => [
+		'PhanAccessMethodInternal',
+	],
+];

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 smiley <smiley@chillerlan.net>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.