From 0b7a337200e649a2ab17fe94e7accabb699b5bc9 Mon Sep 17 00:00:00 2001 From: Pavel Buchnev Date: Fri, 24 Nov 2023 13:40:53 +0400 Subject: [PATCH] Update README.md --- README.md | 343 +++--------------------------------------------------- 1 file changed, 15 insertions(+), 328 deletions(-) diff --git a/README.md b/README.md index e8702b6..59e361f 100644 --- a/README.md +++ b/README.md @@ -6,328 +6,26 @@ [![psalm](https://github.com/spiral-packages/discoverer/actions/workflows/psalm.yml/badge.svg)](https://github.com/spiral-packages/discoverer/actions) [![Total Downloads](https://poser.pugx.org/spiral-packages/discoverer/downloads)](https://packagist.org/spiral-packages/discoverer/phpunit) -## Requirements - -Make sure that your server is configured with following PHP version and extensions: - -- PHP 8.0+ -- Spiral framework 2.9+ - -## Installation - -You can install the package via composer: - -```bash -composer require spiral-packages/discoverer -``` - -After package install you need to register bootloader from the package. - -```php -protected const LOAD = [ - // ... - \Spiral\Discoverer\DiscovererBootloader::class, -]; -``` - -After package install you need to add `Spiral\Discoverer\WithDiscovering` trait from the package to your Application -kernel. - -```php -use Spiral\Discoverer\WithDiscovering; -use Spiral\Framework\Kernel; - -class App extends Kernel -{ - use WithDiscovering; -} -``` - -And then you should modify you `app.php` file. Example you can see below. - -```php - __DIR__ -]); - -$app->discover( - // Bootloaders sources - new \Spiral\Discoverer\Bootloader\BootloadersDiscoverer( - new \Spiral\Discoverer\Bootloader\ComposerRegistry(), - new \Spiral\Discoverer\Bootloader\ArrayRegistry(...), - new \Spiral\Discoverer\Bootloader\ConfigRegistry() - ), - - // Tokenizer directories - new \Spiral\Discoverer\Tokenizer\DirectoriesDiscoverer( - new \Spiral\Discoverer\Tokenizer\ComposerRegistry(), - ) -); - -if ($app->run() !== null) { - $code = (int)$app->serve(); - exit($code); -} -``` - -### Bootloaders discoverer - -It will help you to register bootloaders from different sources - -#### From composer - -Will register bootloaders from application `composer.json` and from other installed composer packages - -```php -new \Spiral\Discoverer\Bootloader\ComposerRegistry(), -``` - -**Package composer.json** - -```json -{ - // ... - "extra": { - "spiral": { - "bootloaders": [ - "Spiral\\Monolog\\Bootloader\\DotenvBootloader", - "Spiral\\DotEnv\\Bootloader\\MonologBootloader" - ], - "dont-discover": [ - "spiral-packages/event-bus" - ] - } - } -} -``` - -**Application composer.json** - -```json -{ - // ... - "extra": { - "spiral": { - "dont-discover": [ - "spiral-packages/foo", - "spiral-packages/bar" - ] - } - } -} -``` - -#### From array - -Will register bootloaders from the passed array - -```php -new \Spiral\Discoverer\Bootloader\ArrayRegistry([ - // Application specific logs - Bootloader\LoggingBootloader::class, - - // ... -]), -``` - -#### From config +1. **Automatic Discovery of Bootloaders**: Automates the process of discovering and registering bootloaders from installed packages, significantly simplifying the integration and setup process in Spiral applications. + +2. **Composer.json Integration**: The package leverages the `composer.json` file of other packages to define bootloaders and tokenizer directories. This integration streamlines the configuration process, making it easier for developers to manage package settings. + +3. **Custom Registry Support**: The package allows for the creation of custom bootloader and tokenizer registries. This flexibility enables developers to tailor the discovery process to their specific needs, enhancing the customization and scalability of their Spiral applications. -```php -new \Spiral\Discoverer\Bootloader\ConfigRegistry(), -``` - -```php -// config/discoverer.php - [ - // Core Services - Framework\SnapshotsBootloader::class, - Framework\I18nBootloader::class, - - // Security and validation - Framework\Security\EncrypterBootloader::class, - Framework\Security\ValidationBootloader::class, - Framework\Security\FiltersBootloader::class, - Framework\Security\GuardBootloader::class, - ], - 'ignoredBootloaders' => [ - // ... - ], -]; -``` - -#### Custom Bootloader registry - -You have the ability to create your custom Registries by -implementing `Spiral\Discoverer\Bootloader\BootloaderRegistryInterface` - -```php -use Spiral\Discoverer\Bootloader\BootloaderRegistryInterface; -use Spiral\Core\Container; -use Spiral\Files\FilesInterface; - -final class JsonRegistry implements BootloaderRegistryInterface -{ - private array $bootloaders = []; - private array $ignorableBootloaders = []; - - public function __construct( - private string $jsonPath - ) { - } - - public function init(Container $container): void - { - // json structure - // { - // "bootloaders": [ - // "Framework\Security\EncrypterBootloader", - // "Framework\Security\GuardBootloader" - // ], - // "ignored_bootloaders": [] - //} - - $files = $container->get(FilesInterface::class); - $data = \json_decode($files->read($this->jsonPath), true); - - $this->bootloaders = $data['bootloaders'] ?? []; - $this->ignorableBootloaders = $data['ignored_bootloaders'] ?? []; - } - - public function getBootloaders(): array - { - return $this->bootloaders; - } - - public function getIgnoredBootloaders(): array - { - return $this->ignorableBootloaders; - } -} -``` - -### Tokenizer directories discoverer - -It will help you to register Tokenizer directories from different sources - -#### From composer - -Will register directories from application `composer.json` and from other installed composer packages - -**Package composer.json** - -```json -{ - // ... - "extra": { - "spiral": { - "directories": [ - "src/Entities" - ] - } - } -} -``` - -**Application composer.json** - -```json -{ - // ... - "extra": { - "spiral": { - "directories": { - "self": [ - "src/Events" - ], - "spiral-package/event-bus": [ - "src/Events" - ], - "spiral-package/notifications": "src/Events" - } - } - } -} -``` - -```php -new \Spiral\Discoverer\Tokenizer\ComposerRegistry(), -``` - -#### Custom Directory registry - -You have the ability to create your custom Registries by -implementing `Spiral\Discoverer\Tokenizer\DirectoryRegistryInterface` - -```php -use Spiral\Discoverer\Tokenizer\DirectoryRegistryInterface; -use Spiral\Core\Container; -use Spiral\Files\FilesInterface; - -final class JsonRegistry implements DirectoryRegistryInterface -{ - private array $directories = []; - - public function __construct( - private string $jsonPath - ) { - } - - public function init(Container $container): void - { - // json structure - // { - // "directories": [ - // "src/Listeners", - // "src/Entities" - // ] - // } +## Requirements - $root = $container->get(\Spiral\Boot\DirectoriesInterface::class)->get('root'); +Make sure that your server is configured with following PHP version and extensions: - $files = $container->get(FilesInterface::class); - $data = \json_decode($files->read($this->jsonPath), true); +- PHP 8.1+ +- Spiral Framework version 3.10 or higher - $this->directories = \array_map(function (string $dir) use($root) { - return $root . $dir; - }, $data['directories'] ?? []); - } +## Documentation, Installation, and Usage Instructions - public function getDirectories(): array - { - return $this->directories; - } -} -``` +See the [documentation](https://spiral.dev/docs/component-discoverer) for detailed installation and usage instructions. ## Testing @@ -335,21 +33,10 @@ final class JsonRegistry implements DirectoryRegistryInterface composer test ``` -## Changelog - -Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. - -## Contributing - -Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details. - -## Security Vulnerabilities - -Please review [our security policy](../../security/policy) on how to report security vulnerabilities. - ## Credits -- [butschster](https://github.com/spiral-packages) +- [butschster](https://github.com/butschster) +- [msmakouz](https://github.com/msmakouz) - [All Contributors](../../contributors) ## License