diff --git a/README.md b/README.md index a866503..7de24ad 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,11 @@ [![Code Coverage](https://coveralls.io/repos/github/olvlvl/composer-attribute-collector/badge.svg?branch=main)](https://coveralls.io/r/olvlvl/composer-attribute-collector?branch=main) [![Downloads](https://img.shields.io/packagist/dt/olvlvl/composer-attribute-collector.svg)](https://packagist.org/packages/olvlvl/composer-attribute-collector) -composer-attribute-collector is a plugin for [Composer][]. Its ambition is to provide a convenient -way—and near zero cost—to retrieve targets of PHP 8 attributes. After the autoloader has been -dumped, the plugin collects attribute targets and generates a static file. Later, these targets can -be retrieved through a convenient interface, without reflection. The plugin is useful when you need -to _discover_ attribute targets in a codebase—for known targets you can use reflection. +**composer-attribute-collector** is a plugin for [Composer][]. Its ambition is to provide a +convenient way—and near zero cost—to retrieve targets of PHP 8 attributes. After the autoloader has +been dumped, the plugin collects attribute targets and generates a static file. These targets can be +retrieved through a convenient interface, without reflection. The plugin is useful when you need to +_discover_ attribute targets in a codebase—for known targets you can use reflection. @@ -21,6 +21,10 @@ to _discover_ attribute targets in a codebase—for known targets you can use re - A single interface to get attribute targets: classes, methods, and properties - Can cache discoveries to speed up consecutive runs. +> [!NOTE] +> Currently, the plugin supports class, method, and property targets. +> You're welcome to [contribute](CONTRIBUTING.md) if you're interested in expending its support. + #### Usage @@ -77,26 +81,13 @@ var_dump($attributes->propertyAttributes); ## Getting started +Here are a few steps to get you started. -### Installation - -```shell -composer require olvlvl/composer-attribute-collector -``` - -The plugin is currently experimental and its interface subject to change. At the moment, it only -supports class, method, and property targets. Please [contribute](CONTRIBUTING.md) if you're interested in -shaping its future. - - - -### Sample configuration +### 1\. Configure the plugin -The plugin only inspects paths and files specified in the configuration with the direction -`include`. That's usually your "src" directory. Add this section to your `composer.json` file to -enable the generation of the attributes file on autoload dump. - -Check the [Configuration options](#configuration) for more details. +The plugin only inspects paths and files specified in the configuration with the `include` property. +That is usually your "src" directory. Add this section to your `composer.json` file to enable the +generation of the "attributes" file when the autoloader is dumped. ```json { @@ -110,12 +101,39 @@ Check the [Configuration options](#configuration) for more details. } ``` +Check the [Configuration options](#configuration) for more details. + -### Autoloading +### 2\. Install the plugin -You can require the attributes file using `require_once 'vendor/attributes.php';` but you might -prefer using Composer's autoloading feature: +Use [Composer][] to install the plugin. +You will be asked if you trust the plugin and wish to activate it. +Select `y` to proceed. + +```shell +composer require olvlvl/composer-attribute-collector +``` + +You should see log messages similar to this: + +``` +Generating autoload files +Generating attributes file +Generated attributes file in 9.137 ms +Generated autoload files +``` + +> [!TIP] +> See the [Frequently Asked Questions](#frequently-asked-questions) section +> to automatically refresh the "attributes" file during development. + + + +### 3\. Autoload the "attributes" file + +You can require the "attributes" file using `require_once 'vendor/attributes.php';` but you might +prefer to use Composer's autoloading feature: ```json { @@ -131,10 +149,14 @@ prefer using Composer's autoloading feature: ## Configuration +Here are a few ways you can configure the plugin. + + + ### Including paths or files ([root-only][]) Use the `include` property to define the paths or files to inspect for attributes. Without this -property, the attributes file will be empty. +property, the "attributes" file will be empty. The specified paths are relative to the `composer.json` file, and the `{vendor}` placeholder is replaced with the path to the vendor folder. @@ -178,48 +200,24 @@ set the environment variable `COMPOSER_ATTRIBUTE_COLLECTOR_USE_CACHE` to `1`, `y Cache items are persisted in the `.composer-attribute-collector` directory, you might want to add it to your `.gitignore` file. +```shell +COMPOSER_ATTRIBUTE_COLLECTOR_USE_CACHE=1 composer dump-autoload +``` + ## Test drive with the Symfony Demo You can try the plugin with a fresh installation of the [Symfony Demo Application](https://github.com/symfony/demo). -Add the `composer-attribute-collector` node to `extra` and the autoload item to the `composer.json` file: - -```json -{ - "autoload": { - "files": [ - "vendor/attributes.php" - ] - }, - "extra": { - "composer-attribute-collector": { - "include": [ - "src" - ] - } - } -} -``` - -Use Composer to install the plugin. You'll be asked if you trust the plugin and wish to activate it. -If you wish to continue, choose `y`. - -```shell -composer require olvlvl/composer-attribute-collector -``` - -You should see log messages similar to this: +> [!TIP] +> The demo application configured with the plugin is [available on GitHub](https://github.com/olvlvl/composer-attribute-collector-usecase-symfony). -``` -Generating autoload files -Generating attributes file -Generated attributes file in 9.137 ms -Generated autoload files -``` +See the [Getting started](#getting-started) section to set up the plugin. If all went well, the file +`vendor/attributes.php` should be available. -The plugin should have generated the file `vendor/attributes.php`. Let's see if we can get the controller methods tagged as routes. Create a PHP file with the following content and run it: +Now, you can try to get the controller methods tagged as routes. Create a PHP file with the +following content and run it: ```php - * - * For the full copyright and license information, please view the LICENSE - * file that was distributed with this source code. - */ - namespace olvlvl\ComposerAttributeCollector; use Closure; diff --git a/src/ClassAttributeCollector.php b/src/ClassAttributeCollector.php index 351ea1e..dee4e13 100644 --- a/src/ClassAttributeCollector.php +++ b/src/ClassAttributeCollector.php @@ -7,7 +7,6 @@ use ReflectionAttribute; use ReflectionClass; use ReflectionException; -use Throwable; /** * @internal @@ -27,8 +26,6 @@ public function __construct( * array, * array, * } - * Where `0` is an array of class attributes, `1` is an array of method attributes, - * and `2` is an array of property attributes. * * @throws ReflectionException */ diff --git a/src/Collection.php b/src/Collection.php index 1405890..87f1d85 100644 --- a/src/Collection.php +++ b/src/Collection.php @@ -1,12 +1,5 @@ - * - * For the full copyright and license information, please view the LICENSE - * file that was distributed with this source code. - */ - namespace olvlvl\ComposerAttributeCollector; use RuntimeException; diff --git a/src/Config.php b/src/Config.php index c6b3b97..1f763de 100644 --- a/src/Config.php +++ b/src/Config.php @@ -2,7 +2,6 @@ namespace olvlvl\ComposerAttributeCollector; -use Composer\Composer; use Composer\Factory; use Composer\PartialComposer; use Composer\Util\Platform; @@ -91,9 +90,9 @@ public static function resolveVendorDir(PartialComposer $composer): string * @param non-empty-string $attributesFile * Absolute path to the `attributes.php` file. * @param non-empty-string[] $include - * Paths that should be included to attributes collection. + * Paths that should be included in the attribute collection. * @param non-empty-string[] $exclude - * Paths that should be excluded from attributes collection. + * Paths that should be excluded from the attribute collection. * @param bool $useCache * Whether a cache should be used during the process. */ diff --git a/src/Filter/Chain.php b/src/Filter/Chain.php index d59479d..0bcedc6 100644 --- a/src/Filter/Chain.php +++ b/src/Filter/Chain.php @@ -1,12 +1,5 @@ - * - * For the full copyright and license information, please view the LICENSE - * file that was distributed with this source code. - */ - namespace olvlvl\ComposerAttributeCollector\Filter; use Composer\IO\IOInterface; diff --git a/src/Filter/ContentFilter.php b/src/Filter/ContentFilter.php index 6c5ce31..9baa6ed 100644 --- a/src/Filter/ContentFilter.php +++ b/src/Filter/ContentFilter.php @@ -1,12 +1,5 @@ - * - * For the full copyright and license information, please view the LICENSE - * file that was distributed with this source code. - */ - namespace olvlvl\ComposerAttributeCollector\Filter; use Composer\IO\IOInterface; diff --git a/src/Filter/InterfaceFilter.php b/src/Filter/InterfaceFilter.php index 41eedbb..9008f1b 100644 --- a/src/Filter/InterfaceFilter.php +++ b/src/Filter/InterfaceFilter.php @@ -1,12 +1,5 @@ - * - * For the full copyright and license information, please view the LICENSE - * file that was distributed with this source code. - */ - namespace olvlvl\ComposerAttributeCollector\Filter; use Composer\IO\IOInterface; diff --git a/src/MemoizeAttributeCollector.php b/src/MemoizeAttributeCollector.php index fbecb9f..24c9c66 100644 --- a/src/MemoizeAttributeCollector.php +++ b/src/MemoizeAttributeCollector.php @@ -45,8 +45,6 @@ public function __construct( /** * @param array $classMap * Where _key_ is a class and _value_ its pathname. - * - * @throws ReflectionException */ public function collectAttributes(array $classMap): TransientCollection { @@ -95,7 +93,7 @@ public function collectAttributes(array $classMap): TransientCollection } /** - * Classes might have been removed, we need to filter according to the classes found. + * Classes might have been removed, we need to filter entries according to the classes found. */ $this->state = array_filter( $this->state, diff --git a/src/MemoizeClassMapFilter.php b/src/MemoizeClassMapFilter.php index de9e96b..1abb2a3 100644 --- a/src/MemoizeClassMapFilter.php +++ b/src/MemoizeClassMapFilter.php @@ -70,7 +70,7 @@ public function filter(array $classMap, Closure $filter): array } /** - * Paths might have been removed, we need to filter according to the paths found. + * Paths might have been removed, we need to filter entries according to the paths found. */ $this->state = array_filter( $this->state, diff --git a/src/MemoizeClassMapGenerator.php b/src/MemoizeClassMapGenerator.php index 77a6347..d304d93 100644 --- a/src/MemoizeClassMapGenerator.php +++ b/src/MemoizeClassMapGenerator.php @@ -112,7 +112,7 @@ private function shouldUpdate(int $timestamp, string $path): bool return true; } - // Could be a file referenced as class map, we don't want to iterate over that. + // Could be a file referenced as a class map, we don't want to iterate over that. if (!is_dir($path)) { return false; } diff --git a/src/Plugin.php b/src/Plugin.php index 052dd98..20a8441 100644 --- a/src/Plugin.php +++ b/src/Plugin.php @@ -96,7 +96,7 @@ public static function onPostAutoloadDump(Event $event): void public static function dump(Config $config, IOInterface $io): void { // - // Scan include paths + // Scan the included paths // $start = microtime(true); $datastore = self::buildDefaultDatastore($config, $io); diff --git a/src/TargetClass.php b/src/TargetClass.php index 05d7286..0f7ca48 100644 --- a/src/TargetClass.php +++ b/src/TargetClass.php @@ -1,12 +1,5 @@ - * - * For the full copyright and license information, please view the LICENSE - * file that was distributed with this source code. - */ - namespace olvlvl\ComposerAttributeCollector; /** @@ -19,6 +12,7 @@ final class TargetClass /** * @param T $attribute * @param class-string $name + * The name of the target class. */ public function __construct( public object $attribute, diff --git a/src/TargetMethod.php b/src/TargetMethod.php index ac81024..fe96060 100644 --- a/src/TargetMethod.php +++ b/src/TargetMethod.php @@ -1,12 +1,5 @@ - * - * For the full copyright and license information, please view the LICENSE - * file that was distributed with this source code. - */ - namespace olvlvl\ComposerAttributeCollector; /** @@ -19,7 +12,9 @@ final class TargetMethod /** * @param T $attribute * @param class-string $class + * The name of the target class. * @param non-empty-string $name + * The name of the target method. */ public function __construct( public object $attribute, diff --git a/src/TargetProperty.php b/src/TargetProperty.php index 6608c61..cf06f0d 100644 --- a/src/TargetProperty.php +++ b/src/TargetProperty.php @@ -1,12 +1,5 @@ - * - * For the full copyright and license information, please view the LICENSE - * file that was distributed with this source code. - */ - namespace olvlvl\ComposerAttributeCollector; /** @@ -19,7 +12,9 @@ final class TargetProperty /** * @param T $attribute * @param class-string $class + * The name of the target class. * @param non-empty-string $name + * The name of the target property. */ public function __construct( public object $attribute, diff --git a/src/TransientCollection.php b/src/TransientCollection.php index 79d8ebc..6f5c291 100644 --- a/src/TransientCollection.php +++ b/src/TransientCollection.php @@ -1,12 +1,5 @@ - * - * For the full copyright and license information, please view the LICENSE - * file that was distributed with this source code. - */ - namespace olvlvl\ComposerAttributeCollector; /**