PHPackages                             bluem/searchstringparser - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Parsing & Serialization](/categories/parsing)
4. /
5. bluem/searchstringparser

ActiveLibrary[Parsing & Serialization](/categories/parsing)

bluem/searchstringparser
========================

Library for parsing search strings

2.0.4(5y ago)133.5k↑162.5%2BSD-2-ClausePHPPHP >=5.3.0CI failing

Since Jul 26Pushed 5y ago2 watchersCompare

[ Source](https://github.com/BlueM/searchstringparser)[ Packagist](https://packagist.org/packages/bluem/searchstringparser)[ Docs](https://github.com/BlueM/searchstringparser)[ RSS](/packages/bluem-searchstringparser/feed)WikiDiscussions master Synced 3w ago

READMEChangelogDependencies (1)Versions (8)Used By (0)

[![SensioLabsInsight](https://camo.githubusercontent.com/09440a99830d8b7b71eb9d793dce5b56531ae835322313669f88b8fad3b847fd/68747470733a2f2f696e73696768742e73656e73696f6c6162732e636f6d2f70726f6a656374732f32646330653962362d323335372d343062642d613536622d3961386461646533343038662f6d696e692e706e67)](https://insight.sensiolabs.com/projects/2dc0e9b6-2357-40bd-a56b-9a8dade3408f)[![Build Status](https://camo.githubusercontent.com/0db218c6881054919e58daf282763d2be673f0532df1b465abb18e0c364f775a/68747470733a2f2f7472617669732d63692e6f72672f426c75654d2f736561726368737472696e677061727365722e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/BlueM/searchstringparser)

SearchstringParser Overview
===========================

[](#searchstringparser-overview)

What is it?
-----------

[](#what-is-it)

SearchstringParser is a library for PHP 5.3 or higher which will take a “typical” search-engine-like search string and split it into parts. It supports phrases, required, optional and excluded terms/phrases by using `+`, `-`, `AND`, `NOT` and `OR`.

If you use a search engine like Apache Solr which does the parsing itself, you may not need a library such as this. But in cases where you need switchable search backends but still have a consistent search syntax or where you simply use your SQL database’s fulltext search features, it provides simple and easy parsing. Equally, even when using a software such as Solr, it can be handy to control what is passed to Solr, for instance to optimize the search syntax (example: by setting the `mm` parameter depending on the number of optional terms).

Installation
------------

[](#installation)

The preferred way to install this library is through [Composer](https://getcomposer.org). For this, add `"bluem/searchstringparser": "~2.0"` to the requirements in your `composer.json` file. As this library uses [semantic versioning](http://semver.org), you will get fixes and feature additions when running `composer update`, but not changes which break the API.

Alternatively, you can clone the repository using git or download a tagged release.

Supported Syntax
----------------

[](#supported-syntax)

- A term which is prefixed by `+` is regarded as required. Example: `+word`.
- When there is an `AND` between two terms, both are regarded as required. Example: `Hello AND World`.
- A term which is prefixed by `-` is regarded as excluded. Example: `-word`
- A term which is preceded by `NOT` is regarded as excluded. Example: `NOT word`
- When there is an `OR` between two terms, both are regarded as optional. Example: `Hello OR World`.
- Phrases can be specified using double quotes. Double quotes inside a phrase can be escaped using a backslash. Example: `"my \" phrase"`.
- Everything said above regarding `+`, `-`, `AND`, `OR`, `NOT` applies to phrases as well.

Any term to which none of above rules applies, is by default regarded as an optional term . This can be changed by passing `array('defaultOperator' => SearchstringParser:SYMBOL_AND)` as argument 2 to `SearchstringParser`’s constructor to make such terms required.

Examples:

- `Hello World` ➔ Optional terms “Hello” and “World”, no required or excluded terms
- `Hello World -foobar` ➜ Optional terms “Hello” and “World”, excluded term “foobar”, no required terms (Equivalent to: `Hello World NOT foobar`)
- `+"search string parser" "PHP 5.6" OR "PHP 5.3" NOT "PHP 4" NOT C# -C++ C` ➔ Required phrase “search string parser”, optional phrases “PHP 5.6” and “PHP 5.3”, excluded phrases/terms “PHP 4”, “C#” and “C++” and skipped term “C” (which is shorter than the default minimum length of 2 characters)

Example with `array('defaultOperator' => SearchstringParser:SYMBOL_AND)`:

- `Hello World -foobar` ➜ Required terms “Hello” and “World”, excluded term “foobar”, no optional terms

Usage
=====

[](#usage)

```
$search = new BlueM\SearchstringParser('Your AND string long OR short NOT "exclude this phrase" X');

$search->getAndTerms();     // array('your', 'string')
$search->getOrTerms();      // array('long', 'short')
$search->getNotTerms();     // array('exclude this phrase')
$search->getSkippedTerms(); // array('X')
```

Changing the minimum length
---------------------------

[](#changing-the-minimum-length)

Simply pass the length to the constructor:

```
$search = new BlueM\SearchstringParser('...', array('minlength' => 3));
```

Dealing with errors
-------------------

[](#dealing-with-errors)

The following errors might occur:

- A phrase is opened using `"`, but not closed
- “NOT” is used as last term
- “OR” is used as first or last term
- “AND” is used as first or last term
- “OR” is preceded or followed by an excluded term/phrase
- “AND” is preceded or followed by an excluded term/phrase
- “NOT” is followed by a term prefixed with “+”

The default behaviour is to not throw exceptions, but to make the best out of the situation. (See unit tests or Testdox output for details.) SearchstringParser will still collect exceptions, so if you want to provide hints to the user, you can do that by getting them via method `getExceptions()`. As `SearchstringParser` throws different exceptions depending on the type of problem, you can nicely handle (or ignore) the errors separately, for example by performing `instanceof` checks.

Author & License
====================

[](#author--license)

This code was written by Carsten Blüm ([www.bluem.net](http://www.bluem.net)) and licensed under the BSD 2-Clause license.

Changes from earlier versions
=============================

[](#changes-from-earlier-versions)

From 2.0.3 to 2.0.4
-------------------

[](#from-203-to-204)

- Fix namespace issues in exception classes
- Add PHPUnit as dev-dependency (tests were present, but dependency was missing)

From 2.0.2 to 2.0.3
-------------------

[](#from-202-to-203)

- Update in Readme

From 2.0.1 to 2.0.2
-------------------

[](#from-201-to-202)

- Use PSR-4 instead of PSR-0

From 2.0 to 2.0.1
-----------------

[](#from-20-to-201)

- HHVM compatibility

From 1.0.1 to 2.0
-----------------

[](#from-101-to-20)

- API is unchanged, but the semantics have changed. Versions below 2 behaved as if `defaultOperator` (introduced with 2.0) was set to `SearchstringParser:SYMBOL_AND`

###  Health Score

34

—

LowBetter than 75% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity30

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity63

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~368 days

Recently: every ~454 days

Total

7

Last Release

2139d ago

Major Versions

1.0.1 → 2.02015-08-24

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/1493457?v=4)[Carsten Blüm](/maintainers/BlueM)[@BlueM](https://github.com/BlueM)

---

Top Contributors

[![BlueM](https://avatars.githubusercontent.com/u/1493457?v=4)](https://github.com/BlueM "BlueM (38 commits)")

---

Tags

parsingsearching

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/bluem-searchstringparser/health.svg)

```
[![Health](https://phpackages.com/badges/bluem-searchstringparser/health.svg)](https://phpackages.com/packages/bluem-searchstringparser)
```

###  Alternatives

[jakubledl/dissect

Lexing and parsing in pure PHP

2234.7M11](/packages/jakubledl-dissect)[parsica-php/parsica

The easiest way to build robust parsers in PHP.

412171.6k4](/packages/parsica-php-parsica)[jejik/mt940

An MT940 bank statement parser for PHP

881.2M2](/packages/jejik-mt940)[kingsquare/php-mt940

Simple MT940 parser in PHP

106827.7k3](/packages/kingsquare-php-mt940)[denissimon/formula-parser

Parsing and evaluating mathematical formulas given as strings.

80326.3k3](/packages/denissimon-formula-parser)[codelicious/php-coda-parser

PHP parser for Belgian CODA banking files

45383.7k2](/packages/codelicious-php-coda-parser)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)