Laravel Topic Normalizer

https://github.com/jeffersongoncalves/laravel-topic-normalizer
Admin
Laravel Topic Normalizer is a Laravel package that merges, slugs, deduplicates, length-filters, and...
Tokens:7,401
Snippets:56
Trust Score:9.8
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install via Composer

Source: https://github.com/jeffersongoncalves/laravel-topic-normalizer/blob/main/README.md

Install the package using Composer. Run this in your Laravel project root.

```bash
composer require jeffersongoncalves/laravel-topic-normalizer
```

--------------------------------

### Example .env with environment variables

Source: https://github.com/jeffersongoncalves/laravel-topic-normalizer/blob/main/_autodocs/configuration.md

Example environment file showing how to override the default configuration values via environment variables. Each variable is cast to int at config load time.

```env
TOPIC_NORMALIZER_MAX=10
TOPIC_NORMALIZER_MAX_LENGTH=40
TOPIC_NORMALIZER_MIN_LENGTH=2
```

--------------------------------

### Config availability after installation

Source: https://github.com/jeffersongoncalves/laravel-topic-normalizer/blob/main/_autodocs/api-reference/topic-normalizer-service-provider.md

Observable effect in a consumer application: config values resolve with defaults.

```php
// config('topic-normalizer.max')            // int, 20 by default
// config('topic-normalizer.max_length')     // int, 50 by default
// config('topic-normalizer.min_length')     // int, 0 by default
```

--------------------------------

### configurePackage() method

Source: https://github.com/jeffersongoncalves/laravel-topic-normalizer/blob/main/_autodocs/api-reference/topic-normalizer-service-provider.md

Registers the package name and config file. Called by the framework; returns void.

```php
public function configurePackage(Package $package): void
{
    $package
        ->name('laravel-topic-normalizer')
        ->hasConfigFile();
}
```

--------------------------------

### Run tests

Source: https://github.com/jeffersongoncalves/laravel-topic-normalizer/blob/main/README.md

Execute the package test suite using Composer.

```bash
composer test
```

--------------------------------

### Basic normalize() call merging three sources

Source: https://github.com/jeffersongoncalves/laravel-topic-normalizer/blob/main/_autodocs/api-reference/topic-normalizer.md

Merges GitHub topics, composer.json keywords, and package.json keywords into a slugged, unique list capped at 20 (default config). Non-array arguments are skipped; empty results are possible.

```php
use JeffersonGoncalves\TopicNormalizer\TopicNormalizer;

$topics = TopicNormalizer::normalize(
    $repo['topics'] ?? [],          // GitHub topics
    $composer['keywords'] ?? [],    // composer.json keywords
    $packageJson['keywords'] ?? [], // package.json keywords
);
// => ['laravel', 'filament', 'php-package', …]  slugged, unique, max 20
```

--------------------------------

### Import TopicNormalizerServiceProvider

Source: https://github.com/jeffersongoncalves/laravel-topic-normalizer/blob/main/_autodocs/api-reference/topic-normalizer-service-provider.md

Full import path for the service provider class.

```php
use JeffersonGoncalves\TopicNormalizer\TopicNormalizerServiceProvider;
```

--------------------------------

### Publish config file

Source: https://github.com/jeffersongoncalves/laravel-topic-normalizer/blob/main/README.md

Publish the package configuration file using the tag 'topic-normalizer-config'. This allows you to customize the default max, max_length, and min_length values.

```bash
php artisan vendor:publish --tag="topic-normalizer-config"
```

--------------------------------

### Manual provider registration in config/app.php

Source: https://github.com/jeffersongoncalves/laravel-topic-normalizer/blob/main/_autodocs/api-reference/topic-normalizer-service-provider.md

Only needed if auto-discovery is disabled.

```php
// config/app.php
'providers' => [
    // ...
    JeffersonGoncalves\TopicNormalizer\TopicNormalizerServiceProvider::class,
],
```

--------------------------------

### Access config values in application code

Source: https://github.com/jeffersongoncalves/laravel-topic-normalizer/blob/main/_autodocs/configuration.md

Shows how to read the configuration values using Laravel's config() helper with defaults matching the package defaults. The comments show the resolved default values.

```php
$max = (int) config('topic-normalizer.max', 20);         // 20
$maxLength = (int) config('topic-normalizer.max_length', 50); // 50
$minLength = (int) config('topic-normalizer.min_length', 0);  // 0
```

--------------------------------

### Config file config/topic-normalizer.php

Source: https://github.com/jeffersongoncalves/laravel-topic-normalizer/blob/main/_autodocs/configuration.md

