diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..cd8eb86 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,15 @@ +; This file is for unifying the coding style for different editors and IDEs. +; More information at http://editorconfig.org + +root = true + +[*] +charset = utf-8 +indent_size = 4 +indent_style = space +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true + +[*.md] +trim_trailing_whitespace = false diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..3eca6c6 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,13 @@ +# Path-based git attributes +# https://www.kernel.org/pub/software/scm/git/docs/gitattributes.html + +# Ignore all test and documentation with "export-ignore". +/.editorconfig export-ignore +/.gitattributes export-ignore +/.gitignore export-ignore +/.php-cs-fixer.php export-ignore +/phpunit.xml.dist export-ignore +/tests export-ignore +/docs export-ignore +/phpstan.neon.dist export-ignore +/.github export-ignore diff --git a/.github/workflows/quality-assurance.yaml b/.github/workflows/quality-assurance.yaml new file mode 100644 index 0000000..07ed0f5 --- /dev/null +++ b/.github/workflows/quality-assurance.yaml @@ -0,0 +1,50 @@ +--- +name: Quality assurance +on: + push: + branches: ['main'] + pull_request: ~ + +jobs: + phpunit: + name: PHPUnit tests on ${{ matrix.php }} + runs-on: ubuntu-latest + strategy: + matrix: + php: [ '8.2', '8.3', '8.4' ] + steps: + - uses: actions/checkout@v2 + - uses: shivammathur/setup-php@v2 + with: + php-version: ${{ matrix.php }} + coverage: xdebug + - run: composer install --no-progress + - run: vendor/bin/phpunit + phpstan: + name: PHPStan checks on ${{ matrix.php }} + runs-on: ubuntu-latest + strategy: + matrix: + php: [ '8.4' ] + steps: + - uses: actions/checkout@v2 + - uses: shivammathur/setup-php@v2 + with: + php-version: ${{ matrix.php }} + coverage: none + - run: composer install --no-progress + - run: composer phpstan + cs: + name: Code Style checks on ${{ matrix.php }} + runs-on: ubuntu-latest + strategy: + matrix: + php: [ '8.4' ] + steps: + - uses: actions/checkout@v2 + - uses: shivammathur/setup-php@v2 + with: + php-version: ${{ matrix.php }} + coverage: none + - run: composer install --no-progress + - run: composer cs diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a930c3e --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +.env +vendor +build +composer.lock diff --git a/.php-cs-fixer.php b/.php-cs-fixer.php new file mode 100644 index 0000000..287fe7a --- /dev/null +++ b/.php-cs-fixer.php @@ -0,0 +1,42 @@ +in(__DIR__) + ->name(__FILE__) + ->exclude([ + 'build', + ]) +; + +$config = new PhpCsFixer\Config(); + +$config + ->setFinder($finder) + ->setCacheFile('build/php-cs-fixer.cache') + ->setLineEnding("\n") + ->setRiskyAllowed(true) + ->setRules([ + '@PER-CS' => true, + 'ordered_imports' => ['imports_order' => ['class', 'function', 'const'], 'sort_algorithm' => 'alpha'], + 'void_return' => true, + 'array_syntax' => ['syntax' => 'short'], + + // apply stricter whitespace rules + 'array_indentation' => true, + 'binary_operator_spaces' => true, + 'cast_spaces' => true, + 'concat_space' => ['spacing' => 'one'], + 'function_declaration' => ['closure_fn_spacing' => 'none'], + 'method_argument_space' => true, + 'no_extra_blank_lines' => true, + 'no_spaces_around_offset' => true, + 'no_trailing_whitespace_in_string' => true, + 'no_whitespace_before_comma_in_array' => true, + 'object_operator_without_whitespace' => true, + 'trim_array_spaces' => true, + 'type_declaration_spaces' => true, + 'unary_operator_spaces' => true, + 'whitespace_after_comma_in_array' => true, + ]); + +return $config; diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1da1f4c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,34 @@ +# Contributing + +Contributions are **welcome** and will be fully **credited**. + +We accept contributions via Pull Requests on [Github](https://github.com/php-fig/per-attributes). + +## Pull Requests + +- **[PER-Coding Standards](https://www.php-fig.org/per/coding-style/)** - Check the code style with `$ composer cs` and fix it with `$ composer cs-fix`. + +- **Add tests!** - Your patch won't be accepted if it doesn't have tests. + +- **Document any change in behaviour** - Make sure the `README.md` and any other relevant documentation are kept up-to-date. + +- **Consider our release cycle** - We try to follow [SemVer v2.0.0](http://semver.org/). Randomly breaking public APIs is not an option. + +- **Create feature branches** - Don't ask us to pull from your main branch. + +- **One pull request per feature** - If you want to do more than one thing, send multiple pull requests. + +- **Send coherent history** - Make sure each individual commit in your pull request is meaningful. If you had to make multiple intermediate commits while developing, please [squash them](http://www.git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages) before submitting. + + +## Running Tests + +``` bash +$ composer test +``` + +## AI Policy + +This project respects the copyright of all Open Source contributors. The legality of using Open Source data to train Code-generation AIs (including but not limited to GitHub Copilot) or of using Code-generation AIs to produce Open Source code is still very murky and unclear. For that reason, *AI-generated code is not welcome in this project and will be rejected on sight*. By submitting a PR, you affirm that the code was written 100% by you, and that you have the legal permission to offer it under the licensing terms of this project. Violation of this policy may result in your banning from the project. + +**Happy coding**! diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..b9e9dfe --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 PHP-FIG + +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. diff --git a/README.md b/README.md index f040313..59b856b 100644 --- a/README.md +++ b/README.md @@ -1 +1,48 @@ -# PER Attributes +# PHP Evolving Recommendation - Attributes + +[![Latest Version on Packagist][ico-version]][link-packagist] +[![Software License][ico-license]](LICENSE.md) +[![Total Downloads][ico-downloads]][link-downloads] + +This package contains PHP attribute definitions published by the PHP Framework Interoperability Group (PHP-FIG). They are intended to have widespread applicability across the PHP ecosystem. + +Any attribute proposed must be approved by a majority of the working group, and in some cases by the PHP-FIG Core Committee. Any submitted attribute must follow these guidelines: + +* It MUST have applicability and relevance for more than one project or application. +* It SHOULD have two or more projects to which the attribute would be relevant that state their intent to use it if approved. +* It MUST be parsable and usable with raw PHP. No third party attribute library requirements are allowed. +* It MUST follow PER-CS coding guidelines. +* It MUST adhere to PHPStan Level 10 levels of code tidiness. +* It MUST be extensively documented through docblocks on the attribute itself. +* It MAY have functionality beyond just the constructor, if relevant. +* If the required PHP version for a specific attribute is higher than that of the package, that MUST be specified in the class docblock. + +Ideally, proposals should be discussed in the [PHP-FIG Discord](https://discord.gg/php-fig), `#per-attributes` channel, prior to proposal. + +## Contributing + +Please see [CONTRIBUTING](CONTRIBUTING.md) for details. + +## Security + +If you discover any security related issues, please use the [GitHub security reporting form](https://github.com/php-fig/per-attributes/security) rather than the issue queue. + +## Working Group + + +- [Larry Garfield][link-crell] +- [All Contributors][link-contributors] +- [Jaap van Otterdijk][link-jaapio] +## License + +The MIT License. Please see [License File](LICENSE.md) for more information. + +[ico-version]: https://img.shields.io/packagist/v/fig/attributes.svg?style=flat-square +[ico-license]: https://img.shields.io/badge/License-MIT-green.svg?style=flat-square +[ico-downloads]: https://img.shields.io/packagist/dt/fig/attributes.svg?style=flat-square + +[link-packagist]: https://packagist.org/packages/fig/attributes +[link-downloads]: https://packagist.org/packages/fig/attributes +[link-crell]: https://github.com/Crell +[link-jaapio]: https://github.com/Jaapio +[link-contributors]: ../../contributors diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..d053c09 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,37 @@ +# Brand Promise + +Perfect security is not an achievable goal, but it is a goal to strive for nonetheless. To that end, we welcome responsible security reports from both users and external security researchers. + +# Scope + +If you believe you've found a security issue in software that is maintained in this repository, we encourage you to notify us. + +| Version | In scope | Source code | +| ------- | -------- |-------------------------------------------| +| latest | ✅ | https://github.com/php-fig/per-attributes | + +Only the latest stable release of this library is supported. In general, bug and security fixes will not be backported unless there is a substantial imminent threat to users in not doing so. + +# How to Submit a Report + +To submit a vulnerability report, please contact us through [GitHub](https://github.com/php-fig/per-attributes/security). Your submission will be reviewed as soon as feasible, but as this is a volunteer project we cannot guarantee a response time. + +# Safe Harbor + +We support safe harbor for security researchers who: + +* Make a good faith effort to avoid privacy violations, destruction of data, and interruption or degradation of our services. +* Only interact with accounts you own or with explicit permission of the account holder. If you do encounter Personally Identifiable Information (PII) contact us immediately, do not proceed with access, and immediately purge any local information. +* Provide us with a reasonable amount of time to resolve vulnerabilities prior to any disclosure to the public or a third-party. + +We will consider activities conducted consistent with this policy to constitute "authorized" conduct and will not pursue civil action or initiate a complaint to law enforcement. We will help to the extent we can if legal action is initiated by a third party against you. + +Please submit a report to us before engaging in conduct that may be inconsistent with or unaddressed by this policy. + +# Preferences + +* Please provide detailed reports with reproducible steps and a clearly defined impact. +* Include the version number of the vulnerable package in your report. +* Providing a suggested fix is welcome, but not required, and we may choose to implement our own, based on your submitted fix or not. +* This is a volunteer project. We will make every effort to respond to security reports in a timely manner, but that may be a week or two on the first contact. + diff --git a/composer.json b/composer.json new file mode 100644 index 0000000..bbb4c22 --- /dev/null +++ b/composer.json @@ -0,0 +1,37 @@ +{ + "name": "fig/attributes", + "require": { + "php": "~8.2" + }, + "require-dev": { + "friendsofphp/php-cs-fixer": "^v3.87.1", + "phpstan/phpstan": "^2.1.11", + "phpunit/phpunit": "^11.1.0" + }, + "autoload": { + "psr-4": { + "Fig\\Attributes\\": "src" + } + }, + "autoload-dev": { + "psr-4": { + "Fig\\Attributes\\": "tests" + } + }, + "scripts": { + "test": "vendor/bin/phpunit", + "test-coverage": "XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-text --coverage-clover=coverage-clover.xml", + "coverage": "XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-text --coverage-html=\"build/coverage\"", + "phpstan": "vendor/bin/phpstan analyze --memory-limit=-1", + "cs": "vendor/bin/php-cs-fixer check --diff", + "cs-fix": "vendor/bin/php-cs-fixer fix --diff", + "all-checks": [ + "@test", + "@phpstan", + "@cs" + ] + }, + "config": { + "sort-packages": true + } +} diff --git a/phpstan.neon.dist b/phpstan.neon.dist new file mode 100644 index 0000000..f2c52a5 --- /dev/null +++ b/phpstan.neon.dist @@ -0,0 +1,24 @@ +parameters: + level: 10 + tmpDir: build/phpstan.cache + paths: + - src + - tests + ignoreErrors: + # PHPStan is overly aggressive on readonly properties. + - identifier: property.uninitializedReadonly + reportUnmatched: false + - identifier: property.readOnlyAssignNotInConstructor + reportUnmatched: false + + # We don't need to be pedantic about iterable types in tests. + - identifier: missingType.iterableValue + paths: + - tests/* + reportUnmatched: false + + # PHPStan doesn't understand PHPUnit's self-termination methods. + - identifier: deadCode.unreachable + paths: + - tests/* + reportUnmatched: false diff --git a/phpunit.xml.dist b/phpunit.xml.dist new file mode 100644 index 0000000..bb0ca6b --- /dev/null +++ b/phpunit.xml.dist @@ -0,0 +1,39 @@ + + + + + tests + + + + + + + + + + + + + src + + + diff --git a/src/Placeholder.php b/src/Placeholder.php new file mode 100644 index 0000000..2296fd1 --- /dev/null +++ b/src/Placeholder.php @@ -0,0 +1,12 @@ +