linkorb/php-tools

This package is not installable via Composer 1.x, please make sure you upgrade to Composer 2+. Read more about our Composer 1.x deprecation policy.

PHP Tools: collection of isolated tools for qa, test, etc

Installs: 0

Dependents: 0

Suggesters: 0

Security: 0

Stars: 1

Watchers: 2

Forks: 0

Open Issues: 0

Language:Dockerfile

v1.0.0 2021-07-12 19:15 UTC

This package is not auto-updated.

Last update: 2021-09-07 18:13:31 UTC


README

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.

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.

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 in tools/ 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

687474703a2f2f7777772e6c696e6b6f72622e636f6d2f642f6d6574612f74696572312f696d616765732f6c696e6b6f7262656e67696e656572696e672d6c6f676f2e706e67
Check out our other projects at linkorb.com/engineering.

Btw, we're hiring!