diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d8d53b0..365724c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -21,7 +21,7 @@ on: name: "Continuous Integration" env: - PHP_EXTENSIONS: "" + PHP_EXTENSIONS: "" # caution: setting 'none' resets/disables shared extensions PHP_INI_VALUES: memory_limit=-1, error_reporting=-1, display_errors=On jobs: @@ -54,6 +54,9 @@ jobs: 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 @@ -121,8 +124,7 @@ jobs: uses: shivammathur/setup-php@v2 with: php-version: "8.3" - extensions: simplexml, ${{ env.PHP_EXTENSIONS }} - ini-values: ${{ env.PHP_INI_VALUES }} + extensions: simplexml coverage: none tools: phpDocumentor diff --git a/README.md b/README.md new file mode 100644 index 0000000..051b9a7 --- /dev/null +++ b/README.md @@ -0,0 +1,55 @@ +# chillerlan/php-library-template + +A template/boilerplate for PHP libraries. + +[![PHP Version Support][php-badge]][php] +[![Packagist version][packagist-badge]][packagist] +[![License][license-badge]][license] +[![Continuous Integration][gh-action-badge]][gh-action] +[![CodeCov][coverage-badge]][coverage] +[![Codacy][codacy-badge]][codacy] +[![Packagist downloads][downloads-badge]][downloads] + +[php-badge]: https://img.shields.io/packagist/php-v/chillerlan/php-library-template?logo=php&color=8892BF&logoColor=fff +[php]: https://www.php.net/supported-versions.php +[packagist-badge]: https://img.shields.io/packagist/v/chillerlan/php-library-template.svg?logo=packagist&logoColor=fff +[packagist]: https://packagist.org/packages/chillerlan/php-library-template +[license-badge]: https://img.shields.io/github/license/chillerlan/php-library-template.svg +[license]: https://github.com/chillerlan/php-library-template/blob/main/LICENSE +[gh-action-badge]: https://img.shields.io/github/actions/workflow/status/chillerlan/php-library-template/ci.yml?branch=main&logo=github&logoColor=fff +[gh-action]: https://github.com/chillerlan/php-library-template/actions/workflows/ci.yml?query=branch%3Amain +[coverage-badge]: https://img.shields.io/codecov/c/github/chillerlan/php-library-template.svg?logo=codecov&logoColor=fff +[coverage]: https://codecov.io/github/chillerlan/php-library-template +[codacy-badge]: https://img.shields.io/codacy/grade/de971588f9a44f1a99e7bbd2a0737951?logo=codacy&logoColor=fff +[codacy]: https://app.codacy.com/gh/chillerlan/php-library-template/dashboard +[downloads-badge]: https://img.shields.io/packagist/dt/chillerlan/php-library-template.svg?logo=packagist&logoColor=fff +[downloads]: https://packagist.org/packages/chillerlan/php-library-template/stats + +## Overview + +### Features + +- [GitHub Actions](https://github.com/chillerlan/php-library-template/actions) runner +- [Composer](https://getcomposer.org) package management +- [PHPUnit](https://phpunit.de) unit tests +- [PHAN](https://github.com/phan/phan) static analysis +- [PHPCS](https://github.com/PHPCSStandards/PHP_CodeSniffer) coding standard analyzer +- [PHPMD](https://phpmd.org) mess detector +- [phpDocumentor](https://www.phpdoc.org) auto generated API docs +- [ReadTheDocs](https://readthedocs.org) documentation builder + + +### Requirements + +- PHP 8.1+ + + +## Documentation + +- The user manual is at https://php-library-template.readthedocs.io/ ([sources](https://github.com/chillerlan/php-library-template/tree/main/docs)) +- An API documentation created with [phpDocumentor](https://www.phpdoc.org/) can be found at https://chillerlan.github.io/php-library-template/ + + +## Disclaimer + +Use at your own risk! diff --git a/docs/Readme.md b/docs/Readme.md new file mode 100644 index 0000000..0446bf5 --- /dev/null +++ b/docs/Readme.md @@ -0,0 +1,73 @@ +# Documentation + +## Auto generated documentation + +### User manual via Sphinx + +[![Documentation Status](https://readthedocs.org/projects/php-library-template/badge/?version=latest)](https://php-library-template.readthedocs.io/en/latest/?badge=latest) + +The user manual can be auto generated with [Sphinx](https://www.sphinx-doc.org) from the markdown sources contained in this directory, in order to upload it to [Read the Docs](https://readthedocs.org). +The online documentation can be found at [php-library-template.readthedocs.io](https://php-library-template.readthedocs.io/en/main/) ([project page](https://readthedocs.org/projects/php-library-template/)), a local copy is built during CI and stored in the [`readthedocs` branch](https://github.com/chillerlan/php-library-template-core/tree/readthedocs). + + +#### Run Sphinx locally + +Requirements: + +- [Python](https://www.python.org/downloads/) >= v3.10 + - [Sphinx](https://www.sphinx-doc.org/en/master/usage/installation.html) >= v6.0 + - [Sphinx RTD theme](https://pypi.org/project/sphinx-rtd-theme/) >= 1.2 + - [MyST Parser](https://myst-parser.readthedocs.io/en/latest/intro.html) >= 2.0 (see [Sphinx Markdown configuration](https://www.sphinx-doc.org/en/master/usage/markdown.html#markdown)) + +Follow these steps to create the user manual: + +- install Sphinx: `pip install sphinx myst-parser sphinx-rtd-theme` +- run in the `/docs` (this) directory: + - on Windows: `.\make.bat html` (make sure `sphinx-build.exe` is in `PATH`) + - on Linux: `make html` +- open [../.build/sphinx/html/index.html](../.build/sphinx/html/index.html) in a browser +- yay! + + +### API docs via phpDocumentor + +[![pages-build-deployment](https://github.com/chillerlan/php-library-template/actions/workflows/pages/pages-build-deployment/badge.svg?branch=gh-pages)](https://github.com/chillerlan/php-library-template/actions/workflows/pages/pages-build-deployment) + +The API documentation can be auto generated with [phpDocumentor](https://www.phpdoc.org/). +There is an [online version available](https://chillerlan.github.io/php-library-template/) via the [`gh-pages` branch](https://github.com/chillerlan/php-library-template/tree/gh-pages) +that is [automatically deployed](https://github.com/chillerlan/php-library-template/deployments) on each push to main. + + +#### Run phpDocumentor locally + +If you'd like to create local docs, please follow these steps: + +- [download phpDocumentor](https://github.com/phpDocumentor/phpDocumentor/releases) v3+ as .phar archive +- run it in the repository root directory: + - on Windows `c:\path\to\php.exe c:\path\to\phpDocumentor.phar --config=phpdoc.xml` + - on Linux just `php /path/to/phpDocumentor.phar --config=phpdoc.xml` +- open [../.build/phpdocs/index.html](../.build/phpdocs/index.html) in a browser +- profit! + + +## Sources + +The markdown sources for the [Read the Docs online manual](https://php-library-template.readthedocs.io) can of course be browsed on GitHub too! + + +### Usage + +- [Overview](./Usage/Overview.md) +- [Installation](./Usage/Installation.md) +- [Quickstart](./Usage/Quickstart.md) + + +### Appendix + +- [How to contribute](./Appendix/Contribute.md) +- [License](./Appendix/License.rst) + + +## License + +The documentation is licensed under the [Creative Commons Attribution 4.0 International (CC BY 4.0) License](https://creativecommons.org/licenses/by/4.0/).