Stopwords Laravel Package

Getting Started

1. Install the package (framework-agnostic PHP, no Laravel auto-discovery):

   composer require juanantoniodelgado/stopwords
   

2. Verify the namespace and API surface first. Read composer.json (autoload.psr-4) and the src/ directory before writing any code — this is a small, single-maintainer library, so the exact class name and method signatures are the contract you'll bind against. Typical shape:

   use Juanantoniodelgado\StopWords\StopWords;
   
   $stop = new StopWords('en');                 // verify supported locale codes
   $clean = $stop->remove('This is a basic test of the library');
   // => "basic test library"
   

3. Register a binding in AppServiceProvider so you're not new-ing the class in controllers (see Patterns below).
4. First realistic use case: preprocessing user-generated text before tokenization for search indexing, keyword/tag extraction, or naive text classification. Do not reach for this on short strings (titles, names) — removal there destroys signal.

Implementation Patterns

Bind a configured instance per locale. Wrap the vendor class so the rest of your app never imports it directly:

// app/Services/Text/StopWordFilter.php
namespace App\Services\Text;

use Juanantoniodelgado\StopWords\StopWords;

class StopWordFilter
{
    public function __construct(private string $locale = 'en') {}

    public function clean(string $text): string
    {
        return (new StopWords($this->locale))->remove($text);
    }
}

// AppServiceProvider::register()
$this->app->bind(StopWordFilter::class, fn () =>
    new StopWordFilter(config('services.stopwords.locale', 'en'))
);

Build a normalization pipeline. The library removes stopwords; it does not lowercase, strip punctuation, or normalize Unicode. Chain your own steps before calling it:

$text = mb_strtolower($text, 'UTF-8');
$text = preg_replace('/[^\p{L}\p{N}\s]/u', ' ', $text);
$text = preg_replace('/\s+/u', ' ', $text);
$filtered = app(StopWordFilter::class)->clean($text);

Locale selection before removal. If you accept multilingual input, detect the language (e.g. palladius/php-eloquent style detectors, or a simple fallback) and instantiate the matching stopword list. Mismatching locale silently degrades results — the filter simply finds nothing to remove.

Cache the constructed instance. The stopword list is loaded per instantiation; bind as singleton per locale or memoize in a small factory keyed by locale to avoid re-parsing the list on every request.

Queued bulk processing. For large imports or backfills, do the removal in a job and chunk the source:

Article::whereNull('indexed_at')->chunkById(500, function ($articles) {
    foreach ($articles as $article) {
        $article->update([
            'search_body' => app(StopWordFilter::class)->clean($article->body),
            'indexed_at'  => now(),
        ]);
    }
});

Search-index integration. Feed the cleaned text into Laravel Scout / TNTSearch / Meilisearch as the "toSearchableArray" payload, but keep the raw text for display. Stopword removal belongs in the index, never in the stored document.

Pair with stemming. Stopword removal and stemming are complementary — apply removal first, then a stemmer (e.g. wamania/php-stemmer) for a clean token set:

$tokens = array_filter(explode(' ', $filtered));
$stems  = array_map(fn ($t) => $stemmer->stem($t), $tokens);

Gotchas and Tips

• License is CC-BY-4.0, not MIT. This is unusual for PHP code and may be incompatible with your dependency/license policy. CC-BY is designed for content, not software; check with legal before shipping in a commercial product, and preserve attribution.
• No Laravel auto-discovery expected. There's likely no ServiceProvider or facade in the package — you own all wiring and config. Don't assume config/stopwords.php exists.
• Method names are not guaranteed. With 11 stars and a single 2024 release, treat the README as the only spec. Add a thin wrapper (as above) so a rename or fork only touches one file.
• Case and punctuation sensitivity. If the underlying list is matched literally, The won't be removed but the will. Lowercase and strip punctuation yourself first.
• UTF-8 pitfalls. Ensure mbstring is available and use mb_* / /u regex flags. Accented-language lists (Spanish, French, German) will break with byte-oriented string ops.
• Empty-result edge case. A title like "The It" can reduce to an empty string. Guard downstream consumers (search analyzers, keyword extractors) against blank output.
• Don't apply to proper nouns or short fields. Stopword lists include words that are meaningful as names/brands (IT, Will, May). Scope the filter to body text only.
• Version pinning. Given low activity, pin a known-good version ("juanantoniodelgado/stopwords": "0.1.*" or an exact tag) so a future release can't silently change behavior. Consider vendoring the language files if the project matters long-term.
• Extension point — custom lists. If a needed locale is missing, don't wait on upstream: merge your own array into the token set in your wrapper (array_diff against a custom blacklist) and keep the package for the built-in languages.
• Debugging checklist: dump tokens before and after the call, confirm the locale string you passed is actually supported, and confirm the list wasn't already stripped upstream. composer show juanantoniodelgado/stopwords will tell you the installed version and license.