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,21 @@
+/.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
+/phpstan.dist.neon      export-ignore
+/phpstan-baseline.neon  export-ignore
+
+*.php diff=php

.github/FUNDING.yml

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

.github/ISSUE_TEMPLATE/01-bug-report.yml

@@ -0,0 +1,62 @@
+# https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms
+# https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema
+
+name: "Bug report"
+description: "You've found a bug? Does the library not behave as expected?"
+title: "[BUG] "
+labels: ["bug"]
+
+body:
+
+  - type: markdown
+    attributes:
+      value: "You've found a bug? Does the library not behave as expected?\nPlease help us to improve this project and fill out the following form.\nIf you are unsure whether it is a bug, or you have a question or an issue that is not a bug, please go to [the discussions section](../discussions) instead. Thanks!"
+
+  - type: textarea
+    validations:
+      required: true
+    attributes:
+      label: "Issue description"
+      description: "Please describe the bug or unexpected behaviour, add screenshots to help explain the problem if applicable."
+      placeholder: "A clear and concise description of the issue"
+
+  - type: textarea
+    validations:
+      required: true
+    attributes:
+      label: "Expected behavior"
+      description: "Please describe what you expected to happen or how the library should behave in this case."
+      placeholder: "A clear and concise description of what you expected to happen"
+
+  - type: textarea
+    validations:
+      required: false
+    attributes:
+      label: "Code sample"
+      description: "If applicable, please add a code sample that reproduces the issue.\nNote: the content of this textarea will be rendered as PHP code!"
+      placeholder: "PHP code"
+      render: php
+
+  - type: dropdown
+    id: version
+    validations:
+      required: true
+    attributes:
+      label: "Library version"
+      description: "What version of the library are you running?"
+      options:
+        - "latest"
+        - "dev-main"
+        - "1.x"
+      default: 0
+
+  - type: textarea
+    validations:
+      required: false
+    attributes:
+      label: "Additional context"
+      description: "Add any other context that might be of use here, e.g. exact library version, PHP Version, operating system, other code snippets..."
+
+  - type: markdown
+    attributes:
+      value: "Thanks for taking the time to fill out this issue report!"

.github/ISSUE_TEMPLATE/02-feature-request.yml

@@ -0,0 +1,53 @@
+# https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms
+# https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema
+
+name: "Feature request"
+description: "You have an idea for a new feature?"
+title: "[ENHANCEMENT] "
+labels: ["enhancement"]
+
+body:
+
+  - type: markdown
+    attributes:
+      value: "You have an idea for a new feature (or improve an existing one)? Great!\nPlease help us to improve this project and fill out the following form.\nIf you have a question or an issue that is not a feature request, please go to [the discussions section](../discussions) instead. Thanks!"
+
+  - type: textarea
+    validations:
+      required: true
+    attributes:
+      label: "Feature description"
+      description: "Please describe the requested feature."
+      placeholder: "A clear and concise description of the requested feature"
+
+  - type: textarea
+    validations:
+      required: false
+    attributes:
+      label: "Code sample"
+      description: "If applicable, please add a code sample to illustrate the feature.\nNote: the content of this textarea will be rendered as PHP code!"
+      placeholder: "PHP code"
+      render: php
+
+  - type: textarea
+    validations:
+      required: false
+    attributes:
+      label: "Additional context"
+      description: "Add any other context that might be of use here, e.g. other code snippets..."
+
+  - type: dropdown
+    validations:
+      required: true
+    id: pr
+    attributes:
+      label: "Pull Request"
+      description: "**Are you (the requester) willing to submit a pull request for that feature?**\nA yes will greatly increase the chance that the feature will be added."
+      options:
+        - ""
+        - "No - I can't/won't submit a PR"
+        - "Yes - I will submit a PR"
+
+  - type: markdown
+    attributes:
+      value: "Thanks for taking the time to fill out this feature request!"

.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/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,108 @@
+# 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"
+
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v4
+
+      - name: "Install PHP"
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-version }}
+          extensions: ${{ 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 PHPStan"
+        run: php vendor/bin/phpstan
+
+
+  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
+
+#      - name: "Send code coverage report to Codacy"
+#        uses: codacy/codacy-coverage-reporter-action@v1
+#        with:
+#          project-token: ${{ secrets.CODACY_PROJECT_TOKEN }}
+#          coverage-reports: .build/coverage/clover.xml
+

.gitignore

@@ -0,0 +1,21 @@
+# 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
+phpstan.neon

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.