Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@butschster
butschster committed Nov 24, 2023
1 parent 9df217f commit 0b7a337
Showing 1 changed file with 15 additions and 328 deletions.
343 changes: 15 additions & 328 deletions README.md
View file
Expand Up @@ -6,350 +6,37 @@
[![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
<?php

declare(strict_types=1);

use App\App;

//
// If you forgot to configure some of this in your php.ini file,
// then don't worry, we will set the standard environment
// settings for you.
//

mb_internal_encoding('UTF-8');
error_reporting(E_ALL | E_STRICT);
ini_set('display_errors', 'stderr');

//
// Register Composer's auto loader.
//
require __DIR__ . '/vendor/autoload.php';
The `spiral-packages/discoverer` package is a useful tool for the Spiral framework. It enhances the framework by allowing the discovery of bootloaders and tokenizer directories from sources beyond the Application kernel. This feature simplifies the process of managing and integrating various packages in your Spiral application.

**Features**

//
// Initialize shared container, bindings, directories etc.
//
$app = App::create([
'root' => __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
<?php

declare(strict_types=1);

return [
'bootloaders' => [
// 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

```bash
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
Expand Down

0 comments on commit 0b7a337

Please sign in to comment.