Default configuration file for the package. Defines max, max_length, and min_length options, each reading an environment variable with a default. max limits the number of topics returned; max_length drops longer slugs; min_length drops shorter slugs (0 disables the check).

```php
return [
    // Maximum number of topics returned (a repo with dozens of keywords
    // shouldn't bloat the row / UI).
    'max' => (int) env('TOPIC_NORMALIZER_MAX', 20),

    // Maximum slug length; longer values are dropped as junk.
    'max_length' => (int) env('TOPIC_NORMALIZER_MAX_LENGTH', 50),

    // Minimum slug length; shorter values are dropped as junk. 0 disables the
    // check (the default). Set to 2 to drop single-character noise.
    'min_length' => (int) env('TOPIC_NORMALIZER_MIN_LENGTH', 0),
];
```

--------------------------------

### normalize() with per-call overrides and defensive handling

Source: https://github.com/jeffersongoncalves/laravel-topic-normalizer/blob/main/_autodocs/api-reference/topic-normalizer.md

Shows per-call overrides: max caps the result, max_length (snake_case alias) drops long slugs, minLength drops short slugs. Also demonstrates that non-numeric override values like 'oops' are silently ignored and fall back to config.

```php
use JeffersonGoncalves\TopicNormalizer\TopicNormalizer;

$topics = TopicNormalizer::normalize(
    $repo['topics'] ?? [],
    $composer['keywords'] ?? [],
    max: 10,        // cap this call at 10 (overrides config('topic-normalizer.max'))
    max_length: 30, // snake_case alias of maxLength — drop slugs longer than 30 chars
    minLength: 2,   // drop single-character slugs like 'a'
);

if ($topics === []) {
    // No topics survived: every value was dropped as junk, no lists were
    // passed, or a non-positive max took effect.
}

// Non-numeric override values are silently ignored and fall back to the
// config value (see the option() helper below):
$topics = TopicNormalizer::normalize($list, max: 'oops'); // max = config('topic-normalizer.max')
```

--------------------------------

### Auto-registration in composer.json

Source: https://github.com/jeffersongoncalves/laravel-topic-normalizer/blob/main/_autodocs/api-reference/topic-normalizer-service-provider.md

Laravel auto-discovers the provider via the extra.laravel.providers entry in composer.json.

```json
"extra": {
    "laravel": {
        "providers": [
            "JeffersonGoncalves\\TopicNormalizer\\TopicNormalizerServiceProvider"
        ]
    }
}
```

--------------------------------

### Basic usage of TopicNormalizer::normalize

Source: https://github.com/jeffersongoncalves/laravel-topic-normalizer/blob/main/README.md

Merge GitHub topics, composer.json keywords, and package.json keywords into a single normalized list. Non-strings are skipped, values are slugged, duplicates removed (first occurrence wins), and the result is capped at the default max of 20.

```php
use JeffersonGoncalves\TopicNormalizer\TopicNormalizer;

$topics = TopicNormalizer::normalize(
    $repo['topics'] ?? [],          // GitHub topics
    $composer['keywords'] ?? [],    // composer.json
    $packageJson['keywords'] ?? [], // package.json
);
// => ['laravel', 'filament', 'php-package', …]  (slugged, unique, max 20)
```

--------------------------------

### TopicNormalizerServiceProvider::configurePackage(Package $package): void

Source: https://github.com/jeffersongoncalves/laravel-topic-normalizer/blob/main/_autodocs/README.md

Public method on the service provider that configures the package name and registers configuration. Called by Laravel during package bootstrapping.

```APIDOC
## [METHOD] TopicNormalizerServiceProvider::configurePackage(Package $package): void

### Description
Public method on the service provider that configures the package name and registers configuration. Called by Laravel during package bootstrapping.

### Method
METHOD

### Signature
`public function configurePackage(Package $package): void`

### Parameters
- **$package** (Spatie\LaravelPackageTools\Package) - Required - The package instance used for configuration.

### Return Value
- **void** - No return value.

### Behavior
- Sets the package name.
- Registers configuration file.
- Enables auto-discovery.
```

--------------------------------

### Per-call overrides with named arguments

Source: https://github.com/jeffersongoncalves/laravel-topic-normalizer/blob/main/README.md

Override config defaults per call using named arguments. Each argument falls back to its config value. max_length and min_length are accepted as snake_case aliases. A max of 0 or less returns an empty list.

```php
$topics = TopicNormalizer::normalize(
    $repo['topics'] ?? [],
    $composer['keywords'] ?? [],
    max: 10,        // cap this call at 10
    maxLength: 30,  // drop slugs longer than 30 chars
    minLength: 2,   // drop single-character noise
);
```

