linkorb / php-tools
PHP Tools: collection of isolated tools for qa, test, etc
Installs: 2
Dependents: 0
Suggesters: 0
Security: 0
Stars: 3
Watchers: 2
Forks: 2
Open Issues: 0
Language:Dockerfile
Requires
- php: >=7.2.0
- bamarni/composer-bin-plugin: ^1.4
This package is not auto-updated.
Last update: 2023-02-22 01:21:50 UTC
README
NOTE: Given the fact that this php-tools repo has identical goals to https://github.com/jakzal/phpqa, we've decided archive php-tools, and contribute to phpqa instead
php-tools
A collection of tools to use in PHP-based projects for static analysis, unit/bdd testing, documentation, etc.
Usage
PHP developers are agreeing that PHP tools should not be like regular composer dependencies (also not through require-dev), but instead be installed globally.
- https://twitter.com/s_bergmann/status/999635212723212288
- composer/composer#5390
- composer/composer#9636
- https://docs.phpdoc.org/2.9/getting-started/installing.html#using-composer ("we are unable to provide support on issues stemming from dependency conflicts")
- https://www.phpdoc.org/ (see "But wait? What about Composer?")
A primary reason for this is that adding many tools to require-dev significantly increases the complexity of the dependencies and constraints of your project. This can quickly lead to conflicts that are hard or impossible to solve. By installing these tools "globally", your project's dependencies will remain simple.
This repository contains the most commonly used PHP tools, so you can easily install them once, globally. You can then run these tools from all of your projects during testing, documentation generation, etc.
Installation
git clone https://github.com/linkorb/php-tools.git
cd php-tools
composer install # this recursively installs the tools inside of the `tools/` directory.
Update your PATH environment variable
To make sure you can call the available tools from any (project) directory, you'll need to add this repository's bin/
directory to your PATH environment variable:
export PATH="/path/to/php-tools/bin:$PATH"
You can now confirm if you can successfully run phpstan --help
from other directories.
To make this change permanent, add the previous line to your ~/.bashrc
, ~/.profile
or similar shell init script. Don't forget to start a new login session to check if it works.
If you're using linuxserver's code-server, you can pass a PATH variable as part of your docker-compose.yml file.
Troubleshooting
Uncaught Error: Undefined constant Bamarni\Composer\Bin\Command\BinCommand::SUCCESS
This can occur if composer-bin-plugin
is unable to resolve the path to binaries saved in the php-tools/bin
folder. Adding path/to/php-tools/bin
to your PATH environment variable before running composer install
may fix this bug.
Alternatives
- Listing tools in "require-dev". This quickly leads to complex dependency conflicts (sometimes unsolvable)
- Installing tools with "composer global install". While this keeps your project dependencies simple, it still combines the constraints of all your tools, still leading to complex dependency graphs.
- Installing "phar" versions of your tools. Nice, but downloading and updating these executables is cumbersome
- Using phive and phar.io to manage your .phar executables. Not all tools are on phar.io, and leads to a lot of duplication
- Using phpqa docker container. Complicated to reuse build configuration between local dev and CI (should be identical)
How does it work?
In the bin/
directory, you'll find a symlink for each of the available tools (phpstan, phpmd, phpcs, etc). These symlinks point to the tools themselves inside the tools/ directory.
This project uses composer-bin-plugin to manage the tools/
directory where every tool get's its own sub-directory (i.e. tools/phpstan
).
Each of those sub-directories is a mini standalone composer project with a single dependency (the tool). You'll find a composer.json
and a composer.lock
file in each tool directory.
You can run composer install
in the php-tools
root directory, which will trigger a composer install
inside each tool sub-directory too.
Adding new tools
You can use the composer-bin-plugin
to add new tools to the collection:
composer bin phpcs require squizlabs/php_codesniffer
- The name after
bin
is the name of the subdirectory intools/
that will be created for this tool. - The part after
require
is the composer package name of the tool as it is registered on packagist.org
Finally, create a symlink to your newly added tool(s):
cd bin/
ln -s ../tools/phpcs/vendor/bin/phpcs bin/phpcs
ln -s ../tools/phpcs/vendor/bin/phpcbf bin/phpcbf
Now commit:
- the tools/phpcs/composer.json and .lock files
- any symlinks you have created in
bin/
The .gitignore
file of this project should ensure you are not committing any vendor/ directories.
The .gitattributes
ensures your composer.lock files are managed as "binary" files, to avoid merge conflicts.
License
MIT. Please refer to the license file for details.
Brought to you by the LinkORB Engineering team
Check out our other projects at linkorb.com/engineering.
Btw, we're hiring!