README

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 searchmethod:

// 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.js
searchByReadme($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 the Kapersoft\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

Jan Willem Kaper

License

The MIT License (MIT). Please see License File for more information.

kapersoft / npmsearch-api

Maintainers

Details