Contracts Reference

This package is contract-first. Implementations (adapters) and higher-level features (graphs) speak the same language.

Query

Represents a provider-agnostic search/filter request with sensible defaults and validation.

Key fields

Construction

use Scholarly\Contracts\Query;

$q = Query::from([
    'q' => 'deep learning',
    'year' => '2018-2022',
    'openAccess' => true,
    'limit' => 50,
    'fields' => ['id','title','year','authors'],
]);

// Or fluent
$q = (new Query())
    ->q('deep learning')
    ->year('2018-')
    ->openAccess(true)
    ->limit(50)
    ->addField('id')->addField('title');

Serialization

$asArray = $q->toArray();

Validation

Paginator

Lazy, typed pagination for provider responses.

API

Usage

$paginator = $adapter->searchWorks($q);

// Pull a page
[$items, $cursor] = [$paginator->page()['items'], $paginator->page()['nextCursor']];

// Or stream lazily
foreach ($paginator as $row) {
    // $row is normalized
}

ScholarlyDataSource

Unified interface across all adapters. Work and author endpoints mirror common capabilities.

Works

Authors

Meta

Normalized shapes (typical)

Exceptions


Core Concepts: Contracts Architecture Getting Started
Features: Graph Analytics Laravel Integration Provider Adapters
Development: Extending GitHub Repository  
External Resources: OpenAlex API Semantic Scholar API Crossref API