--------------------------------

### normalize() method signature with docblock

Source: https://github.com/jeffersongoncalves/laravel-topic-normalizer/blob/main/_autodocs/api-reference/topic-normalizer.md

Full signature of the static normalize() method from src/TopicNormalizer.php. It accepts variadic topic lists and per-call overrides (max, maxLength/max_length, minLength/min_length) as named arguments, returning a list of unique slugs.

```php
/**
 * Merge and normalize one or more topic lists.
 *
 * Per-call overrides may be passed as named arguments alongside the lists,
 * each falling back to its config value:
 *   TopicNormalizer::normalize($a, $b, max: 5, maxLength: 30, minLength: 2);
 * Accepted keys: `max` / `maxLength` (alias `max_length`) / `minLength`
 * (alias `min_length`).
 *
 * @param  array<int, mixed>|int  ...$lists
 * @return list<string>
 */
public static function normalize(mixed ...$lists): array
```

--------------------------------

### Runtime override of config value

Source: https://github.com/jeffersongoncalves/laravel-topic-normalizer/blob/main/_autodocs/configuration.md

Shows how to override the 'max' config value at runtime using Laravel's config() helper. This affects subsequent normalize() calls.

```php
config(['topic-normalizer.max' => 5]); // affects subsequent normalize() calls
```

--------------------------------

### Import TopicNormalizer class

Source: https://github.com/jeffersongoncalves/laravel-topic-normalizer/blob/main/_autodocs/api-reference/topic-normalizer.md

Use this import statement to reference the TopicNormalizer class in your PHP code. The class is located in the src/TopicNormalizer.php file and follows PSR-4 autoloading.

```php
use JeffersonGoncalves\TopicNormalizer\TopicNormalizer;
```

--------------------------------

### TopicNormalizer::normalize()

Source: https://github.com/jeffersongoncalves/laravel-topic-normalizer/blob/main/_autodocs/api-reference/topic-normalizer.md

Merges and normalizes one or more topic lists into a unique, slugged array. Accepts per-call overrides for max, maxLength, and minLength, falling back to config values.

```APIDOC
## [PHP] TopicNormalizer::normalize()

### Description
Merges and normalizes one or more topic lists into a unique, slugged array. Accepts per-call overrides for max, maxLength, and minLength, falling back to config values.

### Method
PHP static method

### Endpoint
`TopicNormalizer::normalize(mixed ...$lists): array`

### Parameters
#### Variadic Parameters
- **...$lists** (mixed) - Optional - Each positional argument is a topic/keyword list (array) to merge. Named arguments `max`, `maxLength` (alias `max_length`), `minLength` (alias `min_length`) are consumed as overrides.

### Request Example
```php
use JeffersonGoncalves\TopicNormalizer\TopicNormalizer;

$topics = TopicNormalizer::normalize(
    $repo['topics'] ?? [],
    $composer['keywords'] ?? [],
    max: 10,
    max_length: 30,
    minLength: 2,
);
```

### Response
#### Success Response
- **list<string>** - Zero-indexed, dense array of unique slugs in first-seen order.

#### Response Example
```php
['laravel', 'filament', 'php-package']
```

### Notes
- Non-array positional arguments are silently skipped.
- Zero arguments or only overrides yield `[]`.
- Non-numeric override values are ignored and fall back to config.
- No exceptions are thrown.
```

--------------------------------

### TopicNormalizer::normalize(mixed ...$lists): array

Source: https://github.com/jeffersongoncalves/laravel-topic-normalizer/blob/main/_autodocs/README.md

Static method that normalizes topic lists through a pipeline of slugging, deduplication, length filtering, and capping. Accepts one or more lists (arrays or integers) and returns a list of normalized topic strings.

```APIDOC
## [STATIC] TopicNormalizer::normalize(mixed ...$lists): array

### Description
Static method that normalizes topic lists through a pipeline of slugging, deduplication, length filtering, and capping. Accepts one or more lists (arrays or integers) and returns a list of normalized topic strings.

### Method
STATIC

### Signature
`public static function normalize(mixed ...$lists): array`

### Parameters
- **$lists** (mixed) - Required - One or more lists (arrays or integers) to normalize. Each list can contain strings or integers.

### Return Value
- **array** - A list of normalized topic strings (list<string>).

### Behavior
- Slugs each topic (accent slugging).
- Deduplicates preserving first occurrence.
- Filters by length (min_length and max_length).
- Caps the result to `max` items.
- Never throws exceptions.

### Example
```php
$result = TopicNormalizer::normalize(['Hello World', 'hello-world', 123]);
// Returns list of normalized strings
```
```
Tokens:
Raw