Search for NPM packages using npmsearch.com API
This is an implementation of npmsearch.com API for the PHP programming environment. More information about npmsearch.com and their API can be found at their GitHub repository.
Installation
You can install the package via composer:
composer require kapersoft/npmsearch-api
Usage
First you initiate the NpmSearch object.
// Initiate NpmSearch
$npmSearch = new Kapersoft\NpmSearch\NpmSearch();
If you like to use your own NpmSearch imeplementation. You can override the URL of the API in the constructor of Kapersoft\NpmSearch\NpmSearch
. You can also pass your your own Guzzle HTTP client to the constructor.
// Create Guzzle HTTP Client
$guzzleClient = new \GuzzleHttp\Client();
// Initiate NpmSearch with custom URL and Guzzle HTTP Client
$npmSearch = new Kapersoft\NpmSearch\NpmSearch('https://my-own-npmsearch-api/query', $guzzleClient);
Search packages
You can search packages using the search
-method:
// Search for kapersoft
$npmSearch->search('kapersoft');
The result is converted to an array that looks like this:
array:4 [
"results" => array:1 [
0 => array:8 [
"maintainers" => array:1 [
0 => "kapersoft"
]
"score" => array:1 [
0 => 0
]
"author" => array:1 [
0 => "kapersoft"
]
"name" => array:1 [
0 => "npo"
]
"description" => array:1 [
0 => "CLI utility to watch NPO streams in QuickTime Player"
]
"version" => array:1 [
0 => "1.2.0"
]
"rating" => array:1 [
0 => 0
]
"modified" => array:1 [
0 => "2018-02-11T22:22:18.543Z"
]
]
]
"total" => 1
"size" => 10
"from" => "0"
]
Specify fields
By default the result will include all fields except readme
. You can specify the fields in the $fields
property of the NpmSearch
-object.
For example:
// Search for jquery with field 'name' returned in the result
$npmsSearch->fields = ['name'];
$npmSearch->search('jquery');
Will return this result:
array:4 [
"results" => array:10 [
0 => array:1 [
"name" => array:1 [
0 => "makeup-jquery"
]
]
1 => array:1 [
"name" => array:1 [
0 => "egis-jquery-qrcode"
]
]
2 => array:1 [
"name" => array:1 [
0 => "eslint-plugin-jquery"
]
]
3 => array:1 [
"name" => array:1 [
0 => "kd-shim-jquery-mousewheel"
]
]
4 => array:1 [
"name" => array:1 [
0 => "jquery-joint-colorbox"
]
]
5 => array:1 [
"name" => array:1 [
0 => "apta-jquery"
]
]
6 => array:1 [
"name" => array:1 [
0 => "jquery-shim"
]
]
7 => array:1 [
"name" => array:1 [
0 => "eslint-plugin-various"
]
]
8 => array:1 [
"name" => array:1 [
0 => "makeup-ebay"
]
]
9 => array:1 [
"name" => array:1 [
0 => "jquery-cycle-2"
]
]
]
"total" => 33208
"size" => 10
"from" => "0"
]
Paging
By default the first 10 results will be returned. If you want to query more packages, you can specify the $start
and $rows
parameters:
// Search for jquery packages 100 to 105
$npmSearch->search('jquery', 100, 5);
Extended search methods
There are also extended search methods next the default search
-method mentioned above. You can search for example for packages by author:
// Search for packages by author 'npm'
$npmSearch->searchByAuthor('npm');
Of course the $start
and $rows
parameters are also available for these methods:
// Search for packages by author 'npm' from 15 to 25
$npmSearch->searchByAuthor('npm', 15, 10);
Advanced search options
In the backend npmsearch.com is a proxy to an ElasticSearch server. So you can use ElasticSearch query string syntax in the search
method:
// Search for packages using a regular expression
$npmSearch->search('name:/joh?n(ath[oa]n)/');
Available search methods
Below the complete list of all search methods:
search($q, $start = 0, $rows = 10)
searchByAuthor($author, $start = 0, $rows = 10)
searchByCreated($created, $start = 0, $rows = 10)
searchByDependencies($dependencies, $start = 0, $rows = 10)
searchByDescription($Description, $start = 0, $rows = 10)
searchByDevDependencies($devDependencies, $start = 0, $rows = 10)
searchByHomepage($homepage, $start = 0, $rows = 10)
searchByKeywords($keywords, $start = 0, $rows = 10)
searchByMaintainers($maintainers, $start = 0, $rows = 10)
searchByModified($modified, $start = 0, $rows = 10)
searchByName($name, $start = 0, $rows = 10)
searchByRating($rating, $start = 0, $rows = 10)
- computed rating as per bin/ratings.jssearchByReadme($readme, $start = 0, $rows = 10)
searchByRepository($repository, $start = 0, $rows = 10)
searchByScripts($scripts, $start = 0, $rows = 10)
searchByTimes($times, $start = 0, $rows = 10)
searchByVersion($version, $start = 0, $rows = 10)
Testing
In the /tests
-folder is one test defined:
NpmSearchTest.php
tests theKapersoft\NpmSearch\NpmSearch-class
using mock Guzzle objects;
You can run the tests in your terminal:
composer test
Changelog
Please see CHANGELOG for more information what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security
If you discover any security related issues, please email kapersoft@gmail.com instead of using the issue tracker.
Credits
License
The MIT License (MIT). Please see License File for more